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