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