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