1=pod 2 3=head1 NAME 4 5EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF). 10SSKDF derives a key using input such as a shared secret key (that was generated 11during the execution of a key establishment scheme) and fixedinfo. 12SSKDF is also informally referred to as 'Concat KDF'. 13 14The output is considered to be keying material. 15 16=head2 Auxiliary function 17 18The implementation uses a selectable auxiliary function H, which can be one of: 19 20=over 4 21 22=item B<H(x) = hash(x, digest=md)> 23 24=item B<H(x) = HMAC_hash(x, key=salt, digest=md)> 25 26=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)> 27 28=back 29 30Both the HMAC and KMAC implementations set the key using the 'salt' value. 31The hash and HMAC also require the digest to be set. 32 33=head2 Identity 34 35"SSKDF" is the name for this implementation; it 36can be used with the EVP_KDF_fetch() function. 37 38=head2 Supported parameters 39 40The supported parameters are: 41 42=over 4 43 44=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 45 46=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 47 48This parameter is ignored for KMAC. 49 50=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> 51 52=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> 53 54=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 55 56These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 57 58=item "key" (B<OSSL_KDF_PARAM_SECRET>) <octet string> 59 60This parameter set the shared secret that is used for key derivation. 61 62=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> 63 64This parameter sets an optional value for fixedinfo, also known as otherinfo. 65 66=back 67 68The OpenSSL FIPS provider also supports the following parameters: 69 70=over 4 71 72=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 73 74A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 75This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" 76is set to 0 and the check fails. 77 78=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 79 80The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 81length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112 82bits. 83Setting this to zero will ignore the error and set the approved 84"fips-indicator" to 0. 85This option breaks FIPS compliance if it causes the approved "fips-indicator" 86to return 0. 87 88=back 89 90=head1 NOTES 91 92A context for SSKDF can be obtained by calling: 93 94 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 95 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 96 97The output length of an SSKDF is specified via the I<keylen> 98parameter to the L<EVP_KDF_derive(3)> function. 99 100=head1 EXAMPLES 101 102This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" 103and fixedinfo value "label": 104 105 EVP_KDF *kdf; 106 EVP_KDF_CTX *kctx; 107 unsigned char out[10]; 108 OSSL_PARAM params[4], *p = params; 109 110 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 111 kctx = EVP_KDF_CTX_new(kdf); 112 EVP_KDF_free(kdf); 113 114 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 115 SN_sha256, strlen(SN_sha256)); 116 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 117 "secret", (size_t)6); 118 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 119 "label", (size_t)5); 120 *p = OSSL_PARAM_construct_end(); 121 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 122 error("EVP_KDF_derive"); 123 } 124 125 EVP_KDF_CTX_free(kctx); 126 127This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", 128fixedinfo value "label" and salt "salt": 129 130 EVP_KDF *kdf; 131 EVP_KDF_CTX *kctx; 132 unsigned char out[10]; 133 OSSL_PARAM params[6], *p = params; 134 135 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 136 kctx = EVP_KDF_CTX_new(kdf); 137 EVP_KDF_free(kdf); 138 139 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, 140 SN_hmac, strlen(SN_hmac)); 141 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 142 SN_sha256, strlen(SN_sha256)); 143 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 144 "secret", (size_t)6); 145 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 146 "label", (size_t)5); 147 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 148 "salt", (size_t)4); 149 *p = OSSL_PARAM_construct_end(); 150 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 151 error("EVP_KDF_derive"); 152 } 153 154 EVP_KDF_CTX_free(kctx); 155 156This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" 157fixedinfo value "label", salt of "salt" and KMAC outlen of 20: 158 159 EVP_KDF *kdf; 160 EVP_KDF_CTX *kctx; 161 unsigned char out[10]; 162 OSSL_PARAM params[6], *p = params; 163 164 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 165 kctx = EVP_KDF_CTX_new(kdf); 166 EVP_KDF_free(kdf); 167 168 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, 169 SN_kmac128, strlen(SN_kmac128)); 170 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 171 "secret", (size_t)6); 172 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 173 "label", (size_t)5); 174 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 175 "salt", (size_t)4); 176 *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); 177 *p = OSSL_PARAM_construct_end(); 178 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 179 error("EVP_KDF_derive"); 180 } 181 182 EVP_KDF_CTX_free(kctx); 183 184=head1 CONFORMING TO 185 186NIST SP800-56Cr1. 187 188=head1 SEE ALSO 189 190L<EVP_KDF(3)>, 191L<EVP_KDF_CTX_new(3)>, 192L<EVP_KDF_CTX_free(3)>, 193L<EVP_KDF_CTX_set_params(3)>, 194L<EVP_KDF_CTX_get_kdf_size(3)>, 195L<EVP_KDF_derive(3)>, 196L<EVP_KDF(3)/PARAMETERS> 197 198=head1 HISTORY 199 200This functionality was added in OpenSSL 3.0. 201 202=head1 COPYRIGHT 203 204Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. Copyright 205(c) 2019, Oracle and/or its affiliates. All rights reserved. 206 207Licensed under the Apache License 2.0 (the "License"). You may not use 208this file except in compliance with the License. You can obtain a copy 209in the file LICENSE in the source distribution or at 210L<https://www.openssl.org/source/license.html>. 211 212=cut 213
