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.
- The requester generates a SignString based on the API request content (including the HTTP Header and Body).
- 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.
- The requester sends both the API request content and digital signature to the server.
- 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.
- 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.
- 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.
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.
|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
|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.
- Convert the names of all HTTP request headers prefixed with
x-acsto lowercase letters.
- Sort all Log Service custom request headers obtained in the previous step lexicographically in ascending order.
- Delete any space at either side of a separator between request header and content.
- Separate all headers and contents with the
\nseparator to form the final CanonicalizedLOGHeader.
- Set CanonicalizedResource to an empty string ("").
- Enter the Log Service resources to be accessed. For example, /logstores/logstorename. The field is left blank if the
logstorenamedoes not exist.
- If the request contains a query string (
QUERY_STRING), add question mark (?) and the query string at the end of 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********"
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
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=
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:
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>