Amazon Web Services
General Reference (Version 1.0)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »

Signing AWS API Requests

Requests to AWS must be signed—that is, they must include information that AWS can use to authenticate the requestor. Requests are signed using the access key ID and secret access key of an account or of an IAM user. (There are a few cases where requests do not have to be signed using an access key, such as anonymous requests to Amazon S3 and some APIs in AWS STS like AssumeRoleWithWebIdentity).

AWS currently supports three signature versions: signature version 2, signature version 3, and signature version 4. This section covers signature version 4 and signature version 2. Most services support version 4, and if a service supports version 4, we strongly recommend that you use that version.

Amazon Route 53 is the only service that requires signature version 3. For information about signature version 3, see Authenticating REST Requests in the Amazon Route 53 API Reference.

When Do You Need to Sign Requests?

If you are using one of the AWS SDKs, the AWS Command Line interface (CLI), or a service-specific CLI, you do not need to worry about signing requests. All you need to do is configure the tools with one or more access keys. These tools construct and send requests to AWS for you, and as part of that process, they sign the requests using an access key that you provide. They take care of many of the connection details, such as calculating signatures, handling request retries, and error handling. The SDKs also contain sample code, tutorials, and other resources to help you get started writing applications that call AWS.

If you are programmatically constructing HTTP or HTTPS requests to AWS, you do have to include code to sign the requests. You might do this for the following reasons:

  • You are working with a programming language for which there is no AWS SDK. For example, currently there is no AWS SDK for C.

  • A feature that you want to work with is not supported by an AWS SDK or by the CLI. This is not common, but one scenario is that there is a short period after a new service feature has been released before all AWS SDKs support the feature.

  • You want complete control over how a request is sent to AWS or over the response that is returned.

Why Requests Are Signed

The signing process helps secure requests in the following ways:

  • Verify the identity of the requester. Signing makes sure that the request has been issued by someone who has a valid access key ID and secret access key. For information about getting access keys, see How Do I Get Security Credentials? in the AWS General Reference.

    Requests can also be signed using temporary security credentials that are obtained using a call to an AWS STS API like AssumeRole or GetFederationToken. In that case, the request must include security token that's part of the temporary security credentials. For more information, go to Creating Temporary Security Credentials in the AWS Security Token Service documentation.

  • Protect data in transit. In order to prevent tampering with a request while it is in transit, some of the request elements are used to calculate a hash (digest) of the request, and the resulting hash value is included as part of the request. When AWS receives the request, it calculates a hash based on the same information and matches it against the hash value in the request that you include. If the hash values don't match, AWS denies the request.

  • Protect against potential replay attacks. A request must reach AWS within 15 minutes of the time stamp in the request. Otherwise, AWS denies the request.

For additional security, you should transmit your requests using Secure Sockets Layer (SSL) by using HTTPS. SSL encrypts the transmission, protecting your request or the response from being viewed in transit.

Making and Signing Requests Using REST or the Query API

AWS services support either REST protocol or a protocol that we refer to as Query API. For example, Amazon S3 and Amazon Route 53 support a REST API. Others, like Amazon EC2 and IAM, support a Query API. In both of these protocols, you make requests over HTTP or HTTPS using an HTTP verb (such as GET or POST) and a parameter named Action or Operation that specifies the API you are calling.

Note

Some AWS services formerly supported SOAP protocol for making requests to AWS. SOAP has been deprecated for AWS.

To sign a request, you calculate a hash (digest) of the request, and then use the hash value, some other values from the request, and a secret access key to create a signed hash—this is the signature.

You can add the signature to a request by using one of the following methods:

  • HTTP Authorization header. You can add the signature to the request using the HTTP Authorization header.

  • Query string parameters. You can add the signature as a query string value to the request. Because the request signature is part of the URL, this type of URL is referred to as a pre-signed URL.