]>
Commit | Line | Data |
---|---|---|
a39bc440 RH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF-KB - The Key-Based EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | The EVP_KDF-KB algorithm implements the Key-Based key derivation function | |
10 | (KBKDF). KBKDF derives a key from repeated application of a keyed MAC to an | |
11 | input secret (and other optional values). | |
12 | ||
13 | =head2 Identity | |
14 | ||
15 | "KBKDF" is the name for this implementation; it can be used with the | |
16 | EVP_KDF_fetch() function. | |
17 | ||
18 | =head2 Supported parameters | |
19 | ||
20 | The supported parameters are: | |
21 | ||
22 | =over 4 | |
23 | ||
f6dead1b | 24 | =item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string> |
a39bc440 | 25 | |
4757a347 SL |
26 | The mode parameter determines which flavor of KBKDF to use - currently the |
27 | choices are "counter" and "feedback". "counter" is the default, and will be | |
28 | used if unspecified. | |
29 | ||
f6dead1b | 30 | =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> |
a39bc440 | 31 | |
4757a347 SL |
32 | The value is either CMAC or HMAC. |
33 | ||
f6dead1b | 34 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
a39bc440 | 35 | |
4757a347 SL |
36 | =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string> |
37 | ||
38 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> | |
a39bc440 | 39 | |
f6dead1b RH |
40 | =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> |
41 | ||
42 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> | |
43 | ||
44 | =item "info (B<OSSL_KDF_PARAM_INFO>) <octet string> | |
45 | ||
46 | =item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string> | |
a39bc440 | 47 | |
4757a347 SL |
48 | The seed parameter is unused in counter mode. |
49 | ||
c9f18e59 | 50 | =item "use-l" (B<OSSL_KDF_PARAM_KBKDF_USE_L>) <integer> |
4757a347 SL |
51 | |
52 | Set to B<0> to disable use of the optional Fixed Input data 'L' (see SP800-108). | |
53 | The default value of B<1> will be used if unspecified. | |
54 | ||
c9f18e59 | 55 | =item "use-separator" (B<OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR>) <integer> |
4757a347 SL |
56 | |
57 | Set to B<0> to disable use of the optional Fixed Input data 'zero separator' | |
58 | (see SP800-108) that is placed between the Label and Context. | |
59 | The default value of B<1> will be used if unspecified. | |
60 | ||
0e9a265e PU |
61 | =item "r" (B<OSSL_KDF_PARAM_KBKDF_R>) <integer> |
62 | ||
63 | Set the fixed value 'r', indicating the length of the counter in bits. | |
64 | ||
65 | Supported values are B<8>, B<16>, B<24>, and B<32>. | |
66 | The default value of B<32> will be used if unspecified. | |
67 | ||
a39bc440 RH |
68 | =back |
69 | ||
4757a347 SL |
70 | Depending on whether mac is CMAC or HMAC, either digest or cipher is required |
71 | (respectively) and the other is unused. | |
f6dead1b RH |
72 | |
73 | The parameters key, salt, info, and seed correspond to KI, Label, Context, and | |
74 | IV (respectively) in SP800-108. As in that document, salt, info, and seed are | |
75 | optional and may be omitted. | |
76 | ||
4757a347 SL |
77 | "mac", "digest", cipher" and "properties" are described in |
78 | L<EVP_KDF(3)/PARAMETERS>. | |
a39bc440 RH |
79 | |
80 | =head1 NOTES | |
81 | ||
82 | A context for KBKDF can be obtained by calling: | |
83 | ||
84 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); | |
660c5344 | 85 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); |
a39bc440 RH |
86 | |
87 | The output length of an KBKDF is specified via the C<keylen> | |
88 | parameter to the L<EVP_KDF_derive(3)> function. | |
89 | ||
f6dead1b | 90 | Note that currently OpenSSL only implements counter and feedback modes. Other |
a39bc440 RH |
91 | variants may be supported in the future. |
92 | ||
93 | =head1 EXAMPLES | |
94 | ||
95 | This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret", | |
96 | Label "label", and Context "context". | |
97 | ||
98 | EVP_KDF *kdf; | |
99 | EVP_KDF_CTX *kctx; | |
100 | unsigned char out[10]; | |
101 | OSSL_PARAM params[6], *p = params; | |
102 | ||
103 | kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); | |
660c5344 | 104 | kctx = EVP_KDF_CTX_new(kdf); |
a39bc440 RH |
105 | EVP_KDF_free(kdf); |
106 | ||
107 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
e44192d1 | 108 | "SHA2-256", 0); |
a39bc440 RH |
109 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, |
110 | "HMAC", 0); | |
111 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, | |
c99248ea | 112 | "secret", strlen("secret")); |
a39bc440 | 113 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, |
a39bc440 | 114 | "label", strlen("label")); |
a90311fe TM |
115 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, |
116 | "context", strlen("context")); | |
a39bc440 | 117 | *p = OSSL_PARAM_construct_end(); |
6980e36a | 118 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) |
a39bc440 RH |
119 | error("EVP_KDF_derive"); |
120 | ||
660c5344 | 121 | EVP_KDF_CTX_free(kctx); |
a39bc440 | 122 | |
f6dead1b RH |
123 | This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret", |
124 | Label "label", and IV "sixteen bytes iv". | |
125 | ||
126 | EVP_KDF *kdf; | |
127 | EVP_KDF_CTX *kctx; | |
128 | unsigned char out[10]; | |
129 | OSSL_PARAM params[8], *p = params; | |
130 | unsigned char *iv = "sixteen bytes iv"; | |
131 | ||
132 | kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); | |
660c5344 | 133 | kctx = EVP_KDF_CTX_new(kdf); |
f6dead1b RH |
134 | EVP_KDF_free(kdf); |
135 | ||
136 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0); | |
137 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0); | |
138 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0); | |
139 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, | |
140 | "secret", strlen("secret")); | |
141 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
f6dead1b | 142 | "label", strlen("label")); |
a90311fe TM |
143 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, |
144 | "context", strlen("context")); | |
f6dead1b RH |
145 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, |
146 | iv, strlen(iv)); | |
147 | *p = OSSL_PARAM_construct_end(); | |
4139a0c6 | 148 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) |
f6dead1b RH |
149 | error("EVP_KDF_derive"); |
150 | ||
660c5344 | 151 | EVP_KDF_CTX_free(kctx); |
f6dead1b | 152 | |
a39bc440 RH |
153 | =head1 CONFORMING TO |
154 | ||
f6dead1b | 155 | NIST SP800-108, IETF RFC 6803, IETF RFC 8009. |
a39bc440 RH |
156 | |
157 | =head1 SEE ALSO | |
158 | ||
159 | L<EVP_KDF(3)>, | |
660c5344 | 160 | L<EVP_KDF_CTX_free(3)>, |
1ba21239 | 161 | L<EVP_KDF_CTX_get_kdf_size(3)>, |
a39bc440 RH |
162 | L<EVP_KDF_derive(3)>, |
163 | L<EVP_KDF(3)/PARAMETERS> | |
164 | ||
165 | =head1 HISTORY | |
166 | ||
167 | This functionality was added to OpenSSL 3.0. | |
168 | ||
169 | =head1 COPYRIGHT | |
170 | ||
8020d79b | 171 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
a39bc440 RH |
172 | Copyright 2019 Red Hat, Inc. |
173 | ||
174 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
175 | this file except in compliance with the License. You can obtain a copy | |
176 | in the file LICENSE in the source distribution or at | |
177 | L<https://www.openssl.org/source/license.html>. | |
178 | ||
179 | =cut |