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