Library Initialization - Revision history

Matt: Correct OPENSSL_init_crypto line

2020-10-16T14:30:41Z

Correct OPENSSL_init_crypto line

Jwalton: Add section on OpenSSL_config and OPENSSL_init_crypto.

2020-01-29T03:50:00Z

Add section on OpenSSL_config and OPENSSL_init_crypto.

Jflopezfernandez: Removed the empty errata section and added page to the examples category

2019-07-29T20:52:52Z

Removed the empty errata section and added page to the examples category

Matt: Make it clearer that you don't need to explicitly initialze in 1.1.0 and above

2018-11-08T10:22:54Z

Make it clearer that you don't need to explicitly initialze in 1.1.0 and above

Aerowolf: /* Autoconf */ OPENSSL_init_ssl had incorrect multiple references in the prose. Replaced the incorrect references with SSL_library_init.

2017-11-22T11:09:22Z

Autoconf: OPENSSL_init_ssl had incorrect multiple references in the prose. Replaced the incorrect references with SSL_library_init.

Jwalton: /* Static Locks */

2017-03-17T17:17:20Z

Static Locks

Jwalton: Add HTML break for formatting.

2017-03-17T17:16:13Z

Add HTML break for formatting.

Jwalton: Added info on Autoconf configuration tests. OpenSSL 1.1.0 is breaking all kinds of projects :)

2016-09-04T05:11:37Z

Added info on Autoconf configuration tests. OpenSSL 1.1.0 is breaking all kinds of projects :)

Wdtj: /* Cleanup */

2016-05-13T14:18:13Z

Cleanup

Jwalton: Added info on 1.1.0 library initialization.

2016-02-25T09:49:03Z

Added info on 1.1.0 library initialization.

@@ Line 183: / Line 183: @@
      OPENSSL_config(NULL);
 #else
-     OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG |
+     OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL);
 #endif</pre>

@@ Line 172: / Line 172: @@
 * OpenSSL_add_all_algorithms();
 * ERR_load_crypto_strings();
 == ENGINEs and RDRAND ==

← Older revision		Revision as of 20:52, 29 July 2019
Line 296:		Line 296:
	Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.		Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

−	~~== Errata ==~~	+	[[Category:Examples]]

@@ Line 1: / Line 1: @@
 This page discusses OpenSSL library initialization when using the <tt>libssl</tt> and <tt>libcrypto</tt> components.
