5 life_cycle-mac - The MAC algorithm life-cycle
9 All message authentication codes (MACs)
10 go through a number of stages in their life-cycle:
16 This state represents the MAC before it has been allocated. It is the
17 starting state for any life-cycle transitions.
21 This state represents the MAC after it has been allocated.
25 This state represents the MAC when it is set up and capable of processing
30 This state represents the MAC when it is set up and capable of processing
31 additional input or generating output.
35 This state represents the MAC when it has generated output.
39 This state is entered when the MAC is freed. It is the terminal state
40 for all life-cycle transitions.
44 =head2 State Transition Diagram
46 The usual life-cycle of a MAC is illustrated:
64 | +-------------------+ |
66 | | EVP_MAC_update | EVP_MAC_init
68 EVP_MAC_init | +-------------------+ |
70 | +-------------------+
72 | | EVP_MAC_final | EVP_MAC_finalXOF
74 | +-------------------+
86 =for html <img src="img/mac.png">
88 =head2 Formal State Transitions
90 This section defines all of the legal state transitions.
91 This is the canonical list.
95 Function Call ------------- Current State -------------
96 start newed initialised updated finaled freed
98 EVP_MAC_init initialised initialised initialised initialised
99 EVP_MAC_update updated updated
100 EVP_MAC_final finaled
101 EVP_MAC_finalXOF finaled
102 EVP_MAC_CTX_free freed freed freed freed freed
103 EVP_MAC_CTX_get_params newed initialised updated
104 EVP_MAC_CTX_set_params newed initialised updated
105 EVP_MAC_CTX_gettable_params newed initialised updated
106 EVP_MAC_CTX_settable_params newed initialised updated
112 <table style="border:1px solid; border-collapse:collapse">
113 <tr><th style="border:1px solid" align="left">Function Call</th>
114 <th style="border:1px solid" colspan="6">Current State</th></tr>
115 <tr><th style="border:1px solid"></th>
116 <th style="border:1px solid" align="center">start</th>
117 <th style="border:1px solid" align="center">newed</th>
118 <th style="border:1px solid" align="center">initialised</th>
119 <th style="border:1px solid" align="center">updated</th>
120 <th style="border:1px solid" align="center">finaled</th>
121 <th style="border:1px solid" align="center">freed</th></tr>
122 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_new</th>
123 <td style="border:1px solid" align="center">newed</td>
124 <td style="border:1px solid" align="center"></td>
125 <td style="border:1px solid" align="center"></td>
126 <td style="border:1px solid" align="center"></td>
127 <td style="border:1px solid" align="center"></td>
128 <td style="border:1px solid" align="center"></td></tr>
129 <tr><th style="border:1px solid" align="left">EVP_MAC_init</th>
130 <td style="border:1px solid" align="center"></td>
131 <td style="border:1px solid" align="center">initialised</td>
132 <td style="border:1px solid" align="center">initialised</td>
133 <td style="border:1px solid" align="center">initialised</td>
134 <td style="border:1px solid" align="center">initialised</td>
135 <td style="border:1px solid" align="center"></td></tr>
136 <tr><th style="border:1px solid" align="left">EVP_MAC_update</th>
137 <td style="border:1px solid" align="center"></td>
138 <td style="border:1px solid" align="center"></td>
139 <td style="border:1px solid" align="center">updated</td>
140 <td style="border:1px solid" align="center">updated</td>
141 <td style="border:1px solid" align="center"></td>
142 <td style="border:1px solid" align="center"></td></tr>
143 <tr><th style="border:1px solid" align="left">EVP_MAC_final</th>
144 <td style="border:1px solid" align="center"></td>
145 <td style="border:1px solid" align="center"></td>
146 <td style="border:1px solid" align="center"></td>
147 <td style="border:1px solid" align="center">finaled</td>
148 <td style="border:1px solid" align="center"></td>
149 <td style="border:1px solid" align="center"></td></tr>
150 <tr><th style="border:1px solid" align="left">EVP_MAC_finalXOF</th>
151 <td style="border:1px solid" align="center"></td>
152 <td style="border:1px solid" align="center"></td>
153 <td style="border:1px solid" align="center"></td>
154 <td style="border:1px solid" align="center">finaled</td>
155 <td style="border:1px solid" align="center"></td>
156 <td style="border:1px solid" align="center"></td></tr>
157 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_free</th>
158 <td style="border:1px solid" align="center">freed</td>
159 <td style="border:1px solid" align="center">freed</td>
160 <td style="border:1px solid" align="center">freed</td>
161 <td style="border:1px solid" align="center">freed</td>
162 <td style="border:1px solid" align="center">freed</td>
163 <td style="border:1px solid" align="center"></td></tr>
164 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_get_params</th>
165 <td style="border:1px solid" align="center"></td>
166 <td style="border:1px solid" align="center">newed</td>
167 <td style="border:1px solid" align="center">initialised</td>
168 <td style="border:1px solid" align="center">updated</td>
169 <td style="border:1px solid" align="center"></td>
170 <td style="border:1px solid" align="center"></td></tr>
171 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_set_params</th>
172 <td style="border:1px solid" align="center"></td>
173 <td style="border:1px solid" align="center">newed</td>
174 <td style="border:1px solid" align="center">initialised</td>
175 <td style="border:1px solid" align="center">updated</td>
176 <td style="border:1px solid" align="center"></td>
177 <td style="border:1px solid" align="center"></td></tr>
178 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_gettable_params</th>
179 <td style="border:1px solid" align="center"></td>
180 <td style="border:1px solid" align="center">newed</td>
181 <td style="border:1px solid" align="center">initialised</td>
182 <td style="border:1px solid" align="center">updated</td>
183 <td style="border:1px solid" align="center"></td>
184 <td style="border:1px solid" align="center"></td></tr>
185 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_settable_params</th>
186 <td style="border:1px solid" align="center"></td>
187 <td style="border:1px solid" align="center">newed</td>
188 <td style="border:1px solid" align="center">initialised</td>
189 <td style="border:1px solid" align="center">updated</td>
190 <td style="border:1px solid" align="center"></td>
191 <td style="border:1px solid" align="center"></td></tr>
198 At some point the EVP layer will begin enforcing the transitions described
203 L<provider-mac(7)>, L<EVP_MAC(3)>.
207 The provider MAC interface was introduced in OpenSSL 3.0.
211 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
213 Licensed under the Apache License 2.0 (the "License"). You may not use
214 this file except in compliance with the License. You can obtain a copy
215 in the file LICENSE in the source distribution or at
216 L<https://www.openssl.org/source/license.html>.