doc/internal/man3/OSSL_METHOD_STORE.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_METHOD_STORE, ossl_method_store_new, ossl_method_store_free,
   6 ossl_method_store_init, ossl_method_store_cleanup,
   7 ossl_method_store_add, ossl_method_store_fetch,
   8 ossl_method_store_remove, ossl_method_store_remove_all_provided,
   9 ossl_method_store_cache_get, ossl_method_store_cache_set,
  10 ossl_method_store_cache_flush_all
  11 - implementation method store and query
  12
  13 =head1 SYNOPSIS
  14
  15  #include "internal/property.h"
  16
  17  typedef struct ossl_method_store_st OSSL_METHOD_STORE;
  18
  19  OSSL_METHOD_STORE *ossl_method_store_new(OSSL_LIB_CTX *ctx);
  20  void ossl_method_store_free(OSSL_METHOD_STORE *store);
  21  int ossl_method_store_init(OSSL_LIB_CTX *ctx);
  22  void ossl_method_store_cleanup(OSSL_LIB_CTX *ctx);
  23  int ossl_method_store_add(OSSL_METHOD_STORE *store, const OSSL_PROVIDER *prov,
  24                            int nid, const char *properties, void *method,
  25                            int (*method_up_ref)(void *),
  26                            void (*method_destruct)(void *));
  27  int ossl_method_store_remove(OSSL_METHOD_STORE *store,
  28                               int nid, const void *method);
  29  int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
  30                              int nid, const char *properties,
  31                              void **method, const OSSL_PROVIDER **prov_rw);
  32  int ossl_method_store_remove_all_provided(OSSL_METHOD_STORE *store,
  33                                            const OSSL_PROVIDER *prov);
  34
  35  int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, OSSL_PROVIDER *prov,
  36                                  int nid, const char *prop_query, void **method);
  37  int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, OSSL_PROVIDER *prov,
  38                                  int nid, const char *prop_query, void *method,
  39                                  int (*method_up_ref)(void *),
  40                                  void (*method_destruct)(void *));
  41  void ossl_method_store_cache_flush_all(OSSL_METHOD_STORE *store);
  42
  43 =head1 DESCRIPTION
  44
  45 OSSL_METHOD_STORE stores methods that can be queried using properties and a
  46 numeric identity (nid).
  47
  48 Methods are expected to be library internal structures.
  49 It's left to the caller to define the exact contents.
  50
  51 Numeric identities are expected to be an algorithm identity for the methods.
  52 It's left to the caller to define exactly what an algorithm is, and to allocate
  53 these numeric identities accordingly.
  54
  55 The B<OSSL_METHOD_STORE> also holds an internal query cache, which is accessed
  56 separately (see L</Cache Functions> below).
  57
  58 =head2 Store Functions
  59
  60 ossl_method_store_init() initialises the method store subsystem in the scope of
  61 the library context I<ctx>.
  62
  63 ossl_method_store_cleanup() cleans up and shuts down the implementation method
  64 store subsystem in the scope of the library context I<ctx>.
  65
  66 ossl_method_store_new() create a new empty method store using the supplied
  67 I<ctx> to allow access to the required underlying property data.
  68
  69 ossl_method_store_free() frees resources allocated to I<store>.
  70
  71 ossl_method_store_add() adds the I<method> constructed from an implementation in
  72 the provider I<prov> to the I<store> as an instance of an algorithm indicated by
  73 I<nid> and the property definition I<properties>, unless the I<store> already
  74 has a method from the same provider with the same I<nid> and I<properties>.
  75 If the I<method_up_ref> function is given, it's called to increment the
  76 reference count of the method.
  77 If the I<method_destruct> function is given, it's called when this function
  78 fails to add the method to the store, or later on when it is being released from
  79 the I<store>.
  80
  81 ossl_method_store_remove() removes the I<method> identified by I<nid> from the
  82 I<store>.
  83
  84 ossl_method_store_fetch() queries I<store> for a method identified by I<nid>
  85 that matches the property query I<prop_query>.
  86 I<*prop> may be a pointer to a provider, which will narrow the search
  87 to methods from that provider.
  88 The result, if any, is returned in I<*method>, and its provider in I<*prov>.
  89
  90 ossl_method_store_remove_all_provided() removes all methods from I<store>
  91 that are provided by I<prov>.
  92 When doing so, it also flushes the corresponding cache entries.
  93
  94 =head2 Cache Functions
  95
  96 ossl_method_store_cache_get() queries the cache associated with the I<store>
  97 for a method identified by I<nid> that matches the property query
  98 I<prop_query>.
  99 Additionally, if I<prov> isn't NULL, it will be used to narrow the search
 100 to only include methods from that provider.
 101 The result, if any, is returned in I<method>.
 102
 103 ossl_method_store_cache_set() sets a cache entry identified by I<nid> from the
 104 provider I<prov>, with the property query I<prop_query> in the I<store>.
 105 Future calls to ossl_method_store_cache_get() will return the specified I<method>.
 106 The I<method_up_ref> function is called to increment the
 107 reference count of the method and the I<method_destruct> function is called
 108 to decrement it.
 109
 110 ossl_method_store_cache_flush_all() flushes all cached entries associated with
 111 I<store>.
 112
 113 =head1 NOTES
 114
 115 The I<prop_query> argument to ossl_method_store_cache_get() and
 116 ossl_method_store_cache_set() is not allowed to be NULL.  Use "" for an
 117 empty property definition or query.
 118
 119 =head1 RETURN VALUES
 120
 121 ossl_method_store_new() returns a new method store object or NULL on failure.
 122
 123 ossl_method_store_free(), ossl_method_store_add(),
 124 ossl_method_store_remove(), ossl_method_store_fetch(),
 125 ossl_method_store_cache_get(), ossl_method_store_cache_set() and
 126 ossl_method_store_flush_cache() return B<1> on success and B<0> on error.
 127
 128 ossl_method_store_free() and ossl_method_store_cleanup() do not return any value.
 129
 130 =head1 HISTORY
 131
 132 This functionality was added to OpenSSL 3.0.
 133
 134 =head1 COPYRIGHT
 135
 136 Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
 137 Copyright (c) 2019, Oracle and/or its affiliates.  All rights reserved.
 138
 139 Licensed under the Apache License 2.0 (the "License").  You may not use this
 140 file except in compliance with the License.  You can obtain a copy in the file
 141 LICENSE in the source distribution or at
 142 L<https://www.openssl.org/source/license.html>.
 143
 144 =cut