Documentation Amazon Simple Storage Service (S3)API Reference

Authenticating Requests: Using theAuthorization Header (AWS Signature Version 4)

Topics

Overview
Signature Calculations for the Authorization Header:Transferring Payload in a Single Chunk (AWS Signature Version 4)
Signature Calculations for the Authorization Header:Transferring Payload in Multiple Chunks (Chunked Upload) (AWS Signature Version4)
Signature calculations for trailing headers(chunked uploads) (AWS Signature Version 4)

Overview

Using the HTTPAuthorization header is the most common method of providingauthentication information. Except forPOSTrequests and requests that are signed by using query parameters, all Amazon S3operations use theAuthorization request header to provideauthentication information.

The following is an example of theAuthorization header value. Linebreaks are added to this example for readability:


Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;range;x-amz-date,Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

The following table describes the various components of theAuthorization header value inthe preceding example:

Component	Description
`AWS4-HMAC-SHA256`	The algorithm that was used to calculate the signature.You must provide this value when you use AWS SignatureVersion 4 for authentication. The string specifies AWS Signature Version 4 (`AWS4`) andthe signing algorithm (`HMAC-SHA256`).
`Credential`	Your access key ID and the scope information, which includes the date, Region, andservice that were used to calculate the signature. This string has the following form: `<your-access-key-id>/<date>/<aws-region>/<aws-service>/aws4_request` Where: `<date>` value isspecified using`YYYYMMDD`format. `<aws-service>`value is`s3` when sending request toAmazon S3.
`SignedHeaders`	A semicolon-separated list of request headers that youused to compute`Signature`. The list includesheader names only, and the header names must be inlowercase. For example: `host;range;x-amz-date`
`Signature`	The 256-bit signature expressed as 64 lowercase hexadecimal characters. For example: `fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024` Notethat the signature calculations vary depending on the option youchoose to transfer the payload.

The signature calculations vary depending on the method you choose to transfer the requestpayload. S3 supports the following options:

Transfer payload in a single chunk– In this case, you have the following signaturecalculation options:
- Signed payload option – You can optionally compute the entire payload checksum andinclude it in signature calculation. This provides addedsecurity but you need to read your payload twice orbuffer it in memory.
  For example, in order to upload a file, you need to read the file first tocompute a payload hash for signature calculation and againfor transmission when you create the request. For smallerpayloads, this approach might be preferable. However, forlarge files, reading the file twice can be inefficient, so you might want to upload data in chunks instead.
  We recommend you include payload checksum for addedsecurity.
- Unsigned payload option – Do not include payload checksum in signature calculation.
For step-by-step instructions to calculate signature and construct the Authorizationheader value, see Signature Calculations for the Authorization Header:Transferring Payload in a Single Chunk (AWS Signature Version 4).
Transfer payload in multiple chunks (chunked upload) – In this case you transfer payloadin chunks. You can transfer a payload in chunks regardless of thepayload size.
You can break up your payload into chunks. These can be fixed orvariable-size chunks. By uploading data in chunks, you avoid reading theentire payload to calculate the signature. Instead, for the first chunk,you calculate a seed signature that uses only the request headers. Thesecond chunk contains the signature for the first chunk, and eachsubsequent chunk contains the signature for the chunk that precedes it.At the end of the upload, you send a final chunk with 0 bytes of datathat contains the signature of the last chunk of the payload. For moreinformation, seeSignature Calculations for the Authorization Header:Transferring Payload in Multiple Chunks (Chunked Upload) (AWS Signature Version4).

When signing your requests, you can use either AWS Signature Version 4 or AWS Signature Version 4A. The key difference between the two is determined by how the signature is calculated. With AWS Signature Version 4A, the signature does not include Region-specific information and is calculated using theAWS4-ECDSA-P256-SHA256 algorithm.

In addition to these options, you have the option of including a trailer with your request. In order to include a trailer with your request, you need to specify that in the header by settingx-amz-content-sha256 to the appropriate value. If you are using a trailing header, you must includex-amz-trailer in the header and specify the trailing header names as a string in a comma-separated list. All trailing headers are written after the final chunk. If you're uploading the data in multiple chunks, you must send a final chunk with 0 bytes of data before sending the trailing header.

When you send a request, you must tell Amazon S3 which of the preceding options you havechosen in your signature calculation, by adding thex-amz-content-sha256 header with one of the followingvalues:

Header value	Description
Actual payload checksum value	This value is the actual checksum of your object and is only possible when you are uploading the data in a single chunk.
UNSIGNED-PAYLOAD	Use this when you are uploading the object as a single unsigned chunk.
STREAMING-UNSIGNED-PAYLOAD-TRAILER	Use this when sending an unsigned payload over multiple chunks. In this case you also have a trailing header after the chunk is uploaded.
STREAMING-AWS4-HMAC-SHA256-PAYLOAD	Use this when sending a payload over multiple chunks, and the chunks are signed using`AWS4-HMAC-SHA256`. This produces a SigV4 signature.
STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER	Use this when sending a payload over multiple chunks, and the chunks are signed using`AWS4-HMAC-SHA256`. This produces a SigV4 signature. In addition, the digest for the chunks is included as a trailing header.
STREAMING-AWS4-ECDSA-P256-SHA256-PAYLOAD	Use this when sending a payload over multiple chunks, and the chunks are signed using`AWS4-ECDSA-P256-SHA256`. This produces a SigV4A signature.
STREAMING-AWS4-ECDSA-P256-SHA256-PAYLOAD-TRAILER	Use this when sending a payload over multiple chunks, and the chunks are signed using`AWS4-ECDSA-P256-SHA256`. This produces a SigV4A signature. In addition, the digest for the chunks is included as a trailing header.

Upon receiving the request, Amazon S3 re-creates the string to sign using information in theAuthorization header and thedate header. It thenverifies with authentication service the signatures match. The request date can bespecified by using either the HTTPDate or thex-amz-dateheader. If both headers are present,x-amz-date takes precedence.