1LIFE_CYCLE-CIPHER(7ossl) OpenSSL LIFE_CYCLE-CIPHER(7ossl)
2
6 life_cycle-cipher - The cipher algorithm life-cycle
7
9 All symmetric ciphers (CIPHERs) go through a number of stages in their
10 life-cycle:
11 start
13 This state represents the CIPHER before it has been allocated. It
14 is the starting state for any life-cycle transitions.
15 newed
17 This state represents the CIPHER after it has been allocated.
18 initialised
20 These states represent the CIPHER when it is set up and capable of
21 processing input. There are three possible initialised states:
22 initialised using EVP_CipherInit
24 initialised for decryption using EVP_DecryptInit
25 initialised for encryption using EVP_EncryptInit
26 updated
27 These states represent the CIPHER when it is set up and capable of
28 processing additional input or generating output. The three
29 possible states directly correspond to those for initialised above.
30 The three different streams should not be mixed.
31 finaled
33 This state represents the CIPHER when it has generated output.
34 freed
36 This state is entered when the CIPHER is freed. It is the terminal
37 state for all life-cycle transitions.
38 State Transition Diagram
40 The usual life-cycle of a CIPHER is illustrated:
41 +---------------------------+
42 | |
43 | start |
44 | |
45 +---------------------------+ + - -
46 - - - - - - - - - - - +
47 | ' any
48 of the initialised '
49 | EVP_CIPHER_CTX_new '
50 updated or finaled states '
51 v '
52 '
53 +---------------------------+ + - -
54 - - - - - - - - - - - +
55 | | |
56 | newed | |
57 EVP_CIPHER_CTX_reset
58 | | <----+
59 +---------------------------+
60 | | |
61 +---------+ | +---------+
62 EVP_DecryptInit | | EVP_CipherInit |
63 EVP_EncryptInit
64 v v v
65 +---------------------------+ +---------------------------+
66 +---------------------------+
67 | | | | |
68 |
69 | initialised | | initialised | |
70 initialised |
71 | for decryption | | | |
72 for encryption |
73 +---------------------------+ +---------------------------+
74 +---------------------------+
75 | |
76 |
77 | EVP_DecryptUpdate | EVP_CipherUpdate
78 EVP_EncryptUpdate |
79 | v
80 |
81 | +---------------------------+
82 |
83 | |
84 |--------------------+ |
85 | | updated |
86 EVP_CipherUpdate | |
87 | | |
88 <------------------+ |
89 v +---------------------------+
90 v
91 +---------------------------+ |
92 +---------------------------+
93 | |---------------------+ | |
94 |
95 | updated | EVP_DecryptUpdate | | |
96 updated |------+
97 | for decryption | <-------------------+ | |
98 for encryption | |
99 +---------------------------+ |
100 +---------------------------+ |
101 | EVP_CipherFinal | |
102 ^ |
103 +-------+ | +--------+
104 | |
105 EVP_DecryptFinal | | |
106 EVP_EncryptFinal +-------------------+
107 v v v
108 EVP_EncryptUpdate
109 +---------------------------+
110 |
111 |-----------------------------+
112 | finaled |
113 |
114 | |
115 <---------------------------+
116 +---------------------------+
117 EVP_CIPHER_CTX_get_params
118 |
119 (AEAD encryption)
120 | EVP_CIPHER_CTX_free
121 v
122 +---------------------------+
123 | |
124 | freed |
125 | |
126 +---------------------------+
127 Formal State Transitions
129 This section defines all of the legal state transitions. This is the
130 canonical list.
131 Function Call
132 ---------------------------------------------- Current State
133 -----------------------------------------------
134 start newed initialised updated
135 finaled initialised updated initialised updated freed
136 decryption
137 decryption encryption encryption
138 EVP_CIPHER_CTX_new newed
139 EVP_CipherInit initialised initialised initialised
140 initialised initialised initialised initialised initialised
141 EVP_DecryptInit initialised initialised initialised
142 initialised initialised initialised initialised initialised
143 decryption decryption decryption
144 decryption decryption decryption decryption decryption
145 EVP_EncryptInit initialised initialised initialised
146 initialised initialised initialised initialised initialised
147 encryption encryption encryption
148 encryption encryption encryption encryption encryption
149 EVP_CipherUpdate updated updated
150 EVP_DecryptUpdate
151 updated updated
152 decryption
153 decryption
154 EVP_EncryptUpdate
155 updated updated
156 encryption
157 encryption
158 EVP_CipherFinal finaled
159 EVP_DecryptFinal
160 finaled
161 EVP_EncryptFinal
162 finaled
163 EVP_CIPHER_CTX_free freed freed freed freed
164 freed freed freed freed freed
165 EVP_CIPHER_CTX_reset newed newed newed
166 newed newed newed newed newed
167 EVP_CIPHER_CTX_get_params newed initialised updated
168 initialised updated initialised updated
169 decryption
170 decryption encryption encryption
171 EVP_CIPHER_CTX_set_params newed initialised updated
172 initialised updated initialised updated
173 decryption
174 decryption encryption encryption
175 EVP_CIPHER_CTX_gettable_params newed initialised updated
176 initialised updated initialised updated
177 decryption
178 decryption encryption encryption
179 EVP_CIPHER_CTX_settable_params newed initialised updated
180 initialised updated initialised updated
181 decryption
182 decryption encryption encryption
183
185 At some point the EVP layer will begin enforcing the transitions
186 described herein.
187
189 provider-cipher(7), EVP_EncryptInit(3)
190
192 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
193 Licensed under the Apache License 2.0 (the "License"). You may not use
195 this file except in compliance with the License. You can obtain a copy
196 in the file LICENSE in the source distribution or at
197 <https://www.openssl.org/source/license.html>.
1983.0.9 2023-07-27 LIFE_CYCLE-CIPHER(7ossl)