This is an automated email from the ASF dual-hosted git repository.
membphis 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 333210f doc(hmac-auth): generate signature should be more detailed
(#2599)
333210f is described below
commit 333210fc644b05a0f911652e5504ae156ea912f0
Author: kiki <[email protected]>
AuthorDate: Tue Nov 3 16:40:33 2020 +0800
doc(hmac-auth): generate signature should be more detailed (#2599)
fix #2531
---
.../plugins-hmac-auth-generate-signature.md | 202 +++++++++++++++++++++
doc/plugins/hmac-auth.md | 27 ++-
doc/zh-cn/plugins/hmac-auth.md | 27 ++-
3 files changed, 252 insertions(+), 4 deletions(-)
diff --git a/doc/examples/plugins-hmac-auth-generate-signature.md
b/doc/examples/plugins-hmac-auth-generate-signature.md
new file mode 100644
index 0000000..d86d013
--- /dev/null
+++ b/doc/examples/plugins-hmac-auth-generate-signature.md
@@ -0,0 +1,202 @@
+<!--
+#
+# 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.
+#
+-->
+
+# HMAC Generate Signature Examples
+
+## Python 3
+
+```python
+import hashlib
+import hmac
+import base64
+
+secret = bytes('the shared secret key here', 'utf-8')
+message = bytes('this is signature string', 'utf-8')
+
+
+hash = hmac.new(secret, message, hashlib.sha256)
+
+# to lowercase hexits
+hash.hexdigest()
+
+# to lowercase base64
+base64.b64encode(hash.digest())
+```
+
+## Java
+
+```java
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.security.NoSuchAlgorithmException;
+import java.security.InvalidKeyException;
+import javax.xml.bind.DatatypeConverter;
+
+class Main {
+ public static void main(String[] args) {
+ try {
+ String secret = "the shared secret key here";
+ String message = "this is signature string";
+
+ Mac hasher = Mac.getInstance("HmacSHA256");
+ hasher.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
+
+ byte[] hash = hasher.doFinal(message.getBytes());
+
+ // to lowercase hexits
+ DatatypeConverter.printHexBinary(hash);
+
+ // to base64
+ DatatypeConverter.printBase64Binary(hash);
+ }
+ catch (NoSuchAlgorithmException e) {}
+ catch (InvalidKeyException e) {}
+ }
+}
+```
+
+## Go
+
+```go
+package main
+
+import (
+ "crypto/hmac"
+ "crypto/sha256"
+ "encoding/base64"
+ "encoding/hex"
+)
+
+func main() {
+ secret := []byte("the shared secret key here")
+ message := []byte("this is signature string")
+
+ hash := hmac.New(sha256.New, secret)
+ hash.Write(message)
+
+ // to lowercase hexits
+ hex.EncodeToString(hash.Sum(nil))
+
+ // to base64
+ base64.StdEncoding.EncodeToString(hash.Sum(nil))
+}
+```
+
+## Ruby
+
+```ruby
+require 'openssl'
+require 'base64'
+
+secret = 'the shared secret key here'
+message = 'this is signature string'
+
+# to lowercase hexits
+OpenSSL::HMAC.hexdigest('sha256', secret, message)
+
+# to base64
+Base64.encode64(OpenSSL::HMAC.digest('sha256', secret, message))
+```
+
+## NodeJs
+
+```js
+var crypto = require('crypto');
+
+var secret = 'the shared secret key here';
+var message = 'this is signature string';
+
+var hash = crypto.createHmac('sha256', secret).update(message);
+
+// to lowercase hexits
+hash.digest('hex');
+
+// to base64
+hash.digest('base64');
+```
+
+## JavaScript ES6
+
+```js
+const secret = 'the shared secret key here';
+const message = 'this is signature string';
+
+const getUtf8Bytes = str =>
+ new Uint8Array(
+ [...unescape(encodeURIComponent(str))].map(c => c.charCodeAt(0))
+ );
+
+const secretBytes = getUtf8Bytes(secret);
+const messageBytes = getUtf8Bytes(message);
+
+const cryptoKey = await crypto.subtle.importKey(
+ 'raw', secretBytes, { name: 'HMAC', hash: 'SHA-256' },
+ true, ['sign']
+);
+const sig = await crypto.subtle.sign('HMAC', cryptoKey, messageBytes);
+
+// to lowercase hexits
+[...new Uint8Array(sig)].map(b => b.toString(16).padStart(2, '0')).join('');
+
+// to base64
+btoa(String.fromCharCode(...new Uint8Array(sig)));
+```
+
+## PHP
+
+```php
+<?php
+
+$secret = 'the shared secret key here';
+$message = 'this is signature string';
+
+// to lowercase hexits
+hash_hmac('sha256', $message, $secret);
+
+// to base64
+base64_encode(hash_hmac('sha256', $message, $secret, true));
+```
+
+## Lua
+
+```lua
+local hmac = require("resty.hmac")
+local secret = 'the shared secret key here'
+local message = 'this is signature string'
+local digest = hmac:new(secret, hmac.ALGOS.SHA256):final(message)
+
+--to lowercase hexits
+ngx.say(digest)
+
+--to base64
+ngx.say(ngx.encode_base64(digest))
+```
+
+## Shell
+
+```bash
+SECRET="the shared secret key here"
+MESSAGE="this is signature string"
+
+# to lowercase hexits
+echo -n $MESSAGE | openssl dgst -sha256 -hmac $SECRET
+
+# to base64
+echo -n $MESSAGE | openssl dgst -sha256 -hmac $SECRET -binary | base64
+```
diff --git a/doc/plugins/hmac-auth.md b/doc/plugins/hmac-auth.md
index 5102e04..733aed7 100644
--- a/doc/plugins/hmac-auth.md
+++ b/doc/plugins/hmac-auth.md
@@ -26,6 +26,7 @@
- [**How To Enable**](#how-to-enable)
- [**Test Plugin**](#test-plugin)
- [**Disable Plugin**](#disable-plugin)
+ - [**Generate Signature Examples**](#generate-signature-examples)
## Name
@@ -126,8 +127,10 @@ x-custom-header:value
### Use the generated signature to try the request
-**Note: ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS respectively
represent the corresponding variables**
-**Note: SIGNED_HEADERS is the headers specified by the client to join the
encryption calculation**
+**Note:**
+1. **ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS respectively
represent the corresponding variables**
+2. **SIGNED_HEADERS is the headers specified by the client to join the
encryption calculation. If there are multiple headers, they must be separated
by ";": `x-custom-header-a;x-custom-header-b`**
+3. **SIGNATURE needs to use base64 for encryption: `base64_encode(SIGNATURE)`**
* The signature information is put together in the request header
`Authorization` field:
@@ -205,3 +208,23 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}
}'
```
+
+## Generate Signature Examples
+
+Take HMAC SHA256 as an example to introduce the signature generation examples
in different languages.
+
+Example inputs:
+
+Variable | Value
+---|---
+secret | this is secret key
+message | this is signature string
+
+Example outputs:
+
+Type | Hash
+---|---
+hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345
+base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U=
+
+Please refer to [**HMAC Generate Signature
Examples**](../examples/plugins-hmac-auth-generate-signature.md)
diff --git a/doc/zh-cn/plugins/hmac-auth.md b/doc/zh-cn/plugins/hmac-auth.md
index 2d7fbbd..818dcee 100644
--- a/doc/zh-cn/plugins/hmac-auth.md
+++ b/doc/zh-cn/plugins/hmac-auth.md
@@ -26,6 +26,7 @@
- [**如何启用**](#如何启用)
- [**测试插件**](#测试插件)
- [**禁用插件**](#禁用插件)
+- [**签名生成示例**](#签名生成示例)
## 名字
@@ -127,8 +128,10 @@ x-custom-header:value
### 使用生成好的签名进行请求尝试
-**注： ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS 分别代表对应的变量**
-**注： SIGNED_HEADERS 为客户端指定的加入加密计算的 headers**
+**注:**
+1. **ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS 分别代表对应的变量**
+2. **SIGNED_HEADERS 为客户端指定的加入加密计算的 headers。若存在多个 headers 需以 ";"
分割：`x-custom-header-a;x-custom-header-b`**
+3. **SIGNATURE 需要使用 base64 进行加密：`base64_encode(SIGNATURE)`**
* 签名信息拼一起放到请求头 `Authorization` 字段中：
@@ -206,3 +209,23 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}
}'
```
+
+## 签名生成示例
+
+以 HMAC SHA256 为例，介绍一下各种语言的签名生成示例。
+
+示例入参说明:
+
+Variable | Value
+---|---
+secret | this is secret key
+message | this is signature string
+
+示例出参说明：
+
+Type | Hash
+---|---
+hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345
+base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U=
+
+具体代码请参考：[**HMAC Generate Signature
Examples**](../../examples/plugins-hmac-auth-generate-signature.md)
