5 provider-kdf - The KDF library E<lt>-E<gt> provider functions
9 =for openssl multiple includes
11 #include <openssl/core_dispatch.h>
12 #include <openssl/core_names.h>
15 * None of these are actual functions, but are displayed like this for
16 * the function signatures for functions that are offered as function
17 * pointers in OSSL_DISPATCH arrays.
20 /* Context management */
21 void *OSSL_FUNC_kdf_newctx(void *provctx);
22 void OSSL_FUNC_kdf_freectx(void *kctx);
23 void *OSSL_FUNC_kdf_dupctx(void *src);
25 /* Encryption/decryption */
26 int OSSL_FUNC_kdf_reset(void *kctx);
27 int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen);
29 /* KDF parameter descriptors */
30 const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx);
31 const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *provctx);
32 const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *provctx);
35 int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]);
36 int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]);
37 int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]);
41 This documentation is primarily aimed at provider authors. See L<provider(7)>
42 for further information.
44 The KDF operation enables providers to implement KDF algorithms and make
45 them available to applications via the API functions L<EVP_KDF_CTX_reset(3)>,
46 and L<EVP_KDF_derive(3)>.
48 All "functions" mentioned here are passed as function pointers between
49 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
50 B<OSSL_ALGORITHM> arrays that are returned by the provider's
51 provider_query_operation() function
52 (see L<provider-base(7)/Provider Functions>).
54 All these "functions" have a corresponding function type definition
55 named B<OSSL_{name}_fn>, and a helper function to retrieve the
56 function pointer from an B<OSSL_DISPATCH> element named
58 For example, the "function" OSSL_FUNC_kdf_newctx() has these:
60 typedef void *(OSSL_OSSL_FUNC_kdf_newctx_fn)(void *provctx);
61 static ossl_inline OSSL_OSSL_FUNC_kdf_newctx_fn
62 OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf);
64 B<OSSL_DISPATCH> array entries are identified by numbers that are provided as
65 macros in L<openssl-core_dispatch.h(7)>, as follows:
67 OSSL_FUNC_kdf_newctx OSSL_FUNC_KDF_NEWCTX
68 OSSL_FUNC_kdf_freectx OSSL_FUNC_KDF_FREECTX
69 OSSL_FUNC_kdf_dupctx OSSL_FUNC_KDF_DUPCTX
71 OSSL_FUNC_kdf_reset OSSL_FUNC_KDF_RESET
72 OSSL_FUNC_kdf_derive OSSL_FUNC_KDF_DERIVE
74 OSSL_FUNC_kdf_get_params OSSL_FUNC_KDF_GET_PARAMS
75 OSSL_FUNC_kdf_get_ctx_params OSSL_FUNC_KDF_GET_CTX_PARAMS
76 OSSL_FUNC_kdf_set_ctx_params OSSL_FUNC_KDF_SET_CTX_PARAMS
78 OSSL_FUNC_kdf_gettable_params OSSL_FUNC_KDF_GETTABLE_PARAMS
79 OSSL_FUNC_kdf_gettable_ctx_params OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS
80 OSSL_FUNC_kdf_settable_ctx_params OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS
82 A KDF algorithm implementation may not implement all of these functions.
83 In order to be a consistent set of functions, at least the following functions
84 must be implemented: OSSL_FUNC_kdf_newctx(), OSSL_FUNC_kdf_freectx(),
85 OSSL_FUNC_kdf_set_ctx_params(), OSSL_FUNC_kdf_derive().
86 All other functions are optional.
88 =head2 Context Management Functions
90 OSSL_FUNC_kdf_newctx() should create and return a pointer to a provider side
91 structure for holding context information during a KDF operation.
92 A pointer to this context will be passed back in a number of the other KDF
93 operation function calls.
94 The parameter I<provctx> is the provider context generated during provider
95 initialisation (see L<provider(7)>).
97 OSSL_FUNC_kdf_freectx() is passed a pointer to the provider side KDF context in
98 the I<kctx> parameter.
99 If it receives NULL as I<kctx> value, it should not do anything other than
101 This function should free any resources associated with that context.
103 OSSL_FUNC_kdf_dupctx() should duplicate the provider side KDF context in the
104 I<kctx> parameter and return the duplicate copy.
106 =head2 Encryption/Decryption Functions
108 OSSL_FUNC_kdf_reset() initialises a KDF operation given a provider
109 side KDF context in the I<kctx> parameter.
111 OSSL_FUNC_kdf_derive() performs the KDF operation.
112 The I<kctx> parameter contains a pointer to the provider side context.
113 The resulting key of the desired I<keylen> should be written to I<key>.
114 If the algorithm does not support the requested I<keylen> the function must
117 =head2 KDF Parameters
119 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
122 OSSL_FUNC_kdf_get_params() gets details of parameter values associated with the
123 provider algorithm and stores them in I<params>.
125 OSSL_FUNC_kdf_set_ctx_params() sets KDF parameters associated with the given
126 provider side KDF context I<kctx> to I<params>.
127 Any parameter settings are additional to any that were previously set.
129 OSSL_FUNC_kdf_get_ctx_params() retrieves gettable parameter values associated
130 with the given provider side KDF context I<kctx> and stores them in I<params>.
132 OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params(), and
133 OSSL_FUNC_kdf_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
134 as descriptors of the parameters that OSSL_FUNC_kdf_get_params(),
135 OSSL_FUNC_kdf_get_ctx_params(), and OSSL_FUNC_kdf_set_ctx_params() can handle,
138 Parameters currently recognised by built-in KDFs are as follows. Not all
139 parameters are relevant to, or are understood by all KDFs:
143 =item "size" (B<OSSL_KDF_PARAM_SIZE>) <unsigned integer>
145 Gets the output size from the associated KDF ctx.
146 If the algorithm produces a variable amount of output, SIZE_MAX should be
148 If the input parameters required to calculate the fixed output size have not yet
149 been supplied, 0 should be returned indicating an error.
151 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
153 Sets the key in the associated KDF ctx.
155 =item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string>
157 Sets the secret in the associated KDF ctx.
159 =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string>
161 Sets the password in the associated KDF ctx.
163 =item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string>
165 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
167 =item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
169 Sets the name of the underlying cipher, digest or MAC to be used.
170 It must name a suitable algorithm for the KDF that's being used.
172 =item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <octet string>
174 Sets the length of the MAC in the associated KDF ctx.
176 =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
178 Sets the properties to be queried when trying to fetch the underlying algorithm.
179 This must be given together with the algorithm naming parameter to be
182 =item "iter" (B<OSSL_KDF_PARAM_ITER>) <unsigned integer>
184 Sets the number of iterations in the associated KDF ctx.
186 =item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string>
188 Sets the mode in the associated KDF ctx.
190 =item "pkcs5" (B<OSSL_KDF_PARAM_PKCS5>) <integer>
192 Enables or diables the SP800-132 compliance checks.
193 A mode of 0 enables the compliance checks.
195 The checks performed are:
199 =item - the iteration count is at least 1000.
201 =item - the salt length is at least 128 bits.
203 =item - the derived key length is at least 112 bits.
207 =item "ukm" (B<OSSL_KDF_PARAM_UKM>) <octet string>
209 Sets an optional random string that is provided by the sender called
210 "partyAInfo". In CMS this is the user keying material.
213 =item "cekalg" (B<OSSL_KDF_PARAM_CEK_ALG>) <UTF8 string>
215 Sets the CEK wrapping algorithm name in the associated KDF ctx.
217 =item "n" (B<OSSL_KDF_PARAM_SCRYPT_N>) <unsigned integer>
219 Sets the scrypt work factor parameter N in the associated KDF ctx.
221 =item "r" (B<OSSL_KDF_PARAM_SCRYPT_R>) <unsigned integer>
223 Sets the scrypt work factor parameter r in the associated KDF ctx.
225 =item "p" (B<OSSL_KDF_PARAM_SCRYPT_P>) <unsigned integer>
227 Sets the scrypt work factor parameter p in the associated KDF ctx.
229 =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
231 Sets the scrypt work factor parameter maxmem in the associated KDF ctx.
233 =item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string>
235 Sets the optional shared info in the associated KDF ctx.
237 =item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string>
239 Sets the IV in the associated KDF ctx.
241 =item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string>
243 Sets the xcghash in the associated KDF ctx.
245 =item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string>
247 Sets the session ID in the associated KDF ctx.
249 =item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <integer>
251 Sets the SSH KDF type parameter in the associated KDF ctx.
252 There are six supported types:
256 =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
258 The Initial IV from client to server.
259 A single char of value 65 (ASCII char 'A').
261 =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
263 The Initial IV from server to client
264 A single char of value 66 (ASCII char 'B').
266 =item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
268 The Encryption Key from client to server
269 A single char of value 67 (ASCII char 'C').
271 =item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
273 The Encryption Key from server to client
274 A single char of value 68 (ASCII char 'D').
276 =item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
278 The Integrity Key from client to server
279 A single char of value 69 (ASCII char 'E').
281 =item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
283 The Integrity Key from client to server
284 A single char of value 70 (ASCII char 'F').
288 =item "constant" (B<OSSL_KDF_PARAM_CONSTANT>) <octet string>
290 Sets the constant value in the associated KDF ctx.
292 =item "id" (B<OSSL_KDF_PARAM_PKCS12_ID>) <integer>
294 Sets the intended usage of the output bits in the associated KDF ctx.
295 It is defined as per RFC 7292 section B.3.
301 OSSL_FUNC_kdf_newctx() and OSSL_FUNC_kdf_dupctx() should return the newly created
302 provider side KDF context, or NULL on failure.
304 OSSL_FUNC_kdf_derive(), OSSL_FUNC_kdf_get_params(),
305 OSSL_FUNC_kdf_get_ctx_params() and OSSL_FUNC_kdf_set_ctx_params() should return 1 for
306 success or 0 on error.
308 OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params() and
309 OSSL_FUNC_kdf_settable_ctx_params() should return a constant B<OSSL_PARAM>
310 array, or NULL if none is offered.
318 The provider KDF interface was introduced in OpenSSL 3.0.
322 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
324 Licensed under the Apache License 2.0 (the "License"). You may not use
325 this file except in compliance with the License. You can obtain a copy
326 in the file LICENSE in the source distribution or at
327 L<https://www.openssl.org/source/license.html>.