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 85=head1 NOTES 86 87A context for SSHKDF can be obtained by calling: 88 89 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); 90 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 91 92The output length of the SSHKDF derivation is specified via the I<keylen> 93parameter to the L<EVP_KDF_derive(3)> function. 94Since the SSHKDF output length is variable, calling L<EVP_KDF_CTX_get_kdf_size(3)> 95to obtain the requisite length is not meaningful. The caller must 96allocate a buffer of the desired length, and pass that buffer to the 97L<EVP_KDF_derive(3)> function along with the desired length. 98 99=head1 EXAMPLES 100 101This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate 102"xcghash" and "session_id" values: 103 104 EVP_KDF *kdf; 105 EVP_KDF_CTX *kctx; 106 char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV; 107 unsigned char key[1024] = "01234..."; 108 unsigned char xcghash[32] = "012345..."; 109 unsigned char session_id[32] = "012345..."; 110 unsigned char out[8]; 111 size_t outlen = sizeof(out); 112 OSSL_PARAM params[6], *p = params; 113 114 kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); 115 kctx = EVP_KDF_CTX_new(kdf); 116 EVP_KDF_free(kdf); 117 118 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 119 SN_sha256, strlen(SN_sha256)); 120 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 121 key, (size_t)1024); 122 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, 123 xcghash, (size_t)32); 124 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID, 125 session_id, (size_t)32); 126 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE, 127 &type, sizeof(type)); 128 *p = OSSL_PARAM_construct_end(); 129 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) 130 /* Error */ 131 132 133=head1 CONFORMING TO 134 135RFC 4253 136 137=head1 SEE ALSO 138 139L<EVP_KDF(3)>, 140L<EVP_KDF_CTX_new(3)>, 141L<EVP_KDF_CTX_free(3)>, 142L<EVP_KDF_CTX_set_params(3)>, 143L<EVP_KDF_CTX_get_kdf_size(3)>, 144L<EVP_KDF_derive(3)>, 145L<EVP_KDF(3)/PARAMETERS> 146 147=head1 HISTORY 148 149This functionality was added in OpenSSL 3.0. 150 151=head1 COPYRIGHT 152 153Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved. 154 155Licensed under the Apache License 2.0 (the "License"). You may not use 156this file except in compliance with the License. You can obtain a copy 157in the file LICENSE in the source distribution or at 158L<https://www.openssl.org/source/license.html>. 159 160=cut 161 162