Authenticating REST Requests

The Amazon S3 REST API uses the standard HTTP Authorization header to pass authentication information. (The name of the standard header is unfortunate, since it carries authentication information, not authorization). Under the Amazon S3 authentication scheme, the Authorization header has the following form:

                    Authorization: AWS AWSAccessKeyId:Signature
                

Developers are issued an AWS Access Key Id and AWS Secret Access Key when they register. For request authentication, the AWSAccessKeyId element identifies the secret key that was used to compute the signature, and (indirectly) the developer making the request.

The Signature element is the RFC 2104 HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, then the requester will have demonstrated possession to the AWS Secret Access Key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.

The following pseudo-grammar illustrates the construction of the Authorization request header. (\n means the Unicode code point U+000A)

                Authorization = "AWS" + " " + AWSAccessKeyId + ":" + Signature;

                Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) );

                StringToSign = HTTP-Verb + "\n" +
                               Content-MD5 + "\n" +
                               Content-Type + "\n" +
                               Date + "\n" +
                               CanonicalizedAmzHeaders + 
                               CanonicalizedResource;

                CanonicalizedResource = [ "/" + Bucket ] +
                                        <HTTP-Request-URI, from the protocol name up to the query string> +
                                        [ sub-resource, if present. For example "?acl", "?location", "?logging", or "?torrent"];

                CanonicalizedAmzHeaders = <described below>

                

To construct the CanonicalizedAmzHeaders part of StringToSign, select all HTTP request headers that start with 'x-amz-' (using a case-insensitive comparison) and do the following:

Finally, append a new-line (U+000A) to each canonicalized header in the resulting list. Construct the CanonicalizedResource element by concatenating all headers in this list into a single string.

The first few header elements of StringToSign (Content-Type, Date, and Content-MD5) are positional in nature. StringToSign does not include the names of these headers, only their values from the request. In contrast, the 'x-amz-' elements are named; Both the header names and the header values appear in StringToSign.

If a positional header called for in the definition of StringToSign is not present in your request, (Content-Type or Content-MD5, for example, are optional for PUT requests, and meaningless for GET requests), substitute the empty string ("") in for that position.

A valid time-stamp (using either the HTTP Date header or an x-amz-date alternative) is mandatory for authenticated requests. Furthermore, the client time-stamp included with an authenticated request must be within 15 minutes of the Amazon S3 system time when the request is received. If not, the request will fail with the RequestTimeTooSkewed error status code. The intention of these restrictions is to limit the possibility that intercepted requests could be replayed by an adversary. For stronger protection against eavesdropping, use the HTTPS transport for authenticated requests.

Some HTTP client libraries do not expose the ability to set the Date header for a request. If you have trouble including the value of the 'Date' header in the canonicalized headers, you can set the time-stamp for the request using an 'x-amz-date' header instead. The value of the x-amz-date header must be in one of the RFC 2616 formats (http://www.ietf.org/rfc/rfc2616.txt). When an x-amz-date header is present in a request, the system will ignore any Date header when computing the request signature. Therefore, if you include the x-amz-date header, use the empty string for the Date when constructing the StringToSign. See the next section for an example.

The following examples use the following (non-working) credentials:

In the example StringToSigns, formatting is not significant and \n means the Unicode code point U+000A.

When REST request authentication fails, the system responds to the request with an XML error document. The information contained in this error document is meant to help developers diagnose the problem. In particular, the StringToSign element of the SignatureDoesNotMatch error document tells you exactly what request canonicalization the system is using.

Some toolkits may silently insert headers that you do not know about beforehand, such as adding the header Content-Type during a PUT. In most of these cases, the value of the inserted header remains constant, allowing you to discover the missing headers using tools such as Ethereal or tcpmon.