]>
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); | |
660c5344 | 69 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a | 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); | |
660c5344 | 85 | kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
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(); | |
6980e36a | 95 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { |
ccd7115a P |
96 | error("EVP_KDF_derive"); |
97 | } | |
98 | ||
660c5344 | 99 | EVP_KDF_CTX_free(kctx); |
ccd7115a P |
100 | |
101 | This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", | |
102 | fixedinfo value "label" and salt "salt": | |
103 | ||
104 | EVP_KDF *kdf; | |
105 | EVP_KDF_CTX *kctx; | |
106 | unsigned char out[10]; | |
107 | OSSL_PARAM params[6], *p = params; | |
108 | ||
109 | kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); | |
660c5344 | 110 | kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
111 | EVP_KDF_free(kdf); |
112 | ||
113 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, | |
114 | SN_hmac, strlen(SN_hmac)); | |
115 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
116 | SN_sha256, strlen(SN_sha256)); | |
117 | *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, | |
118 | "secret", (size_t)6); | |
119 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, | |
120 | "label", (size_t)5); | |
121 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
122 | "salt", (size_t)4); | |
123 | *p = OSSL_PARAM_construct_end(); | |
6980e36a | 124 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { |
ccd7115a P |
125 | error("EVP_KDF_derive"); |
126 | } | |
127 | ||
660c5344 | 128 | EVP_KDF_CTX_free(kctx); |
ccd7115a P |
129 | |
130 | This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" | |
131 | fixedinfo value "label", salt of "salt" and KMAC outlen of 20: | |
132 | ||
133 | EVP_KDF *kdf; | |
134 | EVP_KDF_CTX *kctx; | |
135 | unsigned char out[10]; | |
136 | OSSL_PARAM params[7], *p = params; | |
137 | ||
138 | kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); | |
660c5344 | 139 | kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
140 | EVP_KDF_free(kdf); |
141 | ||
142 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, | |
143 | SN_kmac128, strlen(SN_kmac128)); | |
144 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
145 | SN_sha256, strlen(SN_sha256)); | |
146 | *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, | |
147 | "secret", (size_t)6); | |
148 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, | |
149 | "label", (size_t)5); | |
150 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
151 | "salt", (size_t)4); | |
152 | *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); | |
153 | *p = OSSL_PARAM_construct_end(); | |
6980e36a | 154 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { |
ccd7115a P |
155 | error("EVP_KDF_derive"); |
156 | } | |
157 | ||
660c5344 | 158 | EVP_KDF_CTX_free(kctx); |
ccd7115a P |
159 | |
160 | =head1 CONFORMING TO | |
161 | ||
162 | NIST SP800-56Cr1. | |
163 | ||
164 | =head1 SEE ALSO | |
165 | ||
4c04e7b1 | 166 | L<EVP_KDF(3)>, |
660c5344 MC |
167 | L<EVP_KDF_CTX_new(3)>, |
168 | L<EVP_KDF_CTX_free(3)>, | |
169 | L<EVP_KDF_CTX_set_params(3)>, | |
1ba21239 | 170 | L<EVP_KDF_CTX_get_kdf_size(3)>, |
4c04e7b1 | 171 | L<EVP_KDF_derive(3)>, |
ccd7115a P |
172 | L<EVP_KDF(3)/PARAMETERS> |
173 | ||
174 | =head1 HISTORY | |
175 | ||
176 | This functionality was added to OpenSSL 3.0. | |
177 | ||
178 | =head1 COPYRIGHT | |
179 | ||
8020d79b | 180 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. Copyright |
ccd7115a P |
181 | (c) 2019, Oracle and/or its affiliates. All rights reserved. |
182 | ||
183 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
184 | this file except in compliance with the License. You can obtain a copy | |
185 | in the file LICENSE in the source distribution or at | |
186 | L<https://www.openssl.org/source/license.html>. | |
187 | ||
188 | =cut |