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