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