Redesign the KEYMGMT libcrypto <-> provider interface - the basics
[openssl.git] / doc / man7 / provider-keymgmt.pod
1 =pod
2
3 =head1 NAME
4
5 provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
6
7 =head1 SYNOPSIS
8
9  #include <openssl/core_numbers.h>
10
11  /*
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.
15   */
16
17  /* Key object (keydata) creation and destruction */
18  void *OP_keymgmt_new(void *provctx);
19  void OP_keymgmt_free(void *keydata);
20
21  /* Key object information */
22  int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
23  const OSSL_PARAM *OP_keymgmt_gettable_params(void);
24
25  /* Key object content checks */
26  int OP_keymgmt_has(void *keydata, int selection);
27
28  /* Discovery of supported operations */
29  const char *OP_keymgmt_query_operation_name(int operation_id);
30
31  /* Key object import and export functions */
32  int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
33  const OSSL_PARAM *OP_keymgmt_import_types, (int selection);
34  int OP_keymgmt_export(int selection, void *keydata,
35                        OSSL_CALLBACK *param_cb, void *cbarg);
36  const OSSL_PARAM *OP_keymgmt_export_types(int selection);
37
38  /* Key object validation */
39  int OP_keymgmt_validate(void *keydata, int selection);
40
41  /* Discovery of supported operations */
42  const char *OP_keymgmt_query_operation_name(int operation_id);
43
44 =head1 DESCRIPTION
45
46 The KEYMGMT operation doesn't have much public visibility in OpenSSL
47 libraries, it's rather an internal operation that's designed to work
48 in tandem with operations that use private/public key pairs.
49
50 Because the KEYMGMT operation shares knowledge with the operations it
51 works with in tandem, they must belong to the same provider.
52 The OpenSSL libraries will ensure that they do.
53
54 The primary responsibility of the KEYMGMT operation is to hold the
55 provider side key data for the OpenSSL library EVP_PKEY structure.
56
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>).
62
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
66 B<OSSL_get_{name}>.
67 For example, the "function" OP_keymgmt_new() has these:
68
69  typedef void *(OSSL_OP_keymgmt_new_fn)(void *provctx);
70  static ossl_inline OSSL_OP_keymgmt_new_fn
71      OSSL_get_OP_keymgmt_new(const OSSL_DISPATCH *opf);
72
73 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
74 macros in L<openssl-core_numbers.h(7)>, as follows:
75
76  OP_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
77  OP_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE
78
79  OP_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
80  OP_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
81
82  OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
83
84  OP_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
85  OP_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
86
87  OP_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
88  OP_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
89  OP_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
90  OP_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
91
92
93 =head2 Key Objects
94
95 A key object is a collection of data for an asymmetric key, and is
96 represented as I<keydata> in this manual.
97
98 The exact contents of a key object are defined by the provider, and it
99 is assumed that different operations in one and the same provider use
100 the exact same structure to represent this collection of data, so that
101 for example, a key object that has been created using the KEYMGMT
102 interface that we document here can be passed as is to other provider
103 operations, such as OP_signature_sign_init() (see
104 L<provider-signature(7)>).
105
106 With some of the KEYMGMT functions, it's possible to select a specific
107 subset of data to handle, governed by the bits in a I<selection>
108 indicator.  The bits are:
109
110 =over 4
111
112 =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
113
114 Indicating that the private key data in a key object should be
115 considered.
116
117 =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>
118
119 Indicating that the public key data in a key object should be
120 considered.
121
122 =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS>
123
124 Indicating that the domain parameters in a key object should be
125 considered.
126
127 =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>
128
129 Indicating that other parameters in a key object should be
130 considered.
131
132 Other parameters are key parameters that don't fit any other
133 classification.  In other words, this particular selector bit works as
134 a last resort bit bucket selector.
135
136 =back
137
138 Some selector bits have also been combined for easier use:
139
140 =over 4
141
142 =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
143
144 Indicating that all key object parameters should be considered,
145 regardless of their more granular classification.
146
147 =for comment This should used by EVP functions such as
148 EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters()
149
150 This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
151 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
152
153 =for comment If more parameter categories are added, they should be
154 mentioned here too.
155
156 =item B<OSSL_KEYMGMT_SELECT_KEYPAIR>
157
158 Indicating that both the whole key pair in a key object should be
159 considered, i.e. the combination of public and private key.
160
161 This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
162 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>.
163
164 =item B<OSSL_KEYMGMT_SELECT_ALL>
165
166 Indicating that everything in a key object should be considered.
167
168 =back
169
170 The exact interpretation of those bits or how they combine is left to
171 each function where you can specify a selector.
172
173 =for comment One might think that a combination of bits means that all
174 the selected data subsets must be considered, but then you have to
175 consider that when comparing key objects (future function), an
176 implementation might opt to not compare the private key if it has
177 compared the public key, since a match of one half implies a match of
178 the other half.
179
180 =head2 Constructing and Destructing Functions
181
182 OP_keymgmt_new() should create a provider side key object.  The
183 provider context I<provctx> is passed and may be incorporated in the
184 key object, but that is not mandatory.
185
186 OP_keymgmt_free() should free the passed I<keydata>.
187
188 The constructor and destructor are mandatory, a KEYMGMT implementation
189 without them will not be accepted.
190
191 =for comment when new constructors appear, it's sufficient if only one
192 of them is present.  The remark above will have to change to reflect
193 that.
194
195 =head2 Key Object Information Functions
196
197 OP_keymgmt_get_params() should extract information data associated
198 with the given I<keydata>, see L</Information Parameters>.
199
200 OP_keymgmt_gettable_params() should return a constant array of
201 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
202 can handle.
203
204 If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
205 must also be present.
206
207 =head2 Key Object Checking Functions
208
209 OP_keymgmt_query_operation_name() should return the name of the
210 supported algorithm for the operation I<operation_id>.  This is
211 similar to provider_query_operation() (see L<provider-base(7)>),
212 but only works as an advisory.  If this function is not present, or
213 returns NULL, the caller is free to assume that there's an algorithm
214 from the same provider, of the same name as the one used to fetch the
215 keymgmt and try to use that.
216
217 OP_keymgmt_has() should check whether the given I<keydata> the subsets
218 of data indicated by the I<selector>.  A combination of several
219 selector bits must consider all those subsets, not just one.  An
220 implementation is, however, free to consider an empty subset of data
221 to still be a valid subset.
222
223 OP_keymgmt_validate() should check if the I<keydata> contains valid
224 data subsets indicated by I<selection>.  Some combined selections of
225 data subsets may cause validation of the combined data.
226 For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
227 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
228 for short) is expected to check that the pairwise consistency of
229 I<keydata> is valid.
230
231 =head2 Key Object Import and Export Functions
232
233 OP_keymgmt_import() should import data indicated by I<selection> into
234 I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
235
236 OP_keymgmt_export() should extract values indicated by I<selection>
237 from I<keydata>, create an B<OSSL_PARAM> array with them and call
238 I<param_cb> with that array as well as the given I<cbarg>.
239
240 OP_keymgmt_import_types() should return a constant array of descriptor
241 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
242 OP_keymgmt_import() can handle.
243
244 OP_keymgmt_export_types() should return a constant array of descriptor
245 B<OSSL_PARAM> for data indicated by I<selection>, that the
246 OP_keymgmt_export() callback can expect to receive.
247
248 =head2 Information Parameters
249
250 See L<OSSL_PARAM(3)> for further details on the parameters structure.
251
252 Parameters currently recognised by built-in keymgmt algorithms'
253 OP_keymgmt_get_params:
254
255 =over 4
256
257 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
258
259 The value should be the cryptographic length of the cryptosystem to
260 which the key belongs, in bits.  The definition of cryptographic
261 length is specific to the key cryptosystem.
262
263 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
264
265 The value should be the maximum size that a caller should allocate to
266 safely store a signature (called I<sig> in L<provider-signature(7)>),
267 the result of asymmmetric encryption / decryption (I<out> in
268 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
269 L<provider-keyexch(7)>, and similar data).
270
271 Because an EVP_KEYMGMT method is always tightly bound to another method
272 (signature, asymmetric cipher, key exchange, ...) and must be of the
273 same provider, this number only needs to be synchronised with the
274 dimensions handled in the rest of the same provider.
275
276 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
277
278 The value should be the number of security bits of the given key.
279 Bits of security is defined in SP800-57.
280
281 =back
282
283 =head1 SEE ALSO
284
285 L<provider(7)>
286
287 =head1 HISTORY
288
289 The KEYMGMT interface was introduced in OpenSSL 3.0.
290
291 =head1 COPYRIGHT
292
293 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
294
295 Licensed under the Apache License 2.0 (the "License").  You may not use
296 this file except in compliance with the License.  You can obtain a copy
297 in the file LICENSE in the source distribution or at
298 L<https://www.openssl.org/source/license.html>.
299
300 =cut