Latest update

doc/internal/man3/OSSL_METHOD_STORE.pod

@@ -0,0 +1,116 @@
+=pod
+
+=head1 NAME
+
+OSSL_METHOD_STORE, ossl_method_store_new, ossl_method_store_free,
+ossl_method_store_init, ossl_method_store_cleanup,
+ossl_method_store_add, ossl_method_store_remove, ossl_method_store_fetch,
+ossl_method_store_set_global_properties,
+ossl_method_store_cache_get, ossl_method_store_cache_set
+- implementation method store and query
+
+=head1 SYNOPSIS
+
+ #include "internal/property.h"
+
+ typedef struct ossl_method_store_st OSSL_METHOD_STORE;
+
+ OSSL_METHOD_STORE *ossl_method_store_new(void);
+ void ossl_method_store_free(OSSL_METHOD_STORE *store);
+ int ossl_method_store_init(void);
+ void ossl_method_store_cleanup(void);
+ int ossl_method_store_add(OSSL_METHOD_STORE *store,
+                           int nid, const char *properties,
+                           void *method, void (*method_destruct)(void *));
+ int ossl_method_store_remove(OSSL_METHOD_STORE *store,
+                              int nid, const void *method);
+ int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
+                             int nid, const char *properties,
+                             void **method);
+ int ossl_method_store_set_global_properties(OSSL_METHOD_STORE *store,
+                                            const char *prop_query);
+ int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, int nid,
+                                 const char *prop_query, void **method);
+ int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
+                                 const char *prop_query, void *method);
+
+=head1 DESCRIPTION
+
+OSSL_METHOD_STORE stores methods that can be queried using properties and a
+numeric identity (nid).
+
+Methods are expected to be library internal structures.
+It's left to the caller to define the exact contents.
+
+Numeric identities are expected to be an algorithm identity for the methods.
+It's left to the caller to define exactly what an algorithm is, and to allocate
+these numeric identities accordingly.
+
+The B<OSSL_METHOD_STORE> also holds an internal query cache, which is accessed
+separately (see L</Cache Functions> below).
+
+=head2 Store Functions
+
+ossl_method_store_init() initialises the method store subsystem.
+
+ossl_method_store_cleanup() cleans up and shuts down the implementation method
+store subsystem.
+
+ossl_method_store_new() create a new empty method store.
+
+ossl_method_store_free() frees resources allocated to B<store>.
+
+ossl_method_store_add() adds the B<method> to the B<store> as an instance of an
+algorithm indicated by B<nid> and the property definition B<properties>.
+The optional B<method_destruct> function is called when B<method> is being
+released from B<store>.
+
+ossl_method_store_remove() removes the B<method> identified by B<nid> from the
+B<store>.
+
+ossl_method_store_fetch() queries B<store> for an method identified by B<nid>
+that matches the property query B<prop_query>.
+The result, if any, is returned in B<method>.
+
+ossl_method_store_set_global_properties() sets method B<store> wide query
+properties to B<prop_query>.
+All subsequent fetches will need to meet both these global query properties
+and the ones passed to the ossl_method_store_free().
+
+=head2 Cache Functions
+
+ossl_method_store_cache_get() queries the cache associated with the B<store>
+for an method identified by B<nid> that matches the property query
+B<prop_query>.
+The result, if any, is returned in B<method>.
+
+ossl_method_store_cache_set() sets a cache entry identified by B<nid> with the
+property query B<prop_query> in the B<store>.
+Future cache gets will return the specified B<method>.
+
+=head1 RETURN VALUES
+
+ossl_method_store_new() a new method store object or B<NULL> on failure.
+
+ossl_method_store_free(), ossl_method_store_add(),
+ossl_method_store_remove(), ossl_method_store_fetch(),
+ossl_method_store_set_global_properties(), ossl_method_store_cache_get()
+and ossl_method_store_cache_set() return B<1> on success and B<0> on error.
+
+ossl_method_store_free() and ossl_method_store_cleanup() do not return values.
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright (c) 2019, Oracle and/or its affiliates.  All rights reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use this
+file except in compliance with the License.  You can obtain a copy in the file
+LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut