Signing AWS API requests

Important

If you use an AWS SDKs (see Sample Code and Libraries) or AWS command line (CLI) tool to send API requests to AWS, you can skip this section because the SDK and CLI clients authenticate your requests by using the access keys that you provide. Unless you have a good reason not to, we recommend that you always use an SDK or the CLI.

In Regions that support multiple signature versions, manually signing requests mean you must specify which signature version is used. When you supply requests to Multi-Region Access Points, SDKs and the CLI automatically switch to using Signature Version 4A without additional configuration.

Authentication information that you send in a request must include a signature. To calculate a signature, you first concatenate select request elements to form a string, referred to as the string to sign. You then use a signing key to calculate the hash-based message authentication code (HMAC) of the string to sign.

In AWS Signature Version 4, you don't use your secret access key to sign the request. Instead, you first use your secret access key to derive a signing key. The derived signing key is specific to the date, service, and Region. For more information about how to derive a signing key in different programming languages, see Request signature examples.

Signature Version 4 is the AWS signing protocol. AWS also supports an extension, Signature Version 4A, which supports signatures for multi-Region API requests. For more information, see the sigv4a-signing-examples project on GitHub.

The following diagram illustrates the general process of computing a signature.

• The string to sign depends on the request type. For example, when you use the HTTP Authorization header or the query parameters for authentication, you use a varying combination of request elements to create the string to sign. For an HTTP POST request, the POST policy in the request is the string you sign.

• For signing key, the diagram shows series of calculations, where result of each step you feed into the next step. The final step is the signing key.

• When an AWS service receives an authenticated request, it recreates the signature using the authentication information contained in the request. If the signatures match, the service processes the request. Otherwise, it rejects the request.

Contents

• When to sign requests
• Why requests are signed
• Elements of an AWS API request signature
• Authentication methods
• Create a signed AWS API request
• Request signature examples
• Troubleshoot signed requests for AWS APIs

When to sign requests

When you write custom code that sends API requests to AWS, you must include code that signs the requests. You might write custom code because:

• You are working with a programming language for which there is no AWS SDK.

• You need complete control over how requests are sent to AWS.

Why requests are signed

The signing process helps secure requests in the following ways:

• Verify the identity of the requester

  Authenticated requests require a signature that you create by using your access keys (access key ID, secret access key). If you are using temporary security credentials, the signature calculations also require a security token. For more information, see AWS security credentials programmatic access.

• Protect data in transit

  To prevent tampering with a request while it's 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 an AWS service receives the request, it uses the same information to calculate a hash and matches it against the hash value in your request. If the values don't match, AWS denies the request.

• Protect against potential replay attacks

  In most cases, a request must reach AWS within five minutes of the time stamp in the request. Otherwise, AWS denies the request.