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