xref: /openssl/doc/man7/EVP_KDF-SSHKDF.pod (revision 7ed6de99) 
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