== "OpenSSL cannot fix the fork-safety problem because its not in a position to do so." ==

I'm puzzled by that statement. OpenSSL '''could''' fix the fork-safety issue, and in fact Ben Laurie (among others) has submitted a patch to do so. --[[User:Ppelleti|Ppelleti]] 22:30, 9 November 2013 (UTC)

Random fork-safety

2013-10-03T01:23:11Z

Ppelleti: add a link to Ben Laurie's commit

2013-03-08T03:10:38Z

Ppelleti: /* Initial */ indicate that RAND_poll is called automatically, and RAND_poll has a reasonable implementation on both UNIX and Windows

[[Random Numbers]] are a cryptographic primitive and cornerstone to nearly all cryptographic systems. They are used in almost all areas of cryptography, from key agreement and transport to session keys for bulk encryption. A quality source of random bits and proper use of OpenSSL APIs will help ensure your program is cryptographically sound. On the other hand, a poor source of randomness or incorrect library usage could result in loss of security. This article will help you use random number generation routines correctly when programming with the OpenSSL library.

OpenSSL provides a number of software based random number generators based on a variety of sources. A software based random number generator creates random numbers by executing a software algorithm. There are a number of algorithms specified by a number of standard bodies including NIST, ANSI X9 committee (X9.17 and X9.31) and XXX. In addition, the library can use custom hardware if the hardware has an <tt>ENIGNE</tt> interface.

Good random numbers are notoriously hard to produce from deterministic processes such as a computer executing instructions. A number of cryptographic attacks have been developed because they are so hard to acquire. Especially vulnerable are headless servers, embedded devices, and mobile devices, and you may have to take extra steps to ensure an adequate supply of entropy is available. The extra steps could include ''Hedging'' on a headless server or embedded device, and ''Finger Painting'' on a mobile device. For recent attacks on low entropy devices (such as headless servers and mobile devices), see for example, ''[http://pages.cs.wisc.edu/~rist/papers/sslhedge.html When Good Randomness Goes Bad: Virtual Machine Reset Vulnerabilities and Hedging Deployed Cryptography ]'', ''[https://factorable.net/paper.html Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices]'', and ''[http://www.csoonline.com/article/723229/traffic-sensor-flaw-that-could-allow-driver-tracking-fixed Traffic sensor flaw that could allow driver tracking fixed]''.

== Entropy ==

Entropy is the measure of "randomness" in a sequence of bits. Different sources have different entropy. For example, a physical process in nature may have 100% entropy which appears purely random. On the other hand, the written English language provides about 3 bits/byte (or character) which is at most 38%. Some estimates have shown English characters provide only 1 bit/byte (or 12%). Other sources used as a random stream will have different estimates of entropy, and you will have to determine the quality.

Random number generators need quality entropy for input (a ''seed'', discussed below) and must produce quality output (''quod vide''). When using OpenSSL's APIs, you will be asked to estimate entropy when seeding or reseeding (input). When estimating entropy you should error on the low side to ensure proper fitness of the generator. When receiving bytes, you will receive a code indicating the success/failure of the operation and quality of the bytes (output).

Sometimes the operating system offers block access to hardware random number generators via <tt>/dev/hwrng</tt>. <tt>/dev/hwrng</tt> can be a low volume device, and could potentially block. For example, the [http://www.portwell.com.tw/download/sbc/catalog/Intel_80802_FWH.pdf Intel 82802 Firmware Hub] used with the and i840 chipset produces one byte of data in its register. At other times, <tt>/dev/hwrng</tt> can be a high volume device, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology]. In virtualized environments, <tt>/dev/hwrng</tt> might actually be a [http://wiki.qemu.org/Features-Done/VirtIORNG VirtIO RNG].

Entropy is important for a healthy program, and you should investigate hardware modules to help acquire it, especially if poor entropy or entropy depletion are a concern. There are a number of inexpensive and high quality hardware modules on the market, including a $40UK [http://www.entropykey.co.uk EntropyKey]. There are also a number of high quality and high priced hardware modules and accelerators.

If you lack <tt>/dev/random</tt> and cannot procure a hardware random number generator, you can also consider an alternate entropy gather such as the [http://egd.sourceforge.net Entropy Gathering Daemon (EGD)]. EGD is an userspace substitute for <tt>/dev/random</tt>. OpenSSL provides native support for EGD via <tt>RAND_egd</tt> to connect to the Unix domain socket, and <tt>RAND_egd_bytes</tt> to extract bytes from the daemon.

== Seeds ==

Most random number generators require a seed. A seed is a secret, unpredictable sequence of bytes that is transformed and then used to set the initial state of the generator. The seed ensures that each unique instance of a generator produces a unique stream of bits. No two generators should ever produce the same sequence of random numbers, even when faced with Virtual Machine (VM) rollback attacks (which could happen accidentally by a data center operator).

When seeding your generators, you should use at least 256 bits (32 bytes) of material. You can verify the required number of bits by grepping the source files for <tt>#define ENTROPY_NEEDED</tt>.

=== Initial ===

OpenSSL will attempt to seed the random number generator automatically upon instantiation by calling <tt>RAND_poll</tt>. <tt>RAND_poll</tt> seeds the random number generator using a system-specific entropy source, which is <tt>/dev/urandom</tt> on UNIX-like operating systems, and is a combination of [http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx <tt>CryptGenRandom</tt>] and other sources of entropy on Windows.

The <tt>urandom</tt> device may lack sufficient entropy for your needs, and you might want to reseed it immediately from <tt>/dev/random</tt>. On Unix and other operating systems that provide the block device, you can use <tt>RAND_load_file</tt> to load directly from <tt>/dev/random</tt>.

<pre>int rc = RAND_load_file("/dev/random", 32);
if(rc != 32) {
/* RAND_load_file failed */
}

/* OK to proceed */</pre>

=== Reseed ===

The OpenSSL API allows you to provide a seed and refresh the generator's state with reseeds at anytime during the program's execution. Two functions are provided for seeding and reseeding: <tt>RAND_seed</tt> and <tt>RAND_add</tt>. <tt>RAND_seed</tt> accepts a buffer and size; while <tt>RAND_add</tt> accepts a buffer, size, and entropy estimate in bytes. <tt>RAND_seed</tt> will call <tt>RAND_add</tt> assuming 100% entropy.

<tt>RAND_seed</tt> is shown below. The function is <tt>void</tt>, so it <nowiki>[apparently]</nowiki> cannot fail (or convey failures). Though the example uses the actual number of bytes written to the buffer, the entire buffer can be used to increase entropy (with hopes the unused bytes in the buffer has entropy to extract). Though you can use uninitialized bytes as input, you should not expect any entropy in the uninitialized bytes.

<pre>byte buffer[32];
int written = get_random_bytes(buffer, sizeof(buffer));

RAND_seed(buffer, written);
/* OK to proceed */</pre>

<tt>RAND_add</tt> is similar to <tt>RAND_seed</tt> but requires an entropy estimate. The estimate should be the number of full bytes of entropy in the buffer. If you have a 32 byte buffer with about 50% entropy, you should provide 16 as the entropy estimate. <tt>RAND_add</tt> is also a <tt>void</tt> function, so it cannot fail (or convey failures). The example also uses the actual number of bytes written to the buffer, but the entire buffer can be used to increase entropy. Note that <tt>RAND_add</tt> takes a <tt>double</tt>, so be sure to '''avoid''' integer math. Otherwise, the entropy estimate calculation could result in 0.

<pre>char phrase[64];
int written = get_random_phrase(phrase, sizeof(phrase));

RAND_add(phrase, written, 0.12f * written /* 12% */);
/* OK to proceed */</pre>

On Windows machines, you can also use <tt>RAND_screen</tt> and <tt>RAND_event</tt> on Windows machines. <tt>RAND_screen</tt> will mix the contents of the screen into the generator. <tt>RAND_event</tt> can be used with programs that process [http://msdn.microsoft.com/en-us/library/windows/desktop/ff381405(v=vs.85).aspx Windows Messages]. Both methods should only be used with interactive programs, and not services nor drivers.

=== Persisting ===

If you are worried about slow starts - or the time it takes to get the random number generator in good working order - you can write out a future seed and use it upon the next program execution. To save the future seed, use the library's <tt>RAND_save_file</tt> function. When using <tt>RAND_save_file</tt>, you only need to specify a filename. <tt>RAND_save_file</tt> returns the number of bytes written or -1 to indicate bytes were written without an appropriate seed (failure).

<pre>int written = RAND_save_file("prng.seed");
if(written <= 0)
/* RAND_save_file failed */

/* OK to proceed */</pre>

At program startup, you can attempt to read the saved seed with <tt>RAND_load_file</tt>. You can specify the number of bytes to read, or -1 to indicate the entire file should be used. The bytes read are automatically added to the generator. <tt>RAND_load_file</tt> returns the number of bytes read.

<pre>int read = RAND_load_file("prng.seed", -1);
if(read <= 0)
/* RAND_load_file failed */

/* OK to proceed */</pre>

If possible, you should use protected storage offered by the operating system. For example, you should avoid writing the file and store the seed in the [http://developer.apple.com/library/ios/#documentation/security/Conceptual/keychainServConcepts/iPhoneTasks/iPhoneTasks.html iOS Keychain], [http://developer.android.com/reference/android/security/KeyChain.html Android KeyChain], or [http://msdn.microsoft.com/en-us/library/ms995355.aspx Windows DPAPI]. When writing the seed to the filesystem, be sure to protect the the seed through the file system's permission scheme (Linux has not realized userland needs help from the kernel when storing secrets).

== Generation ==

After the generator has been seeded and is in good working order, you can extract bytes. You have three functions to extract bytes. First is <tt>RAND_bytes</tt> and the second is <tt>RAND_pseudo_bytes</tt>. Both are software based and produce a pseudo-random stream. The third method is hardware based and it reuses <tt>RAND_bytes</tt>.

=== Software ===

<tt>RAND_bytes</tt> will fetch cryptographically strong random bytes. Cryptographically strong bytes are suitable for high integrity needs, such as long term key generation. If your generator is using a software algorithm, then the bytes will be pseudo-random (but still cryptographically strong). <tt>RAND_bytes</tt> returns 1 for success, and 0 otherwise. If you changed the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>ERR_get_error</tt>.

<pre>byte buffer[128];

int rc = RAND_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 1) {
/* RAND_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

<tt>RAND_pseudo_bytes</tt> returns pseudo-random bytes which ''can'' be cryptographically strong. The function returns 1 if the bytes are cryptographically strong, and 0 otherwise. If your application has high integrity requirements, it should ''not'' use <tt>RAND_pseudo_bytes</tt>.

When using <tt>RAND_pseudo_bytes</tt>, both 0 and 1 indicate success. If you change the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>ERR_get_error</tt>.

<pre>byte buffer[32];

int rc = RAND_pseudo_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 0 && rc != 1) {
/* RAND_pseudo_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

=== Hardware ===

Hardware random number generators are almost always better to use than a software based generator. Hardware generators are often called True Random Number generators (TRNG) or Non-Deterministic Random Number Generators since they don't rely on the deterministic behavior of executing software instructions. Their bits streams are nearly always indistinguishable from random streams, and their entropy is always nearly 100%.

Some hardware generators are easier to use than other. For example, an [http://www.entropykey.co.uk EntropyKey] will provide a driver that replenishes <tt>/dev/random</tt>, so an application does not have to do anything special other than reading from the device. Other generators, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key], must be integrated into an application. When integrating generators using OpenSSL, you will use the library's <tt>ENGINE</tt> API.

To integrate a hardware based random number generator, you should load the apporpriate <tt>ENGINE</tt> for the hardware based implementation. Once loaded, set the engine's <tt>RAND_method</tt> method as default with <tt>ENGINE_METHOD_RAND</tt>. After you load the engine and set <tt>RAND_method</tt> for the hardware generator, you simply use <tt>RAND_bytes</tt> as discussed earlier. There are no special steps necessary after the configuration.

If you have OpenSSL 1.0.1 and a machine with [http://semiaccurate.com/2012/04/23/intel-launches-ivy-bridge-amid-crushing-marketing-buzzwords/#.UTYxLlHft0w 3rd generation Core i5 or i7 processor (Ivy Bridge)], then the Intel [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology] (formerly called Bull Mountain) is available to you. The hardware generator is accessed through the <tt>ENGINE</tt> API and wraps the <tt>rdrand</tt> instruction. According to Intel, [http://software.intel.com/en-us/articles/performance-impact-of-intel-secure-key-on-openssl RDRAND-enabled version of OpenSSL outperformed the non-RDRAND version by an order of magnitude].

To ensure <tt>RAND_bytes</tt> uses the hardware engine, you must perform three steps:

* load the <tt>rdrand</tt> engine
* acquire a handle to the engine
* set the default <tt>RAND_method</tt> to the engine

The code below shows you how to load the Intel random number generator engine and set the default <tt>RAND_method</tt>. The code is available for download at [[Media:test-rdrand.zip|test-rdrand.zip]]. While you can call <tt>ENGINE_load_builtin_engines</tt> to make all engines available, the code below focuses on the one engine of interest and loads it via <tt>ENGINE_load_rdrand</tt>. See [http://www.openssl.org/docs/crypto/engine.html OpenSSL's engine(3)] for more details on engines, their loading, and operation.

Casting the error code to a <tt>void*</tt> for hexadecimal display is an abuse (hack?), but it sidesteps problems with <tt>printf</tt> format specifiers on x86 and x64 hardware; and gives you an error that is easily consumed by <tt>openssl errstr</tt>.

<pre> 1 unsigned long err = 0;
2 int rc = 0;
3
4 ENGINE_load_rdrand();
5 ENGINE* eng = ENGINE_by_id("rdrand");
6 err = ERR_get_error();
7
8 if(NULL == eng) {
9 fprintf(stderr, "ENGINE_load_rdrand failed, err = %p\n", (void*)err);
10 abort(); /* failed */
11 }
12
13 rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
14 err = ERR_get_error();
15
16 if(1 != rc) {
17 fprintf(stderr, "ENGINE_set_default failed, err = %p\n", (void*)err);
18 abort(); /* failed */
19 }
20
21 /* OK to proceed */
22
23 ...
24 ENGINE_free(eng);
25 ENGINE_cleanup();</pre>

If you hardware does not support the Intel generator, you will recieve a <tt>NULL</tt> pointer at line 5 and encounter error 0x2606c043 at line 6. The error can then be fed to <tt>openssl errstr</tt>:

<pre>$ ./test-rdrand.exe
...
ENGINE_load_rdrand failed, err = 0x2606c043
$ openssl errstr 0x2606c043
error:2606C043:engine routines:ENGINE_FREE_UTIL:passed a null parameter</pre>

[[File:test-rdrand.png|thumb|250px|right|Verifying rdrand code path]] Line 13 attempts to set the default <tt>RAND_method</tt> to that provided by the engine using <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. Upon success, OpenSSL will internally use <tt>OPENSSL_ia32_rdrand</tt> for random number generation. To verify code correctness, simply set a breakpoint on the function and wait for the debugger to snap as shown in the figure to the right.

The 0x2606c043 error is actually caused by <tt>ENGINE_load_rdrand</tt>. The function will verify the capabilities of the hardware and load the generator's engine if available. <tt>ENGINE_load_rdrand</tt> is a <tt>void</tt> function, so it cannot fail or cannot convey failures (which we know is incorrect from a test run). The source code can be found in <tt>eng_rdrand.c</tt> and is shown below.

<pre>void ENGINE_load_rdrand (void)
{
extern unsigned int OPENSSL_ia32cap_P[];

if (OPENSSL_ia32cap_P[1] & (1<<(62-32)))
{
ENGINE *toadd = ENGINE_rdrand();
if(!toadd) return;
ENGINE_add(toadd);
ENGINE_free(toadd);
ERR_clear_error();
}
}</pre>

According to [http://software.intel.com/en-us/articles/performance-impact-of-intel-secure-key-on-openssl Intel documentation], the random number generator does not need to be seeded via the <tt>RAND_seed</tt> function because the generator is self-seeding. For optimal performance, code that is aware of the underlying random engine can forgo gathering entropy.

Additionally (or more importantly), the following will not cause a crash when using the hardware random number generator (and it fails silently so all looks good from outside the fishbowl):

<pre>/* Bad - don't do this in production */
byte seed[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
RAND_seed(seed, sizeof(seed));</pre>

Finally, you can test if your Mac OS X system has <tt>rdrand</tt> available with the following (thanks to Dave Zarzycki):

<pre>$ sysctl hw.optional.rdrand
hw.optional.rdrand: 1</pre>

On Linux, you can <tt>cat</tt> <tt>cpuinfo</tt>:
<pre>$ cat /proc/cpuinfo | grep -i rdrand
rdrand : 1</pre>

== Miscellaneous ==

Two miscellaneous items remaining are generator cleanup and status. <tt>RAND_cleanup</tt> securely erases the memory used by the random number generator.

You can query the generator's state with <tt>RAND_status</tt>. <tt>RAND_status</tt> returns 1 if the generator is in good working order. If your generator is not in good working order, you should reseed it with at least 256 bits (32 bytes) of entropy. The function [http://www.mail-archive.com/openssl-dev@openssl.org/msg04212.html purposefully hides the number of bytes needed].

== FIPS Mode ==

FIPS mode is a special mode of operation which specifies the library should operate according to the security policies and procedures specified in [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2]. The mode requires use of the FIPS Capable OpenSSL library, and must be enabled with a call to <tt>FIPS_mode_set</tt>. Once in FIPS mode, a ''default DRBG'' is used as specified in [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf SP800-90].

The default DRBG is 256-bit CTR AES using a derivation function, and is decided by the application and not the library module. In the case of an OpenSSL application it is specified in <tt>rand_lib.c</tt> via the <tt>OPENSSL_DRBG_DEFAULT_TYPE</tt> and <tt>OPENSSL_DRBG_DEFAULT_FLAGS</tt> preprocessor macros to allow them to be overridden by local compilation options or at runtime.

To use the FIPS random number generator, simply use <tt>RAND_bytes</tt> as described earlier. Note that the call to <tt>FIPS_mode_set</tt> must succeed in order to operate in FIPS 140 mode.

== Thread Safety ==

The random number generators (among other parts of OpenSSL) are not thread safe by default. To ensure thread safety, you must call <tt>[https://www.openssl.org/docs/crypto/threads.html CRYPTO_set_locking_callback]</tt>.

Talk:Random Numbers

2013-03-08T03:00:54Z

Ppelleti: void * casting hack?

Random Numbers

2013-03-08T02:56:10Z

Ppelleti: /* Thread Safety */ random number generators are not the only non-threadsafe part of OpenSSL (e. g. all error handling is non-threadsafe since it uses a thread-local error queue), and link manpage

[[Random Numbers]] are a cryptographic primitive and cornerstone to nearly all cryptographic systems. They are used in almost all areas of cryptography, from key agreement and transport to session keys for bulk encryption. A quality source of random bits and proper use of OpenSSL APIs will help ensure your program is cryptographically sound. On the other hand, a poor source of randomness or incorrect library usage could result in loss of security. This article will help you use random number generation routines correctly when programming with the OpenSSL library.

OpenSSL provides a number of software based random number generators based on a variety of sources. A software based random number generator creates random numbers by executing a software algorithm. There are a number of algorithms specified by a number of standard bodies including NIST, ANSI X9 committee (X9.17 and X9.31) and XXX. In addition, the library can use custom hardware if the hardware has an <tt>ENIGNE</tt> interface.

Good random numbers are notoriously hard to produce from deterministic processes such as a computer executing instructions. A number of cryptographic attacks have been developed because they are so hard to acquire. Especially vulnerable are headless servers, embedded devices, and mobile devices, and you may have to take extra steps to ensure an adequate supply of entropy is available. The extra steps could include ''Hedging'' on a headless server or embedded device, and ''Finger Painting'' on a mobile device. For recent attacks on low entropy devices (such as headless servers and mobile devices), see for example, ''[http://pages.cs.wisc.edu/~rist/papers/sslhedge.html When Good Randomness Goes Bad: Virtual Machine Reset Vulnerabilities and Hedging Deployed Cryptography ]'', ''[https://factorable.net/paper.html Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices]'', and ''[http://www.csoonline.com/article/723229/traffic-sensor-flaw-that-could-allow-driver-tracking-fixed Traffic sensor flaw that could allow driver tracking fixed]''.

== Entropy ==

Entropy is the measure of "randomness" in a sequence of bits. Different sources have different entropy. For example, a physical process in nature may have 100% entropy which appears purely random. On the other hand, the written English language provides about 3 bits/byte (or character) which is at most 38%. Some estimates have shown English characters provide only 1 bit/byte (or 12%). Other sources used as a random stream will have different estimates of entropy, and you will have to determine the quality.

Random number generators need quality entropy for input (a ''seed'', discussed below) and must produce quality output (''quod vide''). When using OpenSSL's APIs, you will be asked to estimate entropy when seeding or reseeding (input). When estimating entropy you should error on the low side to ensure proper fitness of the generator. When receiving bytes, you will receive a code indicating the success/failure of the operation and quality of the bytes (output).

Sometimes the operating system offers block access to hardware random number generators via <tt>/dev/hwrng</tt>. <tt>/dev/hwrng</tt> can be a low volume device, and could potentially block. For example, the [http://www.portwell.com.tw/download/sbc/catalog/Intel_80802_FWH.pdf Intel 82802 Firmware Hub] used with the and i840 chipset produces one byte of data in its register. At other times, <tt>/dev/hwrng</tt> can be a high volume device, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology]. In virtualized environments, <tt>/dev/hwrng</tt> might actually be a [http://wiki.qemu.org/Features-Done/VirtIORNG VirtIO RNG].

Entropy is important for a healthy program, and you should investigate hardware modules to help acquire it, especially if poor entropy or entropy depletion are a concern. There are a number of inexpensive and high quality hardware modules on the market, including a $40UK [http://www.entropykey.co.uk EntropyKey]. There are also a number of high quality and high priced hardware modules and accelerators.

If you lack <tt>/dev/random</tt> and cannot procure a hardware random number generator, you can also consider an alternate entropy gather such as the [http://egd.sourceforge.net Entropy Gathering Daemon (EGD)]. EGD is an userspace substitute for <tt>/dev/random</tt>. OpenSSL provides native support for EGD via <tt>RAND_egd</tt> to connect to the Unix domain socket, and <tt>RAND_egd_bytes</tt> to extract bytes from the daemon.

== Seeds ==

Most random number generators require a seed. A seed is a secret, unpredictable sequence of bytes that is transformed and then used to set the initial state of the generator. The seed ensures that each unique instance of a generator produces a unique stream of bits. No two generators should ever produce the same sequence of random numbers, even when faced with Virtual Machine (VM) rollback attacks (which could happen accidentally by a data center operator).

When seeding your generators, you should use at least 256 bits (32 bytes) of material. You can verify the required number of bits by grepping the source files for <tt>#define ENTROPY_NEEDED</tt>.

=== Initial ===

OpenSSL will attempt to seed the random number generator automatically upon instantiation if the operating system provides <tt>/dev/urandom</tt>. The <tt>urandom</tt> device may lack sufficient entropy for your needs, and you might want to reseed it immediately from <tt>/dev/random</tt>. On Unix and other operating systems that provide the block device, you can use <tt>RAND_load_file</tt> to load directly from <tt>/dev/random</tt>.

<pre>int rc = RAND_load_file("/dev/random", 32);
if(rc != 32) {
/* RAND_load_file failed */
}

/* OK to proceed */</pre>

On Windows, you should seed your generator from the Wincrypt function [http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx <tt>CryptGenRandom</tt>].

<pre>HCRYPTPROV hProvider = ...;
BYTE seed[32];
BOOL rc = 0;

rc = CryptGenRandom(hProvider, seed, sizeof(seed));
if(rc == FALSE) {
/* CryptGenRandom failed */
}

RAND_seed(seed, sizeof(seed));
/* OK to proceed */</pre>

=== Reseed ===

The OpenSSL API allows you to provide a seed and refresh the generator's state with reseeds at anytime during the program's execution. Two functions are provided for seeding and reseeding: <tt>RAND_seed</tt> and <tt>RAND_add</tt>. <tt>RAND_seed</tt> accepts a buffer and size; while <tt>RAND_add</tt> accepts a buffer, size, and entropy estimate in bytes. <tt>RAND_seed</tt> will call <tt>RAND_add</tt> assuming 100% entropy.

<tt>RAND_seed</tt> is shown below. The function is <tt>void</tt>, so it <nowiki>[apparently]</nowiki> cannot fail (or convey failures). Though the example uses the actual number of bytes written to the buffer, the entire buffer can be used to increase entropy (with hopes the unused bytes in the buffer has entropy to extract). Though you can use uninitialized bytes as input, you should not expect any entropy in the uninitialized bytes.

<pre>byte buffer[32];
int written = get_random_bytes(buffer, sizeof(buffer));

RAND_seed(buffer, written);
/* OK to proceed */</pre>

<tt>RAND_add</tt> is similar to <tt>RAND_seed</tt> but requires an entropy estimate. The estimate should be the number of full bytes of entropy in the buffer. If you have a 32 byte buffer with about 50% entropy, you should provide 16 as the entropy estimate. <tt>RAND_add</tt> is also a <tt>void</tt> function, so it cannot fail (or convey failures). The example also uses the actual number of bytes written to the buffer, but the entire buffer can be used to increase entropy. Note that <tt>RAND_add</tt> takes a <tt>double</tt>, so be sure to '''avoid''' integer math. Otherwise, the entropy estimate calculation could result in 0.

<pre>char phrase[64];
int written = get_random_phrase(phrase, sizeof(phrase));

RAND_add(phrase, written, 0.12f * written /* 12% */);
/* OK to proceed */</pre>

On Windows machines, you can also use <tt>RAND_screen</tt> and <tt>RAND_event</tt> on Windows machines. <tt>RAND_screen</tt> will mix the contents of the screen into the generator. <tt>RAND_event</tt> can be used with programs that process [http://msdn.microsoft.com/en-us/library/windows/desktop/ff381405(v=vs.85).aspx Windows Messages]. Both methods should only be used with interactive programs, and not services nor drivers.

=== Persisting ===

If you are worried about slow starts - or the time it takes to get the random number generator in good working order - you can write out a future seed and use it upon the next program execution. To save the future seed, use the library's <tt>RAND_save_file</tt> function. When using <tt>RAND_save_file</tt>, you only need to specify a filename. <tt>RAND_save_file</tt> returns the number of bytes written or -1 to indicate bytes were written without an appropriate seed (failure).

<pre>int written = RAND_save_file("prng.seed");
if(written <= 0)
/* RAND_save_file failed */

/* OK to proceed */</pre>

At program startup, you can attempt to read the saved seed with <tt>RAND_load_file</tt>. You can specify the number of bytes to read, or -1 to indicate the entire file should be used. The bytes read are automatically added to the generator. <tt>RAND_load_file</tt> returns the number of bytes read.

<pre>int read = RAND_load_file("prng.seed", -1);
if(read <= 0)
/* RAND_load_file failed */

/* OK to proceed */</pre>

If possible, you should use protected storage offered by the operating system. For example, you should avoid writing the file and store the seed in the [http://developer.apple.com/library/ios/#documentation/security/Conceptual/keychainServConcepts/iPhoneTasks/iPhoneTasks.html iOS Keychain], [http://developer.android.com/reference/android/security/KeyChain.html Android KeyChain], or [http://msdn.microsoft.com/en-us/library/ms995355.aspx Windows DPAPI]. When writing the seed to the filesystem, be sure to protect the the seed through the file system's permission scheme (Linux has not realized userland needs help from the kernel when storing secrets).

== Generation ==

After the generator has been seeded and is in good working order, you can extract bytes. You have three functions to extract bytes. First is <tt>RAND_bytes</tt> and the second is <tt>RAND_pseudo_bytes</tt>. Both are software based and produce a pseudo-random stream. The third method is hardware based and it reuses <tt>RAND_bytes</tt>.

=== Software ===

<tt>RAND_bytes</tt> will fetch cryptographically strong random bytes. Cryptographically strong bytes are suitable for high integrity needs, such as long term key generation. If your generator is using a software algorithm, then the bytes will be pseudo-random (but still cryptographically strong). <tt>RAND_bytes</tt> returns 1 for success, and 0 otherwise. If you changed the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>ERR_get_error</tt>.

<pre>byte buffer[128];

int rc = RAND_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 1) {
/* RAND_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

<tt>RAND_pseudo_bytes</tt> returns pseudo-random bytes which ''can'' be cryptographically strong. The function returns 1 if the bytes are cryptographically strong, and 0 otherwise. If your application has high integrity requirements, it should ''not'' use <tt>RAND_pseudo_bytes</tt>.

When using <tt>RAND_pseudo_bytes</tt>, both 0 and 1 indicate success. If you change the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>ERR_get_error</tt>.

<pre>byte buffer[32];

int rc = RAND_pseudo_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 0 && rc != 1) {
/* RAND_pseudo_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

=== Hardware ===

Hardware random number generators are almost always better to use than a software based generator. Hardware generators are often called True Random Number generators (TRNG) or Non-Deterministic Random Number Generators since they don't rely on the deterministic behavior of executing software instructions. Their bits streams are nearly always indistinguishable from random streams, and their entropy is always nearly 100%.

Some hardware generators are easier to use than other. For example, an [http://www.entropykey.co.uk EntropyKey] will provide a driver that replenishes <tt>/dev/random</tt>, so an application does not have to do anything special other than reading from the device. Other generators, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key], must be integrated into an application. When integrating generators using OpenSSL, you will use the library's <tt>ENGINE</tt> API.

To integrate a hardware based random number generator, you should load the apporpriate <tt>ENGINE</tt> for the hardware based implementation. Once loaded, set the engine's <tt>RAND_method</tt> method as default with <tt>ENGINE_METHOD_RAND</tt>. After you load the engine and set <tt>RAND_method</tt> for the hardware generator, you simply use <tt>RAND_bytes</tt> as discussed earlier. There are no special steps necessary after the configuration.

If you have OpenSSL 1.0.1 and a machine with [http://semiaccurate.com/2012/04/23/intel-launches-ivy-bridge-amid-crushing-marketing-buzzwords/#.UTYxLlHft0w 3rd generation Core i5 or i7 processor (Ivy Bridge)], then the Intel [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology] (formerly called Bull Mountain) is available to you. The hardware generator is accessed through the <tt>ENGINE</tt> API and wraps the <tt>rdrand</tt> instruction. According to Intel, [http://software.intel.com/en-us/articles/performance-impact-of-intel-secure-key-on-openssl RDRAND-enabled version of OpenSSL outperformed the non-RDRAND version by an order of magnitude].

To ensure <tt>RAND_bytes</tt> uses the hardware engine, you must perform three steps:

* load the <tt>rdrand</tt> engine
* acquire a handle to the engine
* set the default <tt>RAND_method</tt> to the engine

The code below shows you how to load the Intel random number generator engine and set the default <tt>RAND_method</tt>. The code is available for download at [[Media:test-rdrand.zip|test-rdrand.zip]]. While you can call <tt>ENGINE_load_builtin_engines</tt> to make all engines available, the code below focuses on the one engine of interest and loads it via <tt>ENGINE_load_rdrand</tt>. See [http://www.openssl.org/docs/crypto/engine.html OpenSSL's engine(3)] for more details on engines, their loading, and operation.

Casting the error code to a <tt>void*</tt> for hexadecimal display is an abuse (hack?), but it sidesteps problems with <tt>printf</tt> format specifiers on x86 and x64 hardware; and gives you an error that is easily consumed by <tt>openssl errstr</tt>.

<pre> 1 unsigned long err = 0;
2 int rc = 0;
3
4 ENGINE_load_rdrand();
5 ENGINE* eng = ENGINE_by_id("rdrand");
6 err = ERR_get_error();
7
8 if(NULL == eng) {
9 fprintf(stderr, "ENGINE_load_rdrand failed, err = %p\n", (void*)err);
10 abort(); /* failed */
11 }
12
13 rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
14 err = ERR_get_error();
15
16 if(1 != rc) {
17 fprintf(stderr, "ENGINE_set_default failed, err = %p\n", (void*)err);
18 abort(); /* failed */
19 }
20
21 /* OK to proceed */
22
23 ...
24 ENGINE_free(eng);
25 ENGINE_cleanup();</pre>

If you hardware does not support the Intel generator, you will recieve a <tt>NULL</tt> pointer at line 5 and encounter error 0x2606c043 at line 6. The error can then be fed to <tt>openssl errstr</tt>:

<pre>$ ./test-rdrand.exe
...
ENGINE_load_rdrand failed, err = 0x2606c043
$ openssl errstr 0x2606c043
error:2606C043:engine routines:ENGINE_FREE_UTIL:passed a null parameter</pre>

[[File:test-rdrand.png|thumb|250px|right|Verifying rdrand code path]] Line 13 attempts to set the default <tt>RAND_method</tt> to that provided by the engine using <tt>ENGINE_set_default</tt> with <tt>ENGINE_METHOD_RAND</tt>. Upon success, OpenSSL will internally use <tt>OPENSSL_ia32_rdrand</tt> for random number generation. To verify code correctness, simply set a breakpoint on the function and wait for the debugger to snap as shown in the figure to the right.

The 0x2606c043 error is actually caused by <tt>ENGINE_load_rdrand</tt>. The function will verify the capabilities of the hardware and load the generator's engine if available. <tt>ENGINE_load_rdrand</tt> is a <tt>void</tt> function, so it cannot fail or cannot convey failures (which we know is incorrect from a test run). The source code can be found in <tt>eng_rdrand.c</tt> and is shown below.

<pre>void ENGINE_load_rdrand (void)
{
extern unsigned int OPENSSL_ia32cap_P[];

if (OPENSSL_ia32cap_P[1] & (1<<(62-32)))
{
ENGINE *toadd = ENGINE_rdrand();
if(!toadd) return;
ENGINE_add(toadd);
ENGINE_free(toadd);
ERR_clear_error();
}
}</pre>

According to [http://software.intel.com/en-us/articles/performance-impact-of-intel-secure-key-on-openssl Intel documentation], the random number generator does not need to be seeded via the <tt>RAND_seed</tt> function because the generator is self-seeding. For optimal performance, code that is aware of the underlying random engine can forgo gathering entropy.

Additionally (or more importantly), the following will not cause a crash when using the hardware random number generator (and it fails silently so all looks good from outside the fishbowl):

<pre>/* Bad - don't do this in production */
byte seed[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
RAND_seed(seed, sizeof(seed));</pre>

Finally, you can test if your Mac OS X system has <tt>rdrand</tt> available with the following (thanks to Dave Zarzycki):

<pre>$ sysctl hw.optional.rdrand
hw.optional.rdrand: 1</pre>

On Linux, you can <tt>cat</tt> <tt>cpuinfo</tt>:
<pre>$ cat /proc/cpuinfo | grep -i rdrand
rdrand : 1</pre>

== Miscellaneous ==

Two miscellaneous items remaining are generator cleanup and status. <tt>RAND_cleanup</tt> securely erases the memory used by the random number generator.

You can query the generator's state with <tt>RAND_status</tt>. <tt>RAND_status</tt> returns 1 if the generator is in good working order. If your generator is not in good working order, you should reseed it with at least 256 bits (32 bytes) of entropy. The function [http://www.mail-archive.com/openssl-dev@openssl.org/msg04212.html purposefully hides the number of bytes needed].

== FIPS Mode ==

FIPS mode is a special mode of operation which specifies the library should operate according to the security policies and procedures specified in [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2]. The mode requires use of the FIPS Capable OpenSSL library, and must be enabled with a call to <tt>FIPS_mode_set</tt>. Once in FIPS mode, a ''default DRBG'' is used as specified in [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf SP800-90].

The default DRBG is 256-bit CTR AES using a derivation function, and is decided by the application and not the library module. In the case of an OpenSSL application it is specified in <tt>rand_lib.c</tt> via the <tt>OPENSSL_DRBG_DEFAULT_TYPE</tt> and <tt>OPENSSL_DRBG_DEFAULT_FLAGS</tt> preprocessor macros to allow them to be overridden by local compilation options or at runtime.

To use the FIPS random number generator, simply use <tt>RAND_bytes</tt> as described earlier. Note that the call to <tt>FIPS_mode_set</tt> must succeed in order to operate in FIPS 140 mode.

== Thread Safety ==

The random number generators (among other parts of OpenSSL) are not thread safe by default. To ensure thread safety, you must call <tt>[https://www.openssl.org/docs/crypto/threads.html CRYPTO_set_locking_callback]</tt>.

Talk:Libcrypto API

2013-03-06T01:25:56Z

Ppelleti: /* Return values */ agree with points about error handling

==Current Discussions==

=== Initialization, OPENSSL_conf and engines? ===

Should the recommended initialization code include a call to ENGINE_load_builtin_engines? (Or to OPENSSL_config, which calls ENGINE_load_builtin_engines.) Otherwise, the RdRand engine for getting better random numbers from newer Intel chips (as one example) won't be used.

(My own thoughts on OpenSSL initialization are [https://en.wikibooks.org/wiki/OpenSSL/Initialization here].)

--[[User:Ppelleti|Ppelleti]] 18:05, 3 March 2013 (UTC)

Hmmm - I've not come across this as a recommendation before. What is the original source for your recommendation?

--[[User:Matt|Matt]] 22:15, 3 March 2013 (UTC)

It's not from any existing documentation source, other than gleaning some information from the [https://www.openssl.org/docs/crypto/engine.html#Application_requirements engine] manpage (see "Automatically using builtin ENGINE implementations") and the CHANGES file. But mostly it's my own conclusion, based on reading the source code and performing experiments.

The basic question I was trying to answer was, on modern Intel processors which support AES-NI and RdRand, is OpenSSL taking advantage of these hardware features. The answer appears to be different for the two different features. For AES-NI, it appears from the source code (and was recently [http://marc.info/?l=openssl-users&m=136209324829507&w=2 confirmed] on the mailing list) that AES-NI is automatically used if it is available, without needing to do anything special.

However, for RdRand, it appears that the answer is different. In the source code, there is a separate RdRand engine. If the RdRand engine is not used, then the default pool implementation in md_rand.c is used, and you don't get the benefits of RdRand.

From the section I already mentioned in the "engine" manpage, it sounded like no engines are used by default, and you must enable them by calling ENGINE_load_builtin_engines() followed by ENGINE_register_all_complete(). Although the CHANGES file partially contradicts this advice, saying:

<pre>
*) Add call to ENGINE_register_all_complete() to
ENGINE_load_builtin_engines(), so some implementations get used
automatically instead of needing explicit application support.
[Steve Henson]
</pre>

I did some experiments on a machine with RdRand. I wrote the following little bit of code:

<pre>
ENGINE *rnd = ENGINE_get_default_RAND ();
if (rnd)
printf ("default rand engine: %s\n", ENGINE_get_name (rnd));
else
printf ("no default rand engine\n");
</pre>

If I initialize OpenSSL the typical way:

<pre>
SSL_load_error_strings(); /* readable error messages */
SSL_library_init(); /* initialize library */
OpenSSL_add_all_algorithms();
</pre>

without calling any ENGINE functions, then my little code fragment will print "no default rand engine", indicating the implementation from md_rand.c is being used. But if I call ENGINE_load_builtin_engines() after the other initialization functions, and before my little test, it then prints out that RdRand is the default rand engine.

So, this is how I drew the conclusion that it's necessary to call ENGINE_load_builtin_engines() as part of your initialization, if you want to get RdRand support.

However, this is all made a little bit trickier by the fact that OpenSSL_add_all_algorithms() can actually mean one of two vastly different things, depending on a #define at compile time. If OPENSSL_LOAD_CONF is defined, then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_conf(), but if OPENSSL_LOAD_CONF is not defined (which is the default), then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_noconf().

OPENSSL_add_all_algorithms_conf() is a two-line function:

<pre>
void OPENSSL_add_all_algorithms_conf(void)
{
OPENSSL_add_all_algorithms_noconf();
OPENSSL_config(NULL);
}
</pre>

So the difference is that if OPENSSL_LOAD_CONF is defined, then OPENSSL_config() is called, when it otherwise wouldn't be. What does this have to do with RdRand? The thing is that OPENSSL_config() calls ENGINE_load_builtin_engines(). (And then ENGINE_load_builtin_engines() in turn calls ENGINE_register_all_complete(), as mentioned in the CHANGES entry.)

So, to get RdRand support, you can either #define OPENSSL_LOAD_CONF when building your program, or you can call either ENGINE_load_builtin_engines() or OPENSSL_config() in your initialization sequence. However, it appears that calling ENGINE_load_builtin_engines() more than once will leak memory, so ideally you don't want to call ENGINE_load_builtin_engines() if you also plan on calling OPENSSL_config(), or if you've defined OPENSSL_LOAD_CONF. (Of course, since it's just a small fixed-size leak at initialization, this wouldn't really be a practical problem, but still makes me feel icky.)

--[[User:Ppelleti|Ppelleti]] 04:33, 4 March 2013 (UTC)

Note that the use of OPENSSL_config() '''is''' recommended during initialisation: this is mentioned in the manual page. Currently the routines associated with OPENSSL_config() can be used for adding OIDs and configuring ENGINEs. In future it may well do much more and calling OPENSSL_config() (or the actual conf library if finer control is needed) will automatically take advantage of that.

Here's an example of what I mean. Suppose you have a user who wants to do something weird with an ENGINE: perhaps load an unusual one that needs various ctrls to get it to work. Maybe they want to do something peculiar like use RSA with one ENGINE and DSA with another. You'd have to delve quite deep into the way ENGINE works to support that kind of thing and would it be worth it for something hardly anyone would use?

If instead you called OPENSSL_config() that user can just set up the config file to do what they want and the application writer doesn't have to worry about all the messy ENGINE calls.

--[[User:Steve|Steve]] 13:37, 4 March 2013 (UTC)

So, I've added a call to OPENSSL_config() during the initialisation example. This I think covers both Steve's point above, and Patrick's concern about loading the builtin engines.

--[[User:Matt|Matt]] 21:01, 4 March 2013 (UTC)

=== Return values ===

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure. It would be '''really''' useful if the exceptions were all documented, double checking with the source.

--[[User:Steve|Steve]] 13:57, 4 March 2013 (UTC)

I've added this to the error handling section

--[[User:Matt|Matt]] 21:05, 4 March 2013 (UTC)

Yeah, I've noticed this, and in my own code I've chosen to always compare OpenSSL return values against 1 explicitly. In the spirit of "be bold", I've gone ahead and added this as a recommendation on the page itself. But if anyone thinks this is not a good approach, feel free to change it.

--[[User:Ppelleti|Ppelleti]] 00:37, 5 March 2013 (UTC)

I'm happy with that...but now I'm wondering whether for consistency we should use this throughout the examples that we post on the wiki.

Also, the way the page now reads it looks like we are only recommending your idiom for those functions which might return something other than 0 or 1. Would it not be better to recommend this for all functions even if they do only return 0 or 1. By getting into the habit of always checking in this way it probably means you are less likely to inadvertently go wrong.

Finally, is it not the case that most of the time the if statement is checking of an error condition. Therefore shouldn't we write the code more like this:

<pre>
if(1 != some_function())
/* handle the error */
</pre>
--[[User:Matt|Matt]] 22:31, 5 March 2013 (UTC)

I agree on both points. I'd meant "this idiom can be used to avoid having to worry about whether a particular function can return more than just 0 or 1 or not", and I always use that idiom in my own code for precisely that reason. But I don't think I made my meaning clear enough on the page. I've rephrased it a bit now, but the phrasing still feels a bit awkward, so feel free to improve it to be clearer.

And yes, I agree about flipping the sense of the check. I'd just been trying to be symmetrical with the example right above it.

But I've now flipped the sense, and I've also modified the earlier example (demonstrating "goto") to use the "1 !=" idiom.

--[[User:Ppelleti|Ppelleti]] 01:25, 6 March 2013 (UTC)

==Old Discussions==

=== Best practices for printing errors ===

I'm curious about the recommendation to do this:

<pre>
err:
unsigned long errCode;
while(errCode = ERR_get_error())
{
char *err = ERR_error_string(errCode, NULL);
printf("%s\n", err);
}
</pre>

Wouldn't it be much simpler to just do:

<pre>
err:
ERR_print_errors_fp(stderr);
</pre>

Or, if one really does want to iterate through each line of the error queue individually, wouldn't it still be better for us to recommend using ERR_error_string_n with an explicit buffer? ERR_error_string with a NULL argument is not thread-safe.

--[[User:Ppelleti|Ppelleti]] 18:12, 3 March 2013 (UTC)

Either way does the trick, but I agree yours is simpler. I'll change it.,

--[[User:Matt|Matt]] 22:16, 3 March 2013 (UTC)

ERR_print_errors_fp is the best "call it and forget it" method for errors if it
is appropriate to use an fp. Calling the ERR routines directly can be done but
it's trickier and the example given is incomplete: I'd have to check it further
to see how best to call all the routines. [per Steve Henson]

--[[User:Stevem|Stevem]] 14:27, 4 March 2013 (UTC)

Libcrypto API

2013-03-06T01:20:44Z

Ppelleti: /* Error Handling */ address some issues brought up on the talk page

OpenSSL provides two primary libraries: [[Libssl API|libssl]] and libcrypto. The libcrypto library provides the fundamental cryptographic routines used by [[Libssl API|libssl]]. You can however use libcrypto without using [[Libssl API|libssl]].

==Getting Started==

In order to use libcrypto it must first (typically) be initialised:

#include <openssl/conf.h>
#include <openssl/evp.h>

int main(int arc, char *argv[])
{
/* Load the human readable error strings for libcrypto */
ERR_load_crypto_strings();

/* Load all digest and cipher algorithms */
OpenSSL_add_all_algorithms();

/* Load config file, and other important initialisation */
OPENSSL_config(NULL);

/* ... Do some crypto stuff here ... */

/* Clean up */

/* Removes all digests and ciphers */
EVP_cleanup();

/* Remove error strings */
ERR_free_strings();

return 0;
}

==High Level and Low Level Interfaces==

For most uses, users should use the high level interface that is provided for performing cryptographic operations. This is known as the [[EVP]] interface (short for Envelope). This interface provides a suite of functions for performing encryption/decryption (both symmetric and asymmetric), signing/verifying, as well as generating hashes and MAC codes, across the full range of OpenSSL supported algorithms and modes. Working with the high level interface means that a lot of the complexity of performing cryptographic operations is hidden from view. A single consistent API is provided. In the event that you need to change your code to use a different algorithm (for example), then this is a simple change when using the high level interface. In addition low level issues such as padding and encryption modes are all handled for you.

Refer to [[EVP]] for further information on the high level interface.

In addition to the high level interface, OpenSSL also provides low level interfaces for working directly with the individual algorithms. These low level interfaces are not recommended for the novice user, but provide a degree of control that may not be possible when using only the high level interface.

==Error Handling==

Most OpenSSL functions will return an integer to indicate success or failure. Typically a function will return 1 on success or 0 on error. All return codes should be checked and handled as appropriate.

It is common to see errors handled in a way similar to the following:

if(1 != EVP_xxx()) goto err;
if(1 != EVP_yyy()) goto err;

/* ... do some stuff ... */

err:
ERR_print_errors_fp(stderr);

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure.

One way to avoid being bitten by this potential problem is to always use this idiom to check for errors when calling an OpenSSL function:

<pre>
if (1 != some_openssl_function())
/* handle error */
</pre>

== Further libcrypto information ==

There are a number of other pages that cover specific aspects of working with libcrypto:
* [[EVP|EVP High level interface for cryptographic operations]]
* [[Low Level Cryptographic APIs]]
* [[Random Numbers|Handling Random Numbers]]
* [[BIO|Working with BIOs]]

==See also==
* [[Libssl API]]

Talk:Libcrypto API

2013-03-05T01:48:55Z

Ppelleti: /* Return values */ spelling

==Current Discussions==

=== Initialization, OPENSSL_conf and engines? ===

Should the recommended initialization code include a call to ENGINE_load_builtin_engines? (Or to OPENSSL_config, which calls ENGINE_load_builtin_engines.) Otherwise, the RdRand engine for getting better random numbers from newer Intel chips (as one example) won't be used.

(My own thoughts on OpenSSL initialization are [https://en.wikibooks.org/wiki/OpenSSL/Initialization here].)

--[[User:Ppelleti|Ppelleti]] 18:05, 3 March 2013 (UTC)

Hmmm - I've not come across this as a recommendation before. What is the original source for your recommendation?

--[[User:Matt|Matt]] 22:15, 3 March 2013 (UTC)

It's not from any existing documentation source, other than gleaning some information from the [https://www.openssl.org/docs/crypto/engine.html#Application_requirements engine] manpage (see "Automatically using builtin ENGINE implementations") and the CHANGES file. But mostly it's my own conclusion, based on reading the source code and performing experiments.

The basic question I was trying to answer was, on modern Intel processors which support AES-NI and RdRand, is OpenSSL taking advantage of these hardware features. The answer appears to be different for the two different features. For AES-NI, it appears from the source code (and was recently [http://marc.info/?l=openssl-users&m=136209324829507&w=2 confirmed] on the mailing list) that AES-NI is automatically used if it is available, without needing to do anything special.

However, for RdRand, it appears that the answer is different. In the source code, there is a separate RdRand engine. If the RdRand engine is not used, then the default pool implementation in md_rand.c is used, and you don't get the benefits of RdRand.

From the section I already mentioned in the "engine" manpage, it sounded like no engines are used by default, and you must enable them by calling ENGINE_load_builtin_engines() followed by ENGINE_register_all_complete(). Although the CHANGES file partially contradicts this advice, saying:

<pre>
*) Add call to ENGINE_register_all_complete() to
ENGINE_load_builtin_engines(), so some implementations get used
automatically instead of needing explicit application support.
[Steve Henson]
</pre>

I did some experiments on a machine with RdRand. I wrote the following little bit of code:

<pre>
ENGINE *rnd = ENGINE_get_default_RAND ();
if (rnd)
printf ("default rand engine: %s\n", ENGINE_get_name (rnd));
else
printf ("no default rand engine\n");
</pre>

If I initialize OpenSSL the typical way:

<pre>
SSL_load_error_strings(); /* readable error messages */
SSL_library_init(); /* initialize library */
OpenSSL_add_all_algorithms();
</pre>

without calling any ENGINE functions, then my little code fragment will print "no default rand engine", indicating the implementation from md_rand.c is being used. But if I call ENGINE_load_builtin_engines() after the other initialization functions, and before my little test, it then prints out that RdRand is the default rand engine.

So, this is how I drew the conclusion that it's necessary to call ENGINE_load_builtin_engines() as part of your initialization, if you want to get RdRand support.

However, this is all made a little bit trickier by the fact that OpenSSL_add_all_algorithms() can actually mean one of two vastly different things, depending on a #define at compile time. If OPENSSL_LOAD_CONF is defined, then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_conf(), but if OPENSSL_LOAD_CONF is not defined (which is the default), then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_noconf().

OPENSSL_add_all_algorithms_conf() is a two-line function:

<pre>
void OPENSSL_add_all_algorithms_conf(void)
{
OPENSSL_add_all_algorithms_noconf();
OPENSSL_config(NULL);
}
</pre>

So the difference is that if OPENSSL_LOAD_CONF is defined, then OPENSSL_config() is called, when it otherwise wouldn't be. What does this have to do with RdRand? The thing is that OPENSSL_config() calls ENGINE_load_builtin_engines(). (And then ENGINE_load_builtin_engines() in turn calls ENGINE_register_all_complete(), as mentioned in the CHANGES entry.)

So, to get RdRand support, you can either #define OPENSSL_LOAD_CONF when building your program, or you can call either ENGINE_load_builtin_engines() or OPENSSL_config() in your initialization sequence. However, it appears that calling ENGINE_load_builtin_engines() more than once will leak memory, so ideally you don't want to call ENGINE_load_builtin_engines() if you also plan on calling OPENSSL_config(), or if you've defined OPENSSL_LOAD_CONF. (Of course, since it's just a small fixed-size leak at initialization, this wouldn't really be a practical problem, but still makes me feel icky.)

--[[User:Ppelleti|Ppelleti]] 04:33, 4 March 2013 (UTC)

Note that the use of OPENSSL_config() '''is''' recommended during initialisation: this is mentioned in the manual page. Currently the routines associated with OPENSSL_config() can be used for adding OIDs and configuring ENGINEs. In future it may well do much more and calling OPENSSL_config() (or the actual conf library if finer control is needed) will automatically take advantage of that.

Here's an example of what I mean. Suppose you have a user who wants to do something weird with an ENGINE: perhaps load an unusual one that needs various ctrls to get it to work. Maybe they want to do something peculiar like use RSA with one ENGINE and DSA with another. You'd have to delve quite deep into the way ENGINE works to support that kind of thing and would it be worth it for something hardly anyone would use?

If instead you called OPENSSL_config() that user can just set up the config file to do what they want and the application writer doesn't have to worry about all the messy ENGINE calls.

--[[User:Steve|Steve]] 13:37, 4 March 2013 (UTC)

So, I've added a call to OPENSSL_config() during the initialisation example. This I think covers both Steve's point above, and Patrick's concern about loading the builtin engines.

--[[User:Matt|Matt]] 21:01, 4 March 2013 (UTC)

=== Return values ===

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure. It would be '''really''' useful if the exceptions were all documented, double checking with the source.

--[[User:Steve|Steve]] 13:57, 4 March 2013 (UTC)

I've added this to the error handling section

--[[User:Matt|Matt]] 21:05, 4 March 2013 (UTC)

Yeah, I've noticed this, and in my own code I've chosen to always compare OpenSSL return values against 1 explicitly. In the spirit of "be bold", I've gone ahead and added this as a recommendation on the page itself. But if anyone thinks this is not a good approach, feel free to change it.

--[[User:Ppelleti|Ppelleti]] 00:37, 5 March 2013 (UTC)

==Old Discussions==

=== Best practices for printing errors ===

I'm curious about the recommendation to do this:

<pre>
err:
unsigned long errCode;
while(errCode = ERR_get_error())
{
char *err = ERR_error_string(errCode, NULL);
printf("%s\n", err);
}
</pre>

Wouldn't it be much simpler to just do:

<pre>
err:
ERR_print_errors_fp(stderr);
</pre>

Or, if one really does want to iterate through each line of the error queue individually, wouldn't it still be better for us to recommend using ERR_error_string_n with an explicit buffer? ERR_error_string with a NULL argument is not thread-safe.

--[[User:Ppelleti|Ppelleti]] 18:12, 3 March 2013 (UTC)

Either way does the trick, but I agree yours is simpler. I'll change it.,

--[[User:Matt|Matt]] 22:16, 3 March 2013 (UTC)

ERR_print_errors_fp is the best "call it and forget it" method for errors if it
is appropriate to use an fp. Calling the ERR routines directly can be done but
it's trickier and the example given is incomplete: I'd have to check it further
to see how best to call all the routines. [per Steve Henson]

--[[User:Stevem|Stevem]] 14:27, 4 March 2013 (UTC)

Talk:Libcrypto API

2013-03-05T00:37:54Z

Ppelleti: /* Return values */

==Current Discussions==

=== Initialization, OPENSSL_conf and engines? ===

Should the recommended initialization code include a call to ENGINE_load_builtin_engines? (Or to OPENSSL_config, which calls ENGINE_load_builtin_engines.) Otherwise, the RdRand engine for getting better random numbers from newer Intel chips (as one example) won't be used.

(My own thoughts on OpenSSL initialization are [https://en.wikibooks.org/wiki/OpenSSL/Initialization here].)

--[[User:Ppelleti|Ppelleti]] 18:05, 3 March 2013 (UTC)

Hmmm - I've not come across this as a recommendation before. What is the original source for your recommendation?

--[[User:Matt|Matt]] 22:15, 3 March 2013 (UTC)

It's not from any existing documentation source, other than gleaning some information from the [https://www.openssl.org/docs/crypto/engine.html#Application_requirements engine] manpage (see "Automatically using builtin ENGINE implementations") and the CHANGES file. But mostly it's my own conclusion, based on reading the source code and performing experiments.

The basic question I was trying to answer was, on modern Intel processors which support AES-NI and RdRand, is OpenSSL taking advantage of these hardware features. The answer appears to be different for the two different features. For AES-NI, it appears from the source code (and was recently [http://marc.info/?l=openssl-users&m=136209324829507&w=2 confirmed] on the mailing list) that AES-NI is automatically used if it is available, without needing to do anything special.

However, for RdRand, it appears that the answer is different. In the source code, there is a separate RdRand engine. If the RdRand engine is not used, then the default pool implementation in md_rand.c is used, and you don't get the benefits of RdRand.

From the section I already mentioned in the "engine" manpage, it sounded like no engines are used by default, and you must enable them by calling ENGINE_load_builtin_engines() followed by ENGINE_register_all_complete(). Although the CHANGES file partially contradicts this advice, saying:

<pre>
*) Add call to ENGINE_register_all_complete() to
ENGINE_load_builtin_engines(), so some implementations get used
automatically instead of needing explicit application support.
[Steve Henson]
</pre>

I did some experiments on a machine with RdRand. I wrote the following little bit of code:

<pre>
ENGINE *rnd = ENGINE_get_default_RAND ();
if (rnd)
printf ("default rand engine: %s\n", ENGINE_get_name (rnd));
else
printf ("no default rand engine\n");
</pre>

If I initialize OpenSSL the typical way:

<pre>
SSL_load_error_strings(); /* readable error messages */
SSL_library_init(); /* initialize library */
OpenSSL_add_all_algorithms();
</pre>

without calling any ENGINE functions, then my little code fragment will print "no default rand engine", indicating the implementation from md_rand.c is being used. But if I call ENGINE_load_builtin_engines() after the other initialization functions, and before my little test, it then prints out that RdRand is the default rand engine.

So, this is how I drew the conclusion that it's necessary to call ENGINE_load_builtin_engines() as part of your initialization, if you want to get RdRand support.

However, this is all made a little bit trickier by the fact that OpenSSL_add_all_algorithms() can actually mean one of two vastly different things, depending on a #define at compile time. If OPENSSL_LOAD_CONF is defined, then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_conf(), but if OPENSSL_LOAD_CONF is not defined (which is the default), then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_noconf().

OPENSSL_add_all_algorithms_conf() is a two-line function:

<pre>
void OPENSSL_add_all_algorithms_conf(void)
{
OPENSSL_add_all_algorithms_noconf();
OPENSSL_config(NULL);
}
</pre>

So the difference is that if OPENSSL_LOAD_CONF is defined, then OPENSSL_config() is called, when it otherwise wouldn't be. What does this have to do with RdRand? The thing is that OPENSSL_config() calls ENGINE_load_builtin_engines(). (And then ENGINE_load_builtin_engines() in turn calls ENGINE_register_all_complete(), as mentioned in the CHANGES entry.)

So, to get RdRand support, you can either #define OPENSSL_LOAD_CONF when building your program, or you can call either ENGINE_load_builtin_engines() or OPENSSL_config() in your initialization sequence. However, it appears that calling ENGINE_load_builtin_engines() more than once will leak memory, so ideally you don't want to call ENGINE_load_builtin_engines() if you also plan on calling OPENSSL_config(), or if you've defined OPENSSL_LOAD_CONF. (Of course, since it's just a small fixed-size leak at initialization, this wouldn't really be a practical problem, but still makes me feel icky.)

--[[User:Ppelleti|Ppelleti]] 04:33, 4 March 2013 (UTC)

Note that the use of OPENSSL_config() '''is''' recommended during initialisation: this is mentioned in the manual page. Currently the routines associated with OPENSSL_config() can be used for adding OIDs and configuring ENGINEs. In future it may well do much more and calling OPENSSL_config() (or the actual conf library if finer control is needed) will automatically take advantage of that.

Here's an example of what I mean. Suppose you have a user who wants to do something weird with an ENGINE: perhaps load an unusual one that needs various ctrls to get it to work. Maybe they want to do something peculiar like use RSA with one ENGINE and DSA with another. You'd have to delve quite deep into the way ENGINE works to support that kind of thing and would it be worth it for something hardly anyone would use?

If instead you called OPENSSL_config() that user can just set up the config file to do what they want and the application writer doesn't have to worry about all the messy ENGINE calls.

--[[User:Steve|Steve]] 13:37, 4 March 2013 (UTC)

So, I've added a call to OPENSSL_config() during the initialisation example. This I think covers both Steve's point above, and Patrick's concern about loading the builtin engines.

--[[User:Matt|Matt]] 21:01, 4 March 2013 (UTC)

=== Return values ===

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure. It would be '''really''' useful if the exceptions were all documented, double checking with the source.

--[[User:Steve|Steve]] 13:57, 4 March 2013 (UTC)

I've added this to the error handling section

--[[User:Matt|Matt]] 21:05, 4 March 2013 (UTC)

Yeah, I've noticed this, and in my own code I've chosen to always compare OpenSSL return values against 1 explicitly. In the spirit of "be bold", I've gone ahead and added this as a recommendation on the page itself. But if anyone things this is not a good approach, feel free to change it.

--[[User:Ppelleti|Ppelleti]] 00:37, 5 March 2013 (UTC)

==Old Discussions==

=== Best practices for printing errors ===

I'm curious about the recommendation to do this:

<pre>
err:
unsigned long errCode;
while(errCode = ERR_get_error())
{
char *err = ERR_error_string(errCode, NULL);
printf("%s\n", err);
}
</pre>

Wouldn't it be much simpler to just do:

<pre>
err:
ERR_print_errors_fp(stderr);
</pre>

Or, if one really does want to iterate through each line of the error queue individually, wouldn't it still be better for us to recommend using ERR_error_string_n with an explicit buffer? ERR_error_string with a NULL argument is not thread-safe.

--[[User:Ppelleti|Ppelleti]] 18:12, 3 March 2013 (UTC)

Either way does the trick, but I agree yours is simpler. I'll change it.,

--[[User:Matt|Matt]] 22:16, 3 March 2013 (UTC)

ERR_print_errors_fp is the best "call it and forget it" method for errors if it
is appropriate to use an fp. Calling the ERR routines directly can be done but
it's trickier and the example given is incomplete: I'd have to check it further
to see how best to call all the routines. [per Steve Henson]

--[[User:Stevem|Stevem]] 14:27, 4 March 2013 (UTC)

Libcrypto API

2013-03-05T00:34:13Z

Ppelleti: /* See also */ this link to BIO is now redundant, because there is another link at a more appropriate place on the page

OpenSSL provides two primary libraries: [[Libssl API|libssl]] and libcrypto. The libcrypto library provides the fundamental cryptographic routines used by [[Libssl API|libssl]]. You can however use libcrypto without using [[Libssl API|libssl]].

==Getting Started==

In order to use libcrypto it must first (typically) be initialised:

#include <openssl/conf.h>
#include <openssl/evp.h>

int main(int arc, char *argv[])
{
/* Load the human readable error strings for libcrypto */
ERR_load_crypto_strings();

/* Load all digest and cipher algorithms */
OpenSSL_add_all_algorithms();

/* Load config file, and other important initialisation */
OPENSSL_config(NULL);

/* ... Do some crypto stuff here ... */

/* Clean up */

/* Removes all digests and ciphers */
EVP_cleanup();

/* Remove error strings */
ERR_free_strings();

return 0;
}

==High Level and Low Level Interfaces==

For most uses, users should use the high level interface that is provided for performing cryptographic operations. This is known as the [[EVP]] interface (short for Envelope). This interface provides a suite of functions for performing encryption/decryption (both symmetric and asymmetric), signing/verifying, as well as generating hashes and MAC codes, across the full range of OpenSSL supported algorithms and modes. Working with the high level interface means that a lot of the complexity of performing cryptographic operations is hidden from view. A single consistent API is provided. In the event that you need to change your code to use a different algorithm (for example), then this is a simple change when using the high level interface. In addition low level issues such as padding and encryption modes are all handled for you.

Refer to [[EVP]] for further information on the high level interface.

In addition to the high level interface, OpenSSL also provides low level interfaces for working directly with the individual algorithms. These low level interfaces are not recommended for the novice user, but provide a degree of control that may not be possible when using only the high level interface.

==Error Handling==

Most OpenSSL functions will return an integer to indicate success or failure. Typically a function will return 1 on success or 0 on error. All return codes should be checked and handled as appropriate.

It is common to see errors handled in a way similar to the following:

if(!EVP_xxx()) goto err;
if(!EVP_yyy()) goto err;

/* ... do some stuff ... */

err:
ERR_print_errors_fp(stderr);

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure.

One way to be safe is to use this idiom:

<pre>
if (1 == some_verify_function())
/* signature successful */
</pre>

== Further libcrypto information ==

There are a number of other pages that cover specific aspects of working with libcrypto:
* [[EVP|EVP High level interface for cryptographic operations]]
* [[Low Level Cryptographic APIs]]
* [[Random Numbers|Handling Random Numbers]]
* [[BIO|Working with BIOs]]

==See also==
* [[Libssl API]]

Libcrypto API

2013-03-05T00:32:29Z

Ppelleti: /* Error Handling */ suggest explicitly comparing the return value against 1, which is what I do in my code

OpenSSL provides two primary libraries: [[Libssl API|libssl]] and libcrypto. The libcrypto library provides the fundamental cryptographic routines used by [[Libssl API|libssl]]. You can however use libcrypto without using [[Libssl API|libssl]].

==Getting Started==

In order to use libcrypto it must first (typically) be initialised:

#include <openssl/conf.h>
#include <openssl/evp.h>

int main(int arc, char *argv[])
{
/* Load the human readable error strings for libcrypto */
ERR_load_crypto_strings();

/* Load all digest and cipher algorithms */
OpenSSL_add_all_algorithms();

/* Load config file, and other important initialisation */
OPENSSL_config(NULL);

/* ... Do some crypto stuff here ... */

/* Clean up */

/* Removes all digests and ciphers */
EVP_cleanup();

/* Remove error strings */
ERR_free_strings();

return 0;
}

==High Level and Low Level Interfaces==

For most uses, users should use the high level interface that is provided for performing cryptographic operations. This is known as the [[EVP]] interface (short for Envelope). This interface provides a suite of functions for performing encryption/decryption (both symmetric and asymmetric), signing/verifying, as well as generating hashes and MAC codes, across the full range of OpenSSL supported algorithms and modes. Working with the high level interface means that a lot of the complexity of performing cryptographic operations is hidden from view. A single consistent API is provided. In the event that you need to change your code to use a different algorithm (for example), then this is a simple change when using the high level interface. In addition low level issues such as padding and encryption modes are all handled for you.

Refer to [[EVP]] for further information on the high level interface.

In addition to the high level interface, OpenSSL also provides low level interfaces for working directly with the individual algorithms. These low level interfaces are not recommended for the novice user, but provide a degree of control that may not be possible when using only the high level interface.

==Error Handling==

Most OpenSSL functions will return an integer to indicate success or failure. Typically a function will return 1 on success or 0 on error. All return codes should be checked and handled as appropriate.

It is common to see errors handled in a way similar to the following:

if(!EVP_xxx()) goto err;
if(!EVP_yyy()) goto err;

/* ... do some stuff ... */

err:
ERR_print_errors_fp(stderr);

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure.

One way to be safe is to use this idiom:

<pre>
if (1 == some_verify_function())
/* signature successful */
</pre>

== Further libcrypto information ==

There are a number of other pages that cover specific aspects of working with libcrypto:
* [[EVP|EVP High level interface for cryptographic operations]]
* [[Low Level Cryptographic APIs]]
* [[Random Numbers|Handling Random Numbers]]
* [[BIO|Working with BIOs]]

==See also==
* [[Libssl API]]
* [[BIO]]

User:Ppelleti

2013-03-04T05:34:55Z

Ppelleti: brief info about self

Talk:Libcrypto API

2013-03-04T04:33:36Z

Ppelleti: /* Initialization and engines? */

== Initialization and engines? ==

Should the recommended initialization code include a call to ENGINE_load_builtin_engines? (Or to OPENSSL_config, which calls ENGINE_load_builtin_engines.) Otherwise, the RdRand engine for getting better random numbers from newer Intel chips (as one example) won't be used.

(My own thoughts on OpenSSL initialization are [https://en.wikibooks.org/wiki/OpenSSL/Initialization here].)

--[[User:Ppelleti|Ppelleti]] 18:05, 3 March 2013 (UTC)

Hmmm - I've not come across this as a recommendation before. What is the original source for your recommendation?

--[[User:Matt|Matt]] 22:15, 3 March 2013 (UTC)

It's not from any existing documentation source, other than gleaning some information from the [https://www.openssl.org/docs/crypto/engine.html#Application_requirements engine] manpage (see "Automatically using builtin ENGINE implementations") and the CHANGES file. But mostly it's my own conclusion, based on reading the source code and performing experiments.

The basic question I was trying to answer was, on modern Intel processors which support AES-NI and RdRand, is OpenSSL taking advantage of these hardware features. The answer appears to be different for the two different features. For AES-NI, it appears from the source code (and was recently [http://marc.info/?l=openssl-users&m=136209324829507&w=2 confirmed] on the mailing list) that AES-NI is automatically used if it is available, without needing to do anything special.

However, for RdRand, it appears that the answer is different. In the source code, there is a separate RdRand engine. If the RdRand engine is not used, then the default pool implementation in md_rand.c is used, and you don't get the benefits of RdRand.

From the section I already mentioned in the "engine" manpage, it sounded like no engines are used by default, and you must enable them by calling ENGINE_load_builtin_engines() followed by ENGINE_register_all_complete(). Although the CHANGES file partially contradicts this advice, saying:

<pre>
*) Add call to ENGINE_register_all_complete() to
ENGINE_load_builtin_engines(), so some implementations get used
automatically instead of needing explicit application support.
[Steve Henson]
</pre>

I did some experiments on a machine with RdRand. I wrote the following little bit of code:

<pre>
ENGINE *rnd = ENGINE_get_default_RAND ();
if (rnd)
printf ("default rand engine: %s\n", ENGINE_get_name (rnd));
else
printf ("no default rand engine\n");
</pre>

If I initialize OpenSSL the typical way:

<pre>
SSL_load_error_strings(); /* readable error messages */
SSL_library_init(); /* initialize library */
OpenSSL_add_all_algorithms();
</pre>

without calling any ENGINE functions, then my little code fragment will print "no default rand engine", indicating the implementation from md_rand.c is being used. But if I call ENGINE_load_builtin_engines() after the other initialization functions, and before my little test, it then prints out that RdRand is the default rand engine.

So, this is how I drew the conclusion that it's necessary to call ENGINE_load_builtin_engines() as part of your initialization, if you want to get RdRand support.

However, this is all made a little bit trickier by the fact that OpenSSL_add_all_algorithms() can actually mean one of two vastly different things, depending on a #define at compile time. If OPENSSL_LOAD_CONF is defined, then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_conf(), but if OPENSSL_LOAD_CONF is not defined (which is the default), then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_noconf().

OPENSSL_add_all_algorithms_conf() is a two-line function:

<pre>
void OPENSSL_add_all_algorithms_conf(void)
{
OPENSSL_add_all_algorithms_noconf();
OPENSSL_config(NULL);
}
</pre>

So the difference is that if OPENSSL_LOAD_CONF is defined, then OPENSSL_config() is called, when it otherwise wouldn't be. What does this have to do with RdRand? The thing is that OPENSSL_config() calls ENGINE_load_builtin_engines(). (And then ENGINE_load_builtin_engines() in turn calls ENGINE_register_all_complete(), as mentioned in the CHANGES entry.)

So, to get RdRand support, you can either #define OPENSSL_LOAD_CONF when building your program, or you can call either ENGINE_load_builtin_engines() or OPENSSL_config() in your initialization sequence. However, it appears that calling ENGINE_load_builtin_engines() more than once will leak memory, so ideally you don't want to call ENGINE_load_builtin_engines() if you also plan on calling OPENSSL_config(), or if you've defined OPENSSL_LOAD_CONF. (Of course, since it's just a small fixed-size leak at initialization, this wouldn't really be a practical problem, but still makes me feel icky.)

--[[User:Ppelleti|Ppelleti]] 04:33, 4 March 2013 (UTC)

== Best practices for printing errors ==

I'm curious about the recommendation to do this:

<pre>
err:
unsigned long errCode;
while(errCode = ERR_get_error())
{
char *err = ERR_error_string(errCode, NULL);
printf("%s\n", err);
}
</pre>

Wouldn't it be much simpler to just do:

<pre>
err:
ERR_print_errors_fp(stderr);
</pre>

Or, if one really does want to iterate through each line of the error queue individually, wouldn't it still be better for us to recommend using ERR_error_string_n with an explicit buffer? ERR_error_string with a NULL argument is not thread-safe.

--[[User:Ppelleti|Ppelleti]] 18:12, 3 March 2013 (UTC)

Either way does the trick, but I agree yours is simpler. I'll change it.,

--[[User:Matt|Matt]] 22:16, 3 March 2013 (UTC)

Hostname validation

2013-03-03T18:50:17Z

Ppelleti: minimal explanation of the hostname validation problem, with some links

One [https://crypto.stanford.edu/~dabo/pubs/abstracts/ssl-client-bugs.html very common mistake] made by users of OpenSSL is to assume that OpenSSL will validate the hostname in the server's certificate. Currently, it does not, although a future version (1.1.0?) will include this functionality.

[https://github.com/iSECPartners/ssl-conservatory Here is some sample code] which shows how validating the hostname can be done. However, it does not handle wildcard certificates, so [http://archives.seul.org/libevent/users/Feb-2013/msg00043.html borrowing some code from cURL] might be one way to go.

Diffie-Hellman parameters

2013-03-03T18:36:24Z

Ppelleti: copy the content I wrote from the OpenSSL wikibook

Libssl API

2013-03-03T18:31:21Z

Ppelleti: stub for libssl

libssl is the portion of OpenSSL which supports TLS, and depends on libcrypto.

* [[Diffie-Hellman parameters]]
* [[Hostname validation]]

Libcrypto API

2013-03-03T18:23:05Z

Ppelleti: /* See also */ link to BIO

BIO

2013-03-03T18:22:01Z

Ppelleti: copied the content that I wrote about BIOs from the OpenSSL wikibook

A BIO is an I/O stream abstraction; essentially OpenSSL's answer to the C library's <code>FILE *</code>. OpenSSL comes with a number of useful BIO types predefined, or you can create your own.

BIOs come in two flavors: source/sink, or filter. BIOs can be chained together. Each chain always has exactly one source/sink, but can have any number (zero or more) of filters.

Reading from a BIO can be done with [https://www.openssl.org/docs/crypto/BIO_read.html BIO_read] and <code>BIO_gets</code>.

Writing to a BIO can be done with <code>BIO_write</code>, <code>BIO_puts</code>, <code>BIO_printf</code>, and <code>BIO_vprintf</code>.

== Filter BIOs ==

* [https://www.openssl.org/docs/crypto/BIO_f_base64.html BIO_f_base64]
* [https://www.openssl.org/docs/crypto/BIO_f_buffer.html BIO_f_buffer]
* [https://www.openssl.org/docs/crypto/BIO_f_cipher.html BIO_f_cipher]
* [https://www.openssl.org/docs/crypto/BIO_f_md.html BIO_f_md]
* [https://www.openssl.org/docs/crypto/BIO_f_ssl.html BIO_f_ssl]

== Source/sink BIOs ==

* [https://www.openssl.org/docs/crypto/BIO_s_accept.html BIO_s_accept]
* [https://www.openssl.org/docs/crypto/BIO_s_bio.html BIO_s_bio]
* [https://www.openssl.org/docs/crypto/BIO_s_connect.html BIO_s_connect]
* [https://www.openssl.org/docs/crypto/BIO_s_fd.html BIO_s_fd]
* [https://www.openssl.org/docs/crypto/BIO_s_file.html BIO_s_file]
* [https://www.openssl.org/docs/crypto/BIO_s_mem.html BIO_s_mem]
* [https://www.openssl.org/docs/crypto/BIO_s_null.html BIO_s_null]
* [https://www.openssl.org/docs/crypto/BIO_s_socket.html BIO_s_socket]

Talk:Libcrypto API

2013-03-03T18:12:02Z

Ppelleti: /* Best practices for printing errors */ new section

Talk:Libcrypto API

2013-03-03T18:05:49Z

Ppelleti: Initialization and engines?

OpenSSLWiki - User contributions [en]

Related Links

Related Links

Hostname validation

Hostname validation

Related Links

Related Links

Memory management internals

Internals

Related Links

Random fork-safety

Random Numbers

Random fork-safety

Random fork-safety

Talk:Random fork-safety

Random fork-safety

Random fork-safety

Random fork-safety

Random fork-safety

Random fork-safety

Random Numbers

Diffie-Hellman parameters

Diffie-Hellman parameters

Diffie-Hellman parameters

Related Links

User:Ppelleti

Diffie-Hellman parameters

Diffie Hellman

Talk:Random Numbers

Talk:Random Numbers

Diffie-Hellman parameters

Related Links

Random Numbers

Random Numbers

Talk:Random Numbers

Random Numbers

Talk:Libcrypto API

Libcrypto API

Talk:Libcrypto API

Talk:Libcrypto API

Libcrypto API

Libcrypto API

User:Ppelleti

Talk:Libcrypto API

Hostname validation

Diffie-Hellman parameters

Libssl API

Libcrypto API

BIO

Talk:Libcrypto API

Talk:Libcrypto API