Debian Codegraph @

upstream/debian-unstable/man3/CMAC_CTX.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CMAC_CTX 3SSL"
58 .TH CMAC_CTX 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free,
65 CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final,
66 CMAC_resume
67 \&\- create cipher\-based message authentication codes
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/cmac.h>
72 .Ve
73 .PP
74 The following functions have been deprecated since OpenSSL 3.0, and can be
75 disabled entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version
76 value, see \fBopenssl_user_macros\fR\|(7).
77 .PP
78 .Vb 1
79 \& typedef struct CMAC_CTX_st CMAC_CTX;
80 \&
81 \& CMAC_CTX *CMAC_CTX_new(void);
82 \& void CMAC_CTX_cleanup(CMAC_CTX *ctx);
83 \& void CMAC_CTX_free(CMAC_CTX *ctx);
84 \& EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);
85 \& int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);
86 \& int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,
87 \& const EVP_CIPHER *cipher, ENGINE *impl);
88 \& int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen);
89 \& int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen);
90 \& int CMAC_resume(CMAC_CTX *ctx);
91 .Ve
92 .SH DESCRIPTION
93 .IX Header "DESCRIPTION"
94 The low-level MAC functions documented on this page are deprecated.
95 Applications should use the new \fBEVP_MAC\fR\|(3) interface.
96 Specifically, utilize the following functions for MAC operations:
97 .IP "\fBEVP_MAC_CTX_new\fR\|(3) to create a new MAC context." 4
98 .IX Item "EVP_MAC_CTX_new to create a new MAC context."
99 .PD 0
100 .IP "\fBEVP_MAC_CTX_free\fR\|(3) to free the MAC context." 4
101 .IX Item "EVP_MAC_CTX_free to free the MAC context."
102 .IP "\fBEVP_MAC_init\fR\|(3) to initialize the MAC context." 4
103 .IX Item "EVP_MAC_init to initialize the MAC context."
104 .IP "\fBEVP_MAC_update\fR\|(3) to update the MAC with data." 4
105 .IX Item "EVP_MAC_update to update the MAC with data."
106 .IP "\fBEVP_MAC_final\fR\|(3) to finalize the MAC and retrieve the output." 4
107 .IX Item "EVP_MAC_final to finalize the MAC and retrieve the output."
108 .PD
109 .PP
110 Alternatively, for a single-step MAC computation, use the \fBEVP_Q_mac\fR\|(3)
111 function.
112 .PP
113 The \fBCMAC_CTX\fR type is a structure used for the provision of CMAC
114 (Cipher-based Message Authentication Code) operations.
115 .PP
116 \&\fBCMAC_CTX_new()\fR creates a new \fBCMAC_CTX\fR structure and returns a pointer to it.
117 .PP
118 \&\fBCMAC_CTX_cleanup()\fR resets the \fBCMAC_CTX\fR structure, clearing any internal data
119 but not freeing the structure itself.
120 .PP
121 \&\fBCMAC_CTX_free()\fR frees the \fBCMAC_CTX\fR structure and any associated resources.
122 If the argument is NULL, no action is taken.
123 .PP
124 \&\fBCMAC_CTX_get0_cipher_ctx()\fR returns a pointer to the internal \fBEVP_CIPHER_CTX\fR
125 structure within the \fBCMAC_CTX\fR.
126 .PP
127 \&\fBCMAC_CTX_copy()\fR copies the state from one \fBCMAC_CTX\fR structure to another.
128 .PP
129 \&\fBCMAC_Init()\fR initializes the \fBCMAC_CTX\fR structure for a new CMAC calculation
130 with the specified key, key length, and cipher type.
131 Optionally, an \fBENGINE\fR can be provided.
132 .PP
133 \&\fBCMAC_Update()\fR processes data to be included in the CMAC calculation.
134 This function can be called multiple times to update the context with
135 additional data.
136 .PP
137 \&\fBCMAC_Final()\fR finalizes the CMAC calculation and retrieves the resulting
138 MAC value. The output is stored in the provided buffer, and the length is
139 stored in the variable pointed to by \fIpoutlen\fR. To determine the required
140 buffer size, call with \fIout\fR set to NULL, which stores only the length in
141 \&\fIpoutlen\fR. Allocate a buffer of this size and call \fBCMAC_Final()\fR again with
142 the allocated buffer to retrieve the MAC.
143 .PP
144 \&\fBCMAC_resume()\fR resumes a previously finalized CMAC calculation, allowing
145 additional data to be processed and a new MAC to be generated.
146 .SH "RETURN VALUES"
147 .IX Header "RETURN VALUES"
148 \&\fBCMAC_CTX_new()\fR returns a pointer to a new \fBCMAC_CTX\fR structure or NULL if
149 an error occurs.
150 .PP
151 \&\fBCMAC_CTX_get0_cipher_ctx()\fR returns a pointer to the internal
152 \&\fBEVP_CIPHER_CTX\fR structure, or NULL if an error occurs.
153 .PP
154 \&\fBCMAC_CTX_copy()\fR, \fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR and \fBCMAC_resume()\fR
155 return 1 for success or 0 if an error occurs.
156 .SH HISTORY
157 .IX Header "HISTORY"
158 All functions described here were deprecated in OpenSSL 3.0. For replacements,
159 see \fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3),
160 \&\fBEVP_MAC_update\fR\|(3), and \fBEVP_MAC_final\fR\|(3).
161 .SH COPYRIGHT
162 .IX Header "COPYRIGHT"
163 Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
164 .PP
165 Licensed under the Apache License 2.0 (the "License"). You may not use
166 this file except in compliance with the License. You can obtain a copy
167 in the file LICENSE in the source distribution or at
168 <https://www.openssl.org/source/license.html>.