1.\" $OpenBSD: EVP_chacha20.3,v 1.8 2024/12/09 11:55:52 schwarze Exp $ 2.\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Ronald Tse <ronald.tse@ribose.com>. 22.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: December 9 2024 $ 69.Dt EVP_CHACHA20 3 70.Os 71.Sh NAME 72.Nm EVP_chacha20 , 73.Nm EVP_chacha20_poly1305 74.Nd ChaCha20 stream cipher for EVP 75.Sh SYNOPSIS 76.In openssl/evp.h 77.Ft const EVP_CIPHER * 78.Fn EVP_chacha20 void 79.Ft const EVP_CIPHER * 80.Fn EVP_chacha20_poly1305 void 81.Sh DESCRIPTION 82.Fn EVP_chacha20 83provides the ChaCha20 stream cipher in the EVP framework. 84.Xr EVP_EncryptInit_ex 3 , 85.Xr EVP_DecryptInit_ex 3 , 86and 87.Xr EVP_CipherInit_ex 3 88take a 89.Fa key 90argument of 32 bytes = 256 bits and an 91.Fa iv 92argument of 16 bytes = 128 bits, internally using 93.Xr ChaCha_set_key 3 94and 95.Xr ChaCha_set_iv 3 . 96The lower 8 bytes = 64 bits of 97.Fa iv 98are used as counter and the remaining 8 bytes are used as 99the initialization vector of 100.Xr ChaCha_set_iv 3 . 101.Xr EVP_EncryptUpdate 3 , 102.Xr EVP_EncryptFinal_ex 3 , 103.Xr EVP_DecryptUpdate 3 , 104and 105.Xr EVP_DecryptFinal_ex 3 106internally use 107.Xr ChaCha 3 108to perform encryption and decryption. 109.Xr EVP_CIPHER_CTX_ctrl 3 110always fails for 111.Fa ctx 112objects created from 113.Fn EVP_chacha20 . 114.Pp 115.Fn EVP_chacha20_poly1305 116provides authenticated encryption with ChaCha20-Poly1305. 117Unless compatibility with other implementations 118like OpenSSL or BoringSSL is required, using 119.Xr EVP_AEAD_CTX_init 3 120with 121.Xr EVP_aead_chacha20_poly1305 3 122is recommended instead because the code then becomes transparent 123to the AEAD cipher used, more flexible, and less error prone. 124.Pp 125With 126.Fn EVP_chacha20_poly1305 , 127.Xr EVP_EncryptInit_ex 3 , 128.Xr EVP_DecryptInit_ex 3 , 129and 130.Xr EVP_CipherInit_ex 3 131take a 132.Fa key 133argument of 32 bytes = 256 bits and an 134.Fa iv 135argument of 12 bytes = 96 bits. 136This supports additional authenticated data (AAD) and produces a 128-bit 137authentication tag. 138The constant 139.Dv EVP_CHACHAPOLY_TLS_TAG_LEN 140specifies the length of the authentication tag in bytes and has a value of 16. 141.Pp 142The following 143.Fa type 144arguments are supported for 145.Xr EVP_CIPHER_CTX_ctrl 3 : 146.Bl -tag -width Ds 147.It Dv EVP_CTRL_AEAD_GET_TAG 148Copy the number of bytes indicated by the 149.Fa arg 150argument from the tag to the location indicated by the 151.Fa ptr 152argument; 153to be called after 154.Xr EVP_EncryptFinal_ex 3 . 155This control operation fails if the 156.Fa ctx 157is not configured for encryption or if 158.Fa arg 159is less than 1 or greater than 16. 160.It Dv EVP_CTRL_AEAD_SET_TAG 161Copy the number of bytes indicated by the 162.Fa arg 163argument from the location indicated by the 164.Fa ptr 165argument and designate them as the expected tag length and tag, 166causing subsequent 167.Xr EVP_DecryptFinal_ex 3 168to fail if the tag calculated during decryption does not match. 169It is strongly recommended to specify 170.Fa arg 171as exactly 16. 172Otherwise, only the initial part of the tag may be compared 173and mismatches near the end of the tag may get silently ignored. 174This control operation fails if the 175.Fa ctx 176is configured for encryption or if 177.Fa arg 178is less than 1 or greater than 16. 179If the 180.Fa ptr 181argument is a 182.Dv NULL 183pointer, this control operation succeeds without having any effect. 184.It Dv EVP_CTRL_AEAD_SET_IV_FIXED 185Set the initialization vector by reading the 12 bytes pointed to by the 186.Fa ptr 187argument, independently of 188.Xr EVP_EncryptInit_ex 3 , 189.Xr EVP_DecryptInit_ex 3 , 190and 191.Xr EVP_CipherInit_ex 3 . 192This control operation fails if the 193.Fa arg 194argument is not exactly 12. 195.It Dv EVP_CTRL_AEAD_SET_IVLEN 196Instruct subsequent 197.Xr EVP_EncryptInit_ex 3 , 198.Xr EVP_DecryptInit_ex 3 , 199or 200.Xr EVP_CipherInit_ex 3 201to expect an 202.Fa iv 203argument shorter than the default of 12 bytes; the 204.Fa arg 205argument specifies the number of bytes to be used. 206The initialization functions will only read 207the specified smaller number of bytes from 208.Fa iv 209and internally zero-pad them on the left. 210Using this is not recommended because it is likely more fragile 211and less often tested than the equivalent method of simply providing 212a full-sized 213.Fa iv . 214This control operation fails if 215.Fa arg 216is less than 1 or greater than 16. 217.It Dv EVP_CTRL_INIT 218Set the length of the initialization vector to the default value 219of 12 bytes and clear the Poly1305 internal state. 220The application program usually does not need to invoke this control 221operation manually because it is automatically called internally by 222.Xr EVP_EncryptInit_ex 3 , 223.Xr EVP_DecryptInit_ex 3 , 224and 225.Xr EVP_CipherInit_ex 3 . 226.El 227.Sh RETURN VALUES 228.Fn EVP_chacha20 229and 230.Fn EVP_chacha20_poly1305 231return pointers to static 232.Vt EVP_CIPHER 233objects that contain the implementations of the symmetric cipher. 234.Pp 235If 236.Fa ctx 237was created from 238.Fn EVP_chacha20 239or 240.Fn EVP_chacha20_poly1305 , 241.Xr EVP_CIPHER_CTX_ctrl 3 242returns 1 for success or 0 for failure. 243.Sh SEE ALSO 244.Xr ChaCha 3 , 245.Xr evp 3 , 246.Xr EVP_aead_chacha20_poly1305 3 , 247.Xr EVP_CIPHER_meth_new 3 , 248.Xr EVP_EncryptInit 3 249.Sh STANDARDS 250.Rs 251.%A A. Langley 252.%A W. Chang 253.%A N. Mavrogiannopoulos 254.%A J. Strombergson 255.%A S. Josefsson 256.%D June 2016 257.%R RFC 7905 258.%T ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS) 259.Re 260.Sh HISTORY 261.Fn EVP_chacha20 262first appeared in 263.Ox 5.6 . 264.Pp 265.Fn EVP_chacha20_poly1305 266first appeared in OpenSSL 1.1.0 267.\" OpenSSL commit bd989745 Dec 9 21:30:56 2015 +0100 Andy Polyakov 268and has been available since 269.Ox 7.2 . 270.Sh CAVEATS 271The original publications and code by 272.An Adam Langley 273used a modified AEAD construction that is incompatible with the common 274style used by AEAD in TLS and incompatible with RFC 7905: 275.Pp 276.Rs 277.%A A. Langley 278.%A W. Chang 279.%D November 2013 280.%R draft-agl-tls-chacha20poly1305-04 281.%T ChaCha20 and Poly1305 based Cipher Suites for TLS 282.Re 283.Pp 284.Rs 285.%A Y. Nir 286.%A A. Langley 287.%D May 2018 288.%R RFC 8439 289.%T ChaCha20 and Poly1305 for IETF Protocols 290.Re 291.Pp 292In particular, the original version used a nonce of 8 instead of 12 bytes. 293