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 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(). See
125 OSSL_PARAM(3) for the use of OSSL_PARAM as a parameter descriptor.
126 EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params() return
128 constant OSSL_PARAM arrays that describe the retrievable parameters
129 that can be used with EVP_KDF_CTX_get_params().
130 EVP_KDF_gettable_ctx_params() returns the parameters that can be
131 retrieved from the algorithm, whereas EVP_KDF_CTX_gettable_params()
132 returns the parameters that can be retrieved in the context's current
133 state. See OSSL_PARAM(3) for the use of OSSL_PARAM as a parameter
134 descriptor.
135 EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return
137 constant OSSL_PARAM arrays that describe the settable parameters that
138 can be used with EVP_KDF_CTX_set_params().
139 EVP_KDF_settable_ctx_params() returns the parameters that can be
140 retrieved from the algorithm, whereas EVP_KDF_CTX_settable_params()
141 returns the parameters that can be retrieved in the context's current
142 state. See OSSL_PARAM(3) for the use of OSSL_PARAM as a parameter
143 descriptor.
144 Information functions
146 EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm
147 produces a fixed amount of output and SIZE_MAX otherwise. If an error
148 occurs then 0 is returned. For some algorithms an error may result if
149 input parameters necessary to calculate a fixed output size have not
150 yet been supplied.
151 EVP_KDF_is_a() returns 1 if kdf is an implementation of an algorithm
153 that's identifiable with name, otherwise 0.
154 EVP_KDF_get0_provider() returns the provider that holds the
156 implementation of the given kdf.
157 EVP_KDF_do_all_provided() traverses all KDF implemented by all
159 activated providers in the given library context libctx, and for each
160 of the implementations, calls the given function fn with the
161 implementation method and the given arg as argument.
162 EVP_KDF_get0_name() return the name of the given KDF. For fetched KDFs
164 with multiple names, only one of them is returned; it's recommended to
165 use EVP_KDF_names_do_all() instead.
166 EVP_KDF_names_do_all() traverses all names for kdf, and calls fn with
168 each name and data.
169 EVP_KDF_get0_description() returns a description of the kdf, meant for
171 display and human consumption. The description is at the discretion of
172 the kdf implementation.
173
175 The standard parameter names are:
176 "pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>
178 Some KDF implementations require a password. For those KDF
179 implementations that support it, this parameter sets the password.
180 "salt" (OSSL_KDF_PARAM_SALT) <octet string>
182 Some KDF implementations can take a salt. For those KDF
183 implementations that support it, this parameter sets the salt.
184 The default value, if any, is implementation dependent.
186 "iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>
188 Some KDF implementations require an iteration count. For those KDF
189 implementations that support it, this parameter sets the iteration
190 count.
191 The default value, if any, is implementation dependent.
193 "properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>
195 "mac" (OSSL_KDF_PARAM_MAC) <UTF8 string>
196 "digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>
197 "cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>
198 For KDF implementations that use an underlying computation MAC,
199 digest or cipher, these parameters set what the algorithm should
200 be.
201 The value is always the name of the intended algorithm, or the
203 properties.
204 Note that not all algorithms may support all possible underlying
206 implementations.
207 "key" (OSSL_KDF_PARAM_KEY) <octet string>
209 Some KDF implementations require a key. For those KDF
210 implementations that support it, this octet string parameter sets
211 the key.
212 "maclen" (OSSL_KDF_PARAM_MAC_SIZE) <unsigned integer>
214 Used by implementations that use a MAC with a variable output size
215 (KMAC). For those KDF implementations that support it, this
216 parameter sets the MAC output size.
217 The default value, if any, is implementation dependent. The length
219 must never exceed what can be given with a size_t.
220 "maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>
222 Memory-hard password-based KDF algorithms, such as scrypt, use an
223 amount of memory that depends on the load factors provided as
224 input. For those KDF implementations that support it, this
225 uint64_t parameter sets an upper limit on the amount of memory that
226 may be consumed while performing a key derivation. If this memory
227 usage limit is exceeded because the load factors are chosen too
228 high, the key derivation will fail.
229 The default value is implementation dependent. The memory size
231 must never exceed what can be given with a size_t.
232
234 EVP_KDF_fetch() returns a pointer to a newly fetched EVP_KDF, or NULL
235 if allocation failed.
236 EVP_KDF_get0_provider() returns a pointer to the provider for the KDF,
238 or NULL on error.
239 EVP_KDF_up_ref() returns 1 on success, 0 on error.
241 EVP_KDF_CTX_new() returns either the newly allocated EVP_KDF_CTX
243 structure or NULL if an error occurred.
244 EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value.
246 EVP_KDF_CTX_get_kdf_size() returns the output size. SIZE_MAX is
248 returned to indicate that the algorithm produces a variable amount of
249 output; 0 to indicate failure.
250 EVP_KDF_get0_name() returns the name of the KDF, or NULL on error.
252 EVP_KDF_names_do_all() returns 1 if the callback was called for all
254 names. A return value of 0 means that the callback was not called for
255 any names.
256 The remaining functions return 1 for success and 0 or a negative value
258 for failure. In particular, a return value of -2 indicates the
259 operation is not supported by the KDF algorithm.
260
262 The KDF life-cycle is described in life_cycle-kdf(7). In the future,
263 the transitions described there will be enforced. When this is done,
264 it will not be considered a breaking change to the API.
265
267 "Key Derivation Function (KDF)" in OSSL_PROVIDER-default(7),
268 life_cycle-kdf(7).
269
271 This functionality was added to OpenSSL 3.0.
272
274 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
275 Licensed under the Apache License 2.0 (the "License"). You may not use
277 this file except in compliance with the License. You can obtain a copy
278 in the file LICENSE in the source distribution or at
279 <https://www.openssl.org/source/license.html>.
2803.0.5 2022-11-01 EVP_KDF(3ossl)