Commit 8b75603c authored by Matt Caswell's avatar Matt Caswell
Browse files

Provide documentation for auto-init/auto-deinit 



Provide some man pages for auto-init/deinit. Also update the INSTALL
documentation for information on the new Configure options implemented as
part of this.

Reviewed-by: default avatarRichard Levitte <levitte@openssl.org>
parent 498abff0

INSTALL

+17 −0
Original line number Diff line number Diff line
@@ -51,6 +51,19 @@ 
  --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,

                the library files and binaries are also installed there.



  no-autoalginit Don't automatically load all supported ciphers and digests.

                Typically OpenSSL will make available all of its supported

                ciphers and digests. For a statically linked application this

                may be undesirable if small executable size is an objective.

                This only affects libcrypto. Ciphers and digests will have to be

                loaded manually using EVP_add_cipher() and EVP_add_digest() if

                this option is used.



  no-autoerrinit Don't automatically load all libcrypto/libssl error strings.

                Typically OpenSSL will automatically load human readable error

                strings. For a statically linked application this may be

                undesirable if small executable size is an objective.



  no-threads    Don't try to build with support for multi-threaded

                applications.
@@ -327,6 +340,10 @@ 
 you can still use "no-threads" to suppress an annoying warning message

 from the Configure script.)



 OpenSSL provides in built support for two threading models: pthreads (found on

 most UNIX/Linux systems), and Windows threads. No other threading models are

 supported. If your platform does not provide pthreads or Windows threads then

 you should Configure with the "no-threads" option.



 Note on shared libraries

 ------------------------

INSTALL.WIN

+16 −0
Original line number Diff line number Diff line
@@ -190,3 +190,19 @@ 
 your application code small "shim" snippet, which provides glue between

 OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink

 manual page for further details.



 Support for older Windows platforms

 -----------------------------------



 By default OpenSSL will use functions and capabilities of the Windows platform

 only available in Windows Vista, Windows Server 2008 or later. It is possible

 to enable support for older platforms by defining _WIN32_WINNT at Configure

 time.



  > perl Configure VC-WIN32 --prefix=c:\some\openssl\dir -D_WIN32_WINNT=0x0501



 The value 0x0501 above corresponds to Windows XP which is the oldest supported

 platform. The value 0x0600 corresponds to Windows Vista and Windows Server

 2008. Refer to the Windows documentation for other possible values. Note that

 by forcing support for an older OpenSSL version this may mean less optimal

 approaches are used instead.

doc/crypto/OPENSSL_INIT_crypto_library_start.pod

0 → 100644
+226 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



OPENSSL_INIT_library_stop, OPENSSL_INIT_crypto_library_start,

OPENSSL_INIT_register_stop_handler, OPENSSL_INIT_thread_stop - OpenSSL

initialisation and deinitialisation functions



=head1 SYNOPSIS



 #include <openssl/crypto.h>



 void OPENSSL_INIT_library_stop(void);

 void OPENSSL_INIT_crypto_library_start(uint64_t opts,

                                        const OPENSSL_INIT_SETTINGS *settings);

 int OPENSSL_INIT_register_stop_handler(void (*handler)(void));

 void OPENSSL_INIT_thread_stop(void);



=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_library_start() can be used for this purpose for

libcrypto (see also L<OPENSSL_INIT_ssl_library_start(3)> for the libssl

equivalent). In order to perform non-default initialisation it MUST be called

prior to any other calls of this function. As numerous internal OpenSSL

functions also call this, this usually means you should call it prior to ANY

other OpenSSL function calls.



The B<opts> 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. With this option the

library will not automatically call ERR_load_crypto_strings(). This option is

not a default option. Once selected subsequent calls to

OPENSSL_INIT_crypto_library_start() with the option

B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored. Applications may call

ERR_load_crypto_strings() directly if they wish even if this option has been

selected. If they do so then they must also explicitly call ERR_free_strings()

on application close down.



=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS



Automatic loading of the libcrypto error strings. With this option the

library will automatically call ERR_load_crypto_strings(). This option is a

default option. Once selected subsequent calls to

OPENSSL_INIT_crypto_library_start() with the option

B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> 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_library_start() with the option

B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> 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_library_start() with the option

B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> 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_library_start() with the option

B<OPENSSL_INIT_ADD_ALL_CIPHERS> 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_library_start() with the option

B<OPENSSL_INIT_ADD_ALL_DIGESTS> 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.



