xref: /openssl/doc/man7/EVP_KDF-SSHKDF.pod (revision 6f08353a) 
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
87The OpenSSL FIPS provider also supports the following parameters:
88
89=over 4
90
91=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
92
93A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
94This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check"
95related parameter is set to 0 and the check fails.
96
97=item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <integer>
98
99The default value of 1 causes an error during EVP_KDF_CTX_set_params() if
100used digest is not approved.
101Setting this to zero will ignore the error and set the approved
102"fips-indicator" to 0.
103This option breaks FIPS compliance if it causes the approved "fips-indicator"
104to return 0.
105
106According to SP 800-135r1, the following are approved digest algorithms: SHA-1,
107SHA2-224, SHA2-256, SHA2-384, SHA2-512.
108
109=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer>
110
111The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the
112length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112
113bits.
114Setting this to zero will ignore the error and set the approved
115"fips-indicator" to 0.
116This option breaks FIPS compliance if it causes the approved "fips-indicator"
117to return 0.
118
119=back
120
121=head1 NOTES
122
123A context for SSHKDF can be obtained by calling:
124
125 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
126 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
127
128The output length of the SSHKDF derivation is specified via the I<keylen>
129parameter to the L<EVP_KDF_derive(3)> function.
130Since the SSHKDF output length is variable, calling L<EVP_KDF_CTX_get_kdf_size(3)>
131to obtain the requisite length is not meaningful. The caller must
132allocate a buffer of the desired length, and pass that buffer to the
133L<EVP_KDF_derive(3)> function along with the desired length.
134
135=head1 EXAMPLES
136
137This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
138"xcghash" and "session_id" values:
139
140 EVP_KDF *kdf;
141 EVP_KDF_CTX *kctx;
142 char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV;
143 unsigned char key[1024] = "01234...";
144 unsigned char xcghash[32] = "012345...";
145 unsigned char session_id[32] = "012345...";
146 unsigned char out[8];
147 size_t outlen = sizeof(out);
148 OSSL_PARAM params[6], *p = params;
149
150 kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
151 kctx = EVP_KDF_CTX_new(kdf);
152 EVP_KDF_free(kdf);
153
154 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
155                                         SN_sha256, strlen(SN_sha256));
156 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
157                                          key, (size_t)1024);
158 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH,
159                                          xcghash, (size_t)32);
160 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID,
161                                          session_id, (size_t)32);
162 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE,
163                                         &type, sizeof(type));
164 *p = OSSL_PARAM_construct_end();
165 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0)
166     /* Error */
167
168
169=head1 CONFORMING TO
170
171RFC 4253
172
173=head1 SEE ALSO
174
175L<EVP_KDF(3)>,
176L<EVP_KDF_CTX_new(3)>,
177L<EVP_KDF_CTX_free(3)>,
178L<EVP_KDF_CTX_set_params(3)>,
179L<EVP_KDF_CTX_get_kdf_size(3)>,
180L<EVP_KDF_derive(3)>,
181L<EVP_KDF(3)/PARAMETERS>
182
183=head1 HISTORY
184
185This functionality was added in OpenSSL 3.0.
186
187=head1 COPYRIGHT
188
189Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
190
191Licensed under the Apache License 2.0 (the "License").  You may not use
192this file except in compliance with the License.  You can obtain a copy
193in the file LICENSE in the source distribution or at
194L<https://www.openssl.org/source/license.html>.
195
196=cut
197
198