]>
Commit | Line | Data |
---|---|---|
59972370 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-keyexch - The keyexch library E<lt>-E<gt> provider functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
bb82531f | 9 | =for openssl multiple includes |
59972370 | 10 | |
23c48d94 | 11 | #include <openssl/core_dispatch.h> |
59972370 MC |
12 | #include <openssl/core_names.h> |
13 | ||
14 | /* | |
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. | |
18 | */ | |
19 | ||
20 | /* Context management */ | |
363b1e5d DMSP |
21 | void *OSSL_FUNC_keyexch_newctx(void *provctx); |
22 | void OSSL_FUNC_keyexch_freectx(void *ctx); | |
23 | void *OSSL_FUNC_keyexch_dupctx(void *ctx); | |
59972370 MC |
24 | |
25 | /* Shared secret derivation */ | |
f187d4f9 P |
26 | int OSSL_FUNC_keyexch_init(void *ctx, void *provkey, |
27 | const OSSL_PARAM params[]); | |
363b1e5d DMSP |
28 | int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey); |
29 | int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen, | |
30 | size_t outlen); | |
59972370 MC |
31 | |
32 | /* Key Exchange parameters */ | |
363b1e5d | 33 | int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]); |
fb67126e TM |
34 | const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx, |
35 | void *provctx); | |
363b1e5d | 36 | int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]); |
fb67126e TM |
37 | const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx, |
38 | void *provctx); | |
59972370 MC |
39 | |
40 | =head1 DESCRIPTION | |
41 | ||
42 | This documentation is primarily aimed at provider authors. See L<provider(7)> | |
43 | for further information. | |
44 | ||
45 | The key exchange (OSSL_OP_KEYEXCH) operation enables providers to implement key | |
fadb57e5 RS |
46 | exchange algorithms and make them available to applications via |
47 | L<EVP_PKEY_derive(3)> and | |
59972370 MC |
48 | other related functions). |
49 | ||
50 | All "functions" mentioned here are passed as function pointers between | |
51 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
52 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
53 | provider_query_operation() function | |
54 | (see L<provider-base(7)/Provider Functions>). | |
55 | ||
56 | All these "functions" have a corresponding function type definition | |
57 | named B<OSSL_{name}_fn>, and a helper function to retrieve the | |
58 | function pointer from an B<OSSL_DISPATCH> element named | |
363b1e5d DMSP |
59 | B<OSSL_FUNC_{name}>. |
60 | For example, the "function" OSSL_FUNC_keyexch_newctx() has these: | |
59972370 | 61 | |
363b1e5d DMSP |
62 | typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx); |
63 | static ossl_inline OSSL_FUNC_keyexch_newctx_fn | |
64 | OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf); | |
59972370 MC |
65 | |
66 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
23c48d94 | 67 | macros in L<openssl-core_dispatch.h(7)>, as follows: |
59972370 | 68 | |
363b1e5d DMSP |
69 | OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX |
70 | OSSL_FUNC_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX | |
71 | OSSL_FUNC_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX | |
59972370 | 72 | |
363b1e5d DMSP |
73 | OSSL_FUNC_keyexch_init OSSL_FUNC_KEYEXCH_INIT |
74 | OSSL_FUNC_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER | |
75 | OSSL_FUNC_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE | |
59972370 | 76 | |
363b1e5d DMSP |
77 | OSSL_FUNC_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS |
78 | OSSL_FUNC_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS | |
79 | OSSL_FUNC_keyexch_get_ctx_params OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS | |
80 | OSSL_FUNC_keyexch_gettable_ctx_params OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS | |
59972370 MC |
81 | |
82 | A key exchange algorithm implementation may not implement all of these functions. | |
83 | In order to be a consistent set of functions a provider must implement | |
363b1e5d | 84 | OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive. |
59972370 MC |
85 | All other functions are optional. |
86 | ||
87 | A key exchange algorithm must also implement some mechanism for generating, | |
88 | loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. | |
89 | See L<provider-keymgmt(7)> for further details. | |
90 | ||
91 | =head2 Context Management Functions | |
92 | ||
363b1e5d | 93 | OSSL_FUNC_keyexch_newctx() should create and return a pointer to a provider side |
59972370 MC |
94 | structure for holding context information during a key exchange operation. |
95 | A pointer to this context will be passed back in a number of the other key | |
96 | exchange operation function calls. | |
79c44b4e | 97 | The parameter I<provctx> is the provider context generated during provider |
d7cea0b8 | 98 | initialisation (see L<provider(7)>). |
59972370 | 99 | |
363b1e5d | 100 | OSSL_FUNC_keyexch_freectx() is passed a pointer to the provider side key exchange |
dfabee82 | 101 | context in the I<ctx> parameter. |
59972370 MC |
102 | This function should free any resources associated with that context. |
103 | ||
363b1e5d | 104 | OSSL_FUNC_keyexch_dupctx() should duplicate the provider side key exchange context in |
dfabee82 | 105 | the I<ctx> parameter and return the duplicate copy. |
59972370 MC |
106 | |
107 | =head2 Shared Secret Derivation Functions | |
108 | ||
363b1e5d | 109 | OSSL_FUNC_keyexch_init() initialises a key exchange operation given a provider side key |
79c44b4e | 110 | exchange context in the I<ctx> parameter, and a pointer to a provider key object |
f187d4f9 P |
111 | in the I<provkey> parameter. |
112 | The I<params>, if not NULL, should be set on the context in a manner similar to | |
113 | using OSSL_FUNC_keyexch_set_params(). | |
114 | The key object should have been previously | |
59972370 MC |
115 | generated, loaded or imported into the provider using the key management |
116 | (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. | |
117 | ||
363b1e5d | 118 | OSSL_FUNC_keyexch_set_peer() is called to supply the peer's public key (in the |
dfabee82 RL |
119 | I<provkey> parameter) to be used when deriving the shared secret. |
120 | It is also passed a previously initialised key exchange context in the I<ctx> | |
59972370 MC |
121 | parameter. |
122 | The key object should have been previously generated, loaded or imported into | |
123 | the provider using the key management (OSSL_OP_KEYMGMT) operation (see | |
124 | provider-keymgmt(7)>. | |
125 | ||
363b1e5d | 126 | OSSL_FUNC_keyexch_derive() performs the actual key exchange itself by deriving a shared |
59972370 | 127 | secret. |
dfabee82 | 128 | A previously initialised key exchange context is passed in the I<ctx> |
59972370 | 129 | parameter. |
dfabee82 RL |
130 | The derived secret should be written to the location I<secret> which should not |
131 | exceed I<outlen> bytes. | |
132 | The length of the shared secret should be written to I<*secretlen>. | |
133 | If I<secret> is NULL then the maximum length of the shared secret should be | |
134 | written to I<*secretlen>. | |
59972370 | 135 | |
ce82b892 | 136 | =head2 Key Exchange Parameters Functions |
59972370 | 137 | |
363b1e5d | 138 | OSSL_FUNC_keyexch_set_ctx_params() sets key exchange parameters associated with the |
ce82b892 | 139 | given provider side key exchange context I<ctx> to I<params>, |
b8086652 | 140 | see L</Common Key Exchange parameters>. |
59972370 | 141 | Any parameter settings are additional to any that were previously set. |
f59612fe | 142 | Passing NULL for I<params> should return true. |
59972370 | 143 | |
363b1e5d | 144 | OSSL_FUNC_keyexch_get_ctx_params() gets key exchange parameters associated with the |
ce82b892 | 145 | given provider side key exchange context I<ctx> into I<params>, |
b8086652 | 146 | see L</Common Key Exchange parameters>. |
f59612fe | 147 | Passing NULL for I<params> should return true. |
ce82b892 | 148 | |
363b1e5d | 149 | OSSL_FUNC_keyexch_settable_ctx_params() yields a constant B<OSSL_PARAM> array that |
ce82b892 NT |
150 | describes the settable parameters, i.e. parameters that can be used with |
151 | OP_signature_set_ctx_params(). | |
363b1e5d | 152 | If OSSL_FUNC_keyexch_settable_ctx_params() is present, OSSL_FUNC_keyexch_set_ctx_params() must |
ce82b892 | 153 | also be present, and vice versa. |
363b1e5d | 154 | Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a constant B<OSSL_PARAM> |
ce82b892 NT |
155 | array that describes the gettable parameters, i.e. parameters that can be |
156 | handled by OP_signature_get_ctx_params(). | |
363b1e5d | 157 | If OSSL_FUNC_keyexch_gettable_ctx_params() is present, OSSL_FUNC_keyexch_get_ctx_params() must |
ce82b892 NT |
158 | also be present, and vice versa. |
159 | See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. | |
160 | ||
161 | Notice that not all settable parameters are also gettable, and vice versa. | |
162 | ||
b8086652 | 163 | =head2 Common Key Exchange parameters |
ce82b892 NT |
164 | |
165 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by | |
363b1e5d | 166 | the OSSL_FUNC_keyexch_set_ctx_params() and OSSL_FUNC_keyexch_get_ctx_params() functions. |
ce82b892 | 167 | |
b8086652 SL |
168 | Common parameters currently recognised by built-in key exchange algorithms are |
169 | as follows. | |
59972370 MC |
170 | |
171 | =over 4 | |
172 | ||
0c452a51 | 173 | =item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer> |
59972370 MC |
174 | |
175 | Sets the padding mode for the associated key exchange ctx. | |
176 | Setting a value of 1 will turn padding on. | |
b8086652 | 177 | Setting a value of 0 will turn padding off. |
59972370 MC |
178 | If padding is off then the derived shared secret may be smaller than the largest |
179 | possible secret size. | |
180 | If padding is on then the derived shared secret will have its first bytes filled | |
181 | with 0s where necessary to make the shared secret the same size as the largest | |
182 | possible secret size. | |
183 | ||
ce82b892 | 184 | =back |
9c45222d | 185 | |
59972370 MC |
186 | =head1 RETURN VALUES |
187 | ||
363b1e5d | 188 | OSSL_FUNC_keyexch_newctx() and OSSL_FUNC_keyexch_dupctx() should return the newly created |
59972370 MC |
189 | provider side key exchange context, or NULL on failure. |
190 | ||
363b1e5d DMSP |
191 | OSSL_FUNC_keyexch_init(), OSSL_FUNC_keyexch_set_peer(), OSSL_FUNC_keyexch_derive(), |
192 | OSSL_FUNC_keyexch_set_params(), and OSSL_FUNC_keyexch_get_params() should return 1 for success | |
ce82b892 NT |
193 | or 0 on error. |
194 | ||
363b1e5d | 195 | OSSL_FUNC_keyexch_settable_ctx_params() and OSSL_FUNC_keyexch_gettable_ctx_params() should |
ce82b892 | 196 | always return a constant B<OSSL_PARAM> array. |
59972370 MC |
197 | |
198 | =head1 SEE ALSO | |
199 | ||
200 | L<provider(7)> | |
201 | ||
202 | =head1 HISTORY | |
203 | ||
204 | The provider KEYEXCH interface was introduced in OpenSSL 3.0. | |
205 | ||
206 | =head1 COPYRIGHT | |
207 | ||
8020d79b | 208 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
59972370 MC |
209 | |
210 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
211 | this file except in compliance with the License. You can obtain a copy | |
212 | in the file LICENSE in the source distribution or at | |
213 | L<https://www.openssl.org/source/license.html>. | |
214 | ||
215 | =cut |