Amazon Signature Version 4 for API requests
Important
If you use an Amazon SDK (see Sample Code and
Libraries
In Regions that support multiple signature versions, manually signing requests means you must specify which signature version to use. 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. Amazon Signature Version 4 (SigV4) is the Amazon signing protocol for adding authentication information to Amazon API requests.
You don't use your secret access key to sign API requests. Instead, you use the SigV4 signing process. Signing requests involves:
-
Creating a canonical request based on the request details.
-
Calculating a signature using your Amazon credentials.
-
Adding this signature to the request as an Authorization header.
Amazon then replicates this process and verifies the signature, granting or denying access accordingly.
Note
Amazon also supports an extension, Signature Version 4A, which supports signatures for multi-Region
API requests. For more information, see the sigv4a-signing-examples
How Amazon SigV4 works
The following diagram illustrates the general process of computing a signature:
![An image of the parts of a signature, including the string to sign, signing key, and calculated signature.](images/signing-overview.png)
-
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 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. -
The signing key is a series of calculations, with the result of each step fed into the next. The final step is the signing key.
-
When an Amazon 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.
For more information, see Elements of an Amazon API request signature.
When to sign requests
When you write custom code that sends API requests to Amazon, 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 Amazon SDK.
-
You need complete control over how requests are sent to Amazon.
While API requests authenticate access with Amazon SigV4, Amazon SDKs and the Amazon CLI authenticate your requests by using the access keys that you provide. For more information about authenticating with Amazon SDKs and the Amazon CLI, see Additional resources.
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 Amazon 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 Amazon Web Services 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, Amazon denies the request.
-
Protect against potential replay attacks
In most cases, a request must reach Amazon within five minutes of the time stamp in the request. Otherwise, Amazon denies the request.
Amazon SigV4 can be expressed in the HTTP Authorization header or as a query string in the URL. For more information, see Authentication methods.
Additional resources
-
For more information about the SigV4 signing process for different services, see Request signature examples.
-
To configure credentials for programmatic access for the Amazon CLI, see Authentication and access credentials in the Amazon Command Line Interface User Guide.
-
The Amazon SDKs include source code on GitHub for signing Amazon API requests. For code samples, see Example projects in Amazon samples repository.
-
Amazon SDK for .NET – AWS4Signer.cs
-
Amazon SDK for C++ – AWSAuthV4Signer.cpp
-
Amazon SDK for Go – v4.go
-
Amazon SDK for Java – BaseAws4Signer.java
-
Amazon SDK for JavaScript – v4.js
-
Amazon SDK for PHP – SignatureV4.php
-
Amazon SDK for Python (Boto) – signers.py
-
Amazon SDK for Ruby – signer.rb
-