X-Git-Url: https://code.wpia.club/?a=blobdiff_plain;f=lib%2Fopenssl%2Fdoc%2Fcrypto%2FOPENSSL_init_crypto.pod;fp=lib%2Fopenssl%2Fdoc%2Fcrypto%2FOPENSSL_init_crypto.pod;h=19898807522658fc51bb5642e745955663386958;hb=02ed66432c92de70694700164f986190aad3cbc5;hp=0000000000000000000000000000000000000000;hpb=89016837dcbf2775cd15dc8cbaba00dc6379f86e;p=cassiopeia.git diff --git a/lib/openssl/doc/crypto/OPENSSL_init_crypto.pod b/lib/openssl/doc/crypto/OPENSSL_init_crypto.pod new file mode 100644 index 0000000..1989880 --- /dev/null +++ b/lib/openssl/doc/crypto/OPENSSL_init_crypto.pod @@ -0,0 +1,245 @@ +=pod + +=head1 NAME + +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 + +=head1 SYNOPSIS + + #include + + void OPENSSL_cleanup(void); + int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); + int OPENSSL_atexit(void (*handler)(void)); + void OPENSSL_thread_stop(void); + + OPENSSL_INIT_SETTINGS *OPENSSL_init_new(void); + int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init, + const char* name); + void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init); + +=head1 DESCRIPTION + +During normal operation OpenSSL (libcrypto) will allocate various resources at +start up that must, subsequently, be freed on close down of the library. +Additionally some resources are allocated on a per thread basis (if the +application is multi-threaded), and these resources must be freed prior to the +thread closing. + +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. + +However, there way be situations when explicit initialisation is desirable or +needed, for example when some non-default initialisation is required. The +function OPENSSL_init_crypto() can be used for this purpose for +libcrypto (see also L for the libssl +equivalent). + +Numerous internal OpenSSL functions call OPENSSL_init_crypto(). +Therefore, in order to perform non-default initialisation, +OPENSSL_init_crypto() MUST be called by application code prior to +any other OpenSSL function calls. + +The B parameter specifies which aspects of libcrypto should be +initialised. Valid options are: + +=over 4 + +=item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS + +Suppress automatic loading of the libcrypto error strings. This option is +not a default option. Once selected subsequent calls to +OPENSSL_init_crypto() with the option +B will be ignored. + +=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS + +Automatic loading of the libcrypto error strings. With this option the +library will automatically load the libcrypto error strings. +This option is a default option. Once selected subsequent calls to +OPENSSL_init_crypto() with the option +B will be ignored. + +=item OPENSSL_INIT_ADD_ALL_CIPHERS + +With this option the library will automatically load and make available all +libcrypto ciphers. This option is a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B will be ignored. + +=item OPENSSL_INIT_ADD_ALL_DIGESTS + +With this option the library will automatically load and make available all +libcrypto digests. This option is a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B will be ignored. + +=item OPENSSL_INIT_NO_ADD_ALL_CIPHERS + +With this option the library will suppress automatic loading of libcrypto +ciphers. This option is not a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B will be ignored. + +=item OPENSSL_INIT_NO_ADD_ALL_DIGESTS + +With this option the library will suppress automatic loading of libcrypto +digests. This option is not a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B will be ignored. + +=item OPENSSL_INIT_LOAD_CONFIG + +With this option an OpenSSL configuration file will be automatically loaded and +used by calling OPENSSL_config(). This is not a default option. +See the description of OPENSSL_init_new(), below. + +=item OPENSSL_INIT_NO_LOAD_CONFIG + +With this option the loading of OpenSSL configuration files will be suppressed. +It is the equivalent of calling OPENSSL_no_config(). This is not a default +option. + +=item OPENSSL_INIT_ASYNC + +With this option the library with automatically initialise the libcrypto async +sub-library (see L). This is a default option. + +=item OPENSSL_INIT_ENGINE_RDRAND + +With this option the library will automatically load and initialise the +RDRAND engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_DYNAMIC + +With this option the library will automatically load and initialise the +dynamic engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_OPENSSL + +With this option the library will automatically load and initialise the +openssl engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_CRYPTODEV + +With this option the library will automatically load and initialise the +cryptodev engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_CAPI + +With this option the library will automatically load and initialise the +CAPI engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_PADLOCK + +With this option the library will automatically load and initialise the +padlock engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_DASYNC + +With this option the library will automatically load and initialise the +DASYNC engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_ALL_BUILTIN + +With this option the library will automatically load and initialise all the +built in engines listed above with the exception of the openssl and dasync +engines. This not a default option. + +=back + +Multiple options may be combined together in a single call to +OPENSSL_init_crypto(). For example: + + OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS + | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL); + +The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto +and libssl). All resources allocated by OpenSSL are freed. Typically there +should be no need to call this function directly as it is initiated +automatically on application exit. This is done via the standard C library +L function. In the event that the application will close in a manner +that will not call the registered atexit() handlers then the application should +call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL +are discouraged from calling this function and should instead, typically, rely +on auto-deinitialisation. This is to avoid error conditions where both an +application and a library it depends on both use OpenSSL, and the library +deinitialises it before the application has finished using it. + +Once OPENSSL_cleanup() has been called the library cannot be reinitialised. +Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error +will be added to the error stack. Note that because initialisation has failed +OpenSSL error strings will not be available, only an error code. This code can +be put through the openssl errstr command line application to produce a human +readable error (see L). + +The OPENSSL_atexit() function enables the registration of a +function to be called during OPENSSL_cleanup(). Stop handlers are +called after deinitialisation of resources local to a thread, but before other +process wide resources are freed. In the event that multiple stop handlers are +registered, no guarantees are made about the order of execution. + +The OPENSSL_thread_stop() function deallocates resources associated +with the current thread. Typically this function will be called automatically by +the library when the thread exits. This should only be called directly if +resources should be freed at an earlier time, or under the circumstances +described in the NOTES section below. + +The B flag will load a default configuration +file. To specify a different file, an B must +be created and used. The routines +OPENSSL_init_new() and OPENSSL_INIT_set_config_appname() can be used to +allocate the object and set the application name, and then the +object can be released with OPENSSL_INIT_free() when done. + +=head1 NOTES + +Resources local to a thread are deallocated automatically when the thread exits +(e.g. in a pthreads environment, when pthread_exit() is called). On Windows +platforms this is done in response to a DLL_THREAD_DETACH message being sent to +the libcrypto32.dll entry point. Some windows functions may cause threads to exit +without sending this message (for example ExitProcess()). If the application +uses such functions, then the application must free up OpenSSL resources +directly via a call to OPENSSL_thread_stop() on each thread. Similarly this +message will also not be sent if OpenSSL is linked statically, and therefore +applications using static linking should also call OPENSSL_thread_stop() on each +thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the +threads are not destroyed until after FreeLibrary() is called then each thread +should call OPENSSL_thread_stop() prior to the FreeLibrary() call. + +On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is +multi-threaded and if dlclose() is subsequently called prior to the threads +being destroyed then OpenSSL will not be able to deallocate resources associated +with those threads. The application should either call OPENSSL_thread_stop() on +each thread prior to the dlclose() call, or alternatively the original dlopen() +call should use the RTLD_NODELETE flag (where available on the platform). + +=head1 RETURN VALUES + +The functions OPENSSL_init_crypto, OPENSSL_atexit() and +OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(), +OPENSSL_thread_stop(), OPENSSL_init_new(), OPENSSL_INIT_set_config_appname() +and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut