• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1=pod
2
3=head1 NAME
4
5EVP_KDF-KB - The Key-Based EVP_KDF implementation
6
7=head1 DESCRIPTION
8
9The 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
11input secret (and other optional values).
12
13=head2 Identity
14
15"KBKDF" is the name for this implementation; it can be used with the
16EVP_KDF_fetch() function.
17
18=head2 Supported parameters
19
20The supported parameters are:
21
22=over 4
23
24=item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string>
25
26The mode parameter determines which flavor of KBKDF to use - currently the
27choices are "counter" and "feedback". "counter" is the default, and will be
28used if unspecified.
29
30=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
31
32The 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
48The seed parameter is unused in counter mode.
49
50=item "use-l" (B<OSSL_KDF_PARAM_KBKDF_USE_L>) <integer>
51
52Set to B<0> to disable use of the optional Fixed Input data 'L' (see SP800-108).
53The default value of B<1> will be used if unspecified.
54
55=item "use-separator" (B<OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR>) <integer>
56
57Set 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.
59The default value of B<1> will be used if unspecified.
60
61=back
62
63Depending on whether mac is CMAC or HMAC, either digest or cipher is required
64(respectively) and the other is unused.
65
66The parameters key, salt, info, and seed correspond to KI, Label, Context, and
67IV (respectively) in SP800-108.  As in that document, salt, info, and seed are
68optional and may be omitted.
69
70"mac", "digest", cipher" and "properties" are described in
71L<EVP_KDF(3)/PARAMETERS>.
72
73=head1 NOTES
74
75A 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
80The output length of an KBKDF is specified via the C<keylen>
81parameter to the L<EVP_KDF_derive(3)> function.
82
83Note that currently OpenSSL only implements counter and feedback modes.  Other
84variants may be supported in the future.
85
86=head1 EXAMPLES
87
88This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret",
89Label "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
116This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret",
117Label "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
148NIST SP800-108, IETF RFC 6803, IETF RFC 8009.
149
150=head1 SEE ALSO
151
152L<EVP_KDF(3)>,
153L<EVP_KDF_CTX_free(3)>,
154L<EVP_KDF_CTX_get_kdf_size(3)>,
155L<EVP_KDF_derive(3)>,
156L<EVP_KDF(3)/PARAMETERS>
157
158=head1 HISTORY
159
160This functionality was added in OpenSSL 3.0.
161
162=head1 COPYRIGHT
163
164Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
165Copyright 2019 Red Hat, Inc.
166
167Licensed under the Apache License 2.0 (the "License").  You may not use
168this file except in compliance with the License.  You can obtain a copy
169in the file LICENSE in the source distribution or at
170L<https://www.openssl.org/source/license.html>.
171
172=cut
173