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