1 | =pod
|
---|
2 |
|
---|
3 | =head1 NAME
|
---|
4 |
|
---|
5 | OPENSSL_INIT_new, OPENSSL_INIT_set_config_filename,
|
---|
6 | OPENSSL_INIT_set_config_appname, OPENSSL_INIT_set_config_file_flags,
|
---|
7 | OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit,
|
---|
8 | OPENSSL_thread_stop_ex, OPENSSL_thread_stop - OpenSSL initialisation
|
---|
9 | and deinitialisation functions
|
---|
10 |
|
---|
11 | =head1 SYNOPSIS
|
---|
12 |
|
---|
13 | #include <openssl/crypto.h>
|
---|
14 |
|
---|
15 | void OPENSSL_cleanup(void);
|
---|
16 | int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
|
---|
17 | int OPENSSL_atexit(void (*handler)(void));
|
---|
18 | void OPENSSL_thread_stop_ex(OSSL_LIB_CTX *ctx);
|
---|
19 | void OPENSSL_thread_stop(void);
|
---|
20 |
|
---|
21 | OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
|
---|
22 | int OPENSSL_INIT_set_config_filename(OPENSSL_INIT_SETTINGS *init,
|
---|
23 | const char* filename);
|
---|
24 | int OPENSSL_INIT_set_config_file_flags(OPENSSL_INIT_SETTINGS *init,
|
---|
25 | unsigned long flags);
|
---|
26 | int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
|
---|
27 | const char* name);
|
---|
28 | void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);
|
---|
29 |
|
---|
30 | =head1 DESCRIPTION
|
---|
31 |
|
---|
32 | During normal operation OpenSSL (libcrypto) will allocate various resources at
|
---|
33 | start up that must, subsequently, be freed on close down of the library.
|
---|
34 | Additionally some resources are allocated on a per thread basis (if the
|
---|
35 | application is multi-threaded), and these resources must be freed prior to the
|
---|
36 | thread closing.
|
---|
37 |
|
---|
38 | As of version 1.1.0 OpenSSL will automatically allocate all resources that it
|
---|
39 | needs so no explicit initialisation is required. Similarly it will also
|
---|
40 | automatically deinitialise as required.
|
---|
41 |
|
---|
42 | However, there may be situations when explicit initialisation is desirable or
|
---|
43 | needed, for example when some nondefault initialisation is required. The
|
---|
44 | function OPENSSL_init_crypto() can be used for this purpose for
|
---|
45 | libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl
|
---|
46 | equivalent).
|
---|
47 |
|
---|
48 | Numerous internal OpenSSL functions call OPENSSL_init_crypto().
|
---|
49 | Therefore, in order to perform nondefault initialisation,
|
---|
50 | OPENSSL_init_crypto() MUST be called by application code prior to
|
---|
51 | any other OpenSSL function calls.
|
---|
52 |
|
---|
53 | The B<opts> parameter specifies which aspects of libcrypto should be
|
---|
54 | initialised. Valid options are:
|
---|
55 |
|
---|
56 | =over 4
|
---|
57 |
|
---|
58 | =item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS
|
---|
59 |
|
---|
60 | Suppress automatic loading of the libcrypto error strings. This option is
|
---|
61 | not a default option. Once selected subsequent calls to
|
---|
62 | OPENSSL_init_crypto() with the option
|
---|
63 | B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored.
|
---|
64 |
|
---|
65 | =item OPENSSL_INIT_LOAD_CRYPTO_STRINGS
|
---|
66 |
|
---|
67 | Automatic loading of the libcrypto error strings. With this option the
|
---|
68 | library will automatically load the libcrypto error strings.
|
---|
69 | This option is a default option. Once selected subsequent calls to
|
---|
70 | OPENSSL_init_crypto() with the option
|
---|
71 | B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored.
|
---|
72 |
|
---|
73 | =item OPENSSL_INIT_ADD_ALL_CIPHERS
|
---|
74 |
|
---|
75 | With this option the library will automatically load and make available all
|
---|
76 | libcrypto ciphers. This option is a default option. Once selected subsequent
|
---|
77 | calls to OPENSSL_init_crypto() with the option
|
---|
78 | B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
|
---|
79 |
|
---|
80 | =item OPENSSL_INIT_ADD_ALL_DIGESTS
|
---|
81 |
|
---|
82 | With this option the library will automatically load and make available all
|
---|
83 | libcrypto digests. This option is a default option. Once selected subsequent
|
---|
84 | calls to OPENSSL_init_crypto() with the option
|
---|
85 | B<OPENSSL_INIT_NO_ADD_ALL_DIGESTS> will be ignored.
|
---|
86 |
|
---|
87 | =item OPENSSL_INIT_NO_ADD_ALL_CIPHERS
|
---|
88 |
|
---|
89 | With this option the library will suppress automatic loading of libcrypto
|
---|
90 | ciphers. This option is not a default option. Once selected subsequent
|
---|
91 | calls to OPENSSL_init_crypto() with the option
|
---|
92 | B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored.
|
---|
93 |
|
---|
94 | =item OPENSSL_INIT_NO_ADD_ALL_DIGESTS
|
---|
95 |
|
---|
96 | With this option the library will suppress automatic loading of libcrypto
|
---|
97 | digests. This option is not a default option. Once selected subsequent
|
---|
98 | calls to OPENSSL_init_crypto() with the option
|
---|
99 | B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored.
|
---|
100 |
|
---|
101 | =item OPENSSL_INIT_LOAD_CONFIG
|
---|
102 |
|
---|
103 | With this option an OpenSSL configuration file will be automatically loaded and
|
---|
104 | used by calling OPENSSL_config(). This is a default option.
|
---|
105 | Note that in OpenSSL 1.1.1 this was the default for libssl but not for
|
---|
106 | libcrypto (see L<OPENSSL_init_ssl(3)> for further details about libssl
|
---|
107 | initialisation).
|
---|
108 | In OpenSSL 1.1.0 this was a nondefault option for both libssl and libcrypto.
|
---|
109 | See the description of OPENSSL_INIT_new(), below.
|
---|
110 |
|
---|
111 | =item OPENSSL_INIT_NO_LOAD_CONFIG
|
---|
112 |
|
---|
113 | With this option the loading of OpenSSL configuration files will be suppressed.
|
---|
114 | It is the equivalent of calling OPENSSL_no_config(). This is not a default
|
---|
115 | option.
|
---|
116 |
|
---|
117 | =item OPENSSL_INIT_ASYNC
|
---|
118 |
|
---|
119 | With this option the library with automatically initialise the libcrypto async
|
---|
120 | sub-library (see L<ASYNC_start_job(3)>). This is a default option.
|
---|
121 |
|
---|
122 | =item OPENSSL_INIT_ENGINE_RDRAND
|
---|
123 |
|
---|
124 | With this option the library will automatically load and initialise the
|
---|
125 | RDRAND engine (if available). This not a default option and is deprecated
|
---|
126 | in OpenSSL 3.0.
|
---|
127 |
|
---|
128 | =item OPENSSL_INIT_ENGINE_DYNAMIC
|
---|
129 |
|
---|
130 | With this option the library will automatically load and initialise the
|
---|
131 | dynamic engine. This not a default option and is deprecated
|
---|
132 | in OpenSSL 3.0.
|
---|
133 |
|
---|
134 | =item OPENSSL_INIT_ENGINE_OPENSSL
|
---|
135 |
|
---|
136 | With this option the library will automatically load and initialise the
|
---|
137 | openssl engine. This not a default option and is deprecated
|
---|
138 | in OpenSSL 3.0.
|
---|
139 |
|
---|
140 | =item OPENSSL_INIT_ENGINE_CRYPTODEV
|
---|
141 |
|
---|
142 | With this option the library will automatically load and initialise the
|
---|
143 | cryptodev engine (if available). This not a default option and is deprecated
|
---|
144 | in OpenSSL 3.0.
|
---|
145 |
|
---|
146 | =item OPENSSL_INIT_ENGINE_CAPI
|
---|
147 |
|
---|
148 | With this option the library will automatically load and initialise the
|
---|
149 | CAPI engine (if available). This not a default option and is deprecated
|
---|
150 | in OpenSSL 3.0.
|
---|
151 |
|
---|
152 | =item OPENSSL_INIT_ENGINE_PADLOCK
|
---|
153 |
|
---|
154 | With this option the library will automatically load and initialise the
|
---|
155 | padlock engine (if available). This not a default option and is deprecated
|
---|
156 | in OpenSSL 3.0.
|
---|
157 |
|
---|
158 | =item OPENSSL_INIT_ENGINE_AFALG
|
---|
159 |
|
---|
160 | With this option the library will automatically load and initialise the
|
---|
161 | AFALG engine. This not a default option and is deprecated
|
---|
162 | in OpenSSL 3.0.
|
---|
163 |
|
---|
164 | =item OPENSSL_INIT_ENGINE_ALL_BUILTIN
|
---|
165 |
|
---|
166 | With this option the library will automatically load and initialise all the
|
---|
167 | built in engines listed above with the exception of the openssl and afalg
|
---|
168 | engines. This not a default option and is deprecated
|
---|
169 | in OpenSSL 3.0.
|
---|
170 |
|
---|
171 | =item OPENSSL_INIT_ATFORK
|
---|
172 |
|
---|
173 | With this option the library will register its fork handlers.
|
---|
174 | See OPENSSL_fork_prepare(3) for details.
|
---|
175 |
|
---|
176 | =item OPENSSL_INIT_NO_ATEXIT
|
---|
177 |
|
---|
178 | By default OpenSSL will attempt to clean itself up when the process exits via an
|
---|
179 | "atexit" handler. Using this option suppresses that behaviour. This means that
|
---|
180 | the application will have to clean up OpenSSL explicitly using
|
---|
181 | OPENSSL_cleanup().
|
---|
182 |
|
---|
183 | =back
|
---|
184 |
|
---|
185 | Multiple options may be combined together in a single call to
|
---|
186 | OPENSSL_init_crypto(). For example:
|
---|
187 |
|
---|
188 | OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
|
---|
189 | | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
|
---|
190 |
|
---|
191 | The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto
|
---|
192 | and libssl). All resources allocated by OpenSSL are freed. Typically there
|
---|
193 | should be no need to call this function directly as it is initiated
|
---|
194 | automatically on application exit. This is done via the standard C library
|
---|
195 | atexit() function. In the event that the application will close in a manner
|
---|
196 | that will not call the registered atexit() handlers then the application should
|
---|
197 | call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL
|
---|
198 | are discouraged from calling this function and should instead, typically, rely
|
---|
199 | on auto-deinitialisation. This is to avoid error conditions where both an
|
---|
200 | application and a library it depends on both use OpenSSL, and the library
|
---|
201 | deinitialises it before the application has finished using it.
|
---|
202 |
|
---|
203 | Once OPENSSL_cleanup() has been called the library cannot be reinitialised.
|
---|
204 | Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error
|
---|
205 | will be added to the error stack. Note that because initialisation has failed
|
---|
206 | OpenSSL error strings will not be available, only an error code. This code can
|
---|
207 | be put through the openssl errstr command line application to produce a human
|
---|
208 | readable error (see L<openssl-errstr(1)>).
|
---|
209 |
|
---|
210 | The OPENSSL_atexit() function enables the registration of a
|
---|
211 | function to be called during OPENSSL_cleanup(). Stop handlers are
|
---|
212 | called after deinitialisation of resources local to a thread, but before other
|
---|
213 | process wide resources are freed. In the event that multiple stop handlers are
|
---|
214 | registered, no guarantees are made about the order of execution.
|
---|
215 |
|
---|
216 | The OPENSSL_thread_stop_ex() function deallocates resources associated
|
---|
217 | with the current thread for the given OSSL_LIB_CTX B<ctx>. The B<ctx> parameter
|
---|
218 | can be NULL in which case the default OSSL_LIB_CTX is used.
|
---|
219 |
|
---|
220 | Typically, this function will be called automatically by the library when
|
---|
221 | the thread exits as long as the OSSL_LIB_CTX has not been freed before the thread
|
---|
222 | exits. If OSSL_LIB_CTX_free() is called OPENSSL_thread_stop_ex will be called
|
---|
223 | automatically for the current thread (but not any other threads that may have
|
---|
224 | used this OSSL_LIB_CTX).
|
---|
225 |
|
---|
226 | OPENSSL_thread_stop_ex should be called on all threads that will exit after the
|
---|
227 | OSSL_LIB_CTX is freed.
|
---|
228 | Typically this is not necessary for the default OSSL_LIB_CTX (because all
|
---|
229 | resources are cleaned up on library exit) except if thread local resources
|
---|
230 | should be freed before library exit, or under the circumstances described in
|
---|
231 | the NOTES section below.
|
---|
232 |
|
---|
233 | OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the
|
---|
234 | default OSSL_LIB_CTX is always used.
|
---|
235 |
|
---|
236 | The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a configuration file, as with
|
---|
237 | L<CONF_modules_load_file(3)> with NULL filename and application name and the
|
---|
238 | B<CONF_MFLAGS_IGNORE_MISSING_FILE>, B<CONF_MFLAGS_IGNORE_RETURN_CODES> and
|
---|
239 | B<CONF_MFLAGS_DEFAULT_SECTION> flags.
|
---|
240 | The filename, application name, and flags can be customized by providing a
|
---|
241 | non-null B<OPENSSL_INIT_SETTINGS> object.
|
---|
242 | The object can be allocated via B<OPENSSL_INIT_new()>.
|
---|
243 | The B<OPENSSL_INIT_set_config_filename()> function can be used to specify a
|
---|
244 | nondefault filename, which is copied and need not refer to persistent storage.
|
---|
245 | Similarly, OPENSSL_INIT_set_config_appname() can be used to specify a
|
---|
246 | nondefault application name.
|
---|
247 | Finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags.
|
---|
248 | If the B<CONF_MFLAGS_IGNORE_RETURN_CODES> flag is not included, any errors in
|
---|
249 | the configuration file will cause an error return from B<OPENSSL_init_crypto>
|
---|
250 | or indirectly L<OPENSSL_init_ssl(3)>.
|
---|
251 | The object can be released with OPENSSL_INIT_free() when done.
|
---|
252 |
|
---|
253 | =head1 NOTES
|
---|
254 |
|
---|
255 | Resources local to a thread are deallocated automatically when the thread exits
|
---|
256 | (e.g. in a pthreads environment, when pthread_exit() is called). On Windows
|
---|
257 | platforms this is done in response to a DLL_THREAD_DETACH message being sent to
|
---|
258 | the libcrypto32.dll entry point. Some windows functions may cause threads to exit
|
---|
259 | without sending this message (for example ExitProcess()). If the application
|
---|
260 | uses such functions, then the application must free up OpenSSL resources
|
---|
261 | directly via a call to OPENSSL_thread_stop() on each thread. Similarly this
|
---|
262 | message will also not be sent if OpenSSL is linked statically, and therefore
|
---|
263 | applications using static linking should also call OPENSSL_thread_stop() on each
|
---|
264 | thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the
|
---|
265 | threads are not destroyed until after FreeLibrary() is called then each thread
|
---|
266 | should call OPENSSL_thread_stop() prior to the FreeLibrary() call.
|
---|
267 |
|
---|
268 | On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is
|
---|
269 | multi-threaded and if dlclose() is subsequently called prior to the threads
|
---|
270 | being destroyed then OpenSSL will not be able to deallocate resources associated
|
---|
271 | with those threads. The application should either call OPENSSL_thread_stop() on
|
---|
272 | each thread prior to the dlclose() call, or alternatively the original dlopen()
|
---|
273 | call should use the RTLD_NODELETE flag (where available on the platform).
|
---|
274 |
|
---|
275 | =head1 RETURN VALUES
|
---|
276 |
|
---|
277 | The functions OPENSSL_init_crypto, OPENSSL_atexit() and
|
---|
278 | OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error.
|
---|
279 |
|
---|
280 | =head1 SEE ALSO
|
---|
281 |
|
---|
282 | L<OPENSSL_init_ssl(3)>
|
---|
283 |
|
---|
284 | =head1 HISTORY
|
---|
285 |
|
---|
286 | The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(),
|
---|
287 | OPENSSL_thread_stop(), OPENSSL_INIT_new(), OPENSSL_INIT_set_config_appname()
|
---|
288 | and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0.
|
---|
289 |
|
---|
290 | =head1 COPYRIGHT
|
---|
291 |
|
---|
292 | Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved.
|
---|
293 |
|
---|
294 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
---|
295 | this file except in compliance with the License. You can obtain a copy
|
---|
296 | in the file LICENSE in the source distribution or at
|
---|
297 | L<https://www.openssl.org/source/license.html>.
|
---|
298 |
|
---|
299 | =cut
|
---|