Debian Codegraph @

upstream/debian-unstable/man7/life_cycle-cipher.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-CIPHER 7SSL"
58 .TH LIFE_CYCLE-CIPHER 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\-cipher \- The cipher algorithm life\-cycle
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 All symmetric ciphers (CIPHERs) go through a number of stages in their
68 life-cycle:
69 .IP start 4
70 .IX Item "start"
71 This state represents the CIPHER before it has been allocated. It is the
72 starting state for any life-cycle transitions.
73 .IP newed 4
74 .IX Item "newed"
75 This state represents the CIPHER after it has been allocated.
76 .IP initialised 4
77 .IX Item "initialised"
78 These states represent the CIPHER when it is set up and capable of processing
79 input. There are three possible initialised states:
80 .RS 4
81 .IP "initialised using EVP_CipherInit" 4
82 .IX Item "initialised using EVP_CipherInit"
83 .PD 0
84 .IP "initialised for decryption using EVP_DecryptInit" 4
85 .IX Item "initialised for decryption using EVP_DecryptInit"
86 .IP "initialised for encryption using EVP_EncryptInit" 4
87 .IX Item "initialised for encryption using EVP_EncryptInit"
88 .RE
89 .RS 4
90 .RE
91 .IP updated 4
92 .IX Item "updated"
93 .PD
94 These states represent the CIPHER when it is set up and capable of processing
95 additional input or generating output. The three possible states directly
96 correspond to those for initialised above. The three different streams should
97 not be mixed.
98 .IP finaled 4
99 .IX Item "finaled"
100 This state represents the CIPHER when it has generated output.
101 .IP freed 4
102 .IX Item "freed"
103 This state is entered when the CIPHER is freed. It is the terminal state
104 for all life-cycle transitions.
105 .SS "State Transition Diagram"
106 .IX Subsection "State Transition Diagram"
107 The usual life-cycle of a CIPHER is illustrated:
108 +---------------------------+
109 | |
110 | start |
111 | |
112 +---------------------------+ + - - - - - - - - - - - - - +
113 | ' any of the initialised '
114 | EVP_CIPHER_CTX_new ' updated or finaled states '
115 v ' '
116 +---------------------------+ + - - - - - - - - - - - - - +
117 | | |
118 | newed | | EVP_CIPHER_CTX_reset
119 | | <----+
120 +---------------------------+
121 | | |
122 +---------+ | +---------+
123 EVP_DecryptInit | | EVP_CipherInit | EVP_EncryptInit
124 v v v
125 +---------------------------+ +---------------------------+ +---------------------------+
126 | | | | | |
127 | initialised | | initialised | | initialised |
128 | for decryption | | | | for encryption |
129 +---------------------------+ +---------------------------+ +---------------------------+
130 | | |
131 | EVP_DecryptUpdate | EVP_CipherUpdate EVP_EncryptUpdate |
132 | v |
133 | +---------------------------+ |
134 | | |--------------------+ |
135 | | updated | EVP_CipherUpdate | |
136 | | | <------------------+ |
137 v +---------------------------+ v
138 +---------------------------+ | +---------------------------+
139 | |---------------------+ | | |
140 | updated | EVP_DecryptUpdate | | | updated |------+
141 | for decryption | <-------------------+ | | for encryption | |
142 +---------------------------+ | +---------------------------+ |
143 | EVP_CipherFinal | | ^ |
144 +-------+ | +--------+ | |
145 EVP_DecryptFinal | | | EVP_EncryptFinal +-------------------+
146 v v v EVP_EncryptUpdate
147 +---------------------------+
148 | |-----------------------------+
149 | finaled | |
150 | | <---------------------------+
151 +---------------------------+ EVP_CIPHER_CTX_get_params
152 | (AEAD encryption)
153 | EVP_CIPHER_CTX_free
154 v
155 +---------------------------+
156 | |
157 | freed |
158 | |
159 +---------------------------+
160 .SS "Formal State Transitions"
161 .IX Subsection "Formal State Transitions"
162 This section defines all of the legal state transitions.
163 This is the canonical list.
164 Function Call ---------------------------------------------- Current State -----------------------------------------------
165 start newed initialised updated finaled initialised updated initialised updated freed
166 decryption decryption encryption encryption
167 EVP_CIPHER_CTX_new newed
168 EVP_CipherInit initialised initialised initialised initialised initialised initialised initialised initialised
169 EVP_DecryptInit initialised initialised initialised initialised initialised initialised initialised initialised
170 decryption decryption decryption decryption decryption decryption decryption decryption
171 EVP_EncryptInit initialised initialised initialised initialised initialised initialised initialised initialised
172 encryption encryption encryption encryption encryption encryption encryption encryption
173 EVP_CipherUpdate updated updated
174 EVP_DecryptUpdate updated updated
175 decryption decryption
176 EVP_EncryptUpdate updated updated
177 encryption encryption
178 EVP_CipherFinal finaled
179 EVP_DecryptFinal finaled
180 EVP_EncryptFinal finaled
181 EVP_CIPHER_CTX_free freed freed freed freed freed freed freed freed freed
182 EVP_CIPHER_CTX_reset newed newed newed newed newed newed newed newed
183 EVP_CIPHER_CTX_get_params newed initialised updated initialised updated initialised updated
184 decryption decryption encryption encryption
185 EVP_CIPHER_CTX_set_params newed initialised updated initialised updated initialised updated
186 decryption decryption encryption encryption
187 EVP_CIPHER_CTX_gettable_params newed initialised updated initialised updated initialised updated
188 decryption decryption encryption encryption
189 EVP_CIPHER_CTX_settable_params newed initialised updated initialised updated initialised updated
190 decryption decryption encryption encryption
191 .SH NOTES
192 .IX Header "NOTES"
193 At some point the EVP layer will begin enforcing the transitions described
194 herein.
195 .SH "SEE ALSO"
196 .IX Header "SEE ALSO"
197 \&\fBprovider\-cipher\fR\|(7), \fBEVP_EncryptInit\fR\|(3)
198 .SH COPYRIGHT
199 .IX Header "COPYRIGHT"
200 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
201 .PP
202 Licensed under the Apache License 2.0 (the "License"). You may not use
203 this file except in compliance with the License. You can obtain a copy
204 in the file LICENSE in the source distribution or at
205 <https://www.openssl.org/source/license.html>.