Update internal documentation after global data move to OPENSSL_CTX

 typedef struct ossl_method_store_st OSSL_METHOD_STORE;

 OSSL_METHOD_STORE *ossl_method_store_new(void);

 OSSL_METHOD_STORE *ossl_method_store_new(OPENSSL_CTX *ctx);

 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_init(OPENSSL_CTX *ctx);

 void ossl_method_store_cleanup(OPENSSL_CTX *ctx);

 int ossl_method_store_add(OSSL_METHOD_STORE *store,

                           int nid, const char *properties,

                           void *method, void (*method_destruct)(void *));

=head2 Store Functions

ossl_method_store_init() initialises the method store subsystem.

ossl_method_store_init() initialises the method store subsystem in the scope of

the library context B<ctx>.

ossl_method_store_cleanup() cleans up and shuts down the implementation method

store subsystem.

store subsystem in the scope of the library context B<ctx>.

ossl_method_store_new() create a new empty method store.

ossl_method_store_new() create a new empty method store using the supplied

B<ctx> to allow access to the required underlying property data.

ossl_method_store_free() frees resources allocated to B<store>.

=head1 NAME

openssl_ctx_new_index, openssl_ctx_get_data - internal OPENSSL_CTX routines

openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree

- internal OPENSSL_CTX routines

=head1 SYNOPSIS

 #include "internal/cryptlib.h"

 typedef struct openssl_ctx_method {

     void *(*new_func)(void);

     void *(*new_func)(OPENSSL_CTX *ctx);

     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);

 void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index,

                            const OPENSSL_CTX_METHOD *meth);

 int openssl_ctx_run_once(OPENSSL_CTX *ctx, unsigned int idx,

                          openssl_ctx_run_once_fn run_once_fn);

 int openssl_ctx_onfree(OPENSSL_CTX *ctx, openssl_ctx_onfree_fn onfreefn);

=head1 DESCRIPTION

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.

associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes

to identify data items. These are mapped transparetnly to CRYPTO_EX_DATA dynamic

indexes internally to the implementation.

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

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>. An

OPENSSL_CTX_METHOD must be defined and given in the C<meth> parameter. The index

for it should be defined in cryptlib.h. The functions through the 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>.

openssl_ctx_run_once is used to run some initialisation routine C<run_once_fn>

exactly once per library context C<ctx> object. Each initialisation routine

should be allocate a unique run once index in cryptlib.h.

=head1 RETURN VALUES

Any resources allocated via a run once initialisation routine can be cleaned up

using openssl_ctx_onfree. This associates an "on free" routine C<onfreefn> with

the library context C<ctx>. When C<ctx> is freed all associated "on free"

routines are called.

openssl_ctx_new_index() returns -1 on error, otherwise the allocated

index number.

=head1 RETURN VALUES

openssl_ctx_get_data() returns a pointer on success, or C<NULL> on

failure.

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;

and a destructor to an index.

 typedef struct foo_st {

     int i;

     void *data;

 } FOO;

 static void *foo_new(void)

 static void *foo_new(OPENSSL_CTX *ctx)

 {

     FOO *ptr = OPENSSL_zalloc(sizeof(*foo));

     if (ptr != NULL)

 {

     OPENSSL_free(ptr);

 }

 static const OPENSSL_CTX_METHOD foo_method = {

 /*

  * Include a reference to this in the methods table in context.c 

  * OPENSSL_CTX_FOO_INDEX should be added to internal/cryptlib.h

  */

 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);

 FOO *data = openssl_ctx_get_data(ctx, OPENSSL_CTX_FOO_INDEX, &foo_method);

=head2 Run Once

 void foo_cleanup(OPENSSL_CTX *ctx)

 {

     /* Free foo resources associated with ctx */

 }

 static openssl_ctx_run_once_fn do_foo_init;

 static int do_foo_init(OPENSSL_CTX *ctx)

 {

     /* Allocate and initialise some foo resources and associated with ctx */

     return openssl_ctx_onfree(ctx, &foo_cleanup)

 }

 int foo_some_function(OPENSSL_CTX *ctx)

 {

    if (!openssl_ctx_run_once(ctx,

                              OPENSSL_CTX_FOO_RUN_ONCE_INDEX,

                              do_foo_init))

        return 0;

    /* Do some work using foo resources in ctx */

 }

=head1 SEE ALSO

 struct ossl_method_construct_method_st {

     /* Create store */

     void *(*alloc_tmp_store)(void);

     void *(*alloc_tmp_store)(OPENSSL_CTX *ctx);

     /* Remove a store */

     void (*dealloc_tmp_store)(void *store);

     /* Get an already existing method from a store */

                             int force_cache,

                             OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data);

=head1 DESCRIPTION

All libcrypto sub-systems that want to create their own methods based

=item alloc_tmp_store()

Create a temporary method store.

Create a temporary method store in the scope of the library context C<ctx>.

This store is used to temporarily store methods for easier lookup, for

when the provider doesn't want its dispatch table stored in a longer

term cache.