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.
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.