b3de26a4644b8e89bbbf00619d4178f5e7e6896f
[openssl.git] / doc / man7 / EVP_KDF_SS.pod
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 Numeric identity
32
33 B<EVP_KDF_SS> is the numeric identity for this implementation; it
34 can be used with the EVP_KDF_CTX_new_id() function.
35
36 =head2 Supported controls
37
38 The supported controls are:
39
40 =over 4
41
42 =item B<EVP_KDF_CTRL_SET_MD>
43
44 =item B<EVP_KDF_CTRL_SET_MAC>
45
46 =item B<EVP_MAC_CTRL_SET_MAC_SIZE>
47
48 =item B<EVP_KDF_CTRL_SET_SALT>
49
50 These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
51
52 =item B<EVP_KDF_CTRL_SET_KEY>
53
54 This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
55
56 The shared secret used for key derivation.  This control sets the secret.
57
58 EVP_KDF_ctrl_str() takes two type strings for this control:
59
60 =over 4
61
62 =item "secret"
63
64 The value string is used as is.
65
66 =item "hexsecret"
67
68 The value string is expected to be a hexadecimal number, which will be
69 decoded before being passed on as the control value.
70
71 =back
72
73 =item B<EVP_KDF_CTRL_SET_SSKDF_INFO>
74
75 This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
76
77 An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo.
78
79 EVP_KDF_ctrl_str() takes two type strings for this control:
80
81 =over 4
82
83 =item "info"
84
85 The value string is used as is.
86
87 =item "hexinfo"
88
89 The value string is expected to be a hexadecimal number, which will be
90 decoded before being passed on as the control value.
91
92 =back
93
94 =back
95
96 =head1 NOTES
97
98 A context for SSKDF can be obtained by calling:
99
100 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
101
102 The output length of an SSKDF is specified via the C<keylen>
103 parameter to the L<EVP_KDF_derive(3)> function.
104
105 =head1 EXAMPLE
106
107 This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
108 and fixedinfo value "label":
109
110   EVP_KDF_CTX *kctx;
111   unsigned char out[10];
112
113   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
114
115   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
116       error("EVP_KDF_CTRL_SET_MD");
117   }
118   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
119       error("EVP_KDF_CTRL_SET_KEY");
120   }
121   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
122       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
123   }
124   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
125       error("EVP_KDF_derive");
126   }
127
128   EVP_KDF_CTX_free(kctx);
129
130 =head1 EXAMPLE
131
132 This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
133 fixedinfo value "label" and salt "salt":
134
135   EVP_KDF_CTX *kctx;
136   unsigned char out[10];
137
138   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
139
140   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) {
141       error("EVP_KDF_CTRL_SET_MAC");
142   }
143   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
144       error("EVP_KDF_CTRL_SET_MD");
145   }
146   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
147       error("EVP_KDF_CTRL_SET_KEY");
148   }
149   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
150       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
151   }
152   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
153       error("EVP_KDF_CTRL_SET_SALT");
154   }
155   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
156       error("EVP_KDF_derive");
157   }
158
159   EVP_KDF_CTX_free(kctx);
160
161 =head1 EXAMPLE
162
163 This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
164 fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
165
166   EVP_KDF_CTX *kctx;
167   unsigned char out[10];
168
169   kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
170
171   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) {
172       error("EVP_KDF_CTRL_SET_MAC");
173   }
174   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
175       error("EVP_KDF_CTRL_SET_MD");
176   }
177   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
178       error("EVP_KDF_CTRL_SET_KEY");
179   }
180   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
181       error("EVP_KDF_CTRL_SET_SSKDF_INFO");
182   }
183   /* If not specified the salt will be set to a default value */
184   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
185       error("EVP_KDF_CTRL_SET_SALT");
186   }
187   /* If not specified the default size will be the size of the derived key */
188   if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) {
189       error("EVP_KDF_CTRL_SET_MAC_SIZE");
190   }
191   if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
192       error("EVP_KDF_derive");
193   }
194
195   EVP_KDF_CTX_free(kctx);
196
197
198 =head1 CONFORMING TO
199
200 NIST SP800-56Cr1.
201
202 =head1 SEE ALSO
203
204 L<EVP_KDF_CTX>,
205 L<EVP_KDF_CTX_new_id(3)>,
206 L<EVP_KDF_CTX_free(3)>,
207 L<EVP_KDF_ctrl(3)>,
208 L<EVP_KDF_size(3)>,
209 L<EVP_KDF_derive(3)>,
210 L<EVP_KDF_CTX(3)/CONTROLS>
211
212 =head1 HISTORY
213
214 This functionality was added to OpenSSL 3.0.0.
215
216 =head1 COPYRIGHT
217
218 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
219 (c) 2019, Oracle and/or its affiliates.  All rights reserved.
220
221 Licensed under the Apache License 2.0 (the "License").  You may not use
222 this file except in compliance with the License.  You can obtain a copy
223 in the file LICENSE in the source distribution or at
224 L<https://www.openssl.org/source/license.html>.
225
226 =cut