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