AEAD

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

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.

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.

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

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`

Contents