doc/man7/EVP_KDF-KB.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_KDF-KB - The Key-Based EVP_KDF implementation
   6
   7 =head1 DESCRIPTION
   8
   9 The EVP_KDF-KB algorithm implements the Key-Based key derivation function
  10 (KBKDF).  KBKDF derives a key from repeated application of a keyed MAC to an
  11 input secret (and other optional values).
  12
  13 =head2 Identity
  14
  15 "KBKDF" is the name for this implementation; it can be used with the
  16 EVP_KDF_fetch() function.
  17
  18 =head2 Supported parameters
  19
  20 The supported parameters are:
  21
  22 =over 4
  23
  24 =item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string>
  25
  26 The mode parameter determines which flavor of KBKDF to use - currently the
  27 choices are "counter" and "feedback". "counter" is the default, and will be
  28 used if unspecified.
  29
  30 =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
  31
  32 The value is either CMAC, HMAC, KMAC128 or KMAC256.
  33
  34 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
  35
  36 =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string>
  37
  38 =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
  39
  40 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
  41
  42 =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
  43
  44 =item "info (B<OSSL_KDF_PARAM_INFO>) <octet string>
  45
  46 =item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string>
  47
  48 The seed parameter is unused in counter mode.
  49
  50 =item "use-l" (B<OSSL_KDF_PARAM_KBKDF_USE_L>) <integer>
  51
  52 Set to B<0> to disable use of the optional Fixed Input data 'L' (see SP800-108).
  53 The default value of B<1> will be used if unspecified.
  54
  55 =item "use-separator" (B<OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR>) <integer>
  56
  57 Set to B<0> to disable use of the optional Fixed Input data 'zero separator'
  58 (see SP800-108) that is placed between the Label and Context.
  59 The default value of B<1> will be used if unspecified.
  60
  61 =item "r" (B<OSSL_KDF_PARAM_KBKDF_R>) <integer>
  62
  63 Set the fixed value 'r', indicating the length of the counter in bits.
  64
  65 Supported values are B<8>, B<16>, B<24>, and B<32>.
  66 The default value of B<32> will be used if unspecified.
  67
  68 =back
  69
  70 Depending on whether mac is CMAC or HMAC, either digest or cipher is required
  71 (respectively) and the other is unused. They are unused for KMAC128 and KMAC256.
  72
  73 The parameters key, salt, info, and seed correspond to KI, Label, Context, and
  74 IV (respectively) in SP800-108.  As in that document, salt, info, and seed are
  75 optional and may be omitted.
  76
  77 "mac", "digest", cipher" and "properties" are described in
  78 L<EVP_KDF(3)/PARAMETERS>.
  79
  80 =head1 NOTES
  81
  82 A context for KBKDF can be obtained by calling:
  83
  84  EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
  85  EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
  86
  87 The output length of an KBKDF is specified via the C<keylen>
  88 parameter to the L<EVP_KDF_derive(3)> function.
  89
  90 Note that currently OpenSSL only implements counter and feedback modes.  Other
  91 variants may be supported in the future.
  92
  93 =head1 EXAMPLES
  94
  95 This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret",
  96 Label "label", and Context "context".
  97
  98  EVP_KDF *kdf;
  99  EVP_KDF_CTX *kctx;
 100  unsigned char out[10];
 101  OSSL_PARAM params[6], *p = params;
 102
 103  kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
 104  kctx = EVP_KDF_CTX_new(kdf);
 105  EVP_KDF_free(kdf);
 106
 107  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
 108                                          "SHA2-256", 0);
 109  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
 110                                          "HMAC", 0);
 111  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
 112                                           "secret", strlen("secret"));
 113  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
 114                                           "label", strlen("label"));
 115  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
 116                                           "context", strlen("context"));
 117  *p = OSSL_PARAM_construct_end();
 118  if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
 119      error("EVP_KDF_derive");
 120
 121  EVP_KDF_CTX_free(kctx);
 122
 123 This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret",
 124 Label "label", and IV "sixteen bytes iv".
 125
 126  EVP_KDF *kdf;
 127  EVP_KDF_CTX *kctx;
 128  unsigned char out[10];
 129  OSSL_PARAM params[8], *p = params;
 130  unsigned char *iv = "sixteen bytes iv";
 131
 132  kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
 133  kctx = EVP_KDF_CTX_new(kdf);
 134  EVP_KDF_free(kdf);
 135
 136  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
 137  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0);
 138  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0);
 139  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
 140                                           "secret", strlen("secret"));
 141  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
 142                                           "label", strlen("label"));
 143  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
 144                                           "context", strlen("context"));
 145  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
 146                                           iv, strlen(iv));
 147  *p = OSSL_PARAM_construct_end();
 148  if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
 149      error("EVP_KDF_derive");
 150
 151  EVP_KDF_CTX_free(kctx);
 152
 153 =head1 CONFORMING TO
 154
 155 NIST SP800-108, IETF RFC 6803, IETF RFC 8009.
 156
 157 =head1 SEE ALSO
 158
 159 L<EVP_KDF(3)>,
 160 L<EVP_KDF_CTX_free(3)>,
 161 L<EVP_KDF_CTX_get_kdf_size(3)>,
 162 L<EVP_KDF_derive(3)>,
 163 L<EVP_KDF(3)/PARAMETERS>
 164
 165 =head1 HISTORY
 166
 167 This functionality was added in OpenSSL 3.0.
 168
 169 Support for KMAC was added in OpenSSL 3.1.
 170
 171 =head1 COPYRIGHT
 172
 173 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
 174 Copyright 2019 Red Hat, Inc.
 175
 176 Licensed under the Apache License 2.0 (the "License").  You may not use
 177 this file except in compliance with the License.  You can obtain a copy
 178 in the file LICENSE in the source distribution or at
 179 L<https://www.openssl.org/source/license.html>.
 180
 181 =cut