doc/man3/OPENSSL_CTX.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OPENSSL_CTX, OPENSSL_CTX_new, OPENSSL_CTX_free, OPENSSL_CTX_load_config,
   6 OPENSSL_CTX_set0_default
   7 - OpenSSL library context
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/crypto.h>
  12
  13  typedef struct openssl_ctx_st OPENSSL_CTX;
  14
  15  OPENSSL_CTX *OPENSSL_CTX_new(void);
  16  int OPENSSL_CTX_load_config(OPENSSL_CTX *ctx, const char *config_file);
  17  void OPENSSL_CTX_free(OPENSSL_CTX *ctx);
  18  OPENSSL_CTX *OPENSSL_CTX_set0_default(OPENSSL_CTX *ctx);
  19
  20 =head1 DESCRIPTION
  21
  22 B<OPENSSL_CTX> is an internal OpenSSL library context type.
  23 Applications may allocate their own, but may also use NULL to use
  24 a default context with functions that take an B<OPENSSL_CTX>
  25 argument.
  26
  27 When a non default library context is in use care should be taken with
  28 multi-threaded applications to properly clean up thread local resources before
  29 the OPENSSL_CTX is freed.
  30 See L<OPENSSL_thread_stop_ex(3)> for more information.
  31
  32 OPENSSL_CTX_new() creates a new OpenSSL library context.
  33
  34 OPENSSL_CTX_load_config() loads a configuration file using the given C<ctx>.
  35 This can be used to associate a library context with providers that are loaded
  36 from a configuration.
  37
  38 OPENSSL_CTX_free() frees the given I<ctx>, unless it happens to be the
  39 default OpenSSL library context.
  40
  41 OPENSSL_CTX_set0_default() sets the default OpenSSL library context to be
  42 I<ctx> in the current thread.  The previous default library context is
  43 returned.  Care should be taken by the caller to restore the previous
  44 default library context with a subsequent call of this function.
  45
  46 Care should be taken when changing the default library context and starting
  47 async jobs (see L<ASYNC_start_job(3)>), as the default library context when
  48 the job is started will be used throughout the lifetime of an async job, no
  49 matter how the calling thread makes further default library context changes
  50 in the mean time.  This means that the calling thread must not free the
  51 library context that was the default at the start of the async job before
  52 that job has finished.
  53
  54 =head1 RETURN VALUES
  55
  56 OPENSSL_CTX_new() and OPENSSL_CTX_set0_default() return a library context
  57 pointer on success, or NULL on error.
  58
  59 OPENSSL_CTX_free() doesn't return any value.
  60
  61 =head1 HISTORY
  62
  63 OPENSSL_CTX, OPENSSL_CTX_new(), OPENSSL_CTX_load_config(), OPENSSL_CTX_free()
  64 and OPENSSL_CTX_set0_default() were added in OpenSSL 3.0.
  65
  66 =head1 COPYRIGHT
  67
  68 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
  69
  70 Licensed under the Apache License 2.0 (the "License").  You may not use
  71 this file except in compliance with the License.  You can obtain a copy
  72 in the file LICENSE in the source distribution or at
  73 L<https://www.openssl.org/source/license.html>.
  74
  75 =cut