Debian Codegraph @

upstream/debian-unstable/man3/OSSL_LIB_CTX.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_LIB_CTX 3SSL"
58 .TH OSSL_LIB_CTX 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_LIB_CTX, OSSL_LIB_CTX_get_data, OSSL_LIB_CTX_new,
65 OSSL_LIB_CTX_new_from_dispatch, OSSL_LIB_CTX_new_child,
66 OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config,
67 OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default
68 \&\- OpenSSL library context
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/crypto.h>
73 \&
74 \& typedef struct ossl_lib_ctx_st OSSL_LIB_CTX;
75 \&
76 \& OSSL_LIB_CTX *OSSL_LIB_CTX_new(void);
77 \& OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle,
78 \& const OSSL_DISPATCH *in);
79 \& OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle,
80 \& const OSSL_DISPATCH *in);
81 \& int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file);
82 \& void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx);
83 \& OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void);
84 \& OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx);
85 \& void *OSSL_LIB_CTX_get_data(OSSL_LIB_CTX *ctx, int index);
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\fBOSSL_LIB_CTX\fR is an internal OpenSSL library context type.
90 Applications may allocate their own, but may also use NULL to use
91 a default context with functions that take an \fBOSSL_LIB_CTX\fR
92 argument.
93 .PP
94 When a non default library context is in use care should be taken with
95 multi-threaded applications to properly clean up thread local resources before
96 the OSSL_LIB_CTX is freed.
97 See \fBOPENSSL_thread_stop_ex\fR\|(3) for more information.
98 .PP
99 \&\fBOSSL_LIB_CTX_new()\fR creates a new OpenSSL library context.
100 .PP
101 \&\fBOSSL_LIB_CTX_new_from_dispatch()\fR creates a new OpenSSL library context
102 initialised to use callbacks from the OSSL_DISPATCH structure. This is primarily
103 useful for provider authors. The \fIhandle\fR and dispatch structure arguments
104 passed should be the same ones as passed to a provider's
105 OSSL_provider_init function. Some OpenSSL functions, such as
106 \&\fBBIO_new_from_core_bio\fR\|(3), require the library context to be created in this
107 way in order to work.
108 .PP
109 \&\fBOSSL_LIB_CTX_new_child()\fR is only useful to provider authors and does the same
110 thing as \fBOSSL_LIB_CTX_new_from_dispatch()\fR except that it additionally links the
111 new library context to the application library context. The new library context
112 is a full library context in its own right, but will have all the same providers
113 available to it that are available in the application library context (without
114 having to reload them). If the application loads or unloads providers from the
115 application library context then this will be automatically mirrored in the
116 child library context.
117 .PP
118 In addition providers that are not loaded in the parent library context can be
119 explicitly loaded into the child library context independently from the parent
120 library context. Providers loaded independently in this way will not be mirrored
121 in the parent library context and will not be affected if the parent library
122 context subsequently loads the same provider.
123 .PP
124 A provider may call the function \fBOSSL_PROVIDER_load\fR\|(3) with the child library
125 context as required. If the provider already exists due to it being mirrored
126 from the parent library context then it will remain available and its reference
127 count will be increased. If \fBOSSL_PROVIDER_load\fR\|(3) is called in this way then
128 \&\fBOSSL_PROVIDER_unload\fR\|(3) should be subsequently called to decrement the
129 reference count. \fBOSSL_PROVIDER_unload\fR\|(3) must not be called for a provider in
130 the child library context that did not have an earlier \fBOSSL_PROVIDER_load\fR\|(3)
131 call for that provider in that child library context.
132 .PP
133 In addition to providers, a child library context will also mirror the default
134 properties (set via \fBEVP_set_default_properties\fR\|(3)) from the parent library
135 context. If \fBEVP_set_default_properties\fR\|(3) is called directly on a child
136 library context then the new properties will override anything from the parent
137 library context and mirroring of the properties will stop.
138 .PP
139 When \fBOSSL_LIB_CTX_new_child()\fR is called from within the scope of a provider's
140 \&\fBOSSL_provider_init\fR function the currently initialising provider is not yet
141 available in the application's library context and therefore will similarly not
142 yet be available in the newly constructed child library context. As soon as the
143 \&\fBOSSL_provider_init\fR function returns then the new provider is available in the
144 application's library context and will be similarly mirrored in the child
145 library context.
146 .PP
147 \&\fBOSSL_LIB_CTX_load_config()\fR loads a configuration file using the given \fIctx\fR.
148 This can be used to associate a library context with providers that are loaded
149 from a configuration. This function must not be called concurrently from
150 multiple threads on a single \fIctx\fR.
151 .PP
152 \&\fBOSSL_LIB_CTX_free()\fR frees the given \fIctx\fR, unless it happens to be the
153 default OpenSSL library context. If the argument is NULL, nothing is done.
154 .PP
155 \&\fBOSSL_LIB_CTX_get0_global_default()\fR returns a concrete (non NULL) reference to
156 the global default library context.
157 .PP
158 \&\fBOSSL_LIB_CTX_set0_default()\fR sets the default OpenSSL library context to be
159 \&\fIctx\fR in the current thread. The previous default library context is
160 returned. Care should be taken by the caller to restore the previous
161 default library context with a subsequent call of this function. If \fIctx\fR is
162 NULL then no change is made to the default library context, but a pointer to
163 the current library context is still returned. On a successful call of this
164 function the returned value will always be a concrete (non NULL) library
165 context.
166 .PP
167 Care should be taken when changing the default library context and starting
168 async jobs (see \fBASYNC_start_job\fR\|(3)), as the default library context when
169 the job is started will be used throughout the lifetime of an async job, no
170 matter how the calling thread makes further default library context changes
171 in the mean time. This means that the calling thread must not free the
172 library context that was the default at the start of the async job before
173 that job has finished.
174 .PP
175 \&\fBOSSL_LIB_CTX_get_data()\fR returns a memory address whose interpretation depends
176 on the index. The index argument refers to a context member which is
177 to be retrieved. The values for index are all private to OpenSSL currently
178 and so applications should not typically call this function.
179 If ctx is NULL then the function operates on the default library context.
180 \&\fBOSSL_LIB_CTX_get_data()\fR returns a memory address whose interpretation
181 depends on the index.
182 .SH "RETURN VALUES"
183 .IX Header "RETURN VALUES"
184 \&\fBOSSL_LIB_CTX_new()\fR, \fBOSSL_LIB_CTX_get0_global_default()\fR and
185 \&\fBOSSL_LIB_CTX_set0_default()\fR return a library context pointer on success, or NULL
186 on error.
187 .PP
188 \&\fBOSSL_LIB_CTX_free()\fR doesn't return any value.
189 .PP
190 \&\fBOSSL_LIB_CTX_load_config()\fR returns 1 on success, 0 on error.
191 .PP
192 \&\fBOSSL_LIB_CTX_get_data()\fR returns a memory address whose interpretation
193 depends on the index.
194 .SH HISTORY
195 .IX Header "HISTORY"
196 All of the functions described on this page were added in OpenSSL 3.0.
197 .PP
198 \&\fBOSSL_LIB_CTX_get_data()\fR was introduced in OpenSSL 3.4.
199 .SH COPYRIGHT
200 .IX Header "COPYRIGHT"
201 Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved.
202 .PP
203 Licensed under the Apache License 2.0 (the "License"). You may not use
204 this file except in compliance with the License. You can obtain a copy
205 in the file LICENSE in the source distribution or at
206 <https://www.openssl.org/source/license.html>.