xref: /openssl/doc/man7/life_cycle-mac.pod (revision 57cd10dd) 
1=pod
2
3=head1 NAME
4
5life_cycle-mac - The MAC algorithm life-cycle
6
7=head1 DESCRIPTION
8
9All message authentication codes (MACs)
10go through a number of stages in their life-cycle:
11
12=over 4
13
14=item start
15
16This state represents the MAC before it has been allocated.  It is the
17starting state for any life-cycle transitions.
18
19=item newed
20
21This state represents the MAC after it has been allocated.
22
23=item initialised
24
25This state represents the MAC when it is set up and capable of processing
26input.
27
28=item updated
29
30This state represents the MAC when it is set up and capable of processing
31additional input or generating output.
32
33=item finaled
34
35This state represents the MAC when it has generated output.
36
37=item freed
38
39This state is entered when the MAC is freed.  It is the terminal state
40for all life-cycle transitions.
41
42=back
43
44=head2 State Transition Diagram
45
46The usual life-cycle of a MAC is illustrated:
47
48=begin man
49
50                 +-------------------+
51                 |       start       |
52                 +-------------------+
53                   |
54                   | EVP_MAC_CTX_new
55                   v
56                 +-------------------+
57                 |       newed       |
58                 +-------------------+
59                   |
60                   | EVP_MAC_init
61                   v
62                 +-------------------+
63              +> |    initialised    | <+
64              |  +-------------------+  |
65              |    |                    |
66              |    | EVP_MAC_update     | EVP_MAC_init
67              |    v                    |
68 EVP_MAC_init |  +-------------------+  |
69              |  |      updated      | -+
70              |  +-------------------+
71              |    |               |
72              |    | EVP_MAC_final | EVP_MAC_finalXOF
73              |    v               v
74              |  +-------------------+
75              +- |      finaled      |
76                 +-------------------+
77                   |
78                   | EVP_MAC_CTX_free
79                   v
80                 +-------------------+
81                 |       freed       |
82                 +-------------------+
83
84=end man
85
86=for html <img src="img/mac.png">
87
88=head2 Formal State Transitions
89
90This section defines all of the legal state transitions.
91This is the canonical list.
92
93=begin man
94
95 Function Call                   --------------------- Current State ----------------------
96                                 start   newed    initialised   updated     finaled   freed
97 EVP_MAC_CTX_new                 newed
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
107
108=end man
109
110=begin html
111
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>
192</table>
193
194=end html
195
196=head1 NOTES
197
198At some point the EVP layer will begin enforcing the transitions described
199herein.
200
201=head1 SEE ALSO
202
203L<provider-mac(7)>, L<EVP_MAC(3)>.
204
205=head1 HISTORY
206
207The provider MAC interface was introduced in OpenSSL 3.0.
208
209=head1 COPYRIGHT
210
211Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
212
213Licensed under the Apache License 2.0 (the "License").  You may not use
214this file except in compliance with the License.  You can obtain a copy
215in the file LICENSE in the source distribution or at
216L<https://www.openssl.org/source/license.html>.
217
218=cut
219