1EVP_KDF(3ossl) OpenSSL EVP_KDF(3ossl)
2
6 EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref, EVP_KDF_CTX,
7 EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup, EVP_KDF_CTX_reset,
8 EVP_KDF_derive, EVP_KDF_CTX_get_kdf_size, EVP_KDF_get0_provider,
9 EVP_KDF_CTX_kdf, EVP_KDF_is_a, EVP_KDF_get0_name, EVP_KDF_names_do_all,
10 EVP_KDF_get0_description, EVP_KDF_CTX_get_params,
11 EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided, EVP_KDF_get_params,
12 EVP_KDF_gettable_params, EVP_KDF_gettable_ctx_params,
13 EVP_KDF_settable_ctx_params, EVP_KDF_CTX_gettable_params,
14 EVP_KDF_CTX_settable_params - EVP KDF routines
15
17 #include <openssl/kdf.h>
18 typedef struct evp_kdf_st EVP_KDF;
20 typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
21 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_is_a(const EVP_KDF *kdf, const char *name);
35 const char *EVP_KDF_get0_name(const EVP_KDF *kdf);
36 const char *EVP_KDF_get0_description(const EVP_KDF *kdf);
37 const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);
38 void EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx,
39 void (*fn)(EVP_KDF *kdf, void *arg),
40 void *arg);
41 int EVP_KDF_names_do_all(const EVP_KDF *kdf,
42 void (*fn)(const char *name, void *data),
43 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_get0_provider(const EVP_KDF *kdf);
53
55 The EVP KDF routines are a high-level interface to Key Derivation
56 Function algorithms and should be used instead of algorithm-specific
57 functions.
58 After creating a 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 to
62 EVP_KDF_CTX_set_params() before calling EVP_KDF_derive() to derive the
63 key.
64 Types
66 EVP_KDF is a type that holds the implementation of a KDF.
67 EVP_KDF_CTX is a context type that holds the algorithm inputs.
69 Algorithm implementation fetching
71 EVP_KDF_fetch() fetches an implementation of a KDF algorithm, given a
72 library context libctx and a set of properties. See "ALGORITHM
73 FETCHING" in crypto(7) for further information.
74 See "Key Derivation Function (KDF)" in OSSL_PROVIDER-default(7) for the
76 lists of algorithms supported by the default provider.
77 The returned value must eventually be freed with EVP_KDF_free(3).
79 EVP_KDF_up_ref() increments the reference count of an already fetched
81 KDF.
82 EVP_KDF_free() frees a fetched algorithm. NULL is a valid parameter,
84 for which this function is a no-op.
85 Context manipulation functions
87 EVP_KDF_CTX_new() creates a new context for the KDF implementation kdf.
88 EVP_KDF_CTX_free() frees up the context ctx. If ctx is NULL, nothing
90 is done.
91 EVP_KDF_CTX_kdf() returns the EVP_KDF associated with the context ctx.
93 Computing functions
95 EVP_KDF_CTX_reset() resets the context to the default state as if the
96 context had just been created.
97 EVP_KDF_derive() processes any parameters in Params and then derives
99 keylen bytes of key material and places it in the key buffer. If the
100 algorithm produces a fixed amount of output then an error will occur
101 unless the keylen parameter is equal to that output size, as returned
102 by EVP_KDF_CTX_get_kdf_size().
103 EVP_KDF_get_params() retrieves details about the implementation kdf.
105 The set of parameters given with params determine exactly what
106 parameters should be retrieved. Note that a parameter that is unknown
107 in the underlying context is simply ignored.
108 EVP_KDF_CTX_get_params() retrieves chosen parameters, given the context
110 ctx and its underlying context. The set of parameters given with
111 params determine exactly what parameters should be retrieved. Note
112 that a parameter that is unknown in the underlying context is simply
113 ignored.
114 EVP_KDF_CTX_set_params() passes chosen parameters to the underlying
116 context, given a context ctx. The set of parameters given with params
117 determine exactly what parameters are passed down. Note that a
118 parameter that is unknown in the underlying context is simply ignored.
119 Also, what happens when a needed parameter isn't passed down is defined
120 by the implementation.
121 EVP_KDF_gettable_params() returns an OSSL_PARAM(3) array that describes
123 the retrievable and settable parameters. EVP_KDF_gettable_params()
124 returns parameters that can be used with EVP_KDF_get_params().
125 EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params() return
127 constant OSSL_PARAM(3) arrays that describe the retrievable parameters
128 that can be used with EVP_KDF_CTX_get_params().
129 EVP_KDF_gettable_ctx_params() returns the parameters that can be
130 retrieved from the algorithm, whereas EVP_KDF_CTX_gettable_params()
131 returns the parameters that can be retrieved in the context's current
132 state.
133 EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return
135 constant OSSL_PARAM(3) arrays that describe the settable parameters
136 that can be used with EVP_KDF_CTX_set_params().
137 EVP_KDF_settable_ctx_params() returns the parameters that can be
138 retrieved from the algorithm, whereas EVP_KDF_CTX_settable_params()
139 returns the parameters that can be retrieved in the context's current
140 state.
141 Information functions
143 EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm
144 produces a fixed amount of output and SIZE_MAX otherwise. If an error
145 occurs then 0 is returned. For some algorithms an error may result if
146 input parameters necessary to calculate a fixed output size have not
147 yet been supplied.
148 EVP_KDF_is_a() returns 1 if kdf is an implementation of an algorithm
150 that's identifiable with name, otherwise 0.
151 EVP_KDF_get0_provider() returns the provider that holds the
153 implementation of the given kdf.
154 EVP_KDF_do_all_provided() traverses all KDF implemented by all
156 activated providers in the given library context libctx, and for each
157 of the implementations, calls the given function fn with the
158 implementation method and the given arg as argument.
159 EVP_KDF_get0_name() return the name of the given KDF. For fetched KDFs
161 with multiple names, only one of them is returned; it's recommended to
162 use EVP_KDF_names_do_all() instead.
163 EVP_KDF_names_do_all() traverses all names for kdf, and calls fn with
165 each name and data.
166 EVP_KDF_get0_description() returns a description of the kdf, meant for
168 display and human consumption. The description is at the discretion of
169 the kdf implementation.
170
172 The standard parameter names are:
173 "pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>
175 Some KDF implementations require a password. For those KDF
176 implementations that support it, this parameter sets the password.
177 "salt" (OSSL_KDF_PARAM_SALT) <octet string>
179 Some KDF implementations can take a salt. For those KDF
180 implementations that support it, this parameter sets the salt.
181 The default value, if any, is implementation dependent.
183 "iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>
185 Some KDF implementations require an iteration count. For those KDF
186 implementations that support it, this parameter sets the iteration
187 count.
188 The default value, if any, is implementation dependent.
190 "properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>
192 "mac" (OSSL_KDF_PARAM_MAC) <UTF8 string>
193 "digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>
194 "cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>
195 For KDF implementations that use an underlying computation MAC,
196 digest or cipher, these parameters set what the algorithm should
197 be.
198 The value is always the name of the intended algorithm, or the
200 properties.
201 Note that not all algorithms may support all possible underlying
203 implementations.
204 "key" (OSSL_KDF_PARAM_KEY) <octet string>
206 Some KDF implementations require a key. For those KDF
207 implementations that support it, this octet string parameter sets
208 the key.
209 "maclen" (OSSL_KDF_PARAM_MAC_SIZE) <unsigned integer>
211 Used by implementations that use a MAC with a variable output size
212 (KMAC). For those KDF implementations that support it, this
213 parameter sets the MAC output size.
214 The default value, if any, is implementation dependent. The length
216 must never exceed what can be given with a size_t.
217 "maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>
219 Memory-hard password-based KDF algorithms, such as scrypt, use an
220 amount of memory that depends on the load factors provided as
221 input. For those KDF implementations that support it, this
222 uint64_t parameter sets an upper limit on the amount of memory that
223 may be consumed while performing a key derivation. If this memory
224 usage limit is exceeded because the load factors are chosen too
225 high, the key derivation will fail.
226 The default value is implementation dependent. The memory size
228 must never exceed what can be given with a size_t.
229
231 EVP_KDF_fetch() returns a pointer to a newly fetched EVP_KDF, or NULL
232 if allocation failed.
233 EVP_KDF_get0_provider() returns a pointer to the provider for the KDF,
235 or NULL on error.
236 EVP_KDF_up_ref() returns 1 on success, 0 on error.
238 EVP_KDF_CTX_new() returns either the newly allocated EVP_KDF_CTX
240 structure or NULL if an error occurred.
241 EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value.
243 EVP_KDF_CTX_get_kdf_size() returns the output size. SIZE_MAX is
245 returned to indicate that the algorithm produces a variable amount of
246 output; 0 to indicate failure.
247 EVP_KDF_get0_name() returns the name of the KDF, or NULL on error.
249 EVP_KDF_names_do_all() returns 1 if the callback was called for all
251 names. A return value of 0 means that the callback was not called for
252 any names.
253 The remaining functions return 1 for success and 0 or a negative value
255 for failure. In particular, a return value of -2 indicates the
256 operation is not supported by the KDF algorithm.
257
259 The KDF life-cycle is described in life_cycle-kdf(7). In the future,
260 the transitions described there will be enforced. When this is done,
261 it will not be considered a breaking change to the API.
262
264 "Key Derivation Function (KDF)" in OSSL_PROVIDER-default(7),
265 life_cycle-kdf(7).
266
268 This functionality was added in OpenSSL 3.0.
269
271 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
272 Licensed under the Apache License 2.0 (the "License"). You may not use
274 this file except in compliance with the License. You can obtain a copy
275 in the file LICENSE in the source distribution or at
276 <https://www.openssl.org/source/license.html>.
2773.1.1 2023-08-31 EVP_KDF(3ossl)