secure/lib/libcrypto/man/OPENSSL_init_crypto.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "OPENSSL_INIT_CRYPTO 3"
 136 .TH OPENSSL_INIT_CRYPTO 3 "2019-02-26" "1.1.1b" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 OPENSSL_INIT_new, OPENSSL_INIT_set_config_filename, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_set_config_file_flags, OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit, OPENSSL_thread_stop \- OpenSSL initialisation and deinitialisation functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/crypto.h>
 147 \&
 148 \& void OPENSSL_cleanup(void);
 149 \& int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
 150 \& int OPENSSL_atexit(void (*handler)(void));
 151 \& void OPENSSL_thread_stop(void);
 152 \&
 153 \& OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
 154 \& int OPENSSL_INIT_set_config_filename(OPENSSL_INIT_SETTINGS *init,
 155 \&                                      const char* filename);
 156 \& int OPENSSL_INIT_set_config_file_flags(OPENSSL_INIT_SETTINGS *init,
 157 \&                                        unsigned long flags);
 158 \& int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
 159 \&                                     const char* name);
 160 \& void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 During normal operation OpenSSL (libcrypto) will allocate various resources at
 165 start up that must, subsequently, be freed on close down of the library.
 166 Additionally some resources are allocated on a per thread basis (if the
 167 application is multi-threaded), and these resources must be freed prior to the
 168 thread closing.
 169 .PP
 170 As of version 1.1.0 OpenSSL will automatically allocate all resources that it
 171 needs so no explicit initialisation is required. Similarly it will also
 172 automatically deinitialise as required.
 173 .PP
 174 However, there may be situations when explicit initialisation is desirable or
 175 needed, for example when some non-default initialisation is required. The
 176 function \fBOPENSSL_init_crypto()\fR can be used for this purpose for
 177 libcrypto (see also \fBOPENSSL_init_ssl\fR\|(3) for the libssl
 178 equivalent).
 179 .PP
 180 Numerous internal OpenSSL functions call \fBOPENSSL_init_crypto()\fR.
 181 Therefore, in order to perform non-default initialisation,
 182 \&\fBOPENSSL_init_crypto()\fR \s-1MUST\s0 be called by application code prior to
 183 any other OpenSSL function calls.
 184 .PP
 185 The \fBopts\fR parameter specifies which aspects of libcrypto should be
 186 initialised. Valid options are:
 187 .IP "\s-1OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS\s0" 4
 188 .IX Item "OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS"
 189 Suppress automatic loading of the libcrypto error strings. This option is
 190 not a default option. Once selected subsequent calls to
 191 \&\fBOPENSSL_init_crypto()\fR with the option
 192 \&\fB\s-1OPENSSL_INIT_LOAD_CRYPTO_STRINGS\s0\fR will be ignored.
 193 .IP "\s-1OPENSSL_INIT_LOAD_CRYPTO_STRINGS\s0" 4
 194 .IX Item "OPENSSL_INIT_LOAD_CRYPTO_STRINGS"
 195 Automatic loading of the libcrypto error strings. With this option the
 196 library will automatically load the libcrypto error strings.
 197 This option is a default option. Once selected subsequent calls to
 198 \&\fBOPENSSL_init_crypto()\fR with the option
 199 \&\fB\s-1OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS\s0\fR will be ignored.
 200 .IP "\s-1OPENSSL_INIT_ADD_ALL_CIPHERS\s0" 4
 201 .IX Item "OPENSSL_INIT_ADD_ALL_CIPHERS"
 202 With this option the library will automatically load and make available all
 203 libcrypto ciphers. This option is a default option. Once selected subsequent
 204 calls to \fBOPENSSL_init_crypto()\fR with the option
 205 \&\fB\s-1OPENSSL_INIT_NO_ADD_ALL_CIPHERS\s0\fR will be ignored.
 206 .IP "\s-1OPENSSL_INIT_ADD_ALL_DIGESTS\s0" 4
 207 .IX Item "OPENSSL_INIT_ADD_ALL_DIGESTS"
 208 With this option the library will automatically load and make available all
 209 libcrypto digests. This option is a default option. Once selected subsequent
 210 calls to \fBOPENSSL_init_crypto()\fR with the option
 211 \&\fB\s-1OPENSSL_INIT_NO_ADD_ALL_CIPHERS\s0\fR will be ignored.
 212 .IP "\s-1OPENSSL_INIT_NO_ADD_ALL_CIPHERS\s0" 4
 213 .IX Item "OPENSSL_INIT_NO_ADD_ALL_CIPHERS"
 214 With this option the library will suppress automatic loading of libcrypto
 215 ciphers. This option is not a default option. Once selected subsequent
 216 calls to \fBOPENSSL_init_crypto()\fR with the option
 217 \&\fB\s-1OPENSSL_INIT_ADD_ALL_CIPHERS\s0\fR will be ignored.
 218 .IP "\s-1OPENSSL_INIT_NO_ADD_ALL_DIGESTS\s0" 4
 219 .IX Item "OPENSSL_INIT_NO_ADD_ALL_DIGESTS"
 220 With this option the library will suppress automatic loading of libcrypto
 221 digests. This option is not a default option. Once selected subsequent
 222 calls to \fBOPENSSL_init_crypto()\fR with the option
 223 \&\fB\s-1OPENSSL_INIT_ADD_ALL_DIGESTS\s0\fR will be ignored.
 224 .IP "\s-1OPENSSL_INIT_LOAD_CONFIG\s0" 4
 225 .IX Item "OPENSSL_INIT_LOAD_CONFIG"
 226 With this option an OpenSSL configuration file will be automatically loaded and
 227 used by calling \fBOPENSSL_config()\fR. This is not a default option for libcrypto.
 228 As of OpenSSL 1.1.1 this is a default option for libssl (see
 229 \&\fBOPENSSL_init_ssl\fR\|(3) for further details about libssl initialisation). See the
 230 description of \fBOPENSSL_INIT_new()\fR, below.
 231 .IP "\s-1OPENSSL_INIT_NO_LOAD_CONFIG\s0" 4
 232 .IX Item "OPENSSL_INIT_NO_LOAD_CONFIG"
 233 With this option the loading of OpenSSL configuration files will be suppressed.
 234 It is the equivalent of calling \fBOPENSSL_no_config()\fR. This is not a default
 235 option.
 236 .IP "\s-1OPENSSL_INIT_ASYNC\s0" 4
 237 .IX Item "OPENSSL_INIT_ASYNC"
 238 With this option the library with automatically initialise the libcrypto async
 239 sub-library (see \fBASYNC_start_job\fR\|(3)). This is a default option.
 240 .IP "\s-1OPENSSL_INIT_ENGINE_RDRAND\s0" 4
 241 .IX Item "OPENSSL_INIT_ENGINE_RDRAND"
 242 With this option the library will automatically load and initialise the
 243 \&\s-1RDRAND\s0 engine (if available). This not a default option.
 244 .IP "\s-1OPENSSL_INIT_ENGINE_DYNAMIC\s0" 4
 245 .IX Item "OPENSSL_INIT_ENGINE_DYNAMIC"
 246 With this option the library will automatically load and initialise the
 247 dynamic engine. This not a default option.
 248 .IP "\s-1OPENSSL_INIT_ENGINE_OPENSSL\s0" 4
 249 .IX Item "OPENSSL_INIT_ENGINE_OPENSSL"
 250 With this option the library will automatically load and initialise the
 251 openssl engine. This not a default option.
 252 .IP "\s-1OPENSSL_INIT_ENGINE_CRYPTODEV\s0" 4
 253 .IX Item "OPENSSL_INIT_ENGINE_CRYPTODEV"
 254 With this option the library will automatically load and initialise the
 255 cryptodev engine (if available). This not a default option.
 256 .IP "\s-1OPENSSL_INIT_ENGINE_CAPI\s0" 4
 257 .IX Item "OPENSSL_INIT_ENGINE_CAPI"
 258 With this option the library will automatically load and initialise the
 259 \&\s-1CAPI\s0 engine (if available). This not a default option.
 260 .IP "\s-1OPENSSL_INIT_ENGINE_PADLOCK\s0" 4
 261 .IX Item "OPENSSL_INIT_ENGINE_PADLOCK"
 262 With this option the library will automatically load and initialise the
 263 padlock engine (if available). This not a default option.
 264 .IP "\s-1OPENSSL_INIT_ENGINE_AFALG\s0" 4
 265 .IX Item "OPENSSL_INIT_ENGINE_AFALG"
 266 With this option the library will automatically load and initialise the
 267 \&\s-1AFALG\s0 engine. This not a default option.
 268 .IP "\s-1OPENSSL_INIT_ENGINE_ALL_BUILTIN\s0" 4
 269 .IX Item "OPENSSL_INIT_ENGINE_ALL_BUILTIN"
 270 With this option the library will automatically load and initialise all the
 271 built in engines listed above with the exception of the openssl and afalg
 272 engines. This not a default option.
 273 .IP "\s-1OPENSSL_INIT_ATFORK\s0" 4
 274 .IX Item "OPENSSL_INIT_ATFORK"
 275 With this option the library will register its fork handlers.
 276 See \fBOPENSSL_fork_prepare\fR\|(3) for details.
 277 .IP "\s-1OPENSSL_INIT_NO_ATEXIT\s0" 4
 278 .IX Item "OPENSSL_INIT_NO_ATEXIT"
 279 By default OpenSSL will attempt to clean itself up when the process exits via an
 280 \&\*(L"atexit\*(R" handler. Using this option suppresses that behaviour. This means that
 281 the application will have to clean up OpenSSL explicitly using
 282 \&\fBOPENSSL_cleanup()\fR.
 283 .PP
 284 Multiple options may be combined together in a single call to
 285 \&\fBOPENSSL_init_crypto()\fR. For example:
 286 .PP
 287 .Vb 2
 288 \& OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
 289 \&                     | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
 290 .Ve
 291 .PP
 292 The \fBOPENSSL_cleanup()\fR function deinitialises OpenSSL (both libcrypto
 293 and libssl). All resources allocated by OpenSSL are freed. Typically there
 294 should be no need to call this function directly as it is initiated
 295 automatically on application exit. This is done via the standard C library
 296 \&\fBatexit()\fR function. In the event that the application will close in a manner
 297 that will not call the registered \fBatexit()\fR handlers then the application should
 298 call \fBOPENSSL_cleanup()\fR directly. Developers of libraries using OpenSSL
 299 are discouraged from calling this function and should instead, typically, rely
 300 on auto-deinitialisation. This is to avoid error conditions where both an
 301 application and a library it depends on both use OpenSSL, and the library
 302 deinitialises it before the application has finished using it.
 303 .PP
 304 Once \fBOPENSSL_cleanup()\fR has been called the library cannot be reinitialised.
 305 Attempts to call \fBOPENSSL_init_crypto()\fR will fail and an \s-1ERR_R_INIT_FAIL\s0 error
 306 will be added to the error stack. Note that because initialisation has failed
 307 OpenSSL error strings will not be available, only an error code. This code can
 308 be put through the openssl errstr command line application to produce a human
 309 readable error (see \fBerrstr\fR\|(1)).
 310 .PP
 311 The \fBOPENSSL_atexit()\fR function enables the registration of a
 312 function to be called during \fBOPENSSL_cleanup()\fR. Stop handlers are
 313 called after deinitialisation of resources local to a thread, but before other
 314 process wide resources are freed. In the event that multiple stop handlers are
 315 registered, no guarantees are made about the order of execution.
 316 .PP
 317 The \fBOPENSSL_thread_stop()\fR function deallocates resources associated
 318 with the current thread. Typically this function will be called automatically by
 319 the library when the thread exits. This should only be called directly if
 320 resources should be freed at an earlier time, or under the circumstances
 321 described in the \s-1NOTES\s0 section below.
 322 .PP
 323 The \fB\s-1OPENSSL_INIT_LOAD_CONFIG\s0\fR flag will load a configuration file, as with
 324 \&\fBCONF_modules_load_file\fR\|(3) with \s-1NULL\s0 filename and application name and the
 325 \&\fB\s-1CONF_MFLAGS_IGNORE_MISSING_FILE\s0\fR, \fB\s-1CONF_MFLAGS_IGNORE_RETURN_CODES\s0\fR  and
 326 \&\fB\s-1CONF_MFLAGS_DEFAULT_SECTION\s0\fR flags.
 327 The filename, application name, and flags can be customized by providing a
 328 non-null \fB\s-1OPENSSL_INIT_SETTINGS\s0\fR object.
 329 The object can be allocated via \fB\fBOPENSSL_init_new()\fB\fR.
 330 The \fB\fBOPENSSL_INIT_set_config_filename()\fB\fR function can be used to specify a
 331 non-default filename, which is copied and need not refer to persistent storage.
 332 Similarly, \fBOPENSSL_INIT_set_config_appname()\fR can be used to specify a
 333 non-default application name.
 334 Finally, OPENSSL_INIT_set_file_flags can be used to specify non-default flags.
 335 If the \fB\s-1CONF_MFLAGS_IGNORE_RETURN_CODES\s0\fR flag is not included, any errors in
 336 the configuration file will cause an error return from \fBOPENSSL_init_crypto\fR
 337 or indirectly \fBOPENSSL_init_ssl\fR\|(3).
 338 The object can be released with \fBOPENSSL_INIT_free()\fR when done.
 339 .SH "NOTES"
 340 .IX Header "NOTES"
 341 Resources local to a thread are deallocated automatically when the thread exits
 342 (e.g. in a pthreads environment, when \fBpthread_exit()\fR is called). On Windows
 343 platforms this is done in response to a \s-1DLL_THREAD_DETACH\s0 message being sent to
 344 the libcrypto32.dll entry point. Some windows functions may cause threads to exit
 345 without sending this message (for example \fBExitProcess()\fR). If the application
 346 uses such functions, then the application must free up OpenSSL resources
 347 directly via a call to \fBOPENSSL_thread_stop()\fR on each thread. Similarly this
 348 message will also not be sent if OpenSSL is linked statically, and therefore
 349 applications using static linking should also call \fBOPENSSL_thread_stop()\fR on each
 350 thread. Additionally if OpenSSL is loaded dynamically via \fBLoadLibrary()\fR and the
 351 threads are not destroyed until after \fBFreeLibrary()\fR is called then each thread
 352 should call \fBOPENSSL_thread_stop()\fR prior to the \fBFreeLibrary()\fR call.
 353 .PP
 354 On Linux/Unix where OpenSSL has been loaded via \fBdlopen()\fR and the application is
 355 multi-threaded and if \fBdlclose()\fR is subsequently called prior to the threads
 356 being destroyed then OpenSSL will not be able to deallocate resources associated
 357 with those threads. The application should either call \fBOPENSSL_thread_stop()\fR on
 358 each thread prior to the \fBdlclose()\fR call, or alternatively the original \fBdlopen()\fR
 359 call should use the \s-1RTLD_NODELETE\s0 flag (where available on the platform).
 360 .SH "RETURN VALUES"
 361 .IX Header "RETURN VALUES"
 362 The functions OPENSSL_init_crypto, \fBOPENSSL_atexit()\fR and
 363 \&\fBOPENSSL_INIT_set_config_appname()\fR return 1 on success or 0 on error.
 364 .SH "SEE ALSO"
 365 .IX Header "SEE ALSO"
 366 \&\fBOPENSSL_init_ssl\fR\|(3)
 367 .SH "HISTORY"
 368 .IX Header "HISTORY"
 369 The \fBOPENSSL_init_crypto()\fR, \fBOPENSSL_cleanup()\fR, \fBOPENSSL_atexit()\fR,
 370 \&\fBOPENSSL_thread_stop()\fR, \fBOPENSSL_INIT_new()\fR, \fBOPENSSL_INIT_set_config_appname()\fR
 371 and \fBOPENSSL_INIT_free()\fR functions were added in OpenSSL 1.1.0.
 372 .SH "COPYRIGHT"
 373 .IX Header "COPYRIGHT"
 374 Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved.
 375 .PP
 376 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 377 this file except in compliance with the License.  You can obtain a copy
 378 in the file \s-1LICENSE\s0 in the source distribution or at
 379 <https://www.openssl.org/source/license.html>.