Signing AWS Requests with Signature Version 4
This section explains how to create a signature and add it to a request.
- What Signing Looks Like in a Request
- GET and POST Requests in the Query API
- Summary of Signing Steps
- Task 1: Create a Canonical Request for Signature Version 4
- Task 2: Create a String to Sign for Signature Version 4
- Task 3: Calculate the Signature for AWS Signature Version 4
- Task 4: Add the Signing Information to the Request
What Signing Looks Like in a Request
The following example shows what an HTTPS request might look like as it is sent from your client to AWS, without any signing information.
GET https://iam.amazonaws.com/?Action=ListUsers&Version=2010-05-08 HTTP/1.1 Content-Type: application/x-www-form-urlencoded; charset=utf-8 Host: iam.amazonaws.com X-Amz-Date: 20150830T123600Z
After you complete the signing tasks, you add the authentication information to the request. You can add the authentication information in two ways:
You can add the authentication information to the request with an
Authorization header. Although the HTTP header is named
Authorization, the signing information is actually used for authentication to
establish who the request came from.
Authorization header includes the following information:
Algorithm you used for signing (AWS4-HMAC-SHA256)
Credential scope (with your access key ID)
List of signed headers
Calculated signature. The signature is based on your request information, and you use your AWS secret access key to produce the signature. The signature confirms your identity to AWS.
The following example shows what the preceding request might look like after you've
created the signing information and added it to the request in the
GET https://iam.amazonaws.com/?Action=ListUsers&Version=2010-05-08 HTTP/1.1 Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20150830/us-east-1/iam/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924a6f2b5d7 content-type: application/x-www-form-urlencoded; charset=utf-8 host: iam.amazonaws.com x-amz-date: 20150830T123600Z
As an alternative to adding authentication information with an HTTP request header, you can include it in the query string. The query string contains everything that is part of the request, including the name and parameters for the action, the date, and the authentication information.
The following example shows how you might construct a GET request with the action and authentication information in the query string.
GET https://iam.amazonaws.com?Action=ListUsers&Version=2010-05-08&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20150830%2Fus-east-1%2Fiam%2Faws4_request&X-Amz-Date=20150830T123600Z&X-Amz-Expires=60&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=37ac2f4fde00b0ac9bd9eadeb459b1bbee224158d66e7ae5fcadb70b2d181d02 HTTP/1.1 content-type: application/x-www-form-urlencoded; charset=utf-8 host: iam.amazonaws.com
GET and POST Requests in the Query API
The query API that many AWS services support lets you make requests using either HTTP
POST. (In the query API, you can use
even if you're making requests that change state; that is, the query API is not inherently
GET requests pass parameters on the query string, they are
limited to the maximum length of a URL. If a request includes a large payload (for example,
you might upload a large IAM policy or send many parameters in JSON format for a DynamoDB
request), you generally use a
The signing process is the same for both types of requests.
Summary of Signing Steps
To create a signed request, complete the following:
Arrange the contents of your request (host, action, headers, etc.) into a standard (canonical) format. The canonical request is one of the inputs used to create a string to sign.
Create a string to sign with the canonical request and extra information such as the algorithm, request date, credential scope, and the digest (hash) of the canonical request.
Derive a signing key by performing a succession of keyed hash operations (HMAC operations) on the request date, region, and service, with your AWS secret access key as the key for the initial hashing operation. After you derive the signing key, you then calculate the signature by performing a keyed hash operation on the string to sign. Use the derived signing key as the hash key for this operation.
After you calculate the signature, add it to an HTTP header or to the query string of the request.
The AWS SDKs handle the signature calculation process for you, so you do not have to manually complete the signing process. For more information, see Tools for Amazon Web Services.
The following additional resources illustrate aspects of the signing process:
Examples of the Complete Version 4 Signing Process (Python). This set of programs in Python provide complete examples of the signing process. The examples show signing with a
POSTrequest, with a
GETrequest that has signing information in a request header, and with a
GETrequest that has signing information in the query string.
Signature Version 4 Test Suite. This downloadable package contains a collection of examples that include signature information for various steps in the signing process. You can use these examples to verify that your signing code is producing the correct results at each step of the process.