[apisix] branch master updated: docs(hmac-auth): additional details for generating signing_string (#7816)

[sy...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git


The following commit(s) were added to refs/heads/master by this push:
     new 3a795f60b docs(hmac-auth): additional details for generating signing_string (#7816)
3a795f60b is described below

commit 3a795f60bed9e6fffe5c3b09596c5a1be6730080
Author: tzssangglass <tz...@gmail.com>
AuthorDate: Wed Aug 31 21:51:02 2022 +0800

    docs(hmac-auth): additional details for generating signing_string (#7816)
---
 docs/en/latest/plugins/hmac-auth.md | 49 ++++++++++++++++++++++++++++++++++---
 docs/zh/latest/plugins/hmac-auth.md | 48 +++++++++++++++++++++++++++++++++---
 2 files changed, 91 insertions(+), 6 deletions(-)

diff --git a/docs/en/latest/plugins/hmac-auth.md b/docs/en/latest/plugins/hmac-auth.md
index 551339ca4..c50bd5737 100644
--- a/docs/en/latest/plugins/hmac-auth.md
+++ b/docs/en/latest/plugins/hmac-auth.md
@@ -140,7 +140,52 @@ curl -i http://127.0.0.1:9080/index.html?name=james&age=36 \
 -H "User-Agent: curl/7.29.0"
 ```
 
-The `signing_string` generated according to the algorithm above is:
+### Explanation of signature generation formula process
+
+1. The default HTTP Method for the above request is GET, which gives `signing_string` as
+
+```plain
+"GET"
+```
+
+2. The requested URI is `/index.html`, and the `signing_string` is obtained from the HTTP Method + \n + HTTP URI as
+
+```plain
+"GET
+/index.html"
+```
+
+3. The query item in the URL is `name=james&age=36`, assuming that `encode_uri_params` is false.
+According to the algorithm of `canonical_query_string`, the focus is on dictionary sorting of `key` to get `age=36&name=james`.
+
+```plain
+"GET
+/index.html
+age=36&name=james"
+```
+
+4. The `access_key` is `user-key`, and the `signing_string` is obtained from HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key as
+
+```plain
+"GET
+/index.html
+age=36&name=james
+user-key"
+```
+
+5. Date is in GMT format, as in `Tue, 19 Jan 2021 11:33:20 GMT`, and the `signing_string` is obtained from the  HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date as
+
+```plain
+"GET
+/index.html
+age=36&name=james
+user-key
+Tue, 19 Jan 2021 11:33:20 GMT"
+```
+
+6. `signed_headers_string` is used to specify the headers involved in the signature, which in the above example includes `User-Agent: curl/7.29.0` and `x-custom-a: test`.
+
+And the `signing_string` is obtained from the HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date + \n as
 
 ```plain
 "GET
@@ -153,8 +198,6 @@ x-custom-a:test
 "
 ```
 
-The last request header also needs + `\n`.
-
 The Python code below shows how to generate the signature:
 
 ```python
diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md
index 6aed415e0..aeef613e3 100644
--- a/docs/zh/latest/plugins/hmac-auth.md
+++ b/docs/zh/latest/plugins/hmac-auth.md
@@ -145,7 +145,51 @@ curl -i http://127.0.0.1:9080/index.html?name=james&age=36 \
 -H "User-Agent: curl/7.29.0"
 ```
 
-根据上述算法生成的 `signing_string` 为：
+### 签名生成公式过程详解
+
+1. 上文请求默认的 HTTP Method 是 GET，得到 `signing_string` 为
+
+```plain
+"GET"
+```
+
+2. 请求的 URI 是 `/index.html`，根据 HTTP Method + \n + HTTP URI 得到 `signing_string` 为
+
+```plain
+"GET
+/index.html"
+```
+
+3. URL 中的 query 项是 `name=james&age=36`，假设 `encode_uri_params` 为 false，根据 `canonical_query_string` 的算法，重点是对 `key` 进行字典排序，得到 `age=36&name=james`；根据 HTTP Method + \n + HTTP URI + \n + canonical_query_string 得到 `signing_string` 为
+
+```plain
+"GET
+/index.html
+age=36&name=james"
+```
+
+4. access_key 是 `user-key`，根据 HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key 得到 `signing_string` 为
+
+```plain
+"GET
+/index.html
+age=36&name=james
+user-key"
+```
+
+5. Date 是指 GMT 格式的日期，形如 `Tue, 19 Jan 2021 11:33:20 GMT`, 根据 HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date 得到 `signing_string` 为
+
+```plain
+"GET
+/index.html
+age=36&name=james
+user-key
+Tue, 19 Jan 2021 11:33:20 GMT"
+```
+
+6. `signed_headers_string` 用来制定参与到签名的 headers，在上面示例中包括 `User-Agent: curl/7.29.0` 和 `x-custom-a: test`。
+
+根据 HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date + \n + signed_headers_string + `\n`，得到完整的 `signing_string` 为
 
 ```plain
 "GET
@@ -158,8 +202,6 @@ x-custom-a:test
 "
 ```
 
-最后一个请求头也需要 + `\n`。
-
 以下示例是通过使用 Python 来生成签名 `SIGNATURE`：
 
 ```python