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