From 5918e05ca5c911096da87392a2415a5f925fb6e1 Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 15 Aug 2023 11:26:49 +0000 Subject: [PATCH] Import the EVP_chacha20(3) manual page from the OpenSSL 1.1 branch, which is still under a free license, to work on it in the tree. The required content changes have not been done yet, i only tweaked the markup and wording so far. --- lib/libcrypto/man/EVP_EncryptInit.3 | 15 ++--- lib/libcrypto/man/EVP_chacha20.3 | 93 +++++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/evp.3 | 5 +- 4 files changed, 102 insertions(+), 14 deletions(-) create mode 100644 lib/libcrypto/man/EVP_chacha20.3 diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3 index b4fbfa37302..92680ae07f2 100644 --- a/lib/libcrypto/man/EVP_EncryptInit.3 +++ b/lib/libcrypto/man/EVP_EncryptInit.3 @@ -1,9 +1,7 @@ -.\" $OpenBSD: EVP_EncryptInit.3,v 1.44 2022/08/31 14:27:34 tb Exp $ +.\" $OpenBSD: EVP_EncryptInit.3,v 1.45 2023/08/15 11:26:49 schwarze Exp $ .\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 .\" EVP_bf_cbc.pod EVP_cast5_cbc.pod EVP_idea_cbc.pod EVP_rc2_cbc.pod .\" 7c6d372a Nov 20 13:20:01 2018 +0000 -.\" selective merge up to: OpenSSL 16cfc2c9 Mar 8 22:30:28 2018 +0100 -.\" EVP_chacha20.pod 8fa4d95e Oct 21 11:59:09 2017 +0900 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: @@ -71,7 +69,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 31 2022 $ +.Dd $Mdocdate: August 15 2023 $ .Dt EVP_ENCRYPTINIT 3 .Os .Sh NAME @@ -149,8 +147,7 @@ .Nm EVP_cast5_ecb , .Nm EVP_cast5_cfb64 , .Nm EVP_cast5_cfb , -.Nm EVP_cast5_ofb , -.Nm EVP_chacha20 +.Nm EVP_cast5_ofb .Nd EVP cipher routines .Sh SYNOPSIS .In openssl/evp.h @@ -1020,11 +1017,6 @@ This is a variable key length cipher. is an alias for .Fn EVP_cast5_cfb64 , implemented as a macro. -.It Fn EVP_chacha20 -The ChaCha20 stream cipher. -The key length is 256 bits. -The first 32 bits of the 128-bit IV are used as a counter, -and the remaining 96 bits as a nonce. .El .Pp See also @@ -1241,6 +1233,7 @@ do_crypt(FILE *in, FILE *out, int do_encrypt) .Xr EVP_AEAD_CTX_init 3 , .Xr EVP_aes_128_cbc 3 , .Xr EVP_camellia_128_cbc 3 , +.Xr EVP_chacha20 3 , .Xr EVP_des_cbc 3 , .Xr EVP_OpenInit 3 , .Xr EVP_rc4 3 , diff --git a/lib/libcrypto/man/EVP_chacha20.3 b/lib/libcrypto/man/EVP_chacha20.3 new file mode 100644 index 00000000000..000ac88290f --- /dev/null +++ b/lib/libcrypto/man/EVP_chacha20.3 @@ -0,0 +1,93 @@ +.\" $OpenBSD: EVP_chacha20.3,v 1.1 2023/08/15 11:26:49 schwarze Exp $ +.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 +.\" +.\" This file was written by Ronald Tse +.\" and Matt Caswell . +.\" Copyright (c) 2017, 2019 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 +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" 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 $ +.Dt EVP_CHACHA20 3 +.Os +.Sh NAME +.Nm EVP_chacha20 , +.Nm EVP_chacha20_poly1305 +.Nd ChaCha20 stream cipher for EVP +.Sh SYNOPSIS +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_chacha20 void +.Ft const EVP_CIPHER * +.Fn EVP_chacha20_poly1305 void +.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 +.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. +This supports additional authenticated data (AAD) and produces a 128-bit +authentication tag. +.Sh RETURN VALUES +These functions return return pointers to static +.Vt EVP_CIPHER +objects that contain the implementations of the symmetric cipher. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_CIPHER_meth_new 3 , +.Xr EVP_EncryptInit 3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 3e216956af2..9af9d28c4fa 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.260 2023/08/14 14:22:32 schwarze Exp $ +# $OpenBSD: Makefile,v 1.261 2023/08/15 11:26:49 schwarze Exp $ .include @@ -200,6 +200,7 @@ MAN= \ EVP_VerifyInit.3 \ EVP_aes_128_cbc.3 \ EVP_camellia_128_cbc.3 \ + EVP_chacha20.3 \ EVP_des_cbc.3 \ EVP_rc4.3 \ EVP_sha3_224.3 \ diff --git a/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3 index 5e09e4ad1c4..36f0e07003f 100644 --- a/lib/libcrypto/man/evp.3 +++ b/lib/libcrypto/man/evp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: evp.3,v 1.16 2023/08/14 14:46:40 schwarze Exp $ +.\" $OpenBSD: evp.3,v 1.17 2023/08/15 11:26:49 schwarze Exp $ .\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file was written by Ulf Moeller , @@ -51,7 +51,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 14 2023 $ +.Dd $Mdocdate: August 15 2023 $ .Dt EVP 3 .Os .Sh NAME @@ -197,6 +197,7 @@ operations are more efficient using the high-level interfaces. .Xr EVP_aes_128_cbc 3 , .Xr EVP_BytesToKey 3 , .Xr EVP_camellia_128_cbc 3 , +.Xr EVP_chacha20 3 , .Xr EVP_CIPHER_meth_new 3 , .Xr EVP_des_cbc 3 , .Xr EVP_DigestInit 3 , -- 2.20.1