aead.h

All headers

Authenticated Encryption with Additional Data.

AEAD couples confidentiality and integrity in a single primitive. AEAD algorithms take a key and then can seal and open individual messages. Each message has a unique, per-message nonce and, optionally, additional data which is authenticated but not included in the ciphertext.

The EVP_AEAD_CTX_init function initialises an EVP_AEAD_CTX structure and performs any precomputation needed to use aead with key. The length of the key, key_len, is given in bytes.

The tag_len argument contains the length of the tags, in bytes, and allows for the processing of truncated authenticators. A zero value indicates that the default tag length should be used and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH in order to make the code clear. Using truncated tags increases an attacker's chance of creating a valid forgery. Be aware that the attacker's chance may increase more than exponentially as would naively be expected.

When no longer needed, the initialised EVP_AEAD_CTX structure must be passed to EVP_AEAD_CTX_cleanup, which will deallocate any memory used.

With an EVP_AEAD_CTX in hand, one can seal and open messages. These operations are intended to meet the standard notions of privacy and authenticity for authenticated encryption. For formal definitions see Bellare and Namprempre, "Authenticated encryption: relations among notions and analysis of the generic composition paradigm," Lecture Notes in Computer Science B<1976> (2000), 531–545, http://www-cse.ucsd.edu/~mihir/papers/oem.html.

When sealing messages, a nonce must be given. The length of the nonce is fixed by the AEAD in use and is returned by EVP_AEAD_nonce_length. *The nonce must be unique for all messages with the same key*. This is critically important - nonce reuse may completely undermine the security of the AEAD. Nonces may be predictable and public, so long as they are unique. Uniqueness may be achieved with a simple counter or, if large enough, may be generated randomly. The nonce must be passed into the "open" operation by the receiver so must either be implicit (e.g. a counter), or must be transmitted along with the sealed message.

The "seal" and "open" operations are atomic - an entire message must be encrypted or decrypted in a single call. Large messages may have to be split up in order to accommodate this. When doing so, be mindful of the need not to repeat nonces and the possibility that an attacker could duplicate, reorder or drop message chunks. For example, using a single key for a given (large) message and sealing chunks with nonces counting from zero would be secure as long as the number of chunks was securely transmitted. (Otherwise an attacker could truncate the message by dropping chunks from the end.)

The number of chunks could be transmitted by prefixing it to the plaintext, for example. This also assumes that no other message would ever use the same key otherwise the rule that nonces must be unique for a given key would be violated.

The "seal" and "open" operations also permit additional data to be authenticated via the ad parameter. This data is not included in the ciphertext and must be identical for both the "seal" and "open" call. This permits implicit context to be authenticated but may be empty if not needed.

The "seal" and "open" operations may work in-place if the out and in arguments are equal. Otherwise, if out and in alias, input data may be overwritten before it is read. This situation will cause an error.

The "seal" and "open" operations return one on success and zero on error.

  1. AEAD algorithms
  2. EVP_aead_aes_128_gcm
  3. EVP_aead_aes_192_gcm
  4. EVP_aead_aes_256_gcm
  5. EVP_aead_chacha20_poly1305
  6. EVP_aead_xchacha20_poly1305
  7. EVP_aead_aes_128_ctr_hmac_sha256
  8. EVP_aead_aes_256_ctr_hmac_sha256
  9. EVP_aead_aes_128_gcm_siv
  10. EVP_aead_aes_256_gcm_siv
  11. EVP_aead_aes_128_gcm_randnonce
  12. EVP_aead_aes_256_gcm_randnonce
  13. EVP_aead_aes_128_ccm_bluetooth
  14. EVP_aead_aes_128_ccm_bluetooth_8
  15. EVP_aead_aes_128_ccm_matter
  16. EVP_has_aes_hardware
  17. Utility functions
  18. EVP_AEAD_key_length
  19. EVP_AEAD_nonce_length
  20. EVP_AEAD_max_overhead
  21. EVP_AEAD_max_tag_len
  22. AEAD operations
  23. evp_aead_ctx_st
  24. EVP_AEAD_MAX_KEY_LENGTH
  25. EVP_AEAD_MAX_NONCE_LENGTH
  26. EVP_AEAD_MAX_OVERHEAD
  27. EVP_AEAD_DEFAULT_TAG_LENGTH
  28. EVP_AEAD_CTX_zero
  29. EVP_AEAD_CTX_new
  30. EVP_AEAD_CTX_free
  31. EVP_AEAD_CTX_init
  32. EVP_AEAD_CTX_cleanup
  33. EVP_AEAD_CTX_seal
  34. EVP_AEAD_CTX_open
  35. EVP_AEAD_CTX_seal_scatter
  36. EVP_AEAD_CTX_open_gather
  37. EVP_AEAD_CTX_aead
  38. TLS-specific AEAD algorithms
  39. EVP_aead_aes_128_cbc_sha1_tls
  40. EVP_aead_aes_128_cbc_sha1_tls_implicit_iv
  41. EVP_aead_aes_128_cbc_sha256_tls
  42. EVP_aead_aes_256_cbc_sha1_tls
  43. EVP_aead_aes_256_cbc_sha1_tls_implicit_iv
  44. EVP_aead_des_ede3_cbc_sha1_tls
  45. EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv
  46. EVP_aead_aes_128_gcm_tls12
  47. EVP_aead_aes_256_gcm_tls12
  48. EVP_aead_aes_128_gcm_tls13
  49. EVP_aead_aes_256_gcm_tls13
  50. Obscure functions
  51. evp_aead_direction_t
  52. EVP_AEAD_CTX_init_with_direction
  53. EVP_AEAD_CTX_get_iv
  54. EVP_AEAD_CTX_tag_len

