Topics

• Query Parameters

• Query API Authentication

• Example Request

Each Query request must include some common parameters to handle authentication and selection of an action. For more information, see Common Query Parameters.

Some operations take lists of parameters. These lists are specified using the param.n notation. Values of n are integers starting from 1.

Every request to Amazon EC2 must contain a request signature. A request signature is calculated by constructing a string and then calculating an RFC 2104-compliant HMAC-SHA1 hash, using the Secret AWS Access Key as the key. For more information, see http://www.faqs.org/rfcs/rfc2104.html.

The following are the basic steps used to authenticate requests to AWS. This assumes the developer is registered with AWS and has an Access Key ID and Secret Access Key.

	Note
	If a request contains a Timestamp parameter, the signature calculated for the request expires 15 minutes its value. If a request contains an Expires parameter, the signature expires at the time specified by the Expires parameter.

For example, below is a Query string (linebreaks added for clarity):

?Action=DescribeImages
&AWSAccessKeyId=10QMXFEV71ZS32XQFTR2
&SignatureVersion=1
&Timestamp=2006-12-08T07%3A48%3A03Z
&Version=2007-01-03

For the above Query string, you would calculate the HMAC signature over the following string:

ActionDescribeImagesAWSAccessKeyId10QMXFEV71ZS32XQFTR2SignatureVersion1Timestamp2006-12-08T07:48:03ZVersion2007-01-03

Using the string above and the secret key DMADSSfPfdaDjbK+RRUhS/aDrjsiZadgAUm8gRU2 the base64 encoded signature is as follows:

GjH3941IBe6qsgQu+k7FpCJjpnc=

The following is a Java code sample to compute the signature from the string and the private key.

import java.security.SignatureException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class HmacExample
{

    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
     *     java.security.SignatureException when signature generation fails
     */
    public static String calculateRFC2104HMAC(String data, String key)
        throws java.security.SignatureException
    {
        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);
            mac.init(signingKey);
            
            // compute the hmac on input data bytes
            byte[] rawHmac = mac.doFinal(data.getBytes());
            
            // base64-encode the hmac
            result = Base64.encodeBytes(rawHmac);
        } 
        catch (Exception e) {
            throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
        }
        return result;
    }
}

	Note
	You must import a base 64 encoder to perform the last step above.

Here is a complete example request, including all required parameters:

?AWSAccessKeyId=10QMXFEV71ZS32XQFTR2&Action=DescribeImages&SignatureVersion=1&Timestamp=2006-12-08T07%3A48%3A03Z&Version=2007-01-03&Signature=69DSJs1z%2B0wWJmdB77%2BLm0N0Trs%3D