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