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