1PROVIDER-KEYEXCH(7ossl)             OpenSSL            PROVIDER-KEYEXCH(7ossl)


6       provider-keyexch - The keyexch library <-> provider functions


9        #include <openssl/core_dispatch.h>
10        #include <openssl/core_names.h>
12        /*
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         */
18        /* 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);
23        /* 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);
30        /* 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);


39       This documentation is primarily aimed at provider authors. See
40       provider(7) for further information.
42       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).
46       All "functions" mentioned here are passed as function pointers between
47       libcrypto and the provider in OSSL_DISPATCH arrays via OSSL_ALGORITHM
48       arrays that are returned by the provider's provider_query_operation()
49       function (see "Provider Functions" in provider-base(7)).
51       All these "functions" have a corresponding function type definition
52       named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
53       function pointer from an OSSL_DISPATCH element named OSSL_FUNC_{name}.
54       For example, the "function" OSSL_FUNC_keyexch_newctx() has these:
56        typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
57        static ossl_inline OSSL_FUNC_keyexch_newctx_fn
58            OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);
60       OSSL_DISPATCH arrays are indexed by numbers that are provided as macros
61       in openssl-core_dispatch.h(7), as follows:
63        OSSL_FUNC_keyexch_newctx                OSSL_FUNC_KEYEXCH_NEWCTX
64        OSSL_FUNC_keyexch_freectx               OSSL_FUNC_KEYEXCH_FREECTX
65        OSSL_FUNC_keyexch_dupctx                OSSL_FUNC_KEYEXCH_DUPCTX
67        OSSL_FUNC_keyexch_init                  OSSL_FUNC_KEYEXCH_INIT
68        OSSL_FUNC_keyexch_set_peer              OSSL_FUNC_KEYEXCH_SET_PEER
69        OSSL_FUNC_keyexch_derive                OSSL_FUNC_KEYEXCH_DERIVE
71        OSSL_FUNC_keyexch_set_ctx_params        OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
72        OSSL_FUNC_keyexch_settable_ctx_params   OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
73        OSSL_FUNC_keyexch_get_ctx_params        OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
74        OSSL_FUNC_keyexch_gettable_ctx_params   OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS
76       A key exchange algorithm implementation may not implement all of these
77       functions.  In order to be a consistent set of functions a provider
78       must implement OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx,
79       OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive.  All other
80       functions are optional.
82       A key exchange algorithm must also implement some mechanism for
83       generating, loading or importing keys via the key management
84       (OSSL_OP_KEYMGMT) operation.  See provider-keymgmt(7) for further
85       details.
87   Context Management Functions
88       OSSL_FUNC_keyexch_newctx() should create and return a pointer to a
89       provider side structure for holding context information during a key
90       exchange operation.  A pointer to this context will be passed back in a
91       number of the other key exchange operation function calls.  The
92       parameter provctx is the provider context generated during provider
93       initialisation (see provider(7)).
95       OSSL_FUNC_keyexch_freectx() is passed a pointer to the provider side
96       key exchange context in the ctx parameter.  This function should free
97       any resources associated with that context.
99       OSSL_FUNC_keyexch_dupctx() should duplicate the provider side key
100       exchange context in the ctx parameter and return the duplicate copy.
102   Shared Secret Derivation Functions
103       OSSL_FUNC_keyexch_init() initialises a key exchange operation given a
104       provider side key exchange context in the ctx parameter, and a pointer
105       to a provider key object in the provkey parameter.  The params, if not
106       NULL, should be set on the context in a manner similar to using
107       OSSL_FUNC_keyexch_set_params().  The key object should have been
108       previously generated, loaded or imported into the provider using the
109       key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
111       OSSL_FUNC_keyexch_set_peer() is called to supply the peer's public key
112       (in the provkey parameter) to be used when deriving the shared secret.
113       It is also passed a previously initialised key exchange context in the
114       ctx parameter.  The key object should have been previously generated,
115       loaded or imported into the provider using the key management
116       (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.
118       OSSL_FUNC_keyexch_derive() performs the actual key exchange itself by
119       deriving a shared secret.  A previously initialised key exchange
120       context is passed in the ctx parameter.  The derived secret should be
121       written to the location secret which should not exceed outlen bytes.
122       The length of the shared secret should be written to *secretlen.  If
123       secret is NULL then the maximum length of the shared secret should be
124       written to *secretlen.
126   Key Exchange Parameters Functions
127       OSSL_FUNC_keyexch_set_ctx_params() sets key exchange parameters
128       associated with the given provider side key exchange context ctx to
129       params, see "Common Key Exchange parameters".  Any parameter settings
130       are additional to any that were previously set.  Passing NULL for
131       params should return true.
133       OSSL_FUNC_keyexch_get_ctx_params() gets key exchange parameters
134       associated with the given provider side key exchange context ctx into
135       params, see "Common Key Exchange parameters".  Passing NULL for params
136       should return true.
138       OSSL_FUNC_keyexch_settable_ctx_params() yields a constant OSSL_PARAM
139       array that describes the settable parameters, i.e. parameters that can
140       be used with OP_signature_set_ctx_params().  If
141       OSSL_FUNC_keyexch_settable_ctx_params() is present,
142       OSSL_FUNC_keyexch_set_ctx_params() must also be present, and vice
143       versa.  Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a
144       constant OSSL_PARAM array that describes the gettable parameters, i.e.
145       parameters that can be handled by OP_signature_get_ctx_params().  If
146       OSSL_FUNC_keyexch_gettable_ctx_params() is present,
147       OSSL_FUNC_keyexch_get_ctx_params() must also be present, and vice
148       versa.  See OSSL_PARAM(3) for the use of OSSL_PARAM as parameter
149       descriptor.
151       Notice that not all settable parameters are also gettable, and vice
152       versa.
154   Common Key Exchange parameters
155       See OSSL_PARAM(3) for further details on the parameters structure used
156       by the OSSL_FUNC_keyexch_set_ctx_params() and
157       OSSL_FUNC_keyexch_get_ctx_params() functions.
159       Common parameters currently recognised by built-in key exchange
160       algorithms are as follows.
162       "kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>
163           Sets or gets the Key Derivation Function type to apply within the
164           associated key exchange ctx.
166       "kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>
167           Sets or gets the Digest algorithm to be used as part of the Key
168           Derivation Function associated with the given key exchange ctx.
170       "kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>
171           Sets properties to be used upon look up of the implementation for
172           the selected Digest algorithm for the Key Derivation Function
173           associated with the given key exchange ctx.
175       "kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>
176           Sets or gets the desired size for the output of the chosen Key
177           Derivation Function associated with the given key exchange ctx.
178           The length of the "kdf-outlen" parameter should not exceed that of
179           a size_t.
181       "kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>
182           Sets the User Key Material to be used as part of the selected Key
183           Derivation Function associated with the given key exchange ctx.
185       "kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string ptr>
186           Gets a pointer to the User Key Material to be used as part of the
187           selected Key Derivation Function associated with the given key
188           exchange ctx. Providers usually do not need to support this
189           gettable parameter as its sole purpose is to support functionality
190           of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm() and
191           EVP_PKEY_CTX_get0_dh_kdf_ukm() functions.


194       OSSL_FUNC_keyexch_newctx() and OSSL_FUNC_keyexch_dupctx() should return
195       the newly created provider side key exchange context, or NULL on
196       failure.
198       OSSL_FUNC_keyexch_init(), OSSL_FUNC_keyexch_set_peer(),
199       OSSL_FUNC_keyexch_derive(), OSSL_FUNC_keyexch_set_params(), and
200       OSSL_FUNC_keyexch_get_params() should return 1 for success or 0 on
201       error.
203       OSSL_FUNC_keyexch_settable_ctx_params() and
204       OSSL_FUNC_keyexch_gettable_ctx_params() should always return a constant
205       OSSL_PARAM array.


208       provider(7)


211       The provider KEYEXCH interface was introduced in OpenSSL 3.0.
214       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
216       Licensed under the Apache License 2.0 (the "License").  You may not use
217       this file except in compliance with the License.  You can obtain a copy
218       in the file LICENSE in the source distribution or at
219       <https://www.openssl.org/source/license.html>.
2233.0.5                             2022-07-05           PROVIDER-KEYEXCH(7ossl)