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