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 decribes 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 For KDF implementations that use an underlying computation MAC or
 187 digest, these parameters set what the algorithm should be.
 188
 189 The value is always the name of the intended algorithm,
 190 or the properties.
 191
 192 Note that not all algorithms may support all possible underlying
 193 implementations.
 194
 195 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
 196
 197 Some KDF implementations require a key.
 198 For those KDF implementations that support it, this octet string parameter
 199 sets the key.
 200
 201 =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
 202
 203 Used by implementations that use a MAC with a variable output size (KMAC).
 204 For those KDF implementations that support it, this parameter
 205 sets the MAC output size.
 206
 207 The default value, if any, is implementation dependent.
 208 The length must never exceed what can be given with a B<size_t>.
 209
 210 =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
 211
 212 Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
 213 memory that depends on the load factors provided as input.
 214 For those KDF implementations that support it, this B<uint64_t> parameter sets
 215 an upper limit on the amount of memory that may be consumed while performing
 216 a key derivation.
 217 If this memory usage limit is exceeded because the load factors are chosen
 218 too high, the key derivation will fail.
 219
 220 The default value is implementation dependent.
 221 The memory size must never exceed what can be given with a B<size_t>.
 222
 223 =back
 224
 225 =head1 RETURN VALUES
 226
 227 EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
 228 NULL if allocation failed.
 229
 230 EVP_KDF_provider() returns a pointer to the provider for the KDF, or
 231 NULL on error.
 232
 233 EVP_KDF_up_ref() returns 1 on success, 0 on error.
 234
 235 EVP_KDF_CTX_new() returns either the newly allocated
 236 B<EVP_KDF_CTX> structure or NULL if an error occurred.
 237
 238 EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
 239
 240 EVP_KDF_size() returns the output size.  B<SIZE_MAX> is returned to indicate
 241 that the algorithm produces a variable amount of output; 0 to indicate failure.
 242
 243 The remaining functions return 1 for success and 0 or a negative value for
 244 failure.  In particular, a return value of -2 indicates the operation is not
 245 supported by the KDF algorithm.
 246
 247 =head1 SEE ALSO
 248
 249 L<EVP_KDF-SCRYPT(7)>
 250 L<EVP_KDF-TLS1_PRF(7)>
 251 L<EVP_KDF-PBKDF2(7)>
 252 L<EVP_KDF-HKDF(7)>
 253 L<EVP_KDF-SS(7)>
 254 L<EVP_KDF-SSHKDF(7)>
 255 L<EVP_KDF-X963(7)>
 256 L<EVP_KDF-X942(7)>
 257
 258 =head1 HISTORY
 259
 260 This functionality was added to OpenSSL 3.0.
 261
 262 =head1 COPYRIGHT
 263
 264 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 265
 266 Licensed under the Apache License 2.0 (the "License").  You may not use
 267 this file except in compliance with the License.  You can obtain a copy
 268 in the file LICENSE in the source distribution or at
 269 L<https://www.openssl.org/source/license.html>.
 270
 271 =cut