]>
Commit | Line | Data |
---|---|---|
8b75603c MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
df1f538f VD |
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, | |
ff6da65e | 8 | OPENSSL_thread_stop_ex, OPENSSL_thread_stop - OpenSSL initialisation |
df1f538f | 9 | and deinitialisation functions |
8b75603c MC |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/crypto.h> | |
14 | ||
f672aee4 | 15 | void OPENSSL_cleanup(void); |
0fc32b07 | 16 | int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); |
f672aee4 | 17 | int OPENSSL_atexit(void (*handler)(void)); |
ff6da65e | 18 | void OPENSSL_thread_stop_ex(OPENSSL_CTX *ctx); |
f672aee4 | 19 | void OPENSSL_thread_stop(void); |
8b75603c | 20 | |
1722496f | 21 | OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void); |
df1f538f VD |
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); | |
cda3ae5b RS |
26 | int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init, |
27 | const char* name); | |
dae00d63 | 28 | void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init); |
7253fd55 | 29 | |
8b75603c MC |
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 | ||
8f6a5c56 | 42 | However, there may be situations when explicit initialisation is desirable or |
8b75603c | 43 | needed, for example when some non-default initialisation is required. The |
f672aee4 RS |
44 | function OPENSSL_init_crypto() can be used for this purpose for |
45 | libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl | |
35d8fa56 MC |
46 | equivalent). |
47 | ||
f672aee4 | 48 | Numerous internal OpenSSL functions call OPENSSL_init_crypto(). |
35d8fa56 | 49 | Therefore, in order to perform non-default initialisation, |
f672aee4 | 50 | OPENSSL_init_crypto() MUST be called by application code prior to |
35d8fa56 | 51 | any other OpenSSL function calls. |
8b75603c MC |
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 | ||
f672aee4 | 60 | Suppress automatic loading of the libcrypto error strings. This option is |
8b75603c | 61 | not a default option. Once selected subsequent calls to |
f672aee4 RS |
62 | OPENSSL_init_crypto() with the option |
63 | B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored. | |
8b75603c MC |
64 | |
65 | =item OPENSSL_INIT_LOAD_CRYPTO_STRINGS | |
66 | ||
67 | Automatic loading of the libcrypto error strings. With this option the | |
f672aee4 RS |
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 | |
8b75603c MC |
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 | |
f672aee4 | 77 | calls to OPENSSL_init_crypto() with the option |
8b75603c MC |
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 | |
f672aee4 | 84 | calls to OPENSSL_init_crypto() with the option |
8b75603c MC |
85 | B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> 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 | |
f672aee4 | 91 | calls to OPENSSL_init_crypto() with the option |
8b75603c MC |
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 | |
f672aee4 | 98 | calls to OPENSSL_init_crypto() with the option |
8b75603c MC |
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 | |
29dc6e00 MC |
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 non-default option for both libssl and libcrypto. | |
109 | See the description of OPENSSL_INIT_new(), below. | |
8b75603c MC |
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. | |
126 | ||
127 | =item OPENSSL_INIT_ENGINE_DYNAMIC | |
128 | ||
129 | With this option the library will automatically load and initialise the | |
130 | dynamic engine. This not a default option. | |
131 | ||
132 | =item OPENSSL_INIT_ENGINE_OPENSSL | |
133 | ||
134 | With this option the library will automatically load and initialise the | |
135 | openssl engine. This not a default option. | |
136 | ||
137 | =item OPENSSL_INIT_ENGINE_CRYPTODEV | |
138 | ||
139 | With this option the library will automatically load and initialise the | |
140 | cryptodev engine (if available). This not a default option. | |
141 | ||
142 | =item OPENSSL_INIT_ENGINE_CAPI | |
143 | ||
144 | With this option the library will automatically load and initialise the | |
145 | CAPI engine (if available). This not a default option. | |
146 | ||
147 | =item OPENSSL_INIT_ENGINE_PADLOCK | |
148 | ||
149 | With this option the library will automatically load and initialise the | |
150 | padlock engine (if available). This not a default option. | |
151 | ||
eb2b9892 | 152 | =item OPENSSL_INIT_ENGINE_AFALG |
8b75603c MC |
153 | |
154 | With this option the library will automatically load and initialise the | |
eb2b9892 | 155 | AFALG engine. This not a default option. |
8b75603c MC |
156 | |
157 | =item OPENSSL_INIT_ENGINE_ALL_BUILTIN | |
158 | ||
159 | With this option the library will automatically load and initialise all the | |
eb2b9892 | 160 | built in engines listed above with the exception of the openssl and afalg |
8b75603c MC |
161 | engines. This not a default option. |
162 | ||
b5319bdb | 163 | =item OPENSSL_INIT_ATFORK |
2915fe19 | 164 | |
b5319bdb | 165 | With this option the library will register its fork handlers. |
2915fe19 RS |
166 | See OPENSSL_fork_prepare(3) for details. |
167 | ||
8f6a5c56 MC |
168 | =item OPENSSL_INIT_NO_ATEXIT |
169 | ||
170 | By default OpenSSL will attempt to clean itself up when the process exits via an | |
171 | "atexit" handler. Using this option suppresses that behaviour. This means that | |
172 | the application will have to clean up OpenSSL explicitly using | |
173 | OPENSSL_cleanup(). | |
174 | ||
8b75603c MC |
175 | =back |
176 | ||
177 | Multiple options may be combined together in a single call to | |
9cc55ddd | 178 | OPENSSL_init_crypto(). For example: |
8b75603c | 179 | |
9cc55ddd MC |
180 | OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS |
181 | | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL); | |
8b75603c | 182 | |
f672aee4 | 183 | The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto |
8b75603c MC |
184 | and libssl). All resources allocated by OpenSSL are freed. Typically there |
185 | should be no need to call this function directly as it is initiated | |
186 | automatically on application exit. This is done via the standard C library | |
9e183d22 | 187 | atexit() function. In the event that the application will close in a manner |
8b75603c | 188 | that will not call the registered atexit() handlers then the application should |
f672aee4 | 189 | call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL |
8b75603c MC |
190 | are discouraged from calling this function and should instead, typically, rely |
191 | on auto-deinitialisation. This is to avoid error conditions where both an | |
192 | application and a library it depends on both use OpenSSL, and the library | |
193 | deinitialises it before the application has finished using it. | |
194 | ||
9cc55ddd MC |
195 | Once OPENSSL_cleanup() has been called the library cannot be reinitialised. |
196 | Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error | |
197 | will be added to the error stack. Note that because initialisation has failed | |
198 | OpenSSL error strings will not be available, only an error code. This code can | |
199 | be put through the openssl errstr command line application to produce a human | |
200 | readable error (see L<errstr(1)>). | |
201 | ||
f672aee4 RS |
202 | The OPENSSL_atexit() function enables the registration of a |
203 | function to be called during OPENSSL_cleanup(). Stop handlers are | |
8b75603c MC |
204 | called after deinitialisation of resources local to a thread, but before other |
205 | process wide resources are freed. In the event that multiple stop handlers are | |
206 | registered, no guarantees are made about the order of execution. | |
207 | ||
ff6da65e MC |
208 | The OPENSSL_thread_stop_ex() function deallocates resources associated |
209 | with the current thread for the given OPENSSL_CTX B<ctx>. The B<ctx> parameter | |
210 | can be NULL in which case the default OPENSSL_CTX is used. | |
211 | ||
212 | Typically, this function will be called automatically by the library when | |
213 | the thread exits as long as the OPENSSL_CTX has not been freed before the thread | |
214 | exits. If OPENSSL_CTX_free() is called OPENSSL_thread_stop_ex will be called | |
215 | automatically for the current thread (but not any other threads that may have | |
216 | used this OPENSSL_CTX). | |
217 | ||
218 | OPENSSL_thread_stop_ex should be called on all threads that will exit after the | |
219 | OPENSSL_CTX is freed. | |
220 | Typically this is not necessary for the default OPENSSL_CTX (because all | |
221 | resources are cleaned up on library exit) except if thread local resources | |
222 | should be freed before library exit, or under the circumstances described in | |
223 | the NOTES section below. | |
224 | ||
225 | OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the | |
226 | default OPENSSL_CTX is always used. | |
8b75603c | 227 | |
df1f538f VD |
228 | The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a configuration file, as with |
229 | L<CONF_modules_load_file(3)> with NULL filename and application name and the | |
230 | B<CONF_MFLAGS_IGNORE_MISSING_FILE>, B<CONF_MFLAGS_IGNORE_RETURN_CODES> and | |
231 | B<CONF_MFLAGS_DEFAULT_SECTION> flags. | |
232 | The filename, application name, and flags can be customized by providing a | |
233 | non-null B<OPENSSL_INIT_SETTINGS> object. | |
29dc6e00 | 234 | The object can be allocated via B<OPENSSL_INIT_new()>. |
df1f538f VD |
235 | The B<OPENSSL_INIT_set_config_filename()> function can be used to specify a |
236 | non-default filename, which is copied and need not refer to persistent storage. | |
237 | Similarly, OPENSSL_INIT_set_config_appname() can be used to specify a | |
238 | non-default application name. | |
239 | Finally, OPENSSL_INIT_set_file_flags can be used to specify non-default flags. | |
240 | If the B<CONF_MFLAGS_IGNORE_RETURN_CODES> flag is not included, any errors in | |
241 | the configuration file will cause an error return from B<OPENSSL_init_crypto> | |
242 | or indirectly L<OPENSSL_init_ssl(3)>. | |
243 | The object can be released with OPENSSL_INIT_free() when done. | |
7253fd55 | 244 | |
8b75603c MC |
245 | =head1 NOTES |
246 | ||
247 | Resources local to a thread are deallocated automatically when the thread exits | |
248 | (e.g. in a pthreads environment, when pthread_exit() is called). On Windows | |
249 | platforms this is done in response to a DLL_THREAD_DETACH message being sent to | |
6928b617 | 250 | the libcrypto32.dll entry point. Some windows functions may cause threads to exit |
8b75603c MC |
251 | without sending this message (for example ExitProcess()). If the application |
252 | uses such functions, then the application must free up OpenSSL resources | |
c796e021 MC |
253 | directly via a call to OPENSSL_thread_stop() on each thread. Similarly this |
254 | message will also not be sent if OpenSSL is linked statically, and therefore | |
255 | applications using static linking should also call OPENSSL_thread_stop() on each | |
256 | thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the | |
257 | threads are not destroyed until after FreeLibrary() is called then each thread | |
258 | should call OPENSSL_thread_stop() prior to the FreeLibrary() call. | |
259 | ||
260 | On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is | |
261 | multi-threaded and if dlclose() is subsequently called prior to the threads | |
262 | being destroyed then OpenSSL will not be able to deallocate resources associated | |
263 | with those threads. The application should either call OPENSSL_thread_stop() on | |
264 | each thread prior to the dlclose() call, or alternatively the original dlopen() | |
265 | call should use the RTLD_NODELETE flag (where available on the platform). | |
8b75603c MC |
266 | |
267 | =head1 RETURN VALUES | |
268 | ||
dae00d63 | 269 | The functions OPENSSL_init_crypto, OPENSSL_atexit() and |
cda3ae5b | 270 | OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error. |
8b75603c MC |
271 | |
272 | =head1 SEE ALSO | |
273 | ||
f672aee4 | 274 | L<OPENSSL_init_ssl(3)> |
8b75603c MC |
275 | |
276 | =head1 HISTORY | |
277 | ||
f672aee4 | 278 | The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(), |
1722496f | 279 | OPENSSL_thread_stop(), OPENSSL_INIT_new(), OPENSSL_INIT_set_config_appname() |
dae00d63 | 280 | and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. |
8b75603c | 281 | |
e2f92610 RS |
282 | =head1 COPYRIGHT |
283 | ||
28428130 | 284 | Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 285 | |
4746f25a | 286 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
287 | this file except in compliance with the License. You can obtain a copy |
288 | in the file LICENSE in the source distribution or at | |
289 | L<https://www.openssl.org/source/license.html>. | |
290 | ||
291 | =cut |