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