Interface Authentication V3

Interface authentication v3 is more secure than the other two authentications. The original two interface authentication methods can still be used, and it is recommended to use this authentication method.
Take Cloud VoD batch obtaining video list information interface as an example to illustrate the authentication method.

Request URL

Assemble the URI parameters of the specific interface behind https://api.cloudv.haplat.net

For example, the request URL to get the video list is as follows

https://api.cloudv.haplat.net/vod/videoManage/getVideoList

Request Method

Support GET and POST requests

Individual interfaces support POST requests with content-type: application/json.

Common Parameters

This authentication method uses the following fields of request parameters:

Parameter Name	Types	Is it required	Description
X-WS-AccessKey	string	Yes	Access Key ID (AccessKey ID). The corresponding AccessKey Secret is obtained through the AccessKey management interface of the console. Both the main account and the sub-account have different AccessKey IDs. The server will verify its authorization range, and the account can only operate on the data it has permission to operate.
X-WS-Timestamp	int	Yes	Timestamp in seconds. If the time differs from the server time by more than 5 minutes, the request is invalidated.
Authorization	string	Yes	HTTP standard authentication header fields, for example: "WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,SignedHeaders=content-type;host, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024" where, -WS3 -HMAC-SHA256: this value is fixed at present; - credential: signature certificate, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-WS-AccessKey is the X-; - SignedHeaders: participation in the header information of the signature computation, content-type and the host is mandatory head; - signature : signature digest. The verification certificate is calculated from all the parameters. For details, please refer to the signature calculation process (plus link) below. In the same X-WS-Timestamp, authorization is not allowed to be repeated within 5 minutes
content-Type	string	Yes	The type of data actually sent to the server. If it is called by a get request, then the parameter value is fixed at the beginning of "application/x-www-form-urlencoded"
host	string	Yes	Request domain name, fixed as the requested domain name, "api.cloudv.haplat.net"

Signature (Sinature) calculation process

Algorithm overview

1, Signature=HexEncode(HMAC_SHA256(SecretKey, StringToSign ));
2, Stringtosign = Algorithm +\n+ Timestamp +\n+Hash.SHA256( CanonicalRequest )
3, CanonicalRequest =
Method +'\n'+
RequestURI +'\n'+
QueryString +'\n'+
CanonicalHeaders +'\n'+
SignedHeaders +'\n'+
HashedRequestPayload
4, HashedRequestPayload = Lowercase(HexEncode(Hash.SHA256( RequestPayload )))

1. Canonical Request (CanonicalRequest)

Splice the Canonical Request string (CanonicalRequest) in the following pseudo-code format:

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

Field Name	Explanation
Method	HTTP request method (GET, POST). In this example, the value is POST. Note that the characters here are uppercase.
RequestURI	URI parameter, for the batch get video interface, the value of this parameter is /vod/videoManage/getVideoList
QueryString	The query string in the URL that initiates the HTTP request. For POST requests, it is always an empty string "". For GET requests, it is the string content after the question mark (?) in the URL, for example: "videoName=testVideoName&pageIndex=2&pageSize=5 ".
CanonicalHeaders	The specific information of the header involved 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 own request. Splicing rules: 1. The head key and value are converted to lowercase uniformly, and the leading and trailing spaces are removed, and spliced according to the format of key:value\n; 2. Multiple headers are spliced according to the ascending ASCII order of the head key (lowercase). The calculation result of this example is "content-type: application/json; charset=utf-8\nhost:api.cloudv.haplat.net\n". Note: The content-type must be consistent with the actual sent. 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 headers participating in the signature indicate which headers of this request participated in the signature, and correspond to the specific header information contained in CanonicalHeaders one-to-one. The content-type and host are mandatory headers. Splicing rules: 1. Header keys are uniformly converted to lowercase; 2. Multiple header keys (lowercase) are spliced ​​in ascending ASCII order and separated by semicolons (;). This example is "content-type;host".
HashedRequestPayload	The hash value of the request body (that is, the payload or body). In such content-type: application / json transmission format parameters, the example is { "videoName": "a" , "pageSize": "5", "pageIndex": "2"} hash value; as to Content -Type: application/x-www-form-urlencoded POST request method to pass parameters, the example is the hash value of "videoName=a&pageIndex=2&pageSize=5"; the calculated pseudo code is Lowercase(HexEncode(Hash.SHA256(RequestPayload)) )), that is, SHA256 hash the HTTP request body, then hexadecimal encoding, and finally the encoded string is converted into lowercase letters. For GET requests, RequestPayload is always an empty string. The calculation result for this example is 135b13e1b15e3c836eab2ab9196a86e7bcdb7b68da27215175a65b89ade3587e.

