AK/SK Authentication

Last update:2023-07-18 13:46:16

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)))
  1. 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:

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.

The following shows an example of JSON:

HTTP/1.1   {4xx or 5xx}{error such as Access Denied or InternalError}
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 */

{
    "code": "{the error code, like MissingDateHeader}",
    "message": "{description, like Authorized request, must have a Date or x-cnc-date header }"
}
      

The following shows an example of XML:

HTTP/1.1   {4xx or 5xx}{error such as Access Denied or InternalError}
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}  /* this requestid is unique globally */

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <code>{the error code, like MissingDateHeader}</code>
  <message>{description, like Authorized request must have a Date or x-cnc-date header}</message>
</response>
          

9. Error Code

HTTP Status Code Code Message
401 WPLUS_InvalidHTTPAuthHeader The HTTP authorization header is bad
403 WPLUS_RequestTokenNotExistError request token not exist or expired
431 WPLUS_MatchApiNone there is no suitable api you request.
432 WPLUS_ApiPrivilegeError the account used is not authenticated using this api.
434 WPLUS_RequestExpired Request has expired.
435 WPLUS_AccountTooFrequence The account is too frequent.
436 WPLUS_IPTooFrequence The ip is too frequent.
437 WPLUS_AccountCapacityFull The api capacity is full.
438 WPLUS_APiTooFrequence The api is too frequent.
439 WPLUS_APiCapacityFull The api capacity is full.
440 WPLUS_AccountWhitelist remote ip not exist in account white list.
441 WPLUS_ApiWhitelist remote ip not exist in api white list.
443 WPLUS_ApiUnactive the api invoked is inactive.
446 WPLUS_AccountApiTooFrequence The account to the indicated api is too frequency.
447 WPLUS_APiTooConcurrent The api call exceeds the concurrent threshold.
448 WPLUS_AccountTooConcurrent The account call exceeds the concurrent threshold.
449 WPLUS_AccountApiTooConcurrent The account to the indicated API call is exceed the concurrency threshold.
450 WPLUS_DateError date is error.
453 WPLUS_HystrixSocketConnectTimeout hystrix socket connect timeout!
462 WPLUS_AuthorizationError authorization is error! please check signature, accessKey!
501 WPLUS_SystemError system error!
503 WPLUS_InvokeBackendFail invoke backend fail!
530 WPLUS_InvalidArgument exception occured when read body(InputStream) from HttpServletRequest.
533 WPLUS_CollectAgentMakeDirError collectAgent call error:can not make folder.
534 WPLUS_CollectAgentMakeFileError collectAgent call error:can not make file.
535 WPLUS_RunShellError run shell error.
537 WPLUS_ProcessorHttpJobInvokerCallServiceError We encountered an internal error in CommonJobInvoker when calling netty. Please try again.
555 WPLUS_HystrixSocketConnectError hystrix socket connect error!
Is the content of this document helpful to you?
Yes
I have suggestion
Submitted successfully! Thank you very much for your feedback, we will continue to strive to do better!