new manual page ChaCha(3);

OK tb@

3 files changed, 257 insertions, 2 deletions

diff --git a/lib/libcrypto/man/ChaCha.3 b/lib/libcrypto/man/ChaCha.3
new file mode 100644
index 00000000000..909d8ca77dd
--- /dev/null
+++ b/lib/libcrypto/man/ChaCha.3
@@ -0,0 +1,253 @@
+.\" $OpenBSD: ChaCha.3,v 1.1 2020/06/24 17:00:38 schwarze Exp $
+.\"
+.\" Copyright (c) 2020 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.
+.\"
+.Dd $Mdocdate: June 24 2020 $
+.Dt CHACHA 3
+.Os
+.Sh NAME
+.Nm ChaCha_set_key ,
+.Nm ChaCha_set_iv ,
+.Nm ChaCha ,
+.Nm CRYPTO_chacha_20 ,
+.Nm CRYPTO_hchacha_20 ,
+.Nm CRYPTO_xchacha_20
+.Nd ChaCha20 stream cipher
+.Sh SYNOPSIS
+.In openssl/chacha.h
+.Ft void
+.Fo ChaCha_set_key
+.Fa "ChaCha_ctx *ctx"
+.Fa "const unsigned char *key"
+.Fa "unsigned int keybits"
+.Fc
+.Ft void
+.Fo ChaCha_set_iv
+.Fa "ChaCha_ctx *ctx"
+.Fa "const unsigned char *iv"
+.Fa "const unsigned char *counter"
+.Fc
+.Ft void
+.Fo ChaCha
+.Fa "ChaCha_ctx *ctx"
+.Fa "unsigned char *out"
+.Fa "const unsigned char *in"
+.Fa "size_t len"
+.Fc
+.Ft void
+.Fo CRYPTO_chacha_20
+.Fa "unsigned char *out"
+.Fa "const unsigned char *in"
+.Fa "size_t len"
+.Fa "const unsigned char key[32]"
+.Fa "const unsigned char iv[8]"
+.Fa "uint64_t counter"
+.Fc
+.Ft void
+.Fo CRYPTO_hchacha_20
+.Fa "unsigned char out[32]"
+.Fa "const unsigned char key[32]"
+.Fa "const unsigned char iv[16]"
+.Fc
+.Ft void
+.Fo CRYPTO_xchacha_20
+.Fa "unsigned char *out"
+.Fa "const unsigned char *in"
+.Fa "size_t len"
+.Fa "const unsigned char key[32]"
+.Fa "const unsigned char iv[24]"
+.Fc
+.Sh DESCRIPTION
+These functions provide a low-level implementation
+of the ChaCha stream cipher with 256 and 128 bit keys.
+The number of rounds is hardcoded to 20;
+variants with 8 or 12 rounds are not supported.
+.Pp
+Instead of using these functions directly,
+application programs normally use the more portable
+.Xr EVP_chacha20 3
+high-level interface.
+.Pp
+The ChaCha state is contained in the
+.Vt ChaCha_ctx
+structure and consists of sixteen 32-bit unsigned integers.
+.Pp
+For the recommended value of 256
+.Fa keybits ,
+.Fn ChaCha_set_key
+copies 32 bytes (256 bits) from
+.Fa key
+to the middle eight integers of the ChaCha state,
+using little endian order for each integer.
+For the alternative value of 128
+.Fa keybits ,
+only 16 bytes (128 bits) are copied from
+.Fa key
+to the ChaCha state, but they are copied twice,
+once to the second quarter and once to the third quarter.
+The first quarter of the ChaCha state is set to four constant integers;
+these constants differ depending on whether
+.Fa keybits
+is 128 or 256.
+The last quarter of the ChaCha state remains unchanged.
+.Pp
+.Fn ChaCha_set_iv
+copies eight bytes (64 bits) from
+.Fa counter
+and eight bytes (64 bits) from
+.Fa iv
+to the last quarter of the ChaCha state, the counter to the first
+two integers and the initialization vector to the last two integers,
+again in little endian order.
+If
+.Fa counter
+is
+.Dv NULL ,
+the two respective integers are set to 0 instead.
+The first three quarters of the ChaCha state remain unchanged.
+.Pp
+.Fn ChaCha
+encrypts
+.Fa len
+bytes of data from
+.Fa in
+to
+.Fa out
+using the
+.Fa ctx
+that was previously set up with
+.Fn ChaCha_set_key
+and
+.Fn ChaCha_set_iv .
+Providing an
+.Fa out
+buffer of at least
+.Fa len
+bytes is the responsibility of the caller.
+This function can be called multiple times in a row with varying
+.Fa len
+arguments.
+The
+.Fa len
+does not need to be a multiple of 64.
+.Pp
+.Fn CRYPTO_chacha_20
+encrypts
+.Fa len
+bytes of data from
+.Fa in
+to
+.Fa out
+in a one-shot operation, using the given
+.Fa key
+and
+.Fa iv
+as described for
+.Fn ChaCha_set_key
+and
+.Fn ChaCha_set_iv
+and copying the less significant half of
+.Fa counter
+to the first counter integer in the initial ChaCha state
+and the more significant half to the second integer.
+Providing an
+.Fa out
+buffer of at least
+.Fa len
+bytes is again the responsibility of the caller.
+The maximum supported value for
+.Fa len
+is 2^32 \- 1.
+.Pp
+XChaCha is a variant of ChaCha designed to support longer nonces,
+just like XSalsa20 is a variant of Salsa20 supporting longer nonces.
+.Pp
+.Fn CRYPTO_xchacha_20
+encrypts
+.Fa len
+bytes of data from
+.Fa in
+to
+.Fa out
+in a one-shot operation with the XChaCha algorithm, using the given
+.Fa key
+and
+.Fa iv .
+It is equivalent to
+.Fn CRYPTO_chacha_20
+with the last third of
+.Fa iv ,
+a
+.Fa counter
+of 0, and a key generated with
+.Fn CRYPTO_hchacha_20
+from the first two thirds of
+.Fa iv .
+.Sh SEE ALSO
+.Xr crypto 3 ,
+.Xr EVP_chacha20 3
+.Rs
+.%A Daniel J. Bernstein
+.%T ChaCha, a variant of Salsa20
+.%U http://cr.yp.to/chacha/chacha-20080128.pdf
+.%C Chicago
+.%D January 28, 2008
+.Re
+.Rs
+.%A Daniel J. Bernstein
+.%T Extending the Salsa20 nonce
+.%U https://cr.yp.to/snuffle/xsalsa-20110204.pdf
+.%C Chicago
+.%D August 22, 2017
+.Re
+.Sh STANDARDS
+RFC 8439: ChaCha20 and Poly1305 for IETF Protocols
+.Pp
+Note that the standard specifies
+a 32 bit counter and a 96 bit initialization vector whereas
+this implementation follows Bernstein's original specification
+and uses a 64 bit counter and a 64 bit initialization vector.
+.Pp
+These functions are specific to LibreSSL and not provided by OpenSSL.
+BoringSSL does provide
+.Fn CRYPTO_chacha_20 ,
+but with an incompatible interface, taking a 96 bit
+.Fa iv
+and a 32 bit
+.Fa counter .
+.Sh HISTORY
+.Fn ChaCha_set_key ,
+.Fn ChaCha_set_iv ,
+.Fn ChaCha ,
+and
+.Fn CRYPTO_chacha_20
+first appeared in
+.Ox 5.6 .
+.\" Committed on May 1, 2014.
+.\" BoringSSL added CRYPTO_chacha_20 on June 20, 2014.
+.Pp
+.Fn CRYPTO_hchacha_20
+and
+.Fn CRYPTO_xchacha_20
+first appeared in
+.Ox 6.5 .
+.Sh AUTHORS
+.An -nosplit
+This implementation was written by
+.An Daniel J. Bernstein Aq Mt djb@cr.yp.to .
+The API layer was added by
+.An Joel Sing Aq Mt jsing@openbsd.org
+for ChaCha, and for XChaCha by
+.An David Gwynne Aq Mt dlg@openbsd.org .
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index de6e446f2f5..8114f5b96ba 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.169 2020/06/24 16:06:26 schwarze Exp $
+# $OpenBSD: Makefile,v 1.170 2020/06/24 17:00:38 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -92,6 +92,7 @@ MAN=	\
 	CRYPTO_lock.3 \
 	CRYPTO_memcmp.3 \
 	CRYPTO_set_ex_data.3 \
+	ChaCha.3 \
 	DES_set_key.3 \
 	DH_generate_key.3 \
 	DH_generate_parameters.3 \
diff --git a/lib/libcrypto/man/crypto.3 b/lib/libcrypto/man/crypto.3
index 9f29698e80c..6e98f643de5 100644
--- a/lib/libcrypto/man/crypto.3
+++ b/lib/libcrypto/man/crypto.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: crypto.3,v 1.24 2020/06/24 16:06:27 schwarze Exp $
+.\"	$OpenBSD: crypto.3,v 1.25 2020/06/24 17:00:38 schwarze Exp $
 .\"	OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org> and
@@ -69,6 +69,7 @@ are provided by the generic interface
 Low-level stand-alone interfaces include
 .Xr AES_encrypt 3 ,
 .Xr BF_set_key 3 ,
+.Xr ChaCha 3 ,
 .Xr DES_set_key 3 ,
 and
 .Xr RC4 3 .