Package software.amazon.encryption.s3.algorithms

Enum AlgorithmSuite

  • All Implemented Interfaces:
    Serializable, Comparable<AlgorithmSuite>
    public enum AlgorithmSuite
extends Enum<AlgorithmSuite>
    Defines the cryptographic algorithms available for encrypting and decrypting S3 objects. Each algorithm suite specifies the cipher, key derivation function, block size, IV length, tag length, and whether it supports key commitment.

    Key commitment protects Instruction Files by cryptographically binding the data key to the encrypted object, preventing the data key stored in an Instruction File from being tampered with.

    For more information, refer to the Developer Guide.

    • Enum Constant Detail

      • ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY

        public static final AlgorithmSuite ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY
        AES-256-GCM with HKDF-SHA512 key derivation and key commitment support. This is a recommended algorithm suite providing maximum security with key commitment guarantees. Supports both encryption and decryption operations. This is the default algorithm for v4 clients.

        V3 clients (only v3.6.0 or later) can only use this suite to read objects with key commitment; to use this suite to write objects with key commitment, upgrade to a v4 client.

      • ALG_AES_256_CTR_HKDF_SHA512_COMMIT_KEY

        public static final AlgorithmSuite ALG_AES_256_CTR_HKDF_SHA512_COMMIT_KEY
        AES-256-CTR with HKDF-SHA512 key derivation and key commitment support. This algorithm suite is used only for decrypting ranged get operations with key commitment. Does not support encryption operations.

      • ALG_AES_256_GCM_IV12_TAG16_NO_KDF

        public static final AlgorithmSuite ALG_AES_256_GCM_IV12_TAG16_NO_KDF
        AES-256-GCM without key derivation function or key commitment. This algorithm suite does not support key commitment and is maintained for backward compatibility. This is the default algorithm suite for v3 clients.

        Content encrypted with this algorithm suite can be read by any v2, v3, or v4 client. Supports both encryption and decryption operations.

      • ALG_AES_256_CTR_IV16_TAG16_NO_KDF

        public static final AlgorithmSuite ALG_AES_256_CTR_IV16_TAG16_NO_KDF
        AES-256-CTR without key derivation function or key commitment. This is a legacy algorithm suite used only for decrypting ranged get operations. Does not support encryption operations.

      • ALG_AES_256_CBC_IV16_NO_KDF

        public static final AlgorithmSuite ALG_AES_256_CBC_IV16_NO_KDF
        AES-256-CBC without key derivation function or key commitment. This is a legacy algorithm suite used only for decrypting legacy objects. Does not support encryption operations or authentication.

    • Method Detail

      • values

        public static AlgorithmSuite[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (AlgorithmSuite c : AlgorithmSuite.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        public static AlgorithmSuite valueOf​(String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        IllegalArgumentException - if this enum type has no constant with the specified name
        NullPointerException - if the argument is null

      • id

        public int id()
        Returns the numeric identifier for this algorithm suite used in the encrypted message format.
        Returns:
        the algorithm suite ID as an integer

      • idAsString

        public String idAsString()
        Returns the algorithm suite ID as a string representation.
        Returns:
        the algorithm suite ID as a string

      • idAsBytes

        public byte[] idAsBytes()
        Returns the algorithm suite ID as a 2-byte array in big-endian format.
        Returns:
        the algorithm suite ID as a byte array

      • isLegacy

        public boolean isLegacy()
        Indicates whether this algorithm suite is considered legacy and may have security limitations.
        Returns:
        true if this is a legacy algorithm suite

      • dataKeyAlgorithm

        public String dataKeyAlgorithm()
        Returns the algorithm used for the data key (e.g., "AES").
        Returns:
        the data key algorithm name

      • dataKeyLengthBits

        public int dataKeyLengthBits()
        Returns the length of the data key in bits.
        Returns:
        the data key length (in bits)

      • dataKeyLengthBytes

        public int dataKeyLengthBytes()
        Returns the length of the data key in bytes.
        Returns:
        the data key length (in bytes)

      • cipherName

        public String cipherName()
        Returns the cipher transformation string used for encryption and decryption (e.g., "AES/GCM/NoPadding").
        Returns:
        the cipher name with mode and padding

      • cipherTagLengthBits

        public int cipherTagLengthBits()
        Returns the length of the authentication tag in bits for authenticated encryption modes.
        Returns:
        the tag length (in bits), or 0 if not applicable

      • cipherTagLengthBytes

        public int cipherTagLengthBytes()
        Returns the length of the authentication tag in bytes for authenticated encryption modes.
        Returns:
        the tag length (in bytes), or 0 if not applicable

      • iVLengthBytes

        public int iVLengthBytes()
        Returns the length of the initialization vector (IV) in bytes.
        Returns:
        the IV length (in bytes)

      • cipherBlockSizeBytes

        public int cipherBlockSizeBytes()
        Returns the block size of the cipher in bytes.
        Returns:
        the cipher block size (in bytes)

      • cipherMaxContentLengthBits

        public long cipherMaxContentLengthBits()
        Returns the maximum content length in bits that can be encrypted under a single data key.
        Returns:
        the maximum content length (in bits)

      • cipherMaxContentLengthBytes

        public long cipherMaxContentLengthBytes()
        Returns the maximum content length in bytes that can be encrypted under a single data key.
        Returns:
        the maximum content length (in bytes)

      • isCommitting

        public boolean isCommitting()
        Indicates whether this algorithm suite supports key commitment.
        Returns:
        true if key commitment is supported

      • commitmentLengthBits

        public int commitmentLengthBits()
        Returns the length of the key commitment value in bits.
        Returns:
        the commitment length (in bits), or 0 if not applicable

      • commitmentLengthBytes

        public int commitmentLengthBytes()
        Returns the length of the key commitment value in bytes.
        Returns:
        the commitment length (in bytes), or 0 if not applicable

      • kdfHashAlgorithm

        public String kdfHashAlgorithm()
        Returns the hash algorithm used in the key derivation function (e.g., "HmacSHA512").
        Returns:
        the KDF hash algorithm name, or empty string if no KDF is used

      • commitmentNonceLengthBits

        public int commitmentNonceLengthBits()
        Returns the length of the nonce used for key commitment in bits.
        Returns:
        the commitment nonce length (in bits), or 0 if not applicable

      • commitmentNonceLengthBytes

        public int commitmentNonceLengthBytes()
        Returns the length of the nonce used for key commitment in bytes.
        Returns:
        the commitment nonce length (in bytes), or 0 if not applicable