91b87cecdc19f32821a802e53bd61fe8b2709b5b
[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  int OP_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
25  const OSSL_PARAM *OP_keymgmt_settable_params(void);
26
27  /* Key object content checks */
28  int OP_keymgmt_has(void *keydata, int selection);
29  int OP_keymgmt_match(const void *keydata1, const void *keydata2,
30                       int selection);
31
32  /* Discovery of supported operations */
33  const char *OP_keymgmt_query_operation_name(int operation_id);
34
35  /* Key object import and export functions */
36  int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
37  const OSSL_PARAM *OP_keymgmt_import_types(int selection);
38  int OP_keymgmt_export(int selection, void *keydata,
39                        OSSL_CALLBACK *param_cb, void *cbarg);
40  const OSSL_PARAM *OP_keymgmt_export_types(int selection);
41
42  /* Key object copy */
43  int OP_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection);
44
45  /* Key object validation */
46  int OP_keymgmt_validate(void *keydata, int selection);
47
48 =head1 DESCRIPTION
49
50 The KEYMGMT operation doesn't have much public visibility in OpenSSL
51 libraries, it's rather an internal operation that's designed to work
52 in tandem with operations that use private/public key pairs.
53
54 Because the KEYMGMT operation shares knowledge with the operations it
55 works with in tandem, they must belong to the same provider.
56 The OpenSSL libraries will ensure that they do.
57
58 The primary responsibility of the KEYMGMT operation is to hold the
59 provider side key data for the OpenSSL library EVP_PKEY structure.
60
61 All "functions" mentioned here are passed as function pointers between
62 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
63 B<OSSL_ALGORITHM> arrays that are returned by the provider's
64 provider_query_operation() function
65 (see L<provider-base(7)/Provider Functions>).
66
67 All these "functions" have a corresponding function type definition
68 named B<OSSL_{name}_fn>, and a helper function to retrieve the
69 function pointer from a B<OSSL_DISPATCH> element named
70 B<OSSL_get_{name}>.
71 For example, the "function" OP_keymgmt_new() has these:
72
73  typedef void *(OSSL_OP_keymgmt_new_fn)(void *provctx);
74  static ossl_inline OSSL_OP_keymgmt_new_fn
75      OSSL_get_OP_keymgmt_new(const OSSL_DISPATCH *opf);
76
77 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
78 macros in L<openssl-core_numbers.h(7)>, as follows:
79
80  OP_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
81  OP_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE
82
83  OP_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
84  OP_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
85  OP_keymgmt_set_params           OSSL_FUNC_KEYMGMT_SET_PARAMS
86  OP_keymgmt_settable_params      OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
87
88  OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
89
90  OP_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
91  OP_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
92  OP_keymgmt_match                OSSL_FUNC_KEYMGMT_MATCH
93
94  OP_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
95  OP_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
96  OP_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
97  OP_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
98
99  OP_keymgmt_copy                 OSSL_FUNC_KEYMGMT_COPY
100
101 =head2 Key Objects
102
103 A key object is a collection of data for an asymmetric key, and is
104 represented as I<keydata> in this manual.
105
106 The exact contents of a key object are defined by the provider, and it
107 is assumed that different operations in one and the same provider use
108 the exact same structure to represent this collection of data, so that
109 for example, a key object that has been created using the KEYMGMT
110 interface that we document here can be passed as is to other provider
111 operations, such as OP_signature_sign_init() (see
112 L<provider-signature(7)>).
113
114 With some of the KEYMGMT functions, it's possible to select a specific
115 subset of data to handle, governed by the bits in a I<selection>
116 indicator.  The bits are:
117
118 =over 4
119
120 =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
121
122 Indicating that the private key data in a key object should be
123 considered.
124
125 =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>
126
127 Indicating that the public key data in a key object should be
128 considered.
129
130 =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS>
131
132 Indicating that the domain parameters in a key object should be
133 considered.
134
135 =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>
136
137 Indicating that other parameters in a key object should be
138 considered.
139
140 Other parameters are key parameters that don't fit any other
141 classification.  In other words, this particular selector bit works as
142 a last resort bit bucket selector.
143
144 =back
145
146 Some selector bits have also been combined for easier use:
147
148 =over 4
149
150 =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
151
152 Indicating that all key object parameters should be considered,
153 regardless of their more granular classification.
154
155 =for comment This should used by EVP functions such as
156 EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters()
157
158 This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
159 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
160
161 =for comment If more parameter categories are added, they should be
162 mentioned here too.
163
164 =item B<OSSL_KEYMGMT_SELECT_KEYPAIR>
165
166 Indicating that both the whole key pair in a key object should be
167 considered, i.e. the combination of public and private key.
168
169 This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
170 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>.
171
172 =item B<OSSL_KEYMGMT_SELECT_ALL>
173
174 Indicating that everything in a key object should be considered.
175
176 =back
177
178 The exact interpretation of those bits or how they combine is left to
179 each function where you can specify a selector.
180
181 =for comment One might think that a combination of bits means that all
182 the selected data subsets must be considered, but then you have to
183 consider that when comparing key objects (future function), an
184 implementation might opt to not compare the private key if it has
185 compared the public key, since a match of one half implies a match of
186 the other half.
187
188 =head2 Constructing and Destructing Functions
189
190 OP_keymgmt_new() should create a provider side key object.  The
191 provider context I<provctx> is passed and may be incorporated in the
192 key object, but that is not mandatory.
193
194 OP_keymgmt_free() should free the passed I<keydata>.
195
196 The constructor and destructor are mandatory, a KEYMGMT implementation
197 without them will not be accepted.
198
199 =for comment when new constructors appear, it's sufficient if only one
200 of them is present.  The remark above will have to change to reflect
201 that.
202
203 =head2 Key Object Information Functions
204
205 OP_keymgmt_get_params() should extract information data associated
206 with the given I<keydata>, see L</Information Parameters>.
207
208 OP_keymgmt_gettable_params() should return a constant array of
209 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
210 can handle.
211
212 If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
213 must also be present, and vice versa.
214
215 OP_keymgmt_set_params() should update information data associated
216 with the given I<keydata>, see L</Information Parameters>.
217
218 OP_keymgmt_settable_params() should return a constant array of
219 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params()
220 can handle.
221
222 If OP_keymgmt_settable_params() is present, OP_keymgmt_set_params()
223 must also be present, and vice versa.
224
225 =head2 Key Object Checking Functions
226
227 OP_keymgmt_query_operation_name() should return the name of the
228 supported algorithm for the operation I<operation_id>.  This is
229 similar to provider_query_operation() (see L<provider-base(7)>),
230 but only works as an advisory.  If this function is not present, or
231 returns NULL, the caller is free to assume that there's an algorithm
232 from the same provider, of the same name as the one used to fetch the
233 keymgmt and try to use that.
234
235 OP_keymgmt_has() should check whether the given I<keydata> contains the subsets
236 of data indicated by the I<selector>.  A combination of several
237 selector bits must consider all those subsets, not just one.  An
238 implementation is, however, free to consider an empty subset of data
239 to still be a valid subset.
240
241 OP_keymgmt_validate() should check if the I<keydata> contains valid
242 data subsets indicated by I<selection>.  Some combined selections of
243 data subsets may cause validation of the combined data.
244 For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
245 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
246 for short) is expected to check that the pairwise consistency of
247 I<keydata> is valid.
248
249 OP_keymgmt_match() should check if the data subset indicated by
250 I<selection> in I<keydata1> and I<keydata2> match.  It is assumed that
251 the caller has ensured that I<keydata1> and I<keydata2> are both owned
252 by the implementation of this function.
253
254 =head2 Key Object Import, Export and Copy Functions
255
256 OP_keymgmt_import() should import data indicated by I<selection> into
257 I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
258
259 OP_keymgmt_export() should extract values indicated by I<selection>
260 from I<keydata>, create an B<OSSL_PARAM> array with them and call
261 I<param_cb> with that array as well as the given I<cbarg>.
262
263 OP_keymgmt_import_types() should return a constant array of descriptor
264 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
265 OP_keymgmt_import() can handle.
266
267 OP_keymgmt_export_types() should return a constant array of descriptor
268 B<OSSL_PARAM> for data indicated by I<selection>, that the
269 OP_keymgmt_export() callback can expect to receive.
270
271 OP_keymgmt_copy() should copy data subsets indicated by I<selection>
272 from I<keydata_from> to I<keydata_to>.  It is assumed that the caller
273 has ensured that I<keydata_to> and I<keydata_from> are both owned by
274 the implementation of this function.
275
276 =head2 Built-in RSA Import/Export Types
277
278 The following Import/Export types are available for the built-in RSA algorithm:
279
280 =over 4
281
282 =item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <integer>
283
284 The RSA "n" value.
285
286 =item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <integer>
287
288 The RSA "e" value.
289
290 =item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <integer>
291
292 The RSA "d" value.
293
294 =item "rsa-factor" (B<OSSL_PKEY_PARAM_RSA_FACTOR>) <integer>
295
296 An RSA factor. In 2 prime RSA these are often known as "p" or "q". This value
297 may be repeated up to 10 times in a single key.
298
299 =item "rsa-exponent" (B<OSSL_PKEY_PARAM_RSA_EXPONENT>) <integer>
300
301 An RSA CRT (Chinese Remainder Theorem) exponent. This value may be repeated up
302 to 10 times in a single key.
303
304 =item "rsa-coefficient" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT>) <integer>
305
306 An RSA CRT (Chinese Remainder Theorem) coefficient. This value may be repeated
307 up to 9 times in a single key.
308
309 =back
310
311 =head2 Built-in DSA and Diffie-Hellman Import/Export Types
312
313 The following Import/Export types are available for the built-in DSA and
314 Diffie-Hellman algorithms:
315
316 =over 4
317
318 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <integer> or <octet string>
319
320 The public key value.
321
322 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <integer> or <octet string>
323
324 The private key value.
325
326 =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <integer>
327
328 A DSA or Diffie-Hellman "p" value.
329
330 =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <integer>
331
332 A DSA or Diffie-Hellman "q" value.
333
334 =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <integer>
335
336 A DSA or Diffie-Hellman "g" value.
337
338 =back
339
340 =head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types
341
342 The following Import/Export types are available for the built-in X25519, X448,
343 ED25519 and X448 algorithms:
344
345 =over 4
346
347 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
348
349 The public key value.
350
351 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
352
353 The private key value.
354
355 =back
356
357 =head2 Information Parameters
358
359 See L<OSSL_PARAM(3)> for further details on the parameters structure.
360
361 Parameters currently recognised by built-in keymgmt algorithms
362 are as follows.
363 Not all parameters are relevant to, or are understood by all keymgmt
364 algorithms:
365
366 =over 4
367
368 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
369
370 The value should be the cryptographic length of the cryptosystem to
371 which the key belongs, in bits.  The definition of cryptographic
372 length is specific to the key cryptosystem.
373
374 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
375
376 The value should be the maximum size that a caller should allocate to
377 safely store a signature (called I<sig> in L<provider-signature(7)>),
378 the result of asymmmetric encryption / decryption (I<out> in
379 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
380 L<provider-keyexch(7)>, and similar data).
381
382 Because an EVP_KEYMGMT method is always tightly bound to another method
383 (signature, asymmetric cipher, key exchange, ...) and must be of the
384 same provider, this number only needs to be synchronised with the
385 dimensions handled in the rest of the same provider.
386
387 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
388
389 The value should be the number of security bits of the given key.
390 Bits of security is defined in SP800-57.
391
392 =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>,
393 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
394
395 The value should be either 1 or 0, to respectively enable or disable
396 use of the cofactor in operations using this key.
397
398 In the context of a key that can be used to perform an Elliptic Curve
399 Diffie-Hellman key exchange, this parameter can be used to mark a requirement
400 for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange
401 algorithm.
402
403 See also L<provider-keyexch(7)> for the related
404 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
405 per-operation basis.
406
407 =back
408
409 =head1 RETURN VALUES
410
411 OP_keymgmt_new() should return a valid reference to the newly created provider
412 side key object, or NULL on failure.
413
414 OP_keymgmt_import(), OP_keymgmt_export(), OP_keymgmt_get_params() and
415 OP_keymgmt_set_params() should return 1 for success or 0 on error.
416
417 OP_keymgmt_validate() should return 1 on successful validation, or 0 on
418 failure.
419
420 OP_keymgmt_has() should return 1 if all the selected data subsets are contained
421 in the given I<keydata> or 0 otherwise.
422
423 OP_keymgmt_query_operation_name() should return a pointer to a string matching
424 the requested operation, or NULL if the same name used to fetch the keymgmt
425 applies.
426
427 OP_keymgmt_gettable_params() and OP_keymgmt_settable_params()
428 OP_keymgmt_import_types(), OP_keymgmt_export_types()
429 should
430 always return a constant B<OSSL_PARAM> array.
431
432 =head1 SEE ALSO
433
434 L<provider(7)>
435
436 =head1 HISTORY
437
438 The KEYMGMT interface was introduced in OpenSSL 3.0.
439
440 =head1 COPYRIGHT
441
442 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
443
444 Licensed under the Apache License 2.0 (the "License").  You may not use
445 this file except in compliance with the License.  You can obtain a copy
446 in the file LICENSE in the source distribution or at
447 L<https://www.openssl.org/source/license.html>.
448
449 =cut