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