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_dispatch.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 *OSSL_FUNC_keymgmt_new(void *provctx);
  19  void OSSL_FUNC_keymgmt_free(void *keydata);
  20
  21  /* Generation, a more complex constructor */
  22  void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection);
  23  int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template);
  24  int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
  25  const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx,
  26                                                          void *provctx);
  27  void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
  28  void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx);
  29
  30  /* Key loading by object reference, also a constructor */
  31  void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz);
  32
  33  /* Key object information */
  34  int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
  35  const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx);
  36  int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
  37  const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx);
  38
  39  /* Key object content checks */
  40  int OSSL_FUNC_keymgmt_has(const void *keydata, int selection);
  41  int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2,
  42                              int selection);
  43
  44  /* Discovery of supported operations */
  45  const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id);
  46
  47  /* Key object import and export functions */
  48  int OSSL_FUNC_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
  49  const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
  50  int OSSL_FUNC_keymgmt_export(int selection, void *keydata,
  51                               OSSL_CALLBACK *param_cb, void *cbarg);
  52  const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
  53
  54  /* Key object copy */
  55  int OSSL_FUNC_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection);
  56
  57  /* Key object validation */
  58  int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype);
  59
  60 =head1 DESCRIPTION
  61
  62 The KEYMGMT operation doesn't have much public visibility in OpenSSL
  63 libraries, it's rather an internal operation that's designed to work
  64 in tandem with operations that use private/public key pairs.
  65
  66 Because the KEYMGMT operation shares knowledge with the operations it
  67 works with in tandem, they must belong to the same provider.
  68 The OpenSSL libraries will ensure that they do.
  69
  70 The primary responsibility of the KEYMGMT operation is to hold the
  71 provider side key data for the OpenSSL library EVP_PKEY structure.
  72
  73 All "functions" mentioned here are passed as function pointers between
  74 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
  75 B<OSSL_ALGORITHM> arrays that are returned by the provider's
  76 provider_query_operation() function
  77 (see L<provider-base(7)/Provider Functions>).
  78
  79 All these "functions" have a corresponding function type definition
  80 named B<OSSL_{name}_fn>, and a helper function to retrieve the
  81 function pointer from a B<OSSL_DISPATCH> element named
  82 B<OSSL_FUNC_{name}>.
  83 For example, the "function" OSSL_FUNC_keymgmt_new() has these:
  84
  85  typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx);
  86  static ossl_inline OSSL_FUNC_keymgmt_new_fn
  87      OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf);
  88
  89 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
  90 macros in L<openssl-core_dispatch.h(7)>, as follows:
  91
  92  OSSL_FUNC_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
  93  OSSL_FUNC_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE
  94
  95  OSSL_FUNC_keymgmt_gen_init             OSSL_FUNC_KEYMGMT_GEN_INIT
  96  OSSL_FUNC_keymgmt_gen_set_template     OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE
  97  OSSL_FUNC_keymgmt_gen_set_params       OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS
  98  OSSL_FUNC_keymgmt_gen_settable_params  OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS
  99  OSSL_FUNC_keymgmt_gen                  OSSL_FUNC_KEYMGMT_GEN
 100  OSSL_FUNC_keymgmt_gen_cleanup          OSSL_FUNC_KEYMGMT_GEN_CLEANUP
 101
 102  OSSL_FUNC_keymgmt_load                 OSSL_FUNC_KEYMGMT_LOAD
 103
 104  OSSL_FUNC_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
 105  OSSL_FUNC_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
 106  OSSL_FUNC_keymgmt_set_params           OSSL_FUNC_KEYMGMT_SET_PARAMS
 107  OSSL_FUNC_keymgmt_settable_params      OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
 108
 109  OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
 110
 111  OSSL_FUNC_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
 112  OSSL_FUNC_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
 113  OSSL_FUNC_keymgmt_match                OSSL_FUNC_KEYMGMT_MATCH
 114
 115  OSSL_FUNC_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
 116  OSSL_FUNC_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
 117  OSSL_FUNC_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
 118  OSSL_FUNC_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
 119
 120  OSSL_FUNC_keymgmt_copy                 OSSL_FUNC_KEYMGMT_COPY
 121
 122 =head2 Key Objects
 123
 124 A key object is a collection of data for an asymmetric key, and is
 125 represented as I<keydata> in this manual.
 126
 127 The exact contents of a key object are defined by the provider, and it
 128 is assumed that different operations in one and the same provider use
 129 the exact same structure to represent this collection of data, so that
 130 for example, a key object that has been created using the KEYMGMT
 131 interface that we document here can be passed as is to other provider
 132 operations, such as OP_signature_sign_init() (see
 133 L<provider-signature(7)>).
 134
 135 With some of the KEYMGMT functions, it's possible to select a specific
 136 subset of data to handle, governed by the bits in a I<selection>
 137 indicator.  The bits are:
 138
 139 =over 4
 140
 141 =item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
 142
 143 Indicating that the private key data in a key object should be
 144 considered.
 145
 146 =item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>
 147
 148 Indicating that the public key data in a key object should be
 149 considered.
 150
 151 =item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS>
 152
 153 Indicating that the domain parameters in a key object should be
 154 considered.
 155
 156 =item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>
 157
 158 Indicating that other parameters in a key object should be
 159 considered.
 160
 161 Other parameters are key parameters that don't fit any other
 162 classification.  In other words, this particular selector bit works as
 163 a last resort bit bucket selector.
 164
 165 =back
 166
 167 Some selector bits have also been combined for easier use:
 168
 169 =over 4
 170
 171 =item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
 172
 173 Indicating that all key object parameters should be considered,
 174 regardless of their more granular classification.
 175
 176 =for comment This should used by EVP functions such as
 177 EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters()
 178
 179 This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
 180 B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
 181
 182 =for comment If more parameter categories are added, they should be
 183 mentioned here too.
 184
 185 =item B<OSSL_KEYMGMT_SELECT_KEYPAIR>
 186
 187 Indicating that both the whole key pair in a key object should be
 188 considered, i.e. the combination of public and private key.
 189
 190 This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
 191 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>.
 192
 193 =item B<OSSL_KEYMGMT_SELECT_ALL>
 194
 195 Indicating that everything in a key object should be considered.
 196
 197 =back
 198
 199 The exact interpretation of those bits or how they combine is left to
 200 each function where you can specify a selector.
 201
 202 =for comment One might think that a combination of bits means that all
 203 the selected data subsets must be considered, but then you have to
 204 consider that when comparing key objects (future function), an
 205 implementation might opt to not compare the private key if it has
 206 compared the public key, since a match of one half implies a match of
 207 the other half.
 208
 209 =head2 Constructing and Destructing Functions
 210
 211 OSSL_FUNC_keymgmt_new() should create a provider side key object.  The
 212 provider context I<provctx> is passed and may be incorporated in the
 213 key object, but that is not mandatory.
 214
 215 OSSL_FUNC_keymgmt_free() should free the passed I<keydata>.
 216
 217 OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(),
 218 OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(),
 219 OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a
 220 more elaborate context based key object constructor.
 221
 222 OSSL_FUNC_keymgmt_gen_init() should create the key object generation context
 223 and initialize it with I<selections>, which will determine what kind
 224 of contents the key object to be generated should get.
 225
 226 OSSL_FUNC_keymgmt_gen_set_template() should add I<template> to the context
 227 I<genctx>.  The I<template> is assumed to be a key object constructed
 228 with the same KEYMGMT, and from which content that the implementation
 229 chooses can be used as a template for the key object to be generated.
 230 Typically, the generation of a DSA or DH key would get the domain
 231 parameters from this I<template>.
 232
 233 OSSL_FUNC_keymgmt_gen_set_params() should set additional parameters from
 234 I<params> in the key object generation context I<genctx>.
 235
 236 OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of
 237 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_gen_set_params()
 238 can handle.
 239
 240 OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and
 241 return the result.  The callback I<cb> should be called at regular
 242 intervals with indications on how the key object generation
 243 progresses.
 244
 245 OSSL_FUNC_keymgmt_gen_cleanup() should clean up and free the key object
 246 generation context I<genctx>
 247
 248 OSSL_FUNC_keymgmt_load() creates a provider side key object based on a
 249 I<reference> object with a size of I<reference_sz> bytes, that only the
 250 provider knows how to interpret, but that may come from other operations.
 251 Outside the provider, this reference is simply an array of bytes.
 252
 253 At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and
 254 OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free().
 255 Additionally, if OSSL_FUNC_keymgmt_gen() is present, OSSL_FUNC_keymgmt_gen_init()
 256 and OSSL_FUNC_keymgmt_gen_cleanup() must be present as well.
 257
 258 =head2 Key Object Information Functions
 259
 260 OSSL_FUNC_keymgmt_get_params() should extract information data associated
 261 with the given I<keydata>, see L</Common Information Parameters>.
 262
 263 OSSL_FUNC_keymgmt_gettable_params() should return a constant array of
 264 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_get_params()
 265 can handle.
 266
 267 If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params()
 268 must also be present, and vice versa.
 269
 270 OSSL_FUNC_keymgmt_set_params() should update information data associated
 271 with the given I<keydata>, see L</Common Information Parameters>.
 272
 273 OSSL_FUNC_keymgmt_settable_params() should return a constant array of
 274 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_keymgmt_set_params()
 275 can handle.
 276
 277 If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params()
 278 must also be present, and vice versa.
 279
 280 =head2 Key Object Checking Functions
 281
 282 OSSL_FUNC_keymgmt_query_operation_name() should return the name of the
 283 supported algorithm for the operation I<operation_id>.  This is
 284 similar to provider_query_operation() (see L<provider-base(7)>),
 285 but only works as an advisory.  If this function is not present, or
 286 returns NULL, the caller is free to assume that there's an algorithm
 287 from the same provider, of the same name as the one used to fetch the
 288 keymgmt and try to use that.
 289
 290 OSSL_FUNC_keymgmt_has() should check whether the given I<keydata> contains the subsets
 291 of data indicated by the I<selector>.  A combination of several
 292 selector bits must consider all those subsets, not just one.  An
 293 implementation is, however, free to consider an empty subset of data
 294 to still be a valid subset.
 295
 296 OSSL_FUNC_keymgmt_validate() should check if the I<keydata> contains valid
 297 data subsets indicated by I<selection>.  Some combined selections of
 298 data subsets may cause validation of the combined data.
 299 For example, the combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
 300 B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
 301 for short) is expected to check that the pairwise consistency of
 302 I<keydata> is valid. The I<checktype> parameter controls what type of check is
 303 performed on the subset of data. Two types of check are defined:
 304 B<OSSL_KEYMGMT_VALIDATE_FULL_CHECK> and B<OSSL_KEYMGMT_VALIDATE_QUICK_CHECK>.
 305 The interpretation of how much checking is performed in a full check versus a
 306 quick check is key type specific. Some providers may have no distinction
 307 between a full check and a quick check.
 308
 309 OSSL_FUNC_keymgmt_match() should check if the data subset indicated by
 310 I<selection> in I<keydata1> and I<keydata2> match.  It is assumed that
 311 the caller has ensured that I<keydata1> and I<keydata2> are both owned
 312 by the implementation of this function.
 313
 314 =head2 Key Object Import, Export and Copy Functions
 315
 316 OSSL_FUNC_keymgmt_import() should import data indicated by I<selection> into
 317 I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
 318
 319 OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection>
 320 from I<keydata>, create an B<OSSL_PARAM> array with them and call
 321 I<param_cb> with that array as well as the given I<cbarg>.
 322
 323 OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor
 324 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
 325 OSSL_FUNC_keymgmt_import() can handle.
 326
 327 OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor
 328 B<OSSL_PARAM> for data indicated by I<selection>, that the
 329 OSSL_FUNC_keymgmt_export() callback can expect to receive.
 330
 331 OSSL_FUNC_keymgmt_copy() should copy data subsets indicated by I<selection>
 332 from I<keydata_from> to I<keydata_to>.  It is assumed that the caller
 333 has ensured that I<keydata_to> and I<keydata_from> are both owned by
 334 the implementation of this function.
 335
 336 =head2 Common Information Parameters
 337
 338 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 339
 340 Common information parameters currently recognised by all built-in
 341 keymgmt algorithms are as follows:
 342
 343 =over 4
 344
 345 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
 346
 347 The value should be the cryptographic length of the cryptosystem to
 348 which the key belongs, in bits.  The definition of cryptographic
 349 length is specific to the key cryptosystem.
 350
 351 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
 352
 353 The value should be the maximum size that a caller should allocate to
 354 safely store a signature (called I<sig> in L<provider-signature(7)>),
 355 the result of asymmmetric encryption / decryption (I<out> in
 356 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
 357 L<provider-keyexch(7)>, and similar data).
 358
 359 Because an EVP_KEYMGMT method is always tightly bound to another method
 360 (signature, asymmetric cipher, key exchange, ...) and must be of the
 361 same provider, this number only needs to be synchronised with the
 362 dimensions handled in the rest of the same provider.
 363
 364 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
 365
 366 The value should be the number of security bits of the given key.
 367 Bits of security is defined in SP800-57.
 368
 369 =back
 370
 371 =head1 RETURN VALUES
 372
 373 OSSL_FUNC_keymgmt_new() should return a valid reference to the newly created provider
 374 side key object, or NULL on failure.
 375
 376 OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and
 377 OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error.
 378
 379 OSSL_FUNC_keymgmt_validate() should return 1 on successful validation, or 0 on
 380 failure.
 381
 382 OSSL_FUNC_keymgmt_has() should return 1 if all the selected data subsets are contained
 383 in the given I<keydata> or 0 otherwise.
 384
 385 OSSL_FUNC_keymgmt_query_operation_name() should return a pointer to a string matching
 386 the requested operation, or NULL if the same name used to fetch the keymgmt
 387 applies.
 388
 389 OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params()
 390 OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types()
 391 should
 392 always return a constant B<OSSL_PARAM> array.
 393
 394 =head1 SEE ALSO
 395
 396 L<provider(7)>,
 397 L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>,
 398 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>,
 399 L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>
 400
 401 =head1 HISTORY
 402
 403 The KEYMGMT interface was introduced in OpenSSL 3.0.
 404
 405 =head1 COPYRIGHT
 406
 407 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 408
 409 Licensed under the Apache License 2.0 (the "License").  You may not use
 410 this file except in compliance with the License.  You can obtain a copy
 411 in the file LICENSE in the source distribution or at
 412 L<https://www.openssl.org/source/license.html>.
 413
 414 =cut