AEAD algorithms.

EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode.

Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it is specified to take a variable-length nonce, nonces with other lengths are effectively randomized, which means one must consider collisions. Unless implementing an existing protocol which has already specified incorrect parameters, only use 12-byte nonces.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void);

EVP_aead_aes_192_gcm is AES-192 in Galois Counter Mode.

WARNING: AES-192 is superfluous and shouldn't exist. NIST should never have defined it. Use only when interop with another system requires it, never de novo.

Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it is specified to take a variable-length nonce, nonces with other lengths are effectively randomized, which means one must consider collisions. Unless implementing an existing protocol which has already specified incorrect parameters, only use 12-byte nonces.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_192_gcm(void);

EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode.

Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it is specified to take a variable-length nonce, nonces with other lengths are effectively randomized, which means one must consider collisions. Unless implementing an existing protocol which has already specified incorrect parameters, only use 12-byte nonces.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void);

EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and Poly1305 as described in RFC 8439.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void);

EVP_aead_xchacha20_poly1305 is ChaCha20-Poly1305 with an extended nonce that makes random generation of nonces safe.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xchacha20_poly1305(void);

EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for authentication. The nonce is 12 bytes; the bottom 32-bits are used as the block counter, thus the maximum plaintext size is 64GB.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void);

EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for authentication. See EVP_aead_aes_128_ctr_hmac_sha256 for details.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void);

EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See RFC 8452.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_siv(void);

EVP_aead_aes_256_gcm_siv is AES-256 in GCM-SIV mode. See RFC 8452.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_siv(void);

EVP_aead_aes_128_gcm_randnonce is AES-128 in Galois Counter Mode with internal nonce generation. The 12-byte nonce is appended to the tag and is generated internally. The "tag", for the purpurses of the API, is thus 12 bytes larger. The nonce parameter when using this AEAD must be zero-length. Since the nonce is random, a single key should not be used for more than 2^32 seal operations.

Warning: this is for use for FIPS compliance only. It is probably not suitable for other uses. Using standard AES-GCM AEADs allows one to achieve the same effect, but gives more control over nonce storage.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_randnonce(void);

EVP_aead_aes_256_gcm_randnonce is AES-256 in Galois Counter Mode with internal nonce generation. The 12-byte nonce is appended to the tag and is generated internally. The "tag", for the purpurses of the API, is thus 12 bytes larger. The nonce parameter when using this AEAD must be zero-length. Since the nonce is random, a single key should not be used for more than 2^32 seal operations.

Warning: this is for use for FIPS compliance only. It is probably not suitable for other uses. Using standard AES-GCM AEADs allows one to achieve the same effect, but gives more control over nonce storage.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_randnonce(void);

EVP_aead_aes_128_ccm_bluetooth is AES-128-CCM with M=4 and L=2 (4-byte tags and 13-byte nonces), as decribed in the Bluetooth Core Specification v5.0, Volume 6, Part E, Section 1.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_bluetooth(void);

EVP_aead_aes_128_ccm_bluetooth_8 is AES-128-CCM with M=8 and L=2 (8-byte tags and 13-byte nonces), as used in the Bluetooth Mesh Networking Specification v1.0.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_bluetooth_8(void);

EVP_aead_aes_128_ccm_matter is AES-128-CCM with M=16 and L=2 (16-byte tags and 13-byte nonces), as used in the Matter specification.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ccm_matter(void);

EVP_has_aes_hardware returns one if we enable hardware support for fast and constant-time AES-GCM.

OPENSSL_EXPORT int EVP_has_aes_hardware(void);

Utility functions.

EVP_AEAD_key_length returns the length, in bytes, of the keys used by aead.

OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead);

EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce for aead.

OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead);

EVP_AEAD_max_overhead returns the maximum number of additional bytes added by the act of sealing data with aead.

OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead);

EVP_AEAD_max_tag_len returns the maximum tag length when using aead. This is the largest value that can be passed as tag_len to EVP_AEAD_CTX_init.

OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead);

AEAD operations.

union evp_aead_ctx_st_state {
  uint8_t opaque[564];
  uint64_t alignment;
};

An evp_aead_ctx_st (typedefed as EVP_AEAD_CTX in base.h) represents an AEAD algorithm configured with a specific key and message-independent IV.

struct evp_aead_ctx_st {
  const EVP_AEAD *aead;
  union evp_aead_ctx_st_state state;
  // tag_len may contain the actual length of the authentication tag if it is
  // known at initialization time.
  uint8_t tag_len;
};

EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by any AEAD defined in this header.

#define EVP_AEAD_MAX_KEY_LENGTH 80

EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by any AEAD defined in this header.

#define EVP_AEAD_MAX_NONCE_LENGTH 24

EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD defined in this header.

#define EVP_AEAD_MAX_OVERHEAD 64

EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should be used.

#define EVP_AEAD_DEFAULT_TAG_LENGTH 0

EVP_AEAD_CTX_zero sets an uninitialized ctx to the zero state. It must be initialized with EVP_AEAD_CTX_init before use. It is safe, but not necessary, to call EVP_AEAD_CTX_cleanup in this state. This may be used for more uniform cleanup of EVP_AEAD_CTX.

OPENSSL_EXPORT void EVP_AEAD_CTX_zero(EVP_AEAD_CTX *ctx);

EVP_AEAD_CTX_new allocates an EVP_AEAD_CTX, calls EVP_AEAD_CTX_init and returns the EVP_AEAD_CTX, or NULL on error.

OPENSSL_EXPORT EVP_AEAD_CTX *EVP_AEAD_CTX_new(const EVP_AEAD *aead,
                                              const uint8_t *key,
                                              size_t key_len, size_t tag_len);

EVP_AEAD_CTX_free calls EVP_AEAD_CTX_cleanup and OPENSSL_free on ctx.

OPENSSL_EXPORT void EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx);

EVP_AEAD_CTX_init initializes ctx for the given AEAD algorithm. The impl argument is ignored and should be NULL. Authentication tags may be truncated by passing a size as tag_len. A tag_len of zero indicates the default tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for readability.

Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In the error case, you do not need to call EVP_AEAD_CTX_cleanup, but it's harmless to do so.

OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead,
                                     const uint8_t *key, size_t key_len,
                                     size_t tag_len, ENGINE *impl);

EVP_AEAD_CTX_cleanup frees any data allocated by ctx. It is a no-op to call EVP_AEAD_CTX_cleanup on a EVP_AEAD_CTX that has been memset to all zeros.

OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);

EVP_AEAD_CTX_seal encrypts and authenticates in_len bytes from in and authenticates ad_len bytes from ad and writes the result to out. It returns one on success and zero otherwise.

This function may be called concurrently with itself or any other seal/open function on the same EVP_AEAD_CTX.

At most max_out_len bytes are written to out and, in order to ensure success, max_out_len should be in_len plus the result of EVP_AEAD_max_overhead. On successful return, *out_len is set to the actual number of bytes written.

The length of nonce, nonce_len, must be equal to the result of EVP_AEAD_nonce_length for this AEAD.

EVP_AEAD_CTX_seal never results in a partial output. If max_out_len is insufficient, zero will be returned. If any error occurs, out will be filled with zero bytes and *out_len set to zero.

If in and out alias then out must be == in.

OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out,
                                     size_t *out_len, size_t max_out_len,
                                     const uint8_t *nonce, size_t nonce_len,
                                     const uint8_t *in, size_t in_len,
                                     const uint8_t *ad, size_t ad_len);

EVP_AEAD_CTX_open authenticates in_len bytes from in and ad_len bytes from ad and decrypts at most in_len bytes into out. It returns one on success and zero otherwise.

This function may be called concurrently with itself or any other seal/open function on the same EVP_AEAD_CTX.

At most in_len bytes are written to out. In order to ensure success, max_out_len should be at least in_len. On successful return, *out_len is set to the the actual number of bytes written.

The length of nonce, nonce_len, must be equal to the result of EVP_AEAD_nonce_length for this AEAD.

EVP_AEAD_CTX_open never results in a partial output. If max_out_len is insufficient, zero will be returned. If any error occurs, out will be filled with zero bytes and *out_len set to zero.

If in and out alias then out must be == in.

OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out,
                                     size_t *out_len, size_t max_out_len,
                                     const uint8_t *nonce, size_t nonce_len,
                                     const uint8_t *in, size_t in_len,
                                     const uint8_t *ad, size_t ad_len);

