To send a Security Center API request, you must send an HTTP GET request to the Security Center endpoint. You must add the request parameters that correspond to the API operation being called. After you call the API, the system returns a response. The request and response are encoded in UTF-8.

Request structure

Security Center API operations use the RPC protocol. You can call Security Center API operations by sending HTTP GET requests.

The request syntax is as follows:

https://Endpoint/?Action=xx&Parameters
where:
  • Endpoint: The endpoint of the Security Center API is tds.aliyuncs.com.
  • Action: the name of the operation being performed. For example, to query security events, you must set the Action parameter to DescribeAlarmEventList.
  • Version: the version of the API to be used. The current Security Center API version is 2018-12-03.
  • Parameters: the request parameters for the operation. Separate multiple parameters with ampersands (&).

    Request parameters include both common parameters and operation-specific parameters. Common parameters are used for all Security Center API calls regardless of the operation. For more information, see Common parameters.

The following example demonstrates how to call the DescribeAlarmEventList operation in Security Center.
Note The following code has been formatted for ease reading. 
http(s)://tds.aliyuncs.com/?Action=DescribeAlarmEventList
&Format=xml
&Version=2018-12-03
&Signature=xxxx%xxxx%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=key-test
&TimeStamp=2012-06-01T12:00:00Z
...

API authorization

To ensure the security of your account, we recommend that you call API operations as a Resource Access Management (RAM) user. Before you can call a Security Center API operation as a RAM user, you must create and attach the required permission policy to the RAM user.

Request signatures

You must sign all API requests to ensure security. Security Center uses the request signature to verify the identity of the API caller.

You must add the signature to the RPC API request in the following format:

https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
where:
  • SignatureMethod: the encryption method of the signature string. Set the value to HMAC-SHA1.
  • SignatureVersion: the version of the signature encryption algorithm. Set the value to 1.0.
  • SignatureNonce: a unique, random number used to prevent replay attacks. You must use different random numbers for different requests. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature generated after the request is symmetrically encrypted by using the AccessKey secret.

Security Center implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and RAM users that is similar to a logon username and password. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

Take the DescribeAlarmEventList operation as an example. If the AccessKey ID is testid and the AccessKey secret is testsecret, the original request URL is as follows: 
https://tds.aliyuncs.com/?Action=DescribeAlarmEventList
&TimeStamp=2016-02-23T12:46:24Z
&Format=XML
&AccessKeyId=testid
&SignatureMethod=HMAC-SHA1
&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
&Version=2018-01-17
&SignatureVersion=1.0
Perform the following operations to calculate the signature:
  1. Use the request parameters to compose a string-to-sign. 
    GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeAlarmEventList&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&TimeStamp%3D2016-02-23T12%253A46%253A24Z&Version%3D2018-12-03
    1. Create a canonicalized query string by arranging the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.

      If you use the GET method to submit a request, the request parameters are included as a part of the URI. The request parameters in the URI are placed after the question mark (?) and separated by ampersands (&).

    2. Encode the canonicalized query string in UTF-8. The following table describes the encoding rules.
      Character Encoding rule
      Uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), periods (.),and tildes (~) These characters do not need to be encoded.
      Other characters These characters must be percent encoded in the %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
      Extended UTF-8 characters These characters are encoded in the %XY%ZA…format.
      Spaces Spaces must be encoded as %20. Do not encode spaces as plus signs (+).

      This encoding rule is different from the rule that is used to encode data in the common Multi-purpose Internet Mail Extensions (MIME) format application/x-www-form-urlencoded. For example, java.net.URLEncoder in the standard Java library is in this MIME format.

      However, you can apply the MIME encoding algorithm and then replace the plus sign (+) in the encoded string with %20, the asterisk (*) with %2A, and %7E with the tilde (~). To do this, you can use the following percentEncode method: 

      private static final String ENCODING = "UTF-8";
private static String percentEncode(String value) throws UnsupportedEncodingException 
{
return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
}
    3. Connect the encoded parameter names and values by using equal signs (=).
    4. Sort the parameter name and value pairs in the order specified in Step i. Then, concatenate the pairs with ampersands (&) to construct the canonicalized query string.
  2. Calculate the HMAC value of the string-to-sign.
    Append an ampersand (&) after the AccessKey secret as the key to calculate the HMAC value. In this example, the key is testsecret&. 
    CT9X0VtwR86fNWSnsc6v8YGOjuE=
  3. Add the signature string to the request as the Signature parameter. 
    https://tds.aliyuncs.com/?Action=DescribeAlarmEventList
&TimeStamp=2016-02-23T12:46:24Z
&Format=XML
&AccessKeyId=testid
&SignatureMethod=HMAC-SHA1
&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
&Version=2018-12-03
&SignatureVersion=1.0
&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D
Note Alibaba Cloud offers SDKs for multiple programming languages and third-party SDKs to help you calculate the signature. For more information about Alibaba Cloud SDKs, see Alibaba Cloud SDKs.