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 EXAMPLES
 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 This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
 131 fixedinfo value "label" and salt "salt":
 132
 133   EVP_KDF_CTX *kctx;
 134   unsigned char out[10];
 135
 136   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 137
 138   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) {
 139       error("EVP_KDF_CTRL_SET_MAC");
 140   }
 141   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
 142       error("EVP_KDF_CTRL_SET_MD");
 143   }
 144   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
 145       error("EVP_KDF_CTRL_SET_KEY");
 146   }
 147   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
 148       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
 149   }
 150   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
 151       error("EVP_KDF_CTRL_SET_SALT");
 152   }
 153   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
 154       error("EVP_KDF_derive");
 155   }
 156
 157   EVP_KDF_CTX_free(kctx);
 158
 159 This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
 160 fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
 161
 162   EVP_KDF_CTX *kctx;
 163   unsigned char out[10];
 164
 165   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 166
 167   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) {
 168       error("EVP_KDF_CTRL_SET_MAC");
 169   }
 170   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
 171       error("EVP_KDF_CTRL_SET_MD");
 172   }
 173   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
 174       error("EVP_KDF_CTRL_SET_KEY");
 175   }
 176   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
 177       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
 178   }
 179   /* If not specified the salt will be set to a default value */
 180   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
 181       error("EVP_KDF_CTRL_SET_SALT");
 182   }
 183   /* If not specified the default size will be the size of the derived key */
 184   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) {
 185       error("EVP_KDF_CTRL_SET_MAC_SIZE");
 186   }
 187   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
 188       error("EVP_KDF_derive");
 189   }
 190
 191   EVP_KDF_CTX_free(kctx);
 192
 193
 194 =head1 CONFORMING TO
 195
 196 NIST SP800-56Cr1.
 197
 198 =head1 SEE ALSO
 199
 200 L<EVP_KDF_CTX>,
 201 L<EVP_KDF_CTX_new_id(3)>,
 202 L<EVP_KDF_CTX_free(3)>,
 203 L<EVP_KDF_ctrl(3)>,
 204 L<EVP_KDF_size(3)>,
 205 L<EVP_KDF_derive(3)>,
 206 L<EVP_KDF_CTX(3)/CONTROLS>
 207
 208 =head1 HISTORY
 209
 210 This functionality was added to OpenSSL 3.0.
 211
 212 =head1 COPYRIGHT
 213
 214 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
 215 (c) 2019, Oracle and/or its affiliates.  All rights reserved.
 216
 217 Licensed under the Apache License 2.0 (the "License").  You may not use
 218 this file except in compliance with the License.  You can obtain a copy
 219 in the file LICENSE in the source distribution or at
 220 L<https://www.openssl.org/source/license.html>.
 221
 222 =cut