Add documentation for deprecated CMAC_CTX functions

Fixes #5539: Create a new manual page `CMAC_CTX.pod` documenting the deprecated `CMAC_CTX` functions and add the necessary build dependencies. This page includes function descriptions, usage details, and replacement suggestions with the `EVP_MAC` interface.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24814)

diff --git a/doc/build.info b/doc/build.info
index 5227a10c1ad10bc6724f15c8f1c14b614f8f745a..b2689b7acebf1245bc61273e56572d4738007b5f 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -783,6 +783,10 @@ DEPEND[html/man3/BUF_MEM_new.html]=man3/BUF_MEM_new.pod
 GENERATE[html/man3/BUF_MEM_new.html]=man3/BUF_MEM_new.pod
 DEPEND[man/man3/BUF_MEM_new.3]=man3/BUF_MEM_new.pod
 GENERATE[man/man3/BUF_MEM_new.3]=man3/BUF_MEM_new.pod
+DEPEND[html/man3/CMAC_CTX.html]=man3/CMAC_CTX.pod
+GENERATE[html/man3/CMAC_CTX.html]=man3/CMAC_CTX.pod
+DEPEND[man/man3/CMAC_CTX.3]=man3/CMAC_CTX.pod
+GENERATE[man/man3/CMAC_CTX.3]=man3/CMAC_CTX.pod
 DEPEND[html/man3/CMS_EncryptedData_decrypt.html]=man3/CMS_EncryptedData_decrypt.pod
 GENERATE[html/man3/CMS_EncryptedData_decrypt.html]=man3/CMS_EncryptedData_decrypt.pod
 DEPEND[man/man3/CMS_EncryptedData_decrypt.3]=man3/CMS_EncryptedData_decrypt.pod
@@ -3179,6 +3183,7 @@ html/man3/BN_set_bit.html \
 html/man3/BN_swap.html \
 html/man3/BN_zero.html \
 html/man3/BUF_MEM_new.html \
+html/man3/CMAC_CTX.html \
 html/man3/CMS_EncryptedData_decrypt.html \
 html/man3/CMS_EncryptedData_encrypt.html \
 html/man3/CMS_EnvelopedData_create.html \
@@ -3837,6 +3842,7 @@ man/man3/BN_set_bit.3 \
 man/man3/BN_swap.3 \
 man/man3/BN_zero.3 \
 man/man3/BUF_MEM_new.3 \
+man/man3/CMAC_CTX.3 \
 man/man3/CMS_EncryptedData_decrypt.3 \
 man/man3/CMS_EncryptedData_encrypt.3 \
 man/man3/CMS_EnvelopedData_create.3 \

