doc/man7/EVP_KDF_HKDF.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_KDF_HKDF - The HKDF EVP_KDF implementation
   6
   7 =head1 DESCRIPTION
   8
   9 Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
  10
  11 The EVP_KDF_HKDF algorithm implements the HKDF key derivation function.
  12 HKDF follows the "extract-then-expand" paradigm, where the KDF logically
  13 consists of two modules. The first stage takes the input keying material
  14 and "extracts" from it a fixed-length pseudorandom key K. The second stage
  15 "expands" the key K into several additional pseudorandom keys (the output
  16 of the KDF).
  17
  18 =head2 Numeric identity
  19
  20 B<EVP_KDF_HKDF> is the numeric identity for this implementation; it
  21 can be used with the EVP_KDF_CTX_new_id() function.
  22
  23 =head2 Supported controls
  24
  25 The supported controls are:
  26
  27 =over 4
  28
  29 =item B<EVP_KDF_CTRL_SET_SALT>
  30
  31 =item B<EVP_KDF_CTRL_SET_MD>
  32
  33 =item B<EVP_KDF_CTRL_SET_KEY>
  34
  35 These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
  36
  37 =item B<EVP_KDF_CTRL_RESET_HKDF_INFO>
  38
  39 This control does not expect any arguments.
  40
  41 Resets the context info buffer to zero length.
  42
  43 =item B<EVP_KDF_CTRL_ADD_HKDF_INFO>
  44
  45 This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
  46
  47 Sets the info value to the first B<infolen> bytes of the buffer B<info>.  If a
  48 value is already set, the contents of the buffer are appended to the existing
  49 value.
  50
  51 The total length of the context info buffer cannot exceed 1024 bytes;
  52 this should be more than enough for any normal use of HKDF.
  53
  54 EVP_KDF_ctrl_str() takes two type strings for this control:
  55
  56 =over 4
  57
  58 =item "info"
  59
  60 The value string is used as is.
  61
  62 =item "hexinfo"
  63
  64 The value string is expected to be a hexadecimal number, which will be
  65 decoded before being passed on as the control value.
  66
  67 =back
  68
  69 =item B<EVP_KDF_CTRL_SET_HKDF_MODE>
  70
  71 This control expects one argument: C<int mode>
  72
  73 Sets the mode for the HKDF operation. There are three modes that are currently
  74 defined:
  75
  76 =over 4
  77
  78 =item EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND
  79
  80 This is the default mode.  Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set
  81 up for HKDF will perform an extract followed by an expand operation in one go.
  82 The derived key returned will be the result after the expand operation. The
  83 intermediate fixed-length pseudorandom key K is not returned.
  84
  85 In this mode the digest, key, salt and info values must be set before a key is
  86 derived otherwise an error will occur.
  87
  88 =item EVP_KDF_HKDF_MODE_EXTRACT_ONLY
  89
  90 In this mode calling L<EVP_KDF_derive(3)> will just perform the extract
  91 operation. The value returned will be the intermediate fixed-length pseudorandom
  92 key K.  The C<keylen> parameter must match the size of K, which can be looked
  93 up by calling EVP_KDF_size() after setting the mode and digest.
  94
  95 The digest, key and salt values must be set before a key is derived otherwise
  96 an error will occur.
  97
  98 =item EVP_KDF_HKDF_MODE_EXPAND_ONLY
  99
 100 In this mode calling L<EVP_KDF_derive(3)> will just perform the expand
 101 operation. The input key should be set to the intermediate fixed-length
 102 pseudorandom key K returned from a previous extract operation.
 103
 104 The digest, key and info values must be set before a key is derived otherwise
 105 an error will occur.
 106
 107 =back
 108
 109 EVP_KDF_ctrl_str() type string: "mode"
 110
 111 The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY"
 112 or "EXPAND_ONLY".
 113
 114 =back
 115
 116 =head1 NOTES
 117
 118 A context for HKDF can be obtained by calling:
 119
 120  EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
 121
 122 The output length of an HKDF expand operation is specified via the C<keylen>
 123 parameter to the L<EVP_KDF_derive(3)> function.  When using
 124 EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
 125 the intermediate fixed-length pseudorandom key otherwise an error will occur.
 126 For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
 127 after setting the mode and digest on the C<EVP_KDF_CTX>.
 128
 129 =head1 EXAMPLE
 130
 131 This example derives 10 bytes using SHA-256 with the secret key "secret",
 132 salt value "salt" and info value "label":
 133
 134  EVP_KDF_CTX *kctx;
 135  unsigned char out[10];
 136
 137  kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
 138
 139  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
 140      error("EVP_KDF_CTRL_SET_MD");
 141  }
 142  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
 143      error("EVP_KDF_CTRL_SET_SALT");
 144  }
 145  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
 146      error("EVP_KDF_CTRL_SET_KEY");
 147  }
 148  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
 149      error("EVP_KDF_CTRL_ADD_HKDF_INFO");
 150  }
 151  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
 152      error("EVP_KDF_derive");
 153  }
 154
 155  EVP_KDF_CTX_free(kctx);
 156
 157 =head1 CONFORMING TO
 158
 159 RFC 5869
 160
 161 =head1 SEE ALSO
 162
 163 L<EVP_KDF_CTX>,
 164 L<EVP_KDF_CTX_new_id(3)>,
 165 L<EVP_KDF_CTX_free(3)>,
 166 L<EVP_KDF_ctrl(3)>,
 167 L<EVP_KDF_size(3)>,
 168 L<EVP_KDF_derive(3)>,
 169 L<EVP_KDF_CTX(3)/CONTROLS>
 170
 171 =head1 COPYRIGHT
 172
 173 Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
 174
 175 Licensed under the Apache License 2.0 (the "License").  You may not use
 176 this file except in compliance with the License.  You can obtain a copy
 177 in the file LICENSE in the source distribution or at
 178 L<https://www.openssl.org/source/license.html>.
 179
 180 =cut