AEAD#

EverCrypt provides multiple Authenticated Encryption with Associated Data (AEAD) algorithms, i.e., …

  • ChaCha20Poly1305,

  • AES128-GCM, and

  • AES256-GCM

… via a unified interface.

In this interface, clients are expected to allocate an AEAD context (state) first, which performs key expansion and precomputes internal data, e.g., for AES-GCM. UnsupportedAlgorithm may be returned because of an unsupported algorithm, or because no implementation is available for the target platform (e.g. AES-GCM without ADX+BMI2). The state must finally be freed via the EverCrypt_AEAD_free function.

API Reference#

State management

typedef struct EverCrypt_AEAD_state_s_s EverCrypt_AEAD_state_s#

Both encryption and decryption take a piece of state that holds the key. The state may be reused as many times as desired.

EverCrypt_Error_error_code EverCrypt_AEAD_create_in(Spec_Agile_AEAD_alg a, EverCrypt_AEAD_state_s **dst, uint8_t *k)#

Create the required AEAD state for the algorithm.

Note: The caller must free the AEAD state by calling EverCrypt_AEAD_free.

Parameters

  • a – The argument a must be either of: Spec_Agile_AEAD_AES128_GCM (KEY_LEN=16), Spec_Agile_AEAD_AES256_GCM (KEY_LEN=32), or Spec_Agile_AEAD_CHACHA20_POLY1305 (KEY_LEN=32).

  • dst – Pointer to a pointer where the address of the allocated AEAD state will be written to.

  • k – Pointer to KEY_LEN bytes of memory where the key is read from. The size depends on the used algorithm, see above.

Returns

The function returns EverCrypt_Error_Success on success or EverCrypt_Error_UnsupportedAlgorithm in case of a bad algorithm identifier. (See EverCrypt_Error.h.)

The argument a must be either of:

  • Spec_Agile_AEAD_AES128_GCM,

  • Spec_Agile_AEAD_AES256_GCM, or

  • Spec_Agile_AEAD_CHACHA20_POLY1305.

Spec_Agile_AEAD_alg EverCrypt_AEAD_alg_of_state(EverCrypt_AEAD_state_s *s)#

Return the algorithm used in the AEAD state.

Parameters

s – State of the AEAD algorithm.

Returns

Algorithm used in the AEAD state.

Return the algorithm used in the AEAD state.

void EverCrypt_AEAD_free(EverCrypt_AEAD_state_s *s)#

Cleanup and free the AEAD state.

Parameters

s – State of the AEAD algorithm.

Cleanup and free the AEAD state.

Encryption

EverCrypt_Error_error_code EverCrypt_AEAD_encrypt(EverCrypt_AEAD_state_s *s, uint8_t *iv, uint32_t iv_len, uint8_t *ad, uint32_t ad_len, uint8_t *plain, uint32_t plain_len, uint8_t *cipher, uint8_t *tag)#

Encrypt and authenticate a message (plain) with associated data (ad).

Parameters

  • s – Pointer to the The AEAD state created by EverCrypt_AEAD_create_in. It already contains the encryption key.

  • iv – Pointer to iv_len bytes of memory where the nonce is read from.

  • iv_len – Length of the nonce. Note: ChaCha20Poly1305 requires a 12 byte nonce.

  • ad – Pointer to ad_len bytes of memory where the associated data is read from.

  • ad_len – Length of the associated data.

  • plain – Pointer to plain_len bytes of memory where the to-be-encrypted plaintext is read from.

  • plain_len – Length of the to-be-encrypted plaintext.

  • cipher – Pointer to plain_len bytes of memory where the ciphertext is written to.

  • tag – Pointer to TAG_LEN bytes of memory where the tag is written to. The length of the tag must be of a suitable length for the chosen algorithm: Spec_Agile_AEAD_AES128_GCM (TAG_LEN=16) Spec_Agile_AEAD_AES256_GCM (TAG_LEN=16) Spec_Agile_AEAD_CHACHA20_POLY1305 (TAG_LEN=16)

