AK/SK Authentication-Documentation

1. Introduction

This guide introduces how to use CDNetworks API with the AK/SK authentication(Access Key/Secret Key Authentication) and describes the product description and API calling method.

2.Request Method

Authentication Method
- Authenticating Requests with AK/SK authentication(Access Key/Secret Key Authentication)
Communication Protocol:
- Support both HTTP and HTTPS
- Recommend HTTPS for a higher level of security.
HTTP Request methods:
- Support POST, GET, PUT and DELETE

4. Common Parameters

Request parameters:

Request Header	Type	Required	Description
x-cnc-accessKey	string	Y	Your accessKey to call CDNetworks API
x-cnc-timestamp	int	Y	Timestamp in seconds If the time difference is over five minutes, the request will be unavailable.
Authorization	string	Y	HTTP Standard Authentication Header Field, for example “CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f” - CNC-HMAC-SHA256：Signature method, currently fixed using the value - Credential： The signed credentials,qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z Y x-cnc-accessKey； - SignedHeaders： Header information involved in signature calculation with content type and host as required heads; - Signature： Signed summary. Check credentials, calculated from all parameters, are detailed below in the signed computation process. Identical x-cnc-timestamp, within 5 min authorship does not allow for repetition
content-Type	string	Y	The type of data actually sent to the server.
host	string	Y	API endpoint . e.g“ api.cdnetworks.com”

Response parameters:

Response Header	Description
Accept	Browser-acceptable MIME types
Content-Type	What MIME type the resource is requested, note: required when using POST and PUT methods
Date	Date Format comply with HTTP date formats according to RFC 1123 specifications as of Thu, 17 May 2012 19:37:58 GMT

Authorization Calculation Method

Authorization = Algorithm + ’ ’ + ‘Credential=’ + AccessKey + ', ’ + ‘SignedHeaders=’ + SignedHeaders + ', ’ + ‘Signature=’ + Signature

Field Name	Description
Algorithm	Fixed Value “CNC-HMAC-SHA256”
AccessKey	AccessKeySecret in the key pair, obtained from the Console: Account Management → Basic Information → API Information Management → AccessKey Management page. The value in this example is qiVc3ieau1BlosMghauAhnBcjd2ceqcCC4Z.
SignedHeaders	See below for header information participating in the signature. This example sets the value to "content-type;host"
Signature	Signature value. The result of this sample calculation is “5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f”.

Signature Calculation Procedure

Signature=HexEncode(HMAC_SHA256(SecretKey, StringToSign));
Stringtosign=Algorithm+\n+Timestamp+\n+Hash.SHA256(CanonicalRequest)

CanonicalRequest=
Method+’\n’+
RequestURI+’\n’+
QueryString+’\n’+
CanonicalHeaders+’\n’+
SignedHeaders+’\n’+
HashedRequestPayload

HashedRequestPayload= Lowercase(HexEncode(Hash.SHA256(RequestPayload)))

Canonical Request

Spell the specification request string in the following pseudo-code format:（CanonicalRequest）：

CanonicalRequest =
    Method + '\n' +
    RequestURI + '\n' +
    QueryString + '\n' +
    CanonicalHeaders + '\n' +
    SignedHeaders + '\n' +
    HashedRequestPayload

