From 974f913127f5a5b8d5d71617271097553f0d0200 Mon Sep 17 00:00:00 2001 From: reyk Date: Wed, 14 Oct 2015 07:41:28 +0000 Subject: [PATCH] Add EVP_AEAD_CTX_init(3) manpage to document the new(ish) AEAD API. The "authenticated encryption with additional data" API is used for ciphers like AES-GCM or ChaCha20-Poly1305. The manpage is a beginning and certainly needs more work, especially improvements in the EXAMPLES section. Based on agl's source code comments. Converted from pod to mandoc by schwarze@ OK schwarze@ jsing@ --- lib/libcrypto/doc/evp.pod | 4 + lib/libcrypto/man/EVP_AEAD_CTX_init.3 | 275 ++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- lib/libssl/src/doc/crypto/evp.pod | 4 + 4 files changed, 285 insertions(+), 1 deletion(-) create mode 100644 lib/libcrypto/man/EVP_AEAD_CTX_init.3 diff --git a/lib/libcrypto/doc/evp.pod b/lib/libcrypto/doc/evp.pod index 57c761d01f3..dfd96d3b984 100644 --- a/lib/libcrypto/doc/evp.pod +++ b/lib/libcrypto/doc/evp.pod @@ -25,6 +25,9 @@ functions. Symmetric encryption is available with the LI<...>|EVP_EncryptInit(3)> functions. The LI<...>|EVP_DigestInit(3)> functions provide message digests. +Authenticated encryption with additional data (AEAD) is available with +the LI<...>|EVP_AEAD_CTX_init(3)> functions. + The BI<...> functions provide a high level interface to asymmetric algorithms. To create a new EVP_PKEY see L. EVP_PKEYs can be associated @@ -81,6 +84,7 @@ using the high level interface. L, L, +L, L, L, L, diff --git a/lib/libcrypto/man/EVP_AEAD_CTX_init.3 b/lib/libcrypto/man/EVP_AEAD_CTX_init.3 new file mode 100644 index 00000000000..47531123b41 --- /dev/null +++ b/lib/libcrypto/man/EVP_AEAD_CTX_init.3 @@ -0,0 +1,275 @@ +.\" $OpenBSD: EVP_AEAD_CTX_init.3,v 1.1 2015/10/14 07:41:28 reyk Exp $ +.\" +.\" Copyright (c) 2014, Google Inc. +.\" Parts of the text were written by Adam Langley and David Benjamin. +.\" Copyright (c) 2015 Reyk Floeter +.\" +.\" 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: October 14 2015 $ +.Dt EVP_AEAD_CTX_INIT 3 +.Os +.Sh NAME +.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 +.Nd authenticated encryption with additional data +.Sh SYNOPSIS +.In openssl/evp.h +.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 +.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_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 . +.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 +.Xr EVP_AEAD_overhead 3 . +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. +.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_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 +.\" XXX +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); +.Ed +.Sh SEE ALSO +.Xr evp 3 +.Sh HISTORY +AEAD is based on the implementation by Adam Langley for +Chromium/BoringSSL and first appeared in +.Ox 5.6 . diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 1ebde6fc169..d896f436bc1 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.24 2015/09/17 14:43:23 bcook Exp $ +# $OpenBSD: Makefile,v 1.25 2015/10/14 07:41:28 reyk Exp $ .include # for NOMAN @@ -52,6 +52,7 @@ MAN= \ BN_swap.3 \ BN_zero.3 \ BUF_MEM_new.3 \ + EVP_AEAD_CTX_init.3 \ GENMAN= \ CONF_modules_free.3 \ diff --git a/lib/libssl/src/doc/crypto/evp.pod b/lib/libssl/src/doc/crypto/evp.pod index 57c761d01f3..dfd96d3b984 100644 --- a/lib/libssl/src/doc/crypto/evp.pod +++ b/lib/libssl/src/doc/crypto/evp.pod @@ -25,6 +25,9 @@ functions. Symmetric encryption is available with the LI<...>|EVP_EncryptInit(3)> functions. The LI<...>|EVP_DigestInit(3)> functions provide message digests. +Authenticated encryption with additional data (AEAD) is available with +the LI<...>|EVP_AEAD_CTX_init(3)> functions. + The BI<...> functions provide a high level interface to asymmetric algorithms. To create a new EVP_PKEY see L. EVP_PKEYs can be associated @@ -81,6 +84,7 @@ using the high level interface. L, L, +L, L, L, L, -- 2.20.1