doc/man7/provider-storemgmt.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 provider-storemgmt - The OSSL_STORE library E<lt>-E<gt> provider functions
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/core_dispatch.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  void *OSSL_FUNC_store_open(void *provctx, const char *uri);
  18  void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
  19  const OSSL_PARAM *store_settable_ctx_params(void *provctx);
  20  int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
  21  int OSSL_FUNC_store_load(void *loaderctx,
  22                           OSSL_CALLBACK *object_cb, void *object_cbarg,
  23                           OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
  24  int OSSL_FUNC_store_eof(void *loaderctx);
  25  int OSSL_FUNC_store_close(void *loaderctx);
  26
  27  int OSSL_FUNC_store_export_object
  28      (void *loaderctx, const void *objref, size_t objref_sz,
  29       OSSL_CALLBACK *export_cb, void *export_cbarg);
  30
  31 =head1 DESCRIPTION
  32
  33 The STORE operation is the provider side of the L<ossl_store(7)> API.
  34
  35 The primary responsibility of the STORE operation is to load all sorts
  36 of objects from a container indicated by URI.  These objects are given
  37 to the OpenSSL library in provider-native object abstraction form (see
  38 L<provider-object(7)>).  The OpenSSL library is then responsible for
  39 passing on that abstraction to suitable provided functions.
  40
  41 Examples of functions that the OpenSSL library can pass the abstraction to
  42 include OSSL_FUNC_keymgmt_load() (L<provider-keymgmt(7)>),
  43 OSSL_FUNC_store_export_object() (which exports the object in parameterized
  44 form).
  45
  46 All "functions" mentioned here are passed as function pointers between
  47 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
  48 B<OSSL_ALGORITHM> arrays that are returned by the provider's
  49 provider_query_operation() function
  50 (see L<provider-base(7)/Provider Functions>).
  51
  52 All these "functions" have a corresponding function type definition named
  53 B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer
  54 from a B<OSSL_DISPATCH> element named B<OSSL_get_{name}>.
  55 For example, the "function" OSSL_FUNC_store_load() has these:
  56
  57  typedef void *(OSSL_OSSL_FUNC_store_load_fn)(void *provctx,
  58                                               const OSSL_PARAM params[]);
  59  static ossl_inline OSSL_OSSL_FUNC_store_load_fn
  60      OSSL_OSSL_FUNC_store_load(const OSSL_DISPATCH *opf);
  61
  62 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros
  63 in L<openssl-core_dispatch.h(7)>, as follows:
  64
  65  OSSL_FUNC_store_open                 OSSL_FUNC_STORE_OPEN
  66  OSSL_FUNC_store_attach               OSSL_FUNC_STORE_ATTACH
  67  OSSL_FUNC_store_settable_ctx_params  OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
  68  OSSL_FUNC_store_set_ctx_params       OSSL_FUNC_STORE_SET_CTX_PARAMS
  69  OSSL_FUNC_store_load                 OSSL_FUNC_STORE_LOAD
  70  OSSL_FUNC_store_eof                  OSSL_FUNC_STORE_EOF
  71  OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
  72  OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
  73
  74 =head2 Functions
  75
  76 OSSL_FUNC_store_open() should create a provider side context with data based
  77 on the input I<uri>.  The implementation is entirely responsible for the
  78 interpretation of the URI.
  79
  80 OSSL_FUNC_store_attach() should create a provider side context with the core
  81 B<BIO> I<bio> attached.  This is an alternative to using a URI to find storage,
  82 supporting L<OSSL_STORE_attach(3)>.
  83
  84 OSSL_FUNC_store_settable_ctx_params() should return a constant array of
  85 descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_store_set_ctx_params()
  86 can handle.
  87
  88 OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what
  89 kind of data to expect, search criteria, and so on.  More on those below, in
  90 L</Load Parameters>.  Whether unrecognised parameters are an error or simply
  91 ignored is at the implementation's discretion.
  92
  93 OSSL_FUNC_store_load() loads the next object from the URI opened by
  94 OSSL_FUNC_store_open(), creates an object abstraction for it (see
  95 L<provider-object(7)>), and calls I<object_cb> with it as well as
  96 I<object_cbarg>.  I<object_cb> will then interpret the object abstraction
  97 and do what it can to wrap it or decode it into an OpenSSL structure.  In
  98 case a passphrase needs to be prompted to unlock an object, I<pw_cb> should
  99 be called.
 100
 101 OSSL_FUNC_store_eof() indicates if the end of the set of objects from the
 102 URI has been reached.  When that happens, there's no point trying to do any
 103 further loading.
 104
 105 OSSL_FUNC_store_close() frees the provider side context I<ctx>.
 106
 107 =head2 Load Parameters
 108
 109 =over 4
 110
 111 =item "expect" (B<OSSL_STORE_PARAM_EXPECT>) <integer>
 112
 113 Is a hint of what type of data the OpenSSL library expects to get.
 114 This is only useful for optimization, as the library will check that the
 115 object types match the expectation too.
 116
 117 The number that can be given through this parameter is found in
 118 F<< <openssl/store.h> >>, with the macros having names starting with
 119 C<OSSL_STORE_INFO_>.  These are further described in
 120 L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>.
 121
 122 =item "subject" (B<OSSL_STORE_PARAM_SUBJECT>) <octet string>
 123
 124 Indicates that the caller wants to search for an object with the given
 125 subject associated.  This can be used to select specific certificates
 126 by subject.
 127
 128 The contents of the octet string is expected to be in DER form.
 129
 130 =item "issuer" (B<OSSL_STORE_PARAM_ISSUER>) <octet string>
 131
 132 Indicates that the caller wants to search for an object with the given
 133 issuer associated.  This can be used to select specific certificates
 134 by issuer.
 135
 136 The contents of the octet string is expected to be in DER form.
 137
 138 =item "serial" (B<OSSL_STORE_PARAM_SERIAL>) <integer>
 139
 140 Indicates that the caller wants to search for an object with the given
 141 serial number associated.
 142
 143 =item "digest" (B<OSSL_STORE_PARAM_DIGEST>) <utf8 string>
 144
 145 =item "fingerprint" (B<OSSL_STORE_PARAM_FINGERPRINT>) <octet string>
 146
 147 Indicates that the caller wants to search for an object with the given
 148 fingerprint, computed with the given digest.
 149
 150 =item "alias" (B<OSSL_STORE_PARAM_ALIAS>) <utf8 string>
 151
 152 Indicates that the caller wants to search for an object with the given
 153 alias (some call it a "friendly name").
 154
 155 =back
 156
 157 Several of these search criteria may be combined.  For example, to
 158 search for a certificate by issuer+serial, both the "issuer" and the
 159 "serial" parameters will be given.
 160
 161 =head1 SEE ALSO
 162
 163 L<provider(7)>
 164
 165 =head1 HISTORY
 166
 167 The STORE interface was introduced in OpenSSL 3.0.
 168
 169 =head1 COPYRIGHT
 170
 171 Copyright 2020 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