5 provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
9 #include <openssl/core_numbers.h>
12 * None of these are actual functions, but are displayed like this for
13 * the function signatures for functions that are offered as function
14 * pointers in OSSL_DISPATCH arrays.
17 /* Key domain parameter creation and destruction */
18 void *OP_keymgmt_importdomparams(void *provctx, const OSSL_PARAM params[]);
19 void *OP_keymgmt_gendomparams(void *provctx, const OSSL_PARAM params[]);
20 void OP_keymgmt_freedomparams(void *domparams);
22 /* Key domain parameter export */
23 int OP_keymgmt_exportdomparams(void *domparams, OSSL_PARAM params[]);
25 /* Key domain parameter discovery */
26 const OSSL_PARAM *OP_keymgmt_importdomparam_types(void);
27 const OSSL_PARAM *OP_keymgmt_exportdomparam_types(void);
29 /* Key creation and destruction */
30 void *OP_keymgmt_importkey(void *provctx, const OSSL_PARAM params[]);
31 void *OP_keymgmt_genkey(void *provctx,
32 void *domparams, const OSSL_PARAM genkeyparams[]);
33 void *OP_keymgmt_loadkey(void *provctx, void *id, size_t idlen);
34 void OP_keymgmt_freekey(void *key);
37 int OP_keymgmt_exportkey(void *key, OSSL_PARAM params[]);
40 const OSSL_PARAM *OP_keymgmt_importkey_types(void);
41 const OSSL_PARAM *OP_keymgmt_exportkey_types(void);
45 The KEYMGMT operation doesn't have much public visibility in OpenSSL
46 libraries, it's rather an internal operation that's designed to work
47 in tandem with operations that use private/public key pairs.
49 Because the KEYMGMT operation shares knowledge with the operations it
50 works with in tandem, they must belong to the same provider.
51 The OpenSSL libraries will ensure that they do.
53 The primary responsibility of the KEYMGMT operation is to hold the
54 provider side domain parameters and keys for the OpenSSL library
57 All "functions" mentioned here are passed as function pointers between
58 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
59 B<OSSL_ALGORITHM> arrays that are returned by the provider's
60 provider_query_operation() function
61 (see L<provider-base(7)/Provider Functions>).
63 All these "functions" have a corresponding function type definition
64 named B<OSSL_{name}_fn>, and a helper function to retrieve the
65 function pointer from a B<OSSL_DISPATCH> element named
67 For example, the "function" OP_keymgmt_importdomparams() has these:
70 (OSSL_OP_keymgmt_importdomparams_fn)(void *provctx,
71 const OSSL_PARAM params[]);
72 static ossl_inline OSSL_OP_keymgmt_importdomparams_fn
73 OSSL_get_OP_keymgmt_importdomparams(const OSSL_DISPATCH *opf);
75 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
76 macros in L<openssl-core_numbers.h(7)>, as follows:
78 OP_keymgmt_importdomparams OSSL_FUNC_KEYMGMT_IMPORTDOMPARAMS
79 OP_keymgmt_gendomparams OSSL_FUNC_KEYMGMT_GENDOMPARAMS
80 OP_keymgmt_freedomparams OSSL_FUNC_KEYMGMT_FREEDOMPARAMS
81 OP_keymgmt_exportdomparams OSSL_FUNC_KEYMGMT_EXPORTDOMPARAMS
82 OP_keymgmt_importdomparam_types OSSL_FUNC_KEYMGMT_IMPORTDOMPARAM_TYPES
83 OP_keymgmt_exportdomparam_types OSSL_FUNC_KEYMGMT_EXPORTDOMPARAM_TYPES
85 OP_keymgmt_importkey OSSL_FUNC_KEYMGMT_IMPORTKEY
86 OP_keymgmt_genkey OSSL_FUNC_KEYMGMT_GENKEY
87 OP_keymgmt_loadkey OSSL_FUNC_KEYMGMT_LOADKEY
88 OP_keymgmt_freekey OSSL_FUNC_KEYMGMT_FREEKEY
89 OP_keymgmt_exportkey OSSL_FUNC_KEYMGMT_EXPORTKEY
90 OP_keymgmt_importkey_types OSSL_FUNC_KEYMGMT_IMPORTKEY_TYPES
91 OP_keymgmt_exportkey_types OSSL_FUNC_KEYMGMT_EXPORTKEY_TYPES
93 =head2 Domain Parameter Functions
95 OP_keymgmt_importdomparams() should create a provider side structure
96 for domain parameters, with values taken from the passed B<OSSL_PARAM>
99 OP_keymgmt_gendomparams() should generate domain parameters and create
100 a provider side structure for them.
101 Values of the passed B<OSSL_PARAM> array I<params> should be used as
102 input for parameter generation.
104 OP_keymgmt_freedomparams() should free the passed provider side domain
105 parameter structure I<domparams>.
107 OP_keymgmt_exportdomparams() should extract values from the passed
108 provider side domain parameter structure I<domparams> into the passed
109 B<OSSL_PARAM> I<params>.
110 Only the values specified in I<params> should be extracted.
112 OP_keymgmt_importdomparam_types() should return a constant array of
113 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams()
116 =for comment There should be one corresponding to OP_keymgmt_gendomparams()
119 OP_keymgmt_exportdomparam_types() should return a constant array of
120 descriptor B<OSSL_PARAM>, for parameters that can be exported with
121 OP_keymgmt_exportdomparams().
125 OP_keymgmt_importkey() should create a provider side structure
126 for keys, with values taken from the passed B<OSSL_PARAM> array
129 OP_keymgmt_genkey() should generate keys and create a provider side
131 Values from the passed domain parameters I<domparams> as well as from
132 the passed B<OSSL_PARAM> array I<params> should be used as input for
135 OP_keymgmt_loadkey() should return a provider side key structure with
136 a key loaded from a location known only to the provider, identitified
137 with the identity I<id> of size I<idlen>.
138 This identity is internal to the provider and is retrieved from the
139 provider through other means.
141 =for comment Right now, OP_keymgmt_loadkey is useless, but will be
142 useful as soon as we have a OSSL_STORE interface
144 OP_keymgmt_freekey() should free the passed I<key>.
146 OP_keymgmt_exportkey() should extract values from the passed
147 provider side key I<key> into the passed B<OSSL_PARAM> I<params>.
148 Only the values specified in I<params> should be extracted.
150 OP_keymgmt_importkey_types() should return a constant array of
151 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey()
154 =for comment There should be one corresponding to OP_keymgmt_genkey()
157 OP_keymgmt_exportkey_types() should return a constant array of
158 descriptor B<OSSL_PARAM>, for parameters that can be exported with
159 OP_keymgmt_exportkeys().
167 The KEYMGMT interface was introduced in OpenSSL 3.0.
171 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
173 Licensed under the Apache License 2.0 (the "License"). You may not use
174 this file except in compliance with the License. You can obtain a copy
175 in the file LICENSE in the source distribution or at
176 L<https://www.openssl.org/source/license.html>.