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