]>
Commit | Line | Data |
---|---|---|
d64b6299 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
f9548d21 | 5 | OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch, |
878be71c MC |
6 | OSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, |
7 | OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default | |
22e27978 | 8 | - OpenSSL library context |
d64b6299 RL |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/crypto.h> | |
13 | ||
b4250010 | 14 | typedef struct ossl_lib_ctx_st OSSL_LIB_CTX; |
d64b6299 | 15 | |
b4250010 | 16 | OSSL_LIB_CTX *OSSL_LIB_CTX_new(void); |
f12a5690 MC |
17 | OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle, |
18 | const OSSL_DISPATCH *in); | |
878be71c MC |
19 | OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle, |
20 | const OSSL_DISPATCH *in); | |
b4250010 DMSP |
21 | int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file); |
22 | void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx); | |
978e323a | 23 | OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void); |
b4250010 | 24 | OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx); |
d64b6299 RL |
25 | |
26 | =head1 DESCRIPTION | |
27 | ||
b4250010 | 28 | B<OSSL_LIB_CTX> is an internal OpenSSL library context type. |
5a975275 | 29 | Applications may allocate their own, but may also use NULL to use |
b4250010 | 30 | a default context with functions that take an B<OSSL_LIB_CTX> |
d64b6299 RL |
31 | argument. |
32 | ||
ff6da65e MC |
33 | When a non default library context is in use care should be taken with |
34 | multi-threaded applications to properly clean up thread local resources before | |
b4250010 | 35 | the OSSL_LIB_CTX is freed. |
ff6da65e | 36 | See L<OPENSSL_thread_stop_ex(3)> for more information. |
d64b6299 | 37 | |
b4250010 | 38 | OSSL_LIB_CTX_new() creates a new OpenSSL library context. |
5a975275 | 39 | |
f9548d21 MC |
40 | OSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context |
41 | initialised to use callbacks from the OSSL_DISPATCH structure. This is primarily | |
f12a5690 MC |
42 | useful for provider authors. The I<handle> and dispatch structure arguments |
43 | passed should be the same ones as passed to a provider's | |
44 | OSSL_provider_init function. Some OpenSSL functions, such as | |
45 | L<BIO_new_from_core_bio(3)>, require the library context to be created in this | |
46 | way in order to work. | |
f9548d21 | 47 | |
878be71c MC |
48 | OSSL_LIB_CTX_new_child() is only useful to provider authors and does the same |
49 | thing as OSSL_LIB_CTX_new_from_dispatch() except that it additionally links the | |
50 | new library context to the application library context. The new library context | |
51 | is a full library context in its own right, but will have all the same providers | |
52 | available to it that are available in the application library context (without | |
53 | having to reload them). If the application loads or unloads providers from the | |
54 | application library context then this will be automatically mirrored in the | |
55 | child library context. | |
56 | ||
57 | In addition providers that are not loaded in the parent library context can be | |
58 | explicitly loaded into the child library context independently from the parent | |
59 | library context. Providers loaded independently in this way will not be mirrored | |
60 | in the parent library context and will not be affected if the parent library | |
61 | context subsequently loads the same provider. | |
62 | ||
63 | A provider may call the function L<OSSL_PROVIDER_load(3)> with the child library | |
64 | context as required. If the provider already exists due to it being mirrored | |
65 | from the parent library context then it will remain available and its reference | |
66 | count will be increased. If L<OSSL_PROVIDER_load(3)> is called in this way then | |
67 | L<OSSL_PROVIDER_unload(3)> should be subsequently called to decrement the | |
68 | reference count. L<OSSL_PROVIDER_unload(3)> must not be called for a provider in | |
69 | the child library context that did not have an earlier L<OSSL_PROVIDER_load(3)> | |
70 | call for that provider in that child library context. | |
71 | ||
366bf9ae MC |
72 | In addition to providers, a child library context will also mirror the default |
73 | properties (set via L<EVP_set_default_properties(3)>) from the parent library | |
74 | context. If L<EVP_set_default_properties(3)> is called directly on a child | |
75 | library context then the new properties will override anything from the parent | |
76 | library context and mirroring of the properties will stop. | |
77 | ||
878be71c MC |
78 | OSSL_LIB_CTX_new_child() must only be called from within the scope of a |
79 | provider's B<OSSL_provider_init> function (see L<provider-base(7)>). Calling it | |
80 | outside of that function may succeed but may not correctly mirror all providers | |
81 | and is considered undefined behaviour. When called from within the scope of a | |
82 | provider's B<OSSL_provider_init> function the currently initialising provider is | |
83 | not yet available in the application's library context and therefore will | |
84 | similarly not yet be available in the newly constructed child library context. | |
85 | As soon as the B<OSSL_provider_init> function returns then the new provider is | |
86 | available in the application's library context and will be similarly mirrored in | |
87 | the child library context. Since the current provider is still initialising | |
88 | the provider should not attempt to perform fetches, or call any function that | |
89 | performs a fetch using the child library context until after the initialisation | |
90 | function has completed. | |
91 | ||
b4250010 | 92 | OSSL_LIB_CTX_load_config() loads a configuration file using the given C<ctx>. |
5a975275 RL |
93 | This can be used to associate a library context with providers that are loaded |
94 | from a configuration. | |
95 | ||
b4250010 | 96 | OSSL_LIB_CTX_free() frees the given I<ctx>, unless it happens to be the |
5a975275 | 97 | default OpenSSL library context. |
22e27978 | 98 | |
978e323a MC |
99 | OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to |
100 | the global default library context. | |
101 | ||
b4250010 | 102 | OSSL_LIB_CTX_set0_default() sets the default OpenSSL library context to be |
5a975275 RL |
103 | I<ctx> in the current thread. The previous default library context is |
104 | returned. Care should be taken by the caller to restore the previous | |
92b20fb8 MC |
105 | default library context with a subsequent call of this function. If I<ctx> is |
106 | NULL then no change is made to the default library context, but a pointer to | |
978e323a MC |
107 | the current library context is still returned. On a successful call of this |
108 | function the returned value will always be a concrete (non NULL) library | |
109 | context. | |
d64b6299 | 110 | |
6c689e58 MC |
111 | Care should be taken when changing the default library context and starting |
112 | async jobs (see L<ASYNC_start_job(3)>), as the default library context when | |
113 | the job is started will be used throughout the lifetime of an async job, no | |
114 | matter how the calling thread makes further default library context changes | |
115 | in the mean time. This means that the calling thread must not free the | |
116 | library context that was the default at the start of the async job before | |
117 | that job has finished. | |
118 | ||
d64b6299 RL |
119 | =head1 RETURN VALUES |
120 | ||
978e323a MC |
121 | OSSL_LIB_CTX_new(), OSSL_LIB_CTX_get0_global_default() and |
122 | OSSL_LIB_CTX_set0_default() return a library context pointer on success, or NULL | |
123 | on error. | |
d64b6299 | 124 | |
b4250010 | 125 | OSSL_LIB_CTX_free() doesn't return any value. |
d64b6299 RL |
126 | |
127 | =head1 HISTORY | |
128 | ||
f9548d21 | 129 | All of the functions described on this page were added in OpenSSL 3.0. |
d64b6299 RL |
130 | |
131 | =head1 COPYRIGHT | |
132 | ||
f5afac4b | 133 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
d64b6299 RL |
134 | |
135 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
136 | this file except in compliance with the License. You can obtain a copy | |
137 | in the file LICENSE in the source distribution or at | |
138 | L<https://www.openssl.org/source/license.html>. | |
139 | ||
140 | =cut |