Field	Description
Method	HTTP request method (get, post). The value of this example is get. Note that the characters here are upper case
RequestURI	URI parameter，such as /api/aksk/test
QueryString	The query string in the URL that initiates the HTTP request,The POST request was fixed to an empty string""， For the GET request, it was the content of the string after the question(?) mark in the URL (We need to decode this part)，for exampledecode("test=test&a=a").
CanonicalHeaders	The specific information of the header participating in the signature includes at least two headers: host and content type. You can also add a custom header to participate in the signature to improve the uniqueness and security of your request. Splicing rules: 1. The header key and value are converted to lowercase, remove the leading and trailing spaces, and splice according to the format of key: value \n； 2. Multiple headers are spliced in ascending ASCII order of header key (lowercase).此The result of this calculation is “content-type:application/json\nhost:api.cdnetworks.com\n”. Note: the content type must be consistent with the actual sending. Some programming language network libraries will automatically add the charset value even if it is not specified. If the signature is inconsistent with the sending, the server will return the signature verification failure.
SignedHeaders	The header that participates in the signature indicates which headers participate in the signature of this request, and corresponds to the header specific information contained in canonicalheaders one by one. Content type and host are required headers. Splicing rules: 1. Turn the head key into lowercase; 2. Multiple header keys (lowercase) are spliced in ascending ASCII order with semicolons (;) separate. This example is “content-type;host”.
HashedRequestPayload	Hash value of the request body (i.e. payload or body). If the parameter is passed in the format of content type: application / JSON, the example is the hash value of {"test": "body"}; If the parameter is passed in the post request mode of content type: application / x-www-form-urlencoded, the example is the hash value of "test = body"; The calculation pseudo code is lowercase (hexencode (hash. SHA256 (requestpayload)), that is, SHA256 hash the HTTP request body, then hexadecimal encoding, and finally convert the encoding string into lowercase letters. For GET request，RequestPayload is empty strings. The result of this calculation is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Based on the above rules, the canonical request string obtained in the example is as follows:

GET
/api/aksk/test
test=test&a=a
content-type:application/json
host:api.cdnetworks.com


content-type;host
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

2. String To Sign

Spell the reception signature string in the following format:

StringToSign = Algorithm + \n + Timestamp + \n + HashedCanonicalRequest

Field Name	Description
Algorithm	Signature algorithm, it is currently fixed as “CNC-HMAC-SHA256”.
Timestamp	Request timestamp, which is the value of the common parameter x-cnc-timestamp in the request header, takes the current time UNIX timestamp, accurate to seconds. This example takes a value of 1631239486
HashedCanonicalRequest	The hash value of the specification request string obtained by the splicing of the preceding steps calculates a pseudocode of Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))).The result of this example is “990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0”

Note: Timestamp must be current system time, and you need to ensure that system time and standard time are synchronized and fail if the difference is more than five minutes.
If you don’t synchronize with the standard time for a long time, you might run for a while and the request must fail, returning a signature expiration error.

Based on the above rules, the StringToSign string obtained in the example is as follows:

CNC-HMAC-SHA256
1631239486
990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0

3. Calculated Signature

1）Obtain a signature key, such as：

SecretKey = test

Field Name/	Description
SecretKey	AccessKey Secret

2) Calculate the signature with the pseudocode as follows:

Signature = HexEncode(HMAC_SHA256(SecretKey, StringToSign))
Based on the above rules, the values obtained in the example are:

CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273

The final complete invocation information is as follows:

GET https://api.cdnetworks.com/api/aksk/test?test=test&a=a

Authorization: CNC-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273
Content-Type: application/json;
Host: api.cdnetworks.com
x-cnc-accessKey: qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z 
x-cnc-timestamp: 1631239486

Code examples

Examples of Access Key codes are recommended:

Python3 : Download
Java: Download
Go: Download

7.Response Formats

Success results
The success result shows as below. Samples of both JSON and XML are given.

The following shows an example of JSON:

HTTP/1.1  {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server}  /* globally unique requestid */
{
  /* data of returned results  */
}

The following shows an example of XML:

HTTP/1.1   {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server}  /* globally unique requestid */

<?xml version="1.0" encoding="UTF-8"?>
<!—results root-->
  <!—data of returned results-->
</!—results root-->

8.Error response cases

Results data is not returned if the error occurred in calling API Error cause can be positioned with “Error codes”.
If an error occurred, the HTTP error response has a 4xx or 5xx HTTP status code. The response messages contain the specific error code and error details.
Besides, the request header also contains the globally unique ID: request-id. If the error cause cannot be specified, please contact technical support and provide the RequestId to facilitate the tracking process.