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