Supported encryption algorithms - Amazon S3 Encryption Client
Encryption algorithms (Version 3.x and later)Decryption modes (Version 3.x and later)Encryption algorithms (Version 2.x and earlier)

Supported encryption algorithms

Note

This documentation describes the Amazon S3 Encryption Client version 3.x, which is an independent library. For information about previous versions of the Amazon S3 Encryption Client, see the AWS SDK Developer Guide for your programming language.

The Amazon S3 Encryption Client supports industry-standard algorithms for encrypting objects and data keys. As our knowledge evolves, we adjust our support for encryption algorithms to ensure that your sensitive data is protected. The following topic provides context on which encryption algorithms are fully supported and the different decryption modes supported in version 3.x of the Amazon S3 Encryption Client.

Encryption algorithms (Version 3.x and later)

In versions 3.x and later, the Amazon S3 Encryption Client will use fully supported algorithms to encrypt and decrypt objects and data keys. You can enable the Amazon S3 Encryption Client to decrypt objects and data keys with a legacy encryption algorithm, but it will not encrypt with a legacy encryption algorithm. It encrypts only with a fully supported encryption algorithm.

The following tables list the object encryption algorithms and wrapping algorithms that are supported in version 3.x of the Amazon S3 Encryption Client. Use these tables to determine if any of your objects or data keys were encrypted with an algorithm that is no longer supported. If you need to decrypt objects or data keys that were encrypted with a legacy algorithm, see Enable legacy decryption modes.

Encrypting objects — The following table lists the fully supported (Full) and previously supported (Legacy) encryption algorithms that are used to encrypt objects.

Algorithm Support
AES-GCM Full
AES-CBC Legacy

Encrypting data keys — The following table lists the fully supported (Full) and previously supported (Legacy) wrapping algorithms that are used to encrypt the data keys that encrypt your objects. 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.

Algorithm Support
AES-GCM Full
AWS KMS (with an encryption context) Full
RSA-OAEP-MGF1 and SHA-1 Full
AES Legacy
AESWrap Legacy
AWS KMS (without an encryption context) Legacy
RSA-OAEP-MGF-1 and SHA-256 Legacy
RSA Legacy

Decryption modes (Version 3.x and later)

Version 3.x of the Amazon S3 Encryption Client defines four modes of support for decryption that you can use to enable the client to decrypt objects and data keys with either fully supported or legacy algorithms.

Fully supported

By default, version 3.x of the Amazon S3 Encryption Client encrypts and decrypts your objects using the AES-GCM algorithm suite. AES-GCM is an authenticated scheme. This means that an authentication tag is appended to the encrypted object. The default behavior for versions 1.x and 2.x allowed streaming decryption of AES-GCM encrypted objects. Because authentication happens at the end of the decryption process, the entire object must be read before the cipher can validate the integrity of it. This allows plaintext objects to be released and used before the authentication tag is validated.

Version 3.x of the Amazon S3 Encryption Client supports streaming decryption of AES-GCM encrypted objects, but we recommend using the default decryption mode to prevent the release of unauthenticated plaintext objects.

Buffered (default)

By default, version 3.x of the Amazon S3 Encryption Client automatically buffers the stream contents into memory to 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. The maximum object size that can be decrypted under this mode is 64 MB.

If you are new to the Amazon S3 Encryption Client, know that all of your objects are less than 64 MB, or are unsure of the size of your objects, we recommend you use the buffered decryption mode. Since this is the default mode, it does not require any additional configuration when you instantiate your client.

Delayed authentication

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 you only use this mode if you are decrypting objects larger than 64 MB. However, you may also want to use this 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, even if the object is smaller than 64 MB. 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 raws AES key as the wrapping key. This client only encrypts with fuly 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();
    }
}

Legacy

Legacy wrapping algorithms

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.

The following example specifies a raw AES key as the wrapping key. This client only encrypts with fully supported wrapping algorithms. However, it can decrypt data keys encrypted with fully supported or legacy wrapping algorithms.

// v3
                       
class v3LegacyWrappingAlgorithmsExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .enableLegacyWrappingAlgorithms(true)
                .build();
    }
}
Unauthenticated legacy object encryption algorithms

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 following example specifies an AES key as the wrapping key. This client only encrypts with fully supported algorithms. However, it can decrypt objects encrypted with fully supported or legacy algorithms.

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

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.

Encryption algorithms (Version 2.x and earlier)

The following tables list the object encryption and wrapping algorithms that are supported in versions 2.x and earlier of the Amazon S3 Encryption Client. Versions 1.x and 2.x of the Amazon S3 Encryption Client are included in the following AWS SDKs.

Encrypting objects — The following table lists encryption algorithms that are used to encrypt objects.

Algorithm C++ Go Java .NET PHP v3 Ruby v2
AES-GCM Full Full Full Full Full Full
AES-CBC Legacy Legacy Legacy No No Legacy

Encrypting data keys — The following table lists encryption algorithms that are used to encrypt the data keys that were used to encrypt objects.

Algorithm C++ Go Java .NET PHP v3 Ruby v2
AES-ECB No No Legacy Legacy No Legacy
AES-GCM Full No Full Full No Full
AESWrap Legacy No Legacy Legacy No Legacy
KMS Legacy Legacy Legacy Legacy Legacy Legacy
KMS+context Full Full Full Full Full Full
RSA No No Legacy No No Legacy
RSA-OAEP-SHA1 No No Full Full No Full