To ensure security of users' log data, all HTTP requests of the Log Service API must undergo security authentication. Currently, this security authentication is based on the Alibaba Cloud AccessKey and is completed by using the symmetric encryption algorithm.

This process is as follows:
  1. The requester generates a SignString based on the API request content (including the HTTP Header and Body).
  2. The requester uses Alibaba Cloud's access key pair (AccessKeyID and AccessKeySecret) to sign the signature string generated in the first step, forming a digital signature for this API request.
  3. The requester sends both the API request content and digital signature to the server.
  4. After receiving the request, Log Service repeats steps 1 and 2 and computes the expected digital signature for this request. Note: Log Service retrieves the AccessKey pair used by this request from the backend.
  5. The server compares the expected digital signature to the digital signature sent with the request. If they are completely consistent, the request passes security authentication. Otherwise, the request is immediately rejected.

The entire process can be intuitively described by the following diagram.

Figure 1. Security verification process
The security authentication process above can also be used for the following purposes:
  • Confirm which user sends the API request. Because a user is required to designate the key pair to generate the digital signature before sending the request, the server can use this key pair to confirm the user's identity and then perform access permission management.
  • Confirm whether or not the user request is tampered during the network transmission. This is because Log Service recomputes the digital signature for the received request content. If the request content is tampered during the network transmission, the digital signature cannot match.

Sign an API request

To pass the API request security authentication, you must sign this API request in the client (namely, generate a correct digital signature) and use the HTTP header  Authorization The specific formats are as follows. 

Authorization:LOG <AccessKeyId>:<Signature>

As shown in the preceding format, the Authorization header value contains the AccessKey ID of the AccessKey pair and the corresponding AccessKey Secret is used to construct the signature value.  Follow these steps to construct the

Step 1: Prepare a suitable Alibaba Cloud AccessKey pair

To generate a digital signature for an API request, you must use an AccessKey pair (AccessKey ID and AccessKey Secret).  You can use an existing AccessKey pair or create a new one. The AccessKey pair must be in the "Active" state.

Step 2: Generate the signature string of the request

The signature string of a Log  Service API is generated by using the method, header, and body of the HTTP request. See the detailed generation method as follows: 

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

In the preceding formula, \n indicates the newline escape character and the plus sign (+) indicates the string concatenation operation. The other parts are defined as follows.

Table 1. Signing string Definitions
Name Definitions Example 
VERB The method name of the HTTP request. PUT, GET, and POST
CONTENT-MD5 The type of the HTTP request body. 875264590688CA6171F6228AF5BBB3D2
CONTENT-TYPE  The type of the HTTP request body. application/x-protobuf
DATE The standard timestamp header of the HTTP request, which follows the RFC 1123 format and uses the GMT standard time. Mon, 3 Jan 2010 08:33:47 GMT
CanonicalizedLOGHeaders The string constructed by custom headers prefixed by x-log and x-acs in the HTTP request (for the specific construction method, see the following description). x-log-apiversion:0.6.0\nx-log-bodyrawsize:50\nx-log-signaturemethod:hmac-sha1
CanonicalizedResource A string constructed by an HTTP request Resource (specific construction method to meet in detail) /logstores/app_log

In some HTTP requests without the Body, the CONTENT-MD5 and CONTENT-TYPE fields are null strings respectively. Described below is how to generate a SignString in such case: 

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

As described in  Public request header, the custom request header x-log-date is introduced to Log Service APIs. If you specify this header in your request, the header value will replace the value of the HTTP standard request header Date to compute the request signature.

The CanonicalizedLOGHeaders construction method is as follows:
  1. Convert the names of all HTTP request headers prefixed with x-log and x-acs to lowercase letters.
  2. Sort all Log Service custom request headers obtained in the previous step lexicographically in ascending order.
  3. Delete any space at either side of a separator between request header and content. 
  4. Separate all headers and contents with the \n separator to form the final CanonicalizedLOGHeader.
The CanonicalizedResource construction method is as follows:
  1. Set CanonicalizedResource to an empty string ("").
  2. Enter the Log Service resources to be accessed. For example, /logstores/logstorename.  The field is left blank if the logstorename does not exist.
  3. If the request contains a query string (QUERY_STRING), add question mark (?) and the query string at the end of the ? CanonicalizedResource string.

The QUERY_STRING  is a string generated after the request parameters in the URL are sorted lexicographically. Use an equal sign (  = ) between the parameter name and the parameter value to form a string. Sort the parameter name - value pairs lexicographically in ascending order. Then, use & to connect  the pairs to form a string.  The formula is as follows: 

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

Step 3: Generate the digital signature of the request

Currently, Log Service API only supports one digital signature algorithm, namely, the default signature algorithm hmac-sha1. The entire signature formula is as follows: 

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

Use the HMAC-SHA1 method defined in RFC 2104 as the signature method. The AccessKey Secret used in the preceding formula Service. must correspond to the AccessKey ID used in the  final Authorization header.  Otherwise, the request will not be able to pass authentication by the server.

After the digital signature value is computed, use the value to construct a complete security authentication header for the Log Service API request in the Authorization header format as described at the beginning of this section, and enter the security authentication header in the HTTP request. Then, the HTTP request can be sent.

Examples of the request signature process

To better understand the complete request signature process, use two examples to demonstrate the process.  First, assume that the AccessKey pair used for Log  Service API signature is as follows: 

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

Example 1:

To send the following GET request to list all the Logstores in the ali-test-project project. The HTTP  request is as follows: 

GET /logstores 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 signature string generated by the preceding Log Service API request is as follows:

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

As a GET request, this request has no HTTP body. Therefore, the CONTENT-TYPE and CONTENT-MD5 : fields in the generated signature string are empty strings. To use the previously specified AccessKey Secret to compute the request signature, the obtained signature is as follows 

jEYOTCJs2e88o+y5F4/S5IsnBJQ=

Finally, the digitally signed HTTP request content sent is as follows:

GET /logstores 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 must write the following logs to the Logstore test-logstore in the project  ali-test-project.

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

Therefore, according to the Log Service API definition, the following HTTP request must be constructed: 

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
<Log contents are serialized to byte streams in the ProtoBuffer format>

In this HTTP request, the written log content is first serialized to the ProtoBuffer format (for more information, see ProtoBuffer format ) and then used as the request body.  Therefore, the Content-Type header value of this request is application/x-protobuf.  Similarly, the Content-MD5 header value is the MD5  parameters. According to the above signature string construction method, the signature string corresponding to this request is: 

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

In the same way, if the AccessKeySecret specified previously is used to calculate a signature, the resulting signature will be: 

XWLGYHGg2F2hcfxWxMLiNkGki6g=

Finally, the digitally signed HTTP request content sent is as follows:

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=
<Log contents are serialized to byte streams in the ProtoBuffer format>