diff --git a/doc/man3/CMAC_CTX.pod b/doc/man3/CMAC_CTX.pod
new file mode 100644 (file)
index 0000000..fae4fd1
--- /dev/null
+++ b/doc/man3/CMAC_CTX.pod
@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free,
+CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final,
+CMAC_resume
+- create cipher-based message authentication codes
+
+=head1 SYNOPSIS
+
+ #include <openssl/cmac.h>
+
+The following functions have been deprecated since OpenSSL 3.0, and can be
+disabled entirely by defining B<OPENSSL_API_COMPAT> with a suitable version
+value, see L<openssl_user_macros(7)>.
+
+ typedef struct CMAC_CTX_st CMAC_CTX;
+
+ CMAC_CTX *CMAC_CTX_new(void);
+ void CMAC_CTX_cleanup(CMAC_CTX *ctx);
+ void CMAC_CTX_free(CMAC_CTX *ctx);
+ EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);
+ int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);
+ int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,
+               const EVP_CIPHER *cipher, ENGINE *impl);
+ int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen);
+ int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen);
+ int CMAC_resume(CMAC_CTX *ctx);
+
+=head1 DESCRIPTION
+
+The low-level MAC functions documented on this page are deprecated.
+Applications should use the new L<EVP_MAC(3)> interface.
+Specifically, utilize the following functions for MAC operations:
+
+=over 4
+
+=item L<EVP_MAC_CTX_new(3)> to create a new MAC context.
+
+=item L<EVP_MAC_CTX_free(3)> to free the MAC context.
+
+=item L<EVP_MAC_init(3)> to initialize the MAC context.
+
+=item L<EVP_MAC_update(3)> to update the MAC with data.
+
+=item L<EVP_MAC_final(3)> to finalize the MAC and retrieve the output.
+
+=back
+
+Alternatively, for a single-step MAC computation, use the L<EVP_Q_mac(3)>
+function.
+
+The B<CMAC_CTX> type is a structure used for the provision of CMAC
+(Cipher-based Message Authentication Code) operations.
+
+CMAC_CTX_new() creates a new B<CMAC_CTX> structure and returns a pointer to it.
+
+CMAC_CTX_cleanup() resets the B<CMAC_CTX> structure, clearing any internal data
+but not freeing the structure itself.
+
+CMAC_CTX_free() frees the B<CMAC_CTX> structure and any associated resources.
+If the argument is NULL, no action is taken.
+
+CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal B<EVP_CIPHER_CTX>
+structure within the B<CMAC_CTX>.
+
+CMAC_CTX_copy() copies the state from one B<CMAC_CTX> structure to another.
+
+CMAC_Init() initializes the B<CMAC_CTX> structure for a new CMAC calculation
+with the specified key, key length, and cipher type.
+Optionally, an B<ENGINE> can be provided.
+
+CMAC_Update() processes data to be included in the CMAC calculation.
+This function can be called multiple times to update the context with
+additional data.
+
+CMAC_Final() finalizes the CMAC calculation and retrieves the resulting
+MAC value. The output is stored in the provided buffer, and the length is
+stored in the variable pointed to by I<poutlen>. To determine the required
+buffer size, call with I<out> set to NULL, which stores only the length in
+I<poutlen>. Allocate a buffer of this size and call CMAC_Final() again with
+the allocated buffer to retrieve the MAC.
+
+CMAC_resume() resumes a previously finalized CMAC calculation, allowing
+additional data to be processed and a new MAC to be generated.
+
+=head1 RETURN VALUES
+
+CMAC_CTX_new() returns a pointer to a new B<CMAC_CTX> structure or NULL if
+an error occurs.
+
+CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal
+B<EVP_CIPHER_CTX> structure, or NULL if an error occurs.
+
+CMAC_CTX_copy(), CMAC_Init(), CMAC_Update(), CMAC_Final() and CMAC_resume()
+return 1 for success or 0 if an error occurs.
+
+=head1 HISTORY
+
+All functions described here were deprecated in OpenSSL 3.0. For replacements,
+see L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
+L<EVP_MAC_update(3)>, and L<EVP_MAC_final(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 08231eddce41d93e1ba25d2f9694987b188b4e89..b7d5091b319123a95901e057add1d3041cb16627 100644 (file)
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -282,15 +282,6 @@ CAST_ofb64_encrypt(3)
 CAST_set_key(3)
 CBIGNUM_it(3)
 CERTIFICATEPOLICIES_it(3)
-CMAC_CTX_cleanup(3)
-CMAC_CTX_copy(3)
-CMAC_CTX_free(3)
-CMAC_CTX_get0_cipher_ctx(3)
-CMAC_CTX_new(3)
-CMAC_Final(3)
-CMAC_Init(3)
-CMAC_Update(3)
-CMAC_resume(3)
 CMS_ContentInfo_it(3)
 CMS_EncryptedData_set1_key(3)
 CMS_ReceiptRequest_it(3)

diff --git a/util/other.syms b/util/other.syms
index 3902945ac1ab13b19c619d6acff138568543c812..094a365a21d998ed684e657f482646ff59944765 100644 (file)
--- a/util/other.syms
+++ b/util/other.syms
@@ -833,3 +833,4 @@ EVP_PKEY_id                             define
 EVP_PKEY_base_id                        define
 SSL_set_retry_verify                    define
 TS_VERIFY_CTX                           define
+CMAC_CTX                                define