1LIFE_CYCLE-PKEY(7ossl) OpenSSL LIFE_CYCLE-PKEY(7ossl)
2
6 life_cycle-pkey - The PKEY algorithm life-cycle
7
9 All public keys (PKEYs) go through a number of stages in their life-
10 cycle:
11 start
13 This state represents the PKEY before it has been allocated. It is
14 the starting state for any life-cycle transitions.
15 newed
17 This state represents the PKEY after it has been allocated.
18 decapsulate
20 This state represents the PKEY when it is ready to perform a
21 private key decapsulation opeartion.
22 decrypt
24 This state represents the PKEY when it is ready to decrypt some
25 ciphertext.
26 derive
28 This state represents the PKEY when it is ready to derive a shared
29 secret.
30 digest sign
32 This state represents the PKEY when it is ready to perform a
33 private key signature operation.
34 encapsulate
36 This state represents the PKEY when it is ready to perform a public
37 key encapsulation opeartion.
38 encrypt
40 This state represents the PKEY when it is ready to encrypt some
41 plaintext.
42 key generation
44 This state represents the PKEY when it is ready to generate a new
45 public/private key.
46 parameter generation
48 This state represents the PKEY when it is ready to generate key
49 parameters.
50 verify
52 This state represents the PKEY when it is ready to verify a public
53 key signature.
54 verify recover
56 This state represents the PKEY when it is ready to recover a public
57 key signature data.
58 freed
60 This state is entered when the PKEY is freed. It is the terminal
61 state for all life-cycle transitions.
62 State Transition Diagram
64 The usual life-cycle of a PKEY object is illustrated:
65 +-------------+
66 | |
67 | start |
68 | |
69 EVP_PKEY_derive +-------------+
70 +-------------+ EVP_PKEY_derive_set_peer |
71 +-------------+
72 | |----------------------------+ |
73 +----------------------------| |
74 | derive | | |
75 | EVP_PKEY_verify | verify |
76 | |<---------------------------+ |
77 +--------------------------->| |
78 +-------------+ |
79 +-------------+
80 ^ |
81 ^
82 | EVP_PKEY_derive_init |
83 EVP_PKEY_verify_init |
84 +---------------------------------------+ |
85 +---------------------------------------+
86 | | |
87 +-------------+ | | |
88 +-------------+
89 | |----------------------------+ | | |
90 +----------------------------| |
91 | digest sign | EVP_PKEY_sign | | | |
92 | EVP_PKEY_verify_recover | verify |
93 | |<---------------------------+ | | |
94 +--------------------------->| recover |
95 +-------------+ | | |
96 +-------------+
97 ^ | | |
98 ^
99 | EVP_PKEY_sign_init | | |
100 EVP_PKEY_verify_recover_init |
101 +---------------------------------+ | | |
102 +---------------------------------+
103 | | | | |
104 +-------------+ | | | | |
105 +-------------+
106 | |----------------------------+ | | | | |
107 +----------------------------| |
108 | decapsulate | EVP_PKEY_decapsulate | | | | | |
109 | EVP_PKEY_decrypt | decrypt |
110 | |<---------------------------+ | | v | |
111 +--------------------------->| |
112 +-------------+ | +-------------+ |
113 +-------------+
114 ^ +---| |---+
115 ^
116 | EVP_PKEY_decapsulate_init | |
117 EVP_PKEY_decrypt_init |
118 +-------------------------------------| newed
119 |-------------------------------------+
120 | |
121 +---| |---+
122 +-------------+ | +-------------+ |
123 +-------------+
124 | |----------------------------+ | | | |
125 +----------------------------| |
126 | encapsulate | EVP_PKEY_encapsulate | | | | |
127 | EVP_PKEY_encrypt | encrypt |
128 | |<---------------------------+ | | | |
129 +--------------------------->| |
130 +-------------+ | | | |
131 +-------------+
132 ^ | | | |
133 ^
134 | EVP_PKEY_encapsulate_init | | | |
135 EVP_PKEY_encrypt_init |
136 +---------------------------------+ | |
137 +---------------------------------+
138 | |
139 +---------------------------------------+
140 +---------------------------------------+
141 | EVP_PKEY_paramgen_init
142 EVP_PKEY_keygen_init |
143 v
144 v
145 +-------------+
146 +-------------+
147 | |----------------------------+
148 +----------------------------| |
149 | parameter | |
150 | | key |
151 | generation |<---------------------------+
152 +--------------------------->| generation |
153 +-------------+ EVP_PKEY_paramgen
154 EVP_PKEY_keygen +-------------+
155 EVP_PKEY_gen
156 EVP_PKEY_gen
157 + - - - - - +
160 +-----------+
161 ' ' EVP_PKEY_CTX_free |
162 |
163 ' any state '------------------->|
164 freed |
165 ' ' |
166 |
167 + - - - - - +
168 +-----------+
169 Formal State Transitions
171 This section defines all of the legal state transitions. This is the
172 canonical list.
173 Function Call
174 ----------------------------------------------------------------------
175 Current State
176 ----------------------------------------------------------------------
177 start newed digest verify
178 verify encrypt decrypt derive encapsulate
179 decapsulate parameter key freed
180 sign
181 recover
182 generation generation
183 EVP_PKEY_CTX_new newed
184 EVP_PKEY_CTX_new_id newed
185 EVP_PKEY_CTX_new_from_name newed
186 EVP_PKEY_CTX_new_from_pkey newed
187 EVP_PKEY_sign_init digest digest digest
188 digest digest digest digest digest digest
189 digest digest
190 sign sign sign
191 sign sign sign sign sign sign
192 sign sign
193 EVP_PKEY_sign digest
194 sign
195 EVP_PKEY_verify_init verify verify verify
196 verify verify verify verify verify verify
197 verify verify
198 EVP_PKEY_verify verify
199 EVP_PKEY_verify_recover_init verify verify verify
200 verify verify verify verify verify verify
201 verify verify
202 recover recover
203 recover recover recover recover recover
204 recover recover recover recover
205 EVP_PKEY_verify_recover
206 verify
207 recover
208 EVP_PKEY_encrypt_init encrypt encrypt
209 encrypt encrypt encrypt encrypt encrypt
210 encrypt encrypt encrypt encrypt
211 EVP_PKEY_encrypt
212 encrypt
213 EVP_PKEY_decrypt_init decrypt decrypt
214 decrypt decrypt decrypt decrypt decrypt
215 decrypt decrypt decrypt decrypt
216 EVP_PKEY_decrypt
217 decrypt
218 EVP_PKEY_derive_init derive derive derive
219 derive derive derive derive derive derive
220 derive derive
221 EVP_PKEY_derive_set_peer
222 derive
223 EVP_PKEY_derive
224 derive
225 EVP_PKEY_encapsulate_init encapsulate encapsulate
226 encapsulate encapsulate encapsulate encapsulate encapsulate
227 encapsulate encapsulate encapsulate encapsulate
228 EVP_PKEY_encapsulate
229 encapsulate
230 EVP_PKEY_decapsulate_init decapsulate decapsulate
231 decapsulate decapsulate decapsulate decapsulate decapsulate
232 decapsulate decapsulate decapsulate decapsulate
233 EVP_PKEY_decapsulate
234 decapsulate
235 EVP_PKEY_paramgen_init parameter parameter
236 parameter parameter parameter parameter parameter
237 parameter parameter parameter parameter
238 generation generation
239 generation generation generation generation generation
240 generation generation generation generation
241 EVP_PKEY_paramgen
242 parameter
243 generation
244 EVP_PKEY_keygen_init key key key
245 key key key key key key
246 key key
247 generation generation
248 generation generation generation generation generation
249 generation generation generation generation
250 EVP_PKEY_keygen
251 key
252 generation
253 EVP_PKEY_gen
254 parameter key
255 generation
256 generation
257 EVP_PKEY_CTX_get_params newed digest verify
258 verify encrypt decrypt derive encapsulate
259 decapsulate parameter key
260 sign
261 recover
262 generation generation
263 EVP_PKEY_CTX_set_params newed digest verify
264 verify encrypt decrypt derive encapsulate
265 decapsulate parameter key
266 sign
267 recover
268 generation generation
269 EVP_PKEY_CTX_gettable_params newed digest verify
270 verify encrypt decrypt derive encapsulate
271 decapsulate parameter key
272 sign
273 recover
274 generation generation
275 EVP_PKEY_CTX_settable_params newed digest verify
276 verify encrypt decrypt derive encapsulate
277 decapsulate parameter key
278 sign
279 recover
280 generation generation
281 EVP_PKEY_CTX_free freed freed freed freed
282 freed freed freed freed freed freed
283 freed freed
284
286 At some point the EVP layer will begin enforcing the transitions
287 described herein.
288
290 EVP_PKEY_new(3), EVP_PKEY_decapsulate(3), EVP_PKEY_decrypt(3),
291 EVP_PKEY_encapsulate(3), EVP_PKEY_encrypt(3), EVP_PKEY_derive(3),
292 EVP_PKEY_keygen(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3),
293 EVP_PKEY_verify_recover(3)
294
296 The provider PKEY interface was introduced in OpenSSL 3.0.
297
299 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
300 Licensed under the Apache License 2.0 (the "License"). You may not use
302 this file except in compliance with the License. You can obtain a copy
303 in the file LICENSE in the source distribution or at
304 <https://www.openssl.org/source/license.html>.
3053.0.5 2022-07-05 LIFE_CYCLE-PKEY(7ossl)