Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OPENSSL_INIT_CRYPTO(3)		    OpenSSL		OPENSSL_INIT_CRYPTO(3)

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

SYNOPSIS
	#include <openssl/crypto.h>

	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);

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 OPENSSL_init_ssl(3) 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 opts	parameter specifies which aspects of libcrypto should be
       initialised. Valid options are:

       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
	   OPENSSL_INIT_LOAD_CRYPTO_STRINGS will be ignored.

       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
	   OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS will be ignored.

       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 OPENSSL_INIT_NO_ADD_ALL_CIPHERS will be ignored.

       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 OPENSSL_INIT_NO_ADD_ALL_CIPHERS will be ignored.

       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
	   OPENSSL_INIT_ADD_ALL_CIPHERS	will be	ignored.

       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
	   OPENSSL_INIT_ADD_ALL_DIGESTS	will be	ignored.

       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	for libcrypto.	From OpenSSL 1.1.1 this	is a
	   default option for libssl (see OPENSSL_init_ssl(3) for further
	   details about libssl	initialisation). See the description of
	   OPENSSL_INIT_new(), below.

       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.

       OPENSSL_INIT_ASYNC
	   With	this option the	library	with automatically initialise the
	   libcrypto async sub-library (see ASYNC_start_job(3)). This is a
	   default option.

       OPENSSL_INIT_ENGINE_RDRAND
	   With	this option the	library	will automatically load	and initialise
	   the RDRAND engine (if available). This not a	default	option.

       OPENSSL_INIT_ENGINE_DYNAMIC
	   With	this option the	library	will automatically load	and initialise
	   the dynamic engine. This not	a default option.

       OPENSSL_INIT_ENGINE_OPENSSL
	   With	this option the	library	will automatically load	and initialise
	   the openssl engine. This not	a default option.

       OPENSSL_INIT_ENGINE_CRYPTODEV
	   With	this option the	library	will automatically load	and initialise
	   the cryptodev engine	(if available).	This not a default option.

       OPENSSL_INIT_ENGINE_CAPI
	   With	this option the	library	will automatically load	and initialise
	   the CAPI engine (if available). This	not a default option.

       OPENSSL_INIT_ENGINE_PADLOCK
	   With	this option the	library	will automatically load	and initialise
	   the padlock engine (if available). This not a default option.

       OPENSSL_INIT_ENGINE_AFALG
	   With	this option the	library	will automatically load	and initialise
	   the AFALG engine. This not a	default	option.

       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 afalg engines. This not a default option.

       OPENSSL_INIT_ATFORK
	   With	this option the	library	will register its fork handlers.  See
	   OPENSSL_fork_prepare(3) for details.

       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 atexit() 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
       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
       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 OPENSSL_INIT_LOAD_CONFIG flag will load a default configuration
       file. For optional configuration	file settings, an
       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.

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

RETURN VALUES
       The functions OPENSSL_init_crypto, OPENSSL_atexit() and
       OPENSSL_INIT_set_config_appname() return	1 on success or	0 on error.

SEE ALSO
       OPENSSL_init_ssl(3)

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.

COPYRIGHT
       Copyright 2016-2018 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
       <https://www.openssl.org/source/license.html>.

1.1.1a				  2018-11-20		OPENSSL_INIT_CRYPTO(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OPENSSL_INIT_new&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help