Amazon DevPay
Developer Guide (API Version 2007-12-01)

Authentication of REST-Query Requests

Which Requests Need to Be Authenticated?

Authentication requirements for the License Service requests vary for desktop products and web products:

  • Desktop Products—HTTPS always required; HMAC-SHA1 signature required depending on the License Service action you're calling
  • Web Products—HMAC-SHA1 signature and HTTPS required

Required Information for Authentication

REST-Query requests for the License Service that require authentication must include the following items:

  • AWS Access Key ID—Your Access Key ID, which AWS uses to look up your Secret Access Key. For more information, see Your AWS Access Credentials.
  • Date—A request time stamp or a request expiration time. For more information, see About the Time Stamp.
  • Signature—A valid request signature. You calculate a request signature using your Secret Access Key, which is a shared secret known only to you and AWS.
  • Signature Version—Which signature version is being used. This is AWS-specific information that tells AWS the algorithm you used to form the string that is the basis of the signature. AWS calls the algorithm we're using signature version 1 (for more information about the algorithm, see Calculating an HMAC-SHA1 Request Signature).

General Authentication Process

Following is the series of tasks required to authenticate requests to AWS. It is assumed you have already created an AWS account and received an Access Key ID and Secret Access Key. For more information about these items, see Your AWS Account and Your AWS Access Credentials.

You perform the first three tasks.

HMAC-SHA1 Authentication Process

Process for Authentication: Tasks You Perform

You construct a request to AWS.

You calculate a keyed-hash message authentication code (HMAC-SHA1) signature using your Secret Access Key (for information about HMAC, go to

You include the signature and your Access Key ID in the request, and then send the request to AWS.

AWS performs the next three tasks.

HMAC-SHA1 Authentication Process

Process for Authentication: Tasks AWS Performs

AWS uses the Access Key ID to look up your Secret Access Key.

AWS generates a signature from the request data and the Secret Access Key using the same algorithm you used to calculate the signature you sent in the request.

If the signature generated by AWS matches the one you sent in the request, the request is considered authentic. If the comparison fails, the request is discarded, and AWS returns an error response.

Calculating an HMAC-SHA1 Request Signature

The request must include an HMAC-SHA1 signature. The signature is used as the value for the Signature parameter in the request URL being constructed. The string you use to compute the HMAC signature is constructed using the method described in the following procedure.


Do not URL encode the concatenated string before computing the signature. URL encode the computed signature and other query parameters as specified in RFC1738, section 2.2. In addition, make sure to encode the + character although it is not required by RFC1738. This is required because the + character is interpreted as a blank space by Sun Java classes that perform URL decoding.

To calculate an HMAC-SHA1 signature

  1. Create the string you'll use to generate the signature:

    1. Sort all request parameters alphabetically, ignoring case.

      Include SignatureVersion in the list but not Signature. Do not list as "empty" any optional parameters that are not included in the request. In other words, if no value for ParameterA is specified in the request, do not include a ParameterA entry in this sorted list.

    2. Form a string by concatenating each request parameter's name with its value.

      The format of the string is:


      The parameter names are case sensitive. Do not include any separators in this string, such as question marks (?), ampersands (&), or equals signs (=). Do not URL encode the parameter values.

      This is illustrated with the following request and the corresponding string to be signed (the request is borrowed from the Amazon Simple Queue Service documentation).


      Following is the string to be signed for the preceding request.

  2. Calculate an RFC 2104-compliant HMAC-SHA1 signature, using your Secret Access Key as the key and the string you just created.

    For more information, go to

  3. Convert the resulting value to base64.

    For the preceding string, assuming the Secret Access Key is fake-secret-key, this is the base64 encoded value:


  4. URL encode the resulting value as specified in RFC 1738, section 2.2.

    This is required because base64 encoding can result in characters that are not legal in a URL, such as plus signs (+), slashes (/), and equals signs (=).

    For the preceding signature, this is the URL encoded value:

  5. Pass this final value in the Signature request parameter.

The following Java code snippet constructs the string.

* Assumes parameters are in a java.util.Map named paramMap
* where the key is the parameter name.
Set<String> sortedKeys = new TreeSet<String>(String.CASE_INSENSITIVE_ORDER);

// Don't include Signature in the string to sign.

StringBuilder stringBuilder = new StringBuilder();
for(String key : sortedKeys) {

System.out.println("String to sign : " + stringBuilder.toString());

About the Time Stamp

The time stamp (or expiration time) you use in the request must be a dateTime object (for more information, go to Although it is not required, we recommend you provide the time stamp in the Coordinated Universal Time (Greenwich Mean Time) time zone. For example: 2007-01-31T23:59:59Z.

If you specify a time stamp (instead of an expiration time), the request automatically expires 15 minutes after the time stamp (in other words, AWS does not process a request if the request time stamp is more than 15 minutes earlier than the current time on AWS servers). Make sure your server's time is set correctly.


If you are using .NET you must not send overly specific time stamps, due to different interpretations of how extra time precision should be dropped. To avoid overly specific time stamps, manually construct dateTime objects with no more than millisecond precision.

Java Sample Code for Base64 Encoding

HMAC-SHA1 request signatures must be base64 encoded. The following sample code shows how to perform base64 encoding.

package amazon.webservices.common;
* This class defines common routines for encoding * data in AWS requests.
public class Encoding {
* Performs base64-encoding of input bytes.
* @param rawData * Array of bytes to be encoded.
* @return * The base64 encoded string representation of rawData.
public static String EncodeBase64(byte[] rawData) {
return Base64.encodeBytes(rawData);

Java Sample Code for Calculating HMAC-SHA1 Signatures

The following Java code sample shows how to calculate an HMAC request signature.

package amazon.webservices.common;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

* This class defines common routines for generating
* authentication signatures for AWS requests.
public class Signature {
private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";

* Computes RFC 2104-compliant HMAC signature.
* * @param data
* The data to be signed.
* @param key
* The signing key.
* @return
* The Base64-encoded RFC 2104-compliant HMAC signature.
* @throws
* when signature generation fails
public static String calculateRFC2104HMAC(String data, String key)
String result;
try {

// get an hmac_sha1 key from the raw key bytes
SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM);

// get an hmac_sha1 Mac instance and initialize with the signing key
Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);

// compute the hmac on input data bytes
byte[] rawHmac = mac.doFinal(data.getBytes());

// base64-encode the hmac
result = Encoding.EncodeBase64(rawHmac);

} catch (Exception e) {
throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
return result;