1 | =pod
|
---|
2 |
|
---|
3 | =head1 NAME
|
---|
4 |
|
---|
5 | life_cycle-mac - The MAC algorithm life-cycle
|
---|
6 |
|
---|
7 | =head1 DESCRIPTION
|
---|
8 |
|
---|
9 | All message authentication codes (MACs)
|
---|
10 | go through a number of stages in their life-cycle:
|
---|
11 |
|
---|
12 | =over 4
|
---|
13 |
|
---|
14 | =item start
|
---|
15 |
|
---|
16 | This state represents the MAC before it has been allocated. It is the
|
---|
17 | starting state for any life-cycle transitions.
|
---|
18 |
|
---|
19 | =item newed
|
---|
20 |
|
---|
21 | This state represents the MAC after it has been allocated.
|
---|
22 |
|
---|
23 | =item initialised
|
---|
24 |
|
---|
25 | This state represents the MAC when it is set up and capable of processing
|
---|
26 | input.
|
---|
27 |
|
---|
28 | =item updated
|
---|
29 |
|
---|
30 | This state represents the MAC when it is set up and capable of processing
|
---|
31 | additional input or generating output.
|
---|
32 |
|
---|
33 | =item finaled
|
---|
34 |
|
---|
35 | This state represents the MAC when it has generated output.
|
---|
36 |
|
---|
37 | =item freed
|
---|
38 |
|
---|
39 | This state is entered when the MAC is freed. It is the terminal state
|
---|
40 | for all life-cycle transitions.
|
---|
41 |
|
---|
42 | =back
|
---|
43 |
|
---|
44 | =head2 State Transition Diagram
|
---|
45 |
|
---|
46 | The 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 |
|
---|
90 | This section defines all of the legal state transitions.
|
---|
91 | This 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 |
|
---|
198 | At some point the EVP layer will begin enforcing the transitions described
|
---|
199 | herein.
|
---|
200 |
|
---|
201 | =head1 SEE ALSO
|
---|
202 |
|
---|
203 | L<provider-mac(7)>, L<EVP_MAC(3)>.
|
---|
204 |
|
---|
205 | =head1 HISTORY
|
---|
206 |
|
---|
207 | The provider MAC interface was introduced in OpenSSL 3.0.
|
---|
208 |
|
---|
209 | =head1 COPYRIGHT
|
---|
210 |
|
---|
211 | Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
|
---|
212 |
|
---|
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>.
|
---|
217 |
|
---|
218 | =cut
|
---|