doc/crypto/EVP_PKEY_HKDF.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_HKDF; EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt,
   6 EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info -
   7 HMAC-based Extract-and-Expand key derivation algorithm
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/kdf.h>
  12
  13  int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
  14
  15  int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
  16                                  int saltlen);
  17
  18  int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key,
  19                                 int keylen);
  20
  21  int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info,
  22                                  int infolen);
  23
  24 =head1 DESCRIPTION
  25
  26 The EVP_PKEY_HKDF alogorithm implements the HKDF key derivation function.
  27 HKDF follows the "extract-then-expand" paradigm, where the KDF logically
  28 consists of two modules. The first stage takes the input keying material
  29 and "extracts" from it a fixed-length pseudorandom key K. The second stage
  30 "expands" the key K into several additional pseudorandom keys (the output
  31 of the KDF).
  32
  33 EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF.
  34
  35 EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the
  36 buffer B<salt>. Any existing value is replaced.
  37
  38 EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer
  39 B<key>. Any existing value is replaced.
  40
  41 EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the
  42 buffer B<info>. If a value is already set, it is appended to the existing
  43 value.
  44
  45 =head1 NOTES
  46
  47 All these functions are implemented as macros.
  48
  49 A context for HKDF can be obtained by calling:
  50
  51  EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_HKDF, NULL);
  52
  53 The digest, key, salt and info values must be set before a key is derived or
  54 an error occurs.
  55
  56 The total length of the info buffer cannot exceed 1024 bytes in length: this
  57 should be more than enough for any normal use of HKDF.
  58
  59 The output length of the KDF is specified by the length parameter in the
  60 EVP_PKEY_derive() function. Since the output length is variable, setting
  61 the buffer to B<NULL> is not meaningful for HKDF.
  62
  63 Optimised versions of HKDF can be implemented in an ENGINE.
  64
  65 =head1 RETURN VALUES
  66
  67 All these functions return 1 for success and 0 or a negative value for failure.
  68 In particular a return value of -2 indicates the operation is not supported by
  69 the public key algorithm.
  70
  71 =head1 EXAMPLE
  72
  73 This example derives 10 bytes using SHA-256 with the secret key "secret",
  74 salt value "salt" and info value "label":
  75
  76  EVP_PKEY_CTX *pctx;
  77  unsigned char out[10];
  78  size_t outlen = sizeof(out);
  79  pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
  80
  81  if (EVP_PKEY_derive_init(pctx) <= 0)
  82     /* Error */
  83  if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0)
  84     /* Error */
  85  if (EVP_PKEY_CTX_set1_salt(pctx, "salt", 4) <= 0)
  86     /* Error */
  87  if (EVP_PKEY_CTX_set1_key(pctx, "secret", 6) <= 0)
  88     /* Error */
  89  if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 6) <= 0)
  90     /* Error */
  91  if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
  92     /* Error */
  93
  94 =head1 CONFORMING TO
  95
  96 RFC 5869
  97
  98 =head1 SEE ALSO
  99
 100 L<EVP_PKEY_CTX_new(3)>,
 101 L<EVP_PKEY_derive(3)>,
 102
 103 =cut