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