doc/man7/EVP_KDF_SS.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_KDF_SS - The Single Step / One Step EVP_KDF implementation
   6
   7 =head1 DESCRIPTION
   8
   9 The EVP_KDF_SS algorithm implements the Single Step key derivation function (SSKDF).
  10 SSKDF derives a key using input such as a shared secret key (that was generated
  11 during the execution of a key establishment scheme) and fixedinfo.
  12 SSKDF is also informally referred to as 'Concat KDF'.
  13
  14 =head2 Auxiliary function
  15
  16 The implementation uses a selectable auxiliary function H, which can be one of:
  17
  18 =over 4
  19
  20 =item B<H(x) = hash(x, digest=md)>
  21
  22 =item B<H(x) = HMAC_hash(x, key=salt, digest=md)>
  23
  24 =item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>
  25
  26 =back
  27
  28 Both the HMAC and KMAC implementations set the key using the 'salt' value.
  29 The hash and HMAC also require the digest to be set.
  30
  31 =head2 Numeric identity
  32
  33 B<EVP_KDF_SS> is the numeric identity for this implementation; it
  34 can be used with the EVP_KDF_CTX_new_id() function.
  35
  36 =head2 Supported controls
  37
  38 The supported controls are:
  39
  40 =over 4
  41
  42 =item B<EVP_KDF_CTRL_SET_MD>
  43
  44 =item B<EVP_KDF_CTRL_SET_MAC>
  45
  46 =item B<EVP_MAC_CTRL_SET_MAC_SIZE>
  47
  48 =item B<EVP_KDF_CTRL_SET_SALT>
  49
  50 These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
  51
  52 =item B<EVP_KDF_CTRL_SET_KEY>
  53
  54 This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
  55
  56 The shared secret used for key derivation.  This control sets the secret.
  57
  58 EVP_KDF_ctrl_str() takes two type strings for this control:
  59
  60 =over 4
  61
  62 =item "secret"
  63
  64 The value string is used as is.
  65
  66 =item "hexsecret"
  67
  68 The value string is expected to be a hexadecimal number, which will be
  69 decoded before being passed on as the control value.
  70
  71 =back
  72
  73 =item B<EVP_KDF_CTRL_SET_SSKDF_INFO>
  74
  75 This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
  76
  77 An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo.
  78
  79 EVP_KDF_ctrl_str() takes two type strings for this control:
  80
  81 =over 4
  82
  83 =item "info"
  84
  85 The value string is used as is.
  86
  87 =item "hexinfo"
  88
  89 The value string is expected to be a hexadecimal number, which will be
  90 decoded before being passed on as the control value.
  91
  92 =back
  93
  94 =back
  95
  96 =head1 NOTES
  97
  98 A context for SSKDF can be obtained by calling:
  99
 100 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 101
 102 The output length of an SSKDF is specified via the C<keylen>
 103 parameter to the L<EVP_KDF_derive(3)> function.
 104
 105 =head1 EXAMPLE
 106
 107 This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
 108 and fixedinfo value "label":
 109
 110   EVP_KDF_CTX *kctx;
 111   unsigned char out[10];
 112
 113   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 114
 115   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
 116       error("EVP_KDF_CTRL_SET_MD");
 117   }
 118   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
 119       error("EVP_KDF_CTRL_SET_KEY");
 120   }
 121   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
 122       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
 123   }
 124   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
 125       error("EVP_KDF_derive");
 126   }
 127
 128   EVP_KDF_CTX_free(kctx);
 129
 130 =head1 EXAMPLE
 131
 132 This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
 133 fixedinfo value "label" and salt "salt":
 134
 135   EVP_KDF_CTX *kctx;
 136   unsigned char out[10];
 137
 138   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 139
 140   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) {
 141       error("EVP_KDF_CTRL_SET_MAC");
 142   }
 143   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
 144       error("EVP_KDF_CTRL_SET_MD");
 145   }
 146   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
 147       error("EVP_KDF_CTRL_SET_KEY");
 148   }
 149   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
 150       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
 151   }
 152   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
 153       error("EVP_KDF_CTRL_SET_SALT");
 154   }
 155   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
 156       error("EVP_KDF_derive");
 157   }
 158
 159   EVP_KDF_CTX_free(kctx);
 160
 161 =head1 EXAMPLE
 162
 163 This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
 164 fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
 165
 166   EVP_KDF_CTX *kctx;
 167   unsigned char out[10];
 168
 169   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 170
 171   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) {
 172       error("EVP_KDF_CTRL_SET_MAC");
 173   }
 174   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
 175       error("EVP_KDF_CTRL_SET_MD");
 176   }
 177   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
 178       error("EVP_KDF_CTRL_SET_KEY");
 179   }
 180   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
 181       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
 182   }
 183   /* If not specified the salt will be set to a default value */
 184   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
 185       error("EVP_KDF_CTRL_SET_SALT");
 186   }
 187   /* If not specified the default size will be the size of the derived key */
 188   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) {
 189       error("EVP_KDF_CTRL_SET_MAC_SIZE");
 190   }
 191   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
 192       error("EVP_KDF_derive");
 193   }
 194
 195   EVP_KDF_CTX_free(kctx);
 196
 197
 198 =head1 CONFORMING TO
 199
 200 NIST SP800-56Cr1.
 201
 202 =head1 SEE ALSO
 203
 204 L<EVP_KDF_CTX>,
 205 L<EVP_KDF_CTX_new_id(3)>,
 206 L<EVP_KDF_CTX_free(3)>,
 207 L<EVP_KDF_ctrl(3)>,
 208 L<EVP_KDF_size(3)>,
 209 L<EVP_KDF_derive(3)>,
 210 L<EVP_KDF_CTX(3)/CONTROLS>
 211
 212 =head1 HISTORY
 213
 214 This functionality was added to OpenSSL 3.0.0.
 215
 216 =head1 COPYRIGHT
 217
 218 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
 219 (c) 2019, Oracle and/or its affiliates.  All rights reserved.
 220
 221 Licensed under the Apache License 2.0 (the "License").  You may not use
 222 this file except in compliance with the License.  You can obtain a copy
 223 in the file LICENSE in the source distribution or at
 224 L<https://www.openssl.org/source/license.html>.
 225
 226 =cut