membphis commented on a change in pull request #2192: URL: https://github.com/apache/apisix/pull/2192#discussion_r487938697
########## 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 +Refers to the GET, PUT, POST and other request methods defined in the HTTP protocol, and must be in all uppercase. +2. HTTP URI +`HTTP URI` requirements must start with "/", those that do not start with "/" need to be added, and the empty path is "/". + +3. canonical_query_string +`canonical_query_string` is the result of encoding the `query` in the URL (`query` is the string "key1 = valve1 & key2 = valve2" after the "?" in the URL). + +The coding steps are as follows: Review comment: the current way is not easy to read for the user.  ########## 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 +Refers to the GET, PUT, POST and other request methods defined in the HTTP protocol, and must be in all uppercase. +2. HTTP URI +`HTTP URI` requirements must start with "/", those that do not start with "/" need to be added, and the empty path is "/". + +3. canonical_query_string +`canonical_query_string` is the result of encoding the `query` in the URL (`query` is the string "key1 = valve1 & key2 = valve2" after the "?" in the URL). + +The coding steps are as follows: Review comment: @nic-chen I updated the Chinese version with a better markdown style, you can update the English version with same way: https://github.com/apache/apisix/pull/2192/files#diff-843287a1a4423bbbe03ea7c8a39312d0R95 ########## 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 +Refers to the GET, PUT, POST and other request methods defined in the HTTP protocol, and must be in all uppercase. +2. HTTP URI +`HTTP URI` requirements must start with "/", those that do not start with "/" need to be added, and the empty path is "/". + +3. canonical_query_string +`canonical_query_string` is the result of encoding the `query` in the URL (`query` is the string "key1 = valve1 & key2 = valve2" after the "?" in the URL). + +The coding steps are as follows: + + Extract the `query` item in the URL, that is, the string "key1 = valve1 & key2 = valve2" after the "?" in the URL. + Split the `query` into several items according to the & separator, each item is in the form of key=value or only key. + Encoding each item after disassembly is divided into the following three situations. + + When the item has only key, the conversion formula is UriEncode(key) + "=". + When the item is in the form of key=value, the conversion formula is in the form of UriEncode(key) + "=" + UriEncode(value). Here value can be an empty string. + After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. + +#### Use the generated signature to try the request + +**Note: ACCESS_KEY, SIGNATURE, ALGORITHM, TIMESTAMP respectively represent the corresponding variables** + +* The signature information is put together in the request header `Authorization` field: + +```shell +$ curl http://127.0.0.1:9080/index.html -H 'Authorization: hmac-auth-v1# + ACCESS_KEY + # + base64_encode(SIGNATURE) + # + ALGORITHM + # + TIMESTAMP' -i +HTTP/1.1 200 OK +Content-Type: text/html +Content-Length: 13175 +... +Accept-Ranges: bytes + +<!DOCTYPE html> +<html lang="cn"> +... +``` + +* The signature information is separately placed in the request header: + +```shell +$ curl http://127.0.0.1:9080/index.html -H 'X-HMAC-SIGNATURE: base64_encode(SIGNATURE)' -H 'X-HMAC-ALGORITHM: ALGORITHM' -H 'X-HMAC-TIMESTAMP: TIMESTAMP' -H 'X-HMAC-ACCESS-KEY: ACCESS_KEY' -i +HTTP/1.1 200 OK +Content-Type: text/html +Content-Length: 13175 +... +Accept-Ranges: bytes + +<!DOCTYPE html> +<html lang="cn"> +``` + +## Disable Plugin + +When you want to disable the `hmac-auth` plugin, it is very simple, +you can delete the corresponding json configuration in the plugin configuration, +no need to restart the service, it will take effect immediately: + +```shell +$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d ' +{ + "uri": "/index.html", + "id": 1, Review comment: remove this line, it is useless ---------------------------------------------------------------- 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: us...@infra.apache.org
