Signature Algorithm v2

Applying for Security Credentials

The security credential used in this document is a key, which includes an accessKeyId and an accessKeyPassword.

• AccessKeyId: used to identify the API caller, which is just like a username.

• AccessKeyPassword: used to authenticate the API caller, which is just like a password.

• You must keep your security credentials private and avoid disclosure; otherwise, your assets may be compromised. If they are disclosed, please disable them as soon as possible.

You can apply for the security credentials according to Zenlayer Docs.

Signature Calculation Process

Zenlayer Open API v2 supports POST requests. Only Content-Type: application/json is supported. The API is called in JSON format.

The following uses querying the list of bare metal instances in the Hong Kong region as an example to describe the steps of signature splicing.

Assuming that your AccessKeyId and AccessKeyPassword are AKIDz8krbsJ5yKBZQpn74WFkmLPx3 and Gu5t9xGARNpq86cd98joQYCN3, respectively, if you want to view the status of the instance in the Hong Kong region whose bare metal instance name is "unnamed", then the request may be:

curl -X POST https://console.zenlayer.com/api/v2/bmc \
-H "Authorization: ZC2-HMAC-SHA256 Credential=0D9UtpyKYcHxms5v, SignedHeaders=content-type;host, Signature=efb356c32e55c781e10dc676da59462c22596d82e91c57803666243379555b2f" \
-H "Content-Type: application/json; charset=utf-8" \
-H "X-ZC-Action: DescribeInstances" \
-H "X-ZC-Timestamp: 1673361177" \
-H "X-ZC-Signature-Method: ZC2-HMAC-SHA256" \
-H "X-ZC-Version: 2022-11-20" \
-d '{"pageSize":10,"pageNum":1,"zoneId":"HKG-A"}'

Request Headers:

Key	Explanation	Example
X-ZC-Timestamp	Request timestamp in second	1673361177
X-ZC-Version	API version number	2022-11-20
X-ZC-Action	Request action	DescribeInstances
X-ZC-Signature-Method	Signature method	ZC2-HMAC-SHA256
Authorization	Authentication process

1. Concatenating the CanonicalRequest String

Concatenate the canonical request string (CanonicalRequest) in the following pseudocode format:

CanonicalRequest = 
  HTTPRequestMethod + '\n' + 
  CanonicalURI + '\n' + 
  CanonicalQueryString + '\n' + 
  CanonicalHeaders + '\n' + 
  SignedHeaders + '\n' + 
  HexEncode(Hash(RequestPayload))

Field Name	Explanation
HTTPRequestMethod	HTTP request method (POST).
CanonicalURI	URI parameter. Slash ("/") is used here.
CanonicalQueryString	The query string in the URL of the originating HTTP request. This is always an empty string “” for POST requests.
CanonicalHeaders	Header information for signature calculation. Custom headers can be added to participate in the signature process to improve the uniqueness and security of the request. Concatenation rules: Both the key and value of the header should be converted to lowercase with the leading and trailing spaces removed, so they are concatenated in the format of key:value format(Note: The last character is '\n'); If there are multiple headers, they should be sorted in ASCII ascending order by the header keys (lowercase). The calculation result in this example is： content-type:application/json; charset=utf-8\nhost:console.zenlayer.com\n
SignedHeaders	Header information for signature calculation, indicating which headers of the request participate in the signature process (they must each individually correspond to the headers in CanonicalHeaders). Content-type and host are required headers. Concatenation rules: Both the key and value of the header should be converted to lowercase; If there are multiple headers, they should be sorted in ASCII ascending order by the header keys (lowercase) and separated by semicolons (;). The value in this example is content-type;host.
HashedRequestPayload	Hash value of the request payload (i.e., the body, such as {"pageSize":10,"pageNum":1,"zoneId":"HKG-A"} in this example). The pseudocode for calculation is Lowercase(HexEncode(Hash.SHA256(RequestPayload))) by SHA256 hashing the payload of the HTTP request, performing hexadecimal encoding, and finally converting the encoded string to lowercase letters. The calculation result in this example is 5f714687ba91c606d503467766151206392474accd137ffea6dce2420b67c29a.

2. Concatenating the String to Be Signed

The string to sign is concatenated as follows:

StringToSign =
    Algorithm + \n +           # Signature algorithm, which is ZC2-HMAC-SHA256 for SHA256.
    RequestTimestamp + \n +     # Request timestamp.
    HashedCanonicalRequest 

Field Name	Explanation
Algorithm	Signature algorithm, which is currently always ZC2-HMAC-SHA256.
RequestTimestamp	Request timestamp, i.e., the value of the common parameter X-ZC-Timestamp in the request header, which is the UNIX timestamp of the current time in seconds, such as 1673361177 in this example.
HashedCanonicalRequest	Hash value of the CanonicalRequest string concatenated in the steps above. The pseudocode for calculation is Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))). The calculation result in this example is 29396f9dfa0f03820b931e8aa06e20cda197e73285ebd76aceb83f7dede493ee.

According to the preceding rules, the string to be signed obtained in the example is as follows:

ZC2-HMAC-SHA256
1673361177
29396f9dfa0f03820b931e8aa06e20cda197e73285ebd76aceb83f7dede493ee

3. Calculating the Signature Based on AK and StringToSign

Calculate the derived signature key with the following pseudocode:

Signature = HexEncode(HMAC_SHA256(AccessKeyPassword, StringToSign))

Field Name	Explanation
AccessKeyPassword	The original AccessKeyPassword, i.e., Gu5t9xGARNpq86cd98joQYCN3.
StringToSign	The result obtained in Step 2.

4. Concatenating the Authorization

The Authorization is concatenated as follows:

Authorization =
    Algorithm + ' ' +
    'Credential=' + AccessKeyId +  ', ' +
    'SignedHeaders=' + SignedHeaders + ', ' +
    'Signature=' + Signature

Field Name	Explanation
Algorithm	Signature algorithm, which is always ZC2-HMAC-SHA256.
AccessKeyId	The AccessKeyId in the key pair, i.e., 0D9UtpyKYcHxms5v.
SignedHeaders	Header information for signature calculation (see above), such as content-type;host in this example.
Signature	Signature value. The calculation result in this example is efb356c32e55c781e10dc676da59462c22596d82e91c57803666243379555b2f.