Skip to main content

Authentication

HOST​

  • Dev: https://dpapi-open-dev.klub11.com/

  • UAT: https://dpapi-open-uat.klub11.com/

  • PROD: TBC

签名说明​

1、生成签名 Generating the signature​

签名计算公式: SIGNATURE = base64(hmac-sha256(SECRET_KEY, SIGNING_STRING))
SIGNING_STRING = HTTP Method + \n + HTTP URI + \n + CANONICAL_QUERY_STRING + \n + ACCESS_KEY + \n + Date + \n + SIGNED_HEADERS_STRING

如果 SIGNING_STRING 中的某一项不存在，则需要使用一个空字符串代替

  • HTTP Method：指 HTTP 协议中定义的 GET、PUT、POST 等请求方法，必须使用全大写的形式
  • HTTP URI：HTTP URI。必须以 “/” 开头，“/” 表示空路径
  • Date：请求头中的日期（GMT 格式）
  • CANONICAL_QUERY_STRING：对 URL 中的 query（query 即 URL 中 ? 后面的 key1=valve1&key2=valve2 字符串）排序拼接后的结果（按keyASCII 码由小到大的顺序）
  • SIGNED_HEADERS_STRING 目前固定格式如下
X-CRM-SIGNATURE-NONCE + ":" + {NONCE} + "\n"

NONCE 值 为唯一随机数，不同请求中要使用不同的随机数值

2、Body校验 Validating request body​

Header 增加 X-HMAC-DIGEST, 值为: base64(hmac-sha256(SECRET_KEY, BODY))

3、使用签名进行请求 Using the signature to requests​

构造HTTP Headers 并发起请求 , 示例

curl -i "https://url" \
# ... 公共Header
-H "X-HMAC-ALGORITHM: hmac-sha256" \
-H "X-HMAC-SIGNED-HEADERS: X-CRM-SIGNATURE-NONCE" \
-H "X-HMAC-ACCESS-KEY: {ACCESS_KEY}" \
-H "X-HMAC-SIGNATURE: {SIGNATURE}" \ # 见上面步骤1
-H "X-HMAC-DIGEST: {DIGEST}" \ # 见上面步骤2
-H "Date: {DATE}" \ # GMT日期格式
-H "X-CRM-SIGNATURE-NONCE: {NONCE}" \  #唯一随机数
-H "Content-Type: application/json" \

# 其它自定义Header
-H "User-Agent: curl/7.29.0"
...

{ACCESS_KEY}、{SIGNATURE}、{NONCE}、{DATE}、 {DIGEST} 分别代表对应的变量

签名过程示例​

假设预期请求信息为：

curl -i -X POST -d '{"type":"code","value":"123456"}'  'https://xxx.xxx.xxx/v1/demo/test'

ACCESS_KEY = api-account-001

SECRET_KEY = a6ff27fd150be9a7b6be53844e5d92a2

1、生成签名 Generating the signature​

  • 生成SIGNING_STRING
POST
/v1/demo/test

api-account-001
Sun, 10 Nov 2022 10:49:40 GMT
X-CRM-SIGNATURE-NONCE:606ad583bfbc0aa22d41480e4c19ddcf
  • 生成SIGNATURE

Bash计算示例:

#!/bin/bash
secret="a6ff27fd150be9a7b6be53844e5d92a2"
message="POST
/v1/demo/test

api-account-001
Sun, 10 Nov 2022 10:49:40 GMT
X-CRM-SIGNATURE-NONCE:606ad583bfbc0aa22d41480e4c19ddcf
"

signature="$(echo -n "$message" |  openssl dgst -sha256 -hmac "$secret" -binary | base64)"
echo $signature

计算值为:

vwfbn9csPvQutOtDgM0+vi6ciTeppxE7Qqm9pAPRnGk=

2、Body校验 Validating request body​

Bash计算示例：

#!/bin/bash
secret="a6ff27fd150be9a7b6be53844e5d92a2"
message='{"type":"code","value":"123456"}'

signature="$(echo -n "$message" |  openssl dgst -sha256 -hmac "$secret" -binary | base64)"
echo $signature

计算值为:

CKSih3YS9ud+Qw1H0eVyfFTxJ8rcPSxiWY6nqyMUZXI=

3、使用签名进行请求 Using the signature to requests​

curl -i -X POST -d '{"type":"code","value":"123456"}' 'https://xxx.xxx.xxx/v1/demo/test' \
-H "Content-Type: application/json" \
-H "Date: Sun, 10 Nov 2022 10:49:40 GMT" \
-H "X-HMAC-ALGORITHM: hmac-sha256" \
-H "X-HMAC-ACCESS-KEY: api-account-001" \
-H "X-CRM-SIGNATURE-NONCE: 606ad583bfbc0aa22d41480e4c19ddcf" \
-H "X-HMAC-SIGNED-HEADERS: X-CRM-SIGNATURE-NONCE" \
-H "X-HMAC-SIGNATURE: vwfbn9csPvQutOtDgM0+vi6ciTeppxE7Qqm9pAPRnGk=" \
-H "X-HMAC-DIGEST: CKSih3YS9ud+Qw1H0eVyfFTxJ8rcPSxiWY6nqyMUZXI="