Describe more precisely how these functions are supposed to be used,

document the control operations supported by EVP_chacha20_poly1305(3),
and add the missing STANDARDS and HISTORY sections.

This replaces all text written by Matt Caswell and all text Copyrighted
by OpenSSL in the year 2019.

1 files changed, 185 insertions, 19 deletions

diff --git a/src/lib/libcrypto/man/EVP_chacha20.3 b/src/lib/libcrypto/man/EVP_chacha20.3
index 000ac88290..01193638b8 100644
--- a/src/lib/libcrypto/man/EVP_chacha20.3
+++ b/src/lib/libcrypto/man/EVP_chacha20.3
@@ -1,9 +1,25 @@
-.\" $OpenBSD: EVP_chacha20.3,v 1.1 2023/08/15 11:26:49 schwarze Exp $
+.\" $OpenBSD: EVP_chacha20.3,v 1.2 2023/08/16 13:47:18 schwarze Exp $
 .\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
 .\"
-.\" This file was written by Ronald Tse <ronald.tse@ribose.com>
-.\" and Matt Caswell <matt@openssl.org>.
-.\" Copyright (c) 2017, 2019 The OpenSSL Project.  All rights reserved.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and 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.
+.\"
+.\" The original file was written by Ronald Tse <ronald.tse@ribose.com>.
+.\" Copyright (c) 2017 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -49,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 15 2023 $
+.Dd $Mdocdate: August 16 2023 $
 .Dt EVP_CHACHA20 3
 .Os
 .Sh NAME
@@ -65,29 +81,179 @@
 .Sh DESCRIPTION
 .Fn EVP_chacha20
 provides the ChaCha20 stream cipher in the EVP framework.
-The key length is 256 bits, the IV is 128 bits long.
-The first 32 bits consists of a counter in little-endian order followed
-by a 96 bit nonce.
-For example a nonce of:
-.Pp
-000000000000000000000002
-.Pp
-With an initial counter of 42 (2a in hex) would be expressed as:
-.Pp
-2a000000000000000000000000000002
+.Xr EVP_EncryptInit_ex 3 ,
+.Xr EVP_DecryptInit_ex 3 ,
+and
+.Xr EVP_CipherInit_ex 3
+take a
+.Fa key
+argument of 32 bytes = 256 bits and an
+.Fa iv
+argument of 16 bytes = 128 bits, internally using
+.Xr ChaCha_set_key 3
+and
+.Xr ChaCha_set_iv 3 .
+Due to the symmetry of the internal cipher state, interpreting the
+.Fa iv
+argument as a 4 byte counter followed by a 12 byte nonce
+or interpreting it as an 8 byte counter followed by an 8 byte nonce
+is functionally equivalent.
+.Xr EVP_EncryptUpdate 3 ,
+.Xr EVP_EncryptFinal_ex 3 ,
+.Xr EVP_DecryptUpdate 3 ,
+and
+.Xr EVP_DecryptFinal_ex 3
+internally use
+.Xr ChaCha 3
+to perform encryption and decryption.
+.Xr EVP_CIPHER_CTX_ctrl 3
+always fails for
+.Fa ctx
+objects created from
+.Fn EVP_chacha20 .
 .Pp
 .Fn EVP_chacha20_poly1305
 provides authenticated encryption with ChaCha20-Poly1305.
-Like
-.Fn EVP_chacha20 ,
-the key is 256 bits and the IV is 96 bits.
+.Xr EVP_EncryptInit_ex 3 ,
+.Xr EVP_DecryptInit_ex 3 ,
+and
+.Xr EVP_CipherInit_ex 3
+take a
+.Fa key
+argument of 32 bytes = 256 bits and an
+.Fa iv
+argument of 12 bytes = 96 bits.
 This supports additional authenticated data (AAD) and produces a 128-bit
 authentication tag.
