1=pod
2
3=head1 NAME
4
5EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation
6
7=head1 DESCRIPTION
8
9The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF).
10SSKDF derives a key using input such as a shared secret key (that was generated
11during the execution of a key establishment scheme) and fixedinfo.
12SSKDF is also informally referred to as 'Concat KDF'.
13
14=head2 Auxiliary function
15
16The 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
28Both the HMAC and KMAC implementations set the key using the 'salt' value.
29The hash and HMAC also require the digest to be set.
30
31=head2 Identity
32
33"SSKDF" is the name for this implementation; it
34can be used with the EVP_KDF_fetch() function.
35
36=head2 Supported parameters
37
38The supported parameters are:
39
40=over 4
41
42=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
43
44=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
45
46=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
47
48=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
49
50=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
51
52These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
53
54=item "key" (B<EVP_KDF_CTRL_SET_KEY>) <octet string>
55
56This parameter set the shared secret that is used for key derivation.
57
58=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string>
59
60This parameter sets an optional value for fixedinfo, also known as otherinfo.
61
62=back
63
64=head1 NOTES
65
66A context for SSKDF can be obtained by calling:
67
68 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
69 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
70
71The output length of an SSKDF is specified via the I<keylen>
72parameter to the L<EVP_KDF_derive(3)> function.
73
74=head1 EXAMPLES
75
76This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
77and 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);
85 kctx = EVP_KDF_CTX_new(kdf);
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();
95 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
96     error("EVP_KDF_derive");
97 }
98
99 EVP_KDF_CTX_free(kctx);
100
101This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
102fixedinfo 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);
110 kctx = EVP_KDF_CTX_new(kdf);
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();
124 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
125     error("EVP_KDF_derive");
126 }
127
128 EVP_KDF_CTX_free(kctx);
129
130This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
131fixedinfo 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);
139 kctx = EVP_KDF_CTX_new(kdf);
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();
154 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
155     error("EVP_KDF_derive");
156 }
157
158 EVP_KDF_CTX_free(kctx);
159
160=head1 CONFORMING TO
161
162NIST SP800-56Cr1.
163
164=head1 SEE ALSO
165
166L<EVP_KDF(3)>,
167L<EVP_KDF_CTX_new(3)>,
168L<EVP_KDF_CTX_free(3)>,
169L<EVP_KDF_CTX_set_params(3)>,
170L<EVP_KDF_CTX_get_kdf_size(3)>,
171L<EVP_KDF_derive(3)>,
172L<EVP_KDF(3)/PARAMETERS>
173
174=head1 HISTORY
175
176This functionality was added to OpenSSL 3.0.
177
178=head1 COPYRIGHT
179
180Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.  Copyright
181(c) 2019, Oracle and/or its affiliates.  All rights reserved.
182
183Licensed under the Apache License 2.0 (the "License").  You may not use
184this file except in compliance with the License.  You can obtain a copy
185in the file LICENSE in the source distribution or at
186L<https://www.openssl.org/source/license.html>.
187
188=cut
189