xref: /openssl/doc/man7/life_cycle-cipher.pod (revision 57cd10dd) 
1=pod
2
3=head1 NAME
4
5life_cycle-cipher - The cipher algorithm life-cycle
6
7=head1 DESCRIPTION
8
9All symmetric ciphers (CIPHERs) go through a number of stages in their
10life-cycle:
11
12=over 4
13
14=item start
15
16This state represents the CIPHER before it has been allocated.  It is the
17starting state for any life-cycle transitions.
18
19=item newed
20
21This state represents the CIPHER after it has been allocated.
22
23=item initialised
24
25These states represent the CIPHER when it is set up and capable of processing
26input.  There are three possible initialised states:
27
28=over 4
29
30=item initialised using EVP_CipherInit
31
32=item initialised for decryption using EVP_DecryptInit
33
34=item initialised for encryption using EVP_EncryptInit
35
36=back
37
38=item updated
39
40These states represent the CIPHER when it is set up and capable of processing
41additional input or generating output.  The three possible states directly
42correspond to those for initialised above.  The three different streams should
43not be mixed.
44
45=item finaled
46
47This state represents the CIPHER when it has generated output.
48
49=item freed
50
51This state is entered when the CIPHER is freed.  It is the terminal state
52for all life-cycle transitions.
53
54=back
55
56=head2 State Transition Diagram
57
58The usual life-cycle of a CIPHER is illustrated:
59
60=begin man
61
62                                 +---------------------------+
63                                 |                           |
64                                 |           start           |
65                                 |                           |
66                                 +---------------------------+   + - - - - - - - - - - - - - +
67                                       |                         '  any of the initialised   '
68                                       | EVP_CIPHER_CTX_new      ' updated or finaled states '
69                                       v                         '                           '
70                                 +---------------------------+   + - - - - - - - - - - - - - +
71                                 |                           |      |
72                                 |           newed           |      | EVP_CIPHER_CTX_reset
73                                 |                           | <----+
74                                 +---------------------------+
75                                    |   |                 |
76                          +---------+   |                 +---------+
77          EVP_DecryptInit |             | EVP_CipherInit            | EVP_EncryptInit
78                          v             v                           v
79 +---------------------------+   +---------------------------+   +---------------------------+
80 |                           |   |                           |   |                           |
81 |        initialised        |   |        initialised        |   |        initialised        |
82 |       for decryption      |   |                           |   |       for encryption      |
83 +---------------------------+   +---------------------------+   +---------------------------+
84   |                                   |                                                   |
85   | EVP_DecryptUpdate                 | EVP_CipherUpdate                EVP_EncryptUpdate |
86   |                                   v                                                   |
87   |                             +---------------------------+                             |
88   |                             |                           |--------------------+        |
89   |                             |          updated          |   EVP_CipherUpdate |        |
90   |                             |                           | <------------------+        |
91   v                             +---------------------------+                             v
92 +---------------------------+                         |         +---------------------------+
93 |                           |---------------------+   |         |                           |
94 |          updated          |   EVP_DecryptUpdate |   |         |          updated          |------+
95 |       for decryption      | <-------------------+   |         |       for encryption      |      |
96 +---------------------------+                         |         +---------------------------+      |
97                          |            EVP_CipherFinal |            |           ^                   |
98                          +-------+                    |   +--------+           |                   |
99                 EVP_DecryptFinal |                    |   | EVP_EncryptFinal   +-------------------+
100                                  v                    v   v                      EVP_EncryptUpdate
101                                 +---------------------------+
102                                 |                           |-----------------------------+
103                                 |          finaled          |                             |
104                                 |                           | <---------------------------+
105                                 +---------------------------+   EVP_CIPHER_CTX_get_params
106                                       |                             (AEAD encryption)
107                                       | EVP_CIPHER_CTX_free
108                                       v
109                                 +---------------------------+
110                                 |                           |
111                                 |           freed           |
112                                 |                           |
113                                 +---------------------------+
114
115=end man
116
117=for html <img src="img/cipher.png">
118
119=head2 Formal State Transitions
120
121This section defines all of the legal state transitions.
122This is the canonical list.
123
124=begin man
125
126 Function Call                ---------------------------------------------- Current State -----------------------------------------------
127                              start   newed    initialised   updated     finaled   initialised   updated    initialised   updated    freed
128                                                                                    decryption  decryption   encryption  encryption
129 EVP_CIPHER_CTX_new           newed
130 EVP_CipherInit                    initialised initialised initialised initialised initialised initialised  initialised initialised
131 EVP_DecryptInit                   initialised initialised initialised initialised initialised initialised  initialised initialised
132                                    decryption  decryption  decryption  decryption  decryption  decryption  decryption  decryption
133 EVP_EncryptInit                   initialised initialised initialised initialised initialised initialised  initialised initialised
134                                    encryption  encryption  encryption  encryption  encryption  encryption  encryption  encryption
135 EVP_CipherUpdate                                updated     updated
136 EVP_DecryptUpdate                                                                   updated     updated
137                                                                                    decryption  decryption
138 EVP_EncryptUpdate                                                                                            updated     updated
139                                                                                                             encryption  encryption
140 EVP_CipherFinal                                             finaled
141 EVP_DecryptFinal                                                                                finaled
142 EVP_EncryptFinal                                                                                                         finaled
143 EVP_CIPHER_CTX_free          freed   freed       freed       freed       freed       freed       freed        freed       freed
144 EVP_CIPHER_CTX_reset                 newed       newed       newed       newed       newed       newed        newed       newed
145 EVP_CIPHER_CTX_get_params            newed    initialised   updated               initialised   updated    initialised   updated
146                                                                                    decryption  decryption   encryption  encryption
147 EVP_CIPHER_CTX_set_params            newed    initialised   updated               initialised   updated    initialised   updated
148                                                                                    decryption  decryption   encryption  encryption
149 EVP_CIPHER_CTX_gettable_params       newed    initialised   updated               initialised   updated    initialised   updated
150                                                                                    decryption  decryption   encryption  encryption
151 EVP_CIPHER_CTX_settable_params       newed    initialised   updated               initialised   updated    initialised   updated
152                                                                                    decryption  decryption   encryption  encryption
153
154=end man
155
156=begin html
157
158<table style="border:1px solid; border-collapse:collapse">
159<tr><th style="border:1px solid" align="left">Function Call</th>
160    <th style="border:1px solid" colspan="10">Current State</th></tr>
161<tr><th style="border:1px solid"></th>
162    <th style="border:1px solid" align="center">start</th>
163    <th style="border:1px solid" align="center">newed</th>
164    <th style="border:1px solid" align="center">initialised</th>
165    <th style="border:1px solid" align="center">updated</th>
166    <th style="border:1px solid" align="center">finaled</th>
167    <th style="border:1px solid" align="center">initialised<br>decryption</th>
168    <th style="border:1px solid" align="center">updated<br>decryption</th>
169    <th style="border:1px solid" align="center">initialised<br>encryption</th>
170    <th style="border:1px solid" align="center">updated<br>encryption</th>
171    <th style="border:1px solid" align="center">freed</th></tr>
172<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_new</th>
173    <td style="border:1px solid" align="center">newed</td>
174    <td style="border:1px solid" align="center"></td>
175    <td style="border:1px solid" align="center"></td>
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"></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_CipherInit</th>
184    <td style="border:1px solid" align="center"></td>
185    <td style="border:1px solid" align="center">initialised</td>
186    <td style="border:1px solid" align="center">initialised</td>
187    <td style="border:1px solid" align="center">initialised</td>
188    <td style="border:1px solid" align="center">initialised</td>
189    <td style="border:1px solid" align="center">initialised</td>
190    <td style="border:1px solid" align="center">initialised</td>
191    <td style="border:1px solid" align="center">initialised</td>
192    <td style="border:1px solid" align="center">initialised</td>
193    <td style="border:1px solid" align="center"></td></tr>
194<tr><th style="border:1px solid" align="left">EVP_DecryptInit</th>
195    <td style="border:1px solid" align="center"></td>
196    <td style="border:1px solid" align="center">initialised<br>decryption</td>
197    <td style="border:1px solid" align="center">initialised<br>decryption</td>
198    <td style="border:1px solid" align="center">initialised<br>decryption</td>
199    <td style="border:1px solid" align="center">initialised<br>decryption</td>
200    <td style="border:1px solid" align="center">initialised<br>decryption</td>
201    <td style="border:1px solid" align="center">initialised<br>decryption</td>
202    <td style="border:1px solid" align="center">initialised<br>decryption</td>
203    <td style="border:1px solid" align="center">initialised<br>decryption</td>
204    <td style="border:1px solid" align="center"></td></tr>
205<tr><th style="border:1px solid" align="left">EVP_EncryptInit</th>
206    <td style="border:1px solid" align="center"></td>
207    <td style="border:1px solid" align="center">initialised<br>encryption</td>
208    <td style="border:1px solid" align="center">initialised<br>encryption</td>
209    <td style="border:1px solid" align="center">initialised<br>encryption</td>
210    <td style="border:1px solid" align="center">initialised<br>encryption</td>
211    <td style="border:1px solid" align="center">initialised<br>encryption</td>
212    <td style="border:1px solid" align="center">initialised<br>encryption</td>
213    <td style="border:1px solid" align="center">initialised<br>encryption</td>
214    <td style="border:1px solid" align="center">initialised<br>encryption</td>
215    <td style="border:1px solid" align="center"></td></tr>
216<tr><th style="border:1px solid" align="left">EVP_CipherUpdate</th>
217    <td style="border:1px solid" align="center"></td>
218    <td style="border:1px solid" align="center"></td>
219    <td style="border:1px solid" align="center">updated</td>
220    <td style="border:1px solid" align="center">updated</td>
221    <td style="border:1px solid" align="center"></td>
222    <td style="border:1px solid" align="center"></td>
223    <td style="border:1px solid" align="center"></td>
224    <td style="border:1px solid" align="center"></td>
225    <td style="border:1px solid" align="center"></td>
226    <td style="border:1px solid" align="center"></td></tr>
227<tr><th style="border:1px solid" align="left">EVP_DecryptUpdate</th>
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>
231    <td style="border:1px solid" align="center"></td>
232    <td style="border:1px solid" align="center"></td>
233    <td style="border:1px solid" align="center">updated<br>decryption</td>
234    <td style="border:1px solid" align="center">updated<br>decryption</td>
235    <td style="border:1px solid" align="center"></td>
236    <td style="border:1px solid" align="center"></td>
237    <td style="border:1px solid" align="center"></td></tr>
238<tr><th style="border:1px solid" align="left">EVP_EncryptUpdate</th>
239    <td style="border:1px solid" align="center"></td>
240    <td style="border:1px solid" align="center"></td>
241    <td style="border:1px solid" align="center"></td>
242    <td style="border:1px solid" align="center"></td>
243    <td style="border:1px solid" align="center"></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">updated<br>encryption</td>
247    <td style="border:1px solid" align="center">updated<br>encryption</td>
248    <td style="border:1px solid" align="center"></td></tr>
249<tr><th style="border:1px solid" align="left">EVP_CipherFinal</th>
250    <td style="border:1px solid" align="center"></td>
251    <td style="border:1px solid" align="center"></td>
252    <td style="border:1px solid" align="center"></td>
253    <td style="border:1px solid" align="center">finaled</td>
254    <td style="border:1px solid" align="center"></td>
255    <td style="border:1px solid" align="center"></td>
256    <td style="border:1px solid" align="center"></td>
257    <td style="border:1px solid" align="center"></td>
258    <td style="border:1px solid" align="center"></td>
259    <td style="border:1px solid" align="center"></td></tr>
260<tr><th style="border:1px solid" align="left">EVP_DecryptFinal</th>
261    <td style="border:1px solid" align="center"></td>
262    <td style="border:1px solid" align="center"></td>
263    <td style="border:1px solid" align="center"></td>
264    <td style="border:1px solid" align="center"></td>
265    <td style="border:1px solid" align="center"></td>
266    <td style="border:1px solid" align="center"></td>
267    <td style="border:1px solid" align="center">finaled<br>decryption</td>
268    <td style="border:1px solid" align="center"></td>
269    <td style="border:1px solid" align="center"></td>
270    <td style="border:1px solid" align="center"></td></tr>
271<tr><th style="border:1px solid" align="left">EVP_EncryptFinal</th>
272    <td style="border:1px solid" align="center"></td>
273    <td style="border:1px solid" align="center"></td>
274    <td style="border:1px solid" align="center"></td>
275    <td style="border:1px solid" align="center"></td>
276    <td style="border:1px solid" align="center"></td>
277    <td style="border:1px solid" align="center"></td>
278    <td style="border:1px solid" align="center"></td>
279    <td style="border:1px solid" align="center"></td>
280    <td style="border:1px solid" align="center">finaled<br>decryption</td>
281    <td style="border:1px solid" align="center"></td></tr>
282<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_free</th>
283    <td style="border:1px solid" align="center">freed</td>
284    <td style="border:1px solid" align="center">freed</td>
285    <td style="border:1px solid" align="center">freed</td>
286    <td style="border:1px solid" align="center">freed</td>
287    <td style="border:1px solid" align="center">freed</td>
288    <td style="border:1px solid" align="center">freed</td>
289    <td style="border:1px solid" align="center">freed</td>
290    <td style="border:1px solid" align="center">freed</td>
291    <td style="border:1px solid" align="center">freed</td>
292    <td style="border:1px solid" align="center"></td></tr>
293<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_reset</th>
294    <td style="border:1px solid" align="center"></td>
295    <td style="border:1px solid" align="center"></td>
296    <td style="border:1px solid" align="center">newed</td>
297    <td style="border:1px solid" align="center">newed</td>
298    <td style="border:1px solid" align="center">newed</td>
299    <td style="border:1px solid" align="center">newed</td>
300    <td style="border:1px solid" align="center">newed</td>
301    <td style="border:1px solid" align="center">newed</td>
302    <td style="border:1px solid" align="center">newed</td>
303    <td style="border:1px solid" align="center"></td></tr>
304<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_get_params</th>
305    <td style="border:1px solid" align="center"></td>
306    <td style="border:1px solid" align="center">newed</td>
307    <td style="border:1px solid" align="center">initialised</td>
308    <td style="border:1px solid" align="center">updated</td>
309    <td style="border:1px solid" align="center"></td>
310    <td style="border:1px solid" align="center">initialised<br>decryption</td>
311    <td style="border:1px solid" align="center">updated<br>decryption</td>
312    <td style="border:1px solid" align="center">initialised<br>encryption</td>
313    <td style="border:1px solid" align="center">updated<br>encryption</td>
314    <td style="border:1px solid" align="center"></td></tr>
315<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_set_params</th>
316    <td style="border:1px solid" align="center"></td>
317    <td style="border:1px solid" align="center">newed</td>
318    <td style="border:1px solid" align="center">initialised</td>
319    <td style="border:1px solid" align="center">updated</td>
320    <td style="border:1px solid" align="center"></td>
321    <td style="border:1px solid" align="center">initialised<br>decryption</td>
322    <td style="border:1px solid" align="center">updated<br>decryption</td>
323    <td style="border:1px solid" align="center">initialised<br>encryption</td>
324    <td style="border:1px solid" align="center">updated<br>encryption</td>
325    <td style="border:1px solid" align="center"></td></tr>
326<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_gettable_params</th>
327    <td style="border:1px solid" align="center"></td>
328    <td style="border:1px solid" align="center">newed</td>
329    <td style="border:1px solid" align="center">initialised</td>
330    <td style="border:1px solid" align="center">updated</td>
331    <td style="border:1px solid" align="center"></td>
332    <td style="border:1px solid" align="center">initialised<br>decryption</td>
333    <td style="border:1px solid" align="center">updated<br>decryption</td>
334    <td style="border:1px solid" align="center">initialised<br>encryption</td>
335    <td style="border:1px solid" align="center">updated<br>encryption</td>
336    <td style="border:1px solid" align="center"></td></tr>
337<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_settable_params</th>
338    <td style="border:1px solid" align="center"></td>
339    <td style="border:1px solid" align="center">newed</td>
340    <td style="border:1px solid" align="center">initialised</td>
341    <td style="border:1px solid" align="center">updated</td>
342    <td style="border:1px solid" align="center"></td>
343    <td style="border:1px solid" align="center">initialised<br>decryption</td>
344    <td style="border:1px solid" align="center">updated<br>decryption</td>
345    <td style="border:1px solid" align="center">initialised<br>encryption</td>
346    <td style="border:1px solid" align="center">updated<br>encryption</td>
347    <td style="border:1px solid" align="center"></td></tr>
348</table>
349
350=end html
351
352=head1 NOTES
353
354At some point the EVP layer will begin enforcing the transitions described
355herein.
356
357=head1 SEE ALSO
358
359L<provider-cipher(7)>, L<EVP_EncryptInit(3)>
360
361=head1 COPYRIGHT
362
363Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
364
365Licensed under the Apache License 2.0 (the "License").  You may not use
366this file except in compliance with the License.  You can obtain a copy
367in the file LICENSE in the source distribution or at
368L<https://www.openssl.org/source/license.html>.
369
370=cut
371