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_reset, EVP_KDF_derive,
   8 EVP_KDF_size, EVP_KDF_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
   9 EVP_KDF_number, 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_ctx_params, EVP_KDF_settable_ctx_params,
  12 EVP_KDF_gettable_params - EVP KDF routines
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/kdf.h>
  17
  18  typedef struct evp_kdf_st EVP_KDF;
  19  typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
  20
  21  EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
  22  const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
  23  void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
  24  EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
  25  void EVP_KDF_reset(EVP_KDF_CTX *ctx);
  26  size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
  27  int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
  28  int EVP_KDF_up_ref(EVP_KDF *kdf);
  29  void EVP_KDF_free(EVP_KDF *kdf);
  30  EVP_KDF *EVP_KDF_fetch(OPENSSL_CTX *libctx, const char *algorithm,
  31                         const char *properties);
  32  int EVP_KDF_number(const EVP_KDF *kdf);
  33  int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);
  34  const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
  35  void EVP_KDF_do_all_provided(OPENSSL_CTX *libctx,
  36                               void (*fn)(EVP_KDF *kdf, void *arg),
  37                               void *arg);
  38  void EVP_KDF_names_do_all(const EVP_KDF *kdf,
  39                            void (*fn)(const char *name, void *data),
  40                            void *data);
  41  int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
  42  int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
  43  int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
  44  const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);
  45  const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf);
  46  const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf);
  47  const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
  48
  49 =head1 DESCRIPTION
  50
  51 The EVP KDF routines are a high level interface to Key Derivation Function
  52 algorithms and should be used instead of algorithm-specific functions.
  53
  54 After creating a B<EVP_KDF_CTX> for the required algorithm using
  55 EVP_KDF_CTX_new(), inputs to the algorithm are supplied
  56 using calls to EVP_KDF_CTX_set_params() before
  57 calling EVP_KDF_derive() to derive the key.
  58
  59 =head2 Types
  60
  61 B<EVP_KDF> is a type that holds the implementation of a KDF.
  62
  63 B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
  64
  65 =head2 Algorithm implementation fetching
  66
  67 EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
  68 a library context I<libctx> and a set of I<properties>.
  69 See L<provider(7)/Fetching algorithms> for further information.
  70
  71 The returned value must eventually be freed with
  72 L<EVP_KDF_free(3)>.
  73
  74 EVP_KDF_up_ref() increments the reference count of an already fetched
  75 KDF.
  76
  77 EVP_KDF_free() frees a fetched algorithm.
  78 NULL is a valid parameter, for which this function is a no-op.
  79
  80 =head2 Context manipulation functions
  81
  82 EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
  83
  84 EVP_KDF_CTX_free() frees up the context I<ctx>.  If I<ctx> is NULL, nothing
  85 is done.
  86
  87 EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
  88 I<ctx>.
  89
  90 =head2 Computing functions
  91
  92 EVP_KDF_reset() resets the context to the default state as if the context
  93 had just been created.
  94
  95 EVP_KDF_derive() derives I<keylen> bytes of key material and places it in the
  96 I<key> buffer.  If the algorithm produces a fixed amount of output then an
  97 error will occur unless the I<keylen> parameter is equal to that output size,
  98 as returned by EVP_KDF_size().
  99
 100 EVP_KDF_get_params() retrieves details about the implementation
 101 I<kdf>.
 102 The set of parameters given with I<params> determine exactly what
 103 parameters should be retrieved.
 104 Note that a parameter that is unknown in the underlying context is
 105 simply ignored.
 106
 107 EVP_KDF_CTX_get_params() retrieves chosen parameters, given the
 108 context I<ctx> and its underlying context.
 109 The set of parameters given with I<params> determine exactly what
 110 parameters should be retrieved.
 111 Note that a parameter that is unknown in the underlying context is
 112 simply ignored.
 113
 114 EVP_KDF_CTX_set_params() passes chosen parameters to the underlying
 115 context, given a context I<ctx>.
 116 The set of parameters given with I<params> determine exactly what
 117 parameters are passed down.
 118 Note that a parameter that is unknown in the underlying context is
 119 simply ignored.
 120 Also, what happens when a needed parameter isn't passed down is
 121 defined by the implementation.
 122
 123 EVP_KDF_gettable_params(), EVP_KDF_gettable_ctx_params() and
 124 EVP_KDF_settable_ctx_params() get a constant B<OSSL_PARAM> array that
 125 describes the retrievable and settable parameters, i.e. parameters that
 126 can be used with EVP_KDF_get_params(), EVP_KDF_CTX_get_params()
 127 and EVP_KDF_CTX_set_params(), respectively.
 128 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 129
 130 =head2 Information functions
 131
 132 EVP_KDF_size() returns the output size if the algorithm produces a fixed amount
 133 of output and B<SIZE_MAX> otherwise.  If an error occurs then 0 is returned.
 134 For some algorithms an error may result if input parameters necessary to
 135 calculate a fixed output size have not yet been supplied.
 136
 137 EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an
 138 algorithm that's identifiable with I<name>, otherwise 0.
 139
 140 EVP_KDF_provider() returns the provider that holds the implementation
 141 of the given I<kdf>.
 142
 143 EVP_KDF_do_all_provided() traverses all KDF implemented by all activated
 144 providers in the given library context I<libctx>, and for each of the
 145 implementations, calls the given function I<fn> with the implementation method
 146 and the given I<arg> as argument.
 147
 148 EVP_KDF_number() returns the internal dynamic number assigned to
 149 I<kdf>.
 150
 151 EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls
 152 I<fn> with each name and I<data>.
 153
 154 =head1 PARAMETERS
 155
 156 The standard parameter names are:
 157
 158 =over 4
 159
 160 =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string>
 161
 162 Some KDF implementations require a password.
 163 For those KDF implementations that support it, this parameter sets the password.
 164
 165 =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
 166
 167 Some KDF implementations can take a salt.
 168 For those KDF implementations that support it, this parameter sets the salt.
 169
 170 The default value, if any, is implementation dependent.
 171
 172 =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer>
 173
 174 Some KDF implementations require an iteration count.
 175 For those KDF implementations that support it, this parameter sets the
 176 iteration count.
 177
 178 The default value, if any, is implementation dependent.
 179
 180 =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
 181
 182 =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
 183
 184 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
 185
 186 =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string>
 187
 188 For KDF implementations that use an underlying computation MAC, digest or
 189 cipher, these parameters set what the algorithm should be.
 190
 191 The value is always the name of the intended algorithm,
 192 or the properties.
 193
 194 Note that not all algorithms may support all possible underlying
 195 implementations.
 196
 197 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
 198
 199 Some KDF implementations require a key.
 200 For those KDF implementations that support it, this octet string parameter
 201 sets the key.
 202
 203 =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
 204
 205 Used by implementations that use a MAC with a variable output size (KMAC).
 206 For those KDF implementations that support it, this parameter
 207 sets the MAC output size.
 208
 209 The default value, if any, is implementation dependent.
 210 The length must never exceed what can be given with a B<size_t>.
 211
 212 =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
 213
 214 Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
 215 memory that depends on the load factors provided as input.
 216 For those KDF implementations that support it, this B<uint64_t> parameter sets
 217 an upper limit on the amount of memory that may be consumed while performing
 218 a key derivation.
 219 If this memory usage limit is exceeded because the load factors are chosen
 220 too high, the key derivation will fail.
 221
 222 The default value is implementation dependent.
 223 The memory size must never exceed what can be given with a B<size_t>.
 224
 225 =back
 226
 227 =head1 RETURN VALUES
 228
 229 EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
 230 NULL if allocation failed.
 231
 232 EVP_KDF_provider() returns a pointer to the provider for the KDF, or
 233 NULL on error.
 234
 235 EVP_KDF_up_ref() returns 1 on success, 0 on error.
 236
 237 EVP_KDF_CTX_new() returns either the newly allocated
 238 B<EVP_KDF_CTX> structure or NULL if an error occurred.
 239
 240 EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
 241
 242 EVP_KDF_size() returns the output size.  B<SIZE_MAX> is returned to indicate
 243 that the algorithm produces a variable amount of output; 0 to indicate failure.
 244
 245 The remaining functions return 1 for success and 0 or a negative value for
 246 failure.  In particular, a return value of -2 indicates the operation is not
 247 supported by the KDF algorithm.
 248
 249 =head1 SEE ALSO
 250
 251 L<EVP_KDF-SCRYPT(7)>
 252 L<EVP_KDF-TLS1_PRF(7)>
 253 L<EVP_KDF-PBKDF2(7)>
 254 L<EVP_KDF-HKDF(7)>
 255 L<EVP_KDF-SS(7)>
 256 L<EVP_KDF-SSHKDF(7)>
 257 L<EVP_KDF-X963(7)>
 258 L<EVP_KDF-X942(7)>
 259
 260 =head1 HISTORY
 261
 262 This functionality was added to OpenSSL 3.0.
 263
 264 =head1 COPYRIGHT
 265
 266 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 267
 268 Licensed under the Apache License 2.0 (the "License").  You may not use
 269 this file except in compliance with the License.  You can obtain a copy
 270 in the file LICENSE in the source distribution or at
 271 L<https://www.openssl.org/source/license.html>.
 272
 273 =cut