diff --git a/doc/build.info b/doc/build.info index 5227a10c1ad10..b2689b7acebf1 100644 --- 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 index 0000000000000..fae4fd1516e17 --- /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 + +The following functions have been deprecated since OpenSSL 3.0, and can be +disabled entirely by defining B with a suitable version +value, see L. + + 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 interface. +Specifically, utilize the following functions for MAC operations: + +=over 4 + +=item L to create a new MAC context. + +=item L to free the MAC context. + +=item L to initialize the MAC context. + +=item L to update the MAC with data. + +=item L to finalize the MAC and retrieve the output. + +=back + +Alternatively, for a single-step MAC computation, use the L +function. + +The B type is a structure used for the provision of CMAC +(Cipher-based Message Authentication Code) operations. + +CMAC_CTX_new() creates a new B structure and returns a pointer to it. + +CMAC_CTX_cleanup() resets the B structure, clearing any internal data +but not freeing the structure itself. + +CMAC_CTX_free() frees the B 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 +structure within the B. + +CMAC_CTX_copy() copies the state from one B structure to another. + +CMAC_Init() initializes the B structure for a new CMAC calculation +with the specified key, key length, and cipher type. +Optionally, an B 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. To determine the required +buffer size, call with I set to NULL, which stores only the length in +I. 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 structure or NULL if +an error occurs. + +CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal +B 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, L, L, +L, and L. + +=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. + +=cut diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 08231eddce41d..b7d5091b31912 100644 --- 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 3902945ac1ab1..094a365a21d99 100644 --- 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