=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<ASYNC_start_job(3)>). 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_start_library(). For example:



 OPENSSL_INIT_start_library(OPENSSL_INIT_NO_ADD_ALL_CIPHERS

                            | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);





The B<settings> parameter to OPENSSL_INIT_start_library() may be used to

provide optional settings values to an option. Currently the only option this

applies to is OPENSSL_INIT_LOAD_CONFIG. This provides the optional

OPENSSL_INIT_SET_CONF_FILENAME parameter to provide a filename to load

configuration from. If no filename is provided then the system default

configuration file is assumed. For example



 const OPENSSL_INIT_SETTINGS settings[2] = {

     { OPENSSL_INIT_SET_CONF_FILENAME, .value.type_string = "myconf.cnf" },

     { OPENSSL_INIT_SET_END, .value.type_int = 0 }

 };

 OPENSSL_INIT_crypto_library_start(OPENSSL_INIT_LOAD_CONFIG,

                                   (const OPENSSL_INIT_SETTINGS *)&settings);



The B<settings> parameter must be an array of OPENSSL_INIT_SETTINGS values

terminated with an OPENSSL_INIT_SET_END entry.



The OPENSSL_INIT_library_stop() 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<atexit(3)> 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_INIT_library_stop() 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.



The OPENSSL_INIT_register_stop_handler() function enables the registration of a

function to be called during OPENSSL_INIT_library_stop(). 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_INIT_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.



=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 libeay32.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_INIT_thread_stop(). Similarly this message will

also not be sent if OpenSSL is linked statically, and therefore applications

using static linking should also call OPENSSL_INIT_thread_stop().



=head1 RETURN VALUES



The function OPENSSL_INIT_register_stop_handler() returns 1 on success or 0 on

error.



=head1 SEE ALSO



L<OPENSSL_INIT_ssl_library_start(3)>



=head1 HISTORY



The OPENSSL_INIT_library_stop, OPENSSL_INIT_crypto_library_start,

OPENSSL_INIT_register_stop_handler and OPENSSL_INIT_thread_stop functions were

first added in OpenSSL 1.1.0.



=cut

doc/ssl/OPENSSL_INIT_ssl_library_start.pod

0 → 100644
+78 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



OPENSSL_INIT_ssl_library_start - OpenSSL (libssl and libcrypto) initialisation



=head1 SYNOPSIS



 #include <openssl/ssl.h>



 void OPENSSL_INIT_ssl_library_start(uint64_t opts,

                                     const OPENSSL_INIT_SETTINGS *settings);



=head1 DESCRIPTION



During normal operation OpenSSL (libssl and 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_ssl_library_start() can be used for this purpose. Calling

this function will explicitly initialise BOTH libcrypto and libssl. To

explicitly initialise ONLY libcrypto see the

L<OPENSSL_INIT_crypto_library_start(3)> function. In order to perform

non-default initialisation it MUST be called prior to any other calls of this

function. As numerous internal OpenSSL functions also call this, this usually

means you should call it prior to ANY other OpenSSL function calls.



The B<opts> parameter specifies which aspects of libssl and libcrypto should be

initialised. Valid options for libcrypto are described on the

L<OPENSSL_INIT_crypto_library_start(3)> page. In addition to any libcrypto

specific option the following libssl options can also be used:



=over 4



=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS



Suppress automatic loading of the libssl error strings. With this option the

library will not automatically call ERR_load_SSL_strings(). This option is

not a default option. Once selected subsequent calls to

OPENSSL_INIT_ssl_library_start() with the option

B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. Applications may call

ERR_load_SSL_strings() directly if they wish even if this option has been

selected. If they do so then they must also explicitly call ERR_free_strings()

on application close down.



=item OPENSSL_INIT_LOAD_SSL_STRINGS



Automatic loading of the libssl error strings. With this option the

library will automatically call ERR_load_SSL_strings(). This option is a

default option. Once selected subsequent calls to

OPENSSL_INIT_ssl_library_start() with the option

B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.



=back



The B<settings> parameter specifies optional settings values to an option.

Currently no such settings are available for libssl specific options. However

these settings will also be passed internally to a call to

L<OPENSSL_INIT_crypto_library_start(3)>, so this parameter can also be used to

provide libcrypto settings values.



=head1 SEE ALSO



L<OPENSSL_INIT_crypto_library_start(3)>



=head1 HISTORY



The OPENSSL_INIT_ssl_library_start function was first added in OpenSSL 1.1.0.



=cut