Client-Side Encryption
Protecting data using client-side encryption
Client-side encryption is the act of encrypting data before sending it to Amazon S3.
To enable client-side encryption, you have the following options:
Use a customer master key (CMK) stored in AWS Key Management Service (AWS KMS).
Use a master key that you store within your application.
AWS Encryption SDK
The AWS Encryption SDK is a client-side encryption library that is separate from the language–specific SDKs. You can use this encryption library to more easily implement encryption best practices in Amazon S3. Unlike the Amazon S3 encryption clients in the language–specific AWS SDKs, the AWS Encryption SDK is not tied to Amazon S3 and can be used to encrypt or decrypt data to be stored anywhere.
The AWS Encryption SDK and the Amazon S3 encryption clients are not compatible because they produce ciphertexts with different data formats. For more information about the AWS Encryption SDK, see the AWS Encryption SDK Developer Guide.
AWS SDK support for Amazon S3 client-side encryption
The following AWS SDKs support client-side encryption:
Option 1: Using a CMK stored in AWS KMS
With this option, you use an AWS KMS CMK for client-side encryption when uploading or downloading data in Amazon S3.
When uploading an object — Using the CMK ID, the client first sends a request to AWS KMS for a new symmetric key that it can use to encrypt your object data. AWS KMS returns two versions of a randomly generated data key:
A plaintext version of the data key that the client uses to encrypt the object data.
A cipher blob of the same data key that the client uploads to Amazon S3 as object metadata.
The client obtains a unique data key for each object that it uploads.
When downloading an object — The client downloads the encrypted object from Amazon S3 along with the cipher blob version of the data key stored as object metadata. The client then sends the cipher blob to AWS KMS to get the plaintext version of the data key so that it can decrypt the object data.
Option 2: Using a master key stored within your application
With this option, you use a master key that is stored and management with your application for client-side data encryption.
Important: Your client-side master keys and your unencrypted data are never sent to AWS. It's important that you safely manage your encryption keys. If you lose them, you can't decrypt your data.
This is how it works:
When uploading an object — You provide a client-side master key to the Amazon S3 encryption client. The client uses the master key only to encrypt the data encryption key that it generates randomly.
The following steps describe the process:
The Amazon S3 encryption client generates a one-time-use symmetric key (also known as a data encryption key or data key) locally. It uses the data key to encrypt the data of a single Amazon S3 object. The client generates a separate data key for each object.
The client encrypts the data encryption key using the master key that you provide. The client uploads the encrypted data key and its material description as part of the object metadata. The client uses the material description to determine which client-side master key to use for decryption.
The client uploads the encrypted data to Amazon S3 and saves the encrypted data key as object metadata (
x-amz-meta-x-amz-key) in Amazon S3.
When downloading an object — The client downloads the encrypted object from Amazon S3. Using the material description from the object's metadata, the client determines which master key to use to decrypt the data key. The client uses that master key to decrypt the data key and then uses the data key to decrypt the object.
The client-side master key that you provide can be either a symmetric key or a public/private key pair. The following code examples show how to use each type of key.
For more information, see Client-Side Data Encryption with the AWS SDK for Java and Amazon S3.
Last updated
