5 EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref,
6 EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup,
7 EVP_KDF_CTX_reset, EVP_KDF_derive,
8 EVP_KDF_CTX_get_kdf_size,
9 EVP_KDF_get0_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
10 EVP_KDF_get0_name, EVP_KDF_names_do_all, EVP_KDF_get0_description,
11 EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided,
12 EVP_KDF_get_params, EVP_KDF_gettable_params,
13 EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params,
14 EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines
18 #include <openssl/kdf.h>
20 typedef struct evp_kdf_st EVP_KDF;
21 typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
23 EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
24 const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
25 void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
26 EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
27 void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx);
28 size_t EVP_KDF_CTX_get_kdf_size(EVP_KDF_CTX *ctx);
29 int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen,
30 const OSSL_PARAM params[]);
31 int EVP_KDF_up_ref(EVP_KDF *kdf);
32 void EVP_KDF_free(EVP_KDF *kdf);
33 EVP_KDF *EVP_KDF_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
34 const char *properties);
35 int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);
36 const char *EVP_KDF_get0_name(const EVP_KDF *kdf);
37 const char *EVP_KDF_get0_description(const EVP_KDF *kdf);
38 const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);
39 void EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx,
40 void (*fn)(EVP_KDF *kdf, void *arg),
42 int EVP_KDF_names_do_all(const EVP_KDF *kdf,
43 void (*fn)(const char *name, void *data),
45 int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
46 int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
47 int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
48 const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);
49 const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf);
50 const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf);
51 const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf);
52 const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf);
53 const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);
57 The EVP KDF routines are a high-level interface to Key Derivation Function
58 algorithms and should be used instead of algorithm-specific functions.
60 After creating a B<EVP_KDF_CTX> for the required algorithm using
61 EVP_KDF_CTX_new(), inputs to the algorithm are supplied either by
62 passing them as part of the EVP_KDF_derive() call or using calls
63 to EVP_KDF_CTX_set_params() before calling EVP_KDF_derive() to derive
68 B<EVP_KDF> is a type that holds the implementation of a KDF.
70 B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
72 =head2 Algorithm implementation fetching
74 EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
75 a library context I<libctx> and a set of I<properties>.
76 See L<crypto(7)/ALGORITHM FETCHING> for further information.
78 See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of
79 algorithms supported by the default provider.
81 The returned value must eventually be freed with
84 EVP_KDF_up_ref() increments the reference count of an already fetched
87 EVP_KDF_free() frees a fetched algorithm.
88 NULL is a valid parameter, for which this function is a no-op.
90 =head2 Context manipulation functions
92 EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
94 EVP_KDF_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
97 EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
100 =head2 Computing functions
102 EVP_KDF_CTX_reset() resets the context to the default state as if the context
103 had just been created.
105 EVP_KDF_derive() processes any parameters in I<Params> and then derives
106 I<keylen> bytes of key material and places it in the I<key> buffer.
107 If the algorithm produces a fixed amount of output then an error will
108 occur unless the I<keylen> parameter is equal to that output size,
109 as returned by EVP_KDF_CTX_get_kdf_size().
111 EVP_KDF_get_params() retrieves details about the implementation
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
118 EVP_KDF_CTX_get_params() retrieves chosen parameters, given the
119 context I<ctx> and its underlying context.
120 The set of parameters given with I<params> determine exactly what
121 parameters should be retrieved.
122 Note that a parameter that is unknown in the underlying context is
125 EVP_KDF_CTX_set_params() passes chosen parameters to the underlying
126 context, given a context I<ctx>.
127 The set of parameters given with I<params> determine exactly what
128 parameters are passed down.
129 Note that a parameter that is unknown in the underlying context is
131 Also, what happens when a needed parameter isn't passed down is
132 defined by the implementation.
134 EVP_KDF_gettable_params() returns an B<OSSL_PARAM> array that describes
135 the retrievable and settable parameters. EVP_KDF_gettable_params()
136 returns parameters that can be used with EVP_KDF_get_params().
137 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
139 EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params()
140 return constant B<OSSL_PARAM> arrays that describe the retrievable
141 parameters that can be used with EVP_KDF_CTX_get_params().
142 EVP_KDF_gettable_ctx_params() returns the parameters that can be retrieved
143 from the algorithm, whereas EVP_KDF_CTX_gettable_params() returns
144 the parameters that can be retrieved in the context's current state.
145 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
147 EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return
148 constant B<OSSL_PARAM> arrays that describe the settable parameters that
149 can be used with EVP_KDF_CTX_set_params(). EVP_KDF_settable_ctx_params()
150 returns the parameters that can be retrieved from the algorithm,
151 whereas EVP_KDF_CTX_settable_params() returns the parameters that can
152 be retrieved in the context's current state. See L<OSSL_PARAM(3)>
153 for the use of B<OSSL_PARAM> as a parameter descriptor.
155 =head2 Information functions
157 EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm produces a fixed amount
158 of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned.
159 For some algorithms an error may result if input parameters necessary to
160 calculate a fixed output size have not yet been supplied.
162 EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an
163 algorithm that's identifiable with I<name>, otherwise 0.
165 EVP_KDF_get0_provider() returns the provider that holds the implementation
168 EVP_KDF_do_all_provided() traverses all KDF implemented by all activated
169 providers in the given library context I<libctx>, and for each of the
170 implementations, calls the given function I<fn> with the implementation method
171 and the given I<arg> as argument.
173 EVP_KDF_get0_name() return the name of the given KDF. For fetched KDFs
174 with multiple names, only one of them is returned; it's
175 recommended to use EVP_KDF_names_do_all() instead.
177 EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls
178 I<fn> with each name and I<data>.
180 EVP_KDF_get0_description() returns a description of the I<kdf>, meant for
181 display and human consumption. The description is at the discretion of
182 the I<kdf> implementation.
186 The standard parameter names are:
190 =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string>
192 Some KDF implementations require a password.
193 For those KDF implementations that support it, this parameter sets the password.
195 =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
197 Some KDF implementations can take a salt.
198 For those KDF implementations that support it, this parameter sets the salt.
200 The default value, if any, is implementation dependent.
202 =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer>
204 Some KDF implementations require an iteration count.
205 For those KDF implementations that support it, this parameter sets the
208 The default value, if any, is implementation dependent.
210 =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
212 =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
214 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
216 =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string>
218 For KDF implementations that use an underlying computation MAC, digest or
219 cipher, these parameters set what the algorithm should be.
221 The value is always the name of the intended algorithm,
224 Note that not all algorithms may support all possible underlying
227 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
229 Some KDF implementations require a key.
230 For those KDF implementations that support it, this octet string parameter
233 =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
235 Used by implementations that use a MAC with a variable output size (KMAC).
236 For those KDF implementations that support it, this parameter
237 sets the MAC output size.
239 The default value, if any, is implementation dependent.
240 The length must never exceed what can be given with a B<size_t>.
242 =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
244 Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
245 memory that depends on the load factors provided as input.
246 For those KDF implementations that support it, this B<uint64_t> parameter sets
247 an upper limit on the amount of memory that may be consumed while performing
249 If this memory usage limit is exceeded because the load factors are chosen
250 too high, the key derivation will fail.
252 The default value is implementation dependent.
253 The memory size must never exceed what can be given with a B<size_t>.
259 EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
260 NULL if allocation failed.
262 EVP_KDF_get0_provider() returns a pointer to the provider for the KDF, or
265 EVP_KDF_up_ref() returns 1 on success, 0 on error.
267 EVP_KDF_CTX_new() returns either the newly allocated
268 B<EVP_KDF_CTX> structure or NULL if an error occurred.
270 EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value.
272 EVP_KDF_CTX_get_kdf_size() returns the output size. B<SIZE_MAX> is returned to indicate
273 that the algorithm produces a variable amount of output; 0 to indicate failure.
275 EVP_KDF_get0_name() returns the name of the KDF, or NULL on error.
277 EVP_KDF_names_do_all() returns 1 if the callback was called for all names. A
278 return value of 0 means that the callback was not called for any names.
280 The remaining functions return 1 for success and 0 or a negative value for
281 failure. In particular, a return value of -2 indicates the operation is not
282 supported by the KDF algorithm.
286 The KDF life-cycle is described in L<life_cycle-kdf(7)>. In the future,
287 the transitions described there will be enforced. When this is done, it will
288 not be considered a breaking change to the API.
292 L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>,
293 L<life_cycle-kdf(7)>.
297 This functionality was added to OpenSSL 3.0.
301 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
303 Licensed under the Apache License 2.0 (the "License"). You may not use
304 this file except in compliance with the License. You can obtain a copy
305 in the file LICENSE in the source distribution or at
306 L<https://www.openssl.org/source/license.html>.