This topic describes how to sign API requests.

Signature mechanism

An AccessKey pair is an identity credential that is assigned to an Alibaba Cloud account or Resource Access Management (RAM) user. To create and manage an AccessKey pair, you can go to the AccessKey Management page of the Alibaba Cloud Management Console. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user. The AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey pair strictly confidential.

Message Service (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 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 the following sample code to calculate the signature in the Authorization header.

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.

    This parameter cannot be an empty string and must be in the UTC format. If MNS does not receive a request within 15 minutes after the request is sent, the error code 400 is returned. For more information about the error message and error code, see Syntax of error responses. For example, Thu, 07 Mar 2012 18:49:58 UTC. If you use the x-mns-date parameter instead of the DATE parameter, you must enter the value of the x-mns-date parameter.

  • CanonicalizedMNSHeaders: a combination of HTTP headers that are prefixed with x-mns-. For more information, see the following usage notes.
    Note You must note the following naming conventions of the CanonicalizedHeaders parameter (the headers that are prefixed with x-mns-).
    • 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 with x-mns-.
  • CanonicalizedResource: the URI of the resource that is requested by the HTTP request. For 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.
  • content-type and content-md5 are not required parameters in a request. If you do not 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 15B4D3461F177624206A:xQE0diMbLRepdf3YB+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 responses
    • If the AccessKey ID does not exist or in the Disabled state, the error 403 Forbidden is returned.

      Sample response 1

          Content-Type: text/xml
          Content-Length: 314
          Date: Wed, 18Mar 2012 08:04:06 GMT
          x-mns-request-id: 512B2A634403E52B1956133E
      
          <? 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>512B2A634403E52B1956133E</RequestId>
          <HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
          </Error>          
    • If the Date parameter is not specified in the header or the format of the Date parameter is invalid, the error 403 Forbidden is returned.

      Sample response 2

          Content-Type: text/xml
          Content-Length: 274
          Date: Wed, 18Mar 2012 08:04:06 GMT
          x-mns-request-id: 512B2A634403E52B1956133E
      
          <? 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>7E1A5CF258F535884403E533</RequestId>
          <HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
          </Error>           
    • If MNS does not receive a request within 15 minutes after the request is sent, the error 408 Request Timeout is returned.

      Sample response 3

          Content-Type: text/xml
          Content-Length: 283
          Date: Wed, 11 May 2011 09:01:51 GMT
          x-mns-request-id: 512B2A634403E52B1956133E
      
          <? 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>512B2A634403E52B1956133E</RequestId>
          <HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
          </Error>