Supported encryption algorithms

By default, version 3.x of the Amazon S3 Encryption Client automatically buffers the stream contents into memory as the decrypted object is read to prevent the release of unauthenticated objects. If the client reaches the end of the stream, and the authentication fails, your GetObject request will throw an exception and the unauthenticated object will not be returned.

When you use the buffered decryption mode with the Amazon S3 Encryption Client for Java, the default maximum object size that can be decrypted is 64 MB. However, you can use the optional setBufferSize parameter to customize the maximum object size that the mode will buffer. You can use the setBufferSize parameter to specify any integer between 16 bytes and 64 GB as the maxiumum object size.

The following Java example instantiates the v3Client with a raw AES wrapping key and a maximum object size of 32 MiB.

// v3
                       
class v3DefaultDecryptionModeExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .setBufferSize(32 * 1024 * 1024) // OPTIONAL
                .build();
    }
}

When you use the buffered decryption mode with the Amazon S3 Encryption Client for Go, the default maximum object size that can be decrypted is 63 GiB. You cannot set a custom buffer size with the Amazon S3 Encryption Client for Go. As a result, the buffered decryption mode does not require any additional configuration when you instatiate your client with the Amazon S3 Encryption Client for Go.

We recommend that you use the buffered decryption mode whenever possible. Since this is the default mode, you do not need to specify the buffered decryption mode when you instantiate your client.

The delayed authentication mode also supports streaming decryption of AES-GCM encrypted objects, but it does not buffer or interrupt the stream to prevent unauthenticated objects from being returned. We recommend using the Buffered (default) decryption mode whenever possible. However, you might want to use the delayed authentication mode if you established your own method of buffering the stream while using versions 1.x and 2.x of the client.

If you use the delayed authentication mode and are processing the plaintext data from the stream before reading to the end, you must account for the delayed authentication. Read the entire object to the end before you start using the decrypted object. When using this decryption mode, the Amazon S3 Encryption Client will not authenticate any object until it reaches the end of the stream. You will need to manually roll back any data from the stream if an exception is thrown at the end of the stream.

To enable the delayed authentication mode, specify the enableDelayedAuthenticationMode parameter when you instantiate the v3Client.

The following example specifies a raw AES key as the wrapping key. This client only encrypts with fully supported algorithms and decrypts using the delayed authentication mode.

// v3
                       
class v3DelayedAuthenticationModeExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .enableDelayedAuthenticationMode(true)
                .build();
    }
}

By default, the Amazon S3 Encryption Client uses the wrapping key you specify and one of the fully supported wrapping algorithms to encrypt and decrypt the data keys that encrypt your objects. If you need to decrypt data keys that were encrypted with a legacy wrapping algorithm, you must specify the enableLegacyWrappingAlgorithms parameter when you instantiate your client.

If you need to decrypt objects that were encrypted with a legacy algorithm, or you need to partially decrypt an AES-GCM encrypted object by performing a ranged request, you need to use the unauthenticated legacy mode. The Amazon S3 Encryption Client will decrypt objects with a legacy encryption algorithm, but will use the fully supported AES-GCM algorithm to encrypt any objects that you upload to Amazon S3. The decryption of AES-CBC encrypted objects and ranged requests are considered unauthenticated because the algorithms do not provide any form of authentication to ensure the integrity of the object.

To enable the unauthenticated legacy mode, specify the enableLegacyUnauthenticatedModes parameter when you instantiate the v3Client.

The enableLegacyModes parameter is designed to be a temporary fix. After you've re-encrypted all of your objects with fully supported algorithms, you can remove it from your code.