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 68=head1 NOTES 69 70A context for SSKDF can be obtained by calling: 71 72 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 73 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 74 75The output length of an SSKDF is specified via the I<keylen> 76parameter to the L<EVP_KDF_derive(3)> function. 77 78=head1 EXAMPLES 79 80This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" 81and fixedinfo value "label": 82 83 EVP_KDF *kdf; 84 EVP_KDF_CTX *kctx; 85 unsigned char out[10]; 86 OSSL_PARAM params[4], *p = params; 87 88 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 89 kctx = EVP_KDF_CTX_new(kdf); 90 EVP_KDF_free(kdf); 91 92 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 93 SN_sha256, strlen(SN_sha256)); 94 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 95 "secret", (size_t)6); 96 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 97 "label", (size_t)5); 98 *p = OSSL_PARAM_construct_end(); 99 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 100 error("EVP_KDF_derive"); 101 } 102 103 EVP_KDF_CTX_free(kctx); 104 105This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", 106fixedinfo value "label" and salt "salt": 107 108 EVP_KDF *kdf; 109 EVP_KDF_CTX *kctx; 110 unsigned char out[10]; 111 OSSL_PARAM params[6], *p = params; 112 113 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 114 kctx = EVP_KDF_CTX_new(kdf); 115 EVP_KDF_free(kdf); 116 117 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, 118 SN_hmac, strlen(SN_hmac)); 119 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 120 SN_sha256, strlen(SN_sha256)); 121 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 122 "secret", (size_t)6); 123 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 124 "label", (size_t)5); 125 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 126 "salt", (size_t)4); 127 *p = OSSL_PARAM_construct_end(); 128 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 129 error("EVP_KDF_derive"); 130 } 131 132 EVP_KDF_CTX_free(kctx); 133 134This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" 135fixedinfo value "label", salt of "salt" and KMAC outlen of 20: 136 137 EVP_KDF *kdf; 138 EVP_KDF_CTX *kctx; 139 unsigned char out[10]; 140 OSSL_PARAM params[6], *p = params; 141 142 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); 143 kctx = EVP_KDF_CTX_new(kdf); 144 EVP_KDF_free(kdf); 145 146 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, 147 SN_kmac128, strlen(SN_kmac128)); 148 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 149 "secret", (size_t)6); 150 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 151 "label", (size_t)5); 152 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 153 "salt", (size_t)4); 154 *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); 155 *p = OSSL_PARAM_construct_end(); 156 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 157 error("EVP_KDF_derive"); 158 } 159 160 EVP_KDF_CTX_free(kctx); 161 162=head1 CONFORMING TO 163 164NIST SP800-56Cr1. 165 166=head1 SEE ALSO 167 168L<EVP_KDF(3)>, 169L<EVP_KDF_CTX_new(3)>, 170L<EVP_KDF_CTX_free(3)>, 171L<EVP_KDF_CTX_set_params(3)>, 172L<EVP_KDF_CTX_get_kdf_size(3)>, 173L<EVP_KDF_derive(3)>, 174L<EVP_KDF(3)/PARAMETERS> 175 176=head1 HISTORY 177 178This functionality was added in OpenSSL 3.0. 179 180=head1 COPYRIGHT 181 182Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. Copyright 183(c) 2019, Oracle and/or its affiliates. All rights reserved. 184 185Licensed under the Apache License 2.0 (the "License"). You may not use 186this file except in compliance with the License. You can obtain a copy 187in the file LICENSE in the source distribution or at 188L<https://www.openssl.org/source/license.html>. 189 190=cut 191