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