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