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 creation and destruction */
  30  void *OP_keymgmt_importkey(void *provctx, const OSSL_PARAM params[]);
  31  void *OP_keymgmt_genkey(void *provctx,
  32                          void *domparams, const OSSL_PARAM genkeyparams[]);
  33  void *OP_keymgmt_loadkey(void *provctx, void *id, size_t idlen);
  34  void OP_keymgmt_freekey(void *key);
  35
  36  /* Key export */
  37  int OP_keymgmt_exportkey(void *key, OSSL_PARAM params[]);
  38
  39  /* Key discovery */
  40  const OSSL_PARAM *OP_keymgmt_importkey_types(void);
  41  const OSSL_PARAM *OP_keymgmt_exportkey_types(void);
  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 domain parameters and keys for the OpenSSL library
  55 EVP_PKEY structure.
  56
  57 All "functions" mentioned here are passed as function pointers between
  58 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
  59 B<OSSL_ALGORITHM> arrays that are returned by the provider's
  60 provider_query_operation() function
  61 (see L<provider-base(7)/Provider Functions>).
  62
  63 All these "functions" have a corresponding function type definition
  64 named B<OSSL_{name}_fn>, and a helper function to retrieve the
  65 function pointer from a B<OSSL_DISPATCH> element named
  66 B<OSSL_get_{name}>.
  67 For example, the "function" OP_keymgmt_importdomparams() has these:
  68
  69  typedef void *
  70      (OSSL_OP_keymgmt_importdomparams_fn)(void *provctx,
  71                                           const OSSL_PARAM params[]);
  72  static ossl_inline OSSL_OP_keymgmt_importdomparams_fn
  73      OSSL_get_OP_keymgmt_importdomparams(const OSSL_DISPATCH *opf);
  74
  75 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
  76 macros in L<openssl-core_numbers.h(7)>, as follows:
  77
  78  OP_keymgmt_importdomparams      OSSL_FUNC_KEYMGMT_IMPORTDOMPARAMS
  79  OP_keymgmt_gendomparams         OSSL_FUNC_KEYMGMT_GENDOMPARAMS
  80  OP_keymgmt_freedomparams        OSSL_FUNC_KEYMGMT_FREEDOMPARAMS
  81  OP_keymgmt_exportdomparams      OSSL_FUNC_KEYMGMT_EXPORTDOMPARAMS
  82  OP_keymgmt_importdomparam_types OSSL_FUNC_KEYMGMT_IMPORTDOMPARAM_TYPES
  83  OP_keymgmt_exportdomparam_types OSSL_FUNC_KEYMGMT_EXPORTDOMPARAM_TYPES
  84
  85  OP_keymgmt_importkey            OSSL_FUNC_KEYMGMT_IMPORTKEY
  86  OP_keymgmt_genkey               OSSL_FUNC_KEYMGMT_GENKEY
  87  OP_keymgmt_loadkey              OSSL_FUNC_KEYMGMT_LOADKEY
  88  OP_keymgmt_freekey              OSSL_FUNC_KEYMGMT_FREEKEY
  89  OP_keymgmt_exportkey            OSSL_FUNC_KEYMGMT_EXPORTKEY
  90  OP_keymgmt_importkey_types      OSSL_FUNC_KEYMGMT_IMPORTKEY_TYPES
  91  OP_keymgmt_exportkey_types      OSSL_FUNC_KEYMGMT_EXPORTKEY_TYPES
  92
  93 =head2 Domain Parameter Functions
  94
  95 OP_keymgmt_importdomparams() should create a provider side structure
  96 for domain parameters, with values taken from the passed B<OSSL_PARAM>
  97 array I<params>.
  98
  99 OP_keymgmt_gendomparams() should generate domain parameters and create
 100 a provider side structure for them.
 101 Values of the passed B<OSSL_PARAM> array I<params> should be used as
 102 input for parameter generation.
 103
 104 OP_keymgmt_freedomparams() should free the passed provider side domain
 105 parameter structure I<domparams>.
 106
 107 OP_keymgmt_exportdomparams() should extract values from the passed
 108 provider side domain parameter structure I<domparams> into the passed
 109 B<OSSL_PARAM> I<params>.
 110 Only the values specified in I<params> should be extracted.
 111
 112 OP_keymgmt_importdomparam_types() should return a constant array of
 113 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams()
 114 can handle.
 115
 116 =for comment There should be one corresponding to OP_keymgmt_gendomparams()
 117 as well...
 118
 119 OP_keymgmt_exportdomparam_types() should return a constant array of
 120 descriptor B<OSSL_PARAM>, for parameters that can be exported with
 121 OP_keymgmt_exportdomparams().
 122
 123 =head2 Key functions
 124
 125 OP_keymgmt_importkey() should create a provider side structure
 126 for keys, with values taken from the passed B<OSSL_PARAM> array
 127 I<params>.
 128
 129 OP_keymgmt_genkey() should generate keys and create a provider side
 130 structure for them.
 131 Values from the passed domain parameters I<domparams> as well as from
 132 the passed B<OSSL_PARAM> array I<params> should be used as input for
 133 key generation.
 134
 135 OP_keymgmt_loadkey() should return a provider side key structure with
 136 a key loaded from a location known only to the provider, identitified
 137 with the identity I<id> of size I<idlen>.
 138 This identity is internal to the provider and is retrieved from the
 139 provider through other means.
 140
 141 =for comment Right now, OP_keymgmt_loadkey is useless, but will be
 142 useful as soon as we have a OSSL_STORE interface
 143
 144 OP_keymgmt_freekey() should free the passed I<key>.
 145
 146 OP_keymgmt_exportkey() should extract values from the passed
 147 provider side key I<key> into the passed B<OSSL_PARAM> I<params>.
 148 Only the values specified in I<params> should be extracted.
 149
 150 OP_keymgmt_importkey_types() should return a constant array of
 151 descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey()
 152 can handle.
 153
 154 =for comment There should be one corresponding to OP_keymgmt_genkey()
 155 as well...
 156
 157 OP_keymgmt_exportkey_types() should return a constant array of
 158 descriptor B<OSSL_PARAM>, for parameters that can be exported with
 159 OP_keymgmt_exportkeys().
 160
 161 =head1 SEE ALSO
 162
 163 L<provider(7)>
 164
 165 =head1 HISTORY
 166
 167 The KEYMGMT interface was introduced in OpenSSL 3.0.
 168
 169 =head1 COPYRIGHT
 170
 171 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 172
 173 Licensed under the Apache License 2.0 (the "License").  You may not use
 174 this file except in compliance with the License.  You can obtain a copy
 175 in the file LICENSE in the source distribution or at
 176 L<https://www.openssl.org/source/license.html>.
 177
 178 =cut