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 |
|
---|
24 | =item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string>
|
---|
25 |
|
---|
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 |
|
---|
30 | =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
|
---|
31 |
|
---|
32 | The value is either CMAC or HMAC.
|
---|
33 |
|
---|
34 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
|
---|
35 |
|
---|
36 | =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string>
|
---|
37 |
|
---|
38 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
|
---|
39 |
|
---|
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>
|
---|
47 |
|
---|
48 | The seed parameter is unused in counter mode.
|
---|
49 |
|
---|
50 | =item "use-l" (B<OSSL_KDF_PARAM_KBKDF_USE_L>) <integer>
|
---|
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 |
|
---|
55 | =item "use-separator" (B<OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR>) <integer>
|
---|
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 |
|
---|
61 | =back
|
---|
62 |
|
---|
63 | Depending on whether mac is CMAC or HMAC, either digest or cipher is required
|
---|
64 | (respectively) and the other is unused.
|
---|
65 |
|
---|
66 | The parameters key, salt, info, and seed correspond to KI, Label, Context, and
|
---|
67 | IV (respectively) in SP800-108. As in that document, salt, info, and seed are
|
---|
68 | optional and may be omitted.
|
---|
69 |
|
---|
70 | "mac", "digest", cipher" and "properties" are described in
|
---|
71 | L<EVP_KDF(3)/PARAMETERS>.
|
---|
72 |
|
---|
73 | =head1 NOTES
|
---|
74 |
|
---|
75 | A context for KBKDF can be obtained by calling:
|
---|
76 |
|
---|
77 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
|
---|
78 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
|
---|
79 |
|
---|
80 | The output length of an KBKDF is specified via the C<keylen>
|
---|
81 | parameter to the L<EVP_KDF_derive(3)> function.
|
---|
82 |
|
---|
83 | Note that currently OpenSSL only implements counter and feedback modes. Other
|
---|
84 | variants may be supported in the future.
|
---|
85 |
|
---|
86 | =head1 EXAMPLES
|
---|
87 |
|
---|
88 | This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret",
|
---|
89 | Label "label", and Context "context".
|
---|
90 |
|
---|
91 | EVP_KDF *kdf;
|
---|
92 | EVP_KDF_CTX *kctx;
|
---|
93 | unsigned char out[10];
|
---|
94 | OSSL_PARAM params[6], *p = params;
|
---|
95 |
|
---|
96 | kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
|
---|
97 | kctx = EVP_KDF_CTX_new(kdf);
|
---|
98 | EVP_KDF_free(kdf);
|
---|
99 |
|
---|
100 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
|
---|
101 | "SHA2-256", 0);
|
---|
102 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
|
---|
103 | "HMAC", 0);
|
---|
104 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
|
---|
105 | "secret", strlen("secret"));
|
---|
106 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
|
---|
107 | "label", strlen("label"));
|
---|
108 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
|
---|
109 | "context", strlen("context"));
|
---|
110 | *p = OSSL_PARAM_construct_end();
|
---|
111 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
|
---|
112 | error("EVP_KDF_derive");
|
---|
113 |
|
---|
114 | EVP_KDF_CTX_free(kctx);
|
---|
115 |
|
---|
116 | This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret",
|
---|
117 | Label "label", and IV "sixteen bytes iv".
|
---|
118 |
|
---|
119 | EVP_KDF *kdf;
|
---|
120 | EVP_KDF_CTX *kctx;
|
---|
121 | unsigned char out[10];
|
---|
122 | OSSL_PARAM params[8], *p = params;
|
---|
123 | unsigned char *iv = "sixteen bytes iv";
|
---|
124 |
|
---|
125 | kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
|
---|
126 | kctx = EVP_KDF_CTX_new(kdf);
|
---|
127 | EVP_KDF_free(kdf);
|
---|
128 |
|
---|
129 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
|
---|
130 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0);
|
---|
131 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0);
|
---|
132 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
|
---|
133 | "secret", strlen("secret"));
|
---|
134 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
|
---|
135 | "label", strlen("label"));
|
---|
136 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
|
---|
137 | "context", strlen("context"));
|
---|
138 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
|
---|
139 | iv, strlen(iv));
|
---|
140 | *p = OSSL_PARAM_construct_end();
|
---|
141 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
|
---|
142 | error("EVP_KDF_derive");
|
---|
143 |
|
---|
144 | EVP_KDF_CTX_free(kctx);
|
---|
145 |
|
---|
146 | =head1 CONFORMING TO
|
---|
147 |
|
---|
148 | NIST SP800-108, IETF RFC 6803, IETF RFC 8009.
|
---|
149 |
|
---|
150 | =head1 SEE ALSO
|
---|
151 |
|
---|
152 | L<EVP_KDF(3)>,
|
---|
153 | L<EVP_KDF_CTX_free(3)>,
|
---|
154 | L<EVP_KDF_CTX_get_kdf_size(3)>,
|
---|
155 | L<EVP_KDF_derive(3)>,
|
---|
156 | L<EVP_KDF(3)/PARAMETERS>
|
---|
157 |
|
---|
158 | =head1 HISTORY
|
---|
159 |
|
---|
160 | This functionality was added to OpenSSL 3.0.
|
---|
161 |
|
---|
162 | =head1 COPYRIGHT
|
---|
163 |
|
---|
164 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
|
---|
165 | Copyright 2019 Red Hat, Inc.
|
---|
166 |
|
---|
167 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
---|
168 | this file except in compliance with the License. You can obtain a copy
|
---|
169 | in the file LICENSE in the source distribution or at
|
---|
170 | L<https://www.openssl.org/source/license.html>.
|
---|
171 |
|
---|
172 | =cut
|
---|