1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OSSL_LIB_CTX 3SSL"
.TH OSSL_LIB_CTX 3SSL "2023-10-23" "3.0.11" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
OSSL_LIB_CTX, OSSL_LIB_CTX_new, OSSL_LIB_CTX_new_from_dispatch,
OSSL_LIB_CTX_new_child, OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
\&\- OpenSSL library context
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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_CORE_HANDLE *handle,
\& const OSSL_DISPATCH *in);
\& OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1OSSL_LIB_CTX\s0\fR is an internal OpenSSL library context type.
Applications may allocate their own, but may also use \s-1NULL\s0 to use
a default context with functions that take an \fB\s-1OSSL_LIB_CTX\s0\fR
argument.
.PP
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 \s-1OSSL_LIB_CTX\s0 is freed.
See \fBOPENSSL_thread_stop_ex\fR\|(3) for more information.
.PP
\&\fBOSSL_LIB_CTX_new()\fR creates a new OpenSSL library context.
.PP
\&\fBOSSL_LIB_CTX_new_from_dispatch()\fR creates a new OpenSSL library context
initialised to use callbacks from the \s-1OSSL_DISPATCH\s0 structure. This is primarily
useful for provider authors. The \fIhandle\fR and dispatch structure arguments
passed should be the same ones as passed to a provider's
OSSL_provider_init function. Some OpenSSL functions, such as
\&\fBBIO_new_from_core_bio\fR\|(3), require the library context to be created in this
way in order to work.
.PP
\&\fBOSSL_LIB_CTX_new_child()\fR is only useful to provider authors and does the same
thing as \fBOSSL_LIB_CTX_new_from_dispatch()\fR except that it additionally links the
new library context to the application library context. The new library context
is a full library context in its own right, but will have all the same providers
available to it that are available in the application library context (without
having to reload them). If the application loads or unloads providers from the
application library context then this will be automatically mirrored in the
child library context.
.PP
In addition providers that are not loaded in the parent library context can be
explicitly loaded into the child library context independently from the parent
library context. Providers loaded independently in this way will not be mirrored
in the parent library context and will not be affected if the parent library
context subsequently loads the same provider.
.PP
A provider may call the function \fBOSSL_PROVIDER_load\fR\|(3) with the child library
context as required. If the provider already exists due to it being mirrored
from the parent library context then it will remain available and its reference
count will be increased. If \fBOSSL_PROVIDER_load\fR\|(3) is called in this way then
\&\fBOSSL_PROVIDER_unload\fR\|(3) should be subsequently called to decrement the
reference count. \fBOSSL_PROVIDER_unload\fR\|(3) must not be called for a provider in
the child library context that did not have an earlier \fBOSSL_PROVIDER_load\fR\|(3)
call for that provider in that child library context.
.PP
In addition to providers, a child library context will also mirror the default
properties (set via \fBEVP_set_default_properties\fR\|(3)) from the parent library
context. If \fBEVP_set_default_properties\fR\|(3) is called directly on a child
library context then the new properties will override anything from the parent
library context and mirroring of the properties will stop.
.PP
When \fBOSSL_LIB_CTX_new_child()\fR is called from within the scope of a provider's
\&\fBOSSL_provider_init\fR function the currently initialising provider is not yet
available in the application's library context and therefore will similarly not
yet be available in the newly constructed child library context. As soon as the
\&\fBOSSL_provider_init\fR function returns then the new provider is available in the
application's library context and will be similarly mirrored in the child
library context.
.PP
\&\fBOSSL_LIB_CTX_load_config()\fR loads a configuration file using the given \fIctx\fR.
This can be used to associate a library context with providers that are loaded
from a configuration.
.PP
\&\fBOSSL_LIB_CTX_free()\fR frees the given \fIctx\fR, unless it happens to be the
default OpenSSL library context.
.PP
\&\fBOSSL_LIB_CTX_get0_global_default()\fR returns a concrete (non \s-1NULL\s0) reference to
the global default library context.
.PP
\&\fBOSSL_LIB_CTX_set0_default()\fR sets the default OpenSSL library context to be
\&\fIctx\fR 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 \fIctx\fR is
\&\s-1NULL\s0 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 \s-1NULL\s0) library
context.
.PP
Care should be taken when changing the default library context and starting
async jobs (see \fBASYNC_start_job\fR\|(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.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBOSSL_LIB_CTX_new()\fR, \fBOSSL_LIB_CTX_get0_global_default()\fR and
\&\fBOSSL_LIB_CTX_set0_default()\fR return a library context pointer on success, or \s-1NULL\s0
on error.
.PP
\&\fBOSSL_LIB_CTX_free()\fR doesn't return any value.
.PP
\&\fBOSSL_LIB_CTX_load_config()\fR returns 1 on success, 0 on error.
.SH "HISTORY"
.IX Header "HISTORY"
All of the functions described on this page were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.
|
