Menu
AWS SDK for Java
Developer Guide

Amazon S3 Client-Side Encryption with AWS KMS Managed Keys

The following examples use the AmazonS3EncryptionClientBuilder class to create an Amazon S3 client with client-side encryption enabled. Once configured, any objects you upload to Amazon S3 using this client will be encrypted. Any objects you get from Amazon S3 using this client are automatically decrypted.

Note

The following examples demonstrate how to use the Amazon S3 client-side encryption with AWS KMS managed keys. To learn how to use encryption with your own keys, see Amazon S3 Client-Side Encryption with Client Master Keys.

You can choose from three encryption modes when enabling client-side Amazon S3 encryption: encryption-only, authenticated, and strict authenticated. The following sections show how to enable each type. To learn which algorithms each mode uses, see the CryptoMode definition.

Required Imports

Import the following classes for these examples.

Imports

Copy
import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.AmazonS3Encryption; import com.amazonaws.services.s3.AmazonS3EncryptionClientBuilder; import com.amazonaws.services.s3.model.CryptoConfiguration; import com.amazonaws.services.s3.model.CryptoMode; import com.amazonaws.services.s3.model.EncryptionMaterials; import com.amazonaws.services.s3.model.GetObjectRequest; import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider; import com.amazonaws.services.s3.model.StaticEncryptionMaterialsProvider; import java.security.KeyPair; import java.security.KeyPairGenerator; import java.security.NoSuchAlgorithmException; import javax.crypto.KeyGenerator; import javax.crypto.SecretKey;

Encryption-Only Mode

Encryption-only is the default mode, if no CryptoMode is specified. To use an AWS KMS managed key for encryption, pass the AWS KMS key ID or alias to the KMSEncryptionMaterialsProvider constructor.

Code

Copy
AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.EncryptionOnly)) // Can either be Key ID or alias (prefixed with 'alias/') .withEncryptionMaterials(new KMSEncryptionMaterialsProvider("alias/s3-kms-key")) .build();

Call the putObject method on the Amazon S3 encryption client to upload objects.

Code

Copy
s3Encryption.putObject(BUCKET_NAME, ENCRYPTED_KEY, "some contents");

You can retrieve the object using the same client. This example calls the getObjectAsString method to retrieve the string that was stored.

Code

Copy
System.out.println(s3Encryption.getObjectAsString(BUCKET_NAME, ENCRYPTED_KEY));

See the complete example on GitHub.

Authenticated Encryption Mode

When you use AuthenticatedEncryption mode, an improved key wrapping algorithm is applied during encryption. When decrypting in this mode, the algorithm can verify the integrity of the decrypted object and throw an exception if the check fails. For more details about how authenticated encryption works, see the Amazon S3 Client-Side Authenticated Encryption blog post.

Note

To use client-side authenticated encryption, you must include the latest Bouncy Castle jar file in the classpath of your application.

To enable this mode, specify the AuthenticatedEncryption value in the method.

Code

Copy
AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)) // Can either be Key ID or alias (prefixed with 'alias/') .withEncryptionMaterials(new KMSEncryptionMaterialsProvider("alias/s3-kms-key")) .build();

The AuthenticatedEncryption mode can retrieve unencrypted objects and objects encrypted with EncryptionOnly mode. The following example shows the Amazon S3 encryption client retrieving an unencrypted object.

Code

Copy
AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)) // Can either be Key ID or alias (prefixed with 'alias/') .withEncryptionMaterials(new KMSEncryptionMaterialsProvider("alias/s3-kms-key")) .build(); AmazonS3 s3NonEncrypt = AmazonS3ClientBuilder.defaultClient(); s3Encryption.putObject(BUCKET_NAME, ENCRYPTED_KEY, "some contents"); s3NonEncrypt.putObject(BUCKET_NAME, NON_ENCRYPTED_KEY, "some other contents"); System.out.println(s3Encryption.getObjectAsString(BUCKET_NAME, ENCRYPTED_KEY)); System.out.println(s3Encryption.getObjectAsString(BUCKET_NAME, NON_ENCRYPTED_KEY));

See the complete example on GitHub.

Strict Authenticated Encryption

To enable this mode, specify the StrictAuthenticatedEncryption value in the method.

Note

To use client-side authenticated encryption, you must include the latest Bouncy Castle jar file in the classpath of your application.

Code

Copy
AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)) // Can either be Key ID or alias (prefixed with 'alias/') .withEncryptionMaterials(new KMSEncryptionMaterialsProvider("alias/s3-kms-key")) .build();

In StrictAuthenticatedEncryption mode, the Amazon S3 client throws an exception when retrieving an object that was not encrypted using an authenticated mode.

Code

Copy
AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)) // Can either be Key ID or alias (prefixed with 'alias/') .withEncryptionMaterials(new KMSEncryptionMaterialsProvider("alias/s3-kms-key")) .build(); AmazonS3 s3NonEncrypt = AmazonS3ClientBuilder.defaultClient(); s3Encryption.putObject(BUCKET_NAME, ENCRYPTED_KEY, "some contents"); s3NonEncrypt.putObject(BUCKET_NAME, NON_ENCRYPTED_KEY, "some other contents"); try { s3Encryption.getObjectAsString(BUCKET_NAME, NON_ENCRYPTED_KEY); } catch (SecurityException e) { // Strict authenticated encryption will throw an exception if an object is not encrypted with AES/GCM System.err.println(NON_ENCRYPTED_KEY + " was not encrypted with AES/GCM"); }

See the complete example on GitHub.