doc/man3/OSSL_LIB_CTX.pod

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