xref: /freebsd/crypto/openssl/doc/man3/OSSL_LIB_CTX.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1*b077aed3SPierre Pronchery=pod
2*b077aed3SPierre Pronchery
3*b077aed3SPierre Pronchery=head1 NAME
4*b077aed3SPierre Pronchery
5*b077aed3SPierre ProncheryOSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch,
6*b077aed3SPierre ProncheryOSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
7*b077aed3SPierre ProncheryOSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
8*b077aed3SPierre Pronchery- OpenSSL library context
9*b077aed3SPierre Pronchery
10*b077aed3SPierre Pronchery=head1 SYNOPSIS
11*b077aed3SPierre Pronchery
12*b077aed3SPierre Pronchery #include <openssl/crypto.h>
13*b077aed3SPierre Pronchery
14*b077aed3SPierre Pronchery typedef struct ossl_lib_ctx_st OSSL_LIB_CTX;
15*b077aed3SPierre Pronchery
16*b077aed3SPierre Pronchery OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
17*b077aed3SPierre Pronchery OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle,
18*b077aed3SPierre Pronchery                                              const OSSL_DISPATCH *in);
19*b077aed3SPierre Pronchery OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
20*b077aed3SPierre Pronchery                                      const OSSL_DISPATCH *in);
21*b077aed3SPierre Pronchery int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
22*b077aed3SPierre Pronchery void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
23*b077aed3SPierre Pronchery OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
24*b077aed3SPierre Pronchery OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx);
25*b077aed3SPierre Pronchery
26*b077aed3SPierre Pronchery=head1 DESCRIPTION
27*b077aed3SPierre Pronchery
28*b077aed3SPierre ProncheryB<OSSL_LIB_CTX> is an internal OpenSSL library context type.
29*b077aed3SPierre ProncheryApplications may allocate their own, but may also use NULL to use
30*b077aed3SPierre Proncherya default context with functions that take an B<OSSL_LIB_CTX>
31*b077aed3SPierre Proncheryargument.
32*b077aed3SPierre Pronchery
33*b077aed3SPierre ProncheryWhen a non default library context is in use care should be taken with
34*b077aed3SPierre Proncherymulti-threaded applications to properly clean up thread local resources before
35*b077aed3SPierre Proncherythe OSSL_LIB_CTX is freed.
36*b077aed3SPierre ProncherySee L<OPENSSL_thread_stop_ex(3)> for more information.
37*b077aed3SPierre Pronchery
38*b077aed3SPierre ProncheryOSSL_LIB_CTX_new() creates a new OpenSSL library context.
39*b077aed3SPierre Pronchery
40*b077aed3SPierre ProncheryOSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context
41*b077aed3SPierre Proncheryinitialised to use callbacks from the OSSL_DISPATCH structure. This is primarily
42*b077aed3SPierre Proncheryuseful for provider authors. The I<handle> and dispatch structure arguments
43*b077aed3SPierre Proncherypassed should be the same ones as passed to a provider's
44*b077aed3SPierre ProncheryOSSL_provider_init function. Some OpenSSL functions, such as
45*b077aed3SPierre ProncheryL<BIO_new_from_core_bio(3)>, require the library context to be created in this
46*b077aed3SPierre Proncheryway in order to work.
47*b077aed3SPierre Pronchery
48*b077aed3SPierre ProncheryOSSL_LIB_CTX_new_child() is only useful to provider authors and does the same
49*b077aed3SPierre Proncherything as OSSL_LIB_CTX_new_from_dispatch() except that it additionally links the
50*b077aed3SPierre Proncherynew library context to the application library context. The new library context
51*b077aed3SPierre Proncheryis a full library context in its own right, but will have all the same providers
52*b077aed3SPierre Proncheryavailable to it that are available in the application library context (without
53*b077aed3SPierre Proncheryhaving to reload them). If the application loads or unloads providers from the
54*b077aed3SPierre Proncheryapplication library context then this will be automatically mirrored in the
55*b077aed3SPierre Proncherychild library context.
56*b077aed3SPierre Pronchery
57*b077aed3SPierre ProncheryIn addition providers that are not loaded in the parent library context can be
58*b077aed3SPierre Proncheryexplicitly loaded into the child library context independently from the parent
59*b077aed3SPierre Proncherylibrary context. Providers loaded independently in this way will not be mirrored
60*b077aed3SPierre Proncheryin the parent library context and will not be affected if the parent library
61*b077aed3SPierre Proncherycontext subsequently loads the same provider.
62*b077aed3SPierre Pronchery
63*b077aed3SPierre ProncheryA provider may call the function L<OSSL_PROVIDER_load(3)> with the child library
64*b077aed3SPierre Proncherycontext as required. If the provider already exists due to it being mirrored
65*b077aed3SPierre Proncheryfrom the parent library context then it will remain available and its reference
66*b077aed3SPierre Proncherycount will be increased. If L<OSSL_PROVIDER_load(3)> is called in this way then
67*b077aed3SPierre ProncheryL<OSSL_PROVIDER_unload(3)> should be subsequently called to decrement the
68*b077aed3SPierre Proncheryreference count. L<OSSL_PROVIDER_unload(3)> must not be called for a provider in
69*b077aed3SPierre Proncherythe child library context that did not have an earlier L<OSSL_PROVIDER_load(3)>
70*b077aed3SPierre Proncherycall for that provider in that child library context.
71*b077aed3SPierre Pronchery
72*b077aed3SPierre ProncheryIn addition to providers, a child library context will also mirror the default
73*b077aed3SPierre Proncheryproperties (set via L<EVP_set_default_properties(3)>) from the parent library
74*b077aed3SPierre Proncherycontext. If L<EVP_set_default_properties(3)> is called directly on a child
75*b077aed3SPierre Proncherylibrary context then the new properties will override anything from the parent
76*b077aed3SPierre Proncherylibrary context and mirroring of the properties will stop.
77*b077aed3SPierre Pronchery
78*b077aed3SPierre ProncheryWhen OSSL_LIB_CTX_new_child() is called from within the scope of a provider's
79*b077aed3SPierre ProncheryB<OSSL_provider_init> function the currently initialising provider is not yet
80*b077aed3SPierre Proncheryavailable in the application's library context and therefore will similarly not
81*b077aed3SPierre Proncheryyet be available in the newly constructed child library context. As soon as the
82*b077aed3SPierre ProncheryB<OSSL_provider_init> function returns then the new provider is available in the
83*b077aed3SPierre Proncheryapplication's library context and will be similarly mirrored in the child
84*b077aed3SPierre Proncherylibrary context.
85*b077aed3SPierre Pronchery
86*b077aed3SPierre ProncheryOSSL_LIB_CTX_load_config() loads a configuration file using the given I<ctx>.
87*b077aed3SPierre ProncheryThis can be used to associate a library context with providers that are loaded
88*b077aed3SPierre Proncheryfrom a configuration.
89*b077aed3SPierre Pronchery
90*b077aed3SPierre ProncheryOSSL_LIB_CTX_free() frees the given I<ctx>, unless it happens to be the
91*b077aed3SPierre Proncherydefault OpenSSL library context.
92*b077aed3SPierre Pronchery
93*b077aed3SPierre ProncheryOSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to
94*b077aed3SPierre Proncherythe global default library context.
95*b077aed3SPierre Pronchery
96*b077aed3SPierre ProncheryOSSL_LIB_CTX_set0_default() sets the default OpenSSL library context to be
97*b077aed3SPierre ProncheryI<ctx> in the current thread.  The previous default library context is
98*b077aed3SPierre Proncheryreturned.  Care should be taken by the caller to restore the previous
99*b077aed3SPierre Proncherydefault library context with a subsequent call of this function. If I<ctx> is
100*b077aed3SPierre ProncheryNULL then no change is made to the default library context, but a pointer to
101*b077aed3SPierre Proncherythe current library context is still returned. On a successful call of this
102*b077aed3SPierre Proncheryfunction the returned value will always be a concrete (non NULL) library
103*b077aed3SPierre Proncherycontext.
104*b077aed3SPierre Pronchery
105*b077aed3SPierre ProncheryCare should be taken when changing the default library context and starting
106*b077aed3SPierre Proncheryasync jobs (see L<ASYNC_start_job(3)>), as the default library context when
107*b077aed3SPierre Proncherythe job is started will be used throughout the lifetime of an async job, no
108*b077aed3SPierre Proncherymatter how the calling thread makes further default library context changes
109*b077aed3SPierre Proncheryin the mean time.  This means that the calling thread must not free the
110*b077aed3SPierre Proncherylibrary context that was the default at the start of the async job before
111*b077aed3SPierre Proncherythat job has finished.
112*b077aed3SPierre Pronchery
113*b077aed3SPierre Pronchery=head1 RETURN VALUES
114*b077aed3SPierre Pronchery
115*b077aed3SPierre ProncheryOSSL_LIB_CTX_new(), OSSL_LIB_CTX_get0_global_default() and
116*b077aed3SPierre ProncheryOSSL_LIB_CTX_set0_default() return a library context pointer on success, or NULL
117*b077aed3SPierre Proncheryon error.
118*b077aed3SPierre Pronchery
119*b077aed3SPierre ProncheryOSSL_LIB_CTX_free() doesn't return any value.
120*b077aed3SPierre Pronchery
121*b077aed3SPierre ProncheryOSSL_LIB_CTX_load_config() returns 1 on success, 0 on error.
122*b077aed3SPierre Pronchery
123*b077aed3SPierre Pronchery=head1 HISTORY
124*b077aed3SPierre Pronchery
125*b077aed3SPierre ProncheryAll of the functions described on this page were added in OpenSSL 3.0.
126*b077aed3SPierre Pronchery
127*b077aed3SPierre Pronchery=head1 COPYRIGHT
128*b077aed3SPierre Pronchery
129*b077aed3SPierre ProncheryCopyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
130*b077aed3SPierre Pronchery
131*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
132*b077aed3SPierre Proncherythis file except in compliance with the License.  You can obtain a copy
133*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at
134*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>.
135*b077aed3SPierre Pronchery
136*b077aed3SPierre Pronchery=cut
137