mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-30 14:01:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

Provide documentation for auto-init/auto-deinit

Browse Source 
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: Richard Levitte <levitte@openssl.org>
This commit is contained in:
Matt Caswell 2016-02-09 10:17:59 +00:00
parent 498abff0ae
commit 8b75603cc0
4 changed files with 337 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
INSTALL
View File

@ -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
------------------------

16
INSTALL.WIN
View File

@ -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.

226
doc/crypto/OPENSSL_INIT_crypto_library_start.pod Normal file
View File

@ -0,0 +1,226 @@
=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

78
doc/ssl/OPENSSL_INIT_ssl_library_start.pod Normal file
View File

@ -0,0 +1,78 @@
=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