]>
Commit | Line | Data |
---|---|---|
ccd7115a P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF). | |
10 | SSKDF derives a key using input such as a shared secret key (that was generated | |
11 | during the execution of a key establishment scheme) and fixedinfo. | |
12 | SSKDF is also informally referred to as 'Concat KDF'. | |
13 | ||
14 | =head2 Auxiliary function | |
15 | ||
16 | The implementation uses a selectable auxiliary function H, which can be one of: | |
17 | ||
18 | =over 4 | |
19 | ||
20 | =item B<H(x) = hash(x, digest=md)> | |
21 | ||
22 | =item B<H(x) = HMAC_hash(x, key=salt, digest=md)> | |
23 | ||
24 | =item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)> | |
25 | ||
26 | =back | |
27 | ||
28 | Both the HMAC and KMAC implementations set the key using the 'salt' value. | |
29 | The hash and HMAC also require the digest to be set. | |
30 | ||
31 | =head2 Identity | |
32 | ||
33 | "SSKDF" is the name for this implementation; it | |
34 | can be used with the EVP_KDF_fetch() function. | |
35 | ||
36 | =head2 Supported parameters | |
37 | ||
38 | The supported parameters are: | |
39 | ||
40 | =over 4 | |
41 | ||
0c452a51 | 42 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> |
ccd7115a | 43 | |
0c452a51 | 44 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
ccd7115a | 45 | |
0c452a51 | 46 | =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> |
ccd7115a | 47 | |
0c452a51 | 48 | =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> |
ccd7115a | 49 | |
0c452a51 | 50 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> |
ccd7115a P |
51 | |
52 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. | |
53 | ||
0c452a51 | 54 | =item "key" (B<EVP_KDF_CTRL_SET_KEY>) <octet string> |
ccd7115a P |
55 | |
56 | This parameter set the shared secret that is used for key derivation. | |
57 | ||
0c452a51 | 58 | =item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> |
ccd7115a P |
59 | |
60 | This parameter sets an optional value for fixedinfo, also known as otherinfo. | |
61 | ||
62 | =back | |
63 | ||
64 | =head1 NOTES | |
65 | ||
66 | A context for SSKDF can be obtained by calling: | |
67 | ||
68 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); | |
69 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); | |
70 | ||
dfabee82 | 71 | The output length of an SSKDF is specified via the I<keylen> |
86913ef7 | 72 | parameter to the L<EVP_KDF_derive(3)> function. |
ccd7115a P |
73 | |
74 | =head1 EXAMPLES | |
75 | ||
76 | This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" | |
77 | and fixedinfo value "label": | |
78 | ||
79 | EVP_KDF *kdf; | |
80 | EVP_KDF_CTX *kctx; | |
81 | unsigned char out[10]; | |
82 | OSSL_PARAM params[4], *p = params; | |
83 | ||
84 | kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); | |
85 | kctx = EVP_KDF_CTX_new(kdf); | |
86 | EVP_KDF_free(kdf); | |
87 | ||
88 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
89 | SN_sha256, strlen(SN_sha256)); | |
90 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, | |
91 | "secret", (size_t)6); | |
92 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, | |
93 | "label", (size_t)5); | |
94 | *p = OSSL_PARAM_construct_end(); | |
a218770d P |
95 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) { |
96 | error("EVP_KDF_CTX_set_params"); | |
ccd7115a P |
97 | } |
98 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
99 | error("EVP_KDF_derive"); | |
100 | } | |
101 | ||
102 | EVP_KDF_CTX_free(kctx); | |
103 | ||
104 | This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", | |
105 | fixedinfo value "label" and salt "salt": | |
106 | ||
107 | EVP_KDF *kdf; | |
108 | EVP_KDF_CTX *kctx; | |
109 | unsigned char out[10]; | |
110 | OSSL_PARAM params[6], *p = params; | |
111 | ||
112 | kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); | |
113 | kctx = EVP_KDF_CTX_new(kdf); | |
114 | EVP_KDF_free(kdf); | |
115 | ||
116 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, | |
117 | SN_hmac, strlen(SN_hmac)); | |
118 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
119 | SN_sha256, strlen(SN_sha256)); | |
120 | *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, | |
121 | "secret", (size_t)6); | |
122 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, | |
123 | "label", (size_t)5); | |
124 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
125 | "salt", (size_t)4); | |
126 | *p = OSSL_PARAM_construct_end(); | |
a218770d P |
127 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) { |
128 | error("EVP_KDF_CTX_set_params"); | |
ccd7115a P |
129 | } |
130 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
131 | error("EVP_KDF_derive"); | |
132 | } | |
133 | ||
134 | EVP_KDF_CTX_free(kctx); | |
135 | ||
136 | This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" | |
137 | fixedinfo value "label", salt of "salt" and KMAC outlen of 20: | |
138 | ||
139 | EVP_KDF *kdf; | |
140 | EVP_KDF_CTX *kctx; | |
141 | unsigned char out[10]; | |
142 | OSSL_PARAM params[7], *p = params; | |
143 | ||
144 | kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); | |
145 | kctx = EVP_KDF_CTX_new(kdf); | |
146 | EVP_KDF_free(kdf); | |
147 | ||
148 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, | |
149 | SN_kmac128, strlen(SN_kmac128)); | |
150 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
151 | SN_sha256, strlen(SN_sha256)); | |
152 | *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, | |
153 | "secret", (size_t)6); | |
154 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, | |
155 | "label", (size_t)5); | |
156 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
157 | "salt", (size_t)4); | |
158 | *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); | |
159 | *p = OSSL_PARAM_construct_end(); | |
a218770d P |
160 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) { |
161 | error("EVP_KDF_CTX_set_params"); | |
ccd7115a P |
162 | } |
163 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
164 | error("EVP_KDF_derive"); | |
165 | } | |
166 | ||
167 | EVP_KDF_CTX_free(kctx); | |
168 | ||
169 | =head1 CONFORMING TO | |
170 | ||
171 | NIST SP800-56Cr1. | |
172 | ||
173 | =head1 SEE ALSO | |
174 | ||
4c04e7b1 P |
175 | L<EVP_KDF(3)>, |
176 | L<EVP_KDF_CTX_new(3)>, | |
177 | L<EVP_KDF_CTX_free(3)>, | |
178 | L<EVP_KDF_CTX_set_params(3)>, | |
179 | L<EVP_KDF_size(3)>, | |
180 | L<EVP_KDF_derive(3)>, | |
ccd7115a P |
181 | L<EVP_KDF(3)/PARAMETERS> |
182 | ||
183 | =head1 HISTORY | |
184 | ||
185 | This functionality was added to OpenSSL 3.0. | |
186 | ||
187 | =head1 COPYRIGHT | |
188 | ||
189 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright | |
190 | (c) 2019, Oracle and/or its affiliates. All rights reserved. | |
191 | ||
192 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
193 | this file except in compliance with the License. You can obtain a copy | |
194 | in the file LICENSE in the source distribution or at | |
195 | L<https://www.openssl.org/source/license.html>. | |
196 | ||
197 | =cut |