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