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