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, EVP_KDF_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
9 EVP_KDF_number, EVP_KDF_name, EVP_KDF_names_do_all,
10 EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided,
11 EVP_KDF_get_params, EVP_KDF_gettable_params,
12 EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params,
13 EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines
17 #include <openssl/kdf.h>
19 typedef struct evp_kdf_st EVP_KDF;
20 typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
22 EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
23 const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
24 void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
25 EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
26 void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx);
27 size_t EVP_KDF_CTX_get_kdf_size(EVP_KDF_CTX *ctx);
28 int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen,
29 const OSSL_PARAM params[]);
30 int EVP_KDF_up_ref(EVP_KDF *kdf);
31 void EVP_KDF_free(EVP_KDF *kdf);
32 EVP_KDF *EVP_KDF_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
33 const char *properties);
34 int EVP_KDF_number(const EVP_KDF *kdf);
35 int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);
36 const char *EVP_KDF_name(const EVP_KDF *kdf);
37 const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
38 void EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx,
39 void (*fn)(EVP_KDF *kdf, void *arg),
41 int EVP_KDF_names_do_all(const EVP_KDF *kdf,
42 void (*fn)(const char *name, void *data),
44 int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
45 int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
46 int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
47 const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);
48 const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf);
49 const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf);
50 const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf);
51 const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf);
52 const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
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.
59 After creating a B<EVP_KDF_CTX> for the required algorithm using
60 EVP_KDF_CTX_new(), inputs to the algorithm are supplied either by
61 passing them as part of the EVP_KDF_derive() call or using calls
62 to EVP_KDF_CTX_set_params() before calling EVP_KDF_derive() to derive
67 B<EVP_KDF> is a type that holds the implementation of a KDF.
69 B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
71 =head2 Algorithm implementation fetching
73 EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
74 a library context I<libctx> and a set of I<properties>.
75 See L<provider(7)/Fetching algorithms> for further information.
77 See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of
78 algorithms supported by the default provider.
80 The returned value must eventually be freed with
83 EVP_KDF_up_ref() increments the reference count of an already fetched
86 EVP_KDF_free() frees a fetched algorithm.
87 NULL is a valid parameter, for which this function is a no-op.
89 =head2 Context manipulation functions
91 EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
93 EVP_KDF_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing
96 EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
99 =head2 Computing functions
101 EVP_KDF_CTX_reset() resets the context to the default state as if the context
102 had just been created.
104 EVP_KDF_derive() processes any parameters in I<Params> and then derives
105 I<keylen> bytes of key material and places it in the I<key> buffer.
106 If the algorithm produces a fixed amount of output then an error will
107 occur unless the I<keylen> parameter is equal to that output size,
108 as returned by EVP_KDF_CTX_get_kdf_size().
110 EVP_KDF_get_params() retrieves details about the implementation
112 The set of parameters given with I<params> determine exactly what
113 parameters should be retrieved.
114 Note that a parameter that is unknown in the underlying context is
117 EVP_KDF_CTX_get_params() retrieves chosen parameters, given the
118 context I<ctx> and its underlying context.
119 The set of parameters given with I<params> determine exactly what
120 parameters should be retrieved.
121 Note that a parameter that is unknown in the underlying context is
124 EVP_KDF_CTX_set_params() passes chosen parameters to the underlying
125 context, given a context I<ctx>.
126 The set of parameters given with I<params> determine exactly what
127 parameters are passed down.
128 Note that a parameter that is unknown in the underlying context is
130 Also, what happens when a needed parameter isn't passed down is
131 defined by the implementation.
133 EVP_KDF_gettable_params() returns an B<OSSL_PARAM> array that describes
134 the retrievable and settable parameters. EVP_KDF_gettable_params()
135 returns parameters that can be used with EVP_KDF_get_params().
136 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
138 EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params()
139 return constant B<OSSL_PARAM> arrays that describe the retrievable
140 parameters that can be used with EVP_KDF_CTX_get_params().
141 EVP_KDF_gettable_ctx_params() returns the parameters that can be retrieved
142 from the algorithm, whereas EVP_KDF_CTX_gettable_params() returns
143 the parameters that can be retrieved in the context's current state.
144 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
146 EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return
147 constant B<OSSL_PARAM> arrays that describe the settable parameters that
148 can be used with EVP_KDF_CTX_set_params(). EVP_KDF_settable_ctx_params()
149 returns the parameters that can be retrieved from the algorithm,
150 whereas EVP_KDF_CTX_settable_params() returns the parameters that can
151 be retrieved in the context's current state. See L<OSSL_PARAM(3)>
152 for the use of B<OSSL_PARAM> as a parameter descriptor.
154 =head2 Information functions
156 EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm produces a fixed amount
157 of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned.
158 For some algorithms an error may result if input parameters necessary to
159 calculate a fixed output size have not yet been supplied.
161 EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an
162 algorithm that's identifiable with I<name>, otherwise 0.
164 EVP_KDF_provider() returns the provider that holds the implementation
167 EVP_KDF_do_all_provided() traverses all KDF implemented by all activated
168 providers in the given library context I<libctx>, and for each of the
169 implementations, calls the given function I<fn> with the implementation method
170 and the given I<arg> as argument.
172 EVP_KDF_number() returns the internal dynamic number assigned to
175 EVP_KDF_name() return the name of the given KDF. For fetched KDFs
176 with multiple names, only one of them is returned; it's
177 recommended to use EVP_KDF_names_do_all() instead.
179 EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls
180 I<fn> with each name and I<data>.
184 The standard parameter names are:
188 =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string>
190 Some KDF implementations require a password.
191 For those KDF implementations that support it, this parameter sets the password.
193 =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
195 Some KDF implementations can take a salt.
196 For those KDF implementations that support it, this parameter sets the salt.
198 The default value, if any, is implementation dependent.
200 =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer>
202 Some KDF implementations require an iteration count.
203 For those KDF implementations that support it, this parameter sets the
206 The default value, if any, is implementation dependent.
208 =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
210 =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
212 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
214 =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string>
216 For KDF implementations that use an underlying computation MAC, digest or
217 cipher, these parameters set what the algorithm should be.
219 The value is always the name of the intended algorithm,
222 Note that not all algorithms may support all possible underlying
225 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
227 Some KDF implementations require a key.
228 For those KDF implementations that support it, this octet string parameter
231 =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
233 Used by implementations that use a MAC with a variable output size (KMAC).
234 For those KDF implementations that support it, this parameter
235 sets the MAC output size.
237 The default value, if any, is implementation dependent.
238 The length must never exceed what can be given with a B<size_t>.
240 =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
242 Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
243 memory that depends on the load factors provided as input.
244 For those KDF implementations that support it, this B<uint64_t> parameter sets
245 an upper limit on the amount of memory that may be consumed while performing
247 If this memory usage limit is exceeded because the load factors are chosen
248 too high, the key derivation will fail.
250 The default value is implementation dependent.
251 The memory size must never exceed what can be given with a B<size_t>.
257 EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
258 NULL if allocation failed.
260 EVP_KDF_provider() returns a pointer to the provider for the KDF, or
263 EVP_KDF_up_ref() returns 1 on success, 0 on error.
265 EVP_KDF_CTX_new() returns either the newly allocated
266 B<EVP_KDF_CTX> structure or NULL if an error occurred.
268 EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value.
270 EVP_KDF_CTX_get_kdf_size() returns the output size. B<SIZE_MAX> is returned to indicate
271 that the algorithm produces a variable amount of output; 0 to indicate failure.
273 EVP_KDF_name() returns the name of the KDF, or NULL on error.
275 EVP_KDF_names_do_all() returns 1 if the callback was called for all names. A
276 return value of 0 means that the callback was not called for any names.
278 The remaining functions return 1 for success and 0 or a negative value for
279 failure. In particular, a return value of -2 indicates the operation is not
280 supported by the KDF algorithm.
284 L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>
288 This functionality was added to OpenSSL 3.0.
292 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
294 Licensed under the Apache License 2.0 (the "License"). You may not use
295 this file except in compliance with the License. You can obtain a copy
296 in the file LICENSE in the source distribution or at
297 L<https://www.openssl.org/source/license.html>.