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