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 18The output is considered to be keying material. 19 20=head2 Identity 21 22"SSHKDF" is the name for this implementation; it 23can be used with the EVP_KDF_fetch() function. 24 25=head2 Supported parameters 26 27The supported parameters are: 28 29=over 4 30 31=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 32 33=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 34 35=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 36 37These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 38 39=item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string> 40 41=item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string> 42 43These parameters set the respective values for the KDF. 44If a value is already set, the contents are replaced. 45 46=item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <UTF8 string> 47 48This parameter sets the type for the SSHKDF operation. 49There are six supported types: 50 51=over 4 52 53=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV 54 55The Initial IV from client to server. 56A single char of value 65 (ASCII char 'A'). 57 58=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI 59 60The Initial IV from server to client 61A single char of value 66 (ASCII char 'B'). 62 63=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV 64 65The Encryption Key from client to server 66A single char of value 67 (ASCII char 'C'). 67 68=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI 69 70The Encryption Key from server to client 71A single char of value 68 (ASCII char 'D'). 72 73=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV 74 75The Integrity Key from client to server 76A single char of value 69 (ASCII char 'E'). 77 78=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI 79 80The Integrity Key from client to server 81A single char of value 70 (ASCII char 'F'). 82 83=back 84 85=back 86 87=head1 NOTES 88 89A context for SSHKDF can be obtained by calling: 90 91 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); 92 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 93 94The output length of the SSHKDF derivation is specified via the I<keylen> 95parameter to the L<EVP_KDF_derive(3)> function. 96Since the SSHKDF output length is variable, calling L<EVP_KDF_CTX_get_kdf_size(3)> 97to obtain the requisite length is not meaningful. The caller must 98allocate a buffer of the desired length, and pass that buffer to the 99L<EVP_KDF_derive(3)> function along with the desired length. 100 101=head1 EXAMPLES 102 103This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate 104"xcghash" and "session_id" values: 105 106 EVP_KDF *kdf; 107 EVP_KDF_CTX *kctx; 108 char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV; 109 unsigned char key[1024] = "01234..."; 110 unsigned char xcghash[32] = "012345..."; 111 unsigned char session_id[32] = "012345..."; 112 unsigned char out[8]; 113 size_t outlen = sizeof(out); 114 OSSL_PARAM params[6], *p = params; 115 116 kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); 117 kctx = EVP_KDF_CTX_new(kdf); 118 EVP_KDF_free(kdf); 119 120 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 121 SN_sha256, strlen(SN_sha256)); 122 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 123 key, (size_t)1024); 124 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, 125 xcghash, (size_t)32); 126 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID, 127 session_id, (size_t)32); 128 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE, 129 &type, sizeof(type)); 130 *p = OSSL_PARAM_construct_end(); 131 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) 132 /* Error */ 133 134 135=head1 CONFORMING TO 136 137RFC 4253 138 139=head1 SEE ALSO 140 141L<EVP_KDF(3)>, 142L<EVP_KDF_CTX_new(3)>, 143L<EVP_KDF_CTX_free(3)>, 144L<EVP_KDF_CTX_set_params(3)>, 145L<EVP_KDF_CTX_get_kdf_size(3)>, 146L<EVP_KDF_derive(3)>, 147L<EVP_KDF(3)/PARAMETERS> 148 149=head1 HISTORY 150 151This functionality was added in OpenSSL 3.0. 152 153=head1 COPYRIGHT 154 155Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved. 156 157Licensed under the Apache License 2.0 (the "License"). You may not use 158this file except in compliance with the License. You can obtain a copy 159in the file LICENSE in the source distribution or at 160L<https://www.openssl.org/source/license.html>. 161 162=cut 163 164