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@

4 files changed, 285 insertions, 1 deletions

diff --git a/src/lib/libcrypto/doc/evp.pod b/src/lib/libcrypto/doc/evp.pod
index 57c761d01f..dfd96d3b98 100644
--- a/src/lib/libcrypto/doc/evp.pod
+++ b/src/lib/libcrypto/doc/evp.pod
@@ -25,6 +25,9 @@ functions.
 Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)>
 functions.  The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests.
 
+Authenticated encryption with additional data (AEAD) is available with
+the L<B<EVP_AEAD>I<...>|EVP_AEAD_CTX_init(3)> functions.
+
 The B<EVP_PKEY>I<...> functions provide a high level interface to
 asymmetric algorithms. To create a new EVP_PKEY see
 L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>. EVP_PKEYs can be associated
@@ -81,6 +84,7 @@ using the high level interface.
 
 L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
 L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
+L<EVP_AEAD_CTX_init(3)|EVP_AEAD_CTX_init(3)>,
 L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
 L<EVP_SealInit(3)|EVP_SealInit(3)>,
 L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>,
diff --git a/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3 b/src/lib/libcrypto/man/EVP_AEAD_CTX_init.3
new file mode 100644
index 0000000000..47531123b4
--- /dev/null
+++ b/src/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 <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: 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/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 1ebde6fc16..d896f436bc 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/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 <bsd.own.mk>           # 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/src/lib/libssl/src/doc/crypto/evp.pod b/src/lib/libssl/src/doc/crypto/evp.pod
index 57c761d01f..dfd96d3b98 100644
--- a/src/lib/libssl/src/doc/crypto/evp.pod
+++ b/src/lib/libssl/src/doc/crypto/evp.pod
@@ -25,6 +25,9 @@ functions.
 Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)>
 functions.  The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests.
 
+Authenticated encryption with additional data (AEAD) is available with
+the L<B<EVP_AEAD>I<...>|EVP_AEAD_CTX_init(3)> functions.
+
 The B<EVP_PKEY>I<...> functions provide a high level interface to
 asymmetric algorithms. To create a new EVP_PKEY see
 L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>. EVP_PKEYs can be associated
@@ -81,6 +84,7 @@ using the high level interface.
 
 L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
 L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
+L<EVP_AEAD_CTX_init(3)|EVP_AEAD_CTX_init(3)>,
 L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
 L<EVP_SealInit(3)|EVP_SealInit(3)>,
 L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>,