1=pod 2 3=head1 NAME 4 5EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9Support for computing the B<SSHKDF> KDF through the B<EVP_KDF> API. 10 11The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function. 12It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs, 13encryption keys and integrity keys. 14Five inputs are required to perform key derivation: The hashing function 15(for example SHA256), the Initial Key, the Exchange Hash, the Session ID, 16and the derivation key type. 17 18=head2 Identity 19 20"SSHKDF" is the name for this implementation; it 21can be used with the EVP_KDF_fetch() function. 22 23=head2 Supported parameters 24 25The supported parameters are: 26 27=over 4 28 29=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 30 31=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 32 33=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 34 35These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 36 37=item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string> 38 39=item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string> 40 41These parameters set the respective values for the KDF. 42If a value is already set, the contents are replaced. 43 44=item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <UTF8 string> 45 46This parameter sets the type for the SSHKDF operation. 47There are six supported types: 48 49=over 4 50 51=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV 52 53The Initial IV from client to server. 54A single char of value 65 (ASCII char 'A'). 55 56=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI 57 58The Initial IV from server to client 59A single char of value 66 (ASCII char 'B'). 60 61=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV 62 63The Encryption Key from client to server 64A single char of value 67 (ASCII char 'C'). 65 66=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI 67 68The Encryption Key from server to client 69A single char of value 68 (ASCII char 'D'). 70 71=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV 72 73The Integrity Key from client to server 74A single char of value 69 (ASCII char 'E'). 75 76=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI 77 78The Integrity Key from client to server 79A single char of value 70 (ASCII char 'F'). 80 81=back 82 83=back 84 85The OpenSSL FIPS provider also supports the following parameters: 86 87=over 4 88 89=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 90 91A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 92This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" 93related parameter is set to 0 and the check fails. 94 95=item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <integer> 96 97The default value of 1 causes an error during EVP_KDF_CTX_set_params() if 98used digest is not approved. 99Setting this to zero will ignore the error and set the approved 100"fips-indicator" to 0. 101This option breaks FIPS compliance if it causes the approved "fips-indicator" 102to return 0. 103 104According to SP 800-135r1, the following are approved digest algorithms: SHA-1, 105SHA2-224, SHA2-256, SHA2-384, SHA2-512. 106 107=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 108 109The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 110length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112 111bits. 112Setting this to zero will ignore the error and set the approved 113"fips-indicator" to 0. 114This option breaks FIPS compliance if it causes the approved "fips-indicator" 115to return 0. 116 117=back 118 119=head1 NOTES 120 121A context for SSHKDF can be obtained by calling: 122 123 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); 124 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 125 126The output length of the SSHKDF derivation is specified via the I<keylen> 127parameter to the L<EVP_KDF_derive(3)> function. 128Since the SSHKDF output length is variable, calling L<EVP_KDF_CTX_get_kdf_size(3)> 129to obtain the requisite length is not meaningful. The caller must 130allocate a buffer of the desired length, and pass that buffer to the 131L<EVP_KDF_derive(3)> function along with the desired length. 132 133=head1 EXAMPLES 134 135This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate 136"xcghash" and "session_id" values: 137 138 EVP_KDF *kdf; 139 EVP_KDF_CTX *kctx; 140 char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV; 141 unsigned char key[1024] = "01234..."; 142 unsigned char xcghash[32] = "012345..."; 143 unsigned char session_id[32] = "012345..."; 144 unsigned char out[8]; 145 size_t outlen = sizeof(out); 146 OSSL_PARAM params[6], *p = params; 147 148 kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); 149 kctx = EVP_KDF_CTX_new(kdf); 150 EVP_KDF_free(kdf); 151 152 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 153 SN_sha256, strlen(SN_sha256)); 154 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 155 key, (size_t)1024); 156 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, 157 xcghash, (size_t)32); 158 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID, 159 session_id, (size_t)32); 160 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE, 161 &type, sizeof(type)); 162 *p = OSSL_PARAM_construct_end(); 163 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) 164 /* Error */ 165 166 167=head1 CONFORMING TO 168 169RFC 4253 170 171=head1 SEE ALSO 172 173L<EVP_KDF(3)>, 174L<EVP_KDF_CTX_new(3)>, 175L<EVP_KDF_CTX_free(3)>, 176L<EVP_KDF_CTX_set_params(3)>, 177L<EVP_KDF_CTX_get_kdf_size(3)>, 178L<EVP_KDF_derive(3)>, 179L<EVP_KDF(3)/PARAMETERS> 180 181=head1 HISTORY 182 183This functionality was added in OpenSSL 3.0. 184 185=head1 COPYRIGHT 186 187Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. 188 189Licensed under the Apache License 2.0 (the "License"). You may not use 190this file except in compliance with the License. You can obtain a copy 191in the file LICENSE in the source distribution or at 192L<https://www.openssl.org/source/license.html>. 193 194=cut 195 196