1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
=pod
=head1 NAME
ossl_lib_ctx_get_data, ossl_lib_ctx_run_once, ossl_lib_ctx_onfree,
ossl_lib_ctx_is_child
- internal OSSL_LIB_CTX routines
=head1 SYNOPSIS
#include <openssl/types.h>
#include "internal/cryptlib.h"
typedef struct ossl_lib_ctx_method {
int priority;
void *(*new_func)(OSSL_LIB_CTX *ctx);
void (*free_func)(void *);
} OSSL_LIB_CTX_METHOD;
void *ossl_lib_ctx_get_data(OSSL_LIB_CTX *ctx, int index,
const OSSL_LIB_CTX_METHOD *meth);
int ossl_lib_ctx_run_once(OSSL_LIB_CTX *ctx, unsigned int idx,
ossl_lib_ctx_run_once_fn run_once_fn);
int ossl_lib_ctx_onfree(OSSL_LIB_CTX *ctx, ossl_lib_ctx_onfree_fn onfreefn);
int ossl_lib_ctx_is_child(OSSL_LIB_CTX *ctx);
=head1 DESCRIPTION
Internally, the OpenSSL library context B<OSSL_LIB_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.
ossl_lib_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
OSSL_LIB_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.
ossl_lib_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 ossl_lib_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.
ossl_lib_ctx_is_child() returns 1 if this library context is a child and 0
otherwise.
=head1 RETURN VALUES
ossl_lib_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(OSSL_LIB_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
* OSSL_LIB_CTX_FOO_INDEX should be added to internal/cryptlib.h
* Priorities can be OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
* OSSL_LIB_CTX_METHOD_PRIORITY_1, OSSL_LIB_CTX_METHOD_PRIORITY_2, etc.
* Default priority is low (0). The higher the priority the earlier the
* method's destructor will be called when the library context is cleaned up.
*/
const OSSL_LIB_CTX_METHOD foo_method = {
OSSL_LIB_CTX_METHOD_DEFAULT_PRIORITY,
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 = ossl_lib_ctx_get_data(ctx, OSSL_LIB_CTX_FOO_INDEX, &foo_method);
=head2 Run Once
void foo_cleanup(OSSL_LIB_CTX *ctx)
{
/* Free foo resources associated with ctx */
}
static ossl_lib_ctx_run_once_fn do_foo_init;
static int do_foo_init(OSSL_LIB_CTX *ctx)
{
/* Allocate and initialise some foo resources and associated with ctx */
return ossl_lib_ctx_onfree(ctx, &foo_cleanup)
}
int foo_some_function(OSSL_LIB_CTX *ctx)
{
if (!ossl_lib_ctx_run_once(ctx,
OSSL_LIB_CTX_FOO_RUN_ONCE_INDEX,
do_foo_init))
return 0;
/* Do some work using foo resources in ctx */
}
=head1 SEE ALSO
L<OSSL_LIB_CTX(3)>
=head1 COPYRIGHT
Copyright 2019-2021 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
|
