1PROVIDER-KEYEXCH(7ossl) OpenSSL PROVIDER-KEYEXCH(7ossl)
2
6 provider-keyexch - The keyexch library <-> provider functions
7
9 #include <openssl/core_dispatch.h>
10 #include <openssl/core_names.h>
11 /*
13 * None of these are actual functions, but are displayed like this for
14 * the function signatures for functions that are offered as function
15 * pointers in OSSL_DISPATCH arrays.
16 */
17 /* Context management */
19 void *OSSL_FUNC_keyexch_newctx(void *provctx);
20 void OSSL_FUNC_keyexch_freectx(void *ctx);
21 void *OSSL_FUNC_keyexch_dupctx(void *ctx);
22 /* Shared secret derivation */
24 int OSSL_FUNC_keyexch_init(void *ctx, void *provkey,
25 const OSSL_PARAM params[]);
26 int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey);
27 int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
28 size_t outlen);
29 /* Key Exchange parameters */
31 int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
32 const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx,
33 void *provctx);
34 int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]);
35 const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx,
36 void *provctx);
37
39 This documentation is primarily aimed at provider authors. See
40 provider(7) for further information.
41 The key exchange (OSSL_OP_KEYEXCH) operation enables providers to
43 implement key exchange algorithms and make them available to
44 applications via EVP_PKEY_derive(3) and other related functions).
45 All "functions" mentioned here are passed as function pointers between
47 libcrypto and the provider in OSSL_DISPATCH(3) arrays via
48 OSSL_ALGORITHM(3) arrays that are returned by the provider's
49 provider_query_operation() function (see "Provider Functions" in
50 provider-base(7)).
51 All these "functions" have a corresponding function type definition
53 named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
54 function pointer from an OSSL_DISPATCH(3) element named
55 OSSL_FUNC_{name}. For example, the "function"
56 OSSL_FUNC_keyexch_newctx() has these:
57 typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
59 static ossl_inline OSSL_FUNC_keyexch_newctx_fn
60 OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);
61 OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as
63 macros in openssl-core_dispatch.h(7), as follows:
64 OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX
66 OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX
67 OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX
68 OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT
70 OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER
71 OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE
72 OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
74 OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
75 OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
76 OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS
77 A key exchange algorithm implementation may not implement all of these
79 functions. In order to be a consistent set of functions a provider
80 must implement OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx,
81 OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive. All other
82 functions are optional.
83 A key exchange algorithm must also implement some mechanism for
85 generating, loading or importing keys via the key management
86 (OSSL_OP_KEYMGMT) operation. See provider-keymgmt(7) for further
87 details.
88 Context Management Functions
90 OSSL_FUNC_keyexch_newctx() should create and return a pointer to a
91 provider side structure for holding context information during a key
92 exchange operation. A pointer to this context will be passed back in a
93 number of the other key exchange operation function calls. The
94 parameter provctx is the provider context generated during provider
95 initialisation (see provider(7)).
96 OSSL_FUNC_keyexch_freectx() is passed a pointer to the provider side
98 key exchange context in the ctx parameter. This function should free
99 any resources associated with that context.
100 OSSL_FUNC_keyexch_dupctx() should duplicate the provider side key
102 exchange context in the ctx parameter and return the duplicate copy.
103 Shared Secret Derivation Functions
105 OSSL_FUNC_keyexch_init() initialises a key exchange operation given a
106 provider side key exchange context in the ctx parameter, and a pointer
107 to a provider key object in the provkey parameter. The params, if not
108 NULL, should be set on the context in a manner similar to using
109 OSSL_FUNC_keyexch_set_params(). The key object should have been
110 previously generated, loaded or imported into the provider using the
111 key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
112 OSSL_FUNC_keyexch_set_peer() is called to supply the peer's public key
114 (in the provkey parameter) to be used when deriving the shared secret.
115 It is also passed a previously initialised key exchange context in the
116 ctx parameter. The key object should have been previously generated,
117 loaded or imported into the provider using the key management
118 (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
119 OSSL_FUNC_keyexch_derive() performs the actual key exchange itself by
121 deriving a shared secret. A previously initialised key exchange
122 context is passed in the ctx parameter. The derived secret should be
123 written to the location secret which should not exceed outlen bytes.
124 The length of the shared secret should be written to *secretlen. If
125 secret is NULL then the maximum length of the shared secret should be
126 written to *secretlen.
127 Key Exchange Parameters Functions
129 OSSL_FUNC_keyexch_set_ctx_params() sets key exchange parameters
130 associated with the given provider side key exchange context ctx to
131 params, see "Common Key Exchange parameters". Any parameter settings
132 are additional to any that were previously set. Passing NULL for
133 params should return true.
134 OSSL_FUNC_keyexch_get_ctx_params() gets key exchange parameters
136 associated with the given provider side key exchange context ctx into
137 params, see "Common Key Exchange parameters". Passing NULL for params
138 should return true.
139 OSSL_FUNC_keyexch_settable_ctx_params() yields a constant OSSL_PARAM(3)
141 array that describes the settable parameters, i.e. parameters that can
142 be used with OP_signature_set_ctx_params(). If
143 OSSL_FUNC_keyexch_settable_ctx_params() is present,
144 OSSL_FUNC_keyexch_set_ctx_params() must also be present, and vice
145 versa. Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a
146 constant OSSL_PARAM(3) array that describes the gettable parameters,
147 i.e. parameters that can be handled by OP_signature_get_ctx_params().
148 If OSSL_FUNC_keyexch_gettable_ctx_params() is present,
149 OSSL_FUNC_keyexch_get_ctx_params() must also be present, and vice
150 versa.
151 Notice that not all settable parameters are also gettable, and vice
153 versa.
154 Common Key Exchange parameters
156 See OSSL_PARAM(3) for further details on the parameters structure used
157 by the OSSL_FUNC_keyexch_set_ctx_params() and
158 OSSL_FUNC_keyexch_get_ctx_params() functions.
159 Common parameters currently recognised by built-in key exchange
161 algorithms are as follows.
162 "kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>
164 Sets or gets the Key Derivation Function type to apply within the
165 associated key exchange ctx.
166 "kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>
168 Sets or gets the Digest algorithm to be used as part of the Key
169 Derivation Function associated with the given key exchange ctx.
170 "kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>
172 Sets properties to be used upon look up of the implementation for
173 the selected Digest algorithm for the Key Derivation Function
174 associated with the given key exchange ctx.
175 "kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>
177 Sets or gets the desired size for the output of the chosen Key
178 Derivation Function associated with the given key exchange ctx.
179 The length of the "kdf-outlen" parameter should not exceed that of
180 a size_t.
181 "kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>
183 Sets the User Key Material to be used as part of the selected Key
184 Derivation Function associated with the given key exchange ctx.
185 "kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string ptr>
187 Gets a pointer to the User Key Material to be used as part of the
188 selected Key Derivation Function associated with the given key
189 exchange ctx. Providers usually do not need to support this
190 gettable parameter as its sole purpose is to support functionality
191 of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm() and
192 EVP_PKEY_CTX_get0_dh_kdf_ukm() functions.
193
195 OSSL_FUNC_keyexch_newctx() and OSSL_FUNC_keyexch_dupctx() should return
196 the newly created provider side key exchange context, or NULL on
197 failure.
198 OSSL_FUNC_keyexch_init(), OSSL_FUNC_keyexch_set_peer(),
200 OSSL_FUNC_keyexch_derive(), OSSL_FUNC_keyexch_set_params(), and
201 OSSL_FUNC_keyexch_get_params() should return 1 for success or 0 on
202 error.
203 OSSL_FUNC_keyexch_settable_ctx_params() and
205 OSSL_FUNC_keyexch_gettable_ctx_params() should always return a constant
206 OSSL_PARAM(3) array.
207
209 provider(7)
210
212 The provider KEYEXCH interface was introduced in OpenSSL 3.0.
213
215 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
216 Licensed under the Apache License 2.0 (the "License"). You may not use
218 this file except in compliance with the License. You can obtain a copy
219 in the file LICENSE in the source distribution or at
220 <https://www.openssl.org/source/license.html>.
2213.1.1 2023-08-31 PROVIDER-KEYEXCH(7ossl)