Amazon Simple Email Service
Developer Guide (API Version 2010-12-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Request Authentication and Amazon SES

The topics in this section describe how Amazon Simple Email Service authenticates your requests. In this section you can learn about the basics of authentication, how your AWS account and identifiers are used to support authentication, and how to create an HMAC-SHA signature. This section also covers the request authentication requirements for Query requests.

What Is Authentication?

Authentication is a process for identifying and verifying who is sending a request.

General Process of Authentication

1

The sender obtains the necessary credential.

2

The sender sends a request with the credential to the recipient.

3

The recipient uses the credential to verify that the sender truly sent the request.

4

If so, the recipient processes the request. If no, the recipient rejects the request and responds accordingly.

During authentication, AWS verifies both the identity of the sender and whether the sender is registered to use services offered by AWS. If either test fails, the request is not processed.

The subsequent sections describe how Amazon SES implements authentication to protect your data.

Your AWS Account

To access any services offered by AWS, you must first create an AWS account at http://aws.amazon.com. An AWS account is simply an Amazon.com account that is enabled to use AWS products. You can use an existing Amazon.com account email address and password to create the AWS account.

Alternately, you could create a new AWS-enabled Amazon.com account by using a new email address and password. The address you provide must be valid. You'll be asked to provide a credit card or other payment method to cover the charges for any AWS products you use.

From your AWS account you can view your account activity, view usage reports, and manage your AWS account access identifiers.

To create an AWS account

  1. Go to http://aws.amazon.com, and then click Sign Up.

  2. Follow the on-screen instructions.

Your AWS Access Keys

After you've signed up, you'll need to obtain your AWS access keys if you want to access Amazon SES through the Amazon SES API, whether by the Query (HTTPS) interface directly or indirectly through an AWS SDK, the AWS Command Line Interface, or the AWS Tools for Windows PowerShell. AWS access keys consist of an access key ID and a secret access key.

For information about getting your AWS access keys, see How Do I Get Security Credentials? in the AWS General Reference.

HMAC-SHA Signatures

The Access Key ID is associated with your AWS account. You include it in AWS service requests to identify yourself as the sender of the request.

The Access Key ID is not a secret, and anyone could use your Access Key ID in requests to AWS. To provide proof that you truly are the sender of the request, you must also include a digital signature. For all requests, you calculate the signature using your Secret Access Key. AWS uses the Access Key ID in the request to look up your Secret Access Key and then calculates a digital signature with the key. If the signature AWS calculates matches the signature you sent, the request is considered authentic. Otherwise, the request fails authentication and is not processed.

The topics in this section describe how Amazon Simple Email Service uses HMAC-SHA signatures to authenticate query requests.

In order to access Amazon SES, you must provide the following items so the request can be authenticated:

  • AWSAccessKeyId—Your AWS account is identified by your Access Key ID, which AWS uses to look up your Secret Access Key.

  • Signature—Each request must contain a valid request signature, or the request will be rejected. A request signature is calculated using your Secret Access Key, which is a shared secret known only to you and AWS.

  • Algorithm—Identify which HMAC hash algorithm is being used to calculate your signature, either SHA256 or SHA1.

These items are used to construct an X-Amzn-Authorization HTTP header, which must be sent with every request. For information about HMAC, go to http://www.faqs.org/rfcs/rfc2104.html.

To authenticate a request to AWS, you create a request signature, which you place in an X-Amzn-Authorization HTTP header. This header must be included in the request that you send to AWS.

When AWS receives your request, it does the following:

  1. Uses the access key ID to look up your secret access key.

  2. 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.

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

You can send Query API requests to Amazon SES over HTTPS (Hypertext Transfer Protocol Secure). You must calculate an HMAC-SHA signature to be sent with every request.

The signature forms part of the X-Amzn-Authorization HTTP header, which must be sent with each request. The method used to construct the signature is known as signature version 3.

To create the X-Amzn-Authorization header

  1. Create a Date header to be used in the request. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18.

    Here is an example of what a Date header might look like:

    Date: Tue, 25 May 2010 21:20:27 +0000
  2. To create the string to sign, calculate an RFC 2104-compliant HMAC hash with the Date header value, your secret access key as the key, and SHA256 or SHA1 as the hash algorithm. For more information, go to http://www.ietf.org/rfc/rfc2104.txt.

    Note

    Use only the value of the header when calculating the hash; do not include the word "Date", nor the trailing colon and space.

  3. To create the request signature, convert the HMAC hash to base64. The resulting value is the signature for this request.

  4. Create an X-Amzn-Authorization header, consisting of the following elements:

    1. AWS3-HTTPS.

    2. AWSAccessKeyId=your AWS Access Key ID.

    3. Algorithm=the algorithm you used when creating the string to sign—either HmacSHA1 or HmacSHA256.

    4. Signature=the signature for this request.

    All of the elements, except for AWS3-HTTPS, must be separated by commas.

    Here is an example of what an X-Amzn-Authorization header might look like, using placeholders for the AWS Access Key ID and the signature:

    X-Amzn-Authorization: AWS3-HTTPS AWSAccessKeyId=<Your AWS Access Key ID>, Algorithm=HmacSHA256, Signature=<Signature>