Request signatures

Verification process

The symmetric-key algorithm is used to verify API requests based on AccessKey pairs of Alibaba Cloud. For more information, see AccessKey pair.

The following figure shows the procedure.

The following procedure describes how an API request is verified:

1. The client generates a string to be signed based on the HTTP header and body of an API request.
2. The client signs the string that is generated in Step 1 by using an AccessKey pair. This generates the digital signature of the API request.
3. The client sends the signed API request to the server.
4. The server receives the request and calculates the digital signature of the request. The same process that is described in Step 1 and Step 2 is used.
   Note The server retrieves the AccessKey pair that is used by this request from the backend.
5. The server compares the calculated digital signature with the digital signature that is sent from the client. If the two signatures are the same, the verification succeeds.

Sign an API request

Authorization = "LOG" + AccessKeyId + ":" + Signature

The value of the Authorization request header field contains an AccessKey ID and the digital signature that is calculated based on the AccessKey ID and the corresponding AccessKey secret. The following procedure describes how to calculate a digital signature:

1. Obtain an Alibaba Cloud AccessKey pair.
   For more information, see AccessKey pair. You can use an existing AccessKey pair or create an AccessKey pair. The AccessKey pair must be in the Active state.
2. Generate a string to be signed for the API request.
   The string contains information about the HTTP request method, HTTP request header, and request body. The string is in the following format:

   SignString = VERB + "\n"
                + CONTENT-MD5 + "\n"
                + CONTENT-TYPE + "\n"
                + DATE + "\n"
                + CanonicalizedLOGHeaders + "\n"
                + CanonicalizedResource

   In the preceding formula, \n is a newline character and the plus sign (+) is a string concatenation operator. The following table describes the other elements.

   Table 1. String elements

   Parameter	Description	Example
   VERB	The HTTP request method.	PUT, GET, and POST
   CONTENT-MD5	The MD5 hash of the HTTP request body. The value must be an uppercase string.	875264590688CA6171F6228AF5BBB3D2
   CONTENT-TYPE	The type of the HTTP request body.	application/x-protobuf
   DATE	The standard timestamp header field of the HTTP request. This timestamp header field follows the RFC 1123 specification and is in GMT.	Mon,3 Jan 2010 08:33:47 GMT
   CanonicalizedLOGHeaders	The string that is constructed from the custom fields in the HTTP request. The custom fields are prefixed by x-log and x-acs.	x-log-apiversion:0.6.0\nx-log-bodyrawsize:50\nx-log-signaturemethod:hmac-sha1
   CanonicalizedResource	The string that is constructed by the HTTP request resources.	/logstores/app_log

   CONTENT-TYPE

   If an HTTP request does not have a request body, the CONTENT-MD5 and CONTENT-TYPE fields are empty strings. The string to be signed is in the following format:

   SignString = VERB + "\n"
                + "\n"
                + "\n"
                + DATE + "\n"
                + CanonicalizedLOGHeaders + "\n"
                + CanonicalizedResource

   The x-log-date field is a custom HTTP request header field. For more information, see Common request headers. If you specify this field in an API request, the value of this field replaces the value of the DATE header field in signature calculation.

   • The following procedure describes how to construct the CanonicalizedLOGHeaders string:
     1. Convert the names of all HTTP request fields that are prefixed with x-log and x-acs into lowercase letters.
     2. Sort all custom request fields that are obtained in the previous step in lexicographical order.
     3. Delete all spaces on either side of a delimiter between the request header and content.
     4. Separate all headers and contents with the \n delimiter to obtain the CanonicalizedLOGHeader string.
   • The following procedure describes how to construct the CanonicalizedResource string:
     1. Set the CanonicalizedResource string to an empty string " ".
     2. Enter the Log Service resources that you want to access, for example, /logstores/logstorename. If no Logstore is created in a project, this string can be left blank.
     3. If the request contains a query string QUERY_STRING, add a question mark (?) suffixed by the query string at the end of the CanonicalizedResource string.
     QUERY_STRING is the lexicographic string of the request parameters in the URL. Equal signs (=) are used between the names and values of parameters. The parameter name-value pairs are then sorted in lexicographical order and connected with ampersands (&) to form a string. The following formula shows how to construct a query string:

     QUERY_STRING = "KEY1=VALUE1" + "&" + "KEY2=VALUE2"

