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 domain parameter creation and destruction */
  18  void *OP_keymgmt_importdomparams(void *provctx, const OSSL_PARAM params[]);
  19  void *OP_keymgmt_gendomparams(void *provctx, const OSSL_PARAM params[]);
  20  void OP_keymgmt_freedomparams(void *domparams);
  21
  22  /* Key domain parameter export */
  23  int OP_keymgmt_exportdomparams(void *domparams, OSSL_PARAM params[]);
  24
  25  /* Key domain parameter discovery */
  26  const OSSL_PARAM *OP_keymgmt_importdomparam_types(void);
  27  const OSSL_PARAM *OP_keymgmt_exportdomparam_types(void);
  28
  29  /* Key domain parameter information */
  30  int OP_keymgmt_get_domparam_params(void *domparams, OSSL_PARAM params[]);
  31  const OSSL_PARAM *OP_keymgmt_gettable_domparam_params(void);
  32
  33  /* Key domain parameter validation */
  34  int OP_keymgmt_validate_domparams(void *key);
  35
  36  /* Key creation and destruction */
  37  void *OP_keymgmt_importkey(void *provctx, const OSSL_PARAM params[]);
  38  void *OP_keymgmt_genkey(void *provctx,
  39                          void *domparams, const OSSL_PARAM genkeyparams[]);
  40  void *OP_keymgmt_loadkey(void *provctx, void *id, size_t idlen);
  41  void OP_keymgmt_freekey(void *key);
  42
  43  /* Key export */
  44  int OP_keymgmt_exportkey(void *key, OSSL_PARAM params[]);
  45
  46  /* Key discovery */
  47  const OSSL_PARAM *OP_keymgmt_importkey_types(void);
  48  const OSSL_PARAM *OP_keymgmt_exportkey_types(void);
  49
  50  /* Key information */
  51  int OP_keymgmt_get_key_params(void *key, OSSL_PARAM params[]);
  52  const OSSL_PARAM *OP_keymgmt_gettable_key_params(void);
  53
  54  /* Key validation */
  55  int OP_keymgmt_validate_public(void *key);
  56  int OP_keymgmt_validate_private(void *key);
  57  int OP_keymgmt_validate_pairwise(void *key);
  58
  59  /* Discovery of supported operations */
  60  const char *OP_keymgmt_query_operation_name(int operation_id);
  61
  62 =head1 DESCRIPTION
  63
  64 The KEYMGMT operation doesn't have much public visibility in OpenSSL
  65 libraries, it's rather an internal operation that's designed to work
  66 in tandem with operations that use private/public key pairs.
  67
  68 Because the KEYMGMT operation shares knowledge with the operations it
  69 works with in tandem, they must belong to the same provider.
  70 The OpenSSL libraries will ensure that they do.
  71
  72 The primary responsibility of the KEYMGMT operation is to hold the
  73 provider side domain parameters and keys for the OpenSSL library
  74 EVP_PKEY structure.
  75
  76 All "functions" mentioned here are passed as function pointers between
  77 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
  78 B<OSSL_ALGORITHM> arrays that are returned by the provider's
  79 provider_query_operation() function
  80 (see L<provider-base(7)/Provider Functions>).
  81
  82 All these "functions" have a corresponding function type definition
  83 named B<OSSL_{name}_fn>, and a helper function to retrieve the
  84 function pointer from a B<OSSL_DISPATCH> element named
  85 B<OSSL_get_{name}>.
  86 For example, the "function" OP_keymgmt_importdomparams() has these:
  87
  88  typedef void *
  89      (OSSL_OP_keymgmt_importdomparams_fn)(void *provctx,
  90                                           const OSSL_PARAM params[]);
  91  static ossl_inline OSSL_OP_keymgmt_importdomparams_fn
  92      OSSL_get_OP_keymgmt_importdomparams(const OSSL_DISPATCH *opf);
  93
  94 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
  95 macros in L<openssl-core_numbers.h(7)>, as follows:
  96
  97  OP_keymgmt_importdomparams      OSSL_FUNC_KEYMGMT_IMPORTDOMPARAMS
  98  OP_keymgmt_gendomparams         OSSL_FUNC_KEYMGMT_GENDOMPARAMS
  99  OP_keymgmt_freedomparams        OSSL_FUNC_KEYMGMT_FREEDOMPARAMS
 100  OP_keymgmt_exportdomparams      OSSL_FUNC_KEYMGMT_EXPORTDOMPARAMS
 101  OP_keymgmt_importdomparam_types OSSL_FUNC_KEYMGMT_IMPORTDOMPARAM_TYPES
 102  OP_keymgmt_exportdomparam_types OSSL_FUNC_KEYMGMT_EXPORTDOMPARAM_TYPES
 103  OP_keymgmt_get_domparam_params  OSSL_FUNC_KEYMGMT_GET_DOMPARAM_PARAMS
 104  OP_keymgmt_gettable_domparam_params
 105                                  OSSL_FUNC_KEYMGMT_GETTABLE_DOMPARAM_PARAMS
 106
 107  OP_keymgmt_importkey            OSSL_FUNC_KEYMGMT_IMPORTKEY
 108  OP_keymgmt_genkey               OSSL_FUNC_KEYMGMT_GENKEY
 109  OP_keymgmt_loadkey              OSSL_FUNC_KEYMGMT_LOADKEY
 110  OP_keymgmt_freekey              OSSL_FUNC_KEYMGMT_FREEKEY
 111  OP_keymgmt_exportkey            OSSL_FUNC_KEYMGMT_EXPORTKEY
 112  OP_keymgmt_importkey_types      OSSL_FUNC_KEYMGMT_IMPORTKEY_TYPES
 113  OP_keymgmt_exportkey_types      OSSL_FUNC_KEYMGMT_EXPORTKEY_TYPES
 114  OP_keymgmt_get_key_params       OSSL_FUNC_KEYMGMT_GET_KEY_PARAMS
 115  OP_keymgmt_gettable_key_params  OSSL_FUNC_KEYMGMT_GETTABLE_KEY_PARAMS
 116
 117  OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
 118
 119  OP_keymgmt_validate_domparams   OSSL_FUNC_KEYMGMT_VALIDATE_DOMPARAMS
 120  OP_keymgmt_validate_public      OSSL_FUNC_KEYMGMT_VALIDATE_PUBLIC
 121  OP_keymgmt_validate_private     OSSL_FUNC_KEYMGMT_VALIDATE_PRIVATE
 122  OP_keymgmt_validate_pairwise    OSSL_FUNC_KEYMGMT_VALIDATE_PAIRWISE
 123
 124 =head2 Domain Parameter Functions
 125
 126 OP_keymgmt_importdomparams() should create a provider side structure
 127 for domain parameters, with values taken from the passed B<OSSL_PARAM>
 128 array I<params>.
 129
 130 OP_keymgmt_gendomparams() should generate domain parameters and create
 131 a provider side structure for them.
 132 Values of the passed B<OSSL_PARAM> array I<params> should be used as
 133 input for parameter generation.
 134
 135 OP_keymgmt_freedomparams() should free the passed provider side domain
 136 parameter structure I<domparams>.
 137
 138 OP_keymgmt_exportdomparams() should extract values from the passed
 139 provider side domain parameter structure I<domparams> into the passed
 140 B<OSSL_PARAM> I<params>.
 141 Only the values specified in I<params> should be extracted.
 142
 143 OP_keymgmt_importdomparam_types() should return a constant array of
 144 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams()
 145 can handle.
 146
 147 OP_keymgmt_exportdomparam_types() should return a constant array of
 148 descriptor B<OSSL_PARAM>, for parameters that can be exported with
 149 OP_keymgmt_exportdomparams().
 150
 151 OP_keymgmt_get_domparam_params() should extract information data
 152 associated with the given I<domparams>,
 153 see L</Information Parameters>.
 154
 155 OP_keymgmt_gettable_domparam_params() should return a constant array
 156 of descriptor B<OSSL_PARAM>, for parameters that
 157 OP_keymgmt_get_domparam_params() can handle.
 158
 159 OP_keymgmt_validate_domparams() should return a value of 1 if the
 160 domain parameters are valid, or 0 for invalid.
 161
 162 =head2 Key functions
 163
 164 OP_keymgmt_importkey() should create a provider side structure
 165 for keys, with values taken from the passed B<OSSL_PARAM> array
 166 I<params>.
 167
 168 OP_keymgmt_genkey() should generate keys and create a provider side
 169 structure for them.
 170 Values from the passed domain parameters I<domparams> as well as from
 171 the passed B<OSSL_PARAM> array I<params> should be used as input for
 172 key generation.
 173
 174 OP_keymgmt_loadkey() should return a provider side key structure with
 175 a key loaded from a location known only to the provider, identitified
 176 with the identity I<id> of size I<idlen>.
 177 This identity is internal to the provider and is retrieved from the
 178 provider through other means.
 179
 180 =for comment Right now, OP_keymgmt_loadkey is useless, but will be
 181 useful as soon as we have a OSSL_STORE interface
 182
 183 OP_keymgmt_freekey() should free the passed I<key>.
 184
 185 OP_keymgmt_exportkey() should extract values from the passed
 186 provider side key I<key> into the passed B<OSSL_PARAM> I<params>.
 187 Only the values specified in I<params> should be extracted.
 188
 189 OP_keymgmt_importkey_types() should return a constant array of
 190 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey()
 191 can handle.
 192
 193 OP_keymgmt_exportkey_types() should return a constant array of
 194 descriptor B<OSSL_PARAM>, for parameters that can be exported with
 195 OP_keymgmt_exportkeys().
 196
 197 OP_keymgmt_get_key_params() should extract information data associated
 198 with the given I<key>, see L</Information Parameters>.
 199
 200 OP_keymgmt_gettable_key_params() should return a constant array of
 201 descriptor B<OSSL_PARAM>, for parameters that
 202 OP_keymgmt_get_key_params() can handle.
 203
 204 OP_keymgmt_validate_public() should return 1 if the public component of the
 205 key is valid, or 0 if invalid.
 206 OP_keymgmt_validate_private() should return 1 if the private component of the
 207 key is valid, or 0 if invalid.
 208 OP_keymgmt_validate_pairwise() should return 1 if the the pairwise consistency
 209 of the key is valid, or 0 if invalid.
 210
 211
 212 =head2 Supported operations
 213
 214 OP_keymgmt_query_operation_name() should return the name of the
 215 supported algorithm for the operation I<operation_id>.  This is
 216 similar to provider_query_operation() (see L<provider-base(7)>),
 217 but only works as an advisory.  If this function is not present, or
 218 returns NULL, the caller is free to assume that there's an algorithm
 219 from the same provider, of the same name as the one used to fetch the
 220 keymgmt and try to use that.
 221
 222 =head2 Information Parameters
 223
 224 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 225
 226 Parameters currently recognised by built-in keymgmt algorithms'
 227 OP_keymgmt_get_domparams_params() and OP_keymgmt_get_key_params()
 228 are:
 229
 230 =over 4
 231
 232 =item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer>
 233
 234 The value should be the cryptographic length of the cryptosystem to
 235 which the key belongs, in bits.  The definition of cryptographic
 236 length is specific to the key cryptosystem.
 237
 238 =item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer>
 239
 240 The value should be the maximum size that a caller should allocate to
 241 safely store a signature (called I<sig> in L<provider-signature(7)>),
 242 the result of asymmmetric encryption / decryption (I<out> in
 243 L<provider-asym_cipher(7)>, a derived secret (I<secret> in
 244 L<provider-keyexch(7)>, and similar data).
 245
 246 Because an EVP_KEYMGMT method is always tightly bound to another method
 247 (signature, asymmetric cipher, key exchange, ...) and must be of the
 248 same provider, this number only needs to be synchronised with the
 249 dimensions handled in the rest of the same provider.
 250
 251 =item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer>
 252
 253 The value should be the number of security bits of the given key.
 254 Bits of security is defined in SP800-57.
 255
 256 =back
 257
 258 =head1 SEE ALSO
 259
 260 L<provider(7)>
 261
 262 =head1 HISTORY
 263
 264 The KEYMGMT interface was introduced in OpenSSL 3.0.
 265
 266 =head1 COPYRIGHT
 267
 268 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 269
 270 Licensed under the Apache License 2.0 (the "License").  You may not use
 271 this file except in compliance with the License.  You can obtain a copy
 272 in the file LICENSE in the source distribution or at
 273 L<https://www.openssl.org/source/license.html>.
 274
 275 =cut