mirror of
https://github.com/openssl/openssl.git
synced 2025-01-30 14:01:55 +08:00
dfabee82be
It's all in the details, from man-pages(7):
Formatting conventions for manual pages describing functions
...
Variable names should, like argument names, be specified in italics.
...
Formatting conventions (general)
...
Special macros, which are usually in uppercase, are in bold.
Exception: don't boldface NULL.
...
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10034)
125 lines
5.0 KiB
Plaintext
125 lines
5.0 KiB
Plaintext
=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(OPENSSL_CTX *ctx);
|
|
void ossl_method_store_free(OSSL_METHOD_STORE *store);
|
|
int ossl_method_store_init(OPENSSL_CTX *ctx);
|
|
void ossl_method_store_cleanup(OPENSSL_CTX *ctx);
|
|
int ossl_method_store_add(OSSL_METHOD_STORE *store, const OSSL_PROVIDER *prov,
|
|
int nid, const char *properties, void *method,
|
|
int (*method_up_ref)(void *),
|
|
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 in the scope of
|
|
the library context I<ctx>.
|
|
|
|
ossl_method_store_cleanup() cleans up and shuts down the implementation method
|
|
store subsystem in the scope of the library context I<ctx>.
|
|
|
|
ossl_method_store_new() create a new empty method store using the supplied
|
|
I<ctx> to allow access to the required underlying property data.
|
|
|
|
ossl_method_store_free() frees resources allocated to I<store>.
|
|
|
|
ossl_method_store_add() adds the I<method> constructed from an implementation in
|
|
the provider I<prov> to the I<store> as an instance of an algorithm indicated by
|
|
I<nid> and the property definition I<properties>, unless the I<store> already
|
|
has a method from the same provider with the same I<nid> and I<properties>.
|
|
If the I<method_up_ref> function is given, it's called to increment the
|
|
reference count of the method.
|
|
If the I<method_destruct> function is given, it's called when this function
|
|
fails to add the method to the store, or later on when it is being released from
|
|
the I<store>.
|
|
|
|
ossl_method_store_remove() removes the I<method> identified by I<nid> from the
|
|
I<store>.
|
|
|
|
ossl_method_store_fetch() queries I<store> for a method identified by I<nid>
|
|
that matches the property query I<prop_query>.
|
|
The result, if any, is returned in I<method>.
|
|
|
|
ossl_method_store_set_global_properties() sets method I<store> wide query
|
|
properties to I<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 I<store>
|
|
for a method identified by I<nid> that matches the property query
|
|
I<prop_query>.
|
|
The result, if any, is returned in I<method>.
|
|
|
|
ossl_method_store_cache_set() sets a cache entry identified by I<nid> with the
|
|
property query I<prop_query> in the I<store>.
|
|
Future calls to ossl_method_store_cache_get() will return the specified I<method>.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
ossl_method_store_new() returns a new method store object or 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 any value.
|
|
|
|
=head1 HISTORY
|
|
|
|
This functionality was added to OpenSSL 3.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
|