According to the above rules, the CanonicalRequest string obtained in the example is as follows:

POST
/vod/videoManage/getVideoList

content-type:application/json; charset=utf-8
host:api.cloudv.haplat.net

content-type;host
641f7989f8d223af8c5049f805890fcaf2ae4a99780a01eb454cf7c9368dd1a4

2. Join the string to be signed (StringToSign)

Concatenate the string to be signed in the following format:

StringToSign =

    Algorithm + \n +

    Timestamp + \n +

    HashedCanonicalRequest

Field Name	Explanation
Algorithm	The signature algorithm is currently fixed as "WS3-HMAC-SHA256".
Timestamp	Request timestamp, that is, the value of the public parameter X-WS-Timestamp in the request header, which is the current time UNIX timestamp, accurate to the second. In this example, the value is 1564645579
HashedCanonicalRequest	The hash value of the canonical request string spliced ​​in the foregoing steps is calculated as Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))). The calculation result of this example is "16bc1b4d4e6818f5aec2a7273cb2c3d3e4831fd61c6510222b9bec19bffac646"

Note: Timestamp must be the current system time, and ensure that the system time and standard time are synchronized. If the difference is more than five minutes, it will fail. If it is not synchronized with the standard time for a long time, it may cause the request to fail after running for a period of time and return a signature expiration error.

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

WS3-HMAC-SHA256
1564645579
16bc1b4d4e6818f5aec2a7273cb2c3d3e4831fd61c6510222b9bec19bffac646

3. Calculate the signature (Signature)

1. Obtain the signing key, for example:

SecretKey = bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

Field Name	Explanation
SecretKey	Original AccessKey Secret

2. Calculate the signature, the pseudo code is as follows:

Signature = HexEncode(HMAC\_SHA256(SecretKey, StringToSign))

4. Splicing Authorization

Splice Authorization in the following format:

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

Field Name	Explanation
Algorithm	The signature method is fixed as "WS3-HMAC-SHA256".
AccessKey	The AccessKey Secret in the key pair is obtained from the "User Center-AccessKey Management" page of the console. The value in this example is AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE.
SignedHeaders	See above, the header information involved in the signature. The value of this example is "content-type;host"
Signature	Signature value. The calculation result for this example is "72e494ea809ad7a8c8f7a4507b9bddcbaa8e581f516e8da2f66e2c5a96525168".

According to the above rules, the value obtained in the example is:

WS3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE, SignedHeaders=content-type;host, Signature=792dcb6d648a456a030c9c6683fa7bde2a31cb4c72cfeaa354da000adf7c288d

The final complete call information is as follows:

POST https://api.cloudv.haplat.net/
Authorization: WS3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE, SignedHeaders=content-type;host, Signature=792dcb6d648a456a030c9c6683fa7bde2a31cb4c72cfeaa354da000adf7c288d
Content-Type: application/json; charset=utf-8
Host: api.cloudv.haplat.net
X-WS-AccessKey: AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE
X-WS-Timestamp: 1564645579

{"videoName":"a","pageSize":"5","pageIndex":"2"}

General error code

Error Code	Description
4001	Authentication parameter error, please check whether all required parameters have passed values
4002	X-WS-AccessKey parameter error, please check whether the key exists, whether there are fewer or more characters copied
4003	X-WS-Timestamp parameter error, the time format is second-level timestamp
4004	X-WS-Timestamp expires, and the time difference between the time when the server receives the request and the server receives the request must not exceed five minutes
4005	host parameter error, please check
4006	The content-type parameter is wrong, please check
4007	Authentication failed, please check whether the parameters are correct
4008	Authentication failed, please check whether the signature calculation is wrong, or the signature does not match the actual content sent, it may also be caused by an error in the key AccessKey Secret
4009	The signature has been used, please regenerate the authentication parameters

curl example

content-type: application/json post request (recommended method)

