How Amazon Simple Email Service (Amazon SES) uses Amazon KMS
You can use Amazon Simple Email Service (Amazon SES) to receive email, and (optionally) to encrypt the received
email messages before storing them in an Amazon Simple Storage Service (Amazon S3) bucket that you choose. When you
configure Amazon SES to encrypt email messages, you must choose the Amazon KMS Amazon KMS key under which Amazon SES encrypts the messages. You can choose the Amazon managed key for Amazon SES (its alias is
aws/ses
), or you can choose a symmetric customer managed key that you created in Amazon KMS.
Important
Amazon SES supports only symmetric KMS keys. You cannot use an asymmetric KMS key to encrypt your Amazon SES email messages. For help determining whether a KMS key is symmetric or asymmetric, see Identifying asymmetric KMS keys.
For more information about receiving email using Amazon SES, go to Receiving Email with Amazon SES in the Amazon Simple Email Service Developer Guide.
Topics
Overview of Amazon SES encryption using Amazon KMS
When you configure Amazon SES to receive email and encrypt the email messages before saving them to your S3 bucket, the process works like this:
-
You create a receipt rule for Amazon SES, specifying the S3 action, an S3 bucket for storage, and an Amazon KMS key for encryption.
-
Amazon SES receives an email message that matches your receipt rule.
-
Amazon SES requests a unique data key encrypted with the KMS key that you specified in the applicable receipt rule.
-
Amazon KMS creates a new data key, encrypts it with the specified KMS key, and then sends the encrypted and plaintext copies of the data key to Amazon SES.
-
Amazon SES uses the plaintext data key to encrypt the email message and then removes the plaintext data key from memory as soon as possible after use.
-
Amazon SES puts the encrypted email message and the encrypted data key in the specified S3 bucket. The encrypted data key is stored as metadata with the encrypted email message.
To accomplish Step 3 through Step 6, Amazon SES uses the Amazon–provided Amazon S3 encryption client. Use the same client to retrieve your encrypted email messages from Amazon S3 and decrypt them. For more information, see Getting and decrypting email messages.
Amazon SES encryption context
When Amazon SES requests a data key to encrypt your received email messages (Step 3 in the Overview of Amazon SES encryption using Amazon KMS), it includes an encryption context in the request. The encryption context provides additional authenticated data (AAD) that Amazon KMS uses to ensure data integrity. The encryption context is also written to your Amazon CloudTrail log files, which can help you understand why a given Amazon KMS key (KMS key) was used. Amazon SES uses the following encryption context:
-
The ID of the Amazon Web Services account in which you've configured Amazon SES to receive email messages
-
The rule name of the Amazon SES receipt rule that invoked the S3 action on the email message
-
The Amazon SES message ID for the email message
The following example shows a JSON representation of the encryption context that Amazon SES uses:
{
"aws:ses:source-account": "111122223333
",
"aws:ses:rule-name": "example-receipt-rule-name
",
"aws:ses:message-id": "d6iitobk75ur44p8kdnnp7g2n800
"
}
Giving Amazon SES permission to use your Amazon KMS key
To encrypt your email messages, you can use the Amazon managed key in your account for Amazon SES (aws/ses
), or you can use a customer managed key that you create. Amazon SES already has permission to use the Amazon managed key on
your behalf. However, if you specify a customer managed key when you add the S3 action to your Amazon SES
receipt rule, you must give Amazon SES permission to use the KMS key to encrypt your email messages.
To give Amazon SES permission to use your customer managed key, add the following statement to that KMS key's key policy:
{ "Sid": "Allow SES to encrypt messages using this KMS key", "Effect": "Allow", "Principal": {"Service": "ses.amazonaws.com"}, "Action": [ "kms:Encrypt", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "Null": { "kms:EncryptionContext:aws:ses:rule-name": false, "kms:EncryptionContext:aws:ses:message-id": false }, "StringEquals": {"kms:EncryptionContext:aws:ses:source-account": "
ACCOUNT-ID-WITHOUT-HYPHENS
"} } }
Replace
with the
12-digit ID of the Amazon Web Services account where you've configured Amazon SES to receive email messages.
This policy statement allows Amazon SES to encrypt data with this KMS key only under these
conditions:ACCOUNT-ID-WITHOUT-HYPHENS
-
Amazon SES must specify
aws:ses:rule-name
andaws:ses:message-id
in theEncryptionContext
of their Amazon KMS API requests. -
Amazon SES must specify
aws:ses:source-account
in theEncryptionContext
of their Amazon KMS API requests, and the value foraws:ses:source-account
must match the Amazon Web Services account ID specified in the key policy.
For more information about the encryption context that Amazon SES uses when encrypting your email messages, see Amazon SES encryption context. For general information about how Amazon KMS uses the encryption context, see encryption context.
Getting and decrypting email messages
Amazon SES does not have permission to decrypt your encrypted email messages and cannot decrypt them for you. You must write code to get your email messages from Amazon S3 and decrypt them. To make this easier, use the Amazon S3 encryption client. The following Amazon SDKs include the Amazon S3 encryption client:
-
Amazon SDK for Java
– See AmazonS3EncryptionClient and AmazonS3EncryptionClientV2 in the Amazon SDK for Java API Reference. -
Amazon SDK for Ruby
– See Aws::S3::Encryption::Client in the Amazon SDK for Ruby API Reference. -
Amazon SDK for .NET
– See AmazonS3EncryptionClient in the Amazon SDK for .NET API Reference. -
Amazon SDK for Go
– See s3crypto in the Amazon SDK for Go API Reference.
The Amazon S3 encryption client simplifies the work of constructing the necessary requests to Amazon S3 to retrieve the encrypted email message and to Amazon KMS to decrypt the message's encrypted data key, and of decrypting the email message. For example, to successfully decrypt the encrypted data key you must pass the same encryption context that Amazon SES passed when requesting the data key from Amazon KMS (Step 3 in the Overview of Amazon SES encryption using Amazon KMS). The Amazon S3 encryption client handles this, and much of the other work, for you.
For sample code that uses the Amazon S3 encryption client in the Amazon SDK for Java to do client-side decryption, see the following:
-
Using a KMS key stored in Amazon KMS in the Amazon Simple Storage Service User Guide.
-
Amazon S3 Encryption with Amazon Key Management Service
on the Amazon Developer Blog.