]>
Commit | Line | Data |
---|---|---|
8d76481b SS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ccd7115a | 5 | EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation |
8d76481b SS |
6 | |
7 | =head1 DESCRIPTION | |
8 | ||
9 | Support for computing the B<SSHKDF> KDF through the B<EVP_KDF> API. | |
10 | ||
ccd7115a | 11 | The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function. |
8d76481b SS |
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 | ||
ccd7115a | 18 | =head2 Identity |
8d76481b | 19 | |
ccd7115a P |
20 | "SSHKDF" is the name for this implementation; it |
21 | can be used with the EVP_KDF_fetch() function. | |
8d76481b | 22 | |
ccd7115a | 23 | =head2 Supported parameters |
8d76481b | 24 | |
ccd7115a | 25 | The supported parameters are: |
8d76481b SS |
26 | |
27 | =over 4 | |
28 | ||
0c452a51 | 29 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> |
8d76481b | 30 | |
0c452a51 | 31 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
8d76481b | 32 | |
0c452a51 | 33 | =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> |
8d76481b | 34 | |
ccd7115a | 35 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. |
8d76481b | 36 | |
0c452a51 | 37 | =item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string> |
8d76481b | 38 | |
0c452a51 | 39 | =item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string> |
8d76481b | 40 | |
ccd7115a P |
41 | These parameters set the respective values for the KDF. |
42 | If a value is already set, the contents are replaced. | |
8d76481b | 43 | |
0c452a51 | 44 | =item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <integer> |
8d76481b | 45 | |
ccd7115a P |
46 | This parameter sets the type for the SSHHKDF operation. |
47 | There are six supported types: | |
8d76481b SS |
48 | |
49 | =over 4 | |
50 | ||
c2969ff6 | 51 | =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV |
8d76481b SS |
52 | |
53 | The Initial IV from client to server. | |
54 | A single char of value 65 (ASCII char 'A'). | |
55 | ||
c2969ff6 | 56 | =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI |
8d76481b SS |
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 | ||
8d76481b SS |
83 | =back |
84 | ||
85 | =head1 NOTES | |
86 | ||
87 | A context for SSHKDF can be obtained by calling: | |
88 | ||
ccd7115a P |
89 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); |
90 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); | |
8d76481b | 91 | |
dfabee82 | 92 | The output length of the SSHKDF derivation is specified via the I<keylen> |
ccd7115a P |
93 | parameter to the L<EVP_KDF-derive(3)> function. |
94 | Since the SSHKDF output length is variable, calling L<EVP_KDF-size()> | |
8d76481b SS |
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 | |
ccd7115a | 97 | L<EVP_KDF-derive(3)> function along with the desired length. |
8d76481b | 98 | |
cda77422 | 99 | =head1 EXAMPLES |
8d76481b SS |
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 | ||
ccd7115a | 104 | EVP_KDF *kdf; |
8d76481b SS |
105 | EVP_KDF_CTX *kctx; |
106 | unsigned char key[1024] = "01234..."; | |
107 | unsigned char xcghash[32] = "012345..."; | |
108 | unsigned char session_id[32] = "012345..."; | |
109 | unsigned char out[8]; | |
110 | size_t outlen = sizeof(out); | |
ccd7115a P |
111 | OSSL_PARAM params[6], *p = params; |
112 | ||
113 | kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); | |
114 | kctx = EVP_KDF_CTX_new(kdf); | |
115 | EVP_KDF_free(kdf); | |
116 | ||
117 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
118 | SN_sha256, strlen(SN_sha256)); | |
119 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, | |
120 | key, (size_t)1024); | |
121 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, | |
122 | xcghash, (size_t)32); | |
123 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
124 | session_id, (size_t)32); | |
125 | *p++ = OSSL_PARAM_construct_int(OSSL_KDF_PARAM_SSHKDF_TYPE, | |
126 | EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV); | |
127 | *p = OSSL_PARAM_construct_end(); | |
a218770d | 128 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) |
8d76481b | 129 | /* Error */ |
ccd7115a | 130 | |
8d76481b SS |
131 | if (EVP_KDF_derive(kctx, out, &outlen) <= 0) |
132 | /* Error */ | |
133 | ||
134 | ||
135 | =head1 CONFORMING TO | |
136 | ||
137 | RFC 4253 | |
138 | ||
139 | =head1 SEE ALSO | |
140 | ||
4c04e7b1 P |
141 | L<EVP_KDF(3)>, |
142 | L<EVP_KDF_CTX_new(3)>, | |
143 | L<EVP_KDF_CTX_free(3)>, | |
144 | L<EVP_KDF_CTX_set_params(3)>, | |
145 | L<EVP_KDF_size(3)>, | |
146 | L<EVP_KDF_derive(3)>, | |
ccd7115a | 147 | L<EVP_KDF(3)/PARAMETERS> |
8d76481b SS |
148 | |
149 | =head1 COPYRIGHT | |
150 | ||
40526dfd | 151 | Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. |
8d76481b SS |
152 | |
153 | Licensed under the OpenSSL license (the "License"). You may not use | |
154 | this file except in compliance with the License. You can obtain a copy | |
155 | in the file LICENSE in the source distribution or at | |
156 | L<https://www.openssl.org/source/license.html>. | |
157 | ||
158 | =cut | |
159 |