Authenticating Requests: Using Query Parameters (AWS Signature Version 4)

As described in the authentication overview (see ), you can provide authentication information using query string parameters. Using query parameters to authenticate requests is useful when you want to express a request entirely in a URL. This method is also referred as presigning a URL.

A use case scenario for presigned URLs is that you can grant temporary access to your Amazon S3 resources. For example, you can embed a presigned URL on your website or alternatively use it in command line client (such as Curl) to download objects.

Note

You can also use the AWS CLI to create presigned URLs. For more information, see presign in the AWS CLI Command Reference.

The following is an example presigned URL.

In the example URL, note the following:

The following table describes the query parameters in the URL that provide authentication information.

Query String Parameter Name Example Value
X-Amz-Algorithm  

Identifies the version of AWS Signature and the algorithm that you used to calculate the signature.

For AWS Signature Version 4, you set this parameter value to AWS4-HMAC-SHA256. This string identifies AWS Signature Version 4 (AWS4) and the HMAC-SHA256 algorithm (HMAC-SHA256).

The following diagram illustrates the signature calculation process.

The following table describes the functions that are shown in the diagram. You need to implement code for these functions.

Function Description
Lowercase()   Convert the string to lowercase.  
Hex()   Lowercase base 16 encoding.  
SHA256Hash()   Secure Hash Algorithm (SHA) cryptographic hash function.  
HMAC-SHA256()   Computes HMAC by using the SHA256 algorithm with the signing key provided. This is the final signature.  
Trim()   Remove any leading or trailing whitespace.  
UriEncode()  

URI encode every byte. UriEncode() must enforce the following rules:

URI encode every byte except the unreserved characters: 'A'-'Z', 'a'-'z', '0'-'9', '-', '.', '_', and '~'.

The space character is a reserved character and must be encoded as "%20" (and not as "+").

Each URI encoded byte is formed by a '%' and the two-digit hexadecimal value of the byte.

Letters in the hexadecimal value must be uppercase, for example "%1A".

Encode the forward slash character, '/', everywhere except in the object key name. For example, if the object key name is photos/Jan/sample.jpg, the forward slash in the key name is not encoded.

Important

The standard UriEncode functions provided by your development platform may not work because of differences in implementation and related ambiguity in the underlying RFCs. We recommend that you write your own custom UriEncode function to ensure that your encoding will work.

To see an example of a UriEncode function in Java, see on the GitHub website.

For more information about the signing process (details of creating a canonical request, string to sign, and signature calculations), see Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS Signature Version 4). The process is generally the same except that the creation of CanonicalRequest in a presigned URL differs as follows:

You don't include a payload hash in the Canonical Request, because when you create a presigned URL, you don't know the payload content because the URL is used to upload an arbitrary payload. Instead, you use a constant string UNSIGNED-PAYLOAD.

The Canonical Query String must include all the query parameters from the preceding table except for X-Amz-Signature.

For S3, you must include the X-Amz-Security-Token query parameter in the URL if using credentials sourced from the STS service.

Canonical Headers must include the HTTP host header. If you plan to include any of the x-amz-* headers, these headers must also be added for signature calculation. You can optionally add all other headers that you plan to include in your request. For added security, you should sign as many headers as possible. If you add a signed header that is also a signed query parameter, and they differ in value, you will receive an InvalidRequest error as the input is conflicting.

Suppose you have an object test.txt in your examplebucket bucket. You want to share this object with others for a period of 24 hours (86400 seconds) by creating a presigned URL.

The following steps illustrate first the signature calculations and then construction of the presigned URL. The example makes the following additional assumptions:

Request timestamp is Fri, 24 May 2013 00:00:00 GMT.

The bucket is in the US East (N. Virginia) region, and the credential Scope and the Signing Key calculations use us-east-1 as the region specifier. For more information, see in the AWS General Reference.

You can use this example as a test case to verify the signature that your code calculates; however, you must use the same bucket name, object key, time stamp, and the following example credentials:

Parameter Value
AWSAccessKeyId   AKIAIOSFODNN7EXAMPLE  
AWSSecretAccessKey   wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY  

StringToSign

CanonicalRequest

StringToSign

SigningKey

Signature

Now you have all information to construct a presigned URL. The resulting URL for this example is shown as follows (you can use this to compare your presigned URL):

The following is an example (unrelated to the previous example) showing a presigned URL with the X-Amz-Security-Token parameter.