347 lines
8.4 KiB
Groff
347 lines
8.4 KiB
Groff
|
.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.10 2022/01/10 22:44:22 tb Exp $
|
||
|
|
.\"
|
||
|
|
.\" Copyright (c) 2014, Google Inc.
|
||
|
|
.\" Parts of the text were written by Adam Langley and David Benjamin.
|
||
|
|
.\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org>
|
||
|
|
.\"
|
||
|
|
.\" Permission to use, copy, modify, and/or distribute this software for any
|
||
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
||
|
|
.\" copyright notice and this permission notice appear in all copies.
|
||
|
|
.\"
|
||
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||
|
|
.\"
|
||
|
|
.Dd $Mdocdate: January 10 2022 $
|
||
|
|
.Dt EVP_AEAD_CTX_INIT 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm EVP_AEAD_CTX_new ,
|
||
|
|
.Nm EVP_AEAD_CTX_free ,
|
||
|
|
.Nm EVP_AEAD_CTX_init ,
|
||
|
|
.Nm EVP_AEAD_CTX_cleanup ,
|
||
|
|
.Nm EVP_AEAD_CTX_open ,
|
||
|
|
.Nm EVP_AEAD_CTX_seal ,
|
||
|
|
.Nm EVP_AEAD_key_length ,
|
||
|
|
.Nm EVP_AEAD_max_overhead ,
|
||
|
|
.Nm EVP_AEAD_max_tag_len ,
|
||
|
|
.Nm EVP_AEAD_nonce_length ,
|
||
|
|
.Nm EVP_aead_aes_128_gcm ,
|
||
|
|
.Nm EVP_aead_aes_256_gcm ,
|
||
|
|
.Nm EVP_aead_chacha20_poly1305 ,
|
||
|
|
.Nm EVP_aead_xchacha20_poly1305
|
||
|
|
.Nd authenticated encryption with additional data
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In openssl/evp.h
|
||
|
|
.Ft EVP_AEAD_CTX *
|
||
|
|
.Fn EVP_AEAD_CTX_new void
|
||
|
|
.Ft void
|
||
|
|
.Fo EVP_AEAD_CTX_free
|
||
|
|
.Fa "EVP_AEAD_CTX *ctx"
|
||
|
|
.Fc
|
||
|
|
.Ft int
|
||
|
|
.Fo EVP_AEAD_CTX_init
|
||
|
|
.Fa "EVP_AEAD_CTX *ctx"
|
||
|
|
.Fa "const EVP_AEAD *aead"
|
||
|
|
.Fa "const unsigned char *key"
|
||
|
|
.Fa "size_t key_len"
|
||
|
|
.Fa "size_t tag_len"
|
||
|
|
.Fa "ENGINE *impl"
|
||
|
|
.Fc
|
||
|
|
.Ft void
|
||
|
|
.Fo EVP_AEAD_CTX_cleanup
|
||
|
|
.Fa "EVP_AEAD_CTX *ctx"
|
||
|
|
.Fc
|
||
|
|
.Ft int
|
||
|
|
.Fo EVP_AEAD_CTX_open
|
||
|
|
.Fa "const EVP_AEAD_CTX *ctx"
|
||
|
|
.Fa "unsigned char *out"
|
||
|
|
.Fa "size_t *out_len"
|
||
|
|
.Fa "size_t max_out_len"
|
||
|
|
.Fa "const unsigned char *nonce"
|
||
|
|
.Fa "size_t nonce_len"
|
||
|
|
.Fa "const unsigned char *in"
|
||
|
|
.Fa "size_t in_len"
|
||
|
|
.Fa "const unsigned char *ad"
|
||
|
|
.Fa "size_t ad_len"
|
||
|
|
.Fc
|
||
|
|
.Ft int
|
||
|
|
.Fo EVP_AEAD_CTX_seal
|
||
|
|
.Fa "const EVP_AEAD_CTX *ctx"
|
||
|
|
.Fa "unsigned char *out"
|
||
|
|
.Fa "size_t *out_len"
|
||
|
|
.Fa "size_t max_out_len"
|
||
|
|
.Fa "const unsigned char *nonce"
|
||
|
|
.Fa "size_t nonce_len"
|
||
|
|
.Fa "const unsigned char *in"
|
||
|
|
.Fa "size_t in_len"
|
||
|
|
.Fa "const unsigned char *ad"
|
||
|
|
.Fa "size_t ad_len"
|
||
|
|
.Fc
|
||
|
|
.Ft size_t
|
||
|
|
.Fo EVP_AEAD_key_length
|
||
|
|
.Fa "const EVP_AEAD *aead"
|
||
|
|
.Fc
|
||
|
|
.Ft size_t
|
||
|
|
.Fo EVP_AEAD_max_overhead
|
||
|
|
.Fa "const EVP_AEAD *aead"
|
||
|
|
.Fc
|
||
|
|
.Ft size_t
|
||
|
|
.Fo EVP_AEAD_max_tag_len
|
||
|
|
.Fa "const EVP_AEAD *aead"
|
||
|
|
.Fc
|
||
|
|
.Ft size_t
|
||
|
|
.Fo EVP_AEAD_nonce_length
|
||
|
|
.Fa "const EVP_AEAD *aead"
|
||
|
|
.Fc
|
||
|
|
.Ft const EVP_AEAD *
|
||
|
|
.Fo EVP_aead_aes_128_gcm
|
||
|
|
.Fa void
|
||
|
|
.Fc
|
||
|
|
.Ft const EVP_AEAD *
|
||
|
|
.Fo EVP_aead_aes_256_gcm
|
||
|
|
.Fa void
|
||
|
|
.Fc
|
||
|
|
.Ft const EVP_AEAD *
|
||
|
|
.Fo EVP_aead_chacha20_poly1305
|
||
|
|
.Fa void
|
||
|
|
.Fc
|
||
|
|
.Ft const EVP_AEAD *
|
||
|
|
.Fo EVP_aead_xchacha20_poly1305
|
||
|
|
.Fa void
|
||
|
|
.Fc
|
||
|
|
.Sh 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.
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_new
|
||
|
|
allocates a new context for use with
|
||
|
|
.Fn EVP_AEAD_CTX_init .
|
||
|
|
It can be cleaned up for reuse with
|
||
|
|
.Fn EVP_AEAD_CTX_cleanup
|
||
|
|
and must be freed with
|
||
|
|
.Fn EVP_AEAD_CTX_free .
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_free
|
||
|
|
cleans up
|
||
|
|
.Fa ctx
|
||
|
|
and frees the space allocated to it.
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_init
|
||
|
|
initializes the context
|
||
|
|
.Fa ctx
|
||
|
|
for the given AEAD algorithm
|
||
|
|
.Fa aead .
|
||
|
|
The
|
||
|
|
.Fa impl
|
||
|
|
argument must be
|
||
|
|
.Dv 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.
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_cleanup
|
||
|
|
frees any data allocated for the context
|
||
|
|
.Fa ctx .
|
||
|
|
After
|
||
|
|
.Fn EVP_AEAD_CTX_cleanup ,
|
||
|
|
.Fa ctx
|
||
|
|
is in the same state as after
|
||
|
|
.Fn EVP_AEAD_CTX_new .
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_open
|
||
|
|
authenticates the input
|
||
|
|
.Fa in
|
||
|
|
and optional additional data
|
||
|
|
.Fa ad ,
|
||
|
|
decrypting the input and writing it as output
|
||
|
|
.Fa out .
|
||
|
|
This function may be called (with the same
|
||
|
|
.Vt EVP_AEAD_CTX )
|
||
|
|
concurrently with itself or with
|
||
|
|
.Fn EVP_AEAD_CTX_seal .
|
||
|
|
At most the number of input bytes are written as output.
|
||
|
|
In order to ensure success,
|
||
|
|
.Fa max_out_len
|
||
|
|
should be at least the same as the input length
|
||
|
|
.Fa in_len .
|
||
|
|
On successful return
|
||
|
|
.Fa out_len
|
||
|
|
is set to the actual number of bytes written.
|
||
|
|
The length of the
|
||
|
|
.Fa nonce
|
||
|
|
specified with
|
||
|
|
.Fa nonce_len
|
||
|
|
must be equal to the result of EVP_AEAD_nonce_length for this AEAD.
|
||
|
|
.Fn EVP_AEAD_CTX_open
|
||
|
|
never results in partial output.
|
||
|
|
If
|
||
|
|
.Fa max_out_len
|
||
|
|
is insufficient, zero will be returned and
|
||
|
|
.Fa out_len
|
||
|
|
will be set to zero.
|
||
|
|
If the input and output are aliased then
|
||
|
|
.Fa out
|
||
|
|
must be <=
|
||
|
|
.Fa in .
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_seal
|
||
|
|
encrypts and authenticates the input and authenticates any additional
|
||
|
|
data provided in
|
||
|
|
.Fa ad ,
|
||
|
|
the encrypted input and authentication tag being written as output
|
||
|
|
.Fa out .
|
||
|
|
This function may be called (with the same
|
||
|
|
.Vt EVP_AEAD_CTX )
|
||
|
|
concurrently with itself or with
|
||
|
|
.Fn EVP_AEAD_CTX_open .
|
||
|
|
At most
|
||
|
|
.Fa max_out_len
|
||
|
|
bytes are written as output and, in order to ensure success, this value
|
||
|
|
should be the
|
||
|
|
.Fa in_len
|
||
|
|
plus the result of
|
||
|
|
.Fn EVP_AEAD_max_overhead .
|
||
|
|
On successful return,
|
||
|
|
.Fa out_len
|
||
|
|
is set to the actual number of bytes written.
|
||
|
|
The length of the
|
||
|
|
.Fa nonce
|
||
|
|
specified with
|
||
|
|
.Fa nonce_len
|
||
|
|
must be equal to the result of
|
||
|
|
.Fn EVP_AEAD_nonce_length
|
||
|
|
for this AEAD.
|
||
|
|
.Fn EVP_AEAD_CTX_seal
|
||
|
|
never results in a partial output.
|
||
|
|
If
|
||
|
|
.Fa max_out_len
|
||
|
|
is insufficient, zero will be returned and
|
||
|
|
.Fa out_len
|
||
|
|
will be set to zero.
|
||
|
|
If the input and output are aliased then
|
||
|
|
.Fa out
|
||
|
|
must be <=
|
||
|
|
.Fa in .
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_key_length ,
|
||
|
|
.Fn EVP_AEAD_max_overhead ,
|
||
|
|
.Fn EVP_AEAD_max_tag_len ,
|
||
|
|
and
|
||
|
|
.Fn EVP_AEAD_nonce_length
|
||
|
|
provide information about the AEAD algorithm
|
||
|
|
.Fa aead .
|
||
|
|
.Pp
|
||
|
|
All cipher algorithms have a fixed key length unless otherwise stated.
|
||
|
|
The following ciphers are available:
|
||
|
|
.Bl -tag -width Ds -offset indent
|
||
|
|
.It Fn EVP_aead_aes_128_gcm
|
||
|
|
AES-128 in Galois Counter Mode.
|
||
|
|
.It Fn EVP_aead_aes_256_gcm
|
||
|
|
AES-256 in Galois Counter Mode.
|
||
|
|
.It Fn EVP_aead_chacha20_poly1305
|
||
|
|
ChaCha20 with a Poly1305 authenticator.
|
||
|
|
.It Fn EVP_aead_xchacha20_poly1305
|
||
|
|
XChaCha20 with a Poly1305 authenticator.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Where possible the
|
||
|
|
.Sy EVP_AEAD
|
||
|
|
interface to AEAD ciphers should be used in preference to the older
|
||
|
|
.Sy 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.
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
.Fn EVP_AEAD_CTX_new
|
||
|
|
returns the new
|
||
|
|
.Vt EVP_AEAD_CTX
|
||
|
|
object or
|
||
|
|
.Dv NULL
|
||
|
|
on failure.
|
||
|
|
.Fn EVP_AEAD_CTX_init ,
|
||
|
|
.Fn EVP_AEAD_CTX_open ,
|
||
|
|
and
|
||
|
|
.Fn EVP_AEAD_CTX_seal
|
||
|
|
return 1 for success or zero for failure.
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_key_length
|
||
|
|
returns the length of the key used for this AEAD.
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_max_overhead
|
||
|
|
returns the maximum number of additional bytes added by the act of
|
||
|
|
sealing data with the AEAD.
|
||
|
|
.Pp
|
||
|
|
.Fn 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
|
||
|
|
.Fn EVP_AEAD_CTX_init .
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_nonce_length
|
||
|
|
returns the length of the per-message nonce.
|
||
|
|
.Sh EXAMPLES
|
||
|
|
Encrypt a string using ChaCha20-Poly1305:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
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;
|
||
|
|
|
||
|
|
ctx = EVP_AEAD_CTX_new();
|
||
|
|
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_free(ctx);
|
||
|
|
.Ed
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr evp 3 ,
|
||
|
|
.Xr EVP_EncryptInit 3
|
||
|
|
.Sh STANDARDS
|
||
|
|
.Rs
|
||
|
|
.%A A. Langley
|
||
|
|
.%A W. Chang
|
||
|
|
.%D November 2013
|
||
|
|
.%R draft-agl-tls-chacha20poly1305-04
|
||
|
|
.%T ChaCha20 and Poly1305 based Cipher Suites for TLS
|
||
|
|
.Re
|
||
|
|
.Pp
|
||
|
|
.Rs
|
||
|
|
.%A Y. Nir
|
||
|
|
.%A A. Langley
|
||
|
|
.%D May 2015
|
||
|
|
.%R RFC 7539
|
||
|
|
.%T ChaCha20 and Poly1305 for IETF Protocols
|
||
|
|
.Re
|
||
|
|
.Pp
|
||
|
|
.Rs
|
||
|
|
.%A S. Arciszewski
|
||
|
|
.%D October 2018
|
||
|
|
.%R draft-arciszewski-xchacha-02
|
||
|
|
.%T XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305
|
||
|
|
.Re
|
||
|
|
.Sh HISTORY
|
||
|
|
AEAD is based on the implementation by
|
||
|
|
.An Adam Langley
|
||
|
|
for Chromium/BoringSSL and first appeared in
|
||
|
|
.Ox 5.6 .
|
||
|
|
.Pp
|
||
|
|
.Fn EVP_AEAD_CTX_new
|
||
|
|
and
|
||
|
|
.Fn EVP_AEAD_CTX_free
|
||
|
|
first appeared in
|
||
|
|
.Ox 7.1 .
|