VirtualBox

source: vbox/trunk/src/libs/openssl-3.4.1/doc/man7/life_cycle-digest.pod

Last change on this file was 109052, checked in by vboxsync, 3 weeks ago

openssl-3.4.1: Applied our changes, regenerated files, added missing files and functions. This time with a three way merge. ​bugref:10890
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.2 KB
Line 
1=pod
2
3=head1 NAME
4
5life_cycle-digest - The digest algorithm life-cycle
6
7=head1 DESCRIPTION
8
9All message digests (MDs) go through a number of stages in their life-cycle:
10
11=over 4
12
13=item start
14
15This state represents the MD before it has been allocated. It is the
16starting state for any life-cycle transitions.
17
18=item newed
19
20This state represents the MD after it has been allocated.
21
22=item initialised
23
24This state represents the MD when it is set up and capable of processing
25input.
26
27=item updated
28
29This state represents the MD when it is set up and capable of processing
30additional input or generating output.
31
32=item finaled
33
34This state represents the MD when it has generated output.
35For an XOF digest, this state represents the MD when it has generated a
36single-shot output.
37
38=item squeezed
39
40For an XOF digest, this state represents the MD when it has generated output.
41It can be called multiple times to generate more output. The output length is
42variable for each call.
43
44=item freed
45
46This state is entered when the MD is freed. It is the terminal state
47for all life-cycle transitions.
48
49=back
50
51=head2 State Transition Diagram
52
53The usual life-cycle of a MD is illustrated:
54
55=begin man
56
57 +--------------------+
58 | start |
59 +--------------------+
60 | EVP_MD_CTX_reset
61 | EVP_MD_CTX_new +-------------------------------------------------+
62 v v |
63 EVP_MD_CTX_reset + - - - - - - - - - - - - - - - - - - - - - - + EVP_MD_CTX_reset |
64 +-------------------> ' newed ' <--------------------+ |
65 | + - - - - - - - - - - - - - - - - - - - - - - + | |
66 | | | |
67 | | EVP_DigestInit | |
68 | v | |
69 | EVP_DigestInit + - - - - - - - - - - - - - - - - - - - - - - + | |
70 +----+-------------------> ' initialised ' <+ EVP_DigestInit | |
71 | | + - - - - - - - - - - - - - - - - - - - - - - + | | |
72 | | | ^ | | |
73 | | | EVP_DigestUpdate | EVP_DigestInit | | |
74 | | v | | | |
75 | | +---------------------------------------------+ | | |
76 | +-------------------- | | | | |
77 | | | | | |
78 | EVP_DigestUpdate | | | | |
79 | +-------------------- | | | | |
80 | | | updated | | | |
81 | +-------------------> | | | | |
82 | | | | | |
83 | | | | | |
84 +----+------------------------- | | -+-------------------+----+ |
85 | | +---------------------------------------------+ | | | |
86 | | | | | | |
87 | | | EVP_DigestSqueeze +-------------------+ | | |
88 | | v | | | |
89 | | EVP_DigestSqueeze +---------------------------------------------+ | | |
90 | | +-------------------- | | | | |
91 | | | | squeezed | | | |
92 | | +-------------------> | | ---------------------+ | |
93 | | +---------------------------------------------+ | |
94 | | | | |
95 | | +---------------------------------------+ | |
96 | | | | |
97 | | +---------------------------------------------+ EVP_DigestFinalXOF | | |
98 | +------------------------- | finaled | <--------------------+----+ |
99 | +---------------------------------------------+ | |
100 | EVP_DigestFinal ^ | | | |
101 +---------------------------------+ | | EVP_MD_CTX_free | |
102 | v | |
103 | +------------------+ EVP_MD_CTX_free | |
104 | | freed | <--------------------+ |
105 | +------------------+ |
106 | |
107 +------------------------------------------------------+
108
109=end man
110
111=for html <img src="img/digest.png">
112
113=head2 Formal State Transitions
114
115This section defines all of the legal state transitions.
116This is the canonical list.
117
118=begin man
119
120 Function Call --------------------- Current State -----------------------------------
121 start newed initialised updated finaled squeezed freed
122 EVP_MD_CTX_new newed
123 EVP_DigestInit initialised initialised initialised initialised initialised
124 EVP_DigestUpdate updated updated
125 EVP_DigestFinal finaled
126 EVP_DigestFinalXOF finaled
127 EVP_DigestSqueeze squeezed squeezed
128 EVP_MD_CTX_free freed freed freed freed freed
129 EVP_MD_CTX_reset newed newed newed newed
130 EVP_MD_CTX_get_params newed initialised updated
131 EVP_MD_CTX_set_params newed initialised updated
132 EVP_MD_CTX_gettable_params newed initialised updated
133 EVP_MD_CTX_settable_params newed initialised updated
134 EVP_MD_CTX_copy_ex newed initialised updated squeezed
135
136=end man
137
138=begin html
139
140<table style="border:1px solid; border-collapse:collapse">
141<tr><th style="border:1px solid" align="left">Function Call</th>
142 <th style="border:1px solid" colspan="6">Current State</th></tr>
143<tr><th style="border:1px solid"></th>
144 <th style="border:1px solid" align="center">start</th>
145 <th style="border:1px solid" align="center">newed</th>
146 <th style="border:1px solid" align="center">initialised</th>
147 <th style="border:1px solid" align="center">updated</th>
148 <th style="border:1px solid" align="center">finaled</th>
149 <th style="border:1px solid" align="center">squeezed</th>
150 <th style="border:1px solid" align="center">freed</th></tr>
151<tr><th style="border:1px solid" align="left">EVP_MD_CTX_new</th>
152 <td style="border:1px solid" align="center">newed</td>
153 <td style="border:1px solid" align="center"></td>
154 <td style="border:1px solid" align="center"></td>
155 <td style="border:1px solid" align="center"></td>
156 <td style="border:1px solid" align="center"></td>
157 <td style="border:1px solid" align="center"></td>
158 <td style="border:1px solid" align="center"></td></tr>
159<tr><th style="border:1px solid" align="left">EVP_DigestInit</th>
160 <td style="border:1px solid" align="center"></td>
161 <td style="border:1px solid" align="center">initialised</td>
162 <td style="border:1px solid" align="center">initialised</td>
163 <td style="border:1px solid" align="center">initialised</td>
164 <td style="border:1px solid" align="center">initialised</td>
165 <td style="border:1px solid" align="center">initialised</td>
166 <td style="border:1px solid" align="center"></td></tr>
167<tr><th style="border:1px solid" align="left">EVP_DigestUpdate</th>
168 <td style="border:1px solid" align="center"></td>
169 <td style="border:1px solid" align="center"></td>
170 <td style="border:1px solid" align="center">updated</td>
171 <td style="border:1px solid" align="center">updated</td>
172 <td style="border:1px solid" align="center"></td>
173 <td style="border:1px solid" align="center"></td>
174 <td style="border:1px solid" align="center"></td></tr>
175<tr><th style="border:1px solid" align="left">EVP_DigestFinal</th>
176 <td style="border:1px solid" align="center"></td>
177 <td style="border:1px solid" align="center"></td>
178 <td style="border:1px solid" align="center"></td>
179 <td style="border:1px solid" align="center">finaled</td>
180 <td style="border:1px solid" align="center"></td>
181 <td style="border:1px solid" align="center"></td>
182 <td style="border:1px solid" align="center"></td></tr>
183<tr><th style="border:1px solid" align="left">EVP_DigestSqueeze</th>
184 <td style="border:1px solid" align="center"></td>
185 <td style="border:1px solid" align="center"></td>
186 <td style="border:1px solid" align="center"></td>
187 <td style="border:1px solid" align="center">squeezed</td>
188 <td style="border:1px solid" align="center"></td>
189 <td style="border:1px solid" align="center">squeezed</td>
190 <td style="border:1px solid" align="center"></td></tr>
191<tr><th style="border:1px solid" align="left">EVP_DigestFinalXOF</th>
192 <td style="border:1px solid" align="center"></td>
193 <td style="border:1px solid" align="center"></td>
194 <td style="border:1px solid" align="center"></td>
195 <td style="border:1px solid" align="center">finaled</td>
196 <td style="border:1px solid" align="center"></td>
197 <td style="border:1px solid" align="center"></td>
198 <td style="border:1px solid" align="center"></td></tr>
199<tr><th style="border:1px solid" align="left">EVP_MD_CTX_free</th>
200 <td style="border:1px solid" align="center">freed</td>
201 <td style="border:1px solid" align="center">freed</td>
202 <td style="border:1px solid" align="center">freed</td>
203 <td style="border:1px solid" align="center">freed</td>
204 <td style="border:1px solid" align="center">freed</td>
205 <td style="border:1px solid" align="center"></td>
206 <td style="border:1px solid" align="center"></td></tr>
207<tr><th style="border:1px solid" align="left">EVP_MD_CTX_reset</th>
208 <td style="border:1px solid" align="center"></td>
209 <td style="border:1px solid" align="center">newed</td>
210 <td style="border:1px solid" align="center">newed</td>
211 <td style="border:1px solid" align="center">newed</td>
212 <td style="border:1px solid" align="center">newed</td>
213 <td style="border:1px solid" align="center"></td>
214 <td style="border:1px solid" align="center"></td></tr>
215<tr><th style="border:1px solid" align="left">EVP_MD_CTX_get_params</th>
216 <td style="border:1px solid" align="center"></td>
217 <td style="border:1px solid" align="center">newed</td>
218 <td style="border:1px solid" align="center">initialised</td>
219 <td style="border:1px solid" align="center">updated</td>
220 <td style="border:1px solid" align="center"></td>
221 <td style="border:1px solid" align="center"></td>
222 <td style="border:1px solid" align="center"></td></tr>
223<tr><th style="border:1px solid" align="left">EVP_MD_CTX_set_params</th>
224 <td style="border:1px solid" align="center"></td>
225 <td style="border:1px solid" align="center">newed</td>
226 <td style="border:1px solid" align="center">initialised</td>
227 <td style="border:1px solid" align="center">updated</td>
228 <td style="border:1px solid" align="center"></td>
229 <td style="border:1px solid" align="center"></td>
230 <td style="border:1px solid" align="center"></td></tr>
231<tr><th style="border:1px solid" align="left">EVP_MD_CTX_gettable_params</th>
232 <td style="border:1px solid" align="center"></td>
233 <td style="border:1px solid" align="center">newed</td>
234 <td style="border:1px solid" align="center">initialised</td>
235 <td style="border:1px solid" align="center">updated</td>
236 <td style="border:1px solid" align="center"></td>
237 <td style="border:1px solid" align="center"></td>
238 <td style="border:1px solid" align="center"></td></tr>
239<tr><th style="border:1px solid" align="left">EVP_MD_CTX_settable_params</th>
240 <td style="border:1px solid" align="center"></td>
241 <td style="border:1px solid" align="center">newed</td>
242 <td style="border:1px solid" align="center">initialised</td>
243 <td style="border:1px solid" align="center">updated</td>
244 <td style="border:1px solid" align="center"></td>
245 <td style="border:1px solid" align="center"></td>
246 <td style="border:1px solid" align="center"></td></tr>
247<tr><th style="border:1px solid" align="left">EVP_MD_CTX_copy_ex</th>
248 <td style="border:1px solid" align="center"></td>
249 <td style="border:1px solid" align="center">newed</td>
250 <td style="border:1px solid" align="center">initialised</td>
251 <td style="border:1px solid" align="center">updated</td>
252 <td style="border:1px solid" align="center"></td>
253 <td style="border:1px solid" align="center">squeezed</td>
254 <td style="border:1px solid" align="center"></td></tr>
255</table>
256
257=end html
258
259=head1 NOTES
260
261At some point the EVP layer will begin enforcing the transitions described
262herein.
263
264=head1 SEE ALSO
265
266L<provider-digest(7)>, L<EVP_DigestInit(3)>
267
268=head1 COPYRIGHT
269
270Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
271
272Licensed under the Apache License 2.0 (the "License"). You may not use
273this file except in compliance with the License. You can obtain a copy
274in the file LICENSE in the source distribution or at
275L<https://www.openssl.org/source/license.html>.
276
277=cut
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette