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