1=pod
2
3=head1 NAME
4
5life_cycle-kdf - The KDF algorithm life-cycle
6
7=head1 DESCRIPTION
8
9All key derivation functions (KDFs) and pseudo random functions (PRFs)
10go through a number of stages in their life-cycle:
11
12=over 4
13
14=item start
15
16This state represents the KDF/PRF before it has been allocated.  It is the
17starting state for any life-cycle transitions.
18
19=item newed
20
21This state represents the KDF/PRF after it has been allocated.
22
23=item deriving
24
25This state represents the KDF/PRF when it is set up and capable of generating
26output.
27
28=item freed
29
30This state is entered when the KDF/PRF is freed.  It is the terminal state
31for all life-cycle transitions.
32
33=back
34
35=head2 State Transition Diagram
36
37The usual life-cycle of a KDF/PRF is illustrated:
38
39=begin man
40
41                     +-------------------+
42                     |       start       |
43                     +-------------------+
44                       |
45                       | EVP_KDF_CTX_new
46                       v
47                     +-------------------+
48                     |       newed       | <+
49                     +-------------------+  |
50                       |                    |
51                       | EVP_KDF_derive     |
52                       v                    | EVP_KDF_CTX_reset
53    EVP_KDF_derive   +-------------------+  |
54  + - - - - - - - -  |                   |  |
55  '                  |     deriving      |  |
56  + - - - - - - - -> |                   | -+
57                     +-------------------+
58                       |
59                       | EVP_KDF_CTX_free
60                       v
61                     +-------------------+
62                     |       freed       |
63                     +-------------------+
64
65=end man
66
67=for html <img src="img/kdf.png">
68
69=head2 Formal State Transitions
70
71This section defines all of the legal state transitions.
72This is the canonical list.
73
74=begin man
75
76 Function Call                   ------------- Current State -------------
77                                 start       newed       deriving    freed
78 EVP_KDF_CTX_new                 newed
79 EVP_KDF_derive                             deriving     deriving
80 EVP_KDF_CTX_free                freed       freed        freed
81 EVP_KDF_CTX_reset                           newed        newed
82 EVP_KDF_CTX_get_params                      newed       deriving
83 EVP_KDF_CTX_set_params                      newed       deriving
84 EVP_KDF_CTX_gettable_params                 newed       deriving
85 EVP_KDF_CTX_settable_params                 newed       deriving
86
87=end man
88
89=begin html
90
91<table style="border:1px solid; border-collapse:collapse">
92<tr><th style="border:1px solid" align="left">Function Call</th>
93    <th style="border:1px solid" colspan="4">Current State</th></tr>
94<tr><th style="border:1px solid"></th>
95    <th style="border:1px solid" align="center">start</th>
96    <th style="border:1px solid" align="center">newed</th>
97    <th style="border:1px solid" align="center">deriving</th>
98    <th style="border:1px solid" align="center">freed</th></tr>
99<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_new</th>
100    <td style="border:1px solid" align="center">newed</td>
101    <td style="border:1px solid"></td>
102    <td style="border:1px solid"></td>
103    <td style="border:1px solid"></td></tr>
104<tr><th style="border:1px solid" align="left">EVP_KDF_derive</th>
105    <td style="border:1px solid" align="center"></td>
106    <td style="border:1px solid" align="center">deriving</td>
107    <td style="border:1px solid" align="center">deriving</td>
108    <td style="border:1px solid"></td></tr>
109<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_free</th>
110    <td style="border:1px solid" align="center">freed</td>
111    <td style="border:1px solid" align="center">freed</td>
112    <td style="border:1px solid" align="center">freed</td>
113    <td style="border:1px solid"></td></tr>
114<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_reset</th>
115    <td style="border:1px solid" align="center"></td>
116    <td style="border:1px solid" align="center">newed</td>
117    <td style="border:1px solid" align="center">newed</td>
118    <td style="border:1px solid"></td></tr>
119<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_get_params</th>
120    <td style="border:1px solid" align="center"></td>
121    <td style="border:1px solid" align="center">newed</td>
122    <td style="border:1px solid" align="center">deriving</td>
123    <td style="border:1px solid"></td></tr>
124<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_set_params</th>
125    <td style="border:1px solid" align="center"></td>
126    <td style="border:1px solid" align="center">newed</td>
127    <td style="border:1px solid" align="center">deriving</td>
128    <td style="border:1px solid"></td></tr>
129<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_gettable_params</th>
130    <td style="border:1px solid" align="center"></td>
131    <td style="border:1px solid" align="center">newed</td>
132    <td style="border:1px solid" align="center">deriving</td>
133    <td style="border:1px solid"></td></tr>
134<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_settable_params</th>
135    <td style="border:1px solid" align="center"></td>
136    <td style="border:1px solid" align="center">newed</td>
137    <td style="border:1px solid" align="center">deriving</td>
138    <td style="border:1px solid"></td></tr>
139</table>
140
141=end html
142
143=head1 NOTES
144
145At some point the EVP layer will begin enforcing the transitions described
146herein.
147
148=head1 SEE ALSO
149
150L<provider-kdf(7)>, L<EVP_KDF(3)>.
151
152=head1 HISTORY
153
154The provider KDF interface was introduced in OpenSSL 3.0.
155
156=head1 COPYRIGHT
157
158Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
159
160Licensed under the Apache License 2.0 (the "License").  You may not use
161this file except in compliance with the License.  You can obtain a copy
162in the file LICENSE in the source distribution or at
163L<https://www.openssl.org/source/license.html>.
164
165=cut
166