This article describes the elements and calculation method of the Message Service (MNS) signature mechanism. This article also provides examples about how to sign API requests.

Elements

MNS verifies each API request to ensure data security. Therefore, each request that is sent to MNS must contain the Authorization header. MNS implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. If the signature that is calculated by MNS is the same as the signature in the Authorization header, the request is valid. Otherwise, MNS rejects the request and returns the HTTP status code 403.

To indicate that an HTTP request is valid, you must add the Authorization header to the HTTP request and include the signature in the Authorization header. Syntax: Authorization: MNS AccessKeyId:Signature.

You can use your Alibaba Cloud account to apply for and manage an AccessKey ID and AccessKey secret in the Alibaba Cloud User Management console. An AccessKey ID identifies a user. An AccessKey secret encrypts the signature string and is the key that the server uses to authenticate the signature string. The AccessKey pair must be kept confidential.

Calculation method

You can also use the Signature verification tool to calculate the signature.

Authorization = base64(hmac-sha1(HTTP_METHOD + "\n" 
             + CONTENT-MD5 + "\n"     
             + CONTENT-TYPE + "\n" 
             + DATE + "\n" 
             + CanonicalizedMNSHeaders
             + CanonicalizedResource))  
  • HTTP_METHOD: an uppercase HTTP method,

    such as PUT, GET, POST, and DELETE.

  • Content-MD5: the MD5 hash of the request body.

    If the request does not contain the Content-MD5 header, enter an empty string.

  • CONTENT-TYPE: the content format of the request body.
  • DATE: the time when the request is sent,
    • for example, Thu, 07 Mar 2012 18:49:58 GMT. If you use the x-mns-date parameter instead of the DATE parameter, you must enter the value of the x-mns-date parameter.
    • This parameter cannot be an empty string and must be in the GMT format.
    • If MNS does not receive a request within 15 minutes after the request is sent, MNS returns the error code 400. For more information, see Syntax of error responses.
  • CanonicalizedMNSHeaders: a combination of HTTP headers that are prefixed by x-mns-.
    Take note of the following naming conventions for the CanonicalizedHeaders parameter:
    • The names of the headers must be in lowercase.
    • The headers must be sorted in ascending order.
    • Do not add a space before or after the colon (:) that separates a header name and value.
    • Each header is followed by a line feed (\n). Do not specify the CanonicalizedMNSHeaders parameter if no headers are prefixed by x-mns-.
  • CanonicalizedResource: the URI of the resource that is requested by the HTTP request.

    Example: /queues/$queueName? metaOverride=true.

Note
  • A string-to-sign must be in the UTF-8 format.
  • Use the HMAC-SHA1 signature method that is defined in RFC 2104 and use the AccessKey secret as the key.
  • The content-type and content-md5 parameters are optional in a request. If you do not need to specify these parameters, enter ''.

Examples

Sample requests

PUT /queues/$queueName? metaOverride=true HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 08 Mar 2012 12:00:00 GMT
Authorization: MNS 15B4D3461F177624****:xQE0diMbL****f3YB+FIEXAMPLE=

<? xml version="1.0" encoding="UTF-8"  ? >
<Queue xmlns="http://mns.aliyuncs.com/doc/v1/">
<VisibilityTimeout >60</VisibilityTimeout>
<MaximumMessageSize>1024</MaximumMessageSize>
<MessageRetentionPeriod>120</MessageRetentionPeriod>
<DelaySeconds>30</DelaySeconds>
</Queue>       

Sample response 1

If the AccessKey ID does not exist or is in the Disabled state, the 403 Forbidden error is returned.

Content-Type: text/xml
Content-Length: 314
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****

<? xml version="1.0" encoding="utf-8"? >
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>AccessIDAuthError</Code>
<Message>
    AccessID authentication fail, please check your AccessID and retry.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>       

Sample response 2

If the Date parameter is not specified in the header or the format of the Date parameter is invalid, the 403 Forbidden error is returned.

Content-Type: text/xml
Content-Length: 274
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****

<? xml version="1.0" encoding="UTF-8"? >
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>InvalidArgument</Code>
<Message>Date Header is invalid or missing. </Message>
<RequestId>7E1A5CF258F535884403****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>         

Sample response 3

If MNS does not receive a request within 15 minutes after the request is sent, the error 408 Request Timeout is returned.

Content-Type: text/xml
Content-Length: 283
Date: Wed, 11 May 2011 09:01:51 GMT
x-mns-request-id: 512B2A634403E52B1956****

<? xml version="1.0"  encoding="UTF-8"? >
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>TimeExpired</Code>
<Message>
        The http request you sent is expired.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>