secure/lib/libcrypto/man/OPENSSL_init_crypto.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "OPENSSL_INIT_CRYPTO 3"
 132 .TH OPENSSL_INIT_CRYPTO 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 OPENSSL_INIT_new, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit, OPENSSL_thread_stop \- OpenSSL initialisation and deinitialisation functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/crypto.h>
 143 \&
 144 \& void OPENSSL_cleanup(void);
 145 \& int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
 146 \& int OPENSSL_atexit(void (*handler)(void));
 147 \& void OPENSSL_thread_stop(void);
 148 \&
 149 \& OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
 150 \& int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
 151 \&                                     const char* name);
 152 \& void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 During normal operation OpenSSL (libcrypto) will allocate various resources at
 157 start up that must, subsequently, be freed on close down of the library.
 158 Additionally some resources are allocated on a per thread basis (if the
 159 application is multi-threaded), and these resources must be freed prior to the
 160 thread closing.
 161 .PP
 162 As of version 1.1.0 OpenSSL will automatically allocate all resources that it
 163 needs so no explicit initialisation is required. Similarly it will also
 164 automatically deinitialise as required.
 165 .PP
 166 However, there way be situations when explicit initialisation is desirable or
 167 needed, for example when some non-default initialisation is required. The
 168 function \fIOPENSSL_init_crypto()\fR can be used for this purpose for
 169 libcrypto (see also \fIOPENSSL_init_ssl\fR\|(3) for the libssl
 170 equivalent).
 171 .PP
 172 Numerous internal OpenSSL functions call \fIOPENSSL_init_crypto()\fR.
 173 Therefore, in order to perform non-default initialisation,
 174 \&\fIOPENSSL_init_crypto()\fR \s-1MUST\s0 be called by application code prior to
 175 any other OpenSSL function calls.
 176 .PP
 177 The \fBopts\fR parameter specifies which aspects of libcrypto should be
 178 initialised. Valid options are:
 179 .IP "\s-1OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS\s0" 4
 180 .IX Item "OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS"
 181 Suppress automatic loading of the libcrypto error strings. This option is
 182 not a default option. Once selected subsequent calls to
 183 \&\fIOPENSSL_init_crypto()\fR with the option
 184 \&\fB\s-1OPENSSL_INIT_LOAD_CRYPTO_STRINGS\s0\fR will be ignored.
 185 .IP "\s-1OPENSSL_INIT_LOAD_CRYPTO_STRINGS\s0" 4
 186 .IX Item "OPENSSL_INIT_LOAD_CRYPTO_STRINGS"
 187 Automatic loading of the libcrypto error strings. With this option the
 188 library will automatically load the libcrypto error strings.
 189 This option is a default option. Once selected subsequent calls to
 190 \&\fIOPENSSL_init_crypto()\fR with the option
 191 \&\fB\s-1OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS\s0\fR will be ignored.
 192 .IP "\s-1OPENSSL_INIT_ADD_ALL_CIPHERS\s0" 4
 193 .IX Item "OPENSSL_INIT_ADD_ALL_CIPHERS"
 194 With this option the library will automatically load and make available all
 195 libcrypto ciphers. This option is a default option. Once selected subsequent
 196 calls to \fIOPENSSL_init_crypto()\fR with the option
 197 \&\fB\s-1OPENSSL_INIT_NO_ADD_ALL_CIPHERS\s0\fR will be ignored.
 198 .IP "\s-1OPENSSL_INIT_ADD_ALL_DIGESTS\s0" 4
 199 .IX Item "OPENSSL_INIT_ADD_ALL_DIGESTS"
 200 With this option the library will automatically load and make available all
 201 libcrypto digests. This option is a default option. Once selected subsequent
 202 calls to \fIOPENSSL_init_crypto()\fR with the option
 203 \&\fB\s-1OPENSSL_INIT_NO_ADD_ALL_CIPHERS\s0\fR will be ignored.
 204 .IP "\s-1OPENSSL_INIT_NO_ADD_ALL_CIPHERS\s0" 4
 205 .IX Item "OPENSSL_INIT_NO_ADD_ALL_CIPHERS"
 206 With this option the library will suppress automatic loading of libcrypto
 207 ciphers. This option is not a default option. Once selected subsequent
 208 calls to \fIOPENSSL_init_crypto()\fR with the option
 209 \&\fB\s-1OPENSSL_INIT_ADD_ALL_CIPHERS\s0\fR will be ignored.
 210 .IP "\s-1OPENSSL_INIT_NO_ADD_ALL_DIGESTS\s0" 4
 211 .IX Item "OPENSSL_INIT_NO_ADD_ALL_DIGESTS"
 212 With this option the library will suppress automatic loading of libcrypto
 213 digests. This option is not a default option. Once selected subsequent
 214 calls to \fIOPENSSL_init_crypto()\fR with the option
 215 \&\fB\s-1OPENSSL_INIT_ADD_ALL_DIGESTS\s0\fR will be ignored.
 216 .IP "\s-1OPENSSL_INIT_LOAD_CONFIG\s0" 4
 217 .IX Item "OPENSSL_INIT_LOAD_CONFIG"
 218 With this option an OpenSSL configuration file will be automatically loaded and
 219 used by calling \fIOPENSSL_config()\fR. This is not a default option for libcrypto.
 220 From OpenSSL 1.1.1 this is a default option for libssl (see
 221 \&\fIOPENSSL_init_ssl\fR\|(3) for further details about libssl initialisation). See the
 222 description of \fIOPENSSL_INIT_new()\fR, below.
 223 .IP "\s-1OPENSSL_INIT_NO_LOAD_CONFIG\s0" 4
 224 .IX Item "OPENSSL_INIT_NO_LOAD_CONFIG"
 225 With this option the loading of OpenSSL configuration files will be suppressed.
 226 It is the equivalent of calling \fIOPENSSL_no_config()\fR. This is not a default
 227 option.
 228 .IP "\s-1OPENSSL_INIT_ASYNC\s0" 4
 229 .IX Item "OPENSSL_INIT_ASYNC"
 230 With this option the library with automatically initialise the libcrypto async
 231 sub-library (see \fIASYNC_start_job\fR\|(3)). This is a default option.
 232 .IP "\s-1OPENSSL_INIT_ENGINE_RDRAND\s0" 4
 233 .IX Item "OPENSSL_INIT_ENGINE_RDRAND"
 234 With this option the library will automatically load and initialise the
 235 \&\s-1RDRAND\s0 engine (if available). This not a default option.
 236 .IP "\s-1OPENSSL_INIT_ENGINE_DYNAMIC\s0" 4
 237 .IX Item "OPENSSL_INIT_ENGINE_DYNAMIC"
 238 With this option the library will automatically load and initialise the
 239 dynamic engine. This not a default option.
 240 .IP "\s-1OPENSSL_INIT_ENGINE_OPENSSL\s0" 4
 241 .IX Item "OPENSSL_INIT_ENGINE_OPENSSL"
 242 With this option the library will automatically load and initialise the
 243 openssl engine. This not a default option.
 244 .IP "\s-1OPENSSL_INIT_ENGINE_CRYPTODEV\s0" 4
 245 .IX Item "OPENSSL_INIT_ENGINE_CRYPTODEV"
 246 With this option the library will automatically load and initialise the
 247 cryptodev engine (if available). This not a default option.
 248 .IP "\s-1OPENSSL_INIT_ENGINE_CAPI\s0" 4
 249 .IX Item "OPENSSL_INIT_ENGINE_CAPI"
 250 With this option the library will automatically load and initialise the
 251 \&\s-1CAPI\s0 engine (if available). This not a default option.
 252 .IP "\s-1OPENSSL_INIT_ENGINE_PADLOCK\s0" 4
 253 .IX Item "OPENSSL_INIT_ENGINE_PADLOCK"
 254 With this option the library will automatically load and initialise the
 255 padlock engine (if available). This not a default option.
 256 .IP "\s-1OPENSSL_INIT_ENGINE_AFALG\s0" 4
 257 .IX Item "OPENSSL_INIT_ENGINE_AFALG"
 258 With this option the library will automatically load and initialise the
 259 \&\s-1AFALG\s0 engine. This not a default option.
 260 .IP "\s-1OPENSSL_INIT_ENGINE_ALL_BUILTIN\s0" 4
 261 .IX Item "OPENSSL_INIT_ENGINE_ALL_BUILTIN"
 262 With this option the library will automatically load and initialise all the
 263 built in engines listed above with the exception of the openssl and afalg
 264 engines. This not a default option.
 265 .IP "\s-1OPENSSL_INIT_ATFORK\s0" 4
 266 .IX Item "OPENSSL_INIT_ATFORK"
 267 With this option the library will register its fork handlers.
 268 See \fIOPENSSL_fork_prepare\fR\|(3) for details.
 269 .PP
 270 Multiple options may be combined together in a single call to
 271 \&\fIOPENSSL_init_crypto()\fR. For example:
 272 .PP
 273 .Vb 2
 274 \& OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
 275 \&                     | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
 276 .Ve
 277 .PP
 278 The \fIOPENSSL_cleanup()\fR function deinitialises OpenSSL (both libcrypto
 279 and libssl). All resources allocated by OpenSSL are freed. Typically there
 280 should be no need to call this function directly as it is initiated
 281 automatically on application exit. This is done via the standard C library
 282 \&\fIatexit()\fR function. In the event that the application will close in a manner
 283 that will not call the registered \fIatexit()\fR handlers then the application should
 284 call \fIOPENSSL_cleanup()\fR directly. Developers of libraries using OpenSSL
 285 are discouraged from calling this function and should instead, typically, rely
 286 on auto-deinitialisation. This is to avoid error conditions where both an
 287 application and a library it depends on both use OpenSSL, and the library
 288 deinitialises it before the application has finished using it.
 289 .PP
 290 Once \fIOPENSSL_cleanup()\fR has been called the library cannot be reinitialised.
 291 Attempts to call \fIOPENSSL_init_crypto()\fR will fail and an \s-1ERR_R_INIT_FAIL\s0 error
 292 will be added to the error stack. Note that because initialisation has failed
 293 OpenSSL error strings will not be available, only an error code. This code can
 294 be put through the openssl errstr command line application to produce a human
 295 readable error (see \fIerrstr\fR\|(1)).
 296 .PP
 297 The \fIOPENSSL_atexit()\fR function enables the registration of a
 298 function to be called during \fIOPENSSL_cleanup()\fR. Stop handlers are
 299 called after deinitialisation of resources local to a thread, but before other
 300 process wide resources are freed. In the event that multiple stop handlers are
 301 registered, no guarantees are made about the order of execution.
 302 .PP
 303 The \fIOPENSSL_thread_stop()\fR function deallocates resources associated
 304 with the current thread. Typically this function will be called automatically by
 305 the library when the thread exits. This should only be called directly if
 306 resources should be freed at an earlier time, or under the circumstances
 307 described in the \s-1NOTES\s0 section below.
 308 .PP
 309 The \fB\s-1OPENSSL_INIT_LOAD_CONFIG\s0\fR flag will load a default configuration
 310 file. For optional configuration file settings, an \fB\s-1OPENSSL_INIT_SETTINGS\s0\fR
 311 must be created and used.
 312 The routines \fIOPENSSL_init_new()\fR and \fIOPENSSL_INIT_set_config_appname()\fR can
 313 be used to allocate the object and set the application name, and then the
 314 object can be released with \fIOPENSSL_INIT_free()\fR when done.
 315 .SH "NOTES"
 316 .IX Header "NOTES"
 317 Resources local to a thread are deallocated automatically when the thread exits
 318 (e.g. in a pthreads environment, when \fIpthread_exit()\fR is called). On Windows
 319 platforms this is done in response to a \s-1DLL_THREAD_DETACH\s0 message being sent to
 320 the libcrypto32.dll entry point. Some windows functions may cause threads to exit
 321 without sending this message (for example \fIExitProcess()\fR). If the application
 322 uses such functions, then the application must free up OpenSSL resources
 323 directly via a call to \fIOPENSSL_thread_stop()\fR on each thread. Similarly this
 324 message will also not be sent if OpenSSL is linked statically, and therefore
 325 applications using static linking should also call \fIOPENSSL_thread_stop()\fR on each
 326 thread. Additionally if OpenSSL is loaded dynamically via \fILoadLibrary()\fR and the
 327 threads are not destroyed until after \fIFreeLibrary()\fR is called then each thread
 328 should call \fIOPENSSL_thread_stop()\fR prior to the \fIFreeLibrary()\fR call.
 329 .PP
 330 On Linux/Unix where OpenSSL has been loaded via \fIdlopen()\fR and the application is
 331 multi-threaded and if \fIdlclose()\fR is subsequently called prior to the threads
 332 being destroyed then OpenSSL will not be able to deallocate resources associated
 333 with those threads. The application should either call \fIOPENSSL_thread_stop()\fR on
 334 each thread prior to the \fIdlclose()\fR call, or alternatively the original \fIdlopen()\fR
 335 call should use the \s-1RTLD_NODELETE\s0 flag (where available on the platform).
 336 .SH "RETURN VALUES"
 337 .IX Header "RETURN VALUES"
 338 The functions OPENSSL_init_crypto, \fIOPENSSL_atexit()\fR and
 339 \&\fIOPENSSL_INIT_set_config_appname()\fR return 1 on success or 0 on error.
 340 .SH "SEE ALSO"
 341 .IX Header "SEE ALSO"
 342 \&\fIOPENSSL_init_ssl\fR\|(3)
 343 .SH "HISTORY"
 344 .IX Header "HISTORY"
 345 The \fIOPENSSL_init_crypto()\fR, \fIOPENSSL_cleanup()\fR, \fIOPENSSL_atexit()\fR,
 346 \&\fIOPENSSL_thread_stop()\fR, \fIOPENSSL_INIT_new()\fR, \fIOPENSSL_INIT_set_config_appname()\fR
 347 and \fIOPENSSL_INIT_free()\fR functions were added in OpenSSL 1.1.0.
 348 .SH "COPYRIGHT"
 349 .IX Header "COPYRIGHT"
 350 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 351 .PP
 352 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 353 this file except in compliance with the License.  You can obtain a copy
 354 in the file \s-1LICENSE\s0 in the source distribution or at
 355 <https://www.openssl.org/source/license.html>.