Returns

EverCrypt_AEAD_encrypt may return either EverCrypt_Error_Success or EverCrypt_Error_InvalidKey (EverCrypt_error.h). The latter is returned if and only if the s parameter is NULL.

Encrypt and authenticate a message (plain) with associated data (ad).

s is the AEAD state created by EverCrypt_AEAD_create_in and already contains the encryption key. iv is the nonce required for encryption. Note: ChaCha20Poly1305 requires a 12 byte iv. ad is the associated data that should be authenticated (not encrypted) alongside the ciphertext. plain is the to-be-encrypted plaintext.

The resulting ciphertext will be written into cipher and the mac/tag will be written into tag. Note: The length of the tag array must be of a suitable length for the chosen algorithm. There is no length parameter for the tag.

EverCrypt_AEAD_encrypt may return either EverCrypt_Error_Success or EverCrypt_Error_InvalidKey (EverCrypt_error.h). The latter is returned if and only if the s parameter is NULL.

Decryption

EverCrypt_Error_error_code EverCrypt_AEAD_decrypt(EverCrypt_AEAD_state_s *s, uint8_t *iv, uint32_t iv_len, uint8_t *ad, uint32_t ad_len, uint8_t *cipher, uint32_t cipher_len, uint8_t *tag, uint8_t *dst)#

Verify the authenticity of ad || cipher and decrypt cipher into dst.

EverCrypt_Error_InvalidKey (returned if and only if the s parameter is NULL), EverCrypt_Error_InvalidIVLength (see note about requirements on IV size above), or EverCrypt_Error_AuthenticationFailure (in case the ciphertext could not be authenticated, e.g., due to modifications)

… on failure (EverCrypt_error.h).

Upon success, the plaintext will be written into dst.

Parameters

  • s – Pointer to the The AEAD state created by EverCrypt_AEAD_create_in. It already contains the encryption key.

  • iv – Pointer to iv_len bytes of memory where the nonce is read from.

  • iv_len – Length of the nonce. Note: ChaCha20Poly1305 requires a 12 byte nonce.

  • ad – Pointer to ad_len bytes of memory where the associated data is read from.

  • ad_len – Length of the associated data.

  • cipher – Pointer to cipher_len bytes of memory where the ciphertext is read from.

  • cipher_len – Length of the ciphertext.

  • tag – Pointer to TAG_LEN bytes of memory where the tag is read from. The length of the tag must be of a suitable length for the chosen algorithm: Spec_Agile_AEAD_AES128_GCM (TAG_LEN=16) Spec_Agile_AEAD_AES256_GCM (TAG_LEN=16) Spec_Agile_AEAD_CHACHA20_POLY1305 (TAG_LEN=16)

  • dst – Pointer to cipher_len bytes of memory where the decrypted plaintext will be written to.

Returns

EverCrypt_AEAD_decrypt returns … 

`EverCrypt_Error_Success`
… on success and either of …

Verify the authenticity of ad || cipher and decrypt cipher into dst.

s is the AEAD state created by EverCrypt_AEAD_create_in and already contains the decryption key. iv is the nonce required for decryption and must be 12 bytes long. ad is the associated data that was authenticated (not encrypted) alongside the ciphertext. cipher is the to-be-decrypted ciphertext. tag is the tag/mac generated during encryption. Upon success, the plaintext will be written into dst. Note: The length of dst must be equal to the length of cipher.

EverCrypt_AEAD_decrypt returns …

  • EverCrypt_Error_Success

… on success and either of …

  • EverCrypt_Error_InvalidKey (returned if and only if the s parameter is NULL),

  • EverCrypt_Error_InvalidIVLength (see note about requirements on IV size above), or

  • EverCrypt_Error_AuthenticationFailure (in case the ciphertext could not be authenticated, e.g., due to modifications)

… on failure (EverCrypt_error.h).