xref: /freebsd/crypto/openssl/doc/man7/life_cycle-digest.pod (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95) 
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.
35
36=item freed
37
38This state is entered when the MD is freed.  It is the terminal state
39for all life-cycle transitions.
40
41=back
42
43=head2 State Transition Diagram
44
45The usual life-cycle of a MD is illustrated:
46
47=begin man
48
49                     +-------------------+
50                     |       start       |
51                     +-------------------+
52                       |
53                       | EVP_MD_CTX_new
54                       v
55                     +-------------------+         EVP_MD_CTX_reset
56                     |       newed       | <------------------------------+
57                     +-------------------+                                |
58                       |                                                  |
59                       | EVP_DigestInit                                   |
60                       v                                                  |
61                     +-------------------+                                |
62                +--> |    initialised    | <+ EVP_DigestInit              |
63                |    +-------------------+  |                             |
64                |      |                    |      EVP_DigestUpdate       |
65                |      | EVP_DigestUpdate   |    +------------------+     |
66                |      v                    |    v                  |     |
67                |    +------------------------------------------------+   |
68 EVP_DigestInit |    |                    updated                     | --+
69                |    +------------------------------------------------+   |
70                |      |                    |                             |
71                |      | EVP_DigestFinal    | EVP_DigestFinalXOF          |
72                |      v                    v                             |
73                |    +------------------------------------------------+   |
74                +--- |                    finaled                     | --+
75                     +------------------------------------------------+
76                       |
77                       | EVP_MD_CTX_free
78                       v
79                     +-------------------+
80                     |       freed       |
81                     +-------------------+
82
83=end man
84
85=for html <img src="img/digest.png">
86
87=head2 Formal State Transitions
88
89This section defines all of the legal state transitions.
90This is the canonical list.
91
92=begin man
93
94 Function Call                --------------------- Current State ----------------------
95                              start   newed    initialised   updated     finaled   freed
96 EVP_MD_CTX_new               newed
97 EVP_DigestInit                    initialised initialised initialised initialised
98 EVP_DigestUpdate                                updated     updated
99 EVP_DigestFinal                                             finaled
100 EVP_DigestFinalXOF                                          finaled
101 EVP_MD_CTX_free              freed   freed       freed       freed       freed
102 EVP_MD_CTX_reset                     newed       newed       newed       newed
103 EVP_MD_CTX_get_params                newed    initialised   updated
104 EVP_MD_CTX_set_params                newed    initialised   updated
105 EVP_MD_CTX_gettable_params           newed    initialised   updated
106 EVP_MD_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_MD_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_DigestInit</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_DigestUpdate</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_DigestFinal</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_DigestFinalXOF</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_MD_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_MD_CTX_reset</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">newed</td>
168    <td style="border:1px solid" align="center">newed</td>
169    <td style="border:1px solid" align="center">newed</td>
170    <td style="border:1px solid" align="center"></td></tr>
171<tr><th style="border:1px solid" align="left">EVP_MD_CTX_get_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_MD_CTX_set_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_MD_CTX_gettable_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<tr><th style="border:1px solid" align="left">EVP_MD_CTX_settable_params</th>
193    <td style="border:1px solid" align="center"></td>
194    <td style="border:1px solid" align="center">newed</td>
195    <td style="border:1px solid" align="center">initialised</td>
196    <td style="border:1px solid" align="center">updated</td>
197    <td style="border:1px solid" align="center"></td>
198    <td style="border:1px solid" align="center"></td></tr>
199</table>
200
201=end html
202
203=head1 NOTES
204
205At some point the EVP layer will begin enforcing the transitions described
206herein.
207
208=head1 SEE ALSO
209
210L<provider-digest(7)>, L<EVP_DigestInit(3)>
211
212=head1 COPYRIGHT
213
214Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
215
216Licensed under the Apache License 2.0 (the "License").  You may not use
217this file except in compliance with the License.  You can obtain a copy
218in the file LICENSE in the source distribution or at
219L<https://www.openssl.org/source/license.html>.
220
221=cut
222