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  void *OP_keymgmt_gen_init(void *provctx, int selection);
  22  int OP_keymgmt_gen_set_template(void *genctx, void *template);
  23  int OP_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
  24  const OSSL_PARAM *OP_keymgmt_gen_settable_params(void *provctx);
  25  void *OP_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
  26  void OP_keymgmt_gen_cleanup(void *genctx);
  27
  28  /* Key object information */
  29  int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
  30  const OSSL_PARAM *OP_keymgmt_gettable_params(void);
  31  int OP_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
  32  const OSSL_PARAM *OP_keymgmt_settable_params(void);
  33
  34  /* Key object content checks */
  35  int OP_keymgmt_has(void *keydata, int selection);
  36  int OP_keymgmt_match(const void *keydata1, const void *keydata2,
  37                       int selection);
  38
  39  /* Discovery of supported operations */
  40  const char *OP_keymgmt_query_operation_name(int operation_id);
  41
  42  /* Key object import and export functions */
  43  int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
  44  const OSSL_PARAM *OP_keymgmt_import_types(int selection);
  45  int OP_keymgmt_export(int selection, void *keydata,
  46                        OSSL_CALLBACK *param_cb, void *cbarg);
  47  const OSSL_PARAM *OP_keymgmt_export_types(int selection);
  48
  49  /* Key object copy */
  50  int OP_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection);
  51
  52  /* Key object validation */
  53  int OP_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_get_{name}>.
  78 For example, the "function" OP_keymgmt_new() has these:
  79
  80  typedef void *(OSSL_OP_keymgmt_new_fn)(void *provctx);
  81  static ossl_inline OSSL_OP_keymgmt_new_fn
  82      OSSL_get_OP_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_numbers.h(7)>, as follows:
  86
  87  OP_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
  88  OP_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE
  89
  90  OP_keymgmt_gen_init             OSSL_FUNC_KEYMGMT_GEN_INIT
  91  OP_keymgmt_gen_set_template     OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE
  92  OP_keymgmt_gen_set_params       OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS
  93  OP_keymgmt_gen_settable_params  OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS
  94  OP_keymgmt_gen                  OSSL_FUNC_KEYMGMT_GEN
  95  OP_keymgmt_gen_cleanup          OSSL_FUNC_KEYMGMT_GEN_CLEANUP
  96
  97  OP_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
  98  OP_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
  99  OP_keymgmt_set_params           OSSL_FUNC_KEYMGMT_SET_PARAMS
 100  OP_keymgmt_settable_params      OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
 101
 102  OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
 103
 104  OP_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
 105  OP_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
 106  OP_keymgmt_match                OSSL_FUNC_KEYMGMT_MATCH
 107
 108  OP_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
 109  OP_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
 110  OP_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
 111  OP_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
 112
 113  OP_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 OP_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 OP_keymgmt_free() should free the passed I<keydata>.
 209
 210 OP_keymgmt_gen_init(), OP_keymgmt_gen_set_template(),
 211 OP_keymgmt_gen_set_params(), OP_keymgmt_gen_settable_params(),
 212 OP_keymgmt_gen() and OP_keymgmt_gen_cleanup() work together as a more
 213 elaborate context based key object constructor.
 214
 215 OP_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 OP_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 OP_keymgmt_gen_set_params() should set additional parameters from
 227 I<params> in the key object generation context I<genctx>.
 228
 229 OP_keymgmt_gen_settable_params() should return a constant array of
 230 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_gen_set_params()
 231 can handle.
 232
 233 OP_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 OP_keymgmt_gen_cleanup() should clean up and free the key object
 239 generation context I<genctx>
 240
 241 At least one of OP_keymgmt_new() and OP_keymgmt_gen() are mandatory,
 242 as well as OP_keymgmt_free().  Additionally, if OP_keymgmt_gen() is
 243 present, OP_keymgmt_gen_init() and OP_keymgmt_gen_cleanup() must be
 244 present as well.
 245
 246 =head2 Key Object Information Functions
 247
 248 OP_keymgmt_get_params() should extract information data associated
 249 with the given I<keydata>, see L</Information Parameters>.
 250
 251 OP_keymgmt_gettable_params() should return a constant array of
 252 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
 253 can handle.
 254
 255 If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
 256 must also be present, and vice versa.
 257
 258 OP_keymgmt_set_params() should update information data associated
 259 with the given I<keydata>, see L</Information Parameters>.
 260
 261 OP_keymgmt_settable_params() should return a constant array of
 262 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params()
 263 can handle.
 264
 265 If OP_keymgmt_settable_params() is present, OP_keymgmt_set_params()
 266 must also be present, and vice versa.
 267
 268 =head2 Key Object Checking Functions
 269
 270 OP_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 OP_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 OP_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 OP_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 OP_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 OP_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 OP_keymgmt_import_types() should return a constant array of descriptor
 307 B<OSSL_PARAM> for data indicated by I<selection>, for parameters that
 308 OP_keymgmt_import() can handle.
 309
 310 OP_keymgmt_export_types() should return a constant array of descriptor
 311 B<OSSL_PARAM> for data indicated by I<selection>, that the
 312 OP_keymgmt_export() callback can expect to receive.
 313
 314 OP_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 Built-in RSA Import/Export Types
 320
 321 The following Import/Export types are available for the built-in RSA algorithm:
 322
 323 =over 4
 324
 325 =item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer>
 326
 327 The RSA "n" value.
 328
 329 =item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
 330
 331 The RSA "e" value.
 332
 333 =item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer>
 334
 335 The RSA "d" value.
 336
 337 =item "rsa-factor" (B<OSSL_PKEY_PARAM_RSA_FACTOR>) <unsigned integer>
 338
 339 An RSA factor. In 2 prime RSA these are often known as "p" or "q". This value
 340 may be repeated up to 10 times in a single key.
 341
 342 =item "rsa-exponent" (B<OSSL_PKEY_PARAM_RSA_EXPONENT>) <unsigned integer>
 343
 344 An RSA CRT (Chinese Remainder Theorem) exponent. This value may be repeated up
 345 to 10 times in a single key.
 346
 347 =item "rsa-coefficient" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT>) <unsigned integer>
 348
 349 An RSA CRT (Chinese Remainder Theorem) coefficient. This value may be repeated
 350 up to 9 times in a single key.
 351
 352 =back
 353
 354 =head2 Built-in DSA and Diffie-Hellman Import/Export Types
 355
 356 The following Import/Export types are available for the built-in DSA and
 357 Diffie-Hellman algorithms:
 358
 359 =over 4
 360
 361 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
 362
 363 The public key value.
 364
 365 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
 366
 367 The private key value.
 368
 369 =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
 370
 371 A DSA or Diffie-Hellman "p" value.
 372
 373 =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
 374
 375 A DSA or Diffie-Hellman "q" value.
 376
 377 =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
 378
 379 A DSA or Diffie-Hellman "g" value.
 380
 381 =back
 382
 383 =head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types
 384
 385 The following Import/Export types are available for the built-in X25519, X448,
 386 ED25519 and X448 algorithms:
 387
 388 =over 4
 389
 390 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
 391
 392 The public key value.
 393
 394 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
 395
 396 The private key value.
 397
 398 =back
 399
 400 =head2 Built-in EC Import/Export Types
 401
 402 The following Import/Export types are available for the built-in EC algorithm:
 403
 404 =over 4
 405
 406 =item "curve-name" (B<OSSL_PKEY_PARAM_EC_NAME>) <utf8 string>
 407
 408 The EC curve name.
 409
 410 =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
 411
 412 Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
 413 if the value is zero. The cofactor variant multiplies the shared secret by the
 414 EC curve's cofactor (note for some curves the cofactor is 1).
 415
 416 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
 417
 418 The public key value in EC point format.
 419
 420 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
 421
 422 The private key value.
 423
 424 =back
 425
 426 =head2 Information Parameters
 427
 428 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 429
 430 Parameters currently recognised by built-in keymgmt algorithms
 431 are as follows.
 432 Not all parameters are relevant to, or are understood by all keymgmt
 433 algorithms:
 434
 435 =over 4
 436
 437 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
 438
 439 The value should be the cryptographic length of the cryptosystem to
 440 which the key belongs, in bits.  The definition of cryptographic
 441 length is specific to the key cryptosystem.
 442
 443 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
 444
 445 The value should be the maximum size that a caller should allocate to
 446 safely store a signature (called I<sig> in L<provider-signature(7)>),
 447 the result of asymmmetric encryption / decryption (I<out> in
 448 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
 449 L<provider-keyexch(7)>, and similar data).
 450
 451 Because an EVP_KEYMGMT method is always tightly bound to another method
 452 (signature, asymmetric cipher, key exchange, ...) and must be of the
 453 same provider, this number only needs to be synchronised with the
 454 dimensions handled in the rest of the same provider.
 455
 456 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
 457
 458 The value should be the number of security bits of the given key.
 459 Bits of security is defined in SP800-57.
 460
 461 =item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>,
 462 B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
 463
 464 The value should be either 1 or 0, to respectively enable or disable
 465 use of the cofactor in operations using this key.
 466
 467 In the context of a key that can be used to perform an Elliptic Curve
 468 Diffie-Hellman key exchange, this parameter can be used to mark a requirement
 469 for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange
 470 algorithm.
 471
 472 See also L<provider-keyexch(7)> for the related
 473 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
 474 per-operation basis.
 475
 476 =back
 477
 478 =head1 RETURN VALUES
 479
 480 OP_keymgmt_new() should return a valid reference to the newly created provider
 481 side key object, or NULL on failure.
 482
 483 OP_keymgmt_import(), OP_keymgmt_export(), OP_keymgmt_get_params() and
 484 OP_keymgmt_set_params() should return 1 for success or 0 on error.
 485
 486 OP_keymgmt_validate() should return 1 on successful validation, or 0 on
 487 failure.
 488
 489 OP_keymgmt_has() should return 1 if all the selected data subsets are contained
 490 in the given I<keydata> or 0 otherwise.
 491
 492 OP_keymgmt_query_operation_name() should return a pointer to a string matching
 493 the requested operation, or NULL if the same name used to fetch the keymgmt
 494 applies.
 495
 496 OP_keymgmt_gettable_params() and OP_keymgmt_settable_params()
 497 OP_keymgmt_import_types(), OP_keymgmt_export_types()
 498 should
 499 always return a constant B<OSSL_PARAM> array.
 500
 501 =head1 SEE ALSO
 502
 503 L<provider(7)>
 504
 505 =head1 HISTORY
 506
 507 The KEYMGMT interface was introduced in OpenSSL 3.0.
 508
 509 =head1 COPYRIGHT
 510
 511 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 512
 513 Licensed under the Apache License 2.0 (the "License").  You may not use
 514 this file except in compliance with the License.  You can obtain a copy
 515 in the file LICENSE in the source distribution or at
 516 L<https://www.openssl.org/source/license.html>.
 517
 518 =cut