Signing AWS API Requests

There are two ways you can programmatically call the functionality exposed by an Amazon Web Services (AWS) API: submit a REST/Query request over HTTP/HTTPS, or call wrapper functions in one of the AWS SDKs. This guide describes how to sign your REST/Query requests. If you use an AWS SDK, the SDK handles the signing process for you.

REST/Query Requests

REST or Query requests are HTTP or HTTPS requests that use an HTTP verb (such as GET or POST) and a parameter named Action or Operation that specifies the API you are calling. Calling an API using a REST or Query request is the most direct way to access a web service, but requires that your application handle low-level details such as generating the hash to sign the request, and error handling. The benefit of using a REST or Query request is that you have access to the complete functionality of an API.

AWS SDKs

The AWS SDKs provide functions that wrap an API and take care of many of the connection details, such as calculating signatures, handling request retries, and error handling. The SDKs also contain sample code, tutorials, and other resources to help you get started writing applications that call AWS. Calling the wrapper functions in an SDK can greatly simplify the process of writing an AWS application.

A disadvantage of using the SDKs is that the implementation of the wrapper functions sometimes lags behind changes to the web service's API, meaning that there may be a period between the time that a new web service API is released and when a wrapper function for it becomes available in the SDKs. You can overcome this disadvantage by using the SDKs to generate a raw REST or Query request. For more information about how to download and use the AWS SDKs, go to Sample Code & Libraries.

Signing REST/Query Requests

AWS requires that you authenticate every request by signing it. To sign a request, you calculate a digital signature using a cryptographic hash function. A cryptographic hash is a one-way function that returns a unique hash value based on the input. The input to the hash function includes the text of your request and your secret access key. The hash function returns a hash value that you include in the request as your signature.

After receiving your request, AWS recalculates the signature using the same hash function and input that you used to sign the request. If the resulting signature matches the signature in the request, AWS processes the request. Otherwise, the request is rejected.

For additional security, you should transmit your requests using Secure Sockets Layer (SSL) by using HTTPS. SSL encrypts the transmission, protecting your request or the response from being viewed in transit.

AWS currently supports three signature versions: Signature Version 2, Signature Version 3, and Signature Version 4. This section covers Signature Version 2 and Signature Version 4. For information about Signature Version 3, go to the documentation for the following services: