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