]>
Commit | Line | Data |
---|---|---|
4551763e P |
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 | | +-------------------+ | |
f14a2c9d P |
71 | | | | |
72 | | | EVP_MAC_final | EVP_MAC_finalXOF | |
73 | | v v | |
4551763e P |
74 | | +-------------------+ |
75 | +- | finaled | | |
76 | +-------------------+ | |
77 | | | |
78 | | EVP_MAC_CTX_free | |
79 | v | |
80 | +-------------------+ | |
81 | | freed | | |
82 | +-------------------+ | |
83 | ||
84 | =end man | |
85 | ||
1d95931d | 86 | =for html <img src="img/mac.png"> |
4551763e P |
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 | ||
8809fdff | 95 | Function Call --------------------- Current State ---------------------- |
4551763e | 96 | start newed initialised updated finaled freed |
57cd10dd | 97 | EVP_MAC_CTX_new newed |
4551763e P |
98 | EVP_MAC_init initialised initialised initialised initialised |
99 | EVP_MAC_update updated updated | |
100 | EVP_MAC_final finaled | |
f14a2c9d | 101 | EVP_MAC_finalXOF finaled |
4551763e | 102 | EVP_MAC_CTX_free freed freed freed freed freed |
ed348378 P |
103 | EVP_MAC_CTX_get_params newed initialised updated |
104 | EVP_MAC_CTX_set_params newed initialised updated | |
4551763e P |
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> | |
f14a2c9d P |
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> | |
4551763e P |
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> | |
ed348378 | 164 | <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_get_params</th> |
4551763e P |
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> | |
ed348378 | 171 | <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_set_params</th> |
4551763e P |
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 |