Updates for auto init/deinit review comments
[openssl.git] / doc / crypto / OPENSSL_INIT_crypto_library_start.pod
1 =pod
2
3 =head1 NAME
4
5 OPENSSL_INIT_crypto_library_start, OPENSSL_INIT_library_stop,
6 OPENSSL_INIT_register_stop_handler, OPENSSL_INIT_thread_stop - OpenSSL
7 initialisation and deinitialisation functions
8
9 =head1 SYNOPSIS
10
11  #include <openssl/crypto.h>
12
13  void OPENSSL_INIT_library_stop(void);
14  void OPENSSL_INIT_crypto_library_start(uint64_t opts,
15                                         const OPENSSL_INIT_SETTINGS *settings);
16  int OPENSSL_INIT_register_stop_handler(void (*handler)(void));
17  void OPENSSL_INIT_thread_stop(void);
18
19 =head1 DESCRIPTION
20
21 During normal operation OpenSSL (libcrypto) will allocate various resources at
22 start up that must, subsequently, be freed on close down of the library.
23 Additionally some resources are allocated on a per thread basis (if the
24 application is multi-threaded), and these resources must be freed prior to the
25 thread closing.
26
27 As of version 1.1.0 OpenSSL will automatically allocate all resources that it
28 needs so no explicit initialisation is required. Similarly it will also
29 automatically deinitialise as required.
30
31 However, there way be situations when explicit initialisation is desirable or
32 needed, for example when some non-default initialisation is required. The
33 function OPENSSL_INIT_crypto_library_start() can be used for this purpose for
34 libcrypto (see also L<OPENSSL_INIT_ssl_library_start(3)> for the libssl
35 equivalent).
36
37 Numerous internal OpenSSL functions call OPENSSL_INIT_crypto_library_start().
38 Therefore, in order to perform non-default initialisation,
39 OPENSSL_INIT_crypto_library_start() MUST be called by application code prior to
40 any other OpenSSL function calls.
41
42 The B<opts> parameter specifies which aspects of libcrypto should be
43 initialised. Valid options are:
44
45 =over 4
46
47 =item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS
48
49 Suppress automatic loading of the libcrypto error strings. With this option the
50 library will not automatically call ERR_load_crypto_strings(). This option is
51 not a default option. Once selected subsequent calls to
52 OPENSSL_INIT_crypto_library_start() with the option
53 B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored. Applications may call
54 ERR_load_crypto_strings() directly if they wish even if this option has been
55 selected. If they do so then they must also explicitly call ERR_free_strings()
56 on application close down.
57
58 =item OPENSSL_INIT_LOAD_CRYPTO_STRINGS
59
60 Automatic loading of the libcrypto error strings. With this option the
61 library will automatically call ERR_load_crypto_strings(). This option is a
62 default option. Once selected subsequent calls to
63 OPENSSL_INIT_crypto_library_start() with the option
64 B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored.
65
66 =item OPENSSL_INIT_ADD_ALL_CIPHERS
67
68 With this option the library will automatically load and make available all
69 libcrypto ciphers. This option is a default option. Once selected subsequent
70 calls to OPENSSL_INIT_crypto_library_start() with the option
71 B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
72
73 =item OPENSSL_INIT_ADD_ALL_DIGESTS
74
75 With this option the library will automatically load and make available all
76 libcrypto digests. This option is a default option. Once selected subsequent
77 calls to OPENSSL_INIT_crypto_library_start() with the option
78 B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
79
80 =item OPENSSL_INIT_NO_ADD_ALL_CIPHERS
81
82 With this option the library will suppress automatic loading of libcrypto
83 ciphers. This option is not a default option. Once selected subsequent
84 calls to OPENSSL_INIT_crypto_library_start() with the option
85 B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored.
86
87 =item OPENSSL_INIT_NO_ADD_ALL_DIGESTS
88
89 With this option the library will suppress automatic loading of libcrypto
90 digests. This option is not a default option. Once selected subsequent
91 calls to OPENSSL_INIT_crypto_library_start() with the option
92 B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored.
93
94 =item OPENSSL_INIT_LOAD_CONFIG
95
96 With this option an OpenSSL configuration file will be automatically loaded and
97 used by calling OPENSSL_config(). This is not a default option.
98
99 =item OPENSSL_INIT_NO_LOAD_CONFIG
100
101 With this option the loading of OpenSSL configuration files will be suppressed.
102 It is the equivalent of calling OPENSSL_no_config(). This is not a default
103 option.
104
105 =item OPENSSL_INIT_ASYNC
106
107 With this option the library with automatically initialise the libcrypto async
108 sub-library (see L<ASYNC_start_job(3)>). This is a default option.
109
110 =item OPENSSL_INIT_ENGINE_RDRAND
111
112 With this option the library will automatically load and initialise the
113 RDRAND engine (if available). This not a default option.
114
115 =item OPENSSL_INIT_ENGINE_DYNAMIC
116
117 With this option the library will automatically load and initialise the
118 dynamic engine. This not a default option.
119
120 =item OPENSSL_INIT_ENGINE_OPENSSL
121
122 With this option the library will automatically load and initialise the
123 openssl engine. This not a default option.
124
125 =item OPENSSL_INIT_ENGINE_CRYPTODEV
126
127 With this option the library will automatically load and initialise the
128 cryptodev engine (if available). This not a default option.
129
130 =item OPENSSL_INIT_ENGINE_CAPI
131
132 With this option the library will automatically load and initialise the
133 CAPI engine (if available). This not a default option.
134
135 =item OPENSSL_INIT_ENGINE_PADLOCK
136
137 With this option the library will automatically load and initialise the
138 padlock engine (if available). This not a default option.
139
140 =item OPENSSL_INIT_ENGINE_DASYNC
141
142 With this option the library will automatically load and initialise the
143 DASYNC engine. This not a default option.
144
145 =item OPENSSL_INIT_ENGINE_ALL_BUILTIN
146
147 With this option the library will automatically load and initialise all the
148 built in engines listed above with the exception of the openssl and dasync
149 engines. This not a default option.
150
151 =back
152
153 Multiple options may be combined together in a single call to
154 OPENSSL_INIT_start_library(). For example:
155
156  OPENSSL_INIT_start_library(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
157                             | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
158
159
160 The B<settings> parameter to OPENSSL_INIT_start_library() may be used to
161 provide optional settings values to an option. Currently the only option this
162 applies to is OPENSSL_INIT_LOAD_CONFIG. This provides the optional
163 OPENSSL_INIT_SET_CONF_FILENAME parameter to provide a filename to load
164 configuration from. If no filename is provided then the system default
165 configuration file is assumed. For example
166
167  const OPENSSL_INIT_SETTINGS settings[2] = {
168      { OPENSSL_INIT_SET_CONF_FILENAME, .value.type_string = "myconf.cnf" },
169      { OPENSSL_INIT_SET_END, .value.type_int = 0 }
170  };
171  OPENSSL_INIT_crypto_library_start(OPENSSL_INIT_LOAD_CONFIG, settings);
172
173 The B<settings> parameter must be an array of OPENSSL_INIT_SETTINGS values
174 terminated with an OPENSSL_INIT_SET_END entry.
175
176 The OPENSSL_INIT_library_stop() function deinitialises OpenSSL (both libcrypto
177 and libssl). All resources allocated by OpenSSL are freed. Typically there
178 should be no need to call this function directly as it is initiated
179 automatically on application exit. This is done via the standard C library
180 L<atexit(3)> function. In the event that the application will close in a manner
181 that will not call the registered atexit() handlers then the application should
182 call OPENSSL_INIT_library_stop() directly. Developers of libraries using OpenSSL
183 are discouraged from calling this function and should instead, typically, rely
184 on auto-deinitialisation. This is to avoid error conditions where both an
185 application and a library it depends on both use OpenSSL, and the library
186 deinitialises it before the application has finished using it.
187
188 The OPENSSL_INIT_register_stop_handler() function enables the registration of a
189 function to be called during OPENSSL_INIT_library_stop(). Stop handlers are
190 called after deinitialisation of resources local to a thread, but before other
191 process wide resources are freed. In the event that multiple stop handlers are
192 registered, no guarantees are made about the order of execution.
193
194 The OPENSSL_INIT_thread_stop() function deallocates resources associated
195 with the current thread. Typically this function will be called automatically by
196 the library when the thread exits. This should only be called directly if
197 resources should be freed at an earlier time, or under the circumstances
198 described in the NOTES section below.
199
200 =head1 NOTES
201
202 Resources local to a thread are deallocated automatically when the thread exits
203 (e.g. in a pthreads environment, when pthread_exit() is called). On Windows
204 platforms this is done in response to a DLL_THREAD_DETACH message being sent to
205 the libeay32.dll entry point. Some windows functions may cause threads to exit
206 without sending this message (for example ExitProcess()). If the application
207 uses such functions, then the application must free up OpenSSL resources
208 directly via a call to OPENSSL_INIT_thread_stop(). Similarly this message will
209 also not be sent if OpenSSL is linked statically, and therefore applications
210 using static linking should also call OPENSSL_INIT_thread_stop().
211
212 =head1 RETURN VALUES
213
214 The function OPENSSL_INIT_register_stop_handler() returns 1 on success or 0 on
215 error.
216
217 =head1 SEE ALSO
218
219 L<OPENSSL_INIT_ssl_library_start(3)>
220
221 =head1 HISTORY
222
223 The OPENSSL_INIT_library_stop, OPENSSL_INIT_crypto_library_start,
224 OPENSSL_INIT_register_stop_handler and OPENSSL_INIT_thread_stop functions were
225 added in OpenSSL 1.1.0.
226
227 =cut