Debian Codegraph @

upstream/debian-unstable/man7/life_cycle-pkey.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "LIFE_CYCLE-PKEY 7SSL"
58 .TH LIFE_CYCLE-PKEY 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 life_cycle\-pkey \- The PKEY algorithm life\-cycle
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 All public keys (PKEYs) go through a number of stages in their life-cycle:
68 .IP start 4
69 .IX Item "start"
70 This state represents the PKEY before it has been allocated. It is the
71 starting state for any life-cycle transitions.
72 .IP newed 4
73 .IX Item "newed"
74 This state represents the PKEY after it has been allocated.
75 .IP decapsulate 4
76 .IX Item "decapsulate"
77 This state represents the PKEY when it is ready to perform a private key decapsulation
78 operation.
79 .IP decrypt 4
80 .IX Item "decrypt"
81 This state represents the PKEY when it is ready to decrypt some ciphertext.
82 .IP derive 4
83 .IX Item "derive"
84 This state represents the PKEY when it is ready to derive a shared secret.
85 .IP "digest sign" 4
86 .IX Item "digest sign"
87 This state represents the PKEY when it is ready to perform a private key signature
88 operation.
89 .IP encapsulate 4
90 .IX Item "encapsulate"
91 This state represents the PKEY when it is ready to perform a public key encapsulation
92 operation.
93 .IP encrypt 4
94 .IX Item "encrypt"
95 This state represents the PKEY when it is ready to encrypt some plaintext.
96 .IP "key generation" 4
97 .IX Item "key generation"
98 This state represents the PKEY when it is ready to generate a new public/private key.
99 .IP "parameter generation" 4
100 .IX Item "parameter generation"
101 This state represents the PKEY when it is ready to generate key parameters.
102 .IP verify 4
103 .IX Item "verify"
104 This state represents the PKEY when it is ready to verify a public key signature.
105 .IP "verify recover" 4
106 .IX Item "verify recover"
107 This state represents the PKEY when it is ready to recover a public key signature data.
108 .IP freed 4
109 .IX Item "freed"
110 This state is entered when the PKEY is freed. It is the terminal state
111 for all life-cycle transitions.
112 .SS "State Transition Diagram"
113 .IX Subsection "State Transition Diagram"
114 The usual life-cycle of a PKEY object is illustrated:
115 +-------------+
116 | |
117 | start |
118 | |
119 EVP_PKEY_derive +-------------+
120 +-------------+ EVP_PKEY_derive_set_peer | +-------------+
121 | |----------------------------+ | +----------------------------| |
122 | derive | | | | EVP_PKEY_verify | verify |
123 | |<---------------------------+ | +--------------------------->| |
124 +-------------+ | +-------------+
125 ^ | ^
126 | EVP_PKEY_derive_init | EVP_PKEY_verify_init |
127 +---------------------------------------+ | +---------------------------------------+
128 | | |
129 +-------------+ | | | +-------------+
130 | |----------------------------+ | | | +----------------------------| |
131 | digest sign | EVP_PKEY_sign | | | | | EVP_PKEY_verify_recover | verify |
132 | |<---------------------------+ | | | +--------------------------->| recover |
133 +-------------+ | | | +-------------+
134 ^ | | | ^
135 | EVP_PKEY_sign_init | | | EVP_PKEY_verify_recover_init |
136 +---------------------------------+ | | | +---------------------------------+
137 | | | | |
138 +-------------+ | | | | | +-------------+
139 | |----------------------------+ | | | | | +----------------------------| |
140 | decapsulate | EVP_PKEY_decapsulate | | | | | | | EVP_PKEY_decrypt | decrypt |
141 | |<---------------------------+ | | v | | +--------------------------->| |
142 +-------------+ | +-------------+ | +-------------+
143 ^ +---| |---+ ^
144 | EVP_PKEY_decapsulate_init | | EVP_PKEY_decrypt_init |
145 +-------------------------------------| newed |-------------------------------------+
146 | |
147 +---| |---+
148 +-------------+ | +-------------+ | +-------------+
149 | |----------------------------+ | | | | +----------------------------| |
150 | encapsulate | EVP_PKEY_encapsulate | | | | | | EVP_PKEY_encrypt | encrypt |
151 | |<---------------------------+ | | | | +--------------------------->| |
152 +-------------+ | | | | +-------------+
153 ^ | | | | ^
154 | EVP_PKEY_encapsulate_init | | | | EVP_PKEY_encrypt_init |
155 +---------------------------------+ | | +---------------------------------+
156 | |
157 +---------------------------------------+ +---------------------------------------+
158 | EVP_PKEY_paramgen_init EVP_PKEY_keygen_init |
159 v v
160 +-------------+ +-------------+
161 | |----------------------------+ +----------------------------| |
162 | parameter | | | | key |
163 | generation |<---------------------------+ +--------------------------->| generation |
164 +-------------+ EVP_PKEY_paramgen EVP_PKEY_keygen +-------------+
165 EVP_PKEY_gen EVP_PKEY_gen
166
167
168 + - - - - - + +-----------+
169 ' ' EVP_PKEY_CTX_free | |
170 ' any state '------------------->| freed |
171 ' ' | |
172 + - - - - - + +-----------+
173 .SS "Formal State Transitions"
174 .IX Subsection "Formal State Transitions"
175 This section defines all of the legal state transitions.
176 This is the canonical list.
177 Function Call ---------------------------------------------------------------------- Current State ----------------------------------------------------------------------
178 start newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key freed
179 sign recover generation generation
180 EVP_PKEY_CTX_new newed
181 EVP_PKEY_CTX_new_id newed
182 EVP_PKEY_CTX_new_from_name newed
183 EVP_PKEY_CTX_new_from_pkey newed
184 EVP_PKEY_sign_init digest digest digest digest digest digest digest digest digest digest digest
185 sign sign sign sign sign sign sign sign sign sign sign
186 EVP_PKEY_sign digest
187 sign
188 EVP_PKEY_verify_init verify verify verify verify verify verify verify verify verify verify verify
189 EVP_PKEY_verify verify
190 EVP_PKEY_verify_recover_init verify verify verify verify verify verify verify verify verify verify verify
191 recover recover recover recover recover recover recover recover recover recover recover
192 EVP_PKEY_verify_recover verify
193 recover
194 EVP_PKEY_encrypt_init encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt
195 EVP_PKEY_encrypt encrypt
196 EVP_PKEY_decrypt_init decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt
197 EVP_PKEY_decrypt decrypt
198 EVP_PKEY_derive_init derive derive derive derive derive derive derive derive derive derive derive
199 EVP_PKEY_derive_set_peer derive
200 EVP_PKEY_derive derive
201 EVP_PKEY_encapsulate_init encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate
202 EVP_PKEY_encapsulate encapsulate
203 EVP_PKEY_decapsulate_init decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate
204 EVP_PKEY_decapsulate decapsulate
205 EVP_PKEY_paramgen_init parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter
206 generation generation generation generation generation generation generation generation generation generation generation
207 EVP_PKEY_paramgen parameter
208 generation
209 EVP_PKEY_keygen_init key key key key key key key key key key key
210 generation generation generation generation generation generation generation generation generation generation generation
211 EVP_PKEY_keygen key
212 generation
213 EVP_PKEY_gen parameter key
214 generation generation
215 EVP_PKEY_CTX_get_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key
216 sign recover generation generation
217 EVP_PKEY_CTX_set_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key
218 sign recover generation generation
219 EVP_PKEY_CTX_gettable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key
220 sign recover generation generation
221 EVP_PKEY_CTX_settable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key
222 sign recover generation generation
223 EVP_PKEY_CTX_free freed freed freed freed freed freed freed freed freed freed freed freed
224 .SH NOTES
225 .IX Header "NOTES"
226 At some point the EVP layer will begin enforcing the transitions described
227 herein.
228 .SH "SEE ALSO"
229 .IX Header "SEE ALSO"
230 \&\fBEVP_PKEY_new\fR\|(3),
231 \&\fBEVP_PKEY_decapsulate\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_encapsulate\fR\|(3),
232 \&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_derive\fR\|(3), \fBEVP_PKEY_keygen\fR\|(3),
233 \&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify\fR\|(3), \fBEVP_PKEY_verify_recover\fR\|(3)
234 .SH HISTORY
235 .IX Header "HISTORY"
236 The provider PKEY interface was introduced in OpenSSL 3.0.
237 .SH COPYRIGHT
238 .IX Header "COPYRIGHT"
239 Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved.
240 .PP
241 Licensed under the Apache License 2.0 (the "License"). You may not use
242 this file except in compliance with the License. You can obtain a copy
243 in the file LICENSE in the source distribution or at
244 <https://www.openssl.org/source/license.html>.