If a published API uses the application-enabled authentication method (ApiAppKey
and ApiAppSecret
), when a client calls the API, it needs to use the signature key to perform signature calculation on the request content and transfer the signature to the server for signature verification. This document describes how to implement the signature calculation process on the client.
Note:For application-enabled authentication signature demos for common programming languages, see Development Guide - Generating Application Authentication Signature.
API Gateway provides a frontend signature calculation and verification feature, which can:
ApiAppKey
.The owner of an API can generate an application on the application management page in the API Gateway console. Each application carries a signature key pair (ApiAppKey
and ApiAppSecret
). After the API owner authorizes the API to the specified application (which can be issued by the API owner or owned by an API caller), the API caller can use the application's signature key to call the API.
When the client calls the API, it needs to use the authorized signature key to perform encrypted signature calculation on the critical request content, put the ApiAppKey
and the encrypted signature string in the header of the request, and transfer it to API Gateway. API Gateway will read the header information of the ApiAppKey
in the request, query the value of the ApiAppSecret
corresponding to the value of the ApiAppKey
, use the ApiAppSecret
to perform signature calculation on the critical data in the received request, and compare the generated signature with the signature sent by the client to verify the correctness of the signature. Only if the request passes the signature verification will it be sent to the backend service; otherwise, API Gateway will deem the request invalid and directly return an error.
ApiAppSecret
to encrypt the critical data signature string to get a signature.ApiAppKey
from the received request and query the corresponding ApiAppSecret
through the ApiAppKey
.ApiAppSecret
to encrypt the critical data signature string to get a signature.The client needs to extract the critical data from the HTTP request and splice it into a signature string in the following format:
Headers
HTTPMethod
Accept
Content-Type
Content-MD5
PathAndParameters
The above 6 fields constitute the entire signature string. They need to be separated with \n
. Headers
must contain X-Date
. There is no need to add \n
after PathAndParameters
. Even if other fields are empty, \n
should still be retained. The signature is case sensitive. The extraction rules for each field are as follows:
HeaderKey1 + ": " + HeaderValue1 + "\n"\+
HeaderKey2 + ": " + HeaderValue2 + "\n"\+
...
HeaderKeyN + ": " + HeaderValueN + "\n"
The headers in Authorization
are the ones involved in signature calculation. We recommend you convert them to the lowercase and separate them by ASCII spaces. For example, if the headers involved in the calculation are date
and source
, the format should be headers="date source"
; if only the x-date
header participates in the calculation, the format should be headers="x-date"
.
Accept
header in the request, which can be empty. We recommend you explicitly set the Accept
header. If it is empty, some HTTP clients will set the default value of / for it, causing signature verification to fail.Content-Type
header in the request, which can be empty.Content-MD5
header in the request, which can be empty. The Content-MD5
header is calculated only when the request has a Body
in a non-Form
format. The calculation method of the Content-MD5
value in Java is as follows:String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));
Path
, Query
, and Form
in the following format:path
does not contain release environment (release, prepub, test) information.Query
and Form
parameter pair are sorted in lexicographical order and then spliced in the above-mentioned method.Query
and Form
parameters are empty, use Path
directly without adding ?
.Query
and Form
(i.e., parameters with the same key but different values), the values need to be sorted in lexicographical order and then spliced in the above-mentioned method.Take a general HTTP request as an example:
POST / HTTP/1.1
host:service-3rmwxxxx-1255968888.cq.apigw.tencentcs.com
accept:application/json
content-type:application/x-www-form-urlencoded
source:apigw test
x-date:Thu, 11 Mar 2021 08:29:58 GMT
content-length:8
p=test
The generated correct signature string is as follows:
source: apigw test
x-date: Thu, 11 Mar 2021 08:29:58 GMT
POST
application/json
application/x-www-form-urlencoded
/?p=test
After the client extracts the critical data from the HTTP request and splices it into a signature string, it needs to encrypt and encode the signature string to form the final signature in the following steps:
signing_str
signing information) to get a byte array.The client needs to put the Authorization
in the HTTP request and transfer it to API Gateway for signature verification.
The format of the Authorization
header is as follows:
Authorization: hmac id="secret_id", algorithm="hmac-sha1", headers="date source", signature="Base64(HMAC-SHA1(signing_str, secret_key))"
The parameters in Authorization
are described as follows:
Parameter | Description |
---|---|
hmac | Fixed and used to indicate the calculation method |
ID | Value of the secret_id in the key |
algorithm | Encryption algorithm. HMAC-SHA1 and HMAC-SHA256 are supported currently |
headers | Headers involved in the signature calculation |
signature | Signature obtained after signature calculation is completed, with signing_str as its content |
Below is an example of an HTTP request with a signature:
POST / HTTP/1.1
host:service-3rmwxxxx-1255968888.cq.apigw.tencentcs.com
accept:application/json
content-type:application/x-www-form-urlencoded
source:apigw test
x-date:Thu, 11 Mar 2021 08:29:58 GMT
Authorization:hmac id="xxxxxxx", algorithm="hmac-sha1", headers="source x-date", signature="xyxyxyxyxyxy"
content-length:8
p=test
Question:
If the API Gateway signature verification fails, the server's signature string (StringToSign) will be put in the HTTP response header and returned to the client with an error code of 401.
Solution:
ApiAppSecret
used for signature calculation is correct.StringToSign
are replaced with #
."message":"HMAC signature does not match, Server StringToSign:source: apigw test#x-date: Thu, 11 Mar 2021 08:49:30 GMT#POST#application\/json#application\/x-www-form-urlencoded##\/?p=test"
This means that the server signature is:
source: apigw test
x-date: Thu, 11 Mar 2021 08:29:58 GMT
POST
application/json
application/x-www-form-urlencoded
/?p=test
Was this page helpful?