Signature Method

Last updated: 2019-09-20 10:20:39

PDF

This is a legacy API and may be deprecated in the future. It is currently not displayed on the left sidebar. We recommend using API Category, which is more standardized and has much lower access latency, see API Category.

TencentCloud API authenticates each access request, so each request is required to include the signature (Signature) in the common request parameters for user authentication. The signature is generated with the user’s security credentials, which consist of a SecretId and a SecretKey. Users who have no security credentials can apply for one on Tencent Cloud's official website; otherwise, you will not be able to call TencentCloud API.

Apply for Security Credentials

Before using TencentCloud API for the first time, you need to apply for security credentials in Tencent Cloud Console > API Key Management. Security credentials consist of a SecretId and a SecretKey.

  • SecretId is the identity of the requester.
  • SecretKey is used to encrypt the strings to create a signature so that Tencent Cloud server can validate the identity of the requester.

API key is very important for creating TencentCloud API requests. With TencentCloud APIs, you can access and manage the resources in your Tencent Cloud account. For security reasons, store your keys safely and rotate them regularly (make sure you delete the old key when a new one is created).

How to Apply for Security Credentials

  1. Log in to the Tencent Cloud Console.
  2. Click Products and select Security Credentials under Monitor & Management to go to the TencentCloud API key management page.
  3. On the API Key Management page, click Create Key to create a pair of SecretId/SecretKey.
  • A developer account can have up to two pairs of SecretId/SecretKey.
  • A developer can add a QQ account as a sub-user and use it to apply for different security credentials in multiple developer consoles.
  • A sub-user can only call the specified Tencent Cloud APIs with his security credentials.

Generating a Signature String

After obtaining the security credentials (SecretId and SecretKey), you can generate a signature.

Assume that the SecretId and SecretKey are:
SecretId: AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA
SecretKey: Gu5t9xGARNpq86cd98joQYCN3Cozk1qA

This example is for demonstration purposes only. Make sure that you proceed with your actual SecretId, SecretKey and request parameters.

For example, when you call Tencent Cloud CVM’s API Checking Instance List (DescribeInstances), the request parameters are as follows:

Parameter Name Description Parameter value
Action Method name DescribeInstances
SecretId Key ID AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA
Timestamp Current timestamp 1465185768
Nonce Random positive integer 11886
Region Region where the instance is located ap-guangzhou
SignatureMethod Signature method HmacSHA256
InstanceIds.0 ID of the instance to be queried ins-09dx96dg

1. Sort Parameters

First, sort all request parameters by their names in ascending lexicographical order, just like sorting words in a dictionary in ascending alphabetical or numerical order. That is to say, sort the parameters by their first letters, and then sort the parameters with the same first letter by their second letters and so on. You can do this with the aid of relevant sorting functions in the programming language, such as the ksort function in PHP. The sorting results of the above sample parameters are as follows:

{
    "Action" : "DescribeInstances",
    "InstanceIds.0" : "ins-09dx96dg",
    "Nonce" : "11886",
    "Region" : "ap-guangzhou",
    "SecretId" : "AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA",
    "SignatureMethod" : "HmacSHA256",
    "Timestamp" : "1465185768"
}

Any other programming language can be used to sort these parameters as long as the same result is produced.

2. Generate a Request String

This step generates a request string.
Assign values to the parameters (see the previous step) by following the logic "parameter name"="parameter value". For example, if the value of Action is "DescribeInstances", then Action=DescribeInstances.

  • "Parameter value" is the original value instead of the URL encoded value.
  • If the key of an input parameter contains an underscore, the underscore should be replaced with a .; however, underscores in Value do not need to be replaced. For example, Placement_Zone=CN_GUANGZHOU should be converted to Placement.Zone=CN_GUANGZHOU.

Then, concatenate the formatted parameters with "&" to generate the request string (ignore the line breaks here):

Action=DescribeInstances
&InstanceIds.0=ins-09dx96dg
&Nonce=11886
&Region=ap-guangzhou
&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA
&SignatureMethod=HmacSHA256
&Timestamp=1465185768

