Amazon ECS Webservice Sign

I spent a good part of today trying to learn how to do a simple Java-based query using Amazon’s Product Advertising API.  This entire exercise could have been finished within an hour had there been clear, concise documentation.

Note: My code was working 6 months back and now when i try to work with it it dosen’t work. Below are the reason

In hopes of saving others from encountering these difficulties, I present you with my findings.

Lesson 1 – Don’t Trust the Getting Started Guide

Admittedly the getting started guide gives a useful overview of the functionality and the approach to using the API. However, following the instructions step by step will only lead to frustration. The Java example for
Implementing a Product Advertising API Request DOES NOT WORK!. One would think that simply swapping in the proper access key where it says “YOUR ID” would be all that is needed, but upon execution I found it yields the following:

Exception in thread "main"
The server sent HTTP status code 400: Bad Request

Thinking I had omitted something small, I looked into resolving this error only to discover:

Lesson 2 – APA API’s Authentication has changed

As of August 15, 2009, the API requires a signature mechanism for authentication. In addition to invalidating all the code from the getting started guide, it also adds additional poorly documented steps to the process. Amazon does provide some detail, but it’s probably not the quickest path to get up and running.

Lesson 3 – There are some semi-functional examples

After digging around in the documentation, I found these two examples: Product Advertising API Signed Requests Sample Code – Java REST/QUERY and Product Advertising API Signed Requests Sample Code – Java SOAP. Since everything I had tried up until this point had been SOAP-centric, I decided to try the SOAP example first. Upon the code into Eclipse, I found that this example was fraught with too many errors and dependencies, so I turned to the REST example.

The REST code was clear and mostly error free. The few errors I saw were caused by the absence of the Apache Commons Codec library. After downloading this jar and adding it to my classpath, the example code finally compiled. Unfortunately, when I went to run it, I was greeted with this exception:

Server returned HTTP response code: 403 for URL:

Lesson 4 – Apache Commons Codec 1.3 and 1.4 are different

After crawling through the forums looking for answers, I found out that the REST example above depended on Apache Commons Codec version 1.3, whereas the version I downloaded was 1.4. It turns out the old version appended extra CRLF (\r\n) characters onto the authentication signature, and the workaround is to force the new codec to exhibit the same behavior. If you read the codec’s documentation, you’ll see that the default behavior comes when you set the line length to 76 characters. To fix the REST example change method hmac of SignatureRequestHelper to:

Base64 encoder = new Base64(76, new byte[0]);

After doing all this, I finally got a small victory in the form of real output:

Map form example:
Signed Request is ""
Signed Title is "Harry Potter and the Deathly Hallows (Book 7)"

String form example:
Request is ""
Title is "Harry Potter and the Deathly Hallows (Book 7)"

Below is SignedRequestHelper that works


import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.SortedMap;
import java.util.TimeZone;
import java.util.TreeMap;

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

import org.apache.commons.codec.binary.Base64;

 * This class contains all the logic for signing requests
 * to the Amazon Product Advertising API.
public class SignedRequestsHelper {
     * All strings are handled as UTF-8
    private static final String UTF8_CHARSET = "UTF-8";

     * The HMAC algorithm required by Amazon
    private static final String HMAC_SHA256_ALGORITHM = "HmacSHA256";

     * This is the URI for the service, don't change unless you really know
     * what you're doing.
    private static final String REQUEST_URI = "/onca/xml";

     * The sample uses HTTP GET to fetch the response. If you changed the sample
     * to use HTTP POST instead, change the value below to POST.
    private static final String REQUEST_METHOD = "GET";

    private String endpoint = null;
    private String awsAccessKeyId = null;
    private String awsSecretKey = null;

    private SecretKeySpec secretKeySpec = null;
    private Mac mac = null;

    static { com.sun.crypto.provider.SunJCE());

     * You must provide the three values below to initialize the helper.
     * @param endpoint          Destination for the requests.
     * @param awsAccessKeyId    Your AWS Access Key ID
     * @param awsSecretKey      Your AWS Secret Key
    public static SignedRequestsHelper getInstance(
            String endpoint,
            String awsAccessKeyId,
            String awsSecretKey
    ) throws IllegalArgumentException, UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException
        if (null == endpoint || endpoint.length() == 0)
            { throw new IllegalArgumentException("endpoint is null or empty"); }
        if (null == awsAccessKeyId || awsAccessKeyId.length() == 0)
            { throw new IllegalArgumentException("awsAccessKeyId is null or empty"); }
        if (null == awsSecretKey || awsSecretKey.length() == 0)
            { throw new IllegalArgumentException("awsSecretKey is null or empty"); }
        SignedRequestsHelper instance = new SignedRequestsHelper();
        instance.endpoint = endpoint.toLowerCase();
        instance.awsAccessKeyId = awsAccessKeyId;
        instance.awsSecretKey = awsSecretKey;

        byte[] secretyKeyBytes = instance.awsSecretKey.getBytes(UTF8_CHARSET);
        instance.secretKeySpec = new SecretKeySpec(secretyKeyBytes, HMAC_SHA256_ALGORITHM);
        instance.mac = Mac.getInstance(HMAC_SHA256_ALGORITHM);

