]>
Commit | Line | Data |
---|---|---|
65ce7e65 P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
251e610c | 5 | EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref, |
660c5344 | 6 | EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup, |
1ba21239 SL |
7 | EVP_KDF_CTX_reset, EVP_KDF_derive, |
8 | EVP_KDF_CTX_get_kdf_size, EVP_KDF_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a, | |
c9452d74 | 9 | EVP_KDF_number, EVP_KDF_name, EVP_KDF_names_do_all, |
660c5344 | 10 | EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided, |
41f7ecf3 | 11 | EVP_KDF_get_params, EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params, |
65ce7e65 P |
12 | EVP_KDF_gettable_params - EVP KDF routines |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/kdf.h> | |
17 | ||
18 | typedef struct evp_kdf_st EVP_KDF; | |
19 | typedef struct evp_kdf_ctx_st EVP_KDF_CTX; | |
20 | ||
660c5344 MC |
21 | EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf); |
22 | const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx); | |
23 | void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx); | |
24 | EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src); | |
1ba21239 SL |
25 | void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx); |
26 | size_t EVP_KDF_CTX_get_kdf_size(EVP_KDF_CTX *ctx); | |
65ce7e65 | 27 | int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen); |
65ce7e65 P |
28 | int EVP_KDF_up_ref(EVP_KDF *kdf); |
29 | void EVP_KDF_free(EVP_KDF *kdf); | |
b4250010 | 30 | EVP_KDF *EVP_KDF_fetch(OSSL_LIB_CTX *libctx, const char *algorithm, |
65ce7e65 | 31 | const char *properties); |
506cb0f6 | 32 | int EVP_KDF_number(const EVP_KDF *kdf); |
251e610c | 33 | int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name); |
c9452d74 | 34 | const char *EVP_KDF_name(const EVP_KDF *kdf); |
251e610c | 35 | const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf); |
b4250010 | 36 | void EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx, |
251e610c RL |
37 | void (*fn)(EVP_KDF *kdf, void *arg), |
38 | void *arg); | |
d84f5515 MC |
39 | int EVP_KDF_names_do_all(const EVP_KDF *kdf, |
40 | void (*fn)(const char *name, void *data), | |
41 | void *data); | |
65ce7e65 | 42 | int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]); |
660c5344 MC |
43 | int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]); |
44 | int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]); | |
65ce7e65 | 45 | const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf); |
41f7ecf3 P |
46 | const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf); |
47 | const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf); | |
65ce7e65 P |
48 | const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf); |
49 | ||
50 | =head1 DESCRIPTION | |
51 | ||
8c1cbc72 | 52 | The EVP KDF routines are a high-level interface to Key Derivation Function |
65ce7e65 P |
53 | algorithms and should be used instead of algorithm-specific functions. |
54 | ||
55 | After creating a B<EVP_KDF_CTX> for the required algorithm using | |
660c5344 MC |
56 | EVP_KDF_CTX_new(), inputs to the algorithm are supplied |
57 | using calls to EVP_KDF_CTX_set_params() before | |
65ce7e65 P |
58 | calling EVP_KDF_derive() to derive the key. |
59 | ||
60 | =head2 Types | |
61 | ||
62 | B<EVP_KDF> is a type that holds the implementation of a KDF. | |
63 | ||
64 | B<EVP_KDF_CTX> is a context type that holds the algorithm inputs. | |
65 | ||
66 | =head2 Algorithm implementation fetching | |
67 | ||
68 | EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given | |
69 | a library context I<libctx> and a set of I<properties>. | |
70 | See L<provider(7)/Fetching algorithms> for further information. | |
71 | ||
b8086652 SL |
72 | See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of |
73 | algorithms supported by the default provider. | |
74 | ||
65ce7e65 P |
75 | The returned value must eventually be freed with |
76 | L<EVP_KDF_free(3)>. | |
77 | ||
78 | EVP_KDF_up_ref() increments the reference count of an already fetched | |
79 | KDF. | |
80 | ||
81 | EVP_KDF_free() frees a fetched algorithm. | |
82 | NULL is a valid parameter, for which this function is a no-op. | |
83 | ||
84 | =head2 Context manipulation functions | |
85 | ||
660c5344 | 86 | EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>. |
65ce7e65 | 87 | |
660c5344 | 88 | EVP_KDF_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing |
65ce7e65 P |
89 | is done. |
90 | ||
660c5344 | 91 | EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context |
65ce7e65 P |
92 | I<ctx>. |
93 | ||
94 | =head2 Computing functions | |
95 | ||
a49d0a49 | 96 | EVP_KDF_CTX_reset() resets the context to the default state as if the context |
65ce7e65 P |
97 | had just been created. |
98 | ||
ee2161e8 | 99 | EVP_KDF_derive() derives I<keylen> bytes of key material and places it in the |
65ce7e65 | 100 | I<key> buffer. If the algorithm produces a fixed amount of output then an |
ee2161e8 | 101 | error will occur unless the I<keylen> parameter is equal to that output size, |
1ba21239 | 102 | as returned by EVP_KDF_CTX_get_kdf_size(). |
65ce7e65 P |
103 | |
104 | EVP_KDF_get_params() retrieves details about the implementation | |
105 | I<kdf>. | |
106 | The set of parameters given with I<params> determine exactly what | |
107 | parameters should be retrieved. | |
108 | Note that a parameter that is unknown in the underlying context is | |
109 | simply ignored. | |
110 | ||
660c5344 | 111 | EVP_KDF_CTX_get_params() retrieves chosen parameters, given the |
65ce7e65 P |
112 | context I<ctx> and its underlying context. |
113 | The set of parameters given with I<params> determine exactly what | |
114 | parameters should be retrieved. | |
115 | Note that a parameter that is unknown in the underlying context is | |
116 | simply ignored. | |
117 | ||
660c5344 | 118 | EVP_KDF_CTX_set_params() passes chosen parameters to the underlying |
65ce7e65 P |
119 | context, given a context I<ctx>. |
120 | The set of parameters given with I<params> determine exactly what | |
121 | parameters are passed down. | |
122 | Note that a parameter that is unknown in the underlying context is | |
123 | simply ignored. | |
124 | Also, what happens when a needed parameter isn't passed down is | |
125 | defined by the implementation. | |
126 | ||
41f7ecf3 P |
127 | EVP_KDF_gettable_params(), EVP_KDF_gettable_ctx_params() and |
128 | EVP_KDF_settable_ctx_params() get a constant B<OSSL_PARAM> array that | |
79c44b4e | 129 | describes the retrievable and settable parameters, i.e. parameters that |
660c5344 MC |
130 | can be used with EVP_KDF_get_params(), EVP_KDF_CTX_get_params() |
131 | and EVP_KDF_CTX_set_params(), respectively. | |
65ce7e65 P |
132 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. |
133 | ||
134 | =head2 Information functions | |
135 | ||
1ba21239 | 136 | EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm produces a fixed amount |
65ce7e65 P |
137 | of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned. |
138 | For some algorithms an error may result if input parameters necessary to | |
139 | calculate a fixed output size have not yet been supplied. | |
140 | ||
251e610c RL |
141 | EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an |
142 | algorithm that's identifiable with I<name>, otherwise 0. | |
143 | ||
65ce7e65 P |
144 | EVP_KDF_provider() returns the provider that holds the implementation |
145 | of the given I<kdf>. | |
146 | ||
251e610c | 147 | EVP_KDF_do_all_provided() traverses all KDF implemented by all activated |
65ce7e65 P |
148 | providers in the given library context I<libctx>, and for each of the |
149 | implementations, calls the given function I<fn> with the implementation method | |
150 | and the given I<arg> as argument. | |
151 | ||
506cb0f6 RL |
152 | EVP_KDF_number() returns the internal dynamic number assigned to |
153 | I<kdf>. | |
154 | ||
c9452d74 P |
155 | EVP_KDF_name() return the name of the given KDF. For fetched KDFs |
156 | with multiple names, only one of them is returned; it's | |
157 | recommended to use EVP_KDF_names_do_all() instead. | |
158 | ||
f651c727 RL |
159 | EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls |
160 | I<fn> with each name and I<data>. | |
161 | ||
b1cabee8 | 162 | =head1 PARAMETERS |
65ce7e65 P |
163 | |
164 | The standard parameter names are: | |
165 | ||
166 | =over 4 | |
167 | ||
0c452a51 | 168 | =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> |
65ce7e65 P |
169 | |
170 | Some KDF implementations require a password. | |
171 | For those KDF implementations that support it, this parameter sets the password. | |
172 | ||
0c452a51 | 173 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> |
65ce7e65 P |
174 | |
175 | Some KDF implementations can take a salt. | |
176 | For those KDF implementations that support it, this parameter sets the salt. | |
177 | ||
178 | The default value, if any, is implementation dependent. | |
179 | ||
0c452a51 | 180 | =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> |
65ce7e65 P |
181 | |
182 | Some KDF implementations require an iteration count. | |
183 | For those KDF implementations that support it, this parameter sets the | |
184 | iteration count. | |
185 | ||
186 | The default value, if any, is implementation dependent. | |
187 | ||
0c452a51 | 188 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> |
65ce7e65 | 189 | |
0c452a51 | 190 | =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> |
65ce7e65 | 191 | |
0c452a51 | 192 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
65ce7e65 | 193 | |
33f54da3 SS |
194 | =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string> |
195 | ||
196 | For KDF implementations that use an underlying computation MAC, digest or | |
197 | cipher, these parameters set what the algorithm should be. | |
c69561de | 198 | |
9bd9c440 | 199 | The value is always the name of the intended algorithm, |
c69561de P |
200 | or the properties. |
201 | ||
202 | Note that not all algorithms may support all possible underlying | |
203 | implementations. | |
65ce7e65 | 204 | |
0c452a51 | 205 | =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> |
65ce7e65 P |
206 | |
207 | Some KDF implementations require a key. | |
208 | For those KDF implementations that support it, this octet string parameter | |
209 | sets the key. | |
210 | ||
0c452a51 | 211 | =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> |
65ce7e65 P |
212 | |
213 | Used by implementations that use a MAC with a variable output size (KMAC). | |
214 | For those KDF implementations that support it, this parameter | |
215 | sets the MAC output size. | |
216 | ||
217 | The default value, if any, is implementation dependent. | |
f4651268 | 218 | The length must never exceed what can be given with a B<size_t>. |
65ce7e65 | 219 | |
0c452a51 | 220 | =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer> |
65ce7e65 P |
221 | |
222 | Memory-hard password-based KDF algorithms, such as scrypt, use an amount of | |
223 | memory that depends on the load factors provided as input. | |
560ac83b | 224 | For those KDF implementations that support it, this B<uint64_t> parameter sets |
65ce7e65 P |
225 | an upper limit on the amount of memory that may be consumed while performing |
226 | a key derivation. | |
227 | If this memory usage limit is exceeded because the load factors are chosen | |
228 | too high, the key derivation will fail. | |
229 | ||
230 | The default value is implementation dependent. | |
f4651268 | 231 | The memory size must never exceed what can be given with a B<size_t>. |
65ce7e65 P |
232 | |
233 | =back | |
234 | ||
235 | =head1 RETURN VALUES | |
236 | ||
ee2161e8 | 237 | EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or |
65ce7e65 P |
238 | NULL if allocation failed. |
239 | ||
65ce7e65 P |
240 | EVP_KDF_provider() returns a pointer to the provider for the KDF, or |
241 | NULL on error. | |
242 | ||
ee2161e8 | 243 | EVP_KDF_up_ref() returns 1 on success, 0 on error. |
65ce7e65 | 244 | |
660c5344 | 245 | EVP_KDF_CTX_new() returns either the newly allocated |
ee2161e8 | 246 | B<EVP_KDF_CTX> structure or NULL if an error occurred. |
65ce7e65 | 247 | |
a49d0a49 | 248 | EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value. |
65ce7e65 | 249 | |
1ba21239 | 250 | EVP_KDF_CTX_get_kdf_size() returns the output size. B<SIZE_MAX> is returned to indicate |
65ce7e65 P |
251 | that the algorithm produces a variable amount of output; 0 to indicate failure. |
252 | ||
c9452d74 P |
253 | EVP_KDF_name() returns the name of the KDF, or NULL on error. |
254 | ||
d84f5515 MC |
255 | EVP_KDF_names_do_all() returns 1 if the callback was called for all names. A |
256 | return value of 0 means that the callback was not called for any names. | |
257 | ||
65ce7e65 P |
258 | The remaining functions return 1 for success and 0 or a negative value for |
259 | failure. In particular, a return value of -2 indicates the operation is not | |
260 | supported by the KDF algorithm. | |
261 | ||
262 | =head1 SEE ALSO | |
263 | ||
b8086652 | 264 | L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> |
65ce7e65 P |
265 | |
266 | =head1 HISTORY | |
267 | ||
268 | This functionality was added to OpenSSL 3.0. | |
269 | ||
270 | =head1 COPYRIGHT | |
271 | ||
00c405b3 | 272 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
65ce7e65 P |
273 | |
274 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
275 | this file except in compliance with the License. You can obtain a copy | |
276 | in the file LICENSE in the source distribution or at | |
277 | L<https://www.openssl.org/source/license.html>. | |
278 | ||
279 | =cut |