1EVP_KDF_CTX(3) OpenSSL EVP_KDF_CTX(3)
2
6 EVP_KDF_CTX, EVP_KDF_CTX_new_id, EVP_KDF_CTX_free, EVP_KDF_reset,
7 EVP_KDF_ctrl, EVP_KDF_vctrl, EVP_KDF_ctrl_str, EVP_KDF_size,
8 EVP_KDF_derive - EVP KDF routines
9
11 #include <openssl/kdf.h>
12 typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
14 EVP_KDF_CTX *EVP_KDF_CTX_new_id(int id);
16 void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
17 void EVP_KDF_reset(EVP_KDF_CTX *ctx);
18 int EVP_KDF_ctrl(EVP_KDF_CTX *ctx, int cmd, ...);
19 int EVP_KDF_vctrl(EVP_KDF_CTX *ctx, int cmd, va_list args);
20 int EVP_KDF_ctrl_str(EVP_KDF_CTX *ctx, const char *type, const char *value);
21 size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
22 int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
23
25 The EVP KDF routines are a high level interface to Key Derivation
26 Function algorithms and should be used instead of algorithm-specific
27 functions.
28 After creating a "EVP_KDF_CTX" for the required algorithm using
30 EVP_KDF_CTX_new_id(), inputs to the algorithm are supplied using calls
31 to EVP_KDF_ctrl(), EVP_KDF_vctrl() or EVP_KDF_ctrl_str() before calling
32 EVP_KDF_derive() to derive the key.
33 Types
35 EVP_KDF_CTX is a context type that holds the algorithm inputs.
36 Context manipulation functions
38 EVP_KDF_CTX_new_id() creates a KDF context for the algorithm identified
39 by the specified NID.
40 EVP_KDF_CTX_free() frees up the context "ctx". If "ctx" is "NULL",
42 nothing is done.
43 Computing functions
45 EVP_KDF_reset() resets the context to the default state as if the
46 context had just been created.
47 EVP_KDF_ctrl() is used to provide inputs to the KDF algorithm prior to
49 EVP_KDF_derive() being called. The inputs that may be provided will
50 vary depending on the KDF algorithm or its implementation. This
51 functions takes variable arguments, the exact expected arguments depend
52 on "cmd". See "CONTROLS" below for a description of standard controls.
53 EVP_KDF_vctrl() is the variant of EVP_KDF_ctrl() that takes a "va_list"
55 argument instead of variadic arguments.
56 EVP_KDF_ctrl_str() allows an application to send an algorithm specific
58 control operation to a context "ctx" in string form. This is intended
59 to be used for options specified on the command line or in text files.
60 EVP_KDF_size() returns the output size if the algorithm produces a
62 fixed amount of output and "SIZE_MAX" otherwise. If an error occurs
63 then 0 is returned. For some algorithms an error may result if input
64 parameters necessary to calculate a fixed output size have not yet been
65 supplied.
66 EVP_KDF_derive() derives "keylen" bytes of key material and places it
68 in the "key" buffer. If the algorithm produces a fixed amount of
69 output then an error will occur unless the "keylen" parameter is equal
70 to that output size, as returned by EVP_KDF_size().
71
73 The standard controls are:
74 EVP_KDF_CTRL_SET_PASS
76 This control expects two arguments: "unsigned char *pass", "size_t
77 passlen"
78 Some KDF implementations require a password. For those KDF
80 implementations that support it, this control sets the password.
81 EVP_KDF_ctrl_str() takes two type strings for this control:
83 "pass"
85 The value string is used as is.
86 "hexpass"
88 The value string is expected to be a hexadecimal number, which
89 will be decoded before being passed on as the control value.
90 EVP_KDF_CTRL_SET_SALT
92 This control expects two arguments: "unsigned char *salt", "size_t
93 saltlen"
94 Some KDF implementations can take a salt. For those KDF
96 implementations that support it, this control sets the salt.
97 The default value, if any, is implementation dependent.
99 EVP_KDF_ctrl_str() takes two type strings for this control:
101 "salt"
103 The value string is used as is.
104 "hexsalt"
106 The value string is expected to be a hexadecimal number, which
107 will be decoded before being passed on as the control value.
108 EVP_KDF_CTRL_SET_ITER
110 This control expects one argument: "int iter"
111 Some KDF implementations require an iteration count. For those KDF
113 implementations that support it, this control sets the iteration
114 count.
115 The default value, if any, is implementation dependent.
117 EVP_KDF_ctrl_str() type string: "iter"
119 The value string is expected to be a decimal number.
121 EVP_KDF_CTRL_SET_MD
123 This control expects one argument: "EVP_MD *md"
124 For MAC implementations that use a message digest as an underlying
126 computation algorithm, this control sets what the digest algorithm
127 should be.
128 EVP_KDF_CTRL_SET_CIPHER
130 This control expects one argument: "EVP_CIPHER *cipher"
131 For MAC implementations that use a cipher as an underlying
133 computation algorithm, this control sets what the cipher algorithm
134 should be.
135 EVP_KDF_ctrl_str() type string: "md"
137 The value string is expected to be the name of a digest.
139 EVP_KDF_CTRL_SET_KEY
141 This control expects two arguments: "unsigned char *key", "size_t
142 keylen"
143 Some KDF implementations require a key. For those KDF
145 implementations that support it, this control sets the key.
146 EVP_KDF_ctrl_str() takes two type strings for this control:
148 "key"
150 The value string is used as is.
151 "hexkey"
153 The value string is expected to be a hexadecimal number, which
154 will be decoded before being passed on as the control value.
155 EVP_KDF_CTRL_SET_MAXMEM_BYTES
157 This control expects one argument: "uint64_t maxmem_bytes"
158 Memory-hard password-based KDF algorithms, such as scrypt, use an
160 amount of memory that depends on the load factors provided as
161 input. For those KDF implementations that support it, this control
162 sets an upper limit on the amount of memory that may be consumed
163 while performing a key derivation. If this memory usage limit is
164 exceeded because the load factors are chosen too high, the key
165 derivation will fail.
166 The default value is implementation dependent.
168 EVP_KDF_ctrl_str() type string: "maxmem_bytes"
170 The value string is expected to be a decimal number.
172
174 EVP_KDF_CTX_new_id() returns either the newly allocated "EVP_KDF_CTX"
175 structure or "NULL" if an error occurred.
176 EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
178 EVP_KDF_size() returns the output size. "SIZE_MAX" is returned to
180 indicate that the algorithm produces a variable amount of output; 0 to
181 indicate failure.
182 The remaining functions return 1 for success and 0 or a negative value
184 for failure. In particular, a return value of -2 indicates the
185 operation is not supported by the KDF algorithm.
186
188 EVP_KDF_SCRYPT(7)
189
191 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
192 Licensed under the Apache License 2.0 (the "License"). You may not use
194 this file except in compliance with the License. You can obtain a copy
195 in the file LICENSE in the source distribution or at
196 <https://www.openssl.org/source/license.html>.
1971.1.1i 2021-01-26 EVP_KDF_CTX(3)