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
—
authenticated encryption with additional data
#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);
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.
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.
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.
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);
evp(3)
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.
AEAD is based on the implementation by
Adam
Langley for Chromium/BoringSSL and first appeared in
OpenBSD 5.6.