        return instance;

     * The construct is private since we'd rather use getInstance()
    private SignedRequestsHelper() {}

     * This method signs requests in hashmap form. It returns a URL that should
     * be used to fetch the response. The URL returned should not be modified in
     * any way, doing so will invalidate the signature and Amazon will reject
     * the request.
    public String sign(Map params) {
        // Let's add the AWSAccessKeyId and Timestamp parameters to the request.
        params.put("AWSAccessKeyId", this.awsAccessKeyId);
        params.put("Timestamp", this.timestamp());

        // The parameters need to be processed in lexicographical order, so we'll
        // use a TreeMap implementation for that.
        SortedMap sortedParamMap = new TreeMap(params);

        // get the canonical form the query string
        String canonicalQS = this.canonicalize(sortedParamMap);

        // create the string upon which the signature is calculated
        String toSign =
            REQUEST_METHOD + "\n"
            + this.endpoint + "\n"
            + REQUEST_URI + "\n"
            + canonicalQS;

        // get the signature
        String hmac = this.hmac(toSign);
        String sig = this.percentEncodeRfc3986(hmac);

        // construct the URL
        String url =
            "http://" + this.endpoint + REQUEST_URI + "?" + canonicalQS + "&Signature=" + sig;

        return url;

     * This method signs requests in query-string form. It returns a URL that
     * should be used to fetch the response. The URL returned should not be
     * modified in any way, doing so will invalidate the signature and Amazon
     * will reject the request.
    public String sign(String queryString) {
        // let's break the query string into it's constituent name-value pairs
        Map params = this.createParameterMap(queryString);

        // then we can sign the request as before
        return this.sign(params);

     * Compute the HMAC.
     * @param stringToSign  String to compute the HMAC over.
     * @return              base64-encoded hmac value.
    private String hmac(String stringToSign) {
        String signature = null;
        byte[] data;
        byte[] rawHmac;
        try {
            data = stringToSign.getBytes(UTF8_CHARSET);
            rawHmac = mac.doFinal(data);
            Base64 encoder = new Base64(76, new byte[0]);
            signature = new String(encoder.encode(rawHmac));
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException(UTF8_CHARSET + " is unsupported!", e);
        return signature;

     * Generate a ISO-8601 format timestamp as required by Amazon.
     * @return  ISO-8601 format timestamp.
    private String timestamp() {
        String timestamp = null;
        Calendar cal = Calendar.getInstance();
        DateFormat dfm = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
        timestamp = dfm.format(cal.getTime());
        return timestamp;

     * Canonicalize the query string as required by Amazon.
     * @param sortedParamMap    Parameter name-value pairs in lexicographical order.
     * @return                  Canonical form of query string.
    private String canonicalize(SortedMap sortedParamMap) {
        if (sortedParamMap.isEmpty()) {
            return "";

        StringBuffer buffer = new StringBuffer();
        Iterator<Map.Entry> iter = sortedParamMap.entrySet().iterator();

        while (iter.hasNext()) {
            Map.Entry kvpair =;
            if (iter.hasNext()) {
        String cannoical = buffer.toString();
        return cannoical;

     * Percent-encode values according the RFC 3986. The built-in Java
     * URLEncoder does not encode according to the RFC, so we make the
     * extra replacements.
     * @param s decoded string
     * @return  encoded string per RFC 3986
    private String percentEncodeRfc3986(String s) {
        String out;
        try {
            out = URLEncoder.encode(s, UTF8_CHARSET)
                .replace("+", "%20")
                .replace("*", "%2A")
                .replace("%7E", "~");
        } catch (UnsupportedEncodingException e) {
            out = s;
        return out;

     * Takes a query string, separates the constituent name-value pairs
     * and stores them in a hashmap.
     * @param queryString
     * @return
    private Map createParameterMap(String queryString) {
        Map map = new HashMap();
        String[] pairs = queryString.split("&");

        for (String pair: pairs) {
            if (pair.length() < 1) {

            String[] tokens = pair.split("=",2);
            for(int j=0; j<tokens.length; j++)
                try {
                    tokens[j] = URLDecoder.decode(tokens[j], UTF8_CHARSET);
                } catch (UnsupportedEncodingException e) {
            switch (tokens.length) {
                case 1: {
                    if (pair.charAt(0) == =) {
                        map.put("", tokens[0]);
                    } else {
                        map.put(tokens[0], "");
                case 2: {
                    map.put(tokens[0], tokens[1]);
        return map;

8 thoughts on “Amazon ECS Webservice Sign

  1. Thanks a lot, it helped! Btw. the “if (pair.charAt(0) == =) {” should be “if (pair.charAt(0) == ‘=’) {“.


    P.S.: beware of the new required AssociationTag attribute in a request

  2. It says in my IDE that “Base64 encoder = new Base64(76, new byte[0]);” in the hmac method that the constructor is undefined for the arguments “int, byte[]”, and wants me to have no arguments. What’s going on?

  3. Hi, can anyone provide a main class that call this helper and print out the result of searching some item. I’m having trouble reading the APIs.

  4. while (iter.hasNext()) {
    Map.Entry kvpair =;
    if (iter.hasNext()) {
    I am getting error in buffer append

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s