1=pod 2 3=head1 NAME 4 5EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref, 6EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup, 7EVP_KDF_CTX_reset, EVP_KDF_derive, 8EVP_KDF_CTX_get_kdf_size, 9EVP_KDF_get0_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a, 10EVP_KDF_get0_name, EVP_KDF_names_do_all, EVP_KDF_get0_description, 11EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided, 12EVP_KDF_get_params, EVP_KDF_gettable_params, 13EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params, 14EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines 15 16=head1 SYNOPSIS 17 18 #include <openssl/kdf.h> 19 20 typedef struct evp_kdf_st EVP_KDF; 21 typedef struct evp_kdf_ctx_st EVP_KDF_CTX; 22 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), 41 void *arg); 42 int EVP_KDF_names_do_all(const EVP_KDF *kdf, 43 void (*fn)(const char *name, void *data), 44 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); 54 55=head1 DESCRIPTION 56 57The EVP KDF routines are a high-level interface to Key Derivation Function 58algorithms and should be used instead of algorithm-specific functions. 59 60After creating a B<EVP_KDF_CTX> for the required algorithm using 61EVP_KDF_CTX_new(), inputs to the algorithm are supplied either by 62passing them as part of the EVP_KDF_derive() call or using calls 63to EVP_KDF_CTX_set_params() before calling EVP_KDF_derive() to derive 64the key. 65 66=head2 Types 67 68B<EVP_KDF> is a type that holds the implementation of a KDF. 69 70B<EVP_KDF_CTX> is a context type that holds the algorithm inputs. 71 72=head2 Algorithm implementation fetching 73 74EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given 75a library context I<libctx> and a set of I<properties>. 76See L<crypto(7)/ALGORITHM FETCHING> for further information. 77 78See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of 79algorithms supported by the default provider. 80 81The returned value must eventually be freed with 82L<EVP_KDF_free(3)>. 83 84EVP_KDF_up_ref() increments the reference count of an already fetched 85KDF. 86 87EVP_KDF_free() frees a fetched algorithm. 88NULL is a valid parameter, for which this function is a no-op. 89 90=head2 Context manipulation functions 91 92EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>. 93 94EVP_KDF_CTX_free() frees up the context I<ctx>. If I<ctx> is NULL, nothing 95is done. 96 97EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context 98I<ctx>. 99 100=head2 Computing functions 101 102EVP_KDF_CTX_reset() resets the context to the default state as if the context 103had just been created. 104 105EVP_KDF_derive() processes any parameters in I<Params> and then derives 106I<keylen> bytes of key material and places it in the I<key> buffer. 107If the algorithm produces a fixed amount of output then an error will 108occur unless the I<keylen> parameter is equal to that output size, 109as returned by EVP_KDF_CTX_get_kdf_size(). 110 111EVP_KDF_get_params() retrieves details about the implementation 112I<kdf>. 113The set of parameters given with I<params> determine exactly what 114parameters should be retrieved. 115Note that a parameter that is unknown in the underlying context is 116simply ignored. 117 118EVP_KDF_CTX_get_params() retrieves chosen parameters, given the 119context I<ctx> and its underlying context. 120The set of parameters given with I<params> determine exactly what 121parameters should be retrieved. 122Note that a parameter that is unknown in the underlying context is 123simply ignored. 124 125EVP_KDF_CTX_set_params() passes chosen parameters to the underlying 126context, given a context I<ctx>. 127The set of parameters given with I<params> determine exactly what 128parameters are passed down. 129Note that a parameter that is unknown in the underlying context is 130simply ignored. 131Also, what happens when a needed parameter isn't passed down is 132defined by the implementation. 133 134EVP_KDF_gettable_params() returns an L<OSSL_PARAM(3)> array that describes 135the retrievable and settable parameters. EVP_KDF_gettable_params() 136returns parameters that can be used with EVP_KDF_get_params(). 137 138EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params() 139return constant L<OSSL_PARAM(3)> arrays that describe the retrievable 140parameters that can be used with EVP_KDF_CTX_get_params(). 141EVP_KDF_gettable_ctx_params() returns the parameters that can be retrieved 142from the algorithm, whereas EVP_KDF_CTX_gettable_params() returns 143the parameters that can be retrieved in the context's current state. 144 145EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return 146constant L<OSSL_PARAM(3)> arrays that describe the settable parameters that 147can be used with EVP_KDF_CTX_set_params(). EVP_KDF_settable_ctx_params() 148returns the parameters that can be retrieved from the algorithm, 149whereas EVP_KDF_CTX_settable_params() returns the parameters that can 150be retrieved in the context's current state. 151 152=head2 Information functions 153 154EVP_KDF_CTX_get_kdf_size() returns the output size if the algorithm produces a fixed amount 155of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned. 156For some algorithms an error may result if input parameters necessary to 157calculate a fixed output size have not yet been supplied. 158 159EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an 160algorithm that's identifiable with I<name>, otherwise 0. 161 162EVP_KDF_get0_provider() returns the provider that holds the implementation 163of the given I<kdf>. 164 165EVP_KDF_do_all_provided() traverses all KDF implemented by all activated 166providers in the given library context I<libctx>, and for each of the 167implementations, calls the given function I<fn> with the implementation method 168and the given I<arg> as argument. 169 170EVP_KDF_get0_name() return the name of the given KDF. For fetched KDFs 171with multiple names, only one of them is returned; it's 172recommended to use EVP_KDF_names_do_all() instead. 173 174EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls 175I<fn> with each name and I<data>. 176 177EVP_KDF_get0_description() returns a description of the I<kdf>, meant for 178display and human consumption. The description is at the discretion of 179the I<kdf> implementation. 180 181=head1 PARAMETERS 182 183The standard parameter names are: 184 185=over 4 186 187=item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> 188 189Some KDF implementations require a password. 190For those KDF implementations that support it, this parameter sets the password. 191 192=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 193 194Some KDF implementations can take a non-secret unique cryptographic salt. 195For those KDF implementations that support it, this parameter sets the salt. 196 197The default value, if any, is implementation dependent. 198 199=item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> 200 201Some KDF implementations require an iteration count. 202For those KDF implementations that support it, this parameter sets the 203iteration count. 204 205The default value, if any, is implementation dependent. 206 207=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 208 209=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> 210 211=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 212 213=item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string> 214 215For KDF implementations that use an underlying computation MAC, digest or 216cipher, these parameters set what the algorithm should be. 217 218The value is always the name of the intended algorithm, 219or the properties. 220 221Note that not all algorithms may support all possible underlying 222implementations. 223 224=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 225 226Some KDF implementations require a key. 227For those KDF implementations that support it, this octet string parameter 228sets the key. 229 230=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> 231 232Some KDF implementations, such as L<EVP_KDF-HKDF(7)>, take an 'info' parameter 233for binding the derived key material 234to application- and context-specific information. 235This parameter sets the info, fixed info, other info or shared info argument. 236You can specify this parameter multiple times, and each instance will 237be concatenated to form the final value. 238 239=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> 240 241Used by implementations that use a MAC with a variable output size (KMAC). 242For those KDF implementations that support it, this parameter 243sets the MAC output size. 244 245The default value, if any, is implementation dependent. 246The length must never exceed what can be given with a B<size_t>. 247 248=item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer> 249 250Memory-hard password-based KDF algorithms, such as scrypt, use an amount of 251memory that depends on the load factors provided as input. 252For those KDF implementations that support it, this B<uint64_t> parameter sets 253an upper limit on the amount of memory that may be consumed while performing 254a key derivation. 255If this memory usage limit is exceeded because the load factors are chosen 256too high, the key derivation will fail. 257 258The default value is implementation dependent. 259The memory size must never exceed what can be given with a B<size_t>. 260 261=back 262 263=head1 RETURN VALUES 264 265EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or 266NULL if allocation failed. 267 268EVP_KDF_get0_provider() returns a pointer to the provider for the KDF, or 269NULL on error. 270 271EVP_KDF_up_ref() returns 1 on success, 0 on error. 272 273EVP_KDF_CTX_new() returns either the newly allocated 274B<EVP_KDF_CTX> structure or NULL if an error occurred. 275 276EVP_KDF_CTX_free() and EVP_KDF_CTX_reset() do not return a value. 277 278EVP_KDF_CTX_get_kdf_size() returns the output size. B<SIZE_MAX> is returned to indicate 279that the algorithm produces a variable amount of output; 0 to indicate failure. 280 281EVP_KDF_get0_name() returns the name of the KDF, or NULL on error. 282 283EVP_KDF_names_do_all() returns 1 if the callback was called for all names. A 284return value of 0 means that the callback was not called for any names. 285 286The remaining functions return 1 for success and 0 or a negative value for 287failure. In particular, a return value of -2 indicates the operation is not 288supported by the KDF algorithm. 289 290=head1 NOTES 291 292The KDF life-cycle is described in L<life_cycle-kdf(7)>. In the future, 293the transitions described there will be enforced. When this is done, it will 294not be considered a breaking change to the API. 295 296=head1 SEE ALSO 297 298L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>, 299L<life_cycle-kdf(7)>. 300 301=head1 HISTORY 302 303This functionality was added in OpenSSL 3.0. 304 305=head1 COPYRIGHT 306 307Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 308 309Licensed under the Apache License 2.0 (the "License"). You may not use 310this file except in compliance with the License. You can obtain a copy 311in the file LICENSE in the source distribution or at 312L<https://www.openssl.org/source/license.html>. 313 314=cut 315