Menu
AWS SDK for Java
Developer Guide

Amazon S3 Client-Side Encryption with Client Master Keys

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

Note

The following examples demonstrate using the Amazon S3 client-side encryption with customer-managed client master keys. To learn how to use encryption with AWS KMS managed keys, see Amazon S3 Client-Side Encryption with AWS KMS Managed 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

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.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 enable encryption, you must pass a key to the EncryptionMaterials constructor. The example below uses the KeyGenerator Java class generate a symmetric private key.

Code

SecretKey secretKey = KeyGenerator.getInstance("AES").generateKey(); AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.EncryptionOnly)) .withEncryptionMaterials(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) .build();

To use an asymmetric key or a key pair, simply pass the key pair to the same EncryptionMaterials class. The example below uses the KeyPairGenerator class to generate a key pair.

Code

KeyPair keyPair = KeyPairGenerator.getInstance("RSA").generateKeyPair(); AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.EncryptionOnly)) .withEncryptionMaterials(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(keyPair))) .build();

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

Code

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

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

AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)) .withEncryptionMaterials(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) .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

SecretKey secretKey = KeyGenerator.getInstance("AES").generateKey(); AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)) .withEncryptionMaterials(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) .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

AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.StrictAuthenticatedEncryption)) .withEncryptionMaterials(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) .build();

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

Code

SecretKey secretKey = KeyGenerator.getInstance("AES").generateKey(); AmazonS3Encryption s3Encryption = AmazonS3EncryptionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfiguration(CryptoMode.StrictAuthenticatedEncryption)) .withEncryptionMaterials(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey))) .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)); 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.