Migrating to version 3.x of the Amazon S3 Encryption Client for Java

The v3Client constructor does not use the EncryptionMaterialsProvider that was required in versions 1.x and 2.x of the Amazon S3 Encryption Client. Instead, you use a parameter of the v3Client builder to specify your wrapping key. The Amazon S3 Encryption Client supports the following wrapping keys: AWS Key Management Service (AWS KMS) symmetric AWS KMS keys, raw AES-GCM (Advanced Encryption Standard/Galois Counter Mode) keys, and raw RSA keys. The Amazon S3 Encryption Client optimizes its settings based on the wrapping key type.

When updating from earlier versions of the Amazon S3 Encryption Client to version 3.x, you need to update your client builder code to use the new, simpler interface for the v3Client. If you're decrypting ciphertext that was encrypted by earlier versions of the Amazon S3 Encryption Client, you might also need to allow the Amazon S3 Encryption Client to decrypt legacy encryption algorithms.

To update to Amazon S3 Encryption Client version 3.x, delete the code that instantiates the EncryptionMaterialsProvider. Then replace the code that calls the v1Client or v2Client builder with code that calls the v3Client builder. Use a parameter of the v3Client builder to specify your wrapping key.

The following examples show the equivalent code required to specify a KMS key as the wrapping key in versions 1.x, 2.x, and 3.x of the Amazon S3 Encryption Client.

Version 1.x

In Amazon S3 Encryption Client version 1.x, you instantiate an EncryptionMaterialsProvider with your wrapping key, and then specify that materials provider when instantiating the v1Client object.

// v1

class v1KMSKeyExample {
    public static void main(String[] args) {

        EncryptionMaterialsProvider materialsProvider = new KMSEncryptionMaterialsProvider(kmsKeyId);
        AmazonS3Encryption v1Client = AmazonS3EncryptionClient.encryptionBuilder()
                .withEncryptionMaterialsProvider(materialsProvider)
                .build();
    }
}

Version 2.x

In Amazon S3 Encryption Client version 2.x, you instantiate an EncryptionMaterialsProvider with your wrapping key, and then specify that materials provider when instantiating the v2Client object.

// v2

class v2KMSKeyExample {
    public static void main(String[] args) {

        EncryptionMaterialsProvider materialsProvider = new KMSEncryptionMaterialsProvider(kmsKeyId);
        AmazonS3EncryptionV2 v2Client = AmazonS3EncryptionClientV2.encryptionBuilder()
                .withEncryptionMaterialsProvider(materialsProvider)
                .build();
    }
}

Version 3.x

In Amazon S3 Encryption Client version 3.x, the v3Client constructor requires only a parameter that identifies the wrapping key. For a KMS key, use the kmsKeyId parameter. The value of the kmsKeyId parameter can be any valid KMS key identifier. For details, see Key identifiers in the AWS Key Management Service Developer Guide.

// v3

class v3KMSKeyExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .kmsKeyId(kmsKeyId)
                .build();
    }
}

Enable legacy decryption modes

If you need to decrypt objects or data keys that were encrypted with a legacy algorithm, or you need to partially decrypt an AES-GCM encrypted object when performing a ranged request, you need to explicitly enable this behavior when you instantiate the client.

The v3Client encrypts only with fully supported algorithms. It will never encrypt with a legacy algorithm. By default, it decrypts only with fully supported algorithms, but you can enable it to decrypt with both fully supported and legacy algorithms. For more information, see Decryption modes (Amazon S3 Encryption Client for Java version 3.x and later).

The enableLegacyUnauthenticatedModes parameter of the v3Client builder enables the Amazon S3 Encryption Client to decrypt encrypted objects with a fully supported or legacy encryption algorithm.

Version 3.x of the Amazon S3 Encryption Client uses one of the fully supported wrapping algorithms and the wrapping key you specify to encrypt and decrypt the data keys. The enableLegacyWrappingAlgorithms parameter of the v3Client builder enables the Amazon S3 Encryption Client to decrypt encrypted data keys with a fully supported or legacy wrapping algorithm.

If your v3Client doesn't include the necessary legacy decryption mode with a value of true, and it encounters an object encrypted with a legacy algorithm, it throws S3EncryptionClientException.

For example, this code builds a v3Client object with a user-provided raw AES wrapping key. This client always encrypts only with fully supported algorithms. However, it can decrypt objects and data keys encrypted with fully supported or legacy algorithms.

// v3

class v3EnableLegacyDecryptionModesExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .enableLegacyUnauthenticatedModes(true)
                .enableLegacyWrappingAlgorithms(true)
                .build();
    }
}

The legacy decryption modes are designed to be a temporary fix. After you've re-encrypted all of your objects with fully supported algorithms, you can eliminate it from your code.