1OSSL_LIB_CTX(3ossl)                 OpenSSL                OSSL_LIB_CTX(3ossl)
2
3
4

NAME

6       OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch,
7       OSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
8       OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default - OpenSSL
9       library context
10

SYNOPSIS

12        #include <openssl/crypto.h>
13
14        typedef struct ossl_lib_ctx_st OSSL_LIB_CTX;
15
16        OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
17        OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle,
18                                                     const OSSL_DISPATCH *in);
19        OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
20                                             const OSSL_DISPATCH *in);
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);
23        OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
24        OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx);
25

DESCRIPTION

27       OSSL_LIB_CTX is an internal OpenSSL library context type.  Applications
28       may allocate their own, but may also use NULL to use a default context
29       with functions that take an OSSL_LIB_CTX argument.
30
31       When a non default library context is in use care should be taken with
32       multi-threaded applications to properly clean up thread local resources
33       before the OSSL_LIB_CTX is freed.  See OPENSSL_thread_stop_ex(3) for
34       more information.
35
36       OSSL_LIB_CTX_new() creates a new OpenSSL library context.
37
38       OSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context
39       initialised to use callbacks from the OSSL_DISPATCH structure. This is
40       primarily useful for provider authors. The handle and dispatch
41       structure arguments passed should be the same ones as passed to a
42       provider's OSSL_provider_init function. Some OpenSSL functions, such as
43       BIO_new_from_core_bio(3), require the library context to be created in
44       this way in order to work.
45
46       OSSL_LIB_CTX_new_child() is only useful to provider authors and does
47       the same thing as OSSL_LIB_CTX_new_from_dispatch() except that it
48       additionally links the new library context to the application library
49       context. The new library context is a full library context in its own
50       right, but will have all the same providers available to it that are
51       available in the application library context (without having to reload
52       them). If the application loads or unloads providers from the
53       application library context then this will be automatically mirrored in
54       the child library context.
55
56       In addition providers that are not loaded in the parent library context
57       can be explicitly loaded into the child library context independently
58       from the parent library context. Providers loaded independently in this
59       way will not be mirrored in the parent library context and will not be
60       affected if the parent library context subsequently loads the same
61       provider.
62
63       A provider may call the function OSSL_PROVIDER_load(3) with the child
64       library context as required. If the provider already exists due to it
65       being mirrored from the parent library context then it will remain
66       available and its reference count will be increased. If
67       OSSL_PROVIDER_load(3) is called in this way then
68       OSSL_PROVIDER_unload(3) should be subsequently called to decrement the
69       reference count. OSSL_PROVIDER_unload(3) must not be called for a
70       provider in the child library context that did not have an earlier
71       OSSL_PROVIDER_load(3) call for that provider in that child library
72       context.
73
74       In addition to providers, a child library context will also mirror the
75       default properties (set via EVP_set_default_properties(3)) from the
76       parent library context. If EVP_set_default_properties(3) is called
77       directly on a child library context then the new properties will
78       override anything from the parent library context and mirroring of the
79       properties will stop.
80
81       When OSSL_LIB_CTX_new_child() is called from within the scope of a
82       provider's OSSL_provider_init function the currently initialising
83       provider is not yet available in the application's library context and
84       therefore will similarly not yet be available in the newly constructed
85       child library context. As soon as the OSSL_provider_init function
86       returns then the new provider is available in the application's library
87       context and will be similarly mirrored in the child library context.
88
89       OSSL_LIB_CTX_load_config() loads a configuration file using the given
90       ctx.  This can be used to associate a library context with providers
91       that are loaded from a configuration.
92
93       OSSL_LIB_CTX_free() frees the given ctx, unless it happens to be the
94       default OpenSSL library context.
95
96       OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL)
97       reference to the global default library context.
98
99       OSSL_LIB_CTX_set0_default() sets the default OpenSSL library context to
100       be ctx in the current thread.  The previous default library context is
101       returned.  Care should be taken by the caller to restore the previous
102       default library context with a subsequent call of this function. If ctx
103       is NULL then no change is made to the default library context, but a
104       pointer to the current library context is still returned. On a
105       successful call of this function the returned value will always be a
106       concrete (non NULL) library context.
107
108       Care should be taken when changing the default library context and
109       starting async jobs (see ASYNC_start_job(3)), as the default library
110       context when the job is started will be used throughout the lifetime of
111       an async job, no matter how the calling thread makes further default
112       library context changes in the mean time.  This means that the calling
113       thread must not free the library context that was the default at the
114       start of the async job before that job has finished.
115

RETURN VALUES

117       OSSL_LIB_CTX_new(), OSSL_LIB_CTX_get0_global_default() and
118       OSSL_LIB_CTX_set0_default() return a library context pointer on
119       success, or NULL on error.
120
121       OSSL_LIB_CTX_free() doesn't return any value.
122
123       OSSL_LIB_CTX_load_config() returns 1 on success, 0 on error.
124

HISTORY

126       All of the functions described on this page were added in OpenSSL 3.0.
127
129       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
130
131       Licensed under the Apache License 2.0 (the "License").  You may not use
132       this file except in compliance with the License.  You can obtain a copy
133       in the file LICENSE in the source distribution or at
134       <https://www.openssl.org/source/license.html>.
135
136
137
1383.1.1                             2023-08-31               OSSL_LIB_CTX(3ossl)
Impressum