Debian Codegraph @

upstream/debian-unstable/man7/provider-keyexch.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PROVIDER-KEYEXCH 7SSL"
58 .TH PROVIDER-KEYEXCH 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 provider\-keyexch \- The keyexch library <\-> provider functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& #include <openssl/core_dispatch.h>
69 \& #include <openssl/core_names.h>
70 \&
71 \& /*
72 \& * None of these are actual functions, but are displayed like this for
73 \& * the function signatures for functions that are offered as function
74 \& * pointers in OSSL_DISPATCH arrays.
75 \& */
76 \&
77 \& /* Context management */
78 \& void *OSSL_FUNC_keyexch_newctx(void *provctx);
79 \& void OSSL_FUNC_keyexch_freectx(void *ctx);
80 \& void *OSSL_FUNC_keyexch_dupctx(void *ctx);
81 \&
82 \& /* Shared secret derivation */
83 \& int OSSL_FUNC_keyexch_init(void *ctx, void *provkey,
84 \& const OSSL_PARAM params[]);
85 \& int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey);
86 \& int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
87 \& size_t outlen);
88 \& int OSSL_FUNC_keyexch_derive_skey(void *ctx, const char *key_type, void *provctx,
89 \& OSSL_FUNC_skeymgmt_import_fn *import,
90 \& size_t keylen, const OSSL_PARAM params[]);
91 \&
92 \& /* Key Exchange parameters */
93 \& int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
94 \& const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx,
95 \& void *provctx);
96 \& int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]);
97 \& const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx,
98 \& void *provctx);
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7)
103 for further information.
104 .PP
105 The key exchange (OSSL_OP_KEYEXCH) operation enables providers to implement key
106 exchange algorithms and make them available to applications via
107 \&\fBEVP_PKEY_derive\fR\|(3) and
108 other related functions).
109 .PP
110 All "functions" mentioned here are passed as function pointers between
111 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
112 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
113 \&\fBprovider_query_operation()\fR function
114 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
115 .PP
116 All these "functions" have a corresponding function type definition
117 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
118 function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named
119 \&\fBOSSL_FUNC_{name}\fR.
120 For example, the "function" \fBOSSL_FUNC_keyexch_newctx()\fR has these:
121 .PP
122 .Vb 3
123 \& typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
124 \& static ossl_inline OSSL_FUNC_keyexch_newctx_fn
125 \& OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);
126 .Ve
127 .PP
128 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as
129 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
130 .PP
131 .Vb 3
132 \& OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX
133 \& OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX
134 \& OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX
135 \&
136 \& OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT
137 \& OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER
138 \& OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE
139 \& OSSL_FUNC_keyexch_derive_skey OSSL_FUNC_KEYEXCH_DERIVE_SKEY
140 \&
141 \& OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
142 \& OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
143 \& OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
144 \& OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS
145 .Ve
146 .PP
147 A key exchange algorithm implementation may not implement all of these functions.
148 In order to be a consistent set of functions a provider must implement
149 OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and at least one
150 of OSSL_FUNC_keyexch_derive and OSSL_FUNC_keyexch_derive_skey.
151 All other functions are optional.
152 .PP
153 A key exchange algorithm must also implement some mechanism for generating,
154 loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
155 See \fBprovider\-keymgmt\fR\|(7) for further details.
156 .SS "Context Management Functions"
157 .IX Subsection "Context Management Functions"
158 \&\fBOSSL_FUNC_keyexch_newctx()\fR should create and return a pointer to a provider side
159 structure for holding context information during a key exchange operation.
160 A pointer to this context will be passed back in a number of the other key
161 exchange operation function calls.
162 The parameter \fIprovctx\fR is the provider context generated during provider
163 initialisation (see \fBprovider\fR\|(7)).
164 .PP
165 \&\fBOSSL_FUNC_keyexch_freectx()\fR is passed a pointer to the provider side key exchange
166 context in the \fIctx\fR parameter.
167 This function should free any resources associated with that context.
168 .PP
169 \&\fBOSSL_FUNC_keyexch_dupctx()\fR should duplicate the provider side key exchange context in
170 the \fIctx\fR parameter and return the duplicate copy.
171 .SS "Shared Secret Derivation Functions"
172 .IX Subsection "Shared Secret Derivation Functions"
173 \&\fBOSSL_FUNC_keyexch_init()\fR initialises a key exchange operation given a provider side key
174 exchange context in the \fIctx\fR parameter, and a pointer to a provider key object
175 in the \fIprovkey\fR parameter.
176 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
177 using \fBOSSL_FUNC_keyexch_set_params()\fR.
178 The key object should have been previously
179 generated, loaded or imported into the provider using the key management
180 (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)>.
181 .PP
182 \&\fBOSSL_FUNC_keyexch_set_peer()\fR is called to supply the peer's public key (in the
183 \&\fIprovkey\fR parameter) to be used when deriving the shared secret.
184 It is also passed a previously initialised key exchange context in the \fIctx\fR
185 parameter.
186 The key object should have been previously generated, loaded or imported into
187 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
188 \&\fBprovider\-keymgmt\fR\|(7)>.
189 .PP
190 \&\fBOSSL_FUNC_keyexch_derive()\fR performs the actual key exchange itself by deriving a shared
191 secret.
192 A previously initialised key exchange context is passed in the \fIctx\fR
193 parameter.
194 The derived secret should be written to the location \fIsecret\fR which should not
195 exceed \fIoutlen\fR bytes.
196 The length of the shared secret should be written to \fI*secretlen\fR.
197 If \fIsecret\fR is NULL then the maximum length of the shared secret should be
198 written to \fI*secretlen\fR.
199 .PP
200 \&\fBOSSL_FUNC_keyexch_derive_skey()\fR is similar to \fBOSSL_FUNC_keyexch_derive()\fR but
201 uses an opaque object for storing the derived key. It accepts \fIkey_type\fR
202 parameter to give a hint to the provider what type of the key (e.g. generic or
203 AES) would be generated and \fIimport\fR function from the \fBEVP_SKEYMGMT\fR object
204 to be associated with the key. The \fBEVP_SKEYMGMT\fR object comes from the same
205 provider as the KDF itself.
206 .SS "Key Exchange Parameters Functions"
207 .IX Subsection "Key Exchange Parameters Functions"
208 \&\fBOSSL_FUNC_keyexch_set_ctx_params()\fR sets key exchange parameters associated with the
209 given provider side key exchange context \fIctx\fR to \fIparams\fR,
210 see "Common Key Exchange parameters".
211 Any parameter settings are additional to any that were previously set.
212 Passing NULL for \fIparams\fR should return true.
213 .PP
214 \&\fBOSSL_FUNC_keyexch_get_ctx_params()\fR gets key exchange parameters associated with the
215 given provider side key exchange context \fIctx\fR into \fIparams\fR,
216 see "Common Key Exchange parameters".
217 Passing NULL for \fIparams\fR should return true.
218 .PP
219 \&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR yields a constant \fBOSSL_PARAM\fR\|(3) array that
220 describes the settable parameters, i.e. parameters that can be used with
221 \&\fBOP_signature_set_ctx_params()\fR.
222 If \fBOSSL_FUNC_keyexch_settable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_set_ctx_params()\fR must
223 also be present, and vice versa.
224 Similarly, \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR yields a constant \fBOSSL_PARAM\fR\|(3)
225 array that describes the gettable parameters, i.e. parameters that can be
226 handled by \fBOP_signature_get_ctx_params()\fR.
227 If \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_get_ctx_params()\fR must
228 also be present, and vice versa.
229 .PP
230 Notice that not all settable parameters are also gettable, and vice versa.
231 .SS "Common Key Exchange parameters"
232 .IX Subsection "Common Key Exchange parameters"
233 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
234 the \fBOSSL_FUNC_keyexch_set_ctx_params()\fR and \fBOSSL_FUNC_keyexch_get_ctx_params()\fR functions.
235 .PP
236 Common parameters currently recognised by built-in key exchange algorithms are
237 as follows.
238 .IP """kdf-type"" (\fBOSSL_EXCHANGE_PARAM_KDF_TYPE\fR) <UTF8 string>" 4
239 .IX Item """kdf-type"" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>"
240 Sets or gets the Key Derivation Function type to apply within the associated key
241 exchange ctx.
242 .IP """kdf-digest"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST\fR) <UTF8 string>" 4
243 .IX Item """kdf-digest"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>"
244 Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
245 associated with the given key exchange ctx.
246 .IP """kdf-digest-props"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\fR) <UTF8 string>" 4
247 .IX Item """kdf-digest-props"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>"
248 Sets properties to be used upon look up of the implementation for the selected
249 Digest algorithm for the Key Derivation Function associated with the given key
250 exchange ctx.
251 .IP """kdf-outlen"" (\fBOSSL_EXCHANGE_PARAM_KDF_OUTLEN\fR) <unsigned integer>" 4
252 .IX Item """kdf-outlen"" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>"
253 Sets or gets the desired size for the output of the chosen Key Derivation Function
254 associated with the given key exchange ctx.
255 The length of the "kdf-outlen" parameter should not exceed that of a \fBsize_t\fR.
256 .IP """kdf-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) <octet string>" 4
257 .IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>"
258 Sets the User Key Material to be used as part of the selected Key Derivation
259 Function associated with the given key exchange ctx.
260 .IP """kdf-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) <octet string ptr>" 4
261 .IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string ptr>"
262 Gets a pointer to the User Key Material to be used as part of the selected
263 Key Derivation Function associated with the given key exchange ctx. Providers
264 usually do not need to support this gettable parameter as its sole purpose
265 is to support functionality of the deprecated \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR
266 and \fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR functions.
267 .PP
268 The OpenSSL FIPS provider also supports the following parameters:
269 .IP """fips-indicator"" (\fBOSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4
270 .IX Item """fips-indicator"" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) <integer>"
271 A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
272 This may be used after calling \fBOSSL_FUNC_keyexch_derive()\fR. It may
273 return 0 if either the "digest-check" or the "key-check" are set to 0.
274 .IP """key-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK\fR) <integer>" 4
275 .IX Item """key-check"" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) <integer>"
276 If required this parameter should be set using \fBOSSL_FUNC_keyexch_init()\fR.
277 The default value of 1 causes an error during the init if the key is not FIPS
278 approved (e.g. The key has a security strength of less than 112 bits). Setting
279 this to 0 will ignore the error and set the approved "fips-indicator" to 0.
280 This option breaks FIPS compliance if it causes the approved "fips-indicator"
281 to return 0.
282 .IP """digest-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK\fR) <integer>" 4
283 .IX Item """digest-check"" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) <integer>"
284 If required this parameter should be set before any optional digest is set.
285 The default value of 1 causes an error when the digest is set if the digest is
286 not FIPS approved. Setting this to 0 will ignore the error and set the
287 approved "fips-indicator" to 0.
288 This option breaks FIPS compliance if it causes the approved "fips-indicator"
289 to return 0.
290 .SH "RETURN VALUES"
291 .IX Header "RETURN VALUES"
292 \&\fBOSSL_FUNC_keyexch_newctx()\fR and \fBOSSL_FUNC_keyexch_dupctx()\fR should return the newly created
293 provider side key exchange context, or NULL on failure.
294 .PP
295 \&\fBOSSL_FUNC_keyexch_init()\fR, \fBOSSL_FUNC_keyexch_set_peer()\fR, \fBOSSL_FUNC_keyexch_derive()\fR,
296 \&\fBOSSL_FUNC_keyexch_derive_skey()\fR,
297 \&\fBOSSL_FUNC_keyexch_set_params()\fR, and \fBOSSL_FUNC_keyexch_get_params()\fR should return 1 for success
298 or 0 on error.
299 .PP
300 \&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR and \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR should
301 always return a constant \fBOSSL_PARAM\fR\|(3) array.
302 .SH "SEE ALSO"
303 .IX Header "SEE ALSO"
304 \&\fBprovider\fR\|(7)
305 .SH HISTORY
306 .IX Header "HISTORY"
307 The provider KEYEXCH interface was introduced in OpenSSL 3.0.
308 .PP
309 The Key Exchange Parameters "fips-indicator", "key-check" and "digest-check"
310 were added in OpenSSL 3.4.
311 .PP
312 The \fBOSSL_FUNC_keyexch_derive_skey()\fR function was added in OpenSSL 3.6.
313 .SH COPYRIGHT
314 .IX Header "COPYRIGHT"
315 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
316 .PP
317 Licensed under the Apache License 2.0 (the "License"). You may not use
318 this file except in compliance with the License. You can obtain a copy
319 in the file LICENSE in the source distribution or at
320 <https://www.openssl.org/source/license.html>.