EVP_AEAD_CTX_seal_scatter encrypts and authenticates in_len bytes from in and authenticates ad_len bytes from ad. It writes in_len bytes of ciphertext to out and the authentication tag to out_tag. It returns one on success and zero otherwise.

This function may be called concurrently with itself or any other seal/open function on the same EVP_AEAD_CTX.

Exactly in_len bytes are written to out, and up to EVP_AEAD_max_overhead+extra_in_len bytes to out_tag. On successful return, *out_tag_len is set to the actual number of bytes written to out_tag.

extra_in may point to an additional plaintext input buffer if the cipher supports it. If present, extra_in_len additional bytes of plaintext are encrypted and authenticated, and the ciphertext is written (before the tag) to out_tag. max_out_tag_len must be sized to allow for the additional extra_in_len bytes.

The length of nonce, nonce_len, must be equal to the result of EVP_AEAD_nonce_length for this AEAD.

EVP_AEAD_CTX_seal_scatter never results in a partial output. If max_out_tag_len is insufficient, zero will be returned. If any error occurs, out and out_tag will be filled with zero bytes and *out_tag_len set to zero.

If in and out alias then out must be == in. out_tag may not alias any other argument.

OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter(
    const EVP_AEAD_CTX *ctx, uint8_t *out,
    uint8_t *out_tag, size_t *out_tag_len, size_t max_out_tag_len,
    const uint8_t *nonce, size_t nonce_len,
    const uint8_t *in, size_t in_len,
    const uint8_t *extra_in, size_t extra_in_len,
    const uint8_t *ad, size_t ad_len);

EVP_AEAD_CTX_open_gather decrypts and authenticates in_len bytes from in and authenticates ad_len bytes from ad using in_tag_len bytes of authentication tag from in_tag. If successful, it writes in_len bytes of plaintext to out. It returns one on success and zero otherwise.

This function may be called concurrently with itself or any other seal/open function on the same EVP_AEAD_CTX.

The length of nonce, nonce_len, must be equal to the result of EVP_AEAD_nonce_length for this AEAD.

EVP_AEAD_CTX_open_gather never results in a partial output. If any error occurs, out will be filled with zero bytes.

If in and out alias then out must be == in.

OPENSSL_EXPORT int EVP_AEAD_CTX_open_gather(
    const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *nonce,
    size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *in_tag,
    size_t in_tag_len, const uint8_t *ad, size_t ad_len);

EVP_AEAD_CTX_aead returns the underlying AEAD for ctx, or NULL if one has not been set.

OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx);

TLS-specific AEAD algorithms.

These AEAD primitives do not meet the definition of generic AEADs. They are all specific to TLS and should not be used outside of that context. They must be initialized with EVP_AEAD_CTX_init_with_direction, are stateful, and may not be used concurrently. Any nonces are used as IVs, so they must be unpredictable. They only accept an ad parameter of length 11 (the standard TLS one with length omitted).

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha256_tls(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_tls_implicit_iv(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void);

EVP_aead_aes_128_gcm_tls12 is AES-128 in Galois Counter Mode using the TLS 1.2 nonce construction.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls12(void);

EVP_aead_aes_256_gcm_tls12 is AES-256 in Galois Counter Mode using the TLS 1.2 nonce construction.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls12(void);

EVP_aead_aes_128_gcm_tls13 is AES-128 in Galois Counter Mode using the TLS 1.3 nonce construction.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls13(void);

EVP_aead_aes_256_gcm_tls13 is AES-256 in Galois Counter Mode using the TLS 1.3 nonce construction.

OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls13(void);

Obscure functions.

evp_aead_direction_t denotes the direction of an AEAD operation.

enum evp_aead_direction_t {
  evp_aead_open,
  evp_aead_seal,
};

EVP_AEAD_CTX_init_with_direction calls EVP_AEAD_CTX_init for normal AEADs. For TLS-specific and SSL3-specific AEADs, it initializes ctx for a given direction.

OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction(
    EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len,
    size_t tag_len, enum evp_aead_direction_t dir);

EVP_AEAD_CTX_get_iv sets *out_len to the length of the IV for ctx and sets *out_iv to point to that many bytes of the current IV. This is only meaningful for AEADs with implicit IVs (i.e. CBC mode in TLS 1.0).

It returns one on success or zero on error.

OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx,
                                       const uint8_t **out_iv, size_t *out_len);

EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by EVP_AEAD_CTX_seal_scatter and writes it to *out_tag_len. It returns one on success or zero on error. in_len and extra_in_len must equal the arguments of the same names passed to EVP_AEAD_CTX_seal_scatter.

OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx,
                                        size_t *out_tag_len,
                                        const size_t in_len,
                                        const size_t extra_in_len);