curl -X POST https://api.cloudv.haplat.net/vod/videoManage/getVideoList 
-H "Authorization: WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, SignedHeaders=content-type;host, Signature=471d8f86cefa4fa2f929642207b6df8fe770e82e0df328f4f68af08c8b8a8029" 
-H "Content-Type: application/json; charset=utf-8" 
-H "Host: api.cloudv.haplat.net" 
-H "X-WS-Timestamp: 1564644606" 
-H "X-WS-AccessKey: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" 
-d '{"videoName": "a","pageIndex":"2","pageSize":"5"}'

content-type: application/x-www-form-urlencoded post request

curl -X POST https://api.cloudv.haplat.net/vod/videoManage/getVideoList 
-H "Authorization: WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, SignedHeaders=content-type;host, Signature=37ea1014de0c90e83e733f8d19a5d3ae993896d34450c9f8cf8df5642c81339e" 
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" 
-H "Host: api.cloudv.haplat.net" 
-H "X-WS-Timestamp: 1564644607" 
-H "X-WS-AccessKey: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" 
-d 'videoName=a&pageIndex=2&pageSize=5'

get request
Note that the Content-Type in the get request is fixed in application/x-www-form-urlencoded format.

curl -X GET https://api.cloudv.haplat.net/vod/videoManage/getVideoList?videoName=a&pageIndex=2&pageSize=5 
-H "Authorization: WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, SignedHeaders=content-type;host,     Signature=0b489e43c5cd2e52cbe0768a68c614a4211210a6d63b18ff65cc986f18e75aac" 
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" 
-H "Host: api.cloudv.haplat.net" 
-H "X-WS-Timestamp: 1564644607" 
-H "X-WS-AccessKey: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

content-type: post request of multipart/form-data
Due to the complicated structure of the authorization parameter of the request, it needs to be generated in the code. Please refer to the following java code example.

java code example

The API connection can be used by quoting the tool class, and the until.jar package needs to be imported .

Detailed code example

import com.cnc.cloudv.util.auth.ApiAuthUtil;
import com.cnc.cloudv.util.httpclient.CloudvHttpResponse;

import java.util.HashMap;
import java.util.Map;

public class TestAuthUtil {
//通过秘钥管理获取的秘租
    private final static String ACCESS_KEY = "aaaaaaaaaaaaaaaaaaaaaaaaa";
    private final static String SECRET_KEY = "bbbbbbbbbbbbbbbbb";
//这里固定为云视频API域名
    private final static String API_HOST = "api.cloudv.haplat.net";

    public static void main(String[] args) throws Exception {
        Map<String, String> customHeaderMap = new HashMap<String, String>(2);
	//可以支持自定义头部
        customHeaderMap.put("from", "test-authentification-sdk");
		//请求接口的URI
        String requestURI = "/vod/videoManage/getVideoList";

	//application/json方式的post请求调用
        String body = "{\"videoName\": \"测\",\"pageIndex\":\"2\",\"pageSize\":\"5\",\"format\": \"json\"}";
        CloudvHttpResponse cloudvHttpResponse = ApiAuthUtil.callPostJsonBodyRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, body);
        log(cloudvHttpResponse);
		
	//get请求的调用例子
        String canonicalQueryString = "videoName=" + java.net.URLEncoder.encode("测", "utf-8") + "&pageIndex=2&pageSize=5&format=json";
        cloudvHttpResponse = ApiAuthUtil.callGetRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, canonicalQueryString);
        log(cloudvHttpResponse);

	//form-Urlencoded方式的post请求调用示例
        body = "videoName=" + java.net.URLEncoder.encode("测", "utf-8") + "&pageIndex=2&pageSize=5&format=json";
        cloudvHttpResponse = ApiAuthUtil.callPostFormUrlencodedBodyRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, body);
        log(cloudvHttpResponse);
		
		
	//通过map方式传入URL参数的请求方式
        Map<String, String> map = new HashMap<String, String>();
        map.put("videoName", "测");
        map.put("pageIndex", "2");
        map.put("pageSize", "5");
        map.put("format", "json");
        cloudvHttpResponse = ApiAuthUtil.callPostFormUrlencodedBodyRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, map);
        log(cloudvHttpResponse);

        System.out.print("调用完毕");

    }

    public static void log(CloudvHttpResponse cloudvHttpResponse) throws Exception {
	//每次请求统一会带上一个X-WS-RequestId用来方便排查问题
        System.out.println("返回结果是：" + cloudvHttpResponse + " , requestId = " + cloudvHttpResponse.getHeaders().get("X-WS-RequestId"));
    }

}