Signature Method

Last updated: 2019-05-07 10:23:02

When you send requests to Tencent Cloud API, you need to sign the requests for authentication and security purposes. That is, you include a signature generated by your security credential, which consists of a secret id and a secret key, as a common parameter to the request. Please note that security credentials are required for Tencent Cloud API calls. If you have not had one, feel free to apply on Tencent Cloud official website.

Applying for Security Credentials

Before using Tencent Cloud's APIs for the first time, you need to apply for security credentials on Tencent Cloud Console -> API Key Management. Security credentials consist of a SecretId and a SecretKey, where:

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

SecretKeys are very important through which you can access and work with the resources in your Tencent Cloud account via API. For security reasons, please keep your keys safe and rotate them regularly, and 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 cloud 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 two pairs of SecretId/SecretKey at most.
  • 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 its security credential.

Generating a Signature

A signature can be created with a set of secret ID and secret key. The following example shows how a signature is generated:

Suppose that you have the following SecretId and SecretKey:
SecretId: AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA
SecretKey: Gu5t9xGARNpq86cd98joQYCN3Cozk1qA

This information is only for demonstration purpose. Make sure you proceed with your actual SecretId, SecretKey and request parameters.

For example, when you call Tencent Cloud CVM's API Viewing 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 A random positive integer 11886
Region The region where the instance resides ap-guangzhou
SignatureMethod Signature method HmacSHA256
InstanceIds.0 ID of the instance to be queried ins-09dx96dg

1. Sort parameters

First, sort all the parameters sent in the HTTP request in ascending lexicographical order by their names. (This is like sorting words in a dictionary in ascending alphabetical order or numerical order. That is, sort the parameters by their first letters, then by their second letters if their first letters are the same, and so on). You can use sorting functions available in programming languages, such as the ksort function in PHP. For example,

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

You can use any other programming languages to sort parameters as long as you get the same result as the one in the example above.

2. Concatenate request elements to form a query 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.
  • Any underscore in the parameter names needs to be replaced with ., while the one in parameter values is allowed. For example, Placement_Zone=CN_GUANGZHOU needs to be converted to Placement.Zone=CN_GUANGZHOU.

Then, concatenate the formatted parameters seperate them with"&" to generate the query string (ignore the line breaks in the text):

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

3. Create a string to sign

Structure of string to sign:

HTTP Request Method + Server Domain Name + Path + ? + Query String Components

Description of parameters:

  • HTTP request method: The POST and GET methods are supported. We use a GET request in this case. Please note that both methods are case-sensitive and should always be mentioned in uppercase.
  • Server domain name: The domain name varies by the product or product module to which the API belongs. For example, when you send a request to Tencent Cloud CVM's API to query a list of instances(DescribeInstances), the domain name for this request is: cvm.api.qcloud.com. For more information on the domain names for requests in different products, see the description of each API.
  • Request path: A path that defines how Tencent Cloud product API is exposed to requesters. In general, each product has a fixed and unique request path. For example, the request path for Tencent Cloud CVM is always /v2/index.php.
  • Query string: The string generated in the previous step.

The resulting string to sign (ignore the line breaks in the text):

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. Compute a signature

You can compute a signature using either HmacSHA256 or HmacSHA1 protocols. The HmacSHA1 is preferred unless HmacSHA256 is specified.

** First, create a hash-based message authentication code (HMAC) that uses HmacSHA256 or HmacSHA1 protocols to sign the string from the previous step, then encode the resulting signature to Base64.
In this example, we use PHP language and compute the signature using HmacSHA256 (Note: you can use any other programming languages as long as the resulting signature is the same as the one in this example). The sample code is shown 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=HmacSHA256&Timestamp=1465185768';
$signStr = base64_encode(hash_hmac('sha256', $srcStr, $secretKey, true));
echo $signStr;

The result is as follows:

0EEm/HtGRr/VJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s=

Similarly, if you useHmacSHA1 , the code should be orgainzed 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 result is as follows:

nPVnY6njQmwQ8ciqbPl5Qe+Oru4=

Encode the signature

The signature must be URL encoded.
For example, after encoding, the 'raw' signature generated in the previous step 0EEm/HtGRr/VJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s= is converted to 0EEm%2FHtGRr%2FVJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s%3D . The resulting signature is 0EEm%2FHtGRr%2FVJXTAD9tYMth1Bzm3lLHz5RCDv1GdM8s%3D, which will be used to generate the 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 the failure of signature verification.

Authentication Failures

The following errors may occur when the authentication fails:

Error Code Error Type Error Description
4100 Authentication failed Make sure the signature added to your request is calculated correctly (see steps above as reference) and URL encoded.
4101 No access to this API The sub-user is not authorized to call the API. Contact the developer for authorization. For more information, see Authorization Policy.
4102 No access to the API resources The resources are not accessible. Find the ID of the inaccessible resource in field Message
Contact the developer for authorization. For more information, see Authorization Policy.
4103 Non-developer SecretId cannot be used for this API call Only the developer can call this API with this SecretId.
4104 SecretId does not exist The SecretId does not exist, or the status of SecretKey is incorrect. Make sure the SecretKey is valid to use.
4110 Authentication failed Permission verification failed. Make sure you are granted the permission to access to this resource.
4500 Replay attack error Invalid nonce- nonce must increase with every request. Invalid timestamp - The difference between Timestamp and Tencent server time should not be greater than 2 hours.