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