1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncheryCMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, 6*e7be843bSPierre ProncheryCMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final, 7*e7be843bSPierre ProncheryCMAC_resume 8*e7be843bSPierre Pronchery- create cipher-based message authentication codes 9*e7be843bSPierre Pronchery 10*e7be843bSPierre Pronchery=head1 SYNOPSIS 11*e7be843bSPierre Pronchery 12*e7be843bSPierre Pronchery #include <openssl/cmac.h> 13*e7be843bSPierre Pronchery 14*e7be843bSPierre ProncheryThe following functions have been deprecated since OpenSSL 3.0, and can be 15*e7be843bSPierre Proncherydisabled entirely by defining B<OPENSSL_API_COMPAT> with a suitable version 16*e7be843bSPierre Proncheryvalue, see L<openssl_user_macros(7)>. 17*e7be843bSPierre Pronchery 18*e7be843bSPierre Pronchery typedef struct CMAC_CTX_st CMAC_CTX; 19*e7be843bSPierre Pronchery 20*e7be843bSPierre Pronchery CMAC_CTX *CMAC_CTX_new(void); 21*e7be843bSPierre Pronchery void CMAC_CTX_cleanup(CMAC_CTX *ctx); 22*e7be843bSPierre Pronchery void CMAC_CTX_free(CMAC_CTX *ctx); 23*e7be843bSPierre Pronchery EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx); 24*e7be843bSPierre Pronchery int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in); 25*e7be843bSPierre Pronchery int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen, 26*e7be843bSPierre Pronchery const EVP_CIPHER *cipher, ENGINE *impl); 27*e7be843bSPierre Pronchery int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen); 28*e7be843bSPierre Pronchery int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen); 29*e7be843bSPierre Pronchery int CMAC_resume(CMAC_CTX *ctx); 30*e7be843bSPierre Pronchery 31*e7be843bSPierre Pronchery=head1 DESCRIPTION 32*e7be843bSPierre Pronchery 33*e7be843bSPierre ProncheryThe low-level MAC functions documented on this page are deprecated. 34*e7be843bSPierre ProncheryApplications should use the new L<EVP_MAC(3)> interface. 35*e7be843bSPierre ProncherySpecifically, utilize the following functions for MAC operations: 36*e7be843bSPierre Pronchery 37*e7be843bSPierre Pronchery=over 4 38*e7be843bSPierre Pronchery 39*e7be843bSPierre Pronchery=item L<EVP_MAC_CTX_new(3)> to create a new MAC context. 40*e7be843bSPierre Pronchery 41*e7be843bSPierre Pronchery=item L<EVP_MAC_CTX_free(3)> to free the MAC context. 42*e7be843bSPierre Pronchery 43*e7be843bSPierre Pronchery=item L<EVP_MAC_init(3)> to initialize the MAC context. 44*e7be843bSPierre Pronchery 45*e7be843bSPierre Pronchery=item L<EVP_MAC_update(3)> to update the MAC with data. 46*e7be843bSPierre Pronchery 47*e7be843bSPierre Pronchery=item L<EVP_MAC_final(3)> to finalize the MAC and retrieve the output. 48*e7be843bSPierre Pronchery 49*e7be843bSPierre Pronchery=back 50*e7be843bSPierre Pronchery 51*e7be843bSPierre ProncheryAlternatively, for a single-step MAC computation, use the L<EVP_Q_mac(3)> 52*e7be843bSPierre Proncheryfunction. 53*e7be843bSPierre Pronchery 54*e7be843bSPierre ProncheryThe B<CMAC_CTX> type is a structure used for the provision of CMAC 55*e7be843bSPierre Pronchery(Cipher-based Message Authentication Code) operations. 56*e7be843bSPierre Pronchery 57*e7be843bSPierre ProncheryCMAC_CTX_new() creates a new B<CMAC_CTX> structure and returns a pointer to it. 58*e7be843bSPierre Pronchery 59*e7be843bSPierre ProncheryCMAC_CTX_cleanup() resets the B<CMAC_CTX> structure, clearing any internal data 60*e7be843bSPierre Proncherybut not freeing the structure itself. 61*e7be843bSPierre Pronchery 62*e7be843bSPierre ProncheryCMAC_CTX_free() frees the B<CMAC_CTX> structure and any associated resources. 63*e7be843bSPierre ProncheryIf the argument is NULL, no action is taken. 64*e7be843bSPierre Pronchery 65*e7be843bSPierre ProncheryCMAC_CTX_get0_cipher_ctx() returns a pointer to the internal B<EVP_CIPHER_CTX> 66*e7be843bSPierre Proncherystructure within the B<CMAC_CTX>. 67*e7be843bSPierre Pronchery 68*e7be843bSPierre ProncheryCMAC_CTX_copy() copies the state from one B<CMAC_CTX> structure to another. 69*e7be843bSPierre Pronchery 70*e7be843bSPierre ProncheryCMAC_Init() initializes the B<CMAC_CTX> structure for a new CMAC calculation 71*e7be843bSPierre Proncherywith the specified key, key length, and cipher type. 72*e7be843bSPierre ProncheryOptionally, an B<ENGINE> can be provided. 73*e7be843bSPierre Pronchery 74*e7be843bSPierre ProncheryCMAC_Update() processes data to be included in the CMAC calculation. 75*e7be843bSPierre ProncheryThis function can be called multiple times to update the context with 76*e7be843bSPierre Proncheryadditional data. 77*e7be843bSPierre Pronchery 78*e7be843bSPierre ProncheryCMAC_Final() finalizes the CMAC calculation and retrieves the resulting 79*e7be843bSPierre ProncheryMAC value. The output is stored in the provided buffer, and the length is 80*e7be843bSPierre Proncherystored in the variable pointed to by I<poutlen>. To determine the required 81*e7be843bSPierre Proncherybuffer size, call with I<out> set to NULL, which stores only the length in 82*e7be843bSPierre ProncheryI<poutlen>. Allocate a buffer of this size and call CMAC_Final() again with 83*e7be843bSPierre Proncherythe allocated buffer to retrieve the MAC. 84*e7be843bSPierre Pronchery 85*e7be843bSPierre ProncheryCMAC_resume() resumes a previously finalized CMAC calculation, allowing 86*e7be843bSPierre Proncheryadditional data to be processed and a new MAC to be generated. 87*e7be843bSPierre Pronchery 88*e7be843bSPierre Pronchery=head1 RETURN VALUES 89*e7be843bSPierre Pronchery 90*e7be843bSPierre ProncheryCMAC_CTX_new() returns a pointer to a new B<CMAC_CTX> structure or NULL if 91*e7be843bSPierre Proncheryan error occurs. 92*e7be843bSPierre Pronchery 93*e7be843bSPierre ProncheryCMAC_CTX_get0_cipher_ctx() returns a pointer to the internal 94*e7be843bSPierre ProncheryB<EVP_CIPHER_CTX> structure, or NULL if an error occurs. 95*e7be843bSPierre Pronchery 96*e7be843bSPierre ProncheryCMAC_CTX_copy(), CMAC_Init(), CMAC_Update(), CMAC_Final() and CMAC_resume() 97*e7be843bSPierre Proncheryreturn 1 for success or 0 if an error occurs. 98*e7be843bSPierre Pronchery 99*e7be843bSPierre Pronchery=head1 HISTORY 100*e7be843bSPierre Pronchery 101*e7be843bSPierre ProncheryAll functions described here were deprecated in OpenSSL 3.0. For replacements, 102*e7be843bSPierre Proncherysee L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>, 103*e7be843bSPierre ProncheryL<EVP_MAC_update(3)>, and L<EVP_MAC_final(3)>. 104*e7be843bSPierre Pronchery 105*e7be843bSPierre Pronchery=head1 COPYRIGHT 106*e7be843bSPierre Pronchery 107*e7be843bSPierre ProncheryCopyright 2024 The OpenSSL Project Authors. All Rights Reserved. 108*e7be843bSPierre Pronchery 109*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 110*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 111*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 112*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 113*e7be843bSPierre Pronchery 114*e7be843bSPierre Pronchery=cut 115