membphis commented on a change in pull request #2192: URL: https://github.com/apache/apisix/pull/2192#discussion_r487958081
########## File path: doc/zh-cn/plugins/hmac-auth.md ########## @@ -0,0 +1,157 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +- [English](../../plugins/hmac-auth.md) + +# 目录 +- [**名字**](#名字) +- [**属性**](#属性) +- [**如何启用**](#如何启用) +- [**测试插件**](#测试插件) +- [**禁用插件**](#禁用插件) + + +## 名字 + +`hmac-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。 + +添加 HMAC Authentication 到一个 `service` 或 `route`。 然后 `consumer` 将其签名添加到请求头以验证其请求。 + +## 属性 + +|属性名 |是否可选 | 默认值 |描述| +|--------- |--------|-----------|-----------| +| `access_key` | 必须 | 无 | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `access_key` ，将会出现请求匹配异常。| +| `secret_key`| 必须 | 无 | 与 `access_key` 配对使用。| +| `algorithm` | 可选 | hmac-sha256 | 加密算法。目前支持 `hmac-sha1`, `hmac-sha256` 和 `hmac-sha512`。| +| `clock_skew`| 可选 | 300 | 签名允许的时间偏移，以秒为单位的计时。比如允许时间偏移 10 秒钟，那么就应设置为 `10`。特别地，`0` 表示不对 `timestamp` 进行检查。| + +## 如何启用 + +1. 创建一个 consumer 对象，并设置插件 `hmac-auth` 的值。 + +```shell +curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "username": "jack", + "plugins": { + "hmac-auth": { + "access_key": "user-key", + "secret_key": "my-secret-key", + "clock_skew": 10 + } + } +}' +``` + +2. 创建 Route 或 Service 对象，并开启 `hmac-auth` 插件。 + +```shell +curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri": "/index.html", + "plugins": { + "hmac-auth": {} + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "39.97.63.215:80": 1 + } + } +}' +``` + +## Test Plugin + +### 签名生成公式 + +签名的计算公式为 `signature = HMAC-SHAx-HEX(secret_key, signning_string)`，从公式可以看出，想要获得签名需要得到 `secret_key` 和 `signning_string` 两个参数。其中 `secret_key` 为对应 consumer 所配置的， `signning_string` 的计算公式为： `signning_string = HTTP Method + HTTP URI + canonical_query_string + HTTP BODY + access_key + timestamp + secret_key` Review comment: Two questions: 1. I think the HTTP body is optional. 2. For the `signning_string`, we should add a space when we concat different values, eg: `HTTP METHOD` + " " + `HTTP URI`, it is more easier for understanding. ########## File path: doc/plugins/hmac-auth.md ########## @@ -0,0 +1,156 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +- [中文](../zh-cn/plugins/hmac-auth.md) + +# Summary +- [**Name**](#name) +- [**Attributes**](#attributes) +- [**How To Enable**](#how-to-enable) +- [**Test Plugin**](#test-plugin) +- [**Disable Plugin**](#disable-plugin) + + +## Name + +`hmac-auth` is an authentication plugin that need to work with `consumer`. Add HMAC Authentication to a `service` or `route`. + +The `consumer` then adds its key to request header to verify its request. + +## Attributes + +|Name |Requirement |Default |Description| +|--------- |--------|-----------|-----------| +| access_key | required | none |Different `consumer` objects should have different values, and it should be unique. If different consumers use the same `access_key`, a request matching exception will occur| +| secret_key | required | none |Use as a pair with `access_key`| +| algorithm | optional| hmac-sha256 |Encryption algorithm. support `hmac-sha1`, `hmac-sha256` and `hmac-sha512`| +| clock_skew | optional | 300 |The clock skew allowed by the signature in seconds. For example, if the time is allowed to skew by 10 seconds, then it should be set to `10`. especially, `0` means not checking timestamp.| + +## How To Enable + +1. set a consumer and config the value of the `hmac-auth` option + +```shell +curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "username": "jack", + "plugins": { + "hmac-auth": { + "access_key": "user-key", + "secret_key": "my-secret-key", + "clock_skew": 10 + } + } +}' +``` + +2. add a Route or add a Service , and enable the `hmac-auth` plugin + +```shell +curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri": "/index.html", + "plugins": { + "hmac-auth": {} + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "39.97.63.215:80": 1 + } + } +}' +``` + +## Test Plugin + +#### generate signature: +The calculation formula of the signature is `signature = HMAC-SHAx-HEX(secret_key, signning_string)`. From the formula, it can be seen that in order to obtain the signature, two parameters, `SECRET_KEY` and `SIGNNING_STRING`, are required. Where secret_key is configured by the corresponding consumer, the calculation formula of `SIGNNING_STRING` is: `signning_string = HTTP Method + HTTP URI + canonical_query_string + HTTP BODY + ACCESS_KEY + TIMESTAMP + SECRET_KEY` + +1. HTTP Method Review comment: Please update this English version follow this style: https://github.com/apache/apisix/pull/2192/commits/94b6ea2c421ebee1ae9b00c394d4e0cc73f33171 ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