-There are two ways to initialize the OpenSSL library, and they depend on the version of the library you are using. If you are using OpenSSL 1.0.2 or below, then you would use <tt>SSL_library_init</tt>. If you are using OpenSSL 1.1.0 or above, then you would use <tt>OPENSSL_init_ssl</tt>. A compatibility macro exists in <tt>ssl.h</tt> that maps <tt>SSL_library_init</tt> to <tt>OPENSSL_init_ssl</tt>, so you can continue to use <tt>SSL_library_init</tt> if desired. Also see ''[http://mta.openssl.org/pipermail/openssl-dev/2016-February/005491.html SSL_library_init]'' on the OpenSSL-dev mailing list.
+There are two ways to initialize the OpenSSL library, and they depend on the version of the library you are using. If you are using OpenSSL 1.0.2 or below, then you would use <tt>SSL_library_init</tt>. If you are using OpenSSL 1.1.0 or above, then the library will initialize itself automatically. Optionally you can explicitly initialise it using <tt>OPENSSL_init_ssl</tt> or <tt>OPENSSL_init_crypto</tt>. A compatibility macro exists in <tt>ssl.h</tt> that maps <tt>SSL_library_init</tt> to <tt>OPENSSL_init_ssl</tt>, so you can continue to use <tt>SSL_library_init</tt> if desired. Also see ''[http://mta.openssl.org/pipermail/openssl-dev/2016-February/005491.html SSL_library_init]'' on the OpenSSL-dev mailing list.
-If you fail to initialize the library, then you will experience unexplained errors like <tt>SSL_CTX_new</tt> returning <tt>NULL</tt>, error messages like <tt>SSL_CTX_new:library has no ciphers</tt> and <tt>alert handshake failure</tt> with no shared ciphers.
+The rest of this page discusses initializing the library in 1.0.2. If you are using 1.1.0 or above then you don't need to take any further steps.
 Below is a list of some initialization calls you might encounter in code or documentation. Unfortunately, all the initialization function return a useless values (for example, always 1) or are void functions. There is no way to determine if a failure occurred.
@@ Line 203: / Line 205: @@
 <tt>OPENSSL_config</tt> may (or may not) be called depending upon how the OpenSSL library was configured, and it depends on whether <tt>OPENSSL_LOAD_CONF</tt> was defined. Because <tt>OPENSSL_config</tt> may (or may not) be called, your program may or may not need to make the call to <tt>OPENSSL_config</tt>. If, for example, your program is dynamically loading an ENGINE from <tt>OPENSSL_config</tt>, then you will need to ensure a call to <tt>OPENSSL_config</tt>.
-You can check the value of <tt>OPENSSL_LOAD_CONF</tt> by <tt>cat</tt>'ing <tt><nowiki><openssl/opensslconf.h></nowiki></tt>. You can then decide to call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt> based upon the definition (or lack threof) for <tt>OPENSSL_LOAD_CONF</tt>.
+You can check the value of <tt>OPENSSL_LOAD_CONF</tt> by <tt>cat</tt>'ing you<tt><nowiki><openssl/opensslconf.h></nowiki></tt>. You can then decide to call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt> based upon the definition (or lack threof) for <tt>OPENSSL_LOAD_CONF</tt>.
 <pre>$ cat /usr/local/ssl/include/openssl/opensslconf.h | grep -i load

@@ Line 273: / Line 273: @@
 ==Autoconf==
-OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be usful to detect either <tt>OPENSSL_init_ssl</tt> and <tt>OPENSSL_init_ssl</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>OPENSSL_init_ssl</tt>, you can use the following.
+OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be usful to detect either <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.
 <pre>if test "$with_openssl" = yes ; then

@@ Line 187: / Line 187: @@
 == Static Locks ==
-If your program is multi-threaded, then you will need to install the static locks. The static locks are used for extensively for <tt>libssl</tt>, and used in the random number generator for <tt>libcrypto</tt>.
+If your program is multi-threaded, then you will need to install the static locks. The static locks are used for extensively for <tt>libssl</tt>, and used in the random number generator for <tt>libcrypto</tt>. The locks should be installed '''''after''''' the calling:
-See [http://www.openssl.org/docs/crypto/threads.html threads(3)] for details until the wiki is updated with an example.
+* SSL_library_init
 == OPENSSL_config ==

@@ Line 12: / Line 12: @@
 * SSL_load_error_strings
 * ERR_load_crypto_strings
 == libssl Initialization ==

← Older revision		Revision as of 05:11, 4 September 2016
Line 263:		Line 263:

	After cleanup, you may have some memory leaks due to dynamic allocation of private static variables like <tt>ssl_comp_methods</tt>. This is a well known issue (see [http://rt.openssl.org/Ticket/Display.html?id=2561&user=guest&pass=guest Issue #2561, Memory leak with SSL built-in compressions]).		After cleanup, you may have some memory leaks due to dynamic allocation of private static variables like <tt>ssl_comp_methods</tt>. This is a well known issue (see [http://rt.openssl.org/Ticket/Display.html?id=2561&user=guest&pass=guest Issue #2561, Memory leak with SSL built-in compressions]).
		+
		+	==Autoconf==
		+
		+	OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be usful to detect either <tt>OPENSSL_init_ssl</tt> and <tt>OPENSSL_init_ssl</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>OPENSSL_init_ssl</tt>, you can use the following.
		+
		+	<pre>if test "$with_openssl" = yes ; then
		+	dnl Order matters!
		+	if test "$PORTNAME" != "win32"; then
		+	AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
		+	FOUND_SSL_LIB="no"
		+	AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
		+	AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
		+	AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
		+	else
		+	AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
		+	FOUND_SSL_LIB="no"
		+	AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
		+	AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
		+	AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
		+	fi
		+	fi</pre>
		+
		+	Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

	== Errata ==		== Errata ==

@@ Line 255: / Line 255: @@
 * ERR_remove_state();
 * ERR_free_strings();
 <tt>CRYPTO_cleanup_all_ex_data</tt> and <tt>ERR_remove_state</tt> should be called on each thread, and not just the main thread.

@@ Line 1: / Line 1: @@
 This page discusses OpenSSL library initialization when using the <tt>libssl</tt> and <tt>libcrypto</tt> components.
 If you fail to initialize the library, then you will experience unexplained errors like <tt>SSL_CTX_new</tt> returning <tt>NULL</tt>, error messages like <tt>SSL_CTX_new:library has no ciphers</tt> and <tt>alert handshake failure</tt> with no shared ciphers.
@@ Line 14: / Line 16: @@
 <tt>libssl</tt> should be initialized with calls to <tt>SSL_library_init</tt> and <tt>SSL_load_error_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.
 When you call <tt>libssl</tt>, the function will also initialize <tt>libcrypto</tt> components. There are two corner cases discussed in later sections. The first corner case is static locks, and second is <tt>OPENSSL_config</tt>.
@@ Line 129: / Line 142: @@
 }</pre>
-Finally, [https://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html <tt>OpenSSL_add_all_algorithms(3)</tt>] offers the following advice:
+Finally, [http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html <tt>OpenSSL_add_all_algorithms(3)</tt>] offers the following advice:
 <blockquote>Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a statically linked executable can be quite large. If this is important it is possible to just add the required ciphers and digests.</blockquote>
@@ Line 175: / Line 188: @@
 If your program is multi-threaded, then you will need to install the static locks. The static locks are used for extensively for <tt>libssl</tt>, and used in the random number generator for <tt>libcrypto</tt>.
-See [https://www.openssl.org/docs/crypto/threads.html threads(3)] for details until the wiki is updated with an example.
+See [http://www.openssl.org/docs/crypto/threads.html threads(3)] for details until the wiki is updated with an example.
 == OPENSSL_config ==
@@ Line 223: / Line 236: @@
 ENGINE_cleanup();</pre>
-If you want an engine to provide all incumbent functionality for the OpenSSL library, then then call <tt>ENGINE_register_complete</tt> after loading the engine. Incumbent functionality is determined by the manufacturer and includes includes RSA, DSA, DH, ECDH, MD, and RAND operations. See <tt>eng_all.c</tt>, <tt>eng_fat.c</tt>, and [https://www.openssl.org/docs/crypto/engine.html engine(3)] for details.
+If you want an engine to provide all incumbent functionality for the OpenSSL library, then then call <tt>ENGINE_register_complete</tt> after loading the engine. Incumbent functionality is determined by the manufacturer and includes includes RSA, DSA, DH, ECDH, MD, and RAND operations. See <tt>eng_all.c</tt>, <tt>eng_fat.c</tt>, and [http://www.openssl.org/docs/crypto/engine.html engine(3)] for details.
 <pre>ENGINE* eng = ENGINE_by_id("XXX");