Scroll to navigation

OSSL_LIB_CTX(3SSL) OpenSSL OSSL_LIB_CTX(3SSL)

NAME

OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default - OpenSSL library context

SYNOPSIS

 #include <openssl/crypto.h>

 typedef struct ossl_lib_ctx_st OSSL_LIB_CTX;

 OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
 OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_DISPATCH *in);
 int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
 void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
 OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
 OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx);

DESCRIPTION

OSSL_LIB_CTX is an internal OpenSSL library context type. Applications may allocate their own, but may also use NULL to use a default context with functions that take an OSSL_LIB_CTX argument.

When a non default library context is in use care should be taken with multi-threaded applications to properly clean up thread local resources before the OSSL_LIB_CTX is freed. See OPENSSL_thread_stop_ex(3) for more information.

OSSL_LIB_CTX_new() creates a new OpenSSL library context.

OSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context initialised to use callbacks from the OSSL_DISPATCH structure. This is primarily useful for provider authors. The dispatch structure passed should be the same one as passed to a provider's OSSL_provider_init function in the in argument. Some OpenSSL functions, such as BIO_new_from_core_bio(3), require the library context to be created in this way in order to work.

OSSL_LIB_CTX_load_config() loads a configuration file using the given "ctx". This can be used to associate a library context with providers that are loaded from a configuration.

OSSL_LIB_CTX_free() frees the given ctx, unless it happens to be the default OpenSSL library context.

OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to the global default library context.

OSSL_LIB_CTX_set0_default() sets the default OpenSSL library context to be ctx in the current thread. The previous default library context is returned. Care should be taken by the caller to restore the previous default library context with a subsequent call of this function. If ctx is NULL then no change is made to the default library context, but a pointer to the current library context is still returned. On a successful call of this function the returned value will always be a concrete (non NULL) library context.

Care should be taken when changing the default library context and starting async jobs (see ASYNC_start_job(3)), as the default library context when the job is started will be used throughout the lifetime of an async job, no matter how the calling thread makes further default library context changes in the mean time. This means that the calling thread must not free the library context that was the default at the start of the async job before that job has finished.

RETURN VALUES

OSSL_LIB_CTX_new(), OSSL_LIB_CTX_get0_global_default() and OSSL_LIB_CTX_set0_default() return a library context pointer on success, or NULL on error.

OSSL_LIB_CTX_free() doesn't return any value.

HISTORY

All of the functions described on this page were added in OpenSSL 3.0.

COPYRIGHT

Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

2021-05-06 3.0.0-alpha16