xref: /freebsd-src/crypto/openssl/doc/internal/man3/ossl_lib_ctx_get_data.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1*b077aed3SPierre Pronchery=pod
2*b077aed3SPierre Pronchery
3*b077aed3SPierre Pronchery=head1 NAME
4*b077aed3SPierre Pronchery
5*b077aed3SPierre Proncheryossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree,
6*b077aed3SPierre Proncheryossl_lib_ctx_is_child
7*b077aed3SPierre Pronchery- internal OSSL_LIB_CTX routines
8*b077aed3SPierre Pronchery
9*b077aed3SPierre Pronchery=head1 SYNOPSIS
10*b077aed3SPierre Pronchery
11*b077aed3SPierre Pronchery #include <openssl/types.h>
12*b077aed3SPierre Pronchery #include "internal/cryptlib.h"
13*b077aed3SPierre Pronchery
14*b077aed3SPierre Pronchery typedef struct ossl_lib_ctx_method {
15*b077aed3SPierre Pronchery     int priority;
16*b077aed3SPierre Pronchery     void *(*new_func)(OSSL_LIB_CTX *ctx);
17*b077aed3SPierre Pronchery     void (*free_func)(void *);
18*b077aed3SPierre Pronchery } OSSL_LIB_CTX_METHOD;
19*b077aed3SPierre Pronchery
20*b077aed3SPierre Pronchery void *ossl_lib_ctx_get_data(OSSL_LIB_CTX *ctx, int index,
21*b077aed3SPierre Pronchery                             const OSSL_LIB_CTX_METHOD *meth);
22*b077aed3SPierre Pronchery
23*b077aed3SPierre Pronchery int ossl_lib_ctx_run_once(OSSL_LIB_CTX *ctx, unsigned int idx,
24*b077aed3SPierre Pronchery                           ossl_lib_ctx_run_once_fn run_once_fn);
25*b077aed3SPierre Pronchery int ossl_lib_ctx_onfree(OSSL_LIB_CTX *ctx, ossl_lib_ctx_onfree_fn onfreefn);
26*b077aed3SPierre Pronchery
27*b077aed3SPierre Pronchery int ossl_lib_ctx_is_child(OSSL_LIB_CTX *ctx);
28*b077aed3SPierre Pronchery
29*b077aed3SPierre Pronchery=head1 DESCRIPTION
30*b077aed3SPierre Pronchery
31*b077aed3SPierre ProncheryInternally, the OpenSSL library context B<OSSL_LIB_CTX> is implemented
32*b077aed3SPierre Proncheryas a B<CRYPTO_EX_DATA>, which allows data from diverse parts of the
33*b077aed3SPierre Proncherylibrary to be added and removed dynamically.
34*b077aed3SPierre ProncheryEach such data item must have a corresponding CRYPTO_EX_DATA index
35*b077aed3SPierre Proncheryassociated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes
36*b077aed3SPierre Proncheryto identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic
37*b077aed3SPierre Proncheryindexes internally to the implementation.
38*b077aed3SPierre ProncherySee the example further down to see how that's done.
39*b077aed3SPierre Pronchery
40*b077aed3SPierre Proncheryossl_lib_ctx_get_data() is used to retrieve a pointer to the data in
41*b077aed3SPierre Proncherythe library context I<ctx> associated with the given I<index>. An
42*b077aed3SPierre ProncheryOSSL_LIB_CTX_METHOD must be defined and given in the I<meth> parameter. The index
43*b077aed3SPierre Proncheryfor it should be defined in cryptlib.h. The functions through the method are
44*b077aed3SPierre Proncheryused to create or free items that are stored at that index whenever a library
45*b077aed3SPierre Proncherycontext is created or freed, meaning that the code that use a data item of that
46*b077aed3SPierre Proncheryindex doesn't have to worry about that, just use the data available.
47*b077aed3SPierre Pronchery
48*b077aed3SPierre ProncheryDeallocation of an index happens automatically when the library
49*b077aed3SPierre Proncherycontext is freed.
50*b077aed3SPierre Pronchery
51*b077aed3SPierre Proncheryossl_lib_ctx_run_once is used to run some initialisation routine I<run_once_fn>
52*b077aed3SPierre Proncheryexactly once per library context I<ctx> object. Each initialisation routine
53*b077aed3SPierre Proncheryshould be allocate a unique run once index in cryptlib.h.
54*b077aed3SPierre Pronchery
55*b077aed3SPierre ProncheryAny resources allocated via a run once initialisation routine can be cleaned up
56*b077aed3SPierre Proncheryusing ossl_lib_ctx_onfree. This associates an "on free" routine I<onfreefn> with
57*b077aed3SPierre Proncherythe library context I<ctx>. When I<ctx> is freed all associated "on free"
58*b077aed3SPierre Proncheryroutines are called.
59*b077aed3SPierre Pronchery
60*b077aed3SPierre Proncheryossl_lib_ctx_is_child() returns 1 if this library context is a child and 0
61*b077aed3SPierre Proncheryotherwise.
62*b077aed3SPierre Pronchery
63*b077aed3SPierre Pronchery=head1 RETURN VALUES
64*b077aed3SPierre Pronchery
65*b077aed3SPierre Proncheryossl_lib_ctx_get_data() returns a pointer on success, or NULL on
66*b077aed3SPierre Proncheryfailure.
67*b077aed3SPierre Pronchery
68*b077aed3SPierre Pronchery=head1 EXAMPLES
69*b077aed3SPierre Pronchery
70*b077aed3SPierre Pronchery=head2 Initialization
71*b077aed3SPierre Pronchery
72*b077aed3SPierre ProncheryFor a type C<FOO> that should end up in the OpenSSL library context, a
73*b077aed3SPierre Proncherysmall bit of initialization is needed, i.e. to associate a constructor
74*b077aed3SPierre Proncheryand a destructor to an index.
75*b077aed3SPierre Pronchery
76*b077aed3SPierre Pronchery typedef struct foo_st {
77*b077aed3SPierre Pronchery     int i;
78*b077aed3SPierre Pronchery     void *data;
79*b077aed3SPierre Pronchery } FOO;
80*b077aed3SPierre Pronchery
81*b077aed3SPierre Pronchery static void *foo_new(OSSL_LIB_CTX *ctx)
82*b077aed3SPierre Pronchery {
83*b077aed3SPierre Pronchery     FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
84*b077aed3SPierre Pronchery     if (ptr != NULL)
85*b077aed3SPierre Pronchery         ptr->i = 42;
86*b077aed3SPierre Pronchery     return ptr;
87*b077aed3SPierre Pronchery }
88*b077aed3SPierre Pronchery static void foo_free(void *ptr)
89*b077aed3SPierre Pronchery {
90*b077aed3SPierre Pronchery     OPENSSL_free(ptr);
91*b077aed3SPierre Pronchery }
92*b077aed3SPierre Pronchery
93*b077aed3SPierre Pronchery /*
94*b077aed3SPierre Pronchery  * Include a reference to this in the methods table in context.c
95*b077aed3SPierre Pronchery  * OSSL_LIB_CTX_FOO_INDEX should be added to internal/cryptlib.h
96*b077aed3SPierre Pronchery  * Priorities can be OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
97*b077aed3SPierre Pronchery  * OSSL_LIB_CTX_METHOD_PRIORITY_1, OSSL_LIB_CTX_METHOD_PRIORITY_2, etc.
98*b077aed3SPierre Pronchery  * Default priority is low (0). The higher the priority the earlier the
99*b077aed3SPierre Pronchery  * method's destructor will be called when the library context is cleaned up.
100*b077aed3SPierre Pronchery  */
101*b077aed3SPierre Pronchery const OSSL_LIB_CTX_METHOD foo_method = {
102*b077aed3SPierre Pronchery     OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
103*b077aed3SPierre Pronchery     foo_new,
104*b077aed3SPierre Pronchery     foo_free
105*b077aed3SPierre Pronchery };
106*b077aed3SPierre Pronchery
107*b077aed3SPierre Pronchery=head2 Usage
108*b077aed3SPierre Pronchery
109*b077aed3SPierre ProncheryTo get and use the data stored in the library context, simply do this:
110*b077aed3SPierre Pronchery
111*b077aed3SPierre Pronchery /*
112*b077aed3SPierre Pronchery  * ctx is received from a caller,
113*b077aed3SPierre Pronchery  */
114*b077aed3SPierre Pronchery FOO *data = ossl_lib_ctx_get_data(ctx, OSSL_LIB_CTX_FOO_INDEX, &foo_method);
115*b077aed3SPierre Pronchery
116*b077aed3SPierre Pronchery=head2 Run Once
117*b077aed3SPierre Pronchery
118*b077aed3SPierre Pronchery void foo_cleanup(OSSL_LIB_CTX *ctx)
119*b077aed3SPierre Pronchery {
120*b077aed3SPierre Pronchery     /* Free foo resources associated with ctx */
121*b077aed3SPierre Pronchery }
122*b077aed3SPierre Pronchery
123*b077aed3SPierre Pronchery static ossl_lib_ctx_run_once_fn do_foo_init;
124*b077aed3SPierre Pronchery static int do_foo_init(OSSL_LIB_CTX *ctx)
125*b077aed3SPierre Pronchery {
126*b077aed3SPierre Pronchery     /* Allocate and initialise some foo resources and associated with ctx */
127*b077aed3SPierre Pronchery     return ossl_lib_ctx_onfree(ctx, &foo_cleanup)
128*b077aed3SPierre Pronchery }
129*b077aed3SPierre Pronchery
130*b077aed3SPierre Pronchery int foo_some_function(OSSL_LIB_CTX *ctx)
131*b077aed3SPierre Pronchery {
132*b077aed3SPierre Pronchery    if (!ossl_lib_ctx_run_once(ctx,
133*b077aed3SPierre Pronchery                               OSSL_LIB_CTX_FOO_RUN_ONCE_INDEX,
134*b077aed3SPierre Pronchery                               do_foo_init))
135*b077aed3SPierre Pronchery        return 0;
136*b077aed3SPierre Pronchery
137*b077aed3SPierre Pronchery    /* Do some work using foo resources in ctx */
138*b077aed3SPierre Pronchery }
139*b077aed3SPierre Pronchery
140*b077aed3SPierre Pronchery
141*b077aed3SPierre Pronchery=head1 SEE ALSO
142*b077aed3SPierre Pronchery
143*b077aed3SPierre ProncheryL<OSSL_LIB_CTX(3)>
144*b077aed3SPierre Pronchery
145*b077aed3SPierre Pronchery=head1 COPYRIGHT
146*b077aed3SPierre Pronchery
147*b077aed3SPierre ProncheryCopyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
148*b077aed3SPierre Pronchery
149*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
150*b077aed3SPierre Proncherythis file except in compliance with the License.  You can obtain a copy
151*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at
152*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>.
153*b077aed3SPierre Pronchery
154*b077aed3SPierre Pronchery=cut
155