OpenSSLWiki - User contributions [en]

Random fork-safety

2018-04-04T20:09:43Z

Rsalz:

One of the most important issues in the proper cryptographic use of random numbers is that random numbers must not be reused. Since the UNIX fork() system call duplicates the entire process state, a random number generator which does not take this issue into account will produce the same sequence of random numbers in both the parent and the child (or in multiple children), leading to cryptographic disaster (i. e. people being able to read your communications).

'''The situation has changed greatly, starting with OpenSSL 1.1.0 which completely rewrote RNG. The concerns below do not really apply any more.'''

OpenSSL's default random number generator mixes in the PID, which provides a certain degree of fork safety. However, once the PIDs wrap, new children will start to produce the same random sequence as previous children which had the same PID. This is unlikely to happen in most common cases, but it is not impossible, which makes the issue even more insidious.

The most comprehensive explanation of this problem is probably this blog post:

* [http://emboss.github.io/blog/2013/08/21/openssl-prng-is-not-really-fork-safe/ OpenSSL PRNG Is Not (Really) Fork-safe - martinboßlet - Aug 21, 2013]

However, since this issue has been "rediscovered" and discussed multiple times, here are some additional links (some are also linked from the above article)

* [http://marc.info/?l=openssl-dev&m=130289811108150&w=2 openssl-dev: recycled pids causes PRNG to repeat - Eric Wong - Apr 15, 2011]
* [https://bugs.ruby-lang.org/issues/4579 Ruby bug 4579: SecureRandom + OpenSSL may repeat with fork - Apr 15, 2011]
* [http://www.postgresql.org/message-id/E1UKzBn-0006c2-Cy@gemulon.postgresql.org pgsql: Reset OpenSSL randomness state in each postmaster childprocess - Tom Lane - Mar 27, 2013]
* [https://plus.google.com/+AndroidDevelopers/posts/YxWzeNQMJS2 Google+ discussion of Android SecureRandom issue, caused by OpenSSL PID wraparound - Aug 14, 2013]
* [http://bugs.python.org/issue18747 Python: Re-seed OpenSSL's PRNG after fork - Aug 15, 2013]
* [http://jbp.io/2013/08/15/android-securerandom-guess/ Android SecureRandom vulnerability guess - Joseph Birr-Pixton - Aug 15, 2013]
* [http://www.mail-archive.com/openssl-users@openssl.org/msg71749.html openssl-users: DLL hell - Nico Williams - Aug 15, 2013]
** [http://www.mail-archive.com/openssl-dev@openssl.org/msg32867.html openssl-dev: not fork-safe if pids wrap (continuation of above openssl-users thread) - Aug 22, 2013]
* [http://www.mail-archive.com/openssl-dev@openssl.org/msg33003.html openssl-dev: Patch to increase rng entropy after forking - Ernst-Udo Wallenborn - Sept 18, 2013]
* [http://www.mail-archive.com/openssl-dev@openssl.org/msg33012.html openssl-dev: Mixing time into the pool - Ben Laurie - Sept 21, 2013]
** [https://github.com/openssl/openssl/commit/3cd8547a2018ada88a4303067a2aa15eadc17f39 commit mentioned in above message]
* [http://bugs.python.org/issue19227 Python issue 19227: test_multiprocessing_xxx hangs under Gentoo buildbots - Oct 11, 2013]
* [http://www.mail-archive.com/openssl-dev@openssl.org/msg33604.html openssl-dev: Reseed PRNG on PID change - Florian Weimer - Jan 15, 2014]

== Remediations ==

OpenSSL cannot fix the fork-safety problem because its not in a position to do so. However, there are remediations available and they are listed below.

* Don't use <tt>RAND_bytes</tt>
* Call <tt>RAND_seed</tt> after a fork
* Call <tt>RAND_poll</tt> after a fork
* Use a hardware based generator
* Practice hedging cryptography

The first remediation is to avoid using <tt>RAND_bytes</tt>. Instead, you can read directly from <tt>/dev/random</tt>, <tt>/dev/urandom</tt> or <tt>/dev/srandom</tt>; or use <tt>CryptGenRandom</tt> on Windows systems. Avoiding <tt>RAND_bytes</tt> is not practical in practice because the library will use it internally.

The second remediation is to call <tt>RAND_seed</tt> or <tt>RAND_add</tt> after a fork. Entropy can be obtained from the operating system by reading from <tt>/dev/random</tt>, <tt>/dev/urandom</tt> or <tt>/dev/srandom</tt>; or using <tt>CryptGenRandom</tt> on Windows systems. For mobile devices with an interactive user, you could even add sensor data from the accelerometer, magnetometer and gyroscopes. This is appropriate for most programs, but might have problems in low entropy environments such as mobile devices and headless servers. Additionally, this could have problems in virtualized environments. For details, see [[Random_Numbers|Random Numbers]].

The third remediation is to use <tt>RAND_poll</tt> after a fork. This is used by OpenSSL to seed the generator on startup. The function always reads from <tt>/dev/urandom</tt>, so you will have to seed the generator yourself if you want to use <tt>/dev/random</tt> or <tt>/dev/srandom</tt>. This is appropriate for most programs, and recommended by a number of people familiar with the library. This method has the same potential problems as <tt>RAND_seed</tt> or <tt>RAND_add</tt>. For details, see [[Random_Numbers|Random Numbers]].

The fourth remediation is to use a hardware based generator. This is not always practical because hardware is not always present. Additionally, hardware is not usually auditable so some question its unabridged use in the post-Snowden era. For details, see [[Random_Numbers|Random Numbers]] and [[Manual:Engine(3)|OpenSSL engine(3)]] man page.

The fifth remediation is to practice hedging cryptography. Hedging uses entropy gathered from a peer during key exchange or key agreement to add to the program's internal entropy pool (for example, the random '''R<sub>A</sub>''' or '''R<sub>B</sub>''' in SSL/TLS). The benefit of hedging is its resilient against fork problems, low entropy environments, and virtual machine playbacks. For details, see [http://static.usenix.org/event/hotos05/final_papers/full_papers/garfinkel/garfinkel.pdf When Virtual is Harder than Real: Resource Allocation Challenges in Virtual Machine Based IT Environments] and [http://www.isoc.org/isoc/conferences/ndss/10/pdf/15.pdf When Good Randomness Goes Bad: Virtual Machine Reset Vulnerabilities and Hedging Deployed Cryptography].

Some of the items above recommend reading from operating system provided facilities, such as <tt>/dev/random</tt> and <tt>/dev/urandom</tt>. Since the random number generator should be in good order before the fork, you should be able to add unique information to diversify the generator states between parent and child. Unique information would include the time the call was made and the process identifier. In fact, Ben Laurie [https://github.com/openssl/openssl/commit/3cd8547a2018ada88a4303067a2aa15eadc17f39 pushed a patch to use time] as the uniqueness (unfortunately, it will be years before it gains widespread adoption in the field).

The code below can be used to add unique information to the generator after a fork. The call to <tt>time</tt> ensures the information is unique if the PIDs wrap. The call to <tt>getpid</tt> ensures that two forks that occur back-to-back on hardware with low resolution timers are unique. <tt>long[2]</tt> and <tt>long[3]</tt> attempts to further enhance the generator's state by using random data on the stack (if present).

<pre>long long seed[4];
seed[0] = (long long)time(NULL);
seed[1] = (long long)getpid();
RAND_seed(seed, sizeof(seed));</pre>

License

2017-11-30T20:56:36Z

Rsalz:

License

2017-11-30T20:53:55Z

Rsalz:

We appreciate material and works produced for the community. Documentation, patches, and sample programs help ensure the library is reliable and easy to use. To ensure the most benefit to the project and community, contributions to this wiki must be either:

# existing material copied from a public domain source
# original content created by you and released under the current OpenSSL license (and any future version of it that the OpenSSL project may adopt)
# existing content already released under the current or future OpenSSL license.

The current [https://openssl.org/source/license.html OpenSSL licence] is an "Apache style" license. We are moving to the Apache license soon; see our [https://www.openssl.org/blog/blog/categories/license/ blog posts].

== Source Code Patches ==

If you contribute patches for the library source code, then the OpenSSL project will use the OpenSSL license. Not all patches will be accepted or Incorporated, and there are a variety of reasons why such changes may not be accepted and utilized by the project (not all of them readily apparent). See [[Contributions]] for a discussion of patches and potential concerns.

== Sample Programs ==

If you contribute original sample programs for using the library, then the OpenSSL project will use the OpenSSL license. You should place the following text at the top of the source files:

<pre>Contents licensed under the terms of the OpenSSL license: https://www.openssl.org/source/license.html</pre>

You must also sign a [https://www.openssl.org/policies/cla.html CLA].
== Man Page Documentation ==

If you contribute original documentation for the source code, then the OpenSSL project will use the OpenSSL license. You will not need to do anything to ensure your changes are suitable for use by by the project. As with source code there are a variety of reasons why documentation may not be accepted and utilized by the project, not all of them readily apparent [note: the topic of [[contributions]] deserves a separate discussion];

== Wiki Documentation ==

[[Category:Wiki Usage]]

All contributions to this wiki are considered to be released under the current OpenSSL License (and any future version of it) and contributors agree the contributed content is original, or copied from a public domain or similar free resource, or copied from OpenSSL.

== Copyright Notice ==

Use the following copyright notice for source files, sample programs on the wiki, etc.

<pre> Copyright OpenSSL <nowiki>[YEAR]</nowiki>
Contents licensed under the terms of the OpenSSL license
See https://www.openssl.org/source/license.html for details</pre>

[[Category:Legal]]

EVP Symmetric Encryption and Decryption

2017-11-30T20:44:16Z

Rsalz:

{{DocInclude
|Name=Symmetric Encryption and Decryption
|Url=http://wiki.openssl.org/index.php/Manual:Evp(3)
|Include=evp.h}}

The [[Libcrypto API|libcrypto]] library within OpenSSL provides functions for performing symmetric encryption and decryption operations across a wide range of algorithms and modes. This page walks you through the basics of performing a simple encryption and corresponding decryption operation.

In order to perform encryption/decryption you need to know:
* Your algorithm
* Your mode
* Your key
* Your Initialisation Vector (IV)

This page assumes that you know what all of these things mean. If you don't then please refer to [[Basics of Encryption]].

==Setting it up==

The code below sets up the program. In this example we are going to take a simple message ("The quick brown fox jumps over the lazy dog"), and then encrypt it using a predefined key and IV. In this example the key and IV have been hard coded in - in a real situation you would never do this! Following encryption we will then decrypt the resulting ciphertext, and (hopefully!) end up with the message we first started with. This program expects two functions to be defined: "encrypt" and "decrypt". We will define those further down the page. Note that this uses the auto-init facility in 1.1.0.

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

int main (void)
{
/* Set up the key and iv. Do I need to say to not hard code these in a
* real application? :-)
*/

/* A 256 bit key */
unsigned char *key = (unsigned char *)"01234567890123456789012345678901";

/* A 128 bit IV */
unsigned char *iv = (unsigned char *)"0123456789012345";

/* Message to be encrypted */
unsigned char *plaintext =
(unsigned char *)"The quick brown fox jumps over the lazy dog";

/* Buffer for ciphertext. Ensure the buffer is long enough for the
* ciphertext which may be longer than the plaintext, dependant on the
* algorithm and mode
*/
unsigned char ciphertext[128];

/* Buffer for the decrypted text */
unsigned char decryptedtext[128];

int decryptedtext_len, ciphertext_len;

/* Encrypt the plaintext */
ciphertext_len = encrypt (plaintext, strlen ((char *)plaintext), key, iv,
ciphertext);

/* Do something useful with the ciphertext here */
printf("Ciphertext is:\n");
BIO_dump_fp (stdout, (const char *)ciphertext, ciphertext_len);

/* Decrypt the ciphertext */
decryptedtext_len = decrypt(ciphertext, ciphertext_len, key, iv,
decryptedtext);

/* Add a NULL terminator. We are expecting printable text */
decryptedtext[decryptedtext_len] = '\0';

/* Show the decrypted text */
printf("Decrypted text is:\n");
printf("%s\n", decryptedtext);

return 0;
}

The program sets up a 256 bit key and a 128 bit IV. This is appropriate for the 256-bit AES encryption that we going to be doing in CBC mode. Make sure you use the right key and IV length for the cipher you have selected, or it will go horribly wrong!! The IV should be random for CBC mode.

We've also set up a buffer for the ciphertext to be placed in. It is important to ensure that this buffer is sufficiently large for the expected ciphertext or you may see a program crash (or potentially introduce a security vulnerability into your code). Note: The ciphertext may be longer than the plaintext (e.g. if padding is being used).

We're also going to need a helper function to handle any errors. This will simply dump any error messages from the OpenSSL error stack to the screen, and then abort the program.

void handleErrors(void)
{
ERR_print_errors_fp(stderr);
abort();
}

==Encrypting the message==

So now that we have set up the program we need to define the "encrypt" function. This will take as parameters the plaintext, the length of the plaintext, the key to be used, and the IV. We'll also take in a buffer to put the ciphertext in (which we assume to be long enough), and will return the length of the ciphertext that we have written.

Encrypting consists of the following stages:
* Setting up a context
* Initialising the encryption operation
* Providing plaintext bytes to be encrypted
* Finalising the encryption operation

During initialisation we will provide an EVP_CIPHER object. In this case we are using EVP_aes_256_cbc(), which uses the AES algorithm with a 256-bit key in [[CBC]] mode. Refer to [[EVP#Working with Algorithms and Modes]] for further details.

int encrypt(unsigned char *plaintext, int plaintext_len, unsigned char *key,
unsigned char *iv, unsigned char *ciphertext)
{
EVP_CIPHER_CTX *ctx;

int len;

int ciphertext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new())) handleErrors();

/* Initialise the encryption operation. IMPORTANT - ensure you use a key
* and IV size appropriate for your cipher
* In this example we are using 256 bit AES (i.e. a 256 bit key). The
* IV size for *most* modes is the same as the block size. For AES this
* is 128 bits */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_cbc(), NULL, key, iv))
handleErrors();

/* Provide the message to be encrypted, and obtain the encrypted output.
* EVP_EncryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len))
handleErrors();
ciphertext_len = len;

/* Finalise the encryption. Further ciphertext bytes may be written at
* this stage.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len)) handleErrors();
ciphertext_len += len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}

==Decrypting the Message==

Finally we need to define the "decrypt" operation. This is very similar to encryption and consists of the following stages:
Decrypting consists of the following stages:
* Setting up a context
* Initialising the decryption operation
* Providing ciphertext bytes to be decrypted
* Finalising the decryption operation

Again through the parameters we will receive the ciphertext to be decrypted, the length of the ciphertext, the key and the IV. We'll also receive a buffer to place the decrypted text into, and return the length of the plaintext we have found.

Note that we have passed the length of the ciphertext. This is required as you cannot use functions such as "strlen" on this data - its binary! Similarly, even though in this example our plaintext really is ASCII text, OpenSSL does not know that. In spite of the name plaintext could be binary data, and therefore no NULL terminator will be put on the end (unless you encrypt the NULL as well of course).

Here is the decrypt function:

int decrypt(unsigned char *ciphertext, int ciphertext_len, unsigned char *key,
unsigned char *iv, unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;

int len;

int plaintext_len;

/* Create and initialise the context */
if(!(ctx = EVP_CIPHER_CTX_new())) handleErrors();

/* Initialise the decryption operation. IMPORTANT - ensure you use a key
* and IV size appropriate for your cipher
* In this example we are using 256 bit AES (i.e. a 256 bit key). The
* IV size for *most* modes is the same as the block size. For AES this
* is 128 bits */
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_cbc(), NULL, key, iv))
handleErrors();

/* Provide the message to be decrypted, and obtain the plaintext output.
* EVP_DecryptUpdate can be called multiple times if necessary
*/
if(1 != EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ciphertext_len))
handleErrors();
plaintext_len = len;

/* Finalise the decryption. Further plaintext bytes may be written at
* this stage.
*/
if(1 != EVP_DecryptFinal_ex(ctx, plaintext + len, &len)) handleErrors();
plaintext_len += len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return plaintext_len;
}

==Ciphertext Output==

If all goes well you should end up with output that looks like the following:
Ciphertext is:
0000 - e0 6f 63 a7 11 e8 b7 aa-9f 94 40 10 7d 46 80 a1 .oc.......@.}F..
0010 - 17 99 43 80 ea 31 d2 a2-99 b9 53 02 d4 39 b9 70 ..C..1....S..9.p
0020 - 2c 8e 65 a9 92 36 ec 92-07 04 91 5c f1 a9 8a 44 ,.e..6.....\...D
Decrypted text is:
The quick brown fox jumps over the lazy dog

For further details about symmetric encryption and decryption operations refer to the OpenSSL documentation [[Manual:EVP_EncryptInit(3)]].

==Padding==

OpenSSL uses PKCS padding by default. If the mode you are using allows you to change the padding, then you can change it with <tt>[http://www.openssl.org/docs/man1.0.2/crypto/EVP_CIPHER_CTX_set_padding.html EVP_CIPHER_CTX_set_padding]</tt>. From the man page:

<blockquote>EVP_CIPHER_CTX_set_padding() enables or disables padding. By default encryption operations are padded using standard block padding and the padding is checked and removed when decrypting. If the pad parameter is zero then no padding is performed, the total amount of data encrypted or decrypted must then be a multiple of the block size or an error will occur...

PKCS padding works by adding n padding bytes of value n to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size n will equal the block size. For example if the block size is 8 and 11 bytes are to be encrypted then 5 padding bytes of value 5 will be added...

If padding is disabled then the decryption operation will only succeed if the total amount of data decrypted is a multiple of the block size.</blockquote>

==C++ Programs==

Questions regarding how to use the EVP interfaces from a C++ program arise on occasion. Generally speaking, using the EVP interfaces from a C++ program is the same as using them from a C program.

You can download a sample program using EVP symmetric encryption and C++11 called [[Media:Evp-encrypt-cxx.tar.gz|evp-encrypt.cxx]]. The sample uses a custom allocator to zeroize memory, C++ smart pointers to manage resources, and provides a <tt>secure_string</tt> using <tt>basic_string</tt> and the custom allocator. You need to use <tt>g++ -std=c++11 ...</tt> to compile it because of <tt>std::unique_ptr</tt>.

You should also ensure you configure an build with <tt>-fexception</tt> to ensure C++ exceptions pass as expected through C code. And you should avoid other flags, like <tt>-fno-exceptions</tt> and <tt>-fno-rtti</tt>.

The program's <tt>main</tt> simply encrypts and decrypts a string using AES-256 in CBC mode:

<pre>typedef unsigned char byte;
typedef std::basic_string<char, std::char_traits<char>, zallocator<char> > secure_string;
using EVP_CIPHER_CTX_ptr = std::unique_ptr<EVP_CIPHER_CTX, decltype(&::EVP_CIPHER_CTX_free)>;
...

int main(int argc, char* argv[])
{
// Load the necessary cipher
EVP_add_cipher(EVP_aes_256_cbc());

// plaintext, ciphertext, recovered text
secure_string ptext = "Yoda said, Do or do not. There is no try.";
secure_string ctext, rtext;

byte key[KEY_SIZE], iv[BLOCK_SIZE];
gen_params(key, iv);

aes_encrypt(key, iv, ptext, ctext);
aes_decrypt(key, iv, ctext, rtext);

OPENSSL_cleanse(key, KEY_SIZE);
OPENSSL_cleanse(iv, BLOCK_SIZE);

std::cout << "Original message:\n" << ptext << std::endl;
std::cout << "Recovered message:\n" << rtext << std::endl;

return 0;
}</pre>

And the encryption routine is as follows. The decryption routine is similar:

<pre>void aes_encrypt(const byte key[KEY_SIZE], const byte iv[BLOCK_SIZE], const secure_string& ptext, secure_string& ctext)
{
EVP_CIPHER_CTX_ptr ctx(EVP_CIPHER_CTX_new(), ::EVP_CIPHER_CTX_free);
int rc = EVP_EncryptInit_ex(ctx.get(), EVP_aes_256_cbc(), NULL, key, iv);
if (rc != 1)
throw std::runtime_error("EVP_EncryptInit_ex failed");

// Cipher text expands upto BLOCK_SIZE
ctext.resize(ptext.size()+BLOCK_SIZE);
int out_len1 = (int)ctext.size();

rc = EVP_EncryptUpdate(ctx.get(), (byte*)&ctext[0], &out_len1, (const byte*)&ptext[0], (int)ptext.size());
if (rc != 1)
throw std::runtime_error("EVP_EncryptUpdate failed");

int out_len2 = (int)ctext.size() - out_len1;
rc = EVP_EncryptFinal_ex(ctx.get(), (byte*)&ctext[0]+out_len1, &out_len2);
if (rc != 1)
throw std::runtime_error("EVP_EncryptFinal_ex failed");

// Set cipher text size now that we know it
ctext.resize(out_len1 + out_len2);
}</pre>

==Notes on some unusual modes==

Worthy of mention here is the [[XTS]] mode (e.g. EVP_aes_256_xts()). This works in exactly the same way as shown above, except that the "tweak" is provided in the IV parameter. A further "gotcha" is that XTS mode expects a key which is twice as long as normal. Therefore EVP_aes_256_xts() expects a key which is 512-bits long.

Authenticated encryption modes ([[GCM]] or [[CCM]]) work in essentially the same way as shown above but require some special handling. See [[EVP Authenticated Encryption and Decryption]] for further details.

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [[EVP Authenticated Encryption and Decryption]]
* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
* [[EVP Signing and Verifying]]
* [[EVP Message Digests]]
* [[EVP Key Agreement]]
* [[EVP Key and Parameter Generation]]

[[Category:Crypto API]]
[[Category:C level]]
[[Category:Examples]]

Android

2017-04-20T20:06:07Z

Rsalz: /* Build the OpenSSL Library */

This document will provide instructions for building the OpenSSL library for Android devices. If you need the FIPS Validated Object Module and the FIPS Capable Library, see [[FIPS Library and Android]].

==Executive Summary==

Use the following commands to build and install the OpenSSL library for Android. Before running the commands download openssl-1.0.1g.tar.gz and [[Media:setenv-android.sh|setenv-android.sh]]; place the files in the same directory (the 'root' directory mentioned below); ensure <tt>ANDROID_NDK_ROOT</tt> is set; and verify setenv-android.sh suites your taste. <tt>ANDROID_API</tt> and <tt>ANDROID_TOOLCHAIN</tt> will be set by the <tt>setenv-android.sh</tt> script. The files can be obtained from http://www.openssl.org/source/, http://openssl.com/fips/2.0/platforms/android/, and below (see Downloads section).

=== Prepare the OpenSSL Sources ===

<pre># From the 'root' directory
$ rm -rf openssl-1.0.1g/
$ tar xzf openssl-1.0.1g.tar.gz
$ chmod a+x setenv-android.sh</pre>

=== Build the OpenSSL Library ===

<pre># From the 'root' directory
$ . ./setenv-android.sh
$ cd openssl-1.0.1g/

# Perl is optional, and may fail in OpenSSL 1.1.0
$ perl -pi -e 's/install: all install_docs install_sw/install: install_docs install_sw/g' Makefile.org

# Tune to suit your taste, visit http://wiki.openssl.org/index.php/Compilation_and_Installation
$ ./config shared no-ssl2 no-ssl3 no-comp no-hw no-engine \
--openssldir=/usr/local/ssl/$ANDROID_API --prefix=/usr/local/ssl/$ANDROID_API

$ make depend
$ make all</pre>

=== Install the OpenSSL Library ===

<pre># The -E is important. Root needs some of the user's environment
$ sudo -E make install CC=$ANDROID_TOOLCHAIN/arm-linux-androideabi-gcc RANLIB=$ANDROID_TOOLCHAIN/arm-linux-androideabi-ranlib</pre>

=== Compile and Link against the Library ===

<pre>arm-linux-androideabi-gcc -I /usr/local/ssl/include my_prog.c -o my_prog.exe -L /usr/local/ssl/lib -lssl -lcrypto</pre>

== OpenSSL Library ==

While the Executive Summary provided the whirlwind instructions for building and installing the OpenSSL library, this sections provides detailed instructions. There are six steps to building the OpenSSL Library for use in various projects, and they are listed below. Projects range from simple NDK based command line programs to Android activities using the JNI bridge.

# Acquire the required files
# Adjust the cross-compilation script
# Prepare the OpenSSL sources
# Build the OpenSSL Library
# Install the OpenSSL Library

=== Acquire the Required Files ===

First, obtain the base files from http://www.openssl.org/source/:
* openssl-1.0.1g.tar.gz

Next, acquire the auxiliary files which can be obtained from below (see Downloads section) or http://openssl.com/fips/2.0/platforms/android/. You won't need all the files from the location.
* [[Media:setenv-android.sh|setenv-android.sh]]

<tt>openssl-1.0.1g.tar.gz</tt> is the OpenSSL Library. <tt>setenv-android.sh</tt> is used to set the cross-compilation environment.

After collecting the required files, your working directory will look similar to below.

<pre>android-openssl $ ls -l
-rw-r--r-- 1 4459777 Jun 15 03:32 openssl-1.0.1g.tar.gz
-rwxr-xr-x 1 6760 Jun 23 01:52 setenv-android.sh</pre>

=== Adjust the Cross-Compile Script ===

<tt>setenv-android.sh</tt> is used to set the cross-compilation environment. Open the script an ensure the following match your needs. If you are using android-ndk-r8e, android-14, and <tt>ANDROID_NDK_ROOT</tt> is set, then the script should be ready to use as-is.

* <tt>_ANDROID_NDK</tt> – the version of the NDK. For example, android-ndk-r8e
* <tt>_ANDROID_ARCH</tt> – the architecture. For example, arch-arm or arch-x86
* <tt>_ANDROID_EABI</tt> – the version of the EABI tools. For example, arm-linux-androideabi-4.6, arm-linux-androideabi-4.8, x86-4.6 or x86-4.8
* <tt>_ANDROID_API</tt> – the API level. For example, android-14 or android-18

You should also set <tt>ANDROID_SDK_ROOT</tt> and <tt>ANDROID_NDK_ROOT</tt>. The environmental variables are used internally by the Android platform tools and scripts. For details, see [https://groups.google.com/d/msg/android-ndk/qZjhOaynHXc/2ux2ZZdxy2MJ Recommended NDK Directory?].

Additional environmental variables which are set by <tt>setenv-android.sh</tt> and used by <tt>Configure</tt> and <tt>config</tt> include the following. You should not need to change them.

* <tt>MACHINE</tt> – set to <tt>armv7</tt>
* <tt>RELEASE</tt> – set to <tt>2.6.37</tt>
* <tt>SYSTEM</tt> – set to <tt>android</tt>
* <tt>ARCH</tt> – set to <tt>arm</tt>
* <tt>CROSS_COMPILE</tt> – set to <tt>arm-linux-androideabi-</tt>
* <tt>ANDROID_DEV</tt> – set to <tt>$ANDROID_NDK_ROOT/platforms/$_ANDROID_API/arch-arm/usr</tt>
* <tt>HOSTCC</tt> – set to <tt>gcc</tt>

=== Prepare the OpenSSL Sources ===

Remove stale versions of the OpenSSL Library, and then unpack fresh files. Also ensure the script is executable.

<pre>$ rm -rf openssl-1.0.1g/
$ tar xzf openssl-1.0.1g.tar.gz
$ chmod a+x setenv-android.sh</pre>

=== Build the OpenSSL Library ===

This section of the document will guide you through the creation of the the OpenSSL Library. The OpenSSL Library (and Makefile.org) needs its install rule modified. The install rule includes the all target, which causes items to be built during install. A bug in the process when running as root results in an empty signature for the shared object (the signature is a string of zeros).

To build the OpenSSL Library, you must issue <tt>config</tt>, but other options are up to you. Some suggested options for configure include: shared, no-ssl2, no-ssl3, no-comp, no-hw, and no-engine. <tt>shared</tt> will build and install both the shared object and static archive. You should specify --openssldir to ensure the build system installs the android version of the library in a distinct location (other than <tt>/usr/local/ssl</tt>).

Begin building the OpenSSL library by setting the cross-compilation environment. Note the leading '.' when running the <tt>setenv-android.sh</tt> script. If you have any errors from the script, then you should fix them before proceeding.

<pre>$ . ./setenv-android.sh
$ cd openssl-1.0.1g/</pre>

If you receive a meesage "<tt>Error: FIPS_SIG does not specify incore module, please edit this script</tt>, then its safe to ignore it. <tt>setenv-android.sh</tt> is used to build both the FIPS Capable OpenSSL library and the non-FIPS version of the library. <tt>FIPS_SIG</tt> is '''not''' needed in this configuration.

Next, fix the makefile and run configure. A user on Stack Overflow reports this [http://stackoverflow.com/q/39640180/608639 fails under OpenSSL 1.1.0]. If so skip it because its not essential to the cross-compile.

<pre>$ perl -pi -e 's/install: all install_docs install_sw/install: install_docs install_sw/g' Makefile.org
$ ./config shared no-ssl2 no-ssl3 no-comp no-hw no-engine --openssldir=/usr/local/ssl/android-14/</pre>

Then run make depend and make all:

<pre>$ make depend
$ make all</pre>

After make completes, verify libcrypto.a and libssl.a were built for the embedded architecture.

<pre>$ find . -name libcrypto.a
./libcrypto.a
$ readelf -h ./libcrypto.a | grep -i 'class\|machine' | head -2
Class: ELF32
Machine: ARM</pre>

=== Install the OpenSSL Library ===

Finally, install the library. The makefile's install rule uses both CC and RANLIB, so you will need to fully specify the command variables on the command line (during install, sudo drops the user's path). You must also use sudo's -E option; otherwise ANDROID_TOOLCHAIN will be empty and tools such as arm-linux-androideabi-gcc and arm-linux-androideabi-ranlib will not be found.

<pre>$ sudo -E make install CC=$ANDROID_TOOLCHAIN/arm-linux-androideabi-gcc RANLIB=$ANDROID_TOOLCHAIN/arm-linux-androideabi-ranlib</pre>

=== Compile and Link against the Library ===

[[#Install_the_OpenSSL_Library_2|Install the OpenSSL Library]] placed the cross-compiled library in <tt>/usr/local/ssl</tt>. To link against it, you must perform the following:

<pre>arm-linux-androideabi-gcc -I /usr/local/ssl/include my_prog.c -o my_prog.exe -L /usr/local/ssl/lib -lssl -lcrypto</pre>

The above only tells you how to specify the OpenSSL library. You will still need to include system headers and libraries, or use <tt>--sysroot</tt> to supply the information.

== Testing the OpenSSL Library ==

Testing the installation consists of building a sample program, installing it with adb, and then running the program using a remote shell. Both the static and dynamic version of the OpenSSL library can be tested. Instructions for testing the OpenSSL library are given at [[FIPS Library and Android]]. The same basic steps apply.

== Wrapper Shared Objects ==

Using OpenSSL on Android often involves JNI and the platform's version of OpenSSL or BoringSSL. The platform likely loaded the system's version of <tt>libssl.so</tt> and <tt>libcrypto.so</tt> at boot during Zygote initialization. Due to issues with the loader and symbol resolution, customary <tt>LD_LIBRARY_PATH</tt> tricks do not work for most applications. And changing the build to output different library names, like <tt>libmyssl.so</tt> and <tt>libmycrypto.so</tt>, to avoid clashes does not work either.

The solution to the namespace and symbol resolution problems is to wrap the '''''static''''' version of the OpenSSL library in a separate '''''dynamic''''' library or shared object provided by you. To do so, write a small C wrapper library with references to functions you need from the OpenSSL library. You don't need to wrap all the functions.

Your <tt>wrapper.c</tt> might look as follows (also see GCC's [http://gcc.gnu.org/wiki/Visibility Visibility page]):

<pre>#if __GNUC__ >= 4
#define DLL_PUBLIC __attribute__ ((visibility ("default")))
#define DLL_LOCAL __attribute__ ((visibility ("hidden")))
#else
#define DLL_PUBLIC
#define DLL_LOCAL
#endif

DLL_PUBLIC void My_OpenSSL_add_all_algorithms() {

return (void)OpenSSL_add_all_algorithms();
}

DLL_PUBLIC void My_SSL_load_error_strings() {

return (void)SSL_load_error_strings();
}

...</pre>

Then, compile the source file into a shared object. A typical command line might look as follows.

<pre>$ export OPENSSL_ANDROID = /usr/local/ssl/android-14
$ $(CC) wrapper.c -fPIC -shared -I$(OPENSSL_ANDROID)/include -fvisibility=hidden -Wl,--exclude-libs,ALL \
-Wl,-Bstatic -lcrypto -lssl -L$(OPENSSL_ANDROID)/lib -o wrapper.so -Wl,-Bdynamic</pre>

<tt>-fvisibility=hidden</tt> works as you expect, and <tt>-Wl,--exclude-libs,ALL</tt> means your library does not re-export other linked library symbols. Only the functions marked with <tt>DLL_PUBLIC</tt> will be exported and callable through JNI.

The <tt>-Wl,-Bstatic</tt> tells the linker to use the static version of the OpenSSL library for the Library. After it and the <tt>-Wl,-Bdynamic</tt> tells the linker to use dynamic linking for anything else it might need, like <tt>libc</tt>.

Then use your shared object in place of OpenSSL.

== Miscellaneous ==

The following lists some miscellaneous items we are aware.

=== Position Independent Code ===

The NDK supplies headers for each major platform - for example, API 18, API 14, API 9, API 8, and API 5. If you are building for Android 4.2 (API 17), Android 4.1 (API 16) and Android 4.0 (API 14), then you would use the NDK's API 14 (android-14 platform).

Specify the full library name when calling Java's System.load. That is, call System.load(“libcrypto.so.1.0.0”). Also note that some Android routines expect the prefix of “lib” and suffix of “so”, so you might have to rename the library.

Some versions of the Android Java system loader will load the system's version of the OpenSSL library, even though you built and included a copy with your application. In this case, you might need to write a wrapper shared object and link to the static version of the OpenSSL library. See, for example, ''[https://groups.google.com/forum/#!topic/android-ndk/rAf5tt4UEug "Unable to find native library" error in Native Activity app]''.

If you compile with -fPIE and -pie, then you will core dump unless using Android 4.1 and above. Logcat shows the linker (/system/bin/linker) is the problem.
<pre>shell@android: $ ./fips_hmac.exe -v fips_hmac.exe
[2] + Stopped (signal) ./fips_hmac.exe -v fips_hmac.exe
[1] - Segmentation fault ./fips_hmac.exe -v fips_hmac.exe</pre>

When building the OpenSSL library for Android, take care to specify <tt>-mfloat-abi=softfp</tt>. If you specify <tt>-mfloat-abi=hard</tt> or <tt>-mhard-float</tt> (even if the hardware support a floating point unit), then the entropy estimate passed through the Java VM to <tt>RAND_add</tt> will always be 0.0f. See [https://groups.google.com/d/msg/android-ndk/NbUq9FDDZOo/TJJsAS6nM7wJ Hard-float and JNI] for details.

=== Static Library Linking ===

Using <tt>-Bstatic</tt> and <tt>-Bshared</tt> can cause link problems on occasion. For example, see [http://stackoverflow.com/questions/22667953/error-when-trying-to-compile-wrapper-for-openssl-library-libcrypto-a Android: error when trying to compile wrapper for openssl library libcrypto.a]. To avoid the problem with the linker, specify the full path to the static archive (for example, <tt>/usr/local/ssl/android-14/lib/libcrypto.a</tt>). If you suspect the wrong OpenSSL library is being linked, then use the fully qualified archive path.

== Downloads ==

[[Media:setenv-android.sh|setenv-android.sh]] - script to set Android cross-compile environment.

Use of Git

2016-11-06T19:04:46Z

Rsalz: /* Making pull requests */

Use of Git

2016-11-06T19:04:35Z

Rsalz: /* Making patches */

Use of Git

2016-11-06T19:03:43Z

Rsalz: /* Branches */

Use of Git

2016-11-06T19:02:04Z

Rsalz: /* Pull Requests */

Use of Git

2016-11-06T19:01:45Z

Rsalz: /* Making patches */

File:Setenv-android.sh

2016-09-01T16:57:26Z

Rsalz: Rsalz uploaded a new version of "File:Setenv-android.sh": Address RT4666

Script to set Android cross-compile environment

Main Page

2016-08-24T19:48:42Z

Rsalz:

This is the OpenSSL wiki. The main site is https://www.openssl.org . If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Binaries]]</TD>
</TR>
<TR>
<TD>[[SSL and TLS Protocols]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
</TR>
</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* OpenSSL Manual Pages
::* [[Manual:Openssl(1)]], [[Manual:Ssl(3)]], [[Manual:Crypto(3)]], [[Documentation Index]]
:: If you wish to edit any of the Manual page content please refer to the [[Guidelines for Manual Page Authors]] page.
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* Low Level APIs
::[[Creating an OpenSSL Engine to use indigenous ECDH ECDSA and HASH Algorithms]]
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]
:* [[Simple TLS Server]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/about/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/support/faq.html#BUILD18 How to notify us of suspected security vulnerabilities]
:* [https://www.openssl.org/community/#bugs How to report bugs, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages:
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/support/community.html openssl-dev mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches. Note that manual pages and the FAQ are maintained with the source code.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report (see second bullet, above) and reference the pull request. Or you can attach the patch to the ticket.
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[Developing For OpenSSL]]
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Code reformatting]]

:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)

OpenSSL 1.1.0 Changes

2016-06-27T20:24:24Z

Rsalz:

This is a parent page for discussion about API changes being done for OpenSSL version 1.1

The overall goal of this project is to make most data structures opaque to applications. This provides us with a number of benefits:
* We can add fields without breaking [[Binary_Compatibility|binary compatibility]]
* Applications are more robust and can be more assured about correctness
* It helps us determine which (new) accessors and settors, for example, are needed

Please add sub-pages to discuss particular parts of the library as work progresses.

== Major Changes so far ==

* All structures in libssl public header files have been removed so that they are "opaque" to library users. You should use the provided accessor functions instead
* The old DES API has been removed
* bn, a sub library in libcrypto, has been made opaque
* Access to deprecated functions/macros has been removed by default. To enable access you must do two things. 1) Build OpenSSL with deprecation support (pass "enable-deprecated" as an argument to config) 2) Applications must define "OPENSSL_USE_DEPRECATED" before including OpenSSL header files
* HMAC_Init and HMAC_cleanup were previously stated in the docs and header files as being deprecated - but were not flagged in previous versions with OPENSSL_NO_DEPRECATED. This has been corrected in 1.1.0. Access to these functions/macros will be off by default in 1.1.0 as per the note above about deprecation.

== OPENSSL_API_COMPAT ==

Various functions get deprecated as other interfaces get added, but are still available in a default build.
The include files support setting the OPENSSL_API_COMPAT define that will hide functions that are deprecated in the selected version.
To select the 1.1.0 version use -DOPENSSL_API_COMPAT=0x10100000L.

== Backward compatibility ==

Since some structures have become opaque you can't directly access the member any more. You might need to create backward compatible macros or functions if you still want to support older versions of OpenSSL. A suggested way of doing that is:

<code>
#if OPENSSL_VERSION_NUMBER < 0x10100000L
#define OBJ_get0_data(o) ((o)->data)
#define OBJ_length(o) ((o)->length)
#endif
</code>

== Adding forward-compatible code to older versions ==

Application code now has to use pointers, and cannot allocate objects directly on the stack. One way to do this is to add in missing
constructors like this:

<code>
#if OPENSSL_VERSION_NUMBER < 0x10100000L
HMAC_CTX *HMAC_CTX_new(void)
{
HMAC_CTX *ctx = OPENSSL_malloc(sizeof(*ctx));
if (ctx != NULL) {
if (!HMAC_CTX_reset(ctx)) {
HMAC_CTX_free(ctx);
return NULL;
}
}
return ctx;
}
void HMAC_CTX_free(HMAC_CTX *ctx)
{
if (ctx != NULL) {
hmac_ctx_cleanup(ctx);
EVP_MD_CTX_free(ctx->i_ctx);
EVP_MD_CTX_free(ctx->o_ctx);
EVP_MD_CTX_free(ctx->md_ctx);
OPENSSL_free(ctx);
}
}
#endif
</code>

In other words, look at the 1.1 code and add the missing functions into your source.

== Things that Broke in Qt ==

Here's what's broken in the dev branch of Qt when building openssl master as of 6 Feb 2015.

* DH - we were directly accessing p and q to set the DH params to primes embedded in Qt. We can probably replace this with SSL_CTX_set_dh_auto(ctx, 1). Another option suggested by Steve Henson is to save the DHparams we're using at the moment then use d2i_DHparams to load them in. This is compatible with openssl versions that don't have the dh_auto option.

* ctx->cert_store - we were directly accessing the cert_store field of SSL_CTX. We can probably replace this with X509_STORE *SSL_CTX_get_cert_store(SSL_CTX *ctx) [Fixed in dev]

* session->tlsext_tick_lifetime_hint - we were directly accessing the lifetime hint of the session. [A new API to access this field has been added]

* cipher->valid - we were directly accessing the valid field of SSL_CIPHER. No replacement found. [This turned out not to be needed and so will be removed].

== Things that Broke in Curl ==

* SSL_SESSION->ssl_version. Replaced with SSL_version(SSL *)

== Things that Broke in wget ==

* SSL->state. Replaced with SSL_state(SSL *)

== Things that Broke in Apache Traffic Manager ==

* Setting SSL->rbio without setting SSL->wbio. New function introduction in 1.1.0 to handle this: SSL_set_rbio()

== Things that Broke in OpenConnect ==

In order to simulate "resume" of a DTLS session which never really existed but which was actually negotiated over the VPN control connection, [http://git.infradead.org/users/dwmw2/openconnect.git/blob/fa5cea08:/dtls.c#l147 this code] in the [http://www.infradead.org/openconnect/ OpenConnect VPN client] needs to set the following fields in a new <tt>SSL_SESSION</tt>:
* <tt>->ssl_version</tt>
* <tt>->cipher{,_id}</tt>
* <tt>->master_key{,_length}</tt>
* <tt>->session_id{,_length}</tt>

This was fixed with [http://git.infradead.org/users/dwmw2/openconnect.git/commitdiff/5abb133f this OpenConnect commit] which makes it create the ASN.1 representation of the session and import it with <tt>d2i_SSL_SESSION()</tt>. This is done conditionally in the above patch because it depends on the [http://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff;h=af674d4e20a82c2a98767b837072d7093c70b1cf fix in openssl HEAD] for <tt>d2i_SSL_SESSION()</tt> to make it cope with <tt>DTLS1_BAD_VER</tt> <i>([http://rt.openssl.org/Ticket/Display.html?id=3704 RT#3704])</i>.

Other simpler things which broke:
* <tt>SSL_CIPHER->id</tt>. Replaced with <tt>SSL_CIPHER_get_id()</tt>
* <tt>SSL_CTX->extra_certs</tt>. Replaced with <tt>SSL_CTX_get_extra_chain_certs_only()</tt>

== Things that Broke in TianoCore/EDKII ==

EDKII is the reference implementation of UEFI firmware.

* Various implicit inclusions of <tt><openssl/bn.h></tt> and <tt><openssl/rsa.h></tt> needed to be made explicit. ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/8d7d32c1 (commit)]''
* <tt>X509_NAME->bytes->{data,length}</tt>. Replaced with <tt>i2d_X509_NAME()</tt> ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/e192c51b (commit)]''
* <tt>X509_ATTRIBUTE->{object,value}</tt>. Replaced with <tt>X509_ATTRIBUTE_get0_object()</tt> and <tt>X509_ATTRIBUTE_get0_type()</tt> ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/1bd8ee96 (commit)]''
* <tt>ASN1_OBJECT->{length,data}</tt>. Replaced with <tt>OBJ_get0_data()</tt> and <tt>OBJ_length()</tt>. With backward-compatibility <tt>#define</tt> of same. ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/6a7a36edc (commit)]''

Examples

2015-12-15T18:15:12Z

Rsalz:

Each topic containing code or script example should be tagged with Category:Examples.
So to find all example please select [[:Category:Examples]]

[[Category:Examples]]

'''Atomic intrinsics'''

We (or at least rsalz) want to use atomic intrinsics for OpenSSL's ref-counting in version 1.1

Please post links and/or snippets here on how to do it for various platforms.

Note that we are only interested the platforms we support, and that many were removed in 1.1

Examples

2015-12-15T18:14:32Z

Rsalz:

Each topic containing code or script example should be tagged with Category:Examples.
So to find all example please select [[:Category:Examples]]

[[Category:Examples]]

Atomic intrinsics

We (or at least rsalz) want to use atomic intrinsics for OpenSSL's ref-counting in version 1.1

Please post links and/or snippets here on how to do it for various platforms.

Note that we are only interested the platforms we support, and that many were removed in 1.1

Developing For OpenSSL

2015-07-29T20:04:55Z

Rsalz:

Periodically people ask us how to join the OpenSSL development team. This page is an attempt to answer that question.

Firstly it is important to understand that OpenSSL is complex. It is both a fully featured cryptography library as well as an SSL/TLS library. In addition the command line tools provide a wide array of capabilities. It can take quite a while to become proficient in coding in the internals. It is also clearly security sensitive. For those reasons joining the main development team is by invitation only. Most of the current development team have had an association with OpenSSL of one sort or another for a long time. Some have been on the project since the beginning, whilst many others joined later. For those joining later, without exception, everyone had a number of years of experience working with OpenSSL before they joined the team itself. The list of current development team members is available here: https://www.openssl.org/about/

However, there are still a number of ways to contribute to the project without joining the development team. We welcome such contributions:

* A good place to start is the openssl-users and openssl-dev mailing lists. The first of these forums will give you the opportunity to help out other users of OpenSSL, and learn from other experts in its use. The latter will give you an insight into some of the development issues that the team is tackling - and in particular issues being raised through the RT bug tracking system and responses to those issues.

* We are always looking for good people to help us build up the information held within this wiki. Documentation is one area where we are keen to improve things, and this wiki is an important location for people to come to. Information on how to get an account is available on the [[Welcome]] page.

* Bug fixes and enhancements to the code and documentation, can be submitted as RT tickets or pull requests. See the README for details. If using GitHub pull requests, please create a ticket with the PR number so that we can easily track it.

Use of Git

2015-07-29T20:02:55Z

Rsalz: /* Making patches */

Note: This is a superset of the information at http://www.openssl.org/source/repos.html

== Background information about using the Git distributed version control system ==

This page provides examples for some of the <tt>git</tt> commands used when accessing OpenSSL source code, but does not provide complete coverage.

* Refer to the <tt>git</tt> man ages and http://git-scm.com/ for more complete instructions on using the command.
* Refer to https://github.com/ for more complete instructions on interacting with Github.

== Use of Git with OpenSSL source tree ==

The OpenSSL group hosts its own Git repository at openssl.org, and this contains the master copy of OpenSSL. You can browse this at https://git.openssl.org/gitweb/?p=openssl.git;a=tree, or get a clone (checkout) of it with the command <tt>git clone git://git.openssl.org/openssl.git</tt>.

Contributors to OpenSSL should make use of the Github copy of this repository at https://github.com/openssl/openssl. Github makes it easy to maintain your own fork of OpenSSL for developing your contributions, as well as making a "pull request" to share fixes with the OpenSSL team when finished. Changes in the master Git repository are represented in the Github copy within minutes.

You can view existing pull requests against any of the branches at https://github.com/openssl/openssl/pulls

=== Getting a copy of the OpenSSL source tree ===

If you want to quickly make a copy of the OpenSSL source tree and you do not plan to publish any changes for use by others, just create a clone on your own machine.

<pre>
$ git clone https://github.com/openssl/openssl.git
</pre>

(Refer to Github documentation for instructions on other means of cloning the source tree.)

If you plan to make changes to the sources that you will share with others, including contributing changes to OpenSSL, it is recommended that you create a fork of the OpenSSL tree using your own Github id. You can use this to share changes with others whether or not you intend to submit changes to the OpenSSL team. Refer to the documentation at https://help.github.com/articles/fork-a-repo, in particular the discussion about how to track changes in the real OpenSSL repository that you forked.

=== Branches ===

The Git repositories contain multiple branches, representing development levels of OpenSSL as well as current and upcoming stable branches. An easy way to see the available branches is with the branch selector at https://github.com/openssl/openssl. The branches which are of most interest to most users are

* master (development)
* OpenSSL_1_0_2-stable (for the not-yet-released 1.0.2 series)
* OpenSSL_1_0_1-stable
* OpenSSL_1_0_0-stable

In order to access the code for a branch other than master, clone the Git repository then use the <tt>git checkout ''branchname''</tt> command to switch to a different branch. Consider using separate checkouts for each branch you are working in, with appropriate names for each, such as in the following example.

<pre>
$ git clone https://github.com/openssl/openssl.git OpenSSL-master
$ git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable
$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_0_2-stable)
$ git clone https://github.com/openssl/openssl.git OpenSSL_1_0_1-stable
$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_0_1-stable)
</pre>

If you've created your own fork of OpenSSL, replace the URL on the <tt>git clone</tt> command with the one for your fork. Also, you'll need to follow the instructions at https://help.github.com/articles/fork-a-repo for picking up changes from the master repository that you forked.

=== Making patches ===

Patches posted to OpenSSL development mailing lists or to the [https://www.openssl.org/support/rt.html OpenSSL Request Tracker] should be in Git <tt>format-patch</tt> format if at all practical, since that is easier for OpenSSL committers to apply since it contains author details.

The [http://git-scm.com/docs/git-format-patch <tt>git format-patch</tt>] documentation describes a lot of options. Here is an example of the most basic use.

:* You've been working on a particular OpenSSL branch within a Git clone of the source tree, and have made a couple of commits which you'd like to submit.
:* Print the log for those two commits and one more, the one before your commits:
<pre>
$ git log -3
commit 46983b73e04b448cb6cd9ea180044753174dec6d
Author: Jeff Trawick <trawick@gmail.com>
Date: Fri Apr 25 20:25:19 2014 -0400

spellcheck

commit 1e20bdf6bad38d9766e6cf3e64d903a99f1d9a6b
Author: Jeff Trawick <trawick@gmail.com>
Date: Fri Apr 25 14:07:07 2014 -0400

silly wording change

commit 3e124d66c8b66a48a824387b10768411a348f518
Author: Steve Marquess <marquess@opensslfoundation.com>
Date: Thu Apr 24 07:13:05 2014 -0400

Add new sponsors
(cherry picked from commit 351f0a124bffaa94d2a8abdec2e7dde5ae9c457d)
</pre>
:* Create a patch from changes '''after''' the third commit (<tt>3e124d66c8b66a48a824387b10768411a348f518</tt>), and pipe it to a file instead of letting <tt>git</tt> create a bunch of <tt>.patch</tt> files in the current directory:
<pre>
$ git format-patch 3e124d66c8b66a48a824387b10768411a348f518 --stdout >/tmp/FixWording.txt
$ cat /tmp/FixWording.txt
From 1e20bdf6bad38d9766e6cf3e64d903a99f1d9a6b Mon Sep 17 00:00:00 2001
From: Jeff Trawick <trawick@gmail.com>
Date: Fri, 25 Apr 2014 14:07:07 -0400
Subject: [PATCH 1/2] silly wording change

---
apps/s_client.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/s_client.c b/apps/s_client.c
index 01f4f34..eeb2e77 100644
--- a/apps/s_client.c
+++ b/apps/s_client.c
@@ -323,7 +323,7 @@ static void sc_usage(void)
BIO_printf(bio_err,"\n");
BIO_printf(bio_err," -host host - use -connect instead\n");
BIO_printf(bio_err," -port port - use -connect instead\n");
- BIO_printf(bio_err," -connect host:port - who to connect to (default is %s:%s)\n",SSL_HOST_NAME,PORT_STR);
+ BIO_printf(bio_err," -connect host:port - what to connect to (default is %s:%s)\n",SSL_HOST_NAME,PORT_STR);
BIO_printf(bio_err," -checkhost host - check peer certificate matches \"host\"\n");
BIO_printf(bio_err," -checkemail email - check peer certificate matches \"email\"\n");
BIO_printf(bio_err," -checkip ipaddr - check peer certificate matches \"ipaddr\"\n");
--
1.8.3.2

From 46983b73e04b448cb6cd9ea180044753174dec6d Mon Sep 17 00:00:00 2001
From: Jeff Trawick <trawick@gmail.com>
Date: Fri, 25 Apr 2014 20:25:19 -0400
Subject: [PATCH 2/2] spellcheck

---
PROBLEMS | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/PROBLEMS b/PROBLEMS
index 3eaab01..86f1e6e 100644
--- a/PROBLEMS
+++ b/PROBLEMS
@@ -41,13 +41,13 @@ passing -Wl,-search_paths_first, but it's unknown if the flag was
supported from the initial MacOS X release.

-* Parallell make leads to errors
+* Parallel make leads to errors

-While running tests, running a parallell make is a bad idea. Many test
+While running tests, running a parallel make is a bad idea. Many test
scripts use the same name for output and input files, which means different
will interfere with each other and lead to test failure.

-The solution is simple for now: don't run parallell make when testing.
+The solution is simple for now: don't run parallel make when testing.

* Bugs in gcc triggered
--
1.8.3.2
</pre>

Plan B, if you can't get <tt>git format-patch</tt> to work for some reason, is to create another, unmodified clone of the OpenSSL code, switch it to the branch you're working in, then use <tt>diff -ru</tt> as follows:

<pre>
$ diff -ru OpenSSL_1_0_2-stable-original OpenSSL_1_0_2-stable > /tmp/FixSClientUsage.txt
</pre>

(These two directories were created with <tt>git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable</tt> and <tt>git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable-original</tt>, and each was switched to the desired branch with <tt>git checkout OpenSSL_1_0_2-stable</tt>.)

Double check that only the desired changes are in the patch file. Otherwise, you probably weren't testing with the most recent OpenSSL changes.

Open a ticket using the request tracker and attach your patch file.
If you create your ticket via email, send the patch as an attachment, not as the body of your message.

=== Pull Requests ===

You can also suggest changes by making pull requests on GitHub. If you do this, please open a ticket and reference the PR number
so that we can more easily keep track of it.

=== Making pull requests ===

After developing and testing changes to OpenSSL in your checkout (clone), push them to your fork of OpenSSL (<tt>git push</tt>), then use the Github interface to submit a pull request to the master OpenSSL repository for the particular revision(s).

== Use of Git with the OpenSSL web site ==

The OpenSSL web site is also maintained in git, and can be browsed at https://git.openssl.org/gitweb/?p=openssl-web.git;a=tree.

Unlike the source code, the OpenSSL web site repository is not copied to Github. You can only interact with it via git.openssl.org, so it is not possible to submit pull requests.

Check it out as follows:

<pre>
$ git clone git://git.openssl.org/openssl-web.git
</pre>

In order to submit corrections to the web site, create a patch as described above.

Only the master branch of the web site repository is used.

Main Page

2015-07-29T19:56:12Z

Rsalz: /* Feedback and Contributions */

If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[SSL and TLS Protocols]]</TD>
</TR>
<TR>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
</TR>

</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* OpenSSL Manual Pages
::* [[Manual:Openssl(1)]], [[Manual:Ssl(3)]], [[Manual:Crypto(3)]], [[Documentation Index]]
:: If you wish to edit any of the Manual page content please refer to the [[Guidelines for Manual Page Authors]] page.
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* Low Level APIs
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]
:* [[Simple TLS Server]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/about/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/support/faq.html#BUILD18 How to notify us of suspected security vulnerabilities]
:* [https://www.openssl.org/support/rt.html How to report bugs and patches, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages:
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/support/community.html openssl-dev mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches. Note that manual pages and the FAQ are maintained with the source code.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report (see second bullet, above) and reference the pull request. Or you can attach the patch to the ticket.
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[Developing For OpenSSL]]
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Code reformatting]]

:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)

Code reformatting

2015-03-18T15:30:22Z

Rsalz: Created page with " == Code Reformatting == We recently (early 2015) reformatted all the OpenSSL code, in all release branches. As a result the code is consistent and, to almost everyone, easi..."

== Code Reformatting ==

We recently (early 2015) reformatted all the OpenSSL code, in all release branches.

As a result the code is consistent and, to almost everyone, easier to read.

The style policy is at [[https://openssl.org/about/codingstyle.txt]]

Matt wrote a couple of blog entries about the reformatting: [[https://www.openssl.org/blog/blog/2015/01/05/source-code-reformat/]] and [[https://www.openssl.org/blog/blog/2015/02/11/code-reformat-finished/]].

If you have a smaller number of local patches, you might find this recipe useful to upgrade:

* Take the original release you are currently using. Reformat it according to the second blog entry. Don't worry too much about minor failures or inconsistencies. Save that.

* Take your patched release. Reformat it according to the second blog entry. Don't worry too much about minor failures or inconsistencies. Save that.

* Run a diff between the two releases. You should, for the most part, have just your patches, reformatted.

Main Page

2015-03-18T15:25:12Z

Rsalz: /* Internals and Development */

If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[SSL and TLS Protocols]]</TD>
</TR>
<TR>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
</TR>

</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* OpenSSL Manual Pages
::* [[Manual:Openssl(1)]], [[Manual:Ssl(3)]], [[Manual:Crypto(3)]], [[Documentation Index]]
:: If you wish to edit any of the Manual page content please refer to the [[Guidelines for Manual Page Authors]] page.
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* Low Level APIs
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/about/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/support/faq.html#BUILD18 Notification of suspected security vulnerabilities]
:* [https://www.openssl.org/support/rt.html Contributing bug reports, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches
:::* Note that manual pages and the FAQ are maintained with the source code.
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/support/community.html openssl-dev mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report for the issue and reference the pull request
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Code reformatting]]
:* [[Developing For OpenSSL]]
:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)

OpenSSL 1.1.0 Changes

2015-02-03T21:58:10Z

Rsalz: Creation

Main Page

2015-02-03T21:52:28Z

Rsalz: /* OpenSSL Quick Links */

If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[SSL and TLS Protocols]]</TD>
</TR>
<TR>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
</TR>

</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* OpenSSL Manual Pages
::* [[Manual:Openssl(1)]], [[Manual:Ssl(3)]], [[Manual:Crypto(3)]], [[Documentation Index]]
:: If you wish to edit any of the Manual page content please refer to the [[Guidelines for Manual Page Authors]] page.
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* Low Level APIs
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/about/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/support/faq.html#BUILD18 Notification of suspected security vulnerabilities]
:* [https://www.openssl.org/support/rt.html Contributing bug reports, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches
:::* Note that manual pages and the FAQ are maintained with the source code.
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/support/community.html openssl-dev mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report for the issue and reference the pull request
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Developing For OpenSSL]]
:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)