Debian Codegraph @

upstream/debian-unstable/man7/life_cycle-digest.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-DIGEST 7SSL"
58 .TH LIFE_CYCLE-DIGEST 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\-digest \- The digest algorithm life\-cycle
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 All message digests (MDs) go through a number of stages in their life-cycle:
68 .IP start 4
69 .IX Item "start"
70 This state represents the MD 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 MD after it has been allocated.
75 .IP initialised 4
76 .IX Item "initialised"
77 This state represents the MD when it is set up and capable of processing
78 input.
79 .IP updated 4
80 .IX Item "updated"
81 This state represents the MD when it is set up and capable of processing
82 additional input or generating output.
83 .IP finaled 4
84 .IX Item "finaled"
85 This state represents the MD when it has generated output.
86 For an XOF digest, this state represents the MD when it has generated a
87 single-shot output.
88 .IP squeezed 4
89 .IX Item "squeezed"
90 For an XOF digest, this state represents the MD when it has generated output.
91 It can be called multiple times to generate more output. The output length is
92 variable for each call.
93 .IP freed 4
94 .IX Item "freed"
95 This state is entered when the MD is freed. It is the terminal state
96 for all life-cycle transitions.
97 .SS "State Transition Diagram"
98 .IX Subsection "State Transition Diagram"
99 The usual life-cycle of a MD is illustrated:
100 +--------------------+
101 | start |
102 +--------------------+
103 | EVP_MD_CTX_reset
104 | EVP_MD_CTX_new +-------------------------------------------------+
105 v v |
106 EVP_MD_CTX_reset + - - - - - - - - - - - - - - - - - - - - - - + EVP_MD_CTX_reset |
107 +-------------------> ' newed ' <--------------------+ |
108 | + - - - - - - - - - - - - - - - - - - - - - - + | |
109 | | | |
110 | | EVP_DigestInit | |
111 | v | |
112 | EVP_DigestInit + - - - - - - - - - - - - - - - - - - - - - - + | |
113 +----+-------------------> ' initialised ' <+ EVP_DigestInit | |
114 | | + - - - - - - - - - - - - - - - - - - - - - - + | | |
115 | | | ^ | | |
116 | | | EVP_DigestUpdate | EVP_DigestInit | | |
117 | | v | | | |
118 | | +---------------------------------------------+ | | |
119 | +-------------------- | | | | |
120 | | | | | |
121 | EVP_DigestUpdate | | | | |
122 | +-------------------- | | | | |
123 | | | updated | | | |
124 | +-------------------> | | | | |
125 | | | | | |
126 | | | | | |
127 +----+------------------------- | | -+-------------------+----+ |
128 | | +---------------------------------------------+ | | | |
129 | | | | | | |
130 | | | EVP_DigestSqueeze +-------------------+ | | |
131 | | v | | | |
132 | | EVP_DigestSqueeze +---------------------------------------------+ | | |
133 | | +-------------------- | | | | |
134 | | | | squeezed | | | |
135 | | +-------------------> | | ---------------------+ | |
136 | | +---------------------------------------------+ | |
137 | | | | |
138 | | +---------------------------------------+ | |
139 | | | | |
140 | | +---------------------------------------------+ EVP_DigestFinalXOF | | |
141 | +------------------------- | finaled | <--------------------+----+ |
142 | +---------------------------------------------+ | |
143 | EVP_DigestFinal ^ | | | |
144 +---------------------------------+ | | EVP_MD_CTX_free | |
145 | v | |
146 | +------------------+ EVP_MD_CTX_free | |
147 | | freed | <--------------------+ |
148 | +------------------+ |
149 | |
150 +------------------------------------------------------+
151 .SS "Formal State Transitions"
152 .IX Subsection "Formal State Transitions"
153 This section defines all of the legal state transitions.
154 This is the canonical list.
155 Function Call --------------------- Current State -----------------------------------
156 start newed initialised updated finaled squeezed freed
157 EVP_MD_CTX_new newed
158 EVP_DigestInit initialised initialised initialised initialised initialised
159 EVP_DigestUpdate updated updated
160 EVP_DigestFinal finaled
161 EVP_DigestFinalXOF finaled
162 EVP_DigestSqueeze squeezed squeezed
163 EVP_MD_CTX_free freed freed freed freed freed
164 EVP_MD_CTX_reset newed newed newed newed
165 EVP_MD_CTX_get_params newed initialised updated
166 EVP_MD_CTX_set_params newed initialised updated
167 EVP_MD_CTX_gettable_params newed initialised updated
168 EVP_MD_CTX_settable_params newed initialised updated
169 EVP_MD_CTX_copy_ex newed initialised updated squeezed
170 .SH NOTES
171 .IX Header "NOTES"
172 At some point the EVP layer will begin enforcing the transitions described
173 herein.
174 .SH "SEE ALSO"
175 .IX Header "SEE ALSO"
176 \&\fBprovider\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3)
177 .SH COPYRIGHT
178 .IX Header "COPYRIGHT"
179 Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved.
180 .PP
181 Licensed under the Apache License 2.0 (the "License"). You may not use
182 this file except in compliance with the License. You can obtain a copy
183 in the file LICENSE in the source distribution or at
184 <https://www.openssl.org/source/license.html>.