Debian Codegraph @

upstream/debian-trixie/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.5.6 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 \&
89 \& /* Key Exchange parameters */
90 \& int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
91 \& const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx,
92 \& void *provctx);
93 \& int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]);
94 \& const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx,
95 \& void *provctx);
96 .Ve
97 .SH DESCRIPTION
98 .IX Header "DESCRIPTION"
99 This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7)
100 for further information.
101 .PP
102 The key exchange (OSSL_OP_KEYEXCH) operation enables providers to implement key
103 exchange algorithms and make them available to applications via
104 \&\fBEVP_PKEY_derive\fR\|(3) and
105 other related functions).
106 .PP
107 All "functions" mentioned here are passed as function pointers between
108 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
109 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
110 \&\fBprovider_query_operation()\fR function
111 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
112 .PP
113 All these "functions" have a corresponding function type definition
114 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
115 function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named
116 \&\fBOSSL_FUNC_{name}\fR.
117 For example, the "function" \fBOSSL_FUNC_keyexch_newctx()\fR has these:
118 .PP
119 .Vb 3
120 \& typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
121 \& static ossl_inline OSSL_FUNC_keyexch_newctx_fn
122 \& OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);
123 .Ve
124 .PP
125 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as
126 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
127 .PP
128 .Vb 3
129 \& OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX
130 \& OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX
131 \& OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX
132 \&
133 \& OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT
134 \& OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER
135 \& OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE
136 \&
137 \& OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
138 \& OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
139 \& OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
140 \& OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS
141 .Ve
142 .PP
143 A key exchange algorithm implementation may not implement all of these functions.
144 In order to be a consistent set of functions a provider must implement
145 OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive.
146 All other functions are optional.
147 .PP
148 A key exchange algorithm must also implement some mechanism for generating,
149 loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
150 See \fBprovider\-keymgmt\fR\|(7) for further details.
151 .SS "Context Management Functions"
152 .IX Subsection "Context Management Functions"
153 \&\fBOSSL_FUNC_keyexch_newctx()\fR should create and return a pointer to a provider side
154 structure for holding context information during a key exchange operation.
155 A pointer to this context will be passed back in a number of the other key
156 exchange operation function calls.
157 The parameter \fIprovctx\fR is the provider context generated during provider
158 initialisation (see \fBprovider\fR\|(7)).
159 .PP
160 \&\fBOSSL_FUNC_keyexch_freectx()\fR is passed a pointer to the provider side key exchange
161 context in the \fIctx\fR parameter.
162 This function should free any resources associated with that context.
163 .PP
164 \&\fBOSSL_FUNC_keyexch_dupctx()\fR should duplicate the provider side key exchange context in
165 the \fIctx\fR parameter and return the duplicate copy.
166 .SS "Shared Secret Derivation Functions"
167 .IX Subsection "Shared Secret Derivation Functions"
168 \&\fBOSSL_FUNC_keyexch_init()\fR initialises a key exchange operation given a provider side key
169 exchange context in the \fIctx\fR parameter, and a pointer to a provider key object
170 in the \fIprovkey\fR parameter.
171 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
172 using \fBOSSL_FUNC_keyexch_set_params()\fR.
173 The key object should have been previously
174 generated, loaded or imported into the provider using the key management
175 (OSSL_OP_KEYMGMT) operation (see \fBprovider\-keymgmt\fR\|(7)>.
176 .PP
177 \&\fBOSSL_FUNC_keyexch_set_peer()\fR is called to supply the peer's public key (in the
178 \&\fIprovkey\fR parameter) to be used when deriving the shared secret.
179 It is also passed a previously initialised key exchange context in the \fIctx\fR
180 parameter.
181 The key object should have been previously generated, loaded or imported into
182 the provider using the key management (OSSL_OP_KEYMGMT) operation (see
183 \&\fBprovider\-keymgmt\fR\|(7)>.
184 .PP
185 \&\fBOSSL_FUNC_keyexch_derive()\fR performs the actual key exchange itself by deriving a shared
186 secret.
187 A previously initialised key exchange context is passed in the \fIctx\fR
188 parameter.
189 The derived secret should be written to the location \fIsecret\fR which should not
190 exceed \fIoutlen\fR bytes.
191 The length of the shared secret should be written to \fI*secretlen\fR.
192 If \fIsecret\fR is NULL then the maximum length of the shared secret should be
193 written to \fI*secretlen\fR.
194 .SS "Key Exchange Parameters Functions"
195 .IX Subsection "Key Exchange Parameters Functions"
196 \&\fBOSSL_FUNC_keyexch_set_ctx_params()\fR sets key exchange parameters associated with the
197 given provider side key exchange context \fIctx\fR to \fIparams\fR,
198 see "Common Key Exchange parameters".
199 Any parameter settings are additional to any that were previously set.
200 Passing NULL for \fIparams\fR should return true.
201 .PP
202 \&\fBOSSL_FUNC_keyexch_get_ctx_params()\fR gets key exchange parameters associated with the
203 given provider side key exchange context \fIctx\fR into \fIparams\fR,
204 see "Common Key Exchange parameters".
205 Passing NULL for \fIparams\fR should return true.
206 .PP
207 \&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR yields a constant \fBOSSL_PARAM\fR\|(3) array that
208 describes the settable parameters, i.e. parameters that can be used with
209 \&\fBOP_signature_set_ctx_params()\fR.
210 If \fBOSSL_FUNC_keyexch_settable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_set_ctx_params()\fR must
211 also be present, and vice versa.
212 Similarly, \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR yields a constant \fBOSSL_PARAM\fR\|(3)
213 array that describes the gettable parameters, i.e. parameters that can be
214 handled by \fBOP_signature_get_ctx_params()\fR.
215 If \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR is present, \fBOSSL_FUNC_keyexch_get_ctx_params()\fR must
216 also be present, and vice versa.
217 .PP
218 Notice that not all settable parameters are also gettable, and vice versa.
219 .SS "Common Key Exchange parameters"
220 .IX Subsection "Common Key Exchange parameters"
221 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
222 the \fBOSSL_FUNC_keyexch_set_ctx_params()\fR and \fBOSSL_FUNC_keyexch_get_ctx_params()\fR functions.
223 .PP
224 Common parameters currently recognised by built-in key exchange algorithms are
225 as follows.
226 .IP """kdf-type"" (\fBOSSL_EXCHANGE_PARAM_KDF_TYPE\fR) <UTF8 string>" 4
227 .IX Item """kdf-type"" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>"
228 Sets or gets the Key Derivation Function type to apply within the associated key
229 exchange ctx.
230 .IP """kdf-digest"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST\fR) <UTF8 string>" 4
231 .IX Item """kdf-digest"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>"
232 Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
233 associated with the given key exchange ctx.
234 .IP """kdf-digest-props"" (\fBOSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS\fR) <UTF8 string>" 4
235 .IX Item """kdf-digest-props"" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>"
236 Sets properties to be used upon look up of the implementation for the selected
237 Digest algorithm for the Key Derivation Function associated with the given key
238 exchange ctx.
239 .IP """kdf-outlen"" (\fBOSSL_EXCHANGE_PARAM_KDF_OUTLEN\fR) <unsigned integer>" 4
240 .IX Item """kdf-outlen"" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>"
241 Sets or gets the desired size for the output of the chosen Key Derivation Function
242 associated with the given key exchange ctx.
243 The length of the "kdf-outlen" parameter should not exceed that of a \fBsize_t\fR.
244 .IP """kdf-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) <octet string>" 4
245 .IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>"
246 Sets the User Key Material to be used as part of the selected Key Derivation
247 Function associated with the given key exchange ctx.
248 .IP """kdf-ukm"" (\fBOSSL_EXCHANGE_PARAM_KDF_UKM\fR) <octet string ptr>" 4
249 .IX Item """kdf-ukm"" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string ptr>"
250 Gets a pointer to the User Key Material to be used as part of the selected
251 Key Derivation Function associated with the given key exchange ctx. Providers
252 usually do not need to support this gettable parameter as its sole purpose
253 is to support functionality of the deprecated \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR
254 and \fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR functions.
255 .PP
256 The OpenSSL FIPS provider also supports the following parameters:
257 .IP """fips-indicator"" (\fBOSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR\fR) <integer>" 4
258 .IX Item """fips-indicator"" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) <integer>"
259 A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
260 This may be used after calling \fBOSSL_FUNC_keyexch_derive()\fR. It may
261 return 0 if either the "digest-check" or the "key-check" are set to 0.
262 .IP """key-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK\fR) <integer>" 4
263 .IX Item """key-check"" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) <integer>"
264 If required this parameter should be set using \fBOSSL_FUNC_keyexch_init()\fR.
265 The default value of 1 causes an error during the init if the key is not FIPS
266 approved (e.g. The key has a security strength of less than 112 bits). Setting
267 this to 0 will ignore the error and set the approved "fips-indicator" to 0.
268 This option breaks FIPS compliance if it causes the approved "fips-indicator"
269 to return 0.
270 .IP """digest-check"" (\fBOSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK\fR) <integer>" 4
271 .IX Item """digest-check"" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) <integer>"
272 If required this parameter should be set before any optional digest is set.
273 The default value of 1 causes an error when the digest is set if the digest is
274 not FIPS approved. Setting this to 0 will ignore the error and set the
275 approved "fips-indicator" to 0.
276 This option breaks FIPS compliance if it causes the approved "fips-indicator"
277 to return 0.
278 .SH "RETURN VALUES"
279 .IX Header "RETURN VALUES"
280 \&\fBOSSL_FUNC_keyexch_newctx()\fR and \fBOSSL_FUNC_keyexch_dupctx()\fR should return the newly created
281 provider side key exchange context, or NULL on failure.
282 .PP
283 \&\fBOSSL_FUNC_keyexch_init()\fR, \fBOSSL_FUNC_keyexch_set_peer()\fR, \fBOSSL_FUNC_keyexch_derive()\fR,
284 \&\fBOSSL_FUNC_keyexch_set_params()\fR, and \fBOSSL_FUNC_keyexch_get_params()\fR should return 1 for success
285 or 0 on error.
286 .PP
287 \&\fBOSSL_FUNC_keyexch_settable_ctx_params()\fR and \fBOSSL_FUNC_keyexch_gettable_ctx_params()\fR should
288 always return a constant \fBOSSL_PARAM\fR\|(3) array.
289 .SH "SEE ALSO"
290 .IX Header "SEE ALSO"
291 \&\fBprovider\fR\|(7)
292 .SH HISTORY
293 .IX Header "HISTORY"
294 The provider KEYEXCH interface was introduced in OpenSSL 3.0.
295 .PP
296 The Key Exchange Parameters "fips-indicator", "key-check" and "digest-check"
297 were added in OpenSSL 3.4.
298 .SH COPYRIGHT
299 .IX Header "COPYRIGHT"
300 Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved.
301 .PP
302 Licensed under the Apache License 2.0 (the "License"). You may not use
303 this file except in compliance with the License. You can obtain a copy
304 in the file LICENSE in the source distribution or at
305 <https://www.openssl.org/source/license.html>.