]>
Commit | Line | Data |
---|---|---|
5a285add DM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF_CTX, EVP_KDF_CTX_new_id, EVP_KDF_CTX_free, EVP_KDF_reset, | |
6 | EVP_KDF_ctrl, EVP_KDF_vctrl, EVP_KDF_ctrl_str, EVP_KDF_size, | |
7 | EVP_KDF_derive - EVP KDF routines | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/kdf.h> | |
12 | ||
13 | typedef struct evp_kdf_ctx_st EVP_KDF_CTX; | |
14 | ||
15 | EVP_KDF_CTX *EVP_KDF_CTX_new_id(int id); | |
16 | void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx); | |
17 | void EVP_KDF_reset(EVP_KDF_CTX *ctx); | |
18 | int EVP_KDF_ctrl(EVP_KDF_CTX *ctx, int cmd, ...); | |
19 | int EVP_KDF_vctrl(EVP_KDF_CTX *ctx, int cmd, va_list args); | |
20 | int EVP_KDF_ctrl_str(EVP_KDF_CTX *ctx, const char *type, const char *value); | |
21 | size_t EVP_KDF_size(EVP_KDF_CTX *ctx); | |
22 | int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen); | |
23 | ||
24 | =head1 DESCRIPTION | |
25 | ||
26 | The EVP KDF routines are a high level interface to Key Derivation Function | |
27 | algorithms and should be used instead of algorithm-specific functions. | |
28 | ||
29 | After creating a C<EVP_KDF_CTX> for the required algorithm using | |
30 | EVP_KDF_CTX_new_id(), inputs to the algorithm are supplied using calls to | |
31 | EVP_KDF_ctrl(), EVP_KDF_vctrl() or EVP_KDF_ctrl_str() before calling | |
32 | EVP_KDF_derive() to derive the key. | |
33 | ||
34 | =head2 Types | |
35 | ||
36 | B<EVP_KDF_CTX> is a context type that holds the algorithm inputs. | |
37 | ||
38 | =head2 Context manipulation functions | |
39 | ||
40 | EVP_KDF_CTX_new_id() creates a KDF context for the algorithm identified by the | |
41 | specified NID. | |
42 | ||
43 | EVP_KDF_CTX_free() frees up the context C<ctx>. If C<ctx> is C<NULL>, nothing | |
44 | is done. | |
45 | ||
46 | =head2 Computing functions | |
47 | ||
48 | EVP_KDF_reset() resets the context to the default state as if the context | |
49 | had just been created. | |
50 | ||
51 | EVP_KDF_ctrl() is used to provide inputs to the KDF algorithm prior to | |
52 | EVP_KDF_derive() being called. The inputs that may be provided will vary | |
53 | depending on the KDF algorithm or its implementation. This functions takes | |
54 | variable arguments, the exact expected arguments depend on C<cmd>. | |
55 | See L</CONTROLS> below for a description of standard controls. | |
56 | ||
57 | EVP_KDF_vctrl() is the variant of EVP_KDF_ctrl() that takes a C<va_list> | |
58 | argument instead of variadic arguments. | |
59 | ||
60 | EVP_KDF_ctrl_str() allows an application to send an algorithm specific control | |
61 | operation to a context C<ctx> in string form. This is intended to be used for | |
62 | options specified on the command line or in text files. | |
63 | ||
64 | EVP_KDF_size() returns the output size if the algorithm produces a fixed amount | |
65 | of output and C<SIZE_MAX> otherwise. If an error occurs then 0 is returned. | |
66 | For some algorithms an error may result if input parameters necessary to | |
67 | calculate a fixed output size have not yet been supplied. | |
68 | ||
69 | EVP_KDF_derive() derives C<keylen> bytes of key material and places it in the | |
70 | C<key> buffer. If the algorithm produces a fixed amount of output then an | |
71 | error will occur unless the C<keylen> parameter is equal to that output size, | |
72 | as returned by EVP_KDF_size(). | |
73 | ||
74 | =head1 CONTROLS | |
75 | ||
76 | The standard controls are: | |
77 | ||
78 | =over 4 | |
79 | ||
80 | =item B<EVP_KDF_CTRL_SET_PASS> | |
81 | ||
82 | This control expects two arguments: C<unsigned char *pass>, C<size_t passlen> | |
83 | ||
84 | Some KDF implementations require a password. For those KDF implementations | |
85 | that support it, this control sets the password. | |
86 | ||
87 | EVP_KDF_ctrl_str() takes two type strings for this control: | |
88 | ||
89 | =over 4 | |
90 | ||
91 | =item "pass" | |
92 | ||
93 | The value string is used as is. | |
94 | ||
95 | =item "hexpass" | |
96 | ||
97 | The value string is expected to be a hexadecimal number, which will be | |
98 | decoded before being passed on as the control value. | |
99 | ||
100 | =back | |
101 | ||
102 | =item B<EVP_KDF_CTRL_SET_SALT> | |
103 | ||
104 | This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen> | |
105 | ||
106 | Some KDF implementations can take a salt. For those KDF implementations that | |
107 | support it, this control sets the salt. | |
108 | ||
109 | The default value, if any, is implementation dependent. | |
110 | ||
111 | EVP_KDF_ctrl_str() takes two type strings for this control: | |
112 | ||
113 | =over 4 | |
114 | ||
115 | =item "salt" | |
116 | ||
117 | The value string is used as is. | |
118 | ||
119 | =item "hexsalt" | |
120 | ||
121 | The value string is expected to be a hexadecimal number, which will be | |
122 | decoded before being passed on as the control value. | |
123 | ||
124 | =back | |
125 | ||
126 | =item B<EVP_KDF_CTRL_SET_ITER> | |
127 | ||
128 | This control expects one argument: C<int iter> | |
129 | ||
130 | Some KDF implementations require an iteration count. For those KDF implementations that support it, this control sets the iteration count. | |
131 | ||
132 | The default value, if any, is implementation dependent. | |
133 | ||
134 | EVP_KDF_ctrl_str() type string: "iter" | |
135 | ||
136 | The value string is expected to be a decimal number. | |
137 | ||
9537fe57 SL |
138 | =item B<EVP_KDF_CTRL_SET_MAC> |
139 | ||
140 | This control expects one argument: C<EVP_MAC *mac> | |
141 | ||
142 | Some KDF implementations use a MAC as an underlying computation | |
143 | algorithm, this control sets what the MAC algorithm should be. | |
144 | ||
145 | EVP_KDF_ctrl_str() type string: "mac" | |
146 | ||
147 | The value string is expected to be the name of a MAC. | |
148 | ||
5a285add DM |
149 | =item B<EVP_KDF_CTRL_SET_MD> |
150 | ||
151 | This control expects one argument: C<EVP_MD *md> | |
152 | ||
153 | For MAC implementations that use a message digest as an underlying computation | |
154 | algorithm, this control set what the digest algorithm should be. | |
155 | ||
156 | EVP_KDF_ctrl_str() type string: "md" | |
157 | ||
158 | The value string is expected to be the name of a digest. | |
159 | ||
160 | =item B<EVP_KDF_CTRL_SET_KEY> | |
161 | ||
162 | This control expects two arguments: C<unsigned char *key>, C<size_t keylen> | |
163 | ||
164 | Some KDF implementations require a key. For those KDF implementations that | |
165 | support it, this control sets the key. | |
166 | ||
167 | EVP_KDF_ctrl_str() takes two type strings for this control: | |
168 | ||
169 | =over 4 | |
170 | ||
171 | =item "key" | |
172 | ||
173 | The value string is used as is. | |
174 | ||
175 | =item "hexkey" | |
176 | ||
177 | The value string is expected to be a hexadecimal number, which will be | |
178 | decoded before being passed on as the control value. | |
179 | ||
180 | =back | |
181 | ||
9537fe57 SL |
182 | =item B<EVP_KDF_CTRL_SET_MAC_SIZE> |
183 | ||
184 | This control expects one argument: C<size_t size> | |
185 | ||
186 | Used by implementations that use a MAC with a variable output size (KMAC). For | |
187 | those KDF implementations that support it, this control sets the MAC output size. | |
188 | ||
189 | The default value, if any, is implementation dependent. | |
190 | ||
191 | EVP_KDF_ctrl_str() type string: "outlen" | |
192 | ||
193 | The value string is expected to be a decimal number. | |
194 | ||
5a285add DM |
195 | =item B<EVP_KDF_CTRL_SET_MAXMEM_BYTES> |
196 | ||
197 | This control expects one argument: C<uint64_t maxmem_bytes> | |
198 | ||
199 | Memory-hard password-based KDF algorithms, such as scrypt, use an amount of | |
200 | memory that depends on the load factors provided as input. For those KDF | |
201 | implementations that support it, this control sets an upper limit on the amount | |
202 | of memory that may be consumed while performing a key derivation. If this | |
203 | memory usage limit is exceeded because the load factors are chosen too high, | |
204 | the key derivation will fail. | |
205 | ||
206 | The default value is implementation dependent. | |
207 | ||
208 | EVP_KDF_ctrl_str() type string: "maxmem_bytes" | |
209 | ||
210 | The value string is expected to be a decimal number. | |
211 | ||
212 | =back | |
213 | ||
214 | =head1 RETURN VALUES | |
215 | ||
216 | EVP_KDF_CTX_new_id() returns either the newly allocated C<EVP_KDF_CTX> | |
217 | structure or C<NULL> if an error occurred. | |
218 | ||
219 | EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value. | |
220 | ||
221 | EVP_KDF_size() returns the output size. C<SIZE_MAX> is returned to indicate | |
222 | that the algorithm produces a variable amount of output; 0 to indicate failure. | |
223 | ||
224 | The remaining functions return 1 for success and 0 or a negative value for | |
225 | failure. In particular, a return value of -2 indicates the operation is not | |
226 | supported by the KDF algorithm. | |
227 | ||
228 | =head1 SEE ALSO | |
229 | ||
230 | L<EVP_KDF_SCRYPT(7)> | |
9537fe57 SL |
231 | L<EVP_KDF_TLS1_PRF(7)> |
232 | L<EVP_KDF_PBKDF2(7)> | |
233 | L<EVP_KDF_HKDF(7)> | |
234 | L<EVP_KDF_SS(7)> | |
235 | ||
236 | =head1 HISTORY | |
237 | ||
238 | This functionality was added to OpenSSL 3.0.0. | |
5a285add DM |
239 | |
240 | =head1 COPYRIGHT | |
241 | ||
9537fe57 | 242 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. |
5a285add DM |
243 | |
244 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
245 | this file except in compliance with the License. You can obtain a copy | |
246 | in the file LICENSE in the source distribution or at | |
247 | L<https://www.openssl.org/source/license.html>. | |
248 | ||
249 | =cut |