]>
Commit | Line | Data |
---|---|---|
65ce7e65 P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
251e610c | 5 | EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref, |
765d04c9 | 6 | EVP_KDF_CTX, EVP_KDF_new_ctx, EVP_KDF_free_ctx, EVP_KDF_dup_ctx, |
251e610c | 7 | EVP_KDF_reset, EVP_KDF_derive, |
765d04c9 | 8 | EVP_KDF_size, EVP_KDF_provider, EVP_KDF_get_ctx_kdf, EVP_KDF_is_a, |
506cb0f6 | 9 | EVP_KDF_number, EVP_KDF_names_do_all, |
765d04c9 | 10 | EVP_KDF_get_ctx_params, EVP_KDF_set_ctx_params, EVP_KDF_do_all_provided, |
41f7ecf3 | 11 | EVP_KDF_get_params, EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params, |
65ce7e65 P |
12 | EVP_KDF_gettable_params - EVP KDF routines |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/kdf.h> | |
17 | ||
18 | typedef struct evp_kdf_st EVP_KDF; | |
19 | typedef struct evp_kdf_ctx_st EVP_KDF_CTX; | |
20 | ||
765d04c9 P |
21 | EVP_KDF_CTX *EVP_KDF_new_ctx(const EVP_KDF *kdf); |
22 | const EVP_KDF *EVP_KDF_get_ctx_kdf(EVP_KDF_CTX *ctx); | |
23 | void EVP_KDF_free_ctx(EVP_KDF_CTX *ctx); | |
24 | EVP_KDF_CTX *EVP_KDF_dup_ctx(const EVP_KDF_CTX *src); | |
65ce7e65 P |
25 | void EVP_KDF_reset(EVP_KDF_CTX *ctx); |
26 | size_t EVP_KDF_size(EVP_KDF_CTX *ctx); | |
27 | int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen); | |
65ce7e65 P |
28 | int EVP_KDF_up_ref(EVP_KDF *kdf); |
29 | void EVP_KDF_free(EVP_KDF *kdf); | |
30 | EVP_KDF *EVP_KDF_fetch(OPENSSL_CTX *libctx, const char *algorithm, | |
31 | const char *properties); | |
506cb0f6 | 32 | int EVP_KDF_number(const EVP_KDF *kdf); |
251e610c RL |
33 | int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name); |
34 | const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf); | |
35 | void EVP_KDF_do_all_provided(OPENSSL_CTX *libctx, | |
36 | void (*fn)(EVP_KDF *kdf, void *arg), | |
37 | void *arg); | |
f651c727 RL |
38 | void EVP_KDF_names_do_all(const EVP_KDF *kdf, |
39 | void (*fn)(const char *name, void *data), | |
40 | void *data); | |
65ce7e65 | 41 | int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]); |
765d04c9 P |
42 | int EVP_KDF_get_ctx_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]); |
43 | int EVP_KDF_set_ctx_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]); | |
65ce7e65 | 44 | const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf); |
41f7ecf3 P |
45 | const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf); |
46 | const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf); | |
65ce7e65 P |
47 | const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf); |
48 | ||
49 | =head1 DESCRIPTION | |
50 | ||
8c1cbc72 | 51 | The EVP KDF routines are a high-level interface to Key Derivation Function |
65ce7e65 P |
52 | algorithms and should be used instead of algorithm-specific functions. |
53 | ||
54 | After creating a B<EVP_KDF_CTX> for the required algorithm using | |
765d04c9 P |
55 | EVP_KDF_new_ctx(), inputs to the algorithm are supplied |
56 | using calls to EVP_KDF_set_ctx_params() before | |
65ce7e65 P |
57 | calling EVP_KDF_derive() to derive the key. |
58 | ||
59 | =head2 Types | |
60 | ||
61 | B<EVP_KDF> is a type that holds the implementation of a KDF. | |
62 | ||
63 | B<EVP_KDF_CTX> is a context type that holds the algorithm inputs. | |
64 | ||
65 | =head2 Algorithm implementation fetching | |
66 | ||
67 | EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given | |
68 | a library context I<libctx> and a set of I<properties>. | |
69 | See L<provider(7)/Fetching algorithms> for further information. | |
70 | ||
b8086652 SL |
71 | See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of |
72 | algorithms supported by the default provider. | |
73 | ||
65ce7e65 P |
74 | The returned value must eventually be freed with |
75 | L<EVP_KDF_free(3)>. | |
76 | ||
77 | EVP_KDF_up_ref() increments the reference count of an already fetched | |
78 | KDF. | |
79 | ||
80 | EVP_KDF_free() frees a fetched algorithm. | |
81 | NULL is a valid parameter, for which this function is a no-op. | |
82 | ||
83 | =head2 Context manipulation functions | |
84 | ||
765d04c9 | 85 | EVP_KDF_new_ctx() creates a new context for the KDF implementation I<kdf>. |
65ce7e65 | 86 | |
765d04c9 | 87 | EVP_KDF_free_ctx() frees up the context I<ctx>. If I<ctx> is NULL, nothing |
65ce7e65 P |
88 | is done. |
89 | ||
765d04c9 | 90 | EVP_KDF_get_ctx_kdf() returns the B<EVP_KDF> associated with the context |
65ce7e65 P |
91 | I<ctx>. |
92 | ||
93 | =head2 Computing functions | |
94 | ||
95 | EVP_KDF_reset() resets the context to the default state as if the context | |
96 | had just been created. | |
97 | ||
ee2161e8 | 98 | EVP_KDF_derive() derives I<keylen> bytes of key material and places it in the |
65ce7e65 | 99 | I<key> buffer. If the algorithm produces a fixed amount of output then an |
ee2161e8 | 100 | error will occur unless the I<keylen> parameter is equal to that output size, |
65ce7e65 P |
101 | as returned by EVP_KDF_size(). |
102 | ||
103 | EVP_KDF_get_params() retrieves details about the implementation | |
104 | I<kdf>. | |
105 | The set of parameters given with I<params> determine exactly what | |
106 | parameters should be retrieved. | |
107 | Note that a parameter that is unknown in the underlying context is | |
108 | simply ignored. | |
109 | ||
765d04c9 | 110 | EVP_KDF_get_ctx_params() retrieves chosen parameters, given the |
65ce7e65 P |
111 | context I<ctx> and its underlying context. |
112 | The set of parameters given with I<params> determine exactly what | |
113 | parameters should be retrieved. | |
114 | Note that a parameter that is unknown in the underlying context is | |
115 | simply ignored. | |
116 | ||
765d04c9 | 117 | EVP_KDF_set_ctx_params() passes chosen parameters to the underlying |
65ce7e65 P |
118 | context, given a context I<ctx>. |
119 | The set of parameters given with I<params> determine exactly what | |
120 | parameters are passed down. | |
121 | Note that a parameter that is unknown in the underlying context is | |
122 | simply ignored. | |
123 | Also, what happens when a needed parameter isn't passed down is | |
124 | defined by the implementation. | |
125 | ||
41f7ecf3 P |
126 | EVP_KDF_gettable_params(), EVP_KDF_gettable_ctx_params() and |
127 | EVP_KDF_settable_ctx_params() get a constant B<OSSL_PARAM> array that | |
79c44b4e | 128 | describes the retrievable and settable parameters, i.e. parameters that |
765d04c9 P |
129 | can be used with EVP_KDF_get_params(), EVP_KDF_get_ctx_params() |
130 | and EVP_KDF_set_ctx_params(), respectively. | |
65ce7e65 P |
131 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. |
132 | ||
133 | =head2 Information functions | |
134 | ||
135 | EVP_KDF_size() returns the output size if the algorithm produces a fixed amount | |
136 | of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned. | |
137 | For some algorithms an error may result if input parameters necessary to | |
138 | calculate a fixed output size have not yet been supplied. | |
139 | ||
251e610c RL |
140 | EVP_KDF_is_a() returns 1 if I<kdf> is an implementation of an |
141 | algorithm that's identifiable with I<name>, otherwise 0. | |
142 | ||
65ce7e65 P |
143 | EVP_KDF_provider() returns the provider that holds the implementation |
144 | of the given I<kdf>. | |
145 | ||
251e610c | 146 | EVP_KDF_do_all_provided() traverses all KDF implemented by all activated |
65ce7e65 P |
147 | providers in the given library context I<libctx>, and for each of the |
148 | implementations, calls the given function I<fn> with the implementation method | |
149 | and the given I<arg> as argument. | |
150 | ||
506cb0f6 RL |
151 | EVP_KDF_number() returns the internal dynamic number assigned to |
152 | I<kdf>. | |
153 | ||
f651c727 RL |
154 | EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls |
155 | I<fn> with each name and I<data>. | |
156 | ||
b1cabee8 | 157 | =head1 PARAMETERS |
65ce7e65 P |
158 | |
159 | The standard parameter names are: | |
160 | ||
161 | =over 4 | |
162 | ||
0c452a51 | 163 | =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> |
65ce7e65 P |
164 | |
165 | Some KDF implementations require a password. | |
166 | For those KDF implementations that support it, this parameter sets the password. | |
167 | ||
0c452a51 | 168 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> |
65ce7e65 P |
169 | |
170 | Some KDF implementations can take a salt. | |
171 | For those KDF implementations that support it, this parameter sets the salt. | |
172 | ||
173 | The default value, if any, is implementation dependent. | |
174 | ||
0c452a51 | 175 | =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer> |
65ce7e65 P |
176 | |
177 | Some KDF implementations require an iteration count. | |
178 | For those KDF implementations that support it, this parameter sets the | |
179 | iteration count. | |
180 | ||
181 | The default value, if any, is implementation dependent. | |
182 | ||
0c452a51 | 183 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> |
65ce7e65 | 184 | |
0c452a51 | 185 | =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> |
65ce7e65 | 186 | |
0c452a51 | 187 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
65ce7e65 | 188 | |
33f54da3 SS |
189 | =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string> |
190 | ||
191 | For KDF implementations that use an underlying computation MAC, digest or | |
192 | cipher, these parameters set what the algorithm should be. | |
c69561de | 193 | |
9bd9c440 | 194 | The value is always the name of the intended algorithm, |
c69561de P |
195 | or the properties. |
196 | ||
197 | Note that not all algorithms may support all possible underlying | |
198 | implementations. | |
65ce7e65 | 199 | |
0c452a51 | 200 | =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> |
65ce7e65 P |
201 | |
202 | Some KDF implementations require a key. | |
203 | For those KDF implementations that support it, this octet string parameter | |
204 | sets the key. | |
205 | ||
0c452a51 | 206 | =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer> |
65ce7e65 P |
207 | |
208 | Used by implementations that use a MAC with a variable output size (KMAC). | |
209 | For those KDF implementations that support it, this parameter | |
210 | sets the MAC output size. | |
211 | ||
212 | The default value, if any, is implementation dependent. | |
f4651268 | 213 | The length must never exceed what can be given with a B<size_t>. |
65ce7e65 | 214 | |
0c452a51 | 215 | =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer> |
65ce7e65 P |
216 | |
217 | Memory-hard password-based KDF algorithms, such as scrypt, use an amount of | |
218 | memory that depends on the load factors provided as input. | |
560ac83b | 219 | For those KDF implementations that support it, this B<uint64_t> parameter sets |
65ce7e65 P |
220 | an upper limit on the amount of memory that may be consumed while performing |
221 | a key derivation. | |
222 | If this memory usage limit is exceeded because the load factors are chosen | |
223 | too high, the key derivation will fail. | |
224 | ||
225 | The default value is implementation dependent. | |
f4651268 | 226 | The memory size must never exceed what can be given with a B<size_t>. |
65ce7e65 P |
227 | |
228 | =back | |
229 | ||
230 | =head1 RETURN VALUES | |
231 | ||
ee2161e8 | 232 | EVP_KDF_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or |
65ce7e65 P |
233 | NULL if allocation failed. |
234 | ||
65ce7e65 P |
235 | EVP_KDF_provider() returns a pointer to the provider for the KDF, or |
236 | NULL on error. | |
237 | ||
ee2161e8 | 238 | EVP_KDF_up_ref() returns 1 on success, 0 on error. |
65ce7e65 | 239 | |
765d04c9 | 240 | EVP_KDF_new_ctx() returns either the newly allocated |
ee2161e8 | 241 | B<EVP_KDF_CTX> structure or NULL if an error occurred. |
65ce7e65 | 242 | |
765d04c9 | 243 | EVP_KDF_free_ctx() and EVP_KDF_reset() do not return a value. |
65ce7e65 | 244 | |
ee2161e8 | 245 | EVP_KDF_size() returns the output size. B<SIZE_MAX> is returned to indicate |
65ce7e65 P |
246 | that the algorithm produces a variable amount of output; 0 to indicate failure. |
247 | ||
248 | The remaining functions return 1 for success and 0 or a negative value for | |
249 | failure. In particular, a return value of -2 indicates the operation is not | |
250 | supported by the KDF algorithm. | |
251 | ||
252 | =head1 SEE ALSO | |
253 | ||
b8086652 | 254 | L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> |
65ce7e65 P |
255 | |
256 | =head1 HISTORY | |
257 | ||
258 | This functionality was added to OpenSSL 3.0. | |
259 | ||
260 | =head1 COPYRIGHT | |
261 | ||
00c405b3 | 262 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
65ce7e65 P |
263 | |
264 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
265 | this file except in compliance with the License. You can obtain a copy | |
266 | in the file LICENSE in the source distribution or at | |
267 | L<https://www.openssl.org/source/license.html>. | |
268 | ||
269 | =cut |