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