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
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
=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(OPENSSL_INIT_LOAD_CONFIG, settings);
+OPENSSL_init_crypto(). For example:
-The B<settings> parameter must be an array of OPENSSL_INIT_SETTINGS values
-terminated with an OPENSSL_INIT_SET_END entry.
+ 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
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<errstr(1)>).
+
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
resources should be freed at an earlier time, or under the circumstances
described in the NOTES section below.
+The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a default configuration
+file. To specify a different file, an B<OPENSSL_INIT_SETTINGS> 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 libeay32.dll entry point. Some windows functions may cause threads to exit
+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(). 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().
+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 and OPENSSL_atexit() returns 1 on success or
-0 on error.
+The functions OPENSSL_init_crypto, OPENSSL_atexit() and
+OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error.
=head1 SEE ALSO
=head1 HISTORY
The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(),
-and OPENSSL_thread_stop() functions were added in OpenSSL 1.1.0.
+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<https://www.openssl.org/source/license.html>.
=cut
projects / openssl.git / blobdiff