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.

4 files changed, 357 insertions, 75 deletions

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 <ronald.tse@ribose.com>
@@ -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 <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.
+.\"
+.\" This file is a derived work containing a few sentences
+.\" written by Dr. Stephen Henson <steve@openssl.org>
+.\" 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 <bsd.own.mk>
 
@@ -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 \