Latest update
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
DEFINE_SPARSE_ARRAY_OF, ossl_sa_TYPE_new, ossl_sa_TYPE_free,
|
||||
ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall,
|
||||
ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
|
||||
- sparse array container
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment generic
|
||||
|
||||
#include "internal/sparse_array.h"
|
||||
|
||||
typedef struct sparse_array_st OPENSSL_SA;
|
||||
|
||||
SPARSE_ARRAY_OF(TYPE)
|
||||
DEFINE_SPARSE_ARRAY_OF(TYPE)
|
||||
|
||||
SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void);
|
||||
void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa);
|
||||
void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa);
|
||||
int ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa);
|
||||
void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(size_t, void *));
|
||||
void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa,
|
||||
void (*leaf)(size_t, void *, void *), void *arg);
|
||||
TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
|
||||
int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx, TYPE *value);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
|
||||
B<TYPE>. DEFINE_STACK_OF() creates set of functions for a sparse array of
|
||||
B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
|
||||
element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
|
||||
each function name begins with I<ossl_sa_TYPE_>. For example:
|
||||
|
||||
TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
|
||||
|
||||
ossl_sa_TYPE_num() returns the number of elements in B<sa> or 0 if B<sa> is
|
||||
B<NULL>.
|
||||
|
||||
ossl_sa_TYPE_get() returns element B<idx> in B<sa>, where B<idx> starts at
|
||||
zero. If B<idx> refers to a value that has not been set then B<NULL> is
|
||||
returned.
|
||||
|
||||
ossl_sa_TYPE_set() sets element B<idx> in B<sa> to B<value>, where B<idx>
|
||||
starts at zero. The sparse array will be resized as required.
|
||||
|
||||
ossl_sa_TYPE_new() allocates a new empty sparse array.
|
||||
|
||||
ossl_sa_TYPE_free() frees up the B<sa> structure. It does B<not> free up any
|
||||
elements of B<sa>. After this call B<sa> is no longer valid.
|
||||
|
||||
ossl_sa_TYPE_free_leaves() frees up the B<sa> structure and all of its
|
||||
elements. After this call B<sa> is no longer valid.
|
||||
|
||||
ossl_sa_TYPE_doall() calls the function B<leaf> for each element in B<sa>
|
||||
in ascending index order. The index position, within the sparse array,
|
||||
of each item is passed as the first argument to the leaf function and a
|
||||
pointer to the associated value is is passed as the second argument.
|
||||
|
||||
ossl_sa_TYPE_doall_arg() calls the function B<leaf> for each element in
|
||||
B<sa> in ascending index order. The index position, within the sparse
|
||||
array, of each item is passed as the first argument to the leaf function,
|
||||
a pointer to the associated value is passed as the second argument and
|
||||
the third argument is the user supplied B<arg>.
|
||||
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Sparse arrays are an internal data structure and should B<not> be used by user
|
||||
applications.
|
||||
|
||||
Care should be taken when accessing sparse arrays in multi-threaded
|
||||
environments. The ossl_sa_TYPE_set operation can cause the internal structure
|
||||
of the sparse array to change which causes race conditions if the sparse array
|
||||
is accessed in a different thread.
|
||||
|
||||
SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
|
||||
|
||||
The underlying utility B<OPENSSL_SA_> API should not be used directly. It
|
||||
defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg,
|
||||
OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new,
|
||||
OPENSSL_SA_num and OPENSSL_SA_set.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
|
||||
if the passed sparse array is B<NULL>.
|
||||
|
||||
ossl_sa_TYPE_get() returns a pointer to a sparse array element or B<NULL> if
|
||||
the element has not be set.
|
||||
|
||||
ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
|
||||
case, the elements of the sparse array remain unchanged, although the internal
|
||||
structures might have.
|
||||
|
||||
ossl_sa_TYPE_new() returns an empty sparse array or B<NULL> if an error
|
||||
occurs.
|
||||
|
||||
ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
|
||||
ossl_sa_TYPE_free_leaves() 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
|
||||
@@ -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
|
||||
@@ -0,0 +1,112 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl_ctx_new_index, openssl_ctx_get_data - internal OPENSSL_CTX routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ossl_typ.h>
|
||||
#include "internal/cryptlib.h"
|
||||
|
||||
typedef struct openssl_ctx_method {
|
||||
void *(*new_func)(void);
|
||||
void (*free_func)(void *);
|
||||
} OPENSSL_CTX_METHOD;
|
||||
|
||||
int openssl_ctx_new_index(const OPENSSL_CTX_METHOD *meth);
|
||||
void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Internally, the OpenSSL library context C<OPENSSL_CTX> is implemented
|
||||
as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
|
||||
library to be added and removed dynamically.
|
||||
Each such data item must have a corresponding CRYPTO_EX_DATA index
|
||||
associated with it.
|
||||
See the example further down to see how that's done.
|
||||
|
||||
openssl_ctx_new_index() allocates a new library context index, and
|
||||
associates it with the functions given through C<meth>.
|
||||
The functions given through that method are used to create or free
|
||||
items that are stored at that index whenever a library context is
|
||||
created or freed, meaning that the code that use a data item of that
|
||||
index doesn't have to worry about that, just use the data available.
|
||||
|
||||
Deallocation of an index happens automatically when the library
|
||||
context is freed.
|
||||
|
||||
openssl_ctx_get_data() is used to retrieve a pointer to the data in
|
||||
the library context C<ctx> associated with the given C<index>.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
=head2 Initialization
|
||||
|
||||
For a type C<FOO> that should end up in the OpenSSL library context, a
|
||||
small bit of initialization is needed, i.e. to associate a constructor
|
||||
and a destructor to a new index.
|
||||
|
||||
/* The index will always be entirely global, and dynamically allocated */
|
||||
static int foo_index = -1;
|
||||
|
||||
typedef struct foo_st {
|
||||
int i;
|
||||
void *data;
|
||||
} FOO;
|
||||
|
||||
static void *foo_new(void)
|
||||
{
|
||||
FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
|
||||
if (ptr != NULL)
|
||||
ptr->i = 42;
|
||||
return ptr;
|
||||
}
|
||||
static void foo_free(void *ptr)
|
||||
{
|
||||
OPENSSL_free(ptr);
|
||||
}
|
||||
static const OPENSSL_CTX_METHOD foo_method = {
|
||||
foo_new,
|
||||
foo_free
|
||||
};
|
||||
|
||||
static int foo_init(void)
|
||||
{
|
||||
foo_index = openssl_ctx_new_index(foo_method);
|
||||
|
||||
return foo_index != -1;
|
||||
}
|
||||
|
||||
=head2 Usage
|
||||
|
||||
To get and use the data stored in the library context, simply do this:
|
||||
|
||||
/*
|
||||
* ctx is received from a caller,
|
||||
* foo_index comes from the example above
|
||||
*/
|
||||
FOO *data = openssl_ctx_get_data(ctx, foo_index);
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
openssl_ctx_new_index() returns -1 on error, otherwise the allocated
|
||||
index number.
|
||||
|
||||
openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
|
||||
failure.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<OPENSSL_CTX(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2019 The OpenSSL Project Authors. 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
|
||||
Reference in New Issue
Block a user