NAME
EVP_AEAD_CTX_init,
EVP_AEAD_CTX_cleanup,
EVP_AEAD_CTX_open,
EVP_AEAD_CTX_seal,
EVP_AEAD_key_length,
EVP_AEAD_max_overhead,
EVP_AEAD_max_tag_len,
EVP_AEAD_nonce_length,
EVP_aead_aes_128_gcm,
EVP_aead_aes_256_gcm,
EVP_aead_chacha20_poly1305,
EVP_aead_xchacha20_poly1305 —
authenticated encryption with
additional data
SYNOPSIS
#include
<openssl/evp.h>
int
EVP_AEAD_CTX_init(EVP_AEAD_CTX
*ctx, const EVP_AEAD *aead,
const unsigned char *key, size_t
key_len, size_t tag_len, ENGINE
*impl);
void
EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX
*ctx);
int
EVP_AEAD_CTX_open(const EVP_AEAD_CTX
*ctx, unsigned char *out, size_t
*out_len, size_t max_out_len,
const unsigned char *nonce, size_t
nonce_len, const unsigned char *in,
size_t in_len, const unsigned char
*ad, size_t ad_len);
int
EVP_AEAD_CTX_seal(const EVP_AEAD_CTX
*ctx, unsigned char *out, size_t
*out_len, size_t max_out_len,
const unsigned char *nonce, size_t
nonce_len, const unsigned char *in,
size_t in_len, const unsigned char
*ad, size_t ad_len);
size_t
EVP_AEAD_key_length(const EVP_AEAD
*aead);
size_t
EVP_AEAD_max_overhead(const EVP_AEAD
*aead);
size_t
EVP_AEAD_max_tag_len(const EVP_AEAD
*aead);
size_t
EVP_AEAD_nonce_length(const EVP_AEAD
*aead);
const EVP_AEAD *
EVP_aead_aes_128_gcm(void);
const EVP_AEAD *
EVP_aead_aes_256_gcm(void);
const EVP_AEAD *
EVP_aead_chacha20_poly1305(void);
const EVP_AEAD *
EVP_aead_xchacha20_poly1305(void);
DESCRIPTION
AEAD (Authenticated Encryption with Additional Data) couples confidentiality and integrity in a single primitive. AEAD algorithms take a key and can then 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 output.EVP_AEAD_CTX_init()
initializes the context ctx for the given AEAD
algorithm aead. The impl
argument must be NULL for the default
implementation; other values are currently not supported. Authentication
tags may be truncated by passing a tag length. A tag length of zero
indicates the default tag length should be used.
EVP_AEAD_CTX_cleanup()
frees any data allocated for the context ctx.
EVP_AEAD_CTX_open()
authenticates the input in and optional additional
data ad, decrypting the input and writing it as output
out. This function may be called (with the same
EVP_AEAD_CTX) concurrently with itself or with
EVP_AEAD_CTX_seal(). At most the number of input
bytes are written as output. In order to ensure success,
max_out_len should be at least the same as the input
length in_len. On successful return
out_len is set to the actual number of bytes written.
The length of the nonce specified with
nonce_len must be equal to the result of
EVP_AEAD_nonce_length for this AEAD.
EVP_AEAD_CTX_open() never results in partial output.
If max_out_len is insufficient, zero will be returned
and out_len will be set to zero. If the input and
output are aliased then out must be <=
in.
EVP_AEAD_CTX_seal()
encrypts and authenticates the input and authenticates any additional data
provided in ad, the encrypted input and authentication
tag being written as output out. This function may be
called (with the same EVP_AEAD_CTX) concurrently with
itself or with EVP_AEAD_CTX_open(). At most
max_out_len bytes are written as output and, in order
to ensure success, this value should be the 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 the nonce specified
with 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 and out_len will be set to zero. If
the input and output are aliased then out must be
<= in.
EVP_AEAD_key_length(),
EVP_AEAD_max_overhead(),
EVP_AEAD_max_tag_len(),
and
EVP_AEAD_nonce_length()
provide information about the AEAD algorithm aead.
All cipher algorithms have a fixed key length unless otherwise stated. The following ciphers are available:
EVP_aead_aes_128_gcm()- AES-128 in Galois Counter Mode.
EVP_aead_aes_256_gcm()- AES-256 in Galois Counter Mode.
EVP_aead_chacha20_poly1305()- ChaCha20 with a Poly1305 authenticator.
EVP_aead_xchacha20_poly1305()- XChaCha20 with a Poly1305 authenticator.
Where possible the EVP_AEAD interface to AEAD ciphers should be used in preference to the older EVP variants or to the low level interfaces. This is because the code then becomes transparent to the AEAD cipher used and much more flexible. It is also safer to use as it prevents common mistakes with the native APIs.
RETURN VALUES
EVP_AEAD_CTX_init(),
EVP_AEAD_CTX_open(), and
EVP_AEAD_CTX_seal() return 1 for success or zero for
failure.
EVP_AEAD_key_length() returns the length
of the key used for this AEAD.
EVP_AEAD_max_overhead() returns the
maximum number of additional bytes added by the act of sealing data with the
AEAD.
EVP_AEAD_max_tag_len() returns the maximum
tag length when using this AEAD. This is the largest value that can be
passed as a tag length to EVP_AEAD_CTX_init().
EVP_AEAD_nonce_length() returns the length
of the per-message nonce.
EXAMPLES
Encrypt a string using ChaCha20-Poly1305:
const EVP_AEAD *aead = EVP_aead_chacha20_poly1305();
static const unsigned char nonce[32] = {0};
size_t buf_len, nonce_len;
EVP_AEAD_CTX ctx;
EVP_AEAD_CTX_init(&ctx, aead, key32, EVP_AEAD_key_length(aead),
EVP_AEAD_DEFAULT_TAG_LENGTH, NULL);
nonce_len = EVP_AEAD_nonce_length(aead);
EVP_AEAD_CTX_seal(&ctx, out, &out_len, BUFSIZE, nonce,
nonce_len, in, in_len, NULL, 0);
EVP_AEAD_CTX_cleanup(&ctx);
SEE ALSO
STANDARDS
A. Langley and W. Chang, ChaCha20 and Poly1305 based Cipher Suites for TLS, draft-agl-tls-chacha20poly1305-04, November 2013.
Y. Nir and A. Langley, ChaCha20 and Poly1305 for IETF Protocols, RFC 7539, May 2015.
S. Arciszewski, XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305, draft-arciszewski-xchacha-02, October 2018.
HISTORY
AEAD is based on the implementation by Adam Langley for Chromium/BoringSSL and first appeared in OpenBSD 5.6.