+.Pp
+The following
+.Fa type
+arguments are supported for
+.Xr EVP_CIPHER_CTX_ctrl 3 :
+.Bl -tag -width Ds
+.It Dv EVP_CTRL_AEAD_GET_TAG
+Copy the number of bytes indicated by the
+.Fa arg
+argument from the tag to the location indicated by the
+.Fa ptr
+argument;
+to be called after
+.Xr EVP_EncryptFinal_ex 3 .
+This control operation fails if the
+.Fa ctx
+is not configured for encryption or if
+.Fa arg
+is less than 1 or greater than 16.
+.It Dv EVP_CTRL_AEAD_SET_TAG
+Copy the number of bytes indicated by the
+.Fa arg
+argument from the location indicated by the
+.Fa ptr
+argument and designate them as the expected tag length and tag,
+causing subsequent
+.Xr EVP_DecryptFinal_ex 3
+to fail if the tag calculated during decryption does not match.
+It is strongly recommended to specify
+.Fa arg
+as exactly 16.
+Otherwise, only the initial part of the tag may be compared
+and mismatches near the end of the tag may get silently irgnored.
+This control operation fails if the
+.Fa ctx
+is configured for encryption or if
+.Fa arg
+is less than 1 or greater than 16.
+If the
+.Fa ptr
+argument is a
+.Dv NULL
+pointer, this control operation succeeds without having any effect.
+.It EVP_CTRL_AEAD_SET_IV_FIXED
+Set the initialization vector by reading the 12 bytes pointed to by the
+.Fa ptr
+argument, independently of
+.Xr EVP_EncryptInit_ex 3 ,
+.Xr EVP_DecryptInit_ex 3 ,
+and
+.Xr EVP_CipherInit_ex 3 .
+This control operation fails if the
+.Fa arg
+argument is not exactly 12.
+.It Dv EVP_CTRL_AEAD_SET_IVLEN
+Instruct subsequent
+.Xr EVP_EncryptInit_ex 3 ,
+.Xr EVP_DecryptInit_ex 3 ,
+or
+.Xr EVP_CipherInit_ex 3
+to expect an
+.Fa iv
+argument shorter than the default of 12 bytes; the
+.Fa arg
+argument specifies the number of bytes to be used.
+The initialization functions will only read
+the specified smaller number of bytes from
+.Fa iv
+and internally zero-pad them on the left.
+Using this is not recommended because it is likely more fragile
+and less often tested than the equivalent method of simply providing
+a full-sized
+.Fa iv .
+This control operation fails if
+.Fa arg
+is less than 1 or greater than 16.
+.It Dv EVP_CTRL_INIT
+Set the length of the initialization vector to the default value
+of 12 bytes and clear the Poly1305 internal state.
+The application program usually does not need to invoke this contol
+operation manually because it is automatically called internally by
+.Xr EVP_EncryptInit_ex 3 ,
+.Xr EVP_DecryptInit_ex 3 ,
+and
+.Xr EVP_CipherInit_ex 3 .
+.El
 .Sh RETURN VALUES
-These functions return return pointers to static
+.Fn EVP_chacha20
+and
+.Fn EVP_chacha20_poly1305
+return pointers to static
 .Vt EVP_CIPHER
 objects that contain the implementations of the symmetric cipher.
+.Pp
+If
+.Fa ctx
+was created from
+.Fn EVP_chacha20
+or
+.Fn EVP_chacha20_poly1305 ,
+.Xr EVP_CIPHER_CTX_ctrl 3
+returns 1 for success or 0 for failure.
 .Sh SEE ALSO
+.Xr ChaCha 3 ,
 .Xr evp 3 ,
+.Xr EVP_aead_chacha20_poly1305 3 ,
 .Xr EVP_CIPHER_meth_new 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
+.Sh HISTORY
+.Fn EVP_chacha20
+first appeared in
+.Ox 5.6 .
+.Pp
+.Fn EVP_chacha20_poly1305
+first appeared in OpenSSL 1.1.0 and has been available since
+.Ox 7.2 .