doc/man3/EVP_KDF.pod

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