3. Generate a digital signature for the request.
   Use the digital signature algorithm hmac-sha1 to calculate the digital signature of an API request. Log Service supports only this algorithm for the calculation of digital signatures. Use the algorithm in the following format:

   Signature = base64(hmac-sha1(UTF8-Encoding-Of(SignString), AccessKeySecret))

   • The value generated by the signature algorithm is encoded using standard Base64.
   • The HMAC-SHA1 algorithm is defined in RFC 2104. The AccessKey secret in the preceding formula must match the AccessKey ID in the Authorization field. Otherwise, the request cannot be verified by Log Service.
   • After the digital signature is generated, enter the signature into the Authorization header field. Then, enter the header field in the HTTP request and send the request.
   • A signature string must be encoded in UTF-8. A signature string that contains Chinese characters must be encoded in UTF-8. The encoded signature string is used together with AccessKeySecret to calculate the final signature.
   • The CONTENT-MD5 and CONTENT-TYPE fields are optional. If the values of these fields are null, replace the null values with line feeds \n instead.

Examples

AccessKeyId = "bq2sjzesjmo86kq*********"
AccessKeySecret = "4fdO2fTDDnZPU/L7CHNd********"

• Example 1
  To list all Logstores of a project named ali-test-project, send the following GET request:

  GET /logstores?logstoreName=&offset=0&size=1000 HTTP 1.1
  Mon, 09 Nov 2015 06:11:16 GMT
  Host: ali-test-project.regionid.example.com
  x-log-apiversion: 0.6.0
  x-log-signaturemethod: hmac-sha1

  The following string is the string to be signed that is generated for the API request:

  GET\n\n\nMon, 09 Nov 2015 06:11:16 GMT\nx-log-apiversion:0.6.0\nx-log-signaturemethod:hmac-sha1\n/logstores?logstoreName=&offset=0&size=1000

  A GET request does not have an HTTP body. The values of the CONTENT-MD5 and CONTENT-TYPE fields are empty strings. The following string is the digital signature calculated by using the specified AccessKey secret:

  jEYOTCJs2e88o+y5F4/S5IsnBJQ=

  The following request is a signed API request:

  GET /logstores?logstoreName=&offset=0&size=1000 HTTP 1.1
  Mon, 09 Nov 2015 06:11:16 GMT
  Host: ali-test-project.regionid.example.com
  x-log-apiversion: 0.6.0
  x-log-signaturemethod: hmac-sha1
  Authorization: LOG bq2sjzesjmo86kq35behupbq:jEYOTCJs2e88o+y5F4/S5IsnBJQ=

• Example 2
  You want to write the following log entry to the test-logstore Logstore that belongs to the ali-test-project project:

  topic=""
  time=1447048976
  source="10.10.10.1"
  "TestKey": "TestContent"

  To implement this, send the following POST request:

  POST /logstores/test-logstore HTTP/1.1
  Date: Mon, 09 Nov 2015 06:03:03 GMT
  Host: test-project.regionid.example.com
  x-log-apiversion: 0.6.0
  x-log-signaturemethod: hmac-sha1
  Content-MD5: 1DD45FA4A70A9300CC9FE7305AF2C494
  Content-Length: 52
  x-log-apiversion:0.6.0
  x-log-bodyrawsize:50
  x-log-compresstype:lz4
  x-log-signaturemethod:hmac-sha1
  <The log entry is serialized to byte streams in the ProtoBuffer format.>

  The log entry that you want to write to Log Service is serialized to byte streams in the ProtoBuffer format and then used as the HTTP request body. For more information about the ProtoBuffer format, see Data encoding. In this case, the value of the Content-Type header field is application/x-protobuf. The value of the Content-MD5 header field is the MD5 hash of the HTTP request body. The following string is the string to be signed that is generated for the API request:

  POST\n1DD45FA4A70A9300CC9FE7305AF2C494\napplication/x-protobuf\nMon, 09 Nov 2015 06:03:03 GMT\nx-log-apiversion:0.6.0\nx-log-bodyrawsize:50\nx-log-compresstype:lz4\nx-log-signaturemethod:hmac-sha1\n/logstores/test-logstore

  The following string is the digital signature calculated by using the specified AccessKey secret:

  XWLGYHGg2F2hcfxWxMLiNkGki6g=

  The following request is a signed API request:

  POST /logstores/test-logstore HTTP/1.1
  Date: Mon, 09 Nov 2015 06:03:03 GMT
  Host: test-project.regionid.example.com
  x-log-apiversion: 0.6.0
  x-log-signaturemethod: hmac-sha1
  Content-MD5: 1DD45FA4A70A9300CC9FE7305AF2C494
  Content-Length: 52
  x-log-apiversion:0.6.0
  x-log-bodyrawsize:50
  x-log-compresstype:lz4
  x-log-signaturemethod:hmac-sha1
  Authorization: LOG bq2sjzesjmo86kq35behupbq:XWLGYHGg2F2hcfxWxMLiNkGki6g=
  <The log entry is serialized to byte streams in the ProtoBuffer format.>