3. Concatenating a Signature Original String

This step generates a signature original string.
The structure for a signature original string is as follows:

request method + request domain name + request path + ? + request string

The parameters are as detailed below:
Request method: Both POST and GET methods are supported. GET is used here. Note that the method name should be all capitalized.

  • Request host: This is the host domain name. Request domain name is determined by the product or product module to which the API belongs. For example, the request domain name for the Tencent Cloud CVM API for querying instance list (DescribeInstances) is: cvm.api.qcloud.com. For the request domain names of specific products, see the description of each API.
  • Request path: The request path for the product to which the Tencent Cloud API belongs. Each product has a fixed request path. For example, the request path for Tencent Cloud CVM is always /v2/index.php.
  • Request string: This is the request string generated in the previous step.

The resulting original signature string in the above example is (please ignore the line breaks here):

GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances
&InstanceIds.0=ins-09dx96dg
&Nonce=11886
&Region=ap-guangzhou
&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA
&SignatureMethod=HmacSHA256
&Timestamp=1465185768

4. Generate Signature String

This step generates a signature string.

There are two ways to calculate a signature: HmacSHA256 and HmacSHA1. Here, a signature string is generated based on the specified signature algorithm (i.e., the SignatureMethod parameter). The signature will be calculated with the HmacSHA256 algorithm if SignatureMethod is specified as HmacSHA256. In other cases, the signature will be calculated with HmacSHA1.

First, create a hash-based message authentication code (HMAC) that uses HmacSHA256 or HmacSHA1 protocols to sign the original signature string from the previous step, then encode the resulting signature to Base64.

In this example, we use PHP language and calculate the signature string using HmacSHA256. The sample code is shown as follows (you can use any other programming languages as long as the resulting signature is the same as the one in this example):

$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3Cozk1qA';
$srcStr = 'GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Nonce=11886&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA&SignatureMethod=HmacSHA256&Timestamp=1465185768';
$signStr = base64_encode(hash_hmac('sha256', $srcStr, $secretKey, true));
echo $signStr;

The final signature string is:

0EEm/HtGRr/VJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s=

Similarly, if you specify the signature algorithm as HmacSHA1, the code to generate the signature string is as follows:

$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3Cozk1qA';
$srcStr = 'GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Nonce=11886&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA&SignatureMethod=HmacSHA1&Timestamp=1465185768';
$signStr = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
echo $signStr;

The final signature string is:

nPVnY6njQmwQ8ciqbPl5Qe+Oru4=

Encoding Signature String

The generated signature string cannot be directly used as a request parameter and must be URL encoded.
For example, the signature string 0EEm/HtGRr/VJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s= generated in the previous step should be encoded to 0EEm%2FHtGRr%2FVJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s%3D. Therefore, the resulting request parameter for the signature string (Signature) is 0EEm%2FHtGRr%2FVJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s%3D, which will be used to generate the final request URL.

If you are sending a GET request, all parameters in the request need to be URL encoded. Please note that some languages may offer auto-URL encoding, and repeated encoding will cause signature verification failure.

Authentication Failure

The following errors may occur when authentication fails:

Error Code Error Type Error Description
4100 Authentication failed Authentication failed. Please make sure that the Signature added to your request is calculated correctly (see steps above as reference) and URL encoded
4101 No API access authorization The sub-user is not authorized to call this API. Please contact the developer for authorization. For more information, see Policy
4102 No authorization to access resources You are not authorized to access resources used by this API. Check the relevant resource IDs in the message field and contact the developer for authorization.
For more information, see Policy
4103 Non-developer's SecretId cannot be used to call this API The sub-user's SecretId cannot be used to call this API. Only the developer has access to this API
4104 SecretId does not exist The SecretId does not exist or the status of SecretKey is incorrect. Please make sure that the API key is valid and enabled
4110 Authentication failed Permission verification failed. Please make sure that you have the permission to access the resources
4500 Replay attack error The Nonce parameter must be unique, and the difference between Timestamp and Tencent server time should not be greater than two hours