[thirdparty/openssl.git] / doc / internal / man3 / openssl_ctx_get_data.pod

=pod

=head1 NAME

openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree
- internal OPENSSL_CTX routines

=head1 SYNOPSIS

 #include <openssl/ossl_typ.h>
 #include "internal/cryptlib.h"

 typedef struct openssl_ctx_method {
     void *(*new_func)(OPENSSL_CTX *ctx);
     void (*free_func)(void *);
 } OPENSSL_CTX_METHOD;

 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

Internally, the OpenSSL library context B<OPENSSL_CTX> is implemented
as a B<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. Unlike normal CRYPTO_EX_DATA objects we use static indexes
to identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic
indexes internally to the implementation.
See the example further down to see how that's done.

openssl_ctx_get_data() is used to retrieve a pointer to the data in
the library context I<ctx> associated with the given I<index>. An
OPENSSL_CTX_METHOD must be defined and given in the I<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_run_once is used to run some initialisation routine I<run_once_fn>
exactly once per library context I<ctx> object. Each initialisation routine
should be allocate a unique run once index in cryptlib.h.

Any resources allocated via a run once initialisation routine can be cleaned up
using openssl_ctx_onfree. This associates an "on free" routine I<onfreefn> with
the library context I<ctx>. When I<ctx> is freed all associated "on free"
routines are called.

=head1 RETURN VALUES

openssl_ctx_get_data() returns a pointer on success, or NULL on
failure.

=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 an index.

 typedef struct foo_st {
     int i;
     void *data;
 } FOO;

 static void *foo_new(OPENSSL_CTX *ctx)
 {
     FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
     if (ptr != NULL)
         ptr->i = 42;
     return ptr;
 }
 static void foo_free(void *ptr)
 {
     OPENSSL_free(ptr);
 }

 /*
  * 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
 };

=head2 Usage

To get and use the data stored in the library context, simply do this:

 /*
  * ctx is received from a caller,
  */
 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

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
Commit	Line	Data
d64b6299 RL	1	=pod
	2
	3	=head1 NAME
	4
25b25b0f MC	5	openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree
25b25b0f MC	6	- internal OPENSSL_CTX routines
d64b6299 RL	7
	8	=head1 SYNOPSIS
	9
	10	#include <openssl/ossl_typ.h>
	11	#include "internal/cryptlib.h"
	12
d64b6299	13	typedef struct openssl_ctx_method {
25b25b0f	14	void (new_func)(OPENSSL_CTX *ctx);
d64b6299 RL	15	void (free_func)(void );
	16	} OPENSSL_CTX_METHOD;
	17
25b25b0f MC	18	void openssl_ctx_get_data(OPENSSL_CTX ctx, int index,
	19	const OPENSSL_CTX_METHOD *meth);
	20
	21	int openssl_ctx_run_once(OPENSSL_CTX *ctx, unsigned int idx,
	22	openssl_ctx_run_once_fn run_once_fn);
	23	int openssl_ctx_onfree(OPENSSL_CTX *ctx, openssl_ctx_onfree_fn onfreefn);
d64b6299 RL	24
	25	=head1 DESCRIPTION
	26
dfabee82 RL	27	Internally, the OpenSSL library context B<OPENSSL_CTX> is implemented
dfabee82 RL	28	as a B<CRYPTO_EX_DATA>, which allows data from diverse parts of the
d64b6299 RL	29	library to be added and removed dynamically.
d64b6299 RL	30	Each such data item must have a corresponding CRYPTO_EX_DATA index
25b25b0f	31	associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes
c2969ff6	32	to identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic
25b25b0f	33	indexes internally to the implementation.
d64b6299 RL	34	See the example further down to see how that's done.
d64b6299 RL	35
25b25b0f	36	openssl_ctx_get_data() is used to retrieve a pointer to the data in
dfabee82 RL	37	the library context I<ctx> associated with the given I<index>. An
dfabee82 RL	38	OPENSSL_CTX_METHOD must be defined and given in the I<meth> parameter. The index
25b25b0f MC	39	for it should be defined in cryptlib.h. The functions through the method are
	40	used to create or free items that are stored at that index whenever a library
	41	context is created or freed, meaning that the code that use a data item of that
