From 0f29c352ca0efe3c3a1facb4e84a69fb6c5bd49f Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 20 Dec 2024 01:54:03 +0000 Subject: Move the horrific EVP_aes_128_ccm(3) API out of the important, algorithm-independent EVP_EncryptInit(3) manual as another step in making the latter leaner and more palatable. As a side benefit, the new EVP_aes_128_ccm(3) manual page may provide a better fighting chance to programmers who see themselves forced to support CCM for whatever reason. It documents the mandatory, but so far undocumented EVP_CTRL_CCM_GET_TAG control command and makes the description of the three EVP_CTRL_CCM_SET_* control commands and the numerous related quirks more precise. --- src/lib/libcrypto/man/EVP_EncryptInit.3 | 54 +---- src/lib/libcrypto/man/EVP_aes_128_cbc.3 | 27 +-- src/lib/libcrypto/man/EVP_aes_128_ccm.3 | 348 ++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 3 +- 4 files changed, 357 insertions(+), 75 deletions(-) create mode 100644 src/lib/libcrypto/man/EVP_aes_128_ccm.3 (limited to 'src/lib/libcrypto') diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3 index 8f977b7a2a..7765be2ca6 100644 --- a/src/lib/libcrypto/man/EVP_EncryptInit.3 +++ b/src/lib/libcrypto/man/EVP_EncryptInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_EncryptInit.3,v 1.55 2024/12/17 18:11:44 schwarze Exp $ +.\" $OpenBSD: EVP_EncryptInit.3,v 1.56 2024/12/20 01:54:03 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 @@ -69,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: December 17 2024 $ +.Dd $Mdocdate: December 20 2024 $ .Dt EVP_ENCRYPTINIT 3 .Os .Sh NAME @@ -600,6 +600,7 @@ Some algorithms are documented in separate manual pages: .Bl -column "EVP_camellia_128_cbc(3)" "block size" -compact .It manual page Ta block size Ta Fa key No size Pq in bits .It Xr EVP_aes_128_cbc 3 Ta 128 Ta 128, 192, 256 +.It Xr EVP_aes_128_ccm 3 Ta 128 Ta 128, 192, 256 .It Xr EVP_aes_128_gcm 3 Ta 128 Ta 128, 192, 256 .It Xr EVP_camellia_128_cbc 3 Ta 128 Ta 128, 192, 256 .It Xr EVP_chacha20 3 Ta stream Ta 256 @@ -608,54 +609,6 @@ Some algorithms are documented in separate manual pages: .It Xr EVP_rc4 3 Ta stream Ta variable, default 128 .It Xr EVP_sm4_cbc 3 Ta 128 Ta 128 .El -.Ss CCM mode -The behaviour of CCM mode ciphers is similar to GCM mode, but with -a few additional requirements and different ctrl values. -.Pp -Like GCM mode any additional authenticated data (AAD) is passed -by calling -.Fn EVP_CipherUpdate , -.Fn EVP_EncryptUpdate , -or -.Fn EVP_DecryptUpdate -with the output parameter -.Fa out -set to -.Dv NULL . -Additionally, the total -plaintext or ciphertext length MUST be passed to -.Fn EVP_CipherUpdate , -.Fn EVP_EncryptUpdate , -or -.Fn EVP_DecryptUpdate -with the output and input -parameters -.Pq Fa in No and Fa out -set to -.Dv NULL -and the length passed in the -.Fa in_len -parameter. -.Pp -The following ctrls are supported in CCM mode: -.Bl -tag -width Ds -.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_TAG taglen tag -This call is made to set the expected CCM tag value when decrypting or -the length of the tag (with the -.Fa tag -parameter set to -.Dv NULL ) -when encrypting. -The tag length is often referred to as M. -If not set, a default value is used (12 for AES). -.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_L ivlen NULL -Sets the CCM L value. -If not set, a default is used (8 for AES). -.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_IVLEN ivlen NULL -Sets the CCM nonce (IV) length: this call can only be made before -specifying a nonce value. -The nonce length is given by 15 - L so it is 7 by default for AES. -.El .Sh EXAMPLES Encrypt a string using blowfish: .Bd -literal -offset 3n @@ -770,6 +723,7 @@ do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) .Xr evp 3 , .Xr EVP_AEAD_CTX_init 3 , .Xr EVP_aes_128_cbc 3 , +.Xr EVP_aes_128_ccm 3 , .Xr EVP_aes_128_gcm 3 , .Xr EVP_camellia_128_cbc 3 , .Xr EVP_chacha20 3 , diff --git a/src/lib/libcrypto/man/EVP_aes_128_cbc.3 b/src/lib/libcrypto/man/EVP_aes_128_cbc.3 index cbb68e1543..46e3ef0bdc 100644 --- a/src/lib/libcrypto/man/EVP_aes_128_cbc.3 +++ b/src/lib/libcrypto/man/EVP_aes_128_cbc.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.7 2024/12/17 18:11:44 schwarze Exp $ +.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.8 2024/12/20 01:54:03 schwarze Exp $ .\" selective merge up to: OpenSSL 7c6d372a Nov 20 13:20:01 2018 +0000 .\" .\" This file was written by Ronald Tse @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 17 2024 $ +.Dd $Mdocdate: December 20 2024 $ .Dt EVP_AES_128_CBC 3 .Os .Sh NAME @@ -78,9 +78,6 @@ .Nm EVP_aes_256_ofb , .Nm EVP_aes_128_cbc_hmac_sha1 , .Nm EVP_aes_256_cbc_hmac_sha1 , -.Nm EVP_aes_128_ccm , -.Nm EVP_aes_192_ccm , -.Nm EVP_aes_256_ccm , .Nm EVP_aes_128_wrap , .Nm EVP_aes_192_wrap , .Nm EVP_aes_256_wrap , @@ -142,12 +139,6 @@ .Ft const EVP_CIPHER * .Fn EVP_aes_256_cbc_hmac_sha1 void .Ft const EVP_CIPHER * -.Fn EVP_aes_128_ccm void -.Ft const EVP_CIPHER * -.Fn EVP_aes_192_ccm void -.Ft const EVP_CIPHER * -.Fn EVP_aes_256_ccm void -.Ft const EVP_CIPHER * .Fn EVP_aes_128_wrap void .Ft const EVP_CIPHER * .Fn EVP_aes_192_wrap void @@ -211,16 +202,6 @@ This is not intended for usage outside of TLS and requires calling of some undocumented control functions. These ciphers do not conform to the EVP AEAD interface. .Pp -.Fn EVP_aes_128_ccm , -.Fn EVP_aes_192_ccm , -and -.Fn EVP_aes_256_ccm -provide AES for 128, 192 and 256-bit keys in CBC-MAC Mode (CCM), respectively. -These ciphers require additional control operations to function -correctly; see -.Xr EVP_EncryptInit 3 -for details. -.Pp .Fn EVP_aes_128_wrap , .Fn EVP_aes_192_wrap , and @@ -271,6 +252,7 @@ structure that provides the implementation of the symmetric cipher. .Sh SEE ALSO .Xr AES_encrypt 3 , .Xr evp 3 , +.Xr EVP_aes_128_ccm 3 , .Xr EVP_aes_128_gcm 3 , .Xr EVP_EncryptInit 3 .Sh HISTORY @@ -308,9 +290,6 @@ first appeared in OpenSSL 0.9.7e and have been available since .Fn EVP_aes_256_ctr , .Fn EVP_aes_128_cbc_hmac_sha1 , .Fn EVP_aes_256_cbc_hmac_sha1 , -.Fn EVP_aes_128_ccm , -.Fn EVP_aes_192_ccm , -.Fn EVP_aes_256_ccm , .Fn EVP_aes_128_xts , and .Fn EVP_aes_256_xts diff --git a/src/lib/libcrypto/man/EVP_aes_128_ccm.3 b/src/lib/libcrypto/man/EVP_aes_128_ccm.3 new file mode 100644 index 0000000000..251e805fb0 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_aes_128_ccm.3 @@ -0,0 +1,348 @@ +.\" $OpenBSD: EVP_aes_128_ccm.3,v 1.1 2024/12/20 01:54:03 schwarze Exp $ +.\" full merge up to: +.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 +.\" OpenSSL EVP_aes.pod a1ec85c1 Apr 21 10:49:12 2020 +0100 +.\" +.\" Copyright (c) 2024 Ingo Schwarze +.\" +.\" 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. +.\" +.\" This file is a derived work containing a few sentences +.\" written by Dr. Stephen Henson +.\" covered by the following license: +.\" +.\" Copyright (c) 2012 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: December 20 2024 $ +.Dt EVP_AES_128_CCM 3 +.Os +.Sh NAME +.Nm EVP_aes_128_ccm , +.Nm EVP_aes_192_ccm , +.Nm EVP_aes_256_ccm +.Nd EVP AES cipher in Counter with CBC-MAC mode +.Sh SYNOPSIS +.In openssl/evp.h +.Ft const EVP_CIPHER * +.Fn EVP_aes_128_ccm void +.Ft const EVP_CIPHER * +.Fn EVP_aes_192_ccm void +.Ft const EVP_CIPHER * +.Fn EVP_aes_256_ccm void +.Sh DESCRIPTION +.Fn EVP_aes_128_ccm , +.Fn EVP_aes_192_ccm , +and +.Fn EVP_aes_256_ccm +provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit +keys in Counter with CBC-MAC (CCM) mode in the +.Xr evp 3 +framework. +This mode supports Authenticated Encryption with Additional Data (AEAD) +and can be used in a number of communication protocols. +Longer keys make precomputation attacks harder at a cost in performance. +.Pp +For CCM mode ciphers, the behaviour of the EVP interface is subtly +altered and several additional +.Xr EVP_CIPHER_CTX_ctrl 3 +operations are required to function correctly. +.Pp +The less cumbersome and less error-prone +.Xr EVP_AEAD_CTX_new 3 +API does not provide CCM modes. +Some communication protocols support alternatives to CCM, which may +sometimes allow choosing the better API by avoiding CCM. +.Ss Configuration controls +The following two control commands can be issued as soon as +.Xr EVP_EncryptInit 3 +has been called with a CCM +.Fa type +and +.Dv NULL +pointers for +.Fa key +and +.Fa iv . +Both commands are optional and override each other. +If issued when a nonce is already set, they silently cause data corruption. +The +.Fa ptr +argument is ignored by both; passing +.Dv NULL +is recommended. +.Bl -tag -width Ds +.It Dv EVP_CTRL_CCM_SET_L +Set the size +.Ms L +of the length field to +.Fa arg +bytes and the size of the nonce to +.No 15 \- Fa arg +bytes. +By default, 8 bytes are used for the length field and 7 for the nonce. +Selecting a smaller size +.Ms L +for the length field reduces des maximum size of messages that can be sent, +but in return allows transmitting more messages with the same key. +It is an error to pass less than 2 or more than the default value of 8 for +.Fa arg . +.It Dv EVP_CTRL_CCM_SET_IVLEN +Set the size of the nonce to +.Fa arg +bytes and the size +.Ms L +of the length field to +.No 15 \- Fa arg +bytes. +By default, 7 bytes are used for the nonce and 8 for the length field. +Selecting a larger size of the nonce allows transmitting more messages with +the same key at the expense of reducing the maximum size for each message. +It is an error to pass more than 13 or less than the default value of 7 for +.Fa arg . +.El +.Pp +After optionally issuing one of the above control commands, +.Xr EVP_EncryptInit 3 +can be called a second time, this time passing +.Dv NULL +for the +.Fa type +argument, with the other two arguments pointing to the desired AES key +and to the desired nonce. +.Ss Encryption controls +.Bl -tag -width Ds +.It Dv EVP_CTRL_CCM_SET_TAG +If the +.Fa ptr +argument is +.Dv NULL , +set the tag length +.Ms M +to +.Fa arg +bytes. +The default value is 12. +Selecting a larger value makes tampering harder for an attacker, +at a small expense of making the messages slightly longer. +Selecting a smaller value is not recommended. +It is an error to pass an odd number for +.Fa arg , +or a number that is less than 4 or greater than 16, or to pass +.Dv NULL +to +.Fa ptr +when +.Fa ctx +is not configured for encrypting. +Issuing this control command when an encryption key is already configured +silently causes data corruption. +.It Dv EVP_CTRL_CCM_GET_TAG +Store the +.Fa arg +bytes of the tag in the memory provided by the caller starting at +.Fa ptr . +It is an error to issue this control command when +.Fa ctx +is not configured for encrypting, when no data was encrypted yet, with an +.Fa arg +that does not match the configured tag length +.Ms M , +or when the tag has already been retrieved earlier. +.El +.Pp +Before passing any plaintext data to +.Xr EVP_EncryptUpdate 3 , +call +.Xr EVP_EncryptUpdate 3 +with both +.Fa in +and +.Fa out +set to +.Dv NULL , +passing the total plaintext length in bytes as +.Fa in_len . +This constructs the first block to be digested with CBC-MAC +and copies the text length to +.Pf * Fa out_len . +It does not check whether +.Fa in_len +exceeds the limit of +.Pf 256\(ha Ms L ; +the most significant bytes of excessive values are silently discarded. +.Pp +It is an error if the +.Fa in_len +argument of the +.Xr EVP_EncryptUpdate 3 +call passing the plaintext data does not match the total length +specified ealier. +Splitting the text into more than one chunks to be passed in multiple calls of +.Xr EVP_EncryptUpdate 3 +is not supported for CCM. +.Pp +To specify any additional authenticated data (AAD), call +.Xr EVP_EncryptUpdate 3 +with the +.Fa out +argument set to +.Dv NULL . +.Ss Decryption controls +.Bl -tag -width Ds +.It Dv EVP_CTRL_CCM_SET_TAG +If the +.Fa ptr +argument is not +.Dv NULL , +copy +.Fa arg +bytes starting at +.Fa ptr +to the expected CCM tag value. +It is an error to pass an odd number for +.Fa arg , +or a number that is less than 4 or greater than 16. +Passing a number that does not correspond to the tag length +.Ms M +that was used for encryption does not raise an error right away, +but results in undefined behaviour +and typically causes subsequent authentication failure. +It is also an error to pass a +.Pf non- Dv NULL +.Fa ptr +when +.Fa ctx +is configured for encryption. +.El +.Pp +Before passing any ciphertext data to +.Xr EVP_DecryptUpdate 3 , +call +.Xr EVP_DecryptUpdate 3 +with both +.Fa in +and +.Fa out +set to +.Dv NULL , +passing the total ciphertext length in bytes as +.Fa in_len . +This constructs the first block to be digested with CBC-MAC +and copies the text length to +.Pf * Fa out_len . +It does not check whether +.Fa in_len +exceeds the limit of +.Pf 256\(ha Ms L ; +the most significant bytes of excessive values are silently discarded. +.Pp +It is an error if the +.Fa in_len +argument of the +.Xr EVP_DecryptUpdate 3 +call passing the ciphertext data does not match the total length +specified ealier. +Splitting the text into more than one chunks to be passed in multiple calls of +.Xr EVP_DecryptUpdate 3 +is not supported for CCM. +.Pp +To specify any additional authenticated data (AAD), call +.Xr EVP_DecryptUpdate 3 +with the +.Fa out +argument set to +.Dv NULL . +.Pp +If the return value of +.Xr EVP_DecryptUpdate 3 +does not indicate success, the authentication operation may have failed. +In that case, regard any output data as corrupted. +.Pp +Do not call +.Xr EVP_DecryptFinal 3 +when using CCM. +Such a call would not do anything useful, and it would fail +because the tag that was set with +.Dv EVP_CTRL_CCM_SET_TAG +was already consumed by +.Xr EVP_DecryptUpdate 3 . +.Sh RETURN VALUES +These functions return a static constant +.Vt EVP_CIPHER +structure that provides the implementation of the respective AEAD cipher mode. +.Sh SEE ALSO +.Xr AES_encrypt 3 , +.Xr evp 3 , +.Xr EVP_aes_128_cbc 3 , +.Xr EVP_aes_128_gcm 3 , +.Xr EVP_EncryptInit 3 +.Sh STANDARDS +.Rs +.%A Doug Whiting +.%A Russ Housley +.%A Niels Ferguson +.%T Counter with CBC-MAC (CCM) +.%R RFC 3610 +.%D September 2003 +.Re +.Sh HISTORY +.Fn EVP_aes_128_ccm , +.Fn EVP_aes_192_ccm , +and +.Fn EVP_aes_256_ccm +first appeared in OpenSSL 1.0.1 and have been available since +.Ox 5.3 . diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 137540c69a..9c05e70748 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.301 2024/12/17 18:11:44 schwarze Exp $ +# $OpenBSD: Makefile,v 1.302 2024/12/20 01:54:03 schwarze Exp $ .include @@ -196,6 +196,7 @@ MAN= \ EVP_SignInit.3 \ EVP_VerifyInit.3 \ EVP_aes_128_cbc.3 \ + EVP_aes_128_ccm.3 \ EVP_aes_128_gcm.3 \ EVP_camellia_128_cbc.3 \ EVP_chacha20.3 \ -- cgit v1.2.3-55-g6feb