]>
Commit | Line | Data |
---|---|---|
1bdbdaff P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4ce738d0 RL |
5 | OSSL_METHOD_STORE, ossl_method_store_new, ossl_method_store_free, |
6 | ossl_method_store_init, ossl_method_store_cleanup, | |
2e4d0677 | 7 | ossl_method_store_add, ossl_method_store_fetch, |
f02d3311 | 8 | ossl_method_store_remove, ossl_method_store_remove_all_provided, |
f9e504e8 | 9 | ossl_method_store_cache_get, ossl_method_store_cache_set, |
2e4d0677 | 10 | ossl_method_store_cache_flush_all |
1bdbdaff P |
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 | ||
b4250010 | 19 | OSSL_METHOD_STORE *ossl_method_store_new(OSSL_LIB_CTX *ctx); |
1bdbdaff | 20 | void ossl_method_store_free(OSSL_METHOD_STORE *store); |
b4250010 DMSP |
21 | int ossl_method_store_init(OSSL_LIB_CTX *ctx); |
22 | void ossl_method_store_cleanup(OSSL_LIB_CTX *ctx); | |
c1d56231 | 23 | int ossl_method_store_add(OSSL_METHOD_STORE *store, const OSSL_PROVIDER *prov, |
b1d40ddf RL |
24 | int nid, const char *properties, void *method, |
25 | int (*method_up_ref)(void *), | |
26 | void (*method_destruct)(void *)); | |
1bdbdaff | 27 | int ossl_method_store_remove(OSSL_METHOD_STORE *store, |
0a79572a | 28 | int nid, const void *method); |
1bdbdaff P |
29 | int ossl_method_store_fetch(OSSL_METHOD_STORE *store, |
30 | int nid, const char *properties, | |
dc010ca6 | 31 | void **method, const OSSL_PROVIDER **prov_rw); |
2e4d0677 RL |
32 | int ossl_method_store_remove_all_provided(OSSL_METHOD_STORE *store, |
33 | const OSSL_PROVIDER *prov); | |
34 | ||
dc010ca6 RL |
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, | |
bdbf2df2 P |
39 | int (*method_up_ref)(void *), |
40 | void (*method_destruct)(void *)); | |
60640d79 | 41 | void ossl_method_store_cache_flush_all(OSSL_METHOD_STORE *store); |
1bdbdaff P |
42 | |
43 | =head1 DESCRIPTION | |
44 | ||
0a79572a RL |
45 | OSSL_METHOD_STORE stores methods that can be queried using properties and a |
46 | numeric identity (nid). | |
1bdbdaff | 47 | |
0a79572a RL |
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 | ||
25b25b0f | 60 | ossl_method_store_init() initialises the method store subsystem in the scope of |
dfabee82 | 61 | the library context I<ctx>. |
1bdbdaff P |
62 | |
63 | ossl_method_store_cleanup() cleans up and shuts down the implementation method | |
dfabee82 | 64 | store subsystem in the scope of the library context I<ctx>. |
1bdbdaff | 65 | |
25b25b0f | 66 | ossl_method_store_new() create a new empty method store using the supplied |
dfabee82 | 67 | I<ctx> to allow access to the required underlying property data. |
1bdbdaff | 68 | |
dfabee82 | 69 | ossl_method_store_free() frees resources allocated to I<store>. |
1bdbdaff | 70 | |
dfabee82 RL |
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 | |
b1d40ddf | 76 | reference count of the method. |
dfabee82 | 77 | If the I<method_destruct> function is given, it's called when this function |
b1d40ddf | 78 | fails to add the method to the store, or later on when it is being released from |
dfabee82 | 79 | the I<store>. |
1bdbdaff | 80 | |
dfabee82 RL |
81 | ossl_method_store_remove() removes the I<method> identified by I<nid> from the |
82 | I<store>. | |
1bdbdaff | 83 | |
dfabee82 RL |
84 | ossl_method_store_fetch() queries I<store> for a method identified by I<nid> |
85 | that matches the property query I<prop_query>. | |
dc010ca6 RL |
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>. | |
1bdbdaff | 89 | |
2e4d0677 RL |
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 | ||
0a79572a | 94 | =head2 Cache Functions |
1bdbdaff | 95 | |
dfabee82 RL |
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>. | |
dc010ca6 RL |
99 | Additionally, if I<prov> isn't NULL, it will be used to narrow the search |
100 | to only include methods from that provider. | |
dfabee82 | 101 | The result, if any, is returned in I<method>. |
1bdbdaff | 102 | |
dc010ca6 RL |
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>. | |
dfabee82 | 105 | Future calls to ossl_method_store_cache_get() will return the specified I<method>. |
bdbf2df2 P |
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. | |
1bdbdaff | 109 | |
60640d79 RL |
110 | ossl_method_store_cache_flush_all() flushes all cached entries associated with |
111 | I<store>. | |
112 | ||
af788ad6 P |
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 | ||
1bdbdaff P |
119 | =head1 RETURN VALUES |
120 | ||
dfabee82 | 121 | ossl_method_store_new() returns a new method store object or NULL on failure. |
1bdbdaff P |
122 | |
123 | ossl_method_store_free(), ossl_method_store_add(), | |
124 | ossl_method_store_remove(), ossl_method_store_fetch(), | |
860ecfd7 P |
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. | |
1bdbdaff | 127 | |
3f37050e | 128 | ossl_method_store_free() and ossl_method_store_cleanup() do not return any value. |
1bdbdaff P |
129 | |
130 | =head1 HISTORY | |
131 | ||
4674aaf4 | 132 | This functionality was added to OpenSSL 3.0. |
1bdbdaff P |
133 | |
134 | =head1 COPYRIGHT | |
135 | ||
fecb3aae | 136 | Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. |
1bdbdaff P |
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 |