d64b6299 RL	42	index doesn't have to worry about that, just use the data available.
	43
	44	Deallocation of an index happens automatically when the library
	45	context is freed.
	46
dfabee82 RL	47	openssl_ctx_run_once is used to run some initialisation routine I<run_once_fn>
dfabee82 RL	48	exactly once per library context I<ctx> object. Each initialisation routine
25b25b0f	49	should be allocate a unique run once index in cryptlib.h.
d64b6299	50
25b25b0f	51	Any resources allocated via a run once initialisation routine can be cleaned up
dfabee82 RL	52	using openssl_ctx_onfree. This associates an "on free" routine I<onfreefn> with
dfabee82 RL	53	the library context I<ctx>. When I<ctx> is freed all associated "on free"
25b25b0f	54	routines are called.
4564e77a	55
25b25b0f	56	=head1 RETURN VALUES
4564e77a	57
dfabee82	58	openssl_ctx_get_data() returns a pointer on success, or NULL on
4564e77a PY	59	failure.
4564e77a PY	60
d64b6299 RL	61	=head1 EXAMPLES
	62
	63	=head2 Initialization
	64
	65	For a type C<FOO> that should end up in the OpenSSL library context, a
	66	small bit of initialization is needed, i.e. to associate a constructor
25b25b0f	67	and a destructor to an index.
d64b6299 RL	68
	69	typedef struct foo_st {
	70	int i;
	71	void *data;
	72	} FOO;
	73
25b25b0f	74	static void foo_new(OPENSSL_CTX ctx)
d64b6299 RL	75	{
	76	FOO ptr = OPENSSL_zalloc(sizeof(foo));
	77	if (ptr != NULL)
	78	ptr->i = 42;
	79	return ptr;
	80	}
	81	static void foo_free(void *ptr)
	82	{
	83	OPENSSL_free(ptr);
	84	}
25b25b0f MC	85
	86	/*
	87	* Include a reference to this in the methods table in context.c
	88	* OPENSSL_CTX_FOO_INDEX should be added to internal/cryptlib.h
	89	*/
	90	const OPENSSL_CTX_METHOD foo_method = {
d64b6299 RL	91	foo_new,
	92	foo_free
	93	};
	94
d64b6299 RL	95	=head2 Usage
	96
	97	To get and use the data stored in the library context, simply do this:
	98
	99	/*
	100	* ctx is received from a caller,
d64b6299	101	*/
25b25b0f MC	102	FOO *data = openssl_ctx_get_data(ctx, OPENSSL_CTX_FOO_INDEX, &foo_method);
	103
	104	=head2 Run Once
	105
	106	void foo_cleanup(OPENSSL_CTX *ctx)
	107	{
	108	/* Free foo resources associated with ctx */
	109	}
	110
	111	static openssl_ctx_run_once_fn do_foo_init;
	112	static int do_foo_init(OPENSSL_CTX *ctx)
	113	{
	114	/* Allocate and initialise some foo resources and associated with ctx */
	115	return openssl_ctx_onfree(ctx, &foo_cleanup)
	116	}
	117
	118	int foo_some_function(OPENSSL_CTX *ctx)
	119	{
	120	if (!openssl_ctx_run_once(ctx,
	121	OPENSSL_CTX_FOO_RUN_ONCE_INDEX,
	122	do_foo_init))
	123	return 0;
	124
	125	/* Do some work using foo resources in ctx */
	126	}
	127
d64b6299	128
d64b6299 RL	129	=head1 SEE ALSO
	130
	131	L<OPENSSL_CTX(3)>
	132
	133	=head1 COPYRIGHT
	134
	135	Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
	136
	137	Licensed under the Apache License 2.0 (the "License"). You may not use
	138	this file except in compliance with the License. You can obtain a copy
	139	in the file LICENSE in the source distribution or at
	140	L<https://www.openssl.org/source/license.html>.
	141
	142	=cut