]>
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, | |
7 | ossl_method_store_add, ossl_method_store_remove, ossl_method_store_fetch, | |
8 | ossl_method_store_set_global_properties, | |
1ad2d940 | 9 | ossl_method_store_cache_get, ossl_method_store_cache_set |
1bdbdaff P |
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 | ||
25b25b0f | 18 | OSSL_METHOD_STORE *ossl_method_store_new(OPENSSL_CTX *ctx); |
1bdbdaff | 19 | void ossl_method_store_free(OSSL_METHOD_STORE *store); |
25b25b0f MC |
20 | int ossl_method_store_init(OPENSSL_CTX *ctx); |
21 | void ossl_method_store_cleanup(OPENSSL_CTX *ctx); | |
c1d56231 | 22 | int ossl_method_store_add(OSSL_METHOD_STORE *store, const OSSL_PROVIDER *prov, |
b1d40ddf RL |
23 | int nid, const char *properties, void *method, |
24 | int (*method_up_ref)(void *), | |
25 | void (*method_destruct)(void *)); | |
1bdbdaff | 26 | int ossl_method_store_remove(OSSL_METHOD_STORE *store, |
0a79572a | 27 | int nid, const void *method); |
1bdbdaff P |
28 | int ossl_method_store_fetch(OSSL_METHOD_STORE *store, |
29 | int nid, const char *properties, | |
0a79572a | 30 | void **method); |
1bdbdaff P |
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, | |
0a79572a | 34 | const char *prop_query, void **method); |
1bdbdaff | 35 | int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid, |
0a79572a | 36 | const char *prop_query, void *method); |
1bdbdaff P |
37 | |
38 | =head1 DESCRIPTION | |
39 | ||
0a79572a RL |
40 | OSSL_METHOD_STORE stores methods that can be queried using properties and a |
41 | numeric identity (nid). | |
1bdbdaff | 42 | |
0a79572a RL |
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 | ||
25b25b0f | 55 | ossl_method_store_init() initialises the method store subsystem in the scope of |
dfabee82 | 56 | the library context I<ctx>. |
1bdbdaff P |
57 | |
58 | ossl_method_store_cleanup() cleans up and shuts down the implementation method | |
dfabee82 | 59 | store subsystem in the scope of the library context I<ctx>. |
1bdbdaff | 60 | |
25b25b0f | 61 | ossl_method_store_new() create a new empty method store using the supplied |
dfabee82 | 62 | I<ctx> to allow access to the required underlying property data. |
1bdbdaff | 63 | |
dfabee82 | 64 | ossl_method_store_free() frees resources allocated to I<store>. |
1bdbdaff | 65 | |
dfabee82 RL |
66 | ossl_method_store_add() adds the I<method> constructed from an implementation in |
67 | the provider I<prov> to the I<store> as an instance of an algorithm indicated by | |
68 | I<nid> and the property definition I<properties>, unless the I<store> already | |
69 | has a method from the same provider with the same I<nid> and I<properties>. | |
70 | If the I<method_up_ref> function is given, it's called to increment the | |
b1d40ddf | 71 | reference count of the method. |
dfabee82 | 72 | If the I<method_destruct> function is given, it's called when this function |
b1d40ddf | 73 | fails to add the method to the store, or later on when it is being released from |
dfabee82 | 74 | the I<store>. |
1bdbdaff | 75 | |
dfabee82 RL |
76 | ossl_method_store_remove() removes the I<method> identified by I<nid> from the |
77 | I<store>. | |
1bdbdaff | 78 | |
dfabee82 RL |
79 | ossl_method_store_fetch() queries I<store> for a method identified by I<nid> |
80 | that matches the property query I<prop_query>. | |
81 | The result, if any, is returned in I<method>. | |
1bdbdaff | 82 | |
dfabee82 RL |
83 | ossl_method_store_set_global_properties() sets method I<store> wide query |
84 | properties to I<prop_query>. | |
1bdbdaff | 85 | All subsequent fetches will need to meet both these global query properties |
0a79572a RL |
86 | and the ones passed to the ossl_method_store_free(). |
87 | ||
88 | =head2 Cache Functions | |
1bdbdaff | 89 | |
dfabee82 RL |
90 | ossl_method_store_cache_get() queries the cache associated with the I<store> |
91 | for a method identified by I<nid> that matches the property query | |
92 | I<prop_query>. | |
93 | The result, if any, is returned in I<method>. | |
1bdbdaff | 94 | |
dfabee82 RL |
95 | ossl_method_store_cache_set() sets a cache entry identified by I<nid> with the |
96 | property query I<prop_query> in the I<store>. | |
97 | Future calls to ossl_method_store_cache_get() will return the specified I<method>. | |
1bdbdaff P |
98 | |
99 | =head1 RETURN VALUES | |
100 | ||
dfabee82 | 101 | ossl_method_store_new() returns a new method store object or NULL on failure. |
1bdbdaff P |
102 | |
103 | ossl_method_store_free(), ossl_method_store_add(), | |
104 | ossl_method_store_remove(), ossl_method_store_fetch(), | |
105 | ossl_method_store_set_global_properties(), ossl_method_store_cache_get() | |
106 | and ossl_method_store_cache_set() return B<1> on success and B<0> on error. | |
107 | ||
3f37050e | 108 | ossl_method_store_free() and ossl_method_store_cleanup() do not return any value. |
1bdbdaff P |
109 | |
110 | =head1 HISTORY | |
111 | ||
4674aaf4 | 112 | This functionality was added to OpenSSL 3.0. |
1bdbdaff P |
113 | |
114 | =head1 COPYRIGHT | |
115 | ||
116 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
117 | Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. | |
118 | ||
119 | Licensed under the Apache License 2.0 (the "License"). You may not use this | |
120 | file except in compliance with the License. You can obtain a copy in the file | |
121 | LICENSE in the source distribution or at | |
122 | L<https://www.openssl.org/source/license.html>. | |
123 | ||
124 | =cut |