OpenSSLWiki - User contributions [en]

SSL/TLS Client

2022-12-12T15:33:28Z

Jwalton: Make PREFERRED_CIPHERS a constant array.

[[SSL/TLS Client]] is sample code for a basic web client that fetches a page. The code shown below omits error checking for brevity, but the sample available for download performs the error checking.

The sample code will set up <tt>BIO</tt> to fet a page from <tt>www.random.org</tt>. The code uses TLS (not SSL) and utilizes the Server Name Indication (SNI) extension from [http://tools.ietf.org/rfc/rfc3546.txt RFC 3546, Transport Layer Security (TLS) Extensions].

If you need features beyond the example below, then you should examine <tt>s_client.c</tt> in the <tt>apps/</tt> directory of the OpenSSL distribution. OpenSSL's <tt>s_client</tt> implements nearly every client side feature available from the library.

The code below does '''not''' perform hostname verification. OpenSSL prior to 1.1.0 does not perform the check, and you must perform the check yourself. The OpenSSL [http://www.openssl.org/news/changelog.html Change Log] for OpenSSL 1.1.0 states you can use <tt>-verify_name</tt> option, and <tt>apps.c</tt> offers <tt>-verify_hostname</tt>. But <tt>s_client</tt> does not respond to either switch, so its unclear how hostname checking will be implemented or invoked for a client. '''Note (N.B.)''': hostname verification is marked as experimental, so switches, options, and implementations could change.

If you are looking for guidance on which protocols and ciphers you should be using, then see Adam Langley's blog [http://www.imperialviolet.org/2014/12/08/poodleagain.html The POODLE bites again]. The short version: use only TLS 1.2, use only ephemeral key exchanges, and use only AEAD ciphers (like AES/GCM, Camellia/GCM, ChaCha/Poly1305).

An example of a TLS client written by the developer team can be found in the source code at demos/sslecho.

== Implementation ==

The code below demonstrates a basic client that uses BIOs and TLS to connect to <tt>www.random.org</tt>, and fetches 32 bytes of random data through an HTTP request. The sample code is available for download below.

<pre>#define HOST_NAME "www.random.org"
#define HOST_PORT "443"
#define HOST_RESOURCE "/cgi-bin/randbyte?nbytes=32&format=h"

long res = 1;

SSL_CTX* ctx = NULL;
BIO *web = NULL, *out = NULL;
SSL *ssl = NULL;

init_openssl_library();

const SSL_METHOD* method = SSLv23_method();
if(!(NULL != method)) handleFailure();

ctx = SSL_CTX_new(method);
if(!(ctx != NULL)) handleFailure();

/* Cannot fail ??? */
SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_callback);

/* Cannot fail ??? */
SSL_CTX_set_verify_depth(ctx, 4);

/* Cannot fail ??? */
const long flags = SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_NO_COMPRESSION;
SSL_CTX_set_options(ctx, flags);

res = SSL_CTX_load_verify_locations(ctx, "random-org-chain.pem", NULL);
if(!(1 == res)) handleFailure();

web = BIO_new_ssl_connect(ctx);
if(!(web != NULL)) handleFailure();

res = BIO_set_conn_hostname(web, HOST_NAME ":" HOST_PORT);
if(!(1 == res)) handleFailure();

BIO_get_ssl(web, &ssl);
if(!(ssl != NULL)) handleFailure();

const char PREFERRED_CIPHERS[] = "HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4";
res = SSL_set_cipher_list(ssl, PREFERRED_CIPHERS);
if(!(1 == res)) handleFailure();

res = SSL_set_tlsext_host_name(ssl, HOST_NAME);
if(!(1 == res)) handleFailure();

out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(!(NULL != out)) handleFailure();

res = BIO_do_connect(web);
if(!(1 == res)) handleFailure();

res = BIO_do_handshake(web);
if(!(1 == res)) handleFailure();

/* Step 1: verify a server certificate was presented during the negotiation */
X509* cert = SSL_get_peer_certificate(ssl);
if(cert) { X509_free(cert); } /* Free immediately */
if(NULL == cert) handleFailure();

/* Step 2: verify the result of chain verification */
/* Verification performed according to RFC 4158 */
res = SSL_get_verify_result(ssl);
if(!(X509_V_OK == res)) handleFailure();

/* Step 3: hostname verification */
/* An exercise left to the reader */

BIO_puts(web, "GET " HOST_RESOURCE " HTTP/1.1\r\n"
"Host: " HOST_NAME "\r\n"
"Connection: close\r\n\r\n");
BIO_puts(out, "\n");

int len = 0;
do
{
char buff[1536] = {};
len = BIO_read(web, buff, sizeof(buff));

if(len > 0)
BIO_write(out, buff, len);

} while (len > 0 || BIO_should_retry(web));

if(out)
BIO_free(out);

if(web != NULL)
BIO_free_all(web);

if(NULL != ctx)
SSL_CTX_free(ctx);</pre>

== Initialization ==

The sample program initializes the OpenSSL library with <tt>init_openssl_library</tt>. <tt>init_openssl_library</tt> calls three OpenSSL functions.

<pre>#if (SSLEAY_VERSION_NUMBER >= 0x0907000L)
# include <openssl/conf.h>
#endif
...

void init_openssl_library(void)
{
(void)SSL_library_init();

SSL_load_error_strings();

/* ERR_load_crypto_strings(); */

OPENSSL_config(NULL);

/* Include <openssl/opensslconf.h> to get this define */
#if defined (OPENSSL_THREADS)
fprintf(stdout, "Warning: thread locking is not implemented\n");
#endif
}</pre>

'''<tt>SSL_library_init</tt>''' performs initialization of <tt>libcrypto</tt> and <tt>libssl</tt>, and loads required algorithms. The documents state <tt>SSL_library_init</tt> always returns <tt>1</tt>, so its a useless return value.

'''<tt>SSL_load_error_strings</tt>''' loads error strings from both <tt>libcrypto</tt> and <tt>libssl</tt>. There's no need to call <tt>ERR_load_crypto_strings</tt>.

'''<tt>OpenSSL_add_ssl_algorithms</tt>''' is a <tt>#define</tt> for <tt>SSL_library_init</tt>, so the call is omitted.

'''<tt>OPENSSL_config</tt>''' may (or may not) be needed. Internally, <tt>OPENSSL_config</tt> is called based on a configuration options via <tt>OPENSSL_LOAD_CONF</tt>. If you are dynamically loading an engine specified in <tt>openssl.cnf</tt>, then you might need it so you should call it. That is, don't depend upon the OpenSSL library to call it for you.

If you are building a multi-threaded client, you should set the locking callbacks. See [https://www.openssl.org/docs/crypto/threads.html threads(3)] for details.

A detailed treatment of initialization can be found at [[Library Initialization]].

== Context Setup ==

The sample program uses '''<tt>SSLv23_method</tt>''' to create a context. '''<tt>SSLv23_method</tt>''' specifies that version negotiation will be used. Do not be confused by the name (it does NOT mean that only SSLv2 or SSLv3 will be used). The name is like that for historical reasons, and the function has been renamed to '''<tt>TLS_method</tt>''' in the forthcoming OpenSSL version 1.1.0. Using this method will negotiate the highest protocol version supported by both the server and the client. SSL/TLS versions currently supported by OpenSSL 1.0.2 are SSLv2, SSLv3, TLS1.0, TLS1.1 and TLS1.2.

The actual SSL and TLS protocols are further tuned through options. By using <tt>SSLv23_method</tt> (and removing the unwanted protocol versions with <tt>SSL_OP_NO_SSLv2</tt> and <tt>SSL_OP_NO_SSLv3</tt>), then you will effectively use TLS v1.0 and above, including TLS v1.2. You can also use <tt>SSL_OP_NO_TLSv1</tt> and <tt>SSL_OP_NO_TLSv1_1</tt> if you want to use the TLS 1.2 protocol only.

'''<tt>SSL_CTX_new</tt>''' uses the <tt>SSLv23_method</tt> method to create a new '''SSL/TLS context object'''. If you use, for example <tt>TLSv1_method</tt>, then you will only use TLS v1.0, and if you use <tt>TLSv1_1_method</tt> then you will only use TLS v1.1. Typically you should always use '''<tt>SSLv23_method</tt>''' in preference to the version specific methods.

OpenSSL 1.1.0 improves protocol selection by providing <tt>SSL_CTX_set_max_proto_version()</tt> and <tt>SSL_CTX_set_min_proto_version()</tt>. You no longer need to subtract unwanted options with <tt>SSL_OP_NO_SSLv2</tt> and <tt>SSL_OP_NO_SSLv3</tt>. Also see the [http://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_max_proto_version.html <tt>SSL_CTX_set_max_proto_version()</tt> and <tt>SSL_CTX_set_min_proto_version()</tt> man pages].

== Options (1) ==

After creating a context with <tt>SSLv23_method</tt> and <tt>SSL_CTX_new</tt>, the context object is tuned with the following functions:

* <tt>SSL_CTX_set_verify</tt>
* <tt>SSL_CTX_set_verify_depth</tt>
* <tt>SSL_CTX_set_options</tt>
* <tt>SSL_CTX_load_verify_locations</tt>

'''<tt>SSL_CTX_set_verify</tt>''' sets the <tt>SSL_VERIFY_PEER</tt> flag and the verify callback. This ensures the chain is verified according to [http://tools.ietf.org/html/rfc4158 RFC 4158] and Issuer and Subject information can be printed. If you don't want to perform custom processing (such as printing or checking), then don't set the callback. OpenSSL's default checking should be sufficient, so pass <tt>NULL</tt> to <tt>SSL_CTX_set_verify</tt>.

There is also a <tt>SSL_VERIFY_FAIL_IF_NO_PEER_CERT</tt> flag, but it is used for servers and has no effect on clients. If you accidentally use <tt>SSL_VERIFY_FAIL_IF_NO_PEER_CERT</tt>, then you chain will always verify when call <tt>SSL_get_verify_result</tt> because the flag is ignored for clients (essentially, 0 is passed for the flag which performs no verification).

'''<tt>SSL_CTX_set_verify_depth</tt>''' sets the chain depth to 4. Chain depth is fairly useless in practice.

'''<tt>SSL_CTX_set_options</tt>''' set the <tt>SSL_OP_ALL</tt>, <tt>SSL_OP_NO_SSLv2</tt>, <tt>SSL_OP_NO_SSLv3</tt>, <tt>SSL_OP_NO_COMPRESSION</tt> options. In essence, it takes all the bug fixes and work arounds for the various servers, removes the SSL protocols (leaving only TLS protocols), and removes compression. The remaining TLS protocols are TLS 1.0, TLS 1.1, and TLS 1.2.

'''<tt>SSL_CTX_load_verify_locations</tt>''' loads the certificate chain for the <tt>random.org</tt> site. The site's CA is Comodo, and the chain includes ''AddTrust External CA Root'', ''COMODO Certification Authority'', and ''COMODO Extended Validation Secure Server CA''. Though the chain is provided, only the single trust anchor is needed for validation. The additional intermediate certs are provided to show how to concatenate and load them.

The PEM format means the file is a concatenation of Base64 encoded certificates with the <tt>-----BEGIN CERTIFICATE-----</tt> prologue (and associated epilogue). If the server sends all certificates required to verify the chain (which it should), then only the ''AddTrust External CA Root'' certificate is needed.

The options set on the <tt>CTX*</tt> can be overridden on a per-connection basis by modifying the <tt>SSL*</tt> using <tt>SSL_set_verify</tt>, <tt>SSL_set_verify_depth</tt> and <tt>SSL_set_options</tt> (and friends).

== SSL BIO ==

The sample program uses BIOs for input and output. One BIO is used to connect to <tt>random.org</tt>, and a second BIO is used to print output to <tt>stdout</tt>.

'''<tt>BIO_new_ssl_connect</tt>''' creates a new BIO chain consisting of an SSL BIO (using ctx) followed by a connect BIO.

'''<tt>BIO_set_conn_hostname</tt>''' is used to set the hostname and port that will be used by the connection.

== Options (2) ==

'''<tt>BIO_get_ssl</tt>''' is used to fetch the '''SSL connection object''' created by <tt>BIO_new_ssl_connect</tt>. The connection object inherits from the context object, and can override the settings on the context. The connection object is tuned with the following functions:

* <tt>SSL_set_cipher_list</tt>
* <tt>SSL_set_tlsext_host_name</tt>

'''<tt>SSL_set_cipher_list</tt>''' sets the cipher list. The list prefers elliptic curves, ephemeral [Diffie-Hellman], AES and SHA. It also removes NULL authentication methods and ciphers; and removes medium-security, low-security and export-grade security ciphers, such as 40-bit RC2. If desired, you could set the options on the context with <tt>SSL_CTX_set_cipher_list</tt>.

'''<tt>SSL_set_tlsext_host_name</tt>''' uses the TLS SNI extension to set the hostname. If you are connecting to a Server Name Indication-aware server (such as Apache with name-based virtual hosts or IIS 8.0), then you will receive the proper certificate during the handshake.

== Cipher Suites ==

[[File:cipher-suites.png|thumb|right|Wireshark and ClientHello]] According to <tt>openssl ciphers ALL</tt>, there are just over 110 cipher suites available. Each cipher suite takes 2 bytes in the <tt>ClientHello</tt>, so advertising every cipher suite available at the client is going to cause a big <tt>ClientHello</tt> (or bigger then needed to get the job done). When using <tt>SSL_CTX_set_cipher_list</tt> or <tt>SSL_set_cipher_list</tt> with the string <tt>"HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4"</tt>, you'll cut the number of cipher suites down to about 45. If you know the server '''does not''' support DSA, then you can add <tt>"!DSS"</tt> and reduce the list further by about 7. And removing RSA key transport (<tt>"!kRSA"</tt>) removes another 9 more (this is a good practice because it uses ephemeral key exchanges which provide forward secrecy). Advertising 35 or so ciphers saves about 160 bytes in the <tt>ClientHello</tt>.

Better, pick 16 or 20 ciphers you want to support and advertise them. Order them so the GCM mode ciphers from TLS 1.2 are listed first, and the AES-SHA ciphers from TLS 1.0 are listed last. Though TLS 1.0 should be avoided, its probably needed for interop because only about [https://www.trustworthyinternet.org/ssl-pulse/ half the servers on the internet support TLS 1.2]. If you control the server, then it should be offering TLS 1.2 and clients only need to advertise AEAD ciphers like AES/GCM or Camellia/GCM.

Keeping the <tt>ClientHello</tt> small is important for older F5 and IronPort devices. Apparently, the devices used fixed sized buffers and choke on large <tt>ClientHello</tt>'s. In fact, a "large hello" was the cause of the TLS padding bug on IronPort devices. See [http://www.ietf.org/mail-archive/web/tls/current/msg12145.html TLS padding breaks ironport] on the TLS mailing list for details.

== Connection ==

[[File:bio-fetch-3.png|thumb|right|Wireshark and TLS versions]] After setting the connection object options, the sample connects to the site and negotiates a secure channel.

* <tt>BIO_do_connect</tt>
* <tt>BIO_do_handshake</tt>

'''<tt>BIO_do_connect</tt>''' performs the name lookup for the host and standard TCP/IP three way handshake.

'''<tt>BIO_do_handshake</tt>''' performs the SSL/TLS handshake. If you set a callback with <tt>SSL_CTX_set_verify</tt> or <tt>SSL_set_verify</tt>, then you callback will be invoked for each certificate in the chain used during the execution of the protocol.

The Wireshark packet capture to the right shows the TLS handshake with the SNI extension encountered during the execution of <tt>BIO_do_handshake</tt>. OpenSSL 1.0.1e advertises TLSv1.2 as the highest protocol level in its <tt>ClientHello</tt>.

== Callback ==

OpenSSL provides the ability for an application to interact with the chain validation by way of a callback. Normally, most application don't need to use it since the default OpenSSL behavior is usually adequate. In the callback, you can pass the <tt>preverify</tt> result back to the library (leaving library behavior unchanged), or you can modify the result to account for a specific issue that your software should address (override default behavior). If you don't need to interact with chain validation, then don't set the callback.

The example program returned the <tt>preverify</tt> result to the library and just printed information about the certificate in the chain. It did so by using <tt>SSL_CTX_set_verify</tt> with <tt>SSL_VERIFY_PEER</tt> and the <tt>verify_callback</tt>.

<pre>int verify_callback(int preverify, X509_STORE_CTX* x509_ctx)
{
int depth = X509_STORE_CTX_get_error_depth(x509_ctx);
int err = X509_STORE_CTX_get_error(x509_ctx);

X509* cert = X509_STORE_CTX_get_current_cert(x509_ctx);
X509_NAME* iname = cert ? X509_get_issuer_name(cert) : NULL;
X509_NAME* sname = cert ? X509_get_subject_name(cert) : NULL;

print_cn_name("Issuer (cn)", iname);
print_cn_name("Subject (cn)", sname);

if(depth == 0) {
/* If depth is 0, its the server's certificate. Print the SANs too */
print_san_name("Subject (san)", cert);
}

return preverify;
}</pre>

The OpenSSL library will pass in the value of its preliminary checking of the certificate through <tt>preverify</tt>. '''If''' you always return <tt>1</tt> regardless of the value of <tt>preverify</tt> or the actual result of your processing, then <tt>SSL_get_verify_result</tt> will always return <tt>X509_V_OK</tt>. That's probably a bad idea for production software.

If you don't need to perform special processing on the chain, then you should forgo the <tt>verify_callback</tt> altogether by supplying <tt>NULL</tt> to <tt>SSL_CTX_set_verify</tt>:

<pre>SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL);</pre>

== Verification ==

You use one of two verification procedures, depending on the version of OpenSSL you are using. The change occurs at OpenSSL 1.1.0 because 1.1.0 (and above) implements hostname verification that 1.0.2 (and below) lacked. Painting with a broad brush, minimal checking includes: (1) confirm the server has a certificate, (2) confirm the certificate chain verifies back to a trusted root, and (3) confirm the name of the host matches a hostname listed in the server's certificate.

In the end, its probably better to ignore PKI and just use Public Key Pinning (or Certificate Pinning) when a pre-exisiting relationship exists; or use a Perspectives-like system or a Trust-On-First-Use (TOFU) system when there's no ''a priori'' relationship (similar to SSH's <tt>StrictHostkeyChecking</tt> option). See Peter Gutmann's [https://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security] for details of a security diversification strategy (Chapter 4, starting on page 292).

You usually don't perform revocation in real time because it essentially creates a denial of service on your application. That is, your app will hang while downloading a multi-megabyte CRL or contacts a missing OCSP responder. For a detailed treatment of problems with PKI and Revocation, see Peter Gutmann's [https://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security] (Chapters 1 and 8).

=== OpenSSL 1.0.2 ===

OpenSSL 1.0.2 and below requires at least three checks. These versions of OpenSSL do ''not'' perform hostname validation and the API user must perform it.

==== Server Certificate ====

You must confirm the server provided a certificate. This is because a server might be misconfigured, or the client and server used Anonymous Diffie-Hellman. You do so as follows:

<pre>X509* cert = SSL_get_peer_certificate(ssl);
if(cert) { X509_free(cert); }
if(NULL == cert) handleFailure();</pre>

If the server has a certificate, then <tt>SSL_get_peer_certificate</tt> will return a non-NULL value. You don't really need the certificate, so its <tt>free</tt>'d immediately.

==== Certificate Chain ====

You must confirm the server's certificate chains back to a trusted root, and all the certificates in the chain are valid. You do so as follows:

<pre>long res = SSL_get_verify_result(ssl);
if(!(X509_V_OK == res)) handleFailure();</pre>

<tt>SSL_get_verify_result</tt> returns the result of verifying the chain. See the earlier warning on doing the wrong thing in the verification callback.

==== Certificate Names ====

You must confirm a match between the hostname you contacted and the hostnames listed in the certificate. OpenSSL prior to 1.1.0 does not perform hostname verification, so you will have to perform the checking yourself. The sample code does not offer code at the moment, so you will need to borrow it or implement it.

If you want to borrow the code, take a look at [http://curl.haxx.se/libcurl/ libcurl] and the verification procedure in source file <tt>ssluse.c</tt>. Another source is the C/C++ Secure Coding Guide and Section 10.8, [http://etutorials.org/Programming/secure+programming/Chapter+10.+Public+Key+Infrastructure/10.8+Adding+Hostname+Checking+to+Certificate+Verification/ Adding Hostname Checking to Certificate Verification]. If you implement the code for checking, the sample code shows you how to extract the Common Name (CN) and Subject Alternate Names (SAN) from the certificate in <tt>print_cn_name</tt> and <tt>print_san_name</tt>.

'''Note''': matching between the hostname (used in <tt>BIO_do_connect </tt>) and names in the certificate (from <tt>SSL_get_peer_certificate</tt>) must also be validated. For example, a certificate cannot claim to be wildcarded for <tt>*.com</tt>, <tt>*.net</tt>, or other Top Level Domains (TLDs). In addition to the TLDs, you also have to country level or ccTLDs, so it can't match <tt>*.us</tt>, <tt>*.cn</tt>, <tt>*.fed.us</tt>, <tt>*.公司.cn</tt> or similar levels either. Mozilla maintains a list of ccTLDs that are off limits at the [http://publicsuffix.org/ Public Suffix List], and there are currently 6136 entries on the list.

== Program Output ==

After all this musing, here's the lousy output you get when running the program:

{| align="center"
| [[File:bio-fetch-1.png|350px|Figure 1: Chain Output]]
|    
| [[File:bio-fetch-2.png|350px|Figure 2: Server Response]]
|}

== Session Reuse ==

According to Viktor Dukhovni at [http://mta.openssl.org/pipermail/openssl-users/2016-September/004564.html Possible to control session reuse from the client]:

<pre>> For performance testing purposes, I would like to turn off session
> reuse in the (homegrown) client I use for testing. Is there a function
> in the openssl library to do it?
>
> I tried googling for "openssl client don't send session id" but I didn't
> find anything useful.

Just do nothing. Client sessions are not reused unless you explicitly
arrange for reuse of a session by calling SSL_set_session() before
SSL_connect(). If you're trying to avoid wasting memory on storing
client-side sessions that you'll never reuse then this may help:

SSL_CTX_set_session_cache_mode(client_ctx, SSL_SESS_CACHE_OFF);

but note this is also the default state, so is also not needed unless
some other code has explicitly enabled client-side caching of sessions.

Only the server-side cache is enabled by default.</pre>

== Session Tickets ==

Session tickets are specified in [http://www.ietf.org/rfc/rfc5077.txt RFC 5077]. You can disable session tickets with <tt>SSL_OP_NO_TICKET</tt>:

<pre>const long flags = SSL_OP_NO_SSLv3 | ... | SSL_OP_NO_TICKET;
SSL_CTX_set_options(ctx, flags);</pre>

== 0-RTT ==

0-RTT is specified in XXX (TODO). 0-RTT allows an application to immediately resume a previous session at the expense of consuming unauthenticated data. You should avoid 0-RTT if possible. In fact, an organization's data security policy may not allow it for some higher data sensitivity levels.

Care should be taken if enabling 0-RTT at the client because a number of protections must be enabled at the server. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg15594.html 0-RTT and Anti-Replay] and [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.

* 0-RTT without stateful anti-replay allows for very high number of replays, breaking rate limiting systems, even high-performance ones, resulting in an opening for DDoS attacks.

* 0-RTT without stateful anti-replay allows for very high number of replays, allowing exploiting timing side channels for information leakage. Very few if any applications are engineered to mitigate or eliminate such side channels.

* 0-RTT without global anti-replay allows leaking information from the 0-RTT data via cache timing attacks. HTTP GET URLs sent to CDNs are especially vulnerable.

* 0-RTT without global anti-replay allows non-idempotent actions contained in 0-RTT data to be repeated potentially lots of times. Abuse of HTTP GET for non-idempotent actions is fairly common.

* 0-RTT allows easily reordering request with re-transmission from the client. This can lead to various unexpected application behavior if possibility of such reordering is not taken into account. "Eventually consistent" datastores are especially vulnerable.

* 0-RTT exporters are not safe for authentication unless the server does global anti-replay on 0-RTT.

== Downloads ==

[[Media:openssl-bio-fetch.tar.gz|openssl-bio-fetch.tar.gz]] - The program and Makefile used for this wiki page.

SSL/TLS Client

2022-04-24T23:58:59Z

Jwalton: Add info about demos/sslecho to introduction.

[[SSL/TLS Client]] is sample code for a basic web client that fetches a page. The code shown below omits error checking for brevity, but the sample available for download performs the error checking.

The sample code will set up <tt>BIO</tt> to fet a page from <tt>www.random.org</tt>. The code uses TLS (not SSL) and utilizes the Server Name Indication (SNI) extension from [http://tools.ietf.org/rfc/rfc3546.txt RFC 3546, Transport Layer Security (TLS) Extensions].

If you need features beyond the example below, then you should examine <tt>s_client.c</tt> in the <tt>apps/</tt> directory of the OpenSSL distribution. OpenSSL's <tt>s_client</tt> implements nearly every client side feature available from the library.

The code below does '''not''' perform hostname verification. OpenSSL prior to 1.1.0 does not perform the check, and you must perform the check yourself. The OpenSSL [http://www.openssl.org/news/changelog.html Change Log] for OpenSSL 1.1.0 states you can use <tt>-verify_name</tt> option, and <tt>apps.c</tt> offers <tt>-verify_hostname</tt>. But <tt>s_client</tt> does not respond to either switch, so its unclear how hostname checking will be implemented or invoked for a client. '''Note (N.B.)''': hostname verification is marked as experimental, so switches, options, and implementations could change.

If you are looking for guidance on which protocols and ciphers you should be using, then see Adam Langley's blog [http://www.imperialviolet.org/2014/12/08/poodleagain.html The POODLE bites again]. The short version: use only TLS 1.2, use only ephemeral key exchanges, and use only AEAD ciphers (like AES/GCM, Camellia/GCM, ChaCha/Poly1305).

An example of a TLS client written by the developer team can be found in the source code at demos/sslecho.

== Implementation ==

The code below demonstrates a basic client that uses BIOs and TLS to connect to <tt>www.random.org</tt>, and fetches 32 bytes of random data through an HTTP request. The sample code is available for download below.

<pre>#define HOST_NAME "www.random.org"
#define HOST_PORT "443"
#define HOST_RESOURCE "/cgi-bin/randbyte?nbytes=32&format=h"

long res = 1;

SSL_CTX* ctx = NULL;
BIO *web = NULL, *out = NULL;
SSL *ssl = NULL;

init_openssl_library();

const SSL_METHOD* method = SSLv23_method();
if(!(NULL != method)) handleFailure();

ctx = SSL_CTX_new(method);
if(!(ctx != NULL)) handleFailure();

/* Cannot fail ??? */
SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_callback);

/* Cannot fail ??? */
SSL_CTX_set_verify_depth(ctx, 4);

/* Cannot fail ??? */
const long flags = SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_NO_COMPRESSION;
SSL_CTX_set_options(ctx, flags);

res = SSL_CTX_load_verify_locations(ctx, "random-org-chain.pem", NULL);
if(!(1 == res)) handleFailure();

web = BIO_new_ssl_connect(ctx);
if(!(web != NULL)) handleFailure();

res = BIO_set_conn_hostname(web, HOST_NAME ":" HOST_PORT);
if(!(1 == res)) handleFailure();

BIO_get_ssl(web, &ssl);
if(!(ssl != NULL)) handleFailure();

const char* const PREFERRED_CIPHERS = "HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4";
res = SSL_set_cipher_list(ssl, PREFERRED_CIPHERS);
if(!(1 == res)) handleFailure();

res = SSL_set_tlsext_host_name(ssl, HOST_NAME);
if(!(1 == res)) handleFailure();

out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(!(NULL != out)) handleFailure();

res = BIO_do_connect(web);
if(!(1 == res)) handleFailure();

res = BIO_do_handshake(web);
if(!(1 == res)) handleFailure();

/* Step 1: verify a server certificate was presented during the negotiation */
X509* cert = SSL_get_peer_certificate(ssl);
if(cert) { X509_free(cert); } /* Free immediately */
if(NULL == cert) handleFailure();

/* Step 2: verify the result of chain verification */
/* Verification performed according to RFC 4158 */
res = SSL_get_verify_result(ssl);
if(!(X509_V_OK == res)) handleFailure();

/* Step 3: hostname verification */
/* An exercise left to the reader */

BIO_puts(web, "GET " HOST_RESOURCE " HTTP/1.1\r\n"
"Host: " HOST_NAME "\r\n"
"Connection: close\r\n\r\n");
BIO_puts(out, "\n");

int len = 0;
do
{
char buff[1536] = {};
len = BIO_read(web, buff, sizeof(buff));

if(len > 0)
BIO_write(out, buff, len);

} while (len > 0 || BIO_should_retry(web));

if(out)
BIO_free(out);

if(web != NULL)
BIO_free_all(web);

if(NULL != ctx)
SSL_CTX_free(ctx);</pre>

== Initialization ==

The sample program initializes the OpenSSL library with <tt>init_openssl_library</tt>. <tt>init_openssl_library</tt> calls three OpenSSL functions.

<pre>#if (SSLEAY_VERSION_NUMBER >= 0x0907000L)
# include <openssl/conf.h>
#endif
...

void init_openssl_library(void)
{
(void)SSL_library_init();

SSL_load_error_strings();

/* ERR_load_crypto_strings(); */

OPENSSL_config(NULL);

/* Include <openssl/opensslconf.h> to get this define */
#if defined (OPENSSL_THREADS)
fprintf(stdout, "Warning: thread locking is not implemented\n");
#endif
}</pre>

'''<tt>SSL_library_init</tt>''' performs initialization of <tt>libcrypto</tt> and <tt>libssl</tt>, and loads required algorithms. The documents state <tt>SSL_library_init</tt> always returns <tt>1</tt>, so its a useless return value.

'''<tt>SSL_load_error_strings</tt>''' loads error strings from both <tt>libcrypto</tt> and <tt>libssl</tt>. There's no need to call <tt>ERR_load_crypto_strings</tt>.

'''<tt>OpenSSL_add_ssl_algorithms</tt>''' is a <tt>#define</tt> for <tt>SSL_library_init</tt>, so the call is omitted.

'''<tt>OPENSSL_config</tt>''' may (or may not) be needed. Internally, <tt>OPENSSL_config</tt> is called based on a configuration options via <tt>OPENSSL_LOAD_CONF</tt>. If you are dynamically loading an engine specified in <tt>openssl.cnf</tt>, then you might need it so you should call it. That is, don't depend upon the OpenSSL library to call it for you.

If you are building a multi-threaded client, you should set the locking callbacks. See [https://www.openssl.org/docs/crypto/threads.html threads(3)] for details.

A detailed treatment of initialization can be found at [[Library Initialization]].

== Context Setup ==

The sample program uses '''<tt>SSLv23_method</tt>''' to create a context. '''<tt>SSLv23_method</tt>''' specifies that version negotiation will be used. Do not be confused by the name (it does NOT mean that only SSLv2 or SSLv3 will be used). The name is like that for historical reasons, and the function has been renamed to '''<tt>TLS_method</tt>''' in the forthcoming OpenSSL version 1.1.0. Using this method will negotiate the highest protocol version supported by both the server and the client. SSL/TLS versions currently supported by OpenSSL 1.0.2 are SSLv2, SSLv3, TLS1.0, TLS1.1 and TLS1.2.

The actual SSL and TLS protocols are further tuned through options. By using <tt>SSLv23_method</tt> (and removing the unwanted protocol versions with <tt>SSL_OP_NO_SSLv2</tt> and <tt>SSL_OP_NO_SSLv3</tt>), then you will effectively use TLS v1.0 and above, including TLS v1.2. You can also use <tt>SSL_OP_NO_TLSv1</tt> and <tt>SSL_OP_NO_TLSv1_1</tt> if you want to use the TLS 1.2 protocol only.

'''<tt>SSL_CTX_new</tt>''' uses the <tt>SSLv23_method</tt> method to create a new '''SSL/TLS context object'''. If you use, for example <tt>TLSv1_method</tt>, then you will only use TLS v1.0, and if you use <tt>TLSv1_1_method</tt> then you will only use TLS v1.1. Typically you should always use '''<tt>SSLv23_method</tt>''' in preference to the version specific methods.

OpenSSL 1.1.0 improves protocol selection by providing <tt>SSL_CTX_set_max_proto_version()</tt> and <tt>SSL_CTX_set_min_proto_version()</tt>. You no longer need to subtract unwanted options with <tt>SSL_OP_NO_SSLv2</tt> and <tt>SSL_OP_NO_SSLv3</tt>. Also see the [http://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_max_proto_version.html <tt>SSL_CTX_set_max_proto_version()</tt> and <tt>SSL_CTX_set_min_proto_version()</tt> man pages].

== Options (1) ==

After creating a context with <tt>SSLv23_method</tt> and <tt>SSL_CTX_new</tt>, the context object is tuned with the following functions:

* <tt>SSL_CTX_set_verify</tt>
* <tt>SSL_CTX_set_verify_depth</tt>
* <tt>SSL_CTX_set_options</tt>
* <tt>SSL_CTX_load_verify_locations</tt>

'''<tt>SSL_CTX_set_verify</tt>''' sets the <tt>SSL_VERIFY_PEER</tt> flag and the verify callback. This ensures the chain is verified according to [http://tools.ietf.org/html/rfc4158 RFC 4158] and Issuer and Subject information can be printed. If you don't want to perform custom processing (such as printing or checking), then don't set the callback. OpenSSL's default checking should be sufficient, so pass <tt>NULL</tt> to <tt>SSL_CTX_set_verify</tt>.

There is also a <tt>SSL_VERIFY_FAIL_IF_NO_PEER_CERT</tt> flag, but it is used for servers and has no effect on clients. If you accidentally use <tt>SSL_VERIFY_FAIL_IF_NO_PEER_CERT</tt>, then you chain will always verify when call <tt>SSL_get_verify_result</tt> because the flag is ignored for clients (essentially, 0 is passed for the flag which performs no verification).

'''<tt>SSL_CTX_set_verify_depth</tt>''' sets the chain depth to 4. Chain depth is fairly useless in practice.

'''<tt>SSL_CTX_set_options</tt>''' set the <tt>SSL_OP_ALL</tt>, <tt>SSL_OP_NO_SSLv2</tt>, <tt>SSL_OP_NO_SSLv3</tt>, <tt>SSL_OP_NO_COMPRESSION</tt> options. In essence, it takes all the bug fixes and work arounds for the various servers, removes the SSL protocols (leaving only TLS protocols), and removes compression. The remaining TLS protocols are TLS 1.0, TLS 1.1, and TLS 1.2.

'''<tt>SSL_CTX_load_verify_locations</tt>''' loads the certificate chain for the <tt>random.org</tt> site. The site's CA is Comodo, and the chain includes ''AddTrust External CA Root'', ''COMODO Certification Authority'', and ''COMODO Extended Validation Secure Server CA''. Though the chain is provided, only the single trust anchor is needed for validation. The additional intermediate certs are provided to show how to concatenate and load them.

The PEM format means the file is a concatenation of Base64 encoded certificates with the <tt>-----BEGIN CERTIFICATE-----</tt> prologue (and associated epilogue). If the server sends all certificates required to verify the chain (which it should), then only the ''AddTrust External CA Root'' certificate is needed.

The options set on the <tt>CTX*</tt> can be overridden on a per-connection basis by modifying the <tt>SSL*</tt> using <tt>SSL_set_verify</tt>, <tt>SSL_set_verify_depth</tt> and <tt>SSL_set_options</tt> (and friends).

== SSL BIO ==

The sample program uses BIOs for input and output. One BIO is used to connect to <tt>random.org</tt>, and a second BIO is used to print output to <tt>stdout</tt>.

'''<tt>BIO_new_ssl_connect</tt>''' creates a new BIO chain consisting of an SSL BIO (using ctx) followed by a connect BIO.

'''<tt>BIO_set_conn_hostname</tt>''' is used to set the hostname and port that will be used by the connection.

== Options (2) ==

'''<tt>BIO_get_ssl</tt>''' is used to fetch the '''SSL connection object''' created by <tt>BIO_new_ssl_connect</tt>. The connection object inherits from the context object, and can override the settings on the context. The connection object is tuned with the following functions:

* <tt>SSL_set_cipher_list</tt>
* <tt>SSL_set_tlsext_host_name</tt>

'''<tt>SSL_set_cipher_list</tt>''' sets the cipher list. The list prefers elliptic curves, ephemeral [Diffie-Hellman], AES and SHA. It also removes NULL authentication methods and ciphers; and removes medium-security, low-security and export-grade security ciphers, such as 40-bit RC2. If desired, you could set the options on the context with <tt>SSL_CTX_set_cipher_list</tt>.

'''<tt>SSL_set_tlsext_host_name</tt>''' uses the TLS SNI extension to set the hostname. If you are connecting to a Server Name Indication-aware server (such as Apache with name-based virtual hosts or IIS 8.0), then you will receive the proper certificate during the handshake.

== Cipher Suites ==

[[File:cipher-suites.png|thumb|right|Wireshark and ClientHello]] According to <tt>openssl ciphers ALL</tt>, there are just over 110 cipher suites available. Each cipher suite takes 2 bytes in the <tt>ClientHello</tt>, so advertising every cipher suite available at the client is going to cause a big <tt>ClientHello</tt> (or bigger then needed to get the job done). When using <tt>SSL_CTX_set_cipher_list</tt> or <tt>SSL_set_cipher_list</tt> with the string <tt>"HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4"</tt>, you'll cut the number of cipher suites down to about 45. If you know the server '''does not''' support DSA, then you can add <tt>"!DSS"</tt> and reduce the list further by about 7. And removing RSA key transport (<tt>"!kRSA"</tt>) removes another 9 more (this is a good practice because it uses ephemeral key exchanges which provide forward secrecy). Advertising 35 or so ciphers saves about 160 bytes in the <tt>ClientHello</tt>.

Better, pick 16 or 20 ciphers you want to support and advertise them. Order them so the GCM mode ciphers from TLS 1.2 are listed first, and the AES-SHA ciphers from TLS 1.0 are listed last. Though TLS 1.0 should be avoided, its probably needed for interop because only about [https://www.trustworthyinternet.org/ssl-pulse/ half the servers on the internet support TLS 1.2]. If you control the server, then it should be offering TLS 1.2 and clients only need to advertise AEAD ciphers like AES/GCM or Camellia/GCM.

Keeping the <tt>ClientHello</tt> small is important for older F5 and IronPort devices. Apparently, the devices used fixed sized buffers and choke on large <tt>ClientHello</tt>'s. In fact, a "large hello" was the cause of the TLS padding bug on IronPort devices. See [http://www.ietf.org/mail-archive/web/tls/current/msg12145.html TLS padding breaks ironport] on the TLS mailing list for details.

== Connection ==

[[File:bio-fetch-3.png|thumb|right|Wireshark and TLS versions]] After setting the connection object options, the sample connects to the site and negotiates a secure channel.

* <tt>BIO_do_connect</tt>
* <tt>BIO_do_handshake</tt>

'''<tt>BIO_do_connect</tt>''' performs the name lookup for the host and standard TCP/IP three way handshake.

'''<tt>BIO_do_handshake</tt>''' performs the SSL/TLS handshake. If you set a callback with <tt>SSL_CTX_set_verify</tt> or <tt>SSL_set_verify</tt>, then you callback will be invoked for each certificate in the chain used during the execution of the protocol.

The Wireshark packet capture to the right shows the TLS handshake with the SNI extension encountered during the execution of <tt>BIO_do_handshake</tt>. OpenSSL 1.0.1e advertises TLSv1.2 as the highest protocol level in its <tt>ClientHello</tt>.

== Callback ==

OpenSSL provides the ability for an application to interact with the chain validation by way of a callback. Normally, most application don't need to use it since the default OpenSSL behavior is usually adequate. In the callback, you can pass the <tt>preverify</tt> result back to the library (leaving library behavior unchanged), or you can modify the result to account for a specific issue that your software should address (override default behavior). If you don't need to interact with chain validation, then don't set the callback.

The example program returned the <tt>preverify</tt> result to the library and just printed information about the certificate in the chain. It did so by using <tt>SSL_CTX_set_verify</tt> with <tt>SSL_VERIFY_PEER</tt> and the <tt>verify_callback</tt>.

<pre>int verify_callback(int preverify, X509_STORE_CTX* x509_ctx)
{
int depth = X509_STORE_CTX_get_error_depth(x509_ctx);
int err = X509_STORE_CTX_get_error(x509_ctx);

X509* cert = X509_STORE_CTX_get_current_cert(x509_ctx);
X509_NAME* iname = cert ? X509_get_issuer_name(cert) : NULL;
X509_NAME* sname = cert ? X509_get_subject_name(cert) : NULL;

print_cn_name("Issuer (cn)", iname);
print_cn_name("Subject (cn)", sname);

if(depth == 0) {
/* If depth is 0, its the server's certificate. Print the SANs too */
print_san_name("Subject (san)", cert);
}

return preverify;
}</pre>

The OpenSSL library will pass in the value of its preliminary checking of the certificate through <tt>preverify</tt>. '''If''' you always return <tt>1</tt> regardless of the value of <tt>preverify</tt> or the actual result of your processing, then <tt>SSL_get_verify_result</tt> will always return <tt>X509_V_OK</tt>. That's probably a bad idea for production software.

If you don't need to perform special processing on the chain, then you should forgo the <tt>verify_callback</tt> altogether by supplying <tt>NULL</tt> to <tt>SSL_CTX_set_verify</tt>:

<pre>SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL);</pre>

== Verification ==

You use one of two verification procedures, depending on the version of OpenSSL you are using. The change occurs at OpenSSL 1.1.0 because 1.1.0 (and above) implements hostname verification that 1.0.2 (and below) lacked. Painting with a broad brush, minimal checking includes: (1) confirm the server has a certificate, (2) confirm the certificate chain verifies back to a trusted root, and (3) confirm the name of the host matches a hostname listed in the server's certificate.

In the end, its probably better to ignore PKI and just use Public Key Pinning (or Certificate Pinning) when a pre-exisiting relationship exists; or use a Perspectives-like system or a Trust-On-First-Use (TOFU) system when there's no ''a priori'' relationship (similar to SSH's <tt>StrictHostkeyChecking</tt> option). See Peter Gutmann's [https://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security] for details of a security diversification strategy (Chapter 4, starting on page 292).

You usually don't perform revocation in real time because it essentially creates a denial of service on your application. That is, your app will hang while downloading a multi-megabyte CRL or contacts a missing OCSP responder. For a detailed treatment of problems with PKI and Revocation, see Peter Gutmann's [https://www.cs.auckland.ac.nz/~pgut001/pubs/book.pdf Engineering Security] (Chapters 1 and 8).

=== OpenSSL 1.0.2 ===

OpenSSL 1.0.2 and below requires at least three checks. These versions of OpenSSL do ''not'' perform hostname validation and the API user must perform it.

==== Server Certificate ====

You must confirm the server provided a certificate. This is because a server might be misconfigured, or the client and server used Anonymous Diffie-Hellman. You do so as follows:

<pre>X509* cert = SSL_get_peer_certificate(ssl);
if(cert) { X509_free(cert); }
if(NULL == cert) handleFailure();</pre>

If the server has a certificate, then <tt>SSL_get_peer_certificate</tt> will return a non-NULL value. You don't really need the certificate, so its <tt>free</tt>'d immediately.

==== Certificate Chain ====

You must confirm the server's certificate chains back to a trusted root, and all the certificates in the chain are valid. You do so as follows:

<pre>long res = SSL_get_verify_result(ssl);
if(!(X509_V_OK == res)) handleFailure();</pre>

<tt>SSL_get_verify_result</tt> returns the result of verifying the chain. See the earlier warning on doing the wrong thing in the verification callback.

==== Certificate Names ====

You must confirm a match between the hostname you contacted and the hostnames listed in the certificate. OpenSSL prior to 1.1.0 does not perform hostname verification, so you will have to perform the checking yourself. The sample code does not offer code at the moment, so you will need to borrow it or implement it.

If you want to borrow the code, take a look at [http://curl.haxx.se/libcurl/ libcurl] and the verification procedure in source file <tt>ssluse.c</tt>. Another source is the C/C++ Secure Coding Guide and Section 10.8, [http://etutorials.org/Programming/secure+programming/Chapter+10.+Public+Key+Infrastructure/10.8+Adding+Hostname+Checking+to+Certificate+Verification/ Adding Hostname Checking to Certificate Verification]. If you implement the code for checking, the sample code shows you how to extract the Common Name (CN) and Subject Alternate Names (SAN) from the certificate in <tt>print_cn_name</tt> and <tt>print_san_name</tt>.

'''Note''': matching between the hostname (used in <tt>BIO_do_connect </tt>) and names in the certificate (from <tt>SSL_get_peer_certificate</tt>) must also be validated. For example, a certificate cannot claim to be wildcarded for <tt>*.com</tt>, <tt>*.net</tt>, or other Top Level Domains (TLDs). In addition to the TLDs, you also have to country level or ccTLDs, so it can't match <tt>*.us</tt>, <tt>*.cn</tt>, <tt>*.fed.us</tt>, <tt>*.公司.cn</tt> or similar levels either. Mozilla maintains a list of ccTLDs that are off limits at the [http://publicsuffix.org/ Public Suffix List], and there are currently 6136 entries on the list.

== Program Output ==

After all this musing, here's the lousy output you get when running the program:

{| align="center"
| [[File:bio-fetch-1.png|350px|Figure 1: Chain Output]]
|    
| [[File:bio-fetch-2.png|350px|Figure 2: Server Response]]
|}

== Session Reuse ==

According to Viktor Dukhovni at [http://mta.openssl.org/pipermail/openssl-users/2016-September/004564.html Possible to control session reuse from the client]:

<pre>> For performance testing purposes, I would like to turn off session
> reuse in the (homegrown) client I use for testing. Is there a function
> in the openssl library to do it?
>
> I tried googling for "openssl client don't send session id" but I didn't
> find anything useful.

Just do nothing. Client sessions are not reused unless you explicitly
arrange for reuse of a session by calling SSL_set_session() before
SSL_connect(). If you're trying to avoid wasting memory on storing
client-side sessions that you'll never reuse then this may help:

SSL_CTX_set_session_cache_mode(client_ctx, SSL_SESS_CACHE_OFF);

but note this is also the default state, so is also not needed unless
some other code has explicitly enabled client-side caching of sessions.

Only the server-side cache is enabled by default.</pre>

== Session Tickets ==

Session tickets are specified in [http://www.ietf.org/rfc/rfc5077.txt RFC 5077]. You can disable session tickets with <tt>SSL_OP_NO_TICKET</tt>:

<pre>const long flags = SSL_OP_NO_SSLv3 | ... | SSL_OP_NO_TICKET;
SSL_CTX_set_options(ctx, flags);</pre>

== 0-RTT ==

0-RTT is specified in XXX (TODO). 0-RTT allows an application to immediately resume a previous session at the expense of consuming unauthenticated data. You should avoid 0-RTT if possible. In fact, an organization's data security policy may not allow it for some higher data sensitivity levels.

Care should be taken if enabling 0-RTT at the client because a number of protections must be enabled at the server. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg15594.html 0-RTT and Anti-Replay] and [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.

* 0-RTT without stateful anti-replay allows for very high number of replays, breaking rate limiting systems, even high-performance ones, resulting in an opening for DDoS attacks.

* 0-RTT without stateful anti-replay allows for very high number of replays, allowing exploiting timing side channels for information leakage. Very few if any applications are engineered to mitigate or eliminate such side channels.

* 0-RTT without global anti-replay allows leaking information from the 0-RTT data via cache timing attacks. HTTP GET URLs sent to CDNs are especially vulnerable.

* 0-RTT without global anti-replay allows non-idempotent actions contained in 0-RTT data to be repeated potentially lots of times. Abuse of HTTP GET for non-idempotent actions is fairly common.

* 0-RTT allows easily reordering request with re-transmission from the client. This can lead to various unexpected application behavior if possibility of such reordering is not taken into account. "Eventually consistent" datastores are especially vulnerable.

* 0-RTT exporters are not safe for authentication unless the server does global anti-replay on 0-RTT.

== Downloads ==

[[Media:openssl-bio-fetch.tar.gz|openssl-bio-fetch.tar.gz]] - The program and Makefile used for this wiki page.

Talk:Simple TLS Client

2022-04-24T18:50:51Z

Jwalton: Created page with "This page should probably redirect to SSL/TLS Client. If you want to direct people to OpenSSL's demo code, then mention it on the SSL/TLS Client page. ~~~~"

This page should probably redirect to [[SSL/TLS Client]].

If you want to direct people to OpenSSL's demo code, then mention it on the SSL/TLS Client page.

[[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 18:50, 24 April 2022 (UTC)

EVP Message Digests

2022-01-12T01:51:21Z

Jwalton: Add info on EVP_MD_CTX_create and EVP_MD_CTX_destroy from OpenSSL 1.0.2.

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

A Message Digest or Hash Function takes any arbitrary message (with any content or length) as an input and provides a fixed size hash value as a result. Specifically the function exhibits the following properties:
* It is simple to create a hash value for any given message
* It is computationally infeasible to calculate a message from any given hash (i.e. the function is one-way)
* It is infeasible to modify a message without also modifying the hash value
* It is infeasible to find two messages that result in the same hash

The OpenSSL library supports a wide number of different hash functions including the popular [[:Category:SHA-2]] set of hash functions (i.e. [[SHA-224]], [[SHA-256]], [[SHA-384]] and [[SHA-512]]).

==An Example use of a Hash Function==

Using an OpenSSL message digest/hash function, consists of the following steps:
* Create a Message Digest context
* Initialise the context by identifying the algorithm to be used (built-in algorithms are defined in <code>evp.h</code>)
* Provide the message whose digest needs to be calculated. Messages can be divided into sections and provided over a number of calls to the library if necessary
* Caclulate the digest
* Clean up the context if no longer required

Message digest algorithms are identified using an EVP_MD object. These are built-in to the library and obtained through appropriate library calls (e.g. such as EVP_sha256() or EVP_sha512()).

<pre>
void digest_message(const unsigned char *message, size_t message_len, unsigned char **digest, unsigned int *digest_len)
{
EVP_MD_CTX *mdctx;

if((mdctx = EVP_MD_CTX_new()) == NULL)
handleErrors();

if(1 != EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL))
handleErrors();

if(1 != EVP_DigestUpdate(mdctx, message, message_len))
handleErrors();

if((*digest = (unsigned char *)OPENSSL_malloc(EVP_MD_size(EVP_sha256()))) == NULL)
handleErrors();

if(1 != EVP_DigestFinal_ex(mdctx, *digest, digest_len))
handleErrors();

EVP_MD_CTX_free(mdctx);
}
</pre>

If you need to support both OpenSSL 1.0.x and OpenSSL 1.1.x, then use a <tt>define</tt> for <tt>EVP_MD_CTX_new</tt> and <tt>EVP_MD_CTX_free</tt> as shown below.

<pre>#if OPENSSL_VERSION_NUMBER < 0x10100000L
# define EVP_MD_CTX_new EVP_MD_CTX_create
# define EVP_MD_CTX_free EVP_MD_CTX_destroy
#endif
</pre>

Refer to the OpenSSL manual page for further details [[Manual:EVP_DigestInit(3)]]

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

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

Diffie-Hellman parameters

2021-05-12T20:55:39Z

Jwalton: Spelling.

TLS key agreement algorithms use [[Diffie Hellman|Diffie-Hellman]] groups and provide [http://blog.ivanristic.com/2013/06/ssl-labs-deploying-forward-secrecy.html perfect forward secrecy] (PFS). To use Diffie-Hellman groups and cipher suites with perfect forward secrecy, you must set up Diffie-Hellman parameters [http://www.mail-archive.com/openssl-users@openssl.org/msg71878.html at the server] or the PFS cipher suites will be silently ignored.

Your Diffie-Hellman group parameters should match the key size used in the server's certificate. If you use a 2048-bit RSA prime in the server's certificate, then use a 2048-bit Diffie-Hellman group for key agreement.

Due to [https://weakdh.org/ Logjam vulnerabilities] you should use a group with 2048-bits or higher.

== Diffie-Hellman ==

<code>SSL_CTX_set_tmp_dh</code> is used to set the Diffie-Hellman parameters for a context. One of the easiest ways to get Diffie-Hellman parameters to use with this function is to generate random Diffie-Hellman parameters with the [https://www.openssl.org/docs/apps/dhparam.html dhparam] command-line program with the <code>-C</code> option, and embed the resulting code fragment in your program. For example, <code>openssl dhparam -C 2236</code> might result in:

<pre>
#ifndef HEADER_DH_H
#include <openssl/dh.h>
#endif
DH *get_dh2236()
{
static unsigned char dh2236_p[]={
0x0F,0x52,0xE5,0x24,0xF5,0xFA,0x9D,0xDC,0xC6,0xAB,0xE6,0x04,
0xE4,0x20,0x89,0x8A,0xB4,0xBF,0x27,0xB5,0x4A,0x95,0x57,0xA1,
0x06,0xE7,0x30,0x73,0x83,0x5E,0xC9,0x23,0x11,0xED,0x42,0x45,
0xAC,0x49,0xD3,0xE3,0xF3,0x34,0x73,0xC5,0x7D,0x00,0x3C,0x86,
0x63,0x74,0xE0,0x75,0x97,0x84,0x1D,0x0B,0x11,0xDA,0x04,0xD0,
0xFE,0x4F,0xB0,0x37,0xDF,0x57,0x22,0x2E,0x96,0x42,0xE0,0x7C,
0xD7,0x5E,0x46,0x29,0xAF,0xB1,0xF4,0x81,0xAF,0xFC,0x9A,0xEF,
0xFA,0x89,0x9E,0x0A,0xFB,0x16,0xE3,0x8F,0x01,0xA2,0xC8,0xDD,
0xB4,0x47,0x12,0xF8,0x29,0x09,0x13,0x6E,0x9D,0xA8,0xF9,0x5D,
0x08,0x00,0x3A,0x8C,0xA7,0xFF,0x6C,0xCF,0xE3,0x7C,0x3B,0x6B,
0xB4,0x26,0xCC,0xDA,0x89,0x93,0x01,0x73,0xA8,0x55,0x3E,0x5B,
0x77,0x25,0x8F,0x27,0xA3,0xF1,0xBF,0x7A,0x73,0x1F,0x85,0x96,
0x0C,0x45,0x14,0xC1,0x06,0xB7,0x1C,0x75,0xAA,0x10,0xBC,0x86,
0x98,0x75,0x44,0x70,0xD1,0x0F,0x20,0xF4,0xAC,0x4C,0xB3,0x88,
0x16,0x1C,0x7E,0xA3,0x27,0xE4,0xAD,0xE1,0xA1,0x85,0x4F,0x1A,
0x22,0x0D,0x05,0x42,0x73,0x69,0x45,0xC9,0x2F,0xF7,0xC2,0x48,
0xE3,0xCE,0x9D,0x74,0x58,0x53,0xE7,0xA7,0x82,0x18,0xD9,0x3D,
0xAF,0xAB,0x40,0x9F,0xAA,0x4C,0x78,0x0A,0xC3,0x24,0x2D,0xDB,
0x12,0xA9,0x54,0xE5,0x47,0x87,0xAC,0x52,0xFE,0xE8,0x3D,0x0B,
0x56,0xED,0x9C,0x9F,0xFF,0x39,0xE5,0xE5,0xBF,0x62,0x32,0x42,
0x08,0xAE,0x6A,0xED,0x88,0x0E,0xB3,0x1A,0x4C,0xD3,0x08,0xE4,
0xC4,0xAA,0x2C,0xCC,0xB1,0x37,0xA5,0xC1,0xA9,0x64,0x7E,0xEB,
0xF9,0xD3,0xF5,0x15,0x28,0xFE,0x2E,0xE2,0x7F,0xFE,0xD9,0xB9,
0x38,0x42,0x57,0x03,
};
static unsigned char dh2236_g[]={
0x02,
};
DH *dh;

if ((dh=DH_new()) == NULL) return(NULL);
dh->p=BN_bin2bn(dh2236_p,sizeof(dh2236_p),NULL);
dh->g=BN_bin2bn(dh2236_g,sizeof(dh2236_g),NULL);
if ((dh->p == NULL) || (dh->g == NULL))
{ DH_free(dh); return(NULL); }
return(dh);
}
</pre>

which can then be used like this:

<pre>
DH *dh = get_dh2236 ();
if (1 != SSL_CTX_set_tmp_dh (ctx, dh))
error ();
DH_free (dh);
</pre>

Be sure to choose a bit length [http://www.keylength.com/en/3/ appropriate to the security level you want to achieve], although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be [https://bugzilla.mozilla.org/show_bug.cgi?id=636802 incompatible with older versions of NSS]. Even worse, it appears that [http://stackoverflow.com/questions/6851461/java-why-does-ssl-handshake-give-could-not-generate-dh-keypair-exception versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits]!

== Validating Parameters ==

The Diffie-Hellman parameters should be validated after loading. To perform paramter validation, you call <tt>DH_check</tt>. <tt>DH_check</tt> returns 0 or a bitmask values of the following:

* <tt>DH_CHECK_P_NOT_PRIME</tt> (0x01)
* <tt>DH_CHECK_P_NOT_SAFE_PRIME</tt> (0x02)
* <tt>DH_UNABLE_TO_CHECK_GENERATOR</tt> (0x04)
* <tt>DH_NOT_SUITABLE_GENERATOR</tt> (0x08)

The validation code might look as follows (error checking omitted for clarity):

<pre>BIO* bio = ...;
DH* dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL);

int rc, codes = 0;
rc = DH_check(dh, &codes);
assert(rc == 1);

if(BN_is_word(dh->g, DH_GENERATOR_2))
{
long residue = BN_mod_word(dh->p, 24);
if(residue == 11 || residue == 23) {
codes &= ~DH_NOT_SUITABLE_GENERATOR;
}
}

if (codes & DH_UNABLE_TO_CHECK_GENERATOR)
printf("DH_check: failed to test generator\n");

if (codes & DH_NOT_SUITABLE_GENERATOR)
printf("DH_check: g is not a suitable generator\n");

if (codes & DH_CHECK_P_NOT_PRIME)
printf("DH_check: p is not prime\n");

if (codes & DH_CHECK_P_NOT_SAFE_PRIME)
printf("DH_check: p is not a safe prime\n");</pre>

The additional call to <tt>BN_mod_word(dh->p, 24)</tt> (and unmasking of <tt>DH_NOT_SUITABLE_GENERATOR</tt>) is performed to ensure your program accepts IETF group parameters. OpenSSL checks the prime is congruent to 11 when <tt>g = 2</tt>; while the IETF's primes are congruent to 23 when <tt>g = 2</tt>. Without the test, the IETF parameters would fail validation. For details, see [http://crypto.stackexchange.com/questions/12961/diffie-hellman-parameter-check-when-g-2-must-p-mod-24-11 Diffie-Hellman Parameter Check (when g = 2, must p mod 24 == 11?)].

== Elliptic curve Diffie-Hellman ==

For [[Elliptic Curve Diffie Hellman|elliptic curve Diffie-Hellman]], you can do something like this:

<pre>
EC_KEY *ecdh = EC_KEY_new_by_curve_name (NID_X9_62_prime256v1);
if (! ecdh)
error ();
if (1 != SSL_CTX_set_tmp_ecdh (ctx, ecdh))
error ();
EC_KEY_free (ecdh);
</pre>

Or, in OpenSSL 1.0.2 (not yet released, as of Feb 2013) and higher, you should be able to do:

<pre>
SSL_CTX_set_ecdh_auto (ctx, 1)
</pre>

For more information, see [[Elliptic Curve Diffie Hellman]] and [[Elliptic Curve Cryptography]].

== Diffie-Hellman Groups ==

Ephemeral Diffie-Hellman key agreement needs to happen over a group. The client and server will each pick a random value in the group and perform key agreement with the random parameters. For each run of the protocol, the random parameters will change but the group will remain the same. When you need a group you can either calculate one; or you can use a standard group published by a standards body like the IETF.

Calculating a group is an expensive operation because the safe primes used for the group are harder to find. As the group size gets larger it takes more time to find them. A 3072-bit group can take minutes to find, and a 8192-bit group can take hours to find in the worst case.

To avoid the runtime costs associated with finding a group, you typically you use a standard group, like those published in RFC 3526 or RFC 7919. The declarations for the IETF groups are provided below.

=== RFC 3526 Groups ===

Below are five Diffie-Hellman MODP groups specified in [http://tools.ietf.org/html/rfc3526 RFC 3526, More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE)] (the 1024-bit parameter is from RFC 2409). They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>. RFC 3526 also offers 1536-bit, 6144-bit and 8192-bit primes.

<pre>static const char g_dh1024_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh1536_sz[] = "-----BEGIN DH PARAMETERS-----\n"
"MIHHAoHBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7ORbPcIAfLihY78FmNpINhxV05pp\n"
"Fj+o/STPX4NlXSPco62WHGLzViCFUrue1SkHcJaWbWcMNU5KvJgE8XRsCMojcyf/\n"
"/////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqTrS\n"
"yv//////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqSEI\n"
"ARpyPBKnh+bXiHGaEL26WyaZwycYavTiPBqUaDS2FQvaJYPpyirUTOjbu8LbBN6O\n"
"+S6O/BQfvsqmKHxZR05rwF2ZspZPoJDDoiM7oYZRW+ftH2EpcM7i16+4G912IXBI\n"
"HNAGkSfVsFqpk7TqmI2P3cGG/7fckKbAj030Nck0BjGZ//////////8CAQI=\n"
"-----END DH PARAMETERS-----\n";</pre>

=== RFC 7919 Groups ===

Below are three additional Diffie-Hellman groups specified in [http://tools.ietf.org/html/rfc3526 RFC 7919, Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)]. They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>.

<pre>static const char g_ffdhe2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEoXJf//////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_ffdhe3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3\n"
"7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32\n"
"nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZsYu\n"
"N///////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_ffdhe4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3\n"
"7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32\n"
"nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZp4e\n"
"8W5vUsMWTfT7eTDp5OWIV7asfV9C1p9tGHdjzx1VA0AEh/VbpX4xzHpxNciG77Qx\n"
"iu1qHgEtnmgyqQdgCpGBMMRtx3j5ca0AOAkpmaMzy4t6Gh25PXFAADwqTs6p+Y0K\n"
"zAqCkc3OyX3Pjsm1Wn+IpGtNtahR9EGC4caKAH5eZV9q//////////8CAQI=\n"
"-----END DH PARAMETERS-----\n";</pre>

[[Category:Examples]]

Diffie-Hellman parameters

2021-05-12T19:28:18Z

Jwalton: Rework introduction.

TLS key agreement algorithms use [[Diffie Hellman|Diffie-Hellman]] groups and provide [http://blog.ivanristic.com/2013/06/ssl-labs-deploying-forward-secrecy.html perfect forward secrecy] (PFS). To use Diffie-Hellman groups and cipher suites with perfect forward secrecy, you must set up Diffie-Hellman parameters [http://www.mail-archive.com/openssl-users@openssl.org/msg71878.html at the server] or the PFS cipher suites will be silently ignored.

Your Diffie-Hellman group parameters should match the key size used in the server's certificate. If you use a 2048-bit RSA prime in the server's certificate, then use a 2048-bit Dhiifie-Hellman group for key agreement.

Due to [https://weakdh.org/ Logjam vulnerabilities] you should use a group with 2048-bits or higher.

== Diffie-Hellman ==

<code>SSL_CTX_set_tmp_dh</code> is used to set the Diffie-Hellman parameters for a context. One of the easiest ways to get Diffie-Hellman parameters to use with this function is to generate random Diffie-Hellman parameters with the [https://www.openssl.org/docs/apps/dhparam.html dhparam] command-line program with the <code>-C</code> option, and embed the resulting code fragment in your program. For example, <code>openssl dhparam -C 2236</code> might result in:

<pre>
#ifndef HEADER_DH_H
#include <openssl/dh.h>
#endif
DH *get_dh2236()
{
static unsigned char dh2236_p[]={
0x0F,0x52,0xE5,0x24,0xF5,0xFA,0x9D,0xDC,0xC6,0xAB,0xE6,0x04,
0xE4,0x20,0x89,0x8A,0xB4,0xBF,0x27,0xB5,0x4A,0x95,0x57,0xA1,
0x06,0xE7,0x30,0x73,0x83,0x5E,0xC9,0x23,0x11,0xED,0x42,0x45,
0xAC,0x49,0xD3,0xE3,0xF3,0x34,0x73,0xC5,0x7D,0x00,0x3C,0x86,
0x63,0x74,0xE0,0x75,0x97,0x84,0x1D,0x0B,0x11,0xDA,0x04,0xD0,
0xFE,0x4F,0xB0,0x37,0xDF,0x57,0x22,0x2E,0x96,0x42,0xE0,0x7C,
0xD7,0x5E,0x46,0x29,0xAF,0xB1,0xF4,0x81,0xAF,0xFC,0x9A,0xEF,
0xFA,0x89,0x9E,0x0A,0xFB,0x16,0xE3,0x8F,0x01,0xA2,0xC8,0xDD,
0xB4,0x47,0x12,0xF8,0x29,0x09,0x13,0x6E,0x9D,0xA8,0xF9,0x5D,
0x08,0x00,0x3A,0x8C,0xA7,0xFF,0x6C,0xCF,0xE3,0x7C,0x3B,0x6B,
0xB4,0x26,0xCC,0xDA,0x89,0x93,0x01,0x73,0xA8,0x55,0x3E,0x5B,
0x77,0x25,0x8F,0x27,0xA3,0xF1,0xBF,0x7A,0x73,0x1F,0x85,0x96,
0x0C,0x45,0x14,0xC1,0x06,0xB7,0x1C,0x75,0xAA,0x10,0xBC,0x86,
0x98,0x75,0x44,0x70,0xD1,0x0F,0x20,0xF4,0xAC,0x4C,0xB3,0x88,
0x16,0x1C,0x7E,0xA3,0x27,0xE4,0xAD,0xE1,0xA1,0x85,0x4F,0x1A,
0x22,0x0D,0x05,0x42,0x73,0x69,0x45,0xC9,0x2F,0xF7,0xC2,0x48,
0xE3,0xCE,0x9D,0x74,0x58,0x53,0xE7,0xA7,0x82,0x18,0xD9,0x3D,
0xAF,0xAB,0x40,0x9F,0xAA,0x4C,0x78,0x0A,0xC3,0x24,0x2D,0xDB,
0x12,0xA9,0x54,0xE5,0x47,0x87,0xAC,0x52,0xFE,0xE8,0x3D,0x0B,
0x56,0xED,0x9C,0x9F,0xFF,0x39,0xE5,0xE5,0xBF,0x62,0x32,0x42,
0x08,0xAE,0x6A,0xED,0x88,0x0E,0xB3,0x1A,0x4C,0xD3,0x08,0xE4,
0xC4,0xAA,0x2C,0xCC,0xB1,0x37,0xA5,0xC1,0xA9,0x64,0x7E,0xEB,
0xF9,0xD3,0xF5,0x15,0x28,0xFE,0x2E,0xE2,0x7F,0xFE,0xD9,0xB9,
0x38,0x42,0x57,0x03,
};
static unsigned char dh2236_g[]={
0x02,
};
DH *dh;

if ((dh=DH_new()) == NULL) return(NULL);
dh->p=BN_bin2bn(dh2236_p,sizeof(dh2236_p),NULL);
dh->g=BN_bin2bn(dh2236_g,sizeof(dh2236_g),NULL);
if ((dh->p == NULL) || (dh->g == NULL))
{ DH_free(dh); return(NULL); }
return(dh);
}
</pre>

which can then be used like this:

<pre>
DH *dh = get_dh2236 ();
if (1 != SSL_CTX_set_tmp_dh (ctx, dh))
error ();
DH_free (dh);
</pre>

Be sure to choose a bit length [http://www.keylength.com/en/3/ appropriate to the security level you want to achieve], although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be [https://bugzilla.mozilla.org/show_bug.cgi?id=636802 incompatible with older versions of NSS]. Even worse, it appears that [http://stackoverflow.com/questions/6851461/java-why-does-ssl-handshake-give-could-not-generate-dh-keypair-exception versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits]!

== Validating Parameters ==

The Diffie-Hellman parameters should be validated after loading. To perform paramter validation, you call <tt>DH_check</tt>. <tt>DH_check</tt> returns 0 or a bitmask values of the following:

* <tt>DH_CHECK_P_NOT_PRIME</tt> (0x01)
* <tt>DH_CHECK_P_NOT_SAFE_PRIME</tt> (0x02)
* <tt>DH_UNABLE_TO_CHECK_GENERATOR</tt> (0x04)
* <tt>DH_NOT_SUITABLE_GENERATOR</tt> (0x08)

The validation code might look as follows (error checking omitted for clarity):

<pre>BIO* bio = ...;
DH* dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL);

int rc, codes = 0;
rc = DH_check(dh, &codes);
assert(rc == 1);

if(BN_is_word(dh->g, DH_GENERATOR_2))
{
long residue = BN_mod_word(dh->p, 24);
if(residue == 11 || residue == 23) {
codes &= ~DH_NOT_SUITABLE_GENERATOR;
}
}

if (codes & DH_UNABLE_TO_CHECK_GENERATOR)
printf("DH_check: failed to test generator\n");

if (codes & DH_NOT_SUITABLE_GENERATOR)
printf("DH_check: g is not a suitable generator\n");

if (codes & DH_CHECK_P_NOT_PRIME)
printf("DH_check: p is not prime\n");

if (codes & DH_CHECK_P_NOT_SAFE_PRIME)
printf("DH_check: p is not a safe prime\n");</pre>

The additional call to <tt>BN_mod_word(dh->p, 24)</tt> (and unmasking of <tt>DH_NOT_SUITABLE_GENERATOR</tt>) is performed to ensure your program accepts IETF group parameters. OpenSSL checks the prime is congruent to 11 when <tt>g = 2</tt>; while the IETF's primes are congruent to 23 when <tt>g = 2</tt>. Without the test, the IETF parameters would fail validation. For details, see [http://crypto.stackexchange.com/questions/12961/diffie-hellman-parameter-check-when-g-2-must-p-mod-24-11 Diffie-Hellman Parameter Check (when g = 2, must p mod 24 == 11?)].

== Elliptic curve Diffie-Hellman ==

For [[Elliptic Curve Diffie Hellman|elliptic curve Diffie-Hellman]], you can do something like this:

<pre>
EC_KEY *ecdh = EC_KEY_new_by_curve_name (NID_X9_62_prime256v1);
if (! ecdh)
error ();
if (1 != SSL_CTX_set_tmp_ecdh (ctx, ecdh))
error ();
EC_KEY_free (ecdh);
</pre>

Or, in OpenSSL 1.0.2 (not yet released, as of Feb 2013) and higher, you should be able to do:

<pre>
SSL_CTX_set_ecdh_auto (ctx, 1)
</pre>

For more information, see [[Elliptic Curve Diffie Hellman]] and [[Elliptic Curve Cryptography]].

== Diffie-Hellman Groups ==

Ephemeral Diffie-Hellman key agreement needs to happen over a group. The client and server will each pick a random value in the group and perform key agreement with the random parameters. For each run of the protocol, the random parameters will change but the group will remain the same. When you need a group you can either calculate one; or you can use a standard group published by a standards body like the IETF.

Calculating a group is an expensive operation because the safe primes used for the group are harder to find. As the group size gets larger it takes more time to find them. A 3072-bit group can take minutes to find, and a 8192-bit group can take hours to find in the worst case.

To avoid the runtime costs associated with finding a group, you typically you use a standard group, like those published in RFC 3526 or RFC 7919. The declarations for the IETF groups are provided below.

=== RFC 3526 Groups ===

Below are five Diffie-Hellman MODP groups specified in [http://tools.ietf.org/html/rfc3526 RFC 3526, More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE)] (the 1024-bit parameter is from RFC 2409). They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>. RFC 3526 also offers 1536-bit, 6144-bit and 8192-bit primes.

<pre>static const char g_dh1024_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh1536_sz[] = "-----BEGIN DH PARAMETERS-----\n"
"MIHHAoHBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7ORbPcIAfLihY78FmNpINhxV05pp\n"
"Fj+o/STPX4NlXSPco62WHGLzViCFUrue1SkHcJaWbWcMNU5KvJgE8XRsCMojcyf/\n"
"/////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqTrS\n"
"yv//////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqSEI\n"
"ARpyPBKnh+bXiHGaEL26WyaZwycYavTiPBqUaDS2FQvaJYPpyirUTOjbu8LbBN6O\n"
"+S6O/BQfvsqmKHxZR05rwF2ZspZPoJDDoiM7oYZRW+ftH2EpcM7i16+4G912IXBI\n"
"HNAGkSfVsFqpk7TqmI2P3cGG/7fckKbAj030Nck0BjGZ//////////8CAQI=\n"
"-----END DH PARAMETERS-----\n";</pre>

=== RFC 7919 Groups ===

Below are three additional Diffie-Hellman groups specified in [http://tools.ietf.org/html/rfc3526 RFC 7919, Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)]. They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>.

<pre>static const char g_ffdhe2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEoXJf//////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_ffdhe3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3\n"
"7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32\n"
"nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZsYu\n"
"N///////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_ffdhe4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3\n"
"7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32\n"
"nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZp4e\n"
"8W5vUsMWTfT7eTDp5OWIV7asfV9C1p9tGHdjzx1VA0AEh/VbpX4xzHpxNciG77Qx\n"
"iu1qHgEtnmgyqQdgCpGBMMRtx3j5ca0AOAkpmaMzy4t6Gh25PXFAADwqTs6p+Y0K\n"
"zAqCkc3OyX3Pjsm1Wn+IpGtNtahR9EGC4caKAH5eZV9q//////////8CAQI=\n"
"-----END DH PARAMETERS-----\n";</pre>

[[Category:Examples]]

Diffie-Hellman parameters

2021-05-12T19:21:36Z

Jwalton: Reorganize Diffie-Hellman Groups. Add RFC 7919 group parameters.

To use [http://blog.ivanristic.com/2013/06/ssl-labs-deploying-forward-secrecy.html perfect forward secrecy] cipher suites, you must set up [[Diffie Hellman|Diffie-Hellman]] parameters ([http://www.mail-archive.com/openssl-users@openssl.org/msg71878.html on the server side]), or the PFS cipher suites will be silently ignored.

== Diffie-Hellman ==

<code>SSL_CTX_set_tmp_dh</code> is used to set the Diffie-Hellman parameters for a context. One of the easiest ways to get Diffie-Hellman parameters to use with this function is to generate random Diffie-Hellman parameters with the [https://www.openssl.org/docs/apps/dhparam.html dhparam] command-line program with the <code>-C</code> option, and embed the resulting code fragment in your program. For example, <code>openssl dhparam -C 2236</code> might result in:

<pre>
#ifndef HEADER_DH_H
#include <openssl/dh.h>
#endif
DH *get_dh2236()
{
static unsigned char dh2236_p[]={
0x0F,0x52,0xE5,0x24,0xF5,0xFA,0x9D,0xDC,0xC6,0xAB,0xE6,0x04,
0xE4,0x20,0x89,0x8A,0xB4,0xBF,0x27,0xB5,0x4A,0x95,0x57,0xA1,
0x06,0xE7,0x30,0x73,0x83,0x5E,0xC9,0x23,0x11,0xED,0x42,0x45,
0xAC,0x49,0xD3,0xE3,0xF3,0x34,0x73,0xC5,0x7D,0x00,0x3C,0x86,
0x63,0x74,0xE0,0x75,0x97,0x84,0x1D,0x0B,0x11,0xDA,0x04,0xD0,
0xFE,0x4F,0xB0,0x37,0xDF,0x57,0x22,0x2E,0x96,0x42,0xE0,0x7C,
0xD7,0x5E,0x46,0x29,0xAF,0xB1,0xF4,0x81,0xAF,0xFC,0x9A,0xEF,
0xFA,0x89,0x9E,0x0A,0xFB,0x16,0xE3,0x8F,0x01,0xA2,0xC8,0xDD,
0xB4,0x47,0x12,0xF8,0x29,0x09,0x13,0x6E,0x9D,0xA8,0xF9,0x5D,
0x08,0x00,0x3A,0x8C,0xA7,0xFF,0x6C,0xCF,0xE3,0x7C,0x3B,0x6B,
0xB4,0x26,0xCC,0xDA,0x89,0x93,0x01,0x73,0xA8,0x55,0x3E,0x5B,
0x77,0x25,0x8F,0x27,0xA3,0xF1,0xBF,0x7A,0x73,0x1F,0x85,0x96,
0x0C,0x45,0x14,0xC1,0x06,0xB7,0x1C,0x75,0xAA,0x10,0xBC,0x86,
0x98,0x75,0x44,0x70,0xD1,0x0F,0x20,0xF4,0xAC,0x4C,0xB3,0x88,
0x16,0x1C,0x7E,0xA3,0x27,0xE4,0xAD,0xE1,0xA1,0x85,0x4F,0x1A,
0x22,0x0D,0x05,0x42,0x73,0x69,0x45,0xC9,0x2F,0xF7,0xC2,0x48,
0xE3,0xCE,0x9D,0x74,0x58,0x53,0xE7,0xA7,0x82,0x18,0xD9,0x3D,
0xAF,0xAB,0x40,0x9F,0xAA,0x4C,0x78,0x0A,0xC3,0x24,0x2D,0xDB,
0x12,0xA9,0x54,0xE5,0x47,0x87,0xAC,0x52,0xFE,0xE8,0x3D,0x0B,
0x56,0xED,0x9C,0x9F,0xFF,0x39,0xE5,0xE5,0xBF,0x62,0x32,0x42,
0x08,0xAE,0x6A,0xED,0x88,0x0E,0xB3,0x1A,0x4C,0xD3,0x08,0xE4,
0xC4,0xAA,0x2C,0xCC,0xB1,0x37,0xA5,0xC1,0xA9,0x64,0x7E,0xEB,
0xF9,0xD3,0xF5,0x15,0x28,0xFE,0x2E,0xE2,0x7F,0xFE,0xD9,0xB9,
0x38,0x42,0x57,0x03,
};
static unsigned char dh2236_g[]={
0x02,
};
DH *dh;

if ((dh=DH_new()) == NULL) return(NULL);
dh->p=BN_bin2bn(dh2236_p,sizeof(dh2236_p),NULL);
dh->g=BN_bin2bn(dh2236_g,sizeof(dh2236_g),NULL);
if ((dh->p == NULL) || (dh->g == NULL))
{ DH_free(dh); return(NULL); }
return(dh);
}
</pre>

which can then be used like this:

<pre>
DH *dh = get_dh2236 ();
if (1 != SSL_CTX_set_tmp_dh (ctx, dh))
error ();
DH_free (dh);
</pre>

Be sure to choose a bit length [http://www.keylength.com/en/3/ appropriate to the security level you want to achieve], although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be [https://bugzilla.mozilla.org/show_bug.cgi?id=636802 incompatible with older versions of NSS]. Even worse, it appears that [http://stackoverflow.com/questions/6851461/java-why-does-ssl-handshake-give-could-not-generate-dh-keypair-exception versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits]!

== Validating Parameters ==

The Diffie-Hellman parameters should be validated after loading. To perform paramter validation, you call <tt>DH_check</tt>. <tt>DH_check</tt> returns 0 or a bitmask values of the following:

* <tt>DH_CHECK_P_NOT_PRIME</tt> (0x01)
* <tt>DH_CHECK_P_NOT_SAFE_PRIME</tt> (0x02)
* <tt>DH_UNABLE_TO_CHECK_GENERATOR</tt> (0x04)
* <tt>DH_NOT_SUITABLE_GENERATOR</tt> (0x08)

The validation code might look as follows (error checking omitted for clarity):

<pre>BIO* bio = ...;
DH* dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL);

int rc, codes = 0;
rc = DH_check(dh, &codes);
assert(rc == 1);

if(BN_is_word(dh->g, DH_GENERATOR_2))
{
long residue = BN_mod_word(dh->p, 24);
if(residue == 11 || residue == 23) {
codes &= ~DH_NOT_SUITABLE_GENERATOR;
}
}

if (codes & DH_UNABLE_TO_CHECK_GENERATOR)
printf("DH_check: failed to test generator\n");

if (codes & DH_NOT_SUITABLE_GENERATOR)
printf("DH_check: g is not a suitable generator\n");

if (codes & DH_CHECK_P_NOT_PRIME)
printf("DH_check: p is not prime\n");

if (codes & DH_CHECK_P_NOT_SAFE_PRIME)
printf("DH_check: p is not a safe prime\n");</pre>

The additional call to <tt>BN_mod_word(dh->p, 24)</tt> (and unmasking of <tt>DH_NOT_SUITABLE_GENERATOR</tt>) is performed to ensure your program accepts IETF group parameters. OpenSSL checks the prime is congruent to 11 when <tt>g = 2</tt>; while the IETF's primes are congruent to 23 when <tt>g = 2</tt>. Without the test, the IETF parameters would fail validation. For details, see [http://crypto.stackexchange.com/questions/12961/diffie-hellman-parameter-check-when-g-2-must-p-mod-24-11 Diffie-Hellman Parameter Check (when g = 2, must p mod 24 == 11?)].

== Elliptic curve Diffie-Hellman ==

For [[Elliptic Curve Diffie Hellman|elliptic curve Diffie-Hellman]], you can do something like this:

<pre>
EC_KEY *ecdh = EC_KEY_new_by_curve_name (NID_X9_62_prime256v1);
if (! ecdh)
error ();
if (1 != SSL_CTX_set_tmp_ecdh (ctx, ecdh))
error ();
EC_KEY_free (ecdh);
</pre>

Or, in OpenSSL 1.0.2 (not yet released, as of Feb 2013) and higher, you should be able to do:

<pre>
SSL_CTX_set_ecdh_auto (ctx, 1)
</pre>

For more information, see [[Elliptic Curve Diffie Hellman]] and [[Elliptic Curve Cryptography]].

== Diffie-Hellman Groups ==

Ephemeral Diffie-Hellman key agreement needs to happen over a group. The client and server will each pick a random value in the group and perform key agreement with the random parameters. For each run of the protocol, the random parameters will change but the group will remain the same. When you need a group you can either calculate one; or you can use a standard group published by a standards body like the IETF.

Calculating a group is an expensive operation because the safe primes used for the group are harder to find. As the group size gets larger it takes more time to find them. A 3072-bit group can take minutes to find, and a 8192-bit group can take hours to find in the worst case.

To avoid the runtime costs associated with finding a group, you typically you use a standard group, like those published in RFC 3526 or RFC 7919. The declarations for the IETF groups are provided below.

Due to [https://weakdh.org/ Logjam vulnerabilities] you should use a group with 2048-bits or higher.

== RFC 3526 Groups ==

Below are five Diffie-Hellman MODP groups specified in [http://tools.ietf.org/html/rfc3526 RFC 3526, More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE)] (the 1024-bit parameter is from RFC 2409). They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>. RFC 3526 also offers 1536-bit, 6144-bit and 8192-bit primes.

<pre>static const char g_dh1024_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh1536_sz[] = "-----BEGIN DH PARAMETERS-----\n"
"MIHHAoHBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7ORbPcIAfLihY78FmNpINhxV05pp\n"
"Fj+o/STPX4NlXSPco62WHGLzViCFUrue1SkHcJaWbWcMNU5KvJgE8XRsCMojcyf/\n"
"/////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqTrS\n"
"yv//////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_dh4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqSEI\n"
"ARpyPBKnh+bXiHGaEL26WyaZwycYavTiPBqUaDS2FQvaJYPpyirUTOjbu8LbBN6O\n"
"+S6O/BQfvsqmKHxZR05rwF2ZspZPoJDDoiM7oYZRW+ftH2EpcM7i16+4G912IXBI\n"
"HNAGkSfVsFqpk7TqmI2P3cGG/7fckKbAj030Nck0BjGZ//////////8CAQI=\n"
"-----END DH PARAMETERS-----\n";</pre>

== RFC 7919 Groups ==

Below are three additional Diffie-Hellman groups specified in [http://tools.ietf.org/html/rfc3526 RFC 7919, Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)]. They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>.

<pre>static const char g_ffdhe2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEoXJf//////////wIBAg==\n"
"-----END DH PARAMETERS-----\n";

static const char g_ffdhe3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3\n"
"7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32\n"
"nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZsYu\n"
"N///////////AgEC\n"
"-----END DH PARAMETERS-----\n";

static const char g_ffdhe4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
"+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
"87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
"YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
"7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
"ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3\n"
"7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32\n"
"nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZp4e\n"
"8W5vUsMWTfT7eTDp5OWIV7asfV9C1p9tGHdjzx1VA0AEh/VbpX4xzHpxNciG77Qx\n"
"iu1qHgEtnmgyqQdgCpGBMMRtx3j5ca0AOAkpmaMzy4t6Gh25PXFAADwqTs6p+Y0K\n"
"zAqCkc3OyX3Pjsm1Wn+IpGtNtahR9EGC4caKAH5eZV9q//////////8CAQI=\n"
"-----END DH PARAMETERS-----\n";</pre>

[[Category:Examples]]

Compilation and Installation

2021-03-29T19:19:05Z

Jwalton: /* Using RPATHs */

The following page is a combination of the <tt>INSTALL</tt> file provided with the OpenSSL library and notes from the field. If you have questions about what you are doing or seeing, then you should consult <tt>INSTALL</tt> since it contains the commands and specifies the behavior by the development team.

OpenSSL uses a custom build system to configure the library. Configuration will allow the library to set up the recursive makefiles from <tt>makefile.org</tt>. Once configured, you use <tt>make</tt> to build the library. You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

You must use a C compiler to build the OpenSSL library. You cannot use a C++ compiler. Later, once the library is built, it is OK to create user programs with a C++ compiler. But the library proper must be built with a C compiler.

There are two generations of build system. First is the build system used in OpenSSL 1.0.2 and below. The instructions below apply to it. Second is the build system for OpenSSL 1.1.0 and above. The instructions are similar, but not the same. For example, the second generation abandons the monolithic <tt>Configure</tt> and places individual configurations in the <tt>Configurations</tt> directory. Also, the second generation is more platform agnostic and uses templates to produce a final, top level build file (<tt>Makefile</tt>, <tt>descrip.mms</tt>, what have you).

After you configure and build the library, you should always perform a <tt>make test</tt> to ensure the library performs as expected under its self tests. If you are building OpenSSL 1.1.0 and above, then you will also need PERL 5.10 or higher (see <tt>README.PERL</tt> for details).

OpenSSL's build system does not rely upon <tt>autotools</tt> or <tt>libtool</tt>. Also see [http://www.openssl.org/support/faq.html#MISC5 Why aren't tools like 'autoconf' and 'libtool' used?] in the OpenSSL FAQ.

== Retrieve source code ==

The OpenSSL source code can be downloaded from [http://www.openssl.org/source/ OpenSSL Source Tarballs] or any suitable [http://www.openssl.org/source/mirror.html ftp mirror]. There are various versions including stable as well as unstable versions.

The source code is managed via Git. Its referred to as Master. The repository is

: git://git.openssl.org/openssl.git

The source is also available via a [https://github.com/openssl/openssl GitHub] mirror. This repository is updated every 15 minutes.

* [[Use_of_Git|Accessing OpenSSL source code via Git]]

== Configuration ==

OpenSSL is configured for a particular platform with protocol and behavior options using <tt>Configure</tt> and <tt>config</tt>.

You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

=== Supported Platforms ===

You can run <tt>Configure LIST</tt> to see a list of available platforms.

<pre>$ ./Configure LIST
BC-32
BS2000-OSD
BSD-generic32
BSD-generic64
BSD-ia64
BSD-sparc64
BSD-sparcv8
BSD-x86
BSD-x86-elf
BSD-x86_64
Cygwin
Cygwin-x86_64
DJGPP
...</pre>

If your platform is not listed, then use a similar platform and tune the <tt>$cflags</tt> and <tt>$ldflags</tt> by making a copy of the configure line and giving it its own name. <tt>$cflags</tt> and <tt>$ldflags</tt> correspond to fields 2 and 6 in a configure line. An example of using a similar configure line is presented in [[Compilation_and_Installation#Using_RPATHs|Using RPATHs]].

=== Configure & Config ===

You use <tt>Configure</tt> and <tt>config</tt> to tune the compile and installation process through options and switches. The difference between is <tt>Configure</tt> properly handles the host-arch-compiler triplet, and <tt>config</tt> does not. <tt>config</tt> attempts to guess the triplet, so its a lot like autotool's <tt>config.guess</tt>.

You can usually use <tt>config</tt> and it will do the right thing (from Ubuntu 13.04, x64):

<pre>$ ./config
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring for linux-x86_64
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

Mac OS X can have issues (its often a neglected platform), and you will have to use <tt>Configure</tt>:

<pre> ./Configure darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

You can also configure on Darwin by exporting <tt>KERNEL_BITS</tt>:

<pre>$ export KERNEL_BITS=64
$ ./config shared no-ssl2 no-ssl3 enable-ec_nistp_64_gcc_128 --openssldir=/usr/local/ssl/macosx-x64/
Operating system: i686-apple-darwinDarwin Kernel Version 12.5.0: Sun Sep 29 13:33:47 PDT 2013; root:xnu-2050.48.12~1/RELEASE_X86_64
Configuring for darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

If you provide a option not known to configure or ask for help, then you get a brief help message:

<pre>$ ./Configure --help
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]</pre>

And if you supply an unknown triplet:

<pre>$ ./Configure darwin64-x86_64-clang
Configuring for darwin64-x86_64-clang
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]

pick os/compiler from:
BC-32 BS2000-OSD BSD-generic32 BSD-generic64 BSD-ia64 BSD-sparc64 BSD-sparcv8
BSD-x86 BSD-x86-elf BSD-x86_64 Cygwin Cygwin-pre1.3 DJGPP MPE/iX-gcc OS2-EMX
...

NOTE: If in doubt, on Unix-ish systems use './config'.</pre>

=== Dependencies ===

If you are prompted to run <tt>make depend</tt>, then you must do so. For OpenSSL 1.0.2 and below, its required to update the standard distribution once configuration options change.

<pre>Since you've disabled or enabled at least one algorithm, you need to do
the following before building:

make depend
</pre>

OpenSSL 1.1.0 and above performs the dependency step for you, so you should not see the message. However, you should perform a <tt>make clean</tt> to ensure the list of objects files is accurate after a reconfiguration.

== Configure Options ==

OpenSSL has been around a long time, and it carries around a lot of cruft. For example, from above, SSLv2 is enabled by default. SSLv2 is completely broken, and you should disable it during configuration. You can disable protocols and provide other options through <tt>Configure</tt> and <tt>config</tt>, and the following lists some of them.

'''Note''': if you specify a non-existent option, then the configure scripts will proceed without warning. For example, if you inadvertently specify '''no-sslv2''' rather than '''no-ssl2 no-ssl3''', the script will configure ''with'' SSLv2 and ''without'' warning for the unknown no-sslv2.

'''Note''': when building a shared object, both the static archive and shared objects are built. You do not need to do anything special to build both when '''shared''' is specified.

{| class="wikitable sortable" border="1"
|+ OpenSSL Library Options
|-
! scope="col" width="150px" | Option
! scope="col" class="unsortable" | Description
|-
| --prefix=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| --openssldir=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| -d || Debug build of the library. Optimizations are disabled (no <tt>-O3</tt> or similar) and <tt>libefence</tt> is used (<tt>apt-get install electric-fence</tt> or <tt>yum install electric-fence</tt>). TODO: Any other features?
|-
| shared || Build a shared object in addition to the static archive. You probably need a [[#Using_RPATHs|RPATH]] when enabling <tt>shared</tt> to ensure <tt>openssl</tt> uses the correct <tt>libssl</tt> and <tt>libcrypto</tt> after installation.
|-
| enable-ec_nistp_64_gcc_128 || Use on little endian platforms when GCC supports <tt>__uint128_t</tt>. ECDH is about 2 to 4 times faster. Not enabled by default because <tt>Configure</tt> can't determine it. Enable it if your compiler defines <tt>__SIZEOF_INT128__</tt>, the CPU is little endian and it tolerates unaligned data access.
|-
| enable-capieng || Enables the Microsoft CAPI engine on Windows platforms. Used to access the Windows Certificate Store. Also see [http://openssl.6102.n7.nabble.com/Using-Windows-certificate-store-through-OpenSSL-td46788.html Using Windows certificate store through OpenSSL] on the OpenSSL developer list.
|-
| no-ssl2 || Disables SSLv2. <tt>OPENSSL_NO_SSL2</tt> will be defined in the OpenSSL headers.
|-
| no-ssl3 || Disables SSLv3. <tt>OPENSSL_NO_SSL3</tt> will be defined in the OpenSSL headers.
|-
| no-comp || Disables compression independent of <tt>zlib</tt>. <tt>OPENSSL_NO_COMP</tt> will be defined in the OpenSSL headers.
|-
| no-idea || Disables IDEA algorithm. Unlike RC5 and MDC2, IDEA is enabled by default
|-
| no-asm || Disables assembly language routines (and uses C routines)
|-
| no-dtls || Disables DTLS in OpenSSL 1.1.0 and above
|-
| no-dtls1 || Disables DTLS in OpenSSL 1.0.2 and below
|-
| no-shared || Disables shared objects (only a static library is created)
|-
| no-hw || Disables hardware support (useful on mobile devices)
|-
| no-engine || Disables hardware support (useful on mobile devices)
|-
| no-threads || Disables threading support.
|-
| no-dso || Disables the OpenSSL DSO API (the library offers a shared object abstraction layer). If you disable DSO, then you must disable Engines also
|-
| no-err || Removes all error function names and error reason text to reduce footprint
|-
| no-npn/no-nextprotoneg || Disables Next Protocol Negotiation (NPN). Use <tt>no-nextprotoneg</tt> for 1.1.0 and above; and <tt>no-npn</tt> otherwise
|-
| no-psk || Disables Preshared Key (PSK). PSK provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-srp || Disables Secure Remote Password (SRP). SRP provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-ec2m || Used when configuring FIPS Capable Library with a FIPS Object Module that only includes prime curves. That is, use this switch if you use <tt>openssl-fips-ecp-2.0.5</tt>.
|-
| no-weak-ssl-ciphers || Disables RC4. Available in OpenSSL 1.1.0 and above.
|-
| -DXXX || Defines XXX. For example, <tt>-DOPENSSL_NO_HEARTBEATS</tt>.
|-
| -DPEDANTIC || Defines PEDANTIC. The library will avoid some undefined behavior, like casting an unaligned byte array to a different pointer type. This define should be used if building OpenSSL with undefined behavior sanitizer (<tt>-fsanitize=undefined</tt>).
|-
| -DOPENSSL_USE_IPV6=0 || Disables IPv6. Useful if OpenSSL encounters incorrect or inconsistent platform headers and mistakenly enables IPv6. Must be passed to <tt>Configure</tt> manually.
|-
| -DNO_FORK || Defines NO_FORK. Disables calls to <tt>fork</tt>. Useful for operating systems like AppleTVOS, WatchOS, AppleTVSimulator and WatchSimulator.
|-
| -L''something'', -l''something'', -K''something'', -Wl,''something'' || Linker options, will become part of LDFLAGS.
|-
| -''anythingelse'', +''anythingelse'' || Compiler options, will become part of CFLAGS.
|}

'''''Note''''': on older OSes, like CentOS 5, BSD 5, and Windows XP or Vista, you will need to configure with <tt>no-async</tt> when building OpenSSL 1.1.0 and above. The configuration system does not detect lack of the Posix feature on the platforms.

'''''Note''''': you can verify compiler support for <tt>__uint128_t</tt> with the following:

<pre># gcc -dM -E - </dev/null | grep __SIZEOF_INT128__
#define __SIZEOF_INT128__ 16</pre>

=== PREFIX and OPENSSLDIR ===

<tt>--prefix</tt> and <tt>--openssldir</tt> control the configuration of installed components. The behavior and interactions of <tt>--prefix</tt> and <tt>--openssldir</tt> are slightly different between OpenSSL 1.0.2 and below, and OpenSSL 1.1.0 and above.

The '''''rule of thumb''''' to use when you want something that "just works" for all recent versions of OpenSSL, including OpenSSL 1.0.2 and 1.1.0, is:

* specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>
* set <tt>--prefix</tt> and <tt>--openssldir</tt> to the same location

One word of caution is ''avoid'' <tt>--prefix=/usr</tt> when OpenSSL versions are '''''not''''' [[Binary_Compatibility|binary compatible]]. You will replace the distro's version of OpenSSL with your version of OpenSSL. It will most likely break everything, including the package management system.

'''OpenSSL 1.0.2 and below'''

It is usually ''not'' necessary to specify <tt>--prefix</tt>. If <tt>--prefix</tt> is ''not'' specified, then <tt>--openssldir</tt> is used. However, specifying ''only'' <tt>--prefix</tt> may result in broken builds because the 1.0.2 build system attempts to build in a FIPS configuration.

You can ''omit'' If <tt>--prefix</tt> and use <tt>--openssldir</tt>. In this case, the paths for <tt>--openssldir</tt> will be used during configuration. If <tt>--openssldir</tt> is not specified, the the default <tt>/usr/local/ssl</tt> is used.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

'''OpenSSL 1.1.0 and above'''

OpenSSL 1.1.0 changed the behavior of install rules. You should specify both <tt>--prefix</tt> and <tt>--openssldir</tt> to ensure <tt>make install</tt> works as expected.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

=== Debug Configuration ===

From the list above, its possible to quickly configure a "debug" build with <tt>./config -d</tt>. However, you can often get into a more amicable state ''without'' the [http://en.wikipedia.org/wiki/Electric_Fence Electric Fence] dependency by issuing:

<pre>$ ./config no-asm -g3 -O0 -fno-omit-frame-pointer -fno-inline-functions
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring OpenSSL version 1.1.0-pre5-dev (0x0x10100005L)
no-asm [option] OPENSSL_NO_ASM
...
Configuring for linux-x86_64
IsMK1MF =no
CC =gcc
CFLAG =-Wall -O3 -pthread -m64 -DL_ENDIAN -g3 -O0 -fno-omit-frame-pointer
...</pre>

Don't be alarmed about both <tt>-O3</tt> and <tt>-O0</tt>. The last setting ''"sticks"'', and that's the <tt>-O0</tt>.

If you are working in Visual Studio and you can't step into library calls, then see [http://stackoverflow.com/q/38249235 Step into not working, but can force stepping after some asm steps] on Stack Overflow.

=== Modifying Build Settings ===

Sometimes you need to work around OpenSSL's selections for building the library. For example, you might want to use <tt>-Os</tt> for a mobile device (rather than <tt>-O3</tt>), or you might want to use the <tt>clang</tt> compiler (rather than <tt>gcc</tt>).

In case like these, its often easier to modify <tt>Configure</tt> and <tt>Makefile.org</tt> rather than trying to add targets to the configure scripts. Below is a patch that modifies <tt>Configure</tt> and <tt>Makefile.org</tt> for use under the iOS 7.0 SDK (which lacks <tt>gcc</tt> in <tt>/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/</tt>):

* Modifies <tt>Configure</tt> to use <tt>clang</tt>
* Modifies <tt>Makefile.org</tt> to use <tt>clang</tt>
* Modifies <tt>CFLAG</tt> to use <tt>-Os</tt>
* Modifies <tt>MAKEDEPPROG</tt> to use <tt>$(CC) -M</tt>

Setting and resetting of <tt>LANG</tt> is required on Mac OSX to work around a <tt>sed</tt> bug or limitation.

<pre>OLD_LANG=$LANG
unset LANG

sed -i "" 's|\"iphoneos-cross\"\,\"llvm-gcc\:-O3|\"iphoneos-cross\"\,\"clang\:-Os|g' Configure
sed -i "" 's/CC= cc/CC= clang/g' Makefile.org
sed -i "" 's/CFLAG= -O/CFLAG= -Os/g' Makefile.org
sed -i "" 's/MAKEDEPPROG=makedepend/MAKEDEPPROG=$(CC) -M/g' Makefile.org

export LANG=$OLD_LANG</pre>

After modification, be sure to dclean and configure again so the new settings are picked up:

<pre>make dclean

./config
make depend
make all
...</pre>

=== Using RPATHs ===

<tt>RPATH</tt>'s are supported by default on the BSD platforms, but not others. If you are working on Linux and compatibles, then you have to manually add an RPATH. One of the easiest ways to add a <tt>RPATH</tt> is to configure with it as shown below.

<pre>./config -Wl,-rpath=/usr/local/ssl/lib</pre>

For modern Linux you should also use <tt>-Wl,--enable-new-dtags</tt>. The linker option sets a <tt>RUNPATH</tt> as opposed to a <tt>RPATH</tt>. A <tt>RUNPATH</tt> allows library path overrides at runtime, while a <tt>RPATH</tt> does not.

<pre>./config -Wl,-rpath=/usr/local/ssl/lib -Wl,--enable-new-dtags</pre>

'''''Note well''''': you should use a <tt>RPATH</tt> or <tt>RUNPATH</tt> when building both OpenSSL and your program. If you don't add a <tt>RPATH</tt> or <tt>RUNPATH</tt> to both, then your program could runtime-link to the wrong version of OpenSSL. Linking against random versions of a security library is ''not'' a good idea.

You can also add an <tt>RPATH</tt> or <tt>RUNPATH</tt> by hard coding the <tt>RPATH</tt> into a configure line. For example, on Debian x86_64 open the file <tt>Configure</tt> in an editor, copy <tt>linux-x86_64</tt>, name it <tt>linux-x86_64-rpath</tt>, and make the following change to add the <tt>-rpath</tt> option. Notice the addition of <tt>-Wl,-rpath=...</tt> in two places.

<pre>"linux-x86_64-rpath", "gcc:-m64 -DL_ENDIAN -O3 -Wall -Wl,-rpath=/usr/local/ssl/lib::
-D_REENTRANT::-Wl,-rpath=/usr/local/ssl/lib -ldl:SIXTY_FOUR_BIT_LONG RC4_CHUNK DES_INT DES_UNROLL:
${x86_64_asm}:elf:dlfcn:linux-shared:-fPIC:-m64:.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR):::64",</pre>

Above, fields 2 and 6 were changed. They correspond to <tt>$cflag</tt> and <tt>$ldflag</tt> in OpenSSL's builds system.

Then, Configure with the new configuration:

<pre>$ ./Configure linux-x86_64-rpath shared no-ssl2 no-ssl3 no-comp \
--openssldir=/usr/local/ssl enable-ec_nistp_64_gcc_128</pre>

Finally, after <tt>make</tt>, verify the settings stuck:

<pre>$ readelf -d ./libssl.so | grep -i -E 'rpath|runpath'
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./libcrypto.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./apps/openssl | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]</pre>

Once you perform <tt>make install</tt>, then <tt>ldd</tt> will produce expected results:

<pre>$ ldd /usr/local/ssl/lib/libssl.so
linux-vdso.so.1 => (0x00007ffceff6c000)
ibcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007ff5eff96000)
...

$ ldd /usr/local/ssl/bin/openssl
linux-vdso.so.1 => (0x00007ffc30d3a000)
libssl.so.1.0.0 => /usr/local/ssl/lib/libssl.so.1.0.0 (0x00007f9e8372e000)
libcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007f9e832c0000)
...</pre>

=== FIPS Capable Library ===

If you want to use FIPS validated cryptography, you download, build and install the FIPS Object Module (<tt>openssl-fips-2.0.5.tar.gz</tt>) according to the [https://www.openssl.org/docs/fips/UserGuide-2.0.pdf FIPS User Guide 2.0] and [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.pdf FIPS 140-2 Security Policy]. You then download, build and install the FIPS Capable Library (<tt>openssl-1.0.1e.tar.gz</tt>).

When configuring the FIPS Capable Library, you must use <tt>fips</tt> as an option:

<pre>./config fips <other options ...></pre>

If you are configuring the FIPS Capable Library with only prime curves (<tt>openssl-fips-ecp-2.0.5.tar.gz</tt>), then you must configure with <tt>no-ec2m</tt>:

<pre>./config fips no-ec2m <other options ...></pre>

=== Compile Time Checking ===

If you disable an option during configure, you can check if it's available through <tt>OPENSSL_NO_*</tt> defines. OpenSSL writes the configure options to <tt><openssl/opensslconf.h></tt>. For example, if you want to know if SSLv3 is available, then you would perform the following in your code:

<pre>#include <openssl/opensslconf.h>
...

#if !defined(OPENSSL_NO_SSL3)
/* SSLv3 is available */
#endif</pre>

== Compilation ==

After configuring the library, you should run <tt>make</tt>. If prompted, there's usually no need to <tt>make depend</tt> since you are building from a clean download.

==== Quick ====

<pre>./config <nowiki><options ...> --openssldir=/usr/local/ssl</nowiki>
make
make test
sudo make install</pre>

Various options can be found examining the <tt>Configure</tt> file (there is a well commented block at its top). OpenSSL ships with SSLv2, SSLv3 and Compression enabled by default (see <tt>my $disabled</tt>), so you might want to use <tt>no-ssl2 no-ssl3</tt>, <tt>no-ssl3</tt>, and <tt>no-comp</tt>.

== Platfom specific ==

=== Linux ===

==== Intel ====

==== ARM ====

==== X32 (ILP32) ====

X32 uses the 32-bit data model (ILP32) on x86_64/amd64. To properly configure for X32 under current OpenSSL distributions, you must use <tt>Configure</tt> and use the x32 triplet:

<pre># ./Configure LIST | grep x32
linux-x32
...</pre>

Then:

<pre># ./Configure linux-x32
Configuring OpenSSL version 1.1.0-pre6-dev (0x0x10100006L)
no-asan [default] OPENSSL_NO_ASAN (skip dir)
...
Configuring for linux-x32
CC =gcc
CFLAG =-Wall -O3 -pthread -mx32 -DL_ENDIAN
SHARED_CFLAG =-fPIC
...</pre>

If using an amd64-compatible processor and GCC with that supports <tt>__uint128_t</tt>, then you usually add <tt>enable-ec_nistp_64_gcc_128 </tt> in addition to your other flags.

=== Windows ===
3noch wrote a VERY good guide in 2012 [https://web.archive.org/web/20161123004257/http://developer.covenanteyes.com/building-openssl-for-visual-studio// here] (PLEASE NOTE: the guide was written in 2012 and is no longer available at the original location; the link now points to an archived version at the Internet Archive Wayback Machine).

Like he said in his article, make absolutely sure to create separate directories for 32 and 64 bit versions.

==== W32 / Windows NT - Windows 9x ====

type INSTALL.W32

* you need Perl for Win32. Unless you will build on Cygwin, you will need ActiveState Perl, available from http://www.activestate.com/ActivePerl.
* one of the following C compilers:
** Visual C++
** Borland C
** GNU C (Cygwin or MinGW)
* Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ is required if you intend to utilize assembler modules. Note that NASM is now the only supported assembler.

==== W64 ====

Read first the INSTALL.W64 documentation note containing some specific 64bits information.
See also INSTALL.W32 that still provides additonnal build information common to both the 64 and 32 bit versions.

You may be surprised: the 64bit artefacts are indeed output in the out32* sub-directories and bear names ending *32.dll. Fact is the 64 bit compile target is so far an incremental change over the legacy 32bit windows target. Numerous compile flags are still labelled "32" although those do apply to both 32 and 64bit targets.

The important pre-requisites are to have PERL available (for essential file processing so as to prepare sources and scripts for the target OS) and of course a C compiler like Microsoft Visual Studio for C/C++. Also note the procedure changed at OpenSSL 1.1.0 and is more streamlined. Also see [https://stackoverflow.com/q/39076244/608639 Why there is no ms\do_ms.bat after perl Configure VC-WIN64A] on Stack Overflow.

=== OpenSSL 1.1.0 ===

For OpenSSL 1.1.0 and above perform these steps:

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# Extract the source files to your folder, here <code>cd c:\myPath\openssl</code>
# Launch Visual Studio tool x64 Cross Tools Command prompt
# Goto your defined folder <code>cd c:\myPath\openssl</code>
# Configure for the target OS with <code>perl Configure VC-WIN64A</code> or other configurations to be found in the INSTALL file (e.g. UNIX targets).
## For instance: <code>perl Configure VC-WIN64A</code>.
# (''Optional'') In case you compiled before on 32 or 64-bits, make sure you run <code>nmake clean</code> to prevent trouble across 32 and 64-bits which share output folder.
# Now build with: <code>nmake</code>
# Output can be found in the '''root''' of your folder as '''libcrypto-1_1x64.dll''' and '''libssl-1_1-x64.dll''' (with all the build additionals such as .pdb .lik or static .lib). You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers libcrypto-1_1x64.dll | more</code>, and look at the FILE HEADER section.
# Test the code using the 'test' make target, by running <code>nmake test</code>.
# Reminder, clean your code to prevent issues the next time you compile for a different target. See step 7.

==== Windows CE ====
'' Not specified ''

=== OpenSSL 1.0.2 ===

For OpenSSL 1.0.2 and earlier the procedure is as follows.

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# launch a Visual Studio tool x64 Cross Tools Command prompt
# change to the directory where you have copied openssl sources <code>cd c:\myPath\openssl</code>
# configure for the target OS with the command <code>perl Configure VC-WIN64A</code>. You may also be interested to set more configuration options as documented in the general INSTALL note (for UNIX targets). For instance: <code>perl Configure VC-WIN64A</code>.
# prepare the target environment with the command: <code>ms\do_win64a</code>
# ensure you start afresh and notably without linkable products from a previous 32bit compile (as 32 and 64 bits compiling still share common directories) with the command: <code>nmake -f ms\ntdll.mak clean</code> for the DLL target and <code>nmake -f ms\nt.mak clean</code> for static libraries.
# build the code with: <code>nmake -f ms\ntdll.mak</code> (respectively <code>nmake -f ms\nt.mak</code> )
# the artefacts will be found in sub directories out32dll and out32dll.dbg (respectively out32 and out32.dbg for static libraries). The libcrypto and ssl libraries are still named libeay32.lib and ssleay32.lib, and associated includes in inc32 ! You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers out32dll/libeay32.lib | more</code>, and look at the FILE HEADER section.
# test the code using the various *test.exe programs in out32dll. Use the 'test' make target to run all tests as in <code>nmake -f ms\ntdll.mak test</code>
# we recommend that you move/copy needed includes and libraries from the "32" directories under a new explicit directory tree for 64bit applications from where you will import and link your target applications, similar to that explained in INSTALL.W32.

==== Windows CE ====

=== OS X ===

The earlier discussion presented a lot of information (and some of it had OS X information). Here are the TLDR versions to configure, build and install the library.

If configuring for 64-bit OS X, then use a command similar to:

<pre>./Configure darwin64-x86_64-cc shared enable-ec_nistp_64_gcc_128 no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macos-x86_64
make depend
sudo make install</pre>

If configuring for 32-bit OS X, then use a command similar to:

<pre>./Configure darwin-i386-cc shared no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macosx-i386
make depend
sudo make install</pre>

If you want to build a multiarch OpenSSL library, then see this answer on Stack Overflow: [http://stackoverflow.com/a/25531033/608639 Build Multiarch OpenSSL on OS X].

=== iOS ===

The following builds OpenSSL for iOS using the iPhoneOS SDK. The configuration avoids the dynamic library the DSO interface and engines.

If you run <tt>make install</tt>, then the headers will be installed in <tt>/usr/local/openssl-ios/include</tt> and libraries will be installed in <tt>/usr/local/openssl-ios/lib</tt>.

==== 32-bit ====

For OpenSSL 1.1.0 and above, a 32-bit iOS cross-compiles uses the <tt>ios-cross</tt> target, and options similar to <tt>--prefix=/usr/local/openssl-ios</tt>.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT OPENSSL_BN_ASM_GF2m SHA1_ASM SHA256_ASM SHA512_ASM AES_ASM BSAES_ASM GHASH_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

If you are working with OpenSSL 1.0.2 or below, then use the <tt>iphoneos-cross</tt> target.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure iphoneos-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios
Configuring for iphoneos-cross
no-dso [option]
no-engine [option] OPENSSL_NO_ENGINE (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-hw [option] OPENSSL_NO_HW
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS (skip dir)
no-zlib [default]
no-zlib-dynamic [default]
IsMK1MF=0
CC =clang
CFLAG =-DOPENSSL_THREADS -D_REENTRANT -O3 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fomit-frame-pointer -fno-common
...</pre>

==== 64-bit ====

For OpenSSL 1.1.0 , a 64-bit iOS cross-compiles uses the <tt>ios64-cross</tt> target, and <tt>--prefix=/usr/local/openssl-ios64</tt>. <tt>ios64-cross</tt>. There is no built-in 64-bit iOS support for OpenSSL 1.0.2 or below.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios64-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios64

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios64-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT SHA1_ASM SHA256_ASM SHA512_ASM VPAES_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

=== Android ===

Visit [[Android]] and [[FIPS Library and Android]].

=== More ===

==== VAX/VMS ====

I you wonder what are files ending with .com like test/testca.com those are VAX/VMX scripts.
This code is still maintained.

==== OS/2 ====

==== NetWare ====
5.x 6.x

==== HP-UX ====
[[HP-UX Itanium FIPS and OpenSSL build]]

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be useful to detect either <tt>OPENSSL_init_ssl</tt> or <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Shell level]]
[[Category:Installation]]
[[Category:Compilation]]

Compilation and Installation

2021-03-29T19:14:04Z

Jwalton: Add info on RUNPATHs

The following page is a combination of the <tt>INSTALL</tt> file provided with the OpenSSL library and notes from the field. If you have questions about what you are doing or seeing, then you should consult <tt>INSTALL</tt> since it contains the commands and specifies the behavior by the development team.

OpenSSL uses a custom build system to configure the library. Configuration will allow the library to set up the recursive makefiles from <tt>makefile.org</tt>. Once configured, you use <tt>make</tt> to build the library. You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

You must use a C compiler to build the OpenSSL library. You cannot use a C++ compiler. Later, once the library is built, it is OK to create user programs with a C++ compiler. But the library proper must be built with a C compiler.

There are two generations of build system. First is the build system used in OpenSSL 1.0.2 and below. The instructions below apply to it. Second is the build system for OpenSSL 1.1.0 and above. The instructions are similar, but not the same. For example, the second generation abandons the monolithic <tt>Configure</tt> and places individual configurations in the <tt>Configurations</tt> directory. Also, the second generation is more platform agnostic and uses templates to produce a final, top level build file (<tt>Makefile</tt>, <tt>descrip.mms</tt>, what have you).

After you configure and build the library, you should always perform a <tt>make test</tt> to ensure the library performs as expected under its self tests. If you are building OpenSSL 1.1.0 and above, then you will also need PERL 5.10 or higher (see <tt>README.PERL</tt> for details).

OpenSSL's build system does not rely upon <tt>autotools</tt> or <tt>libtool</tt>. Also see [http://www.openssl.org/support/faq.html#MISC5 Why aren't tools like 'autoconf' and 'libtool' used?] in the OpenSSL FAQ.

== Retrieve source code ==

The OpenSSL source code can be downloaded from [http://www.openssl.org/source/ OpenSSL Source Tarballs] or any suitable [http://www.openssl.org/source/mirror.html ftp mirror]. There are various versions including stable as well as unstable versions.

The source code is managed via Git. Its referred to as Master. The repository is

: git://git.openssl.org/openssl.git

The source is also available via a [https://github.com/openssl/openssl GitHub] mirror. This repository is updated every 15 minutes.

* [[Use_of_Git|Accessing OpenSSL source code via Git]]

== Configuration ==

OpenSSL is configured for a particular platform with protocol and behavior options using <tt>Configure</tt> and <tt>config</tt>.

You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

=== Supported Platforms ===

You can run <tt>Configure LIST</tt> to see a list of available platforms.

<pre>$ ./Configure LIST
BC-32
BS2000-OSD
BSD-generic32
BSD-generic64
BSD-ia64
BSD-sparc64
BSD-sparcv8
BSD-x86
BSD-x86-elf
BSD-x86_64
Cygwin
Cygwin-x86_64
DJGPP
...</pre>

If your platform is not listed, then use a similar platform and tune the <tt>$cflags</tt> and <tt>$ldflags</tt> by making a copy of the configure line and giving it its own name. <tt>$cflags</tt> and <tt>$ldflags</tt> correspond to fields 2 and 6 in a configure line. An example of using a similar configure line is presented in [[Compilation_and_Installation#Using_RPATHs|Using RPATHs]].

=== Configure & Config ===

You use <tt>Configure</tt> and <tt>config</tt> to tune the compile and installation process through options and switches. The difference between is <tt>Configure</tt> properly handles the host-arch-compiler triplet, and <tt>config</tt> does not. <tt>config</tt> attempts to guess the triplet, so its a lot like autotool's <tt>config.guess</tt>.

You can usually use <tt>config</tt> and it will do the right thing (from Ubuntu 13.04, x64):

<pre>$ ./config
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring for linux-x86_64
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

Mac OS X can have issues (its often a neglected platform), and you will have to use <tt>Configure</tt>:

<pre> ./Configure darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

You can also configure on Darwin by exporting <tt>KERNEL_BITS</tt>:

<pre>$ export KERNEL_BITS=64
$ ./config shared no-ssl2 no-ssl3 enable-ec_nistp_64_gcc_128 --openssldir=/usr/local/ssl/macosx-x64/
Operating system: i686-apple-darwinDarwin Kernel Version 12.5.0: Sun Sep 29 13:33:47 PDT 2013; root:xnu-2050.48.12~1/RELEASE_X86_64
Configuring for darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

If you provide a option not known to configure or ask for help, then you get a brief help message:

<pre>$ ./Configure --help
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]</pre>

And if you supply an unknown triplet:

<pre>$ ./Configure darwin64-x86_64-clang
Configuring for darwin64-x86_64-clang
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]

pick os/compiler from:
BC-32 BS2000-OSD BSD-generic32 BSD-generic64 BSD-ia64 BSD-sparc64 BSD-sparcv8
BSD-x86 BSD-x86-elf BSD-x86_64 Cygwin Cygwin-pre1.3 DJGPP MPE/iX-gcc OS2-EMX
...

NOTE: If in doubt, on Unix-ish systems use './config'.</pre>

=== Dependencies ===

If you are prompted to run <tt>make depend</tt>, then you must do so. For OpenSSL 1.0.2 and below, its required to update the standard distribution once configuration options change.

<pre>Since you've disabled or enabled at least one algorithm, you need to do
the following before building:

make depend
</pre>

OpenSSL 1.1.0 and above performs the dependency step for you, so you should not see the message. However, you should perform a <tt>make clean</tt> to ensure the list of objects files is accurate after a reconfiguration.

== Configure Options ==

OpenSSL has been around a long time, and it carries around a lot of cruft. For example, from above, SSLv2 is enabled by default. SSLv2 is completely broken, and you should disable it during configuration. You can disable protocols and provide other options through <tt>Configure</tt> and <tt>config</tt>, and the following lists some of them.

'''Note''': if you specify a non-existent option, then the configure scripts will proceed without warning. For example, if you inadvertently specify '''no-sslv2''' rather than '''no-ssl2 no-ssl3''', the script will configure ''with'' SSLv2 and ''without'' warning for the unknown no-sslv2.

'''Note''': when building a shared object, both the static archive and shared objects are built. You do not need to do anything special to build both when '''shared''' is specified.

{| class="wikitable sortable" border="1"
|+ OpenSSL Library Options
|-
! scope="col" width="150px" | Option
! scope="col" class="unsortable" | Description
|-
| --prefix=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| --openssldir=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| -d || Debug build of the library. Optimizations are disabled (no <tt>-O3</tt> or similar) and <tt>libefence</tt> is used (<tt>apt-get install electric-fence</tt> or <tt>yum install electric-fence</tt>). TODO: Any other features?
|-
| shared || Build a shared object in addition to the static archive. You probably need a [[#Using_RPATHs|RPATH]] when enabling <tt>shared</tt> to ensure <tt>openssl</tt> uses the correct <tt>libssl</tt> and <tt>libcrypto</tt> after installation.
|-
| enable-ec_nistp_64_gcc_128 || Use on little endian platforms when GCC supports <tt>__uint128_t</tt>. ECDH is about 2 to 4 times faster. Not enabled by default because <tt>Configure</tt> can't determine it. Enable it if your compiler defines <tt>__SIZEOF_INT128__</tt>, the CPU is little endian and it tolerates unaligned data access.
|-
| enable-capieng || Enables the Microsoft CAPI engine on Windows platforms. Used to access the Windows Certificate Store. Also see [http://openssl.6102.n7.nabble.com/Using-Windows-certificate-store-through-OpenSSL-td46788.html Using Windows certificate store through OpenSSL] on the OpenSSL developer list.
|-
| no-ssl2 || Disables SSLv2. <tt>OPENSSL_NO_SSL2</tt> will be defined in the OpenSSL headers.
|-
| no-ssl3 || Disables SSLv3. <tt>OPENSSL_NO_SSL3</tt> will be defined in the OpenSSL headers.
|-
| no-comp || Disables compression independent of <tt>zlib</tt>. <tt>OPENSSL_NO_COMP</tt> will be defined in the OpenSSL headers.
|-
| no-idea || Disables IDEA algorithm. Unlike RC5 and MDC2, IDEA is enabled by default
|-
| no-asm || Disables assembly language routines (and uses C routines)
|-
| no-dtls || Disables DTLS in OpenSSL 1.1.0 and above
|-
| no-dtls1 || Disables DTLS in OpenSSL 1.0.2 and below
|-
| no-shared || Disables shared objects (only a static library is created)
|-
| no-hw || Disables hardware support (useful on mobile devices)
|-
| no-engine || Disables hardware support (useful on mobile devices)
|-
| no-threads || Disables threading support.
|-
| no-dso || Disables the OpenSSL DSO API (the library offers a shared object abstraction layer). If you disable DSO, then you must disable Engines also
|-
| no-err || Removes all error function names and error reason text to reduce footprint
|-
| no-npn/no-nextprotoneg || Disables Next Protocol Negotiation (NPN). Use <tt>no-nextprotoneg</tt> for 1.1.0 and above; and <tt>no-npn</tt> otherwise
|-
| no-psk || Disables Preshared Key (PSK). PSK provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-srp || Disables Secure Remote Password (SRP). SRP provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-ec2m || Used when configuring FIPS Capable Library with a FIPS Object Module that only includes prime curves. That is, use this switch if you use <tt>openssl-fips-ecp-2.0.5</tt>.
|-
| no-weak-ssl-ciphers || Disables RC4. Available in OpenSSL 1.1.0 and above.
|-
| -DXXX || Defines XXX. For example, <tt>-DOPENSSL_NO_HEARTBEATS</tt>.
|-
| -DPEDANTIC || Defines PEDANTIC. The library will avoid some undefined behavior, like casting an unaligned byte array to a different pointer type. This define should be used if building OpenSSL with undefined behavior sanitizer (<tt>-fsanitize=undefined</tt>).
|-
| -DOPENSSL_USE_IPV6=0 || Disables IPv6. Useful if OpenSSL encounters incorrect or inconsistent platform headers and mistakenly enables IPv6. Must be passed to <tt>Configure</tt> manually.
|-
| -DNO_FORK || Defines NO_FORK. Disables calls to <tt>fork</tt>. Useful for operating systems like AppleTVOS, WatchOS, AppleTVSimulator and WatchSimulator.
|-
| -L''something'', -l''something'', -K''something'', -Wl,''something'' || Linker options, will become part of LDFLAGS.
|-
| -''anythingelse'', +''anythingelse'' || Compiler options, will become part of CFLAGS.
|}

'''''Note''''': on older OSes, like CentOS 5, BSD 5, and Windows XP or Vista, you will need to configure with <tt>no-async</tt> when building OpenSSL 1.1.0 and above. The configuration system does not detect lack of the Posix feature on the platforms.

'''''Note''''': you can verify compiler support for <tt>__uint128_t</tt> with the following:

<pre># gcc -dM -E - </dev/null | grep __SIZEOF_INT128__
#define __SIZEOF_INT128__ 16</pre>

=== PREFIX and OPENSSLDIR ===

<tt>--prefix</tt> and <tt>--openssldir</tt> control the configuration of installed components. The behavior and interactions of <tt>--prefix</tt> and <tt>--openssldir</tt> are slightly different between OpenSSL 1.0.2 and below, and OpenSSL 1.1.0 and above.

The '''''rule of thumb''''' to use when you want something that "just works" for all recent versions of OpenSSL, including OpenSSL 1.0.2 and 1.1.0, is:

* specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>
* set <tt>--prefix</tt> and <tt>--openssldir</tt> to the same location

One word of caution is ''avoid'' <tt>--prefix=/usr</tt> when OpenSSL versions are '''''not''''' [[Binary_Compatibility|binary compatible]]. You will replace the distro's version of OpenSSL with your version of OpenSSL. It will most likely break everything, including the package management system.

'''OpenSSL 1.0.2 and below'''

It is usually ''not'' necessary to specify <tt>--prefix</tt>. If <tt>--prefix</tt> is ''not'' specified, then <tt>--openssldir</tt> is used. However, specifying ''only'' <tt>--prefix</tt> may result in broken builds because the 1.0.2 build system attempts to build in a FIPS configuration.

You can ''omit'' If <tt>--prefix</tt> and use <tt>--openssldir</tt>. In this case, the paths for <tt>--openssldir</tt> will be used during configuration. If <tt>--openssldir</tt> is not specified, the the default <tt>/usr/local/ssl</tt> is used.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

'''OpenSSL 1.1.0 and above'''

OpenSSL 1.1.0 changed the behavior of install rules. You should specify both <tt>--prefix</tt> and <tt>--openssldir</tt> to ensure <tt>make install</tt> works as expected.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

=== Debug Configuration ===

From the list above, its possible to quickly configure a "debug" build with <tt>./config -d</tt>. However, you can often get into a more amicable state ''without'' the [http://en.wikipedia.org/wiki/Electric_Fence Electric Fence] dependency by issuing:

<pre>$ ./config no-asm -g3 -O0 -fno-omit-frame-pointer -fno-inline-functions
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring OpenSSL version 1.1.0-pre5-dev (0x0x10100005L)
no-asm [option] OPENSSL_NO_ASM
...
Configuring for linux-x86_64
IsMK1MF =no
CC =gcc
CFLAG =-Wall -O3 -pthread -m64 -DL_ENDIAN -g3 -O0 -fno-omit-frame-pointer
...</pre>

Don't be alarmed about both <tt>-O3</tt> and <tt>-O0</tt>. The last setting ''"sticks"'', and that's the <tt>-O0</tt>.

If you are working in Visual Studio and you can't step into library calls, then see [http://stackoverflow.com/q/38249235 Step into not working, but can force stepping after some asm steps] on Stack Overflow.

=== Modifying Build Settings ===

Sometimes you need to work around OpenSSL's selections for building the library. For example, you might want to use <tt>-Os</tt> for a mobile device (rather than <tt>-O3</tt>), or you might want to use the <tt>clang</tt> compiler (rather than <tt>gcc</tt>).

In case like these, its often easier to modify <tt>Configure</tt> and <tt>Makefile.org</tt> rather than trying to add targets to the configure scripts. Below is a patch that modifies <tt>Configure</tt> and <tt>Makefile.org</tt> for use under the iOS 7.0 SDK (which lacks <tt>gcc</tt> in <tt>/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/</tt>):

* Modifies <tt>Configure</tt> to use <tt>clang</tt>
* Modifies <tt>Makefile.org</tt> to use <tt>clang</tt>
* Modifies <tt>CFLAG</tt> to use <tt>-Os</tt>
* Modifies <tt>MAKEDEPPROG</tt> to use <tt>$(CC) -M</tt>

Setting and resetting of <tt>LANG</tt> is required on Mac OSX to work around a <tt>sed</tt> bug or limitation.

<pre>OLD_LANG=$LANG
unset LANG

sed -i "" 's|\"iphoneos-cross\"\,\"llvm-gcc\:-O3|\"iphoneos-cross\"\,\"clang\:-Os|g' Configure
sed -i "" 's/CC= cc/CC= clang/g' Makefile.org
sed -i "" 's/CFLAG= -O/CFLAG= -Os/g' Makefile.org
sed -i "" 's/MAKEDEPPROG=makedepend/MAKEDEPPROG=$(CC) -M/g' Makefile.org

export LANG=$OLD_LANG</pre>

After modification, be sure to dclean and configure again so the new settings are picked up:

<pre>make dclean

./config
make depend
make all
...</pre>

=== Using RPATHs ===

<tt>RPATH</tt>'s are supported by default on the BSD platforms, but not others. If you are working on Linux and compatibles, then you have to manually add an RPATH. One of the easiest ways to add a <tt>RPATH</tt> is to configure with it as shown below.

<pre>./config -Wl,-rpath=/usr/local/ssl/lib</pre>

For modern Linux you should also use <tt>-Wl,--enable-new-dtags</tt>. The linker option sets a RUNPATH as opposed to a RPATH. A RUNPATH allows runtime path overrides, while a RPATH does not.

<pre>./config -Wl,-rpath=/usr/local/ssl/lib -Wl,--enable-new-dtags</pre>

'''''Note well''''': you should use a RPATH or RUNPATH when building both OpenSSL and your program. If you don't add a RPATH or RUNPATH to both, then your program could runtime-link to the wrong version of OpenSSL. Linking against random versions of a security library is ''not'' a good idea.

You can also add an <tt>RPATH</tt> or <tt>RUNPATH</tt> by hard coding the <tt>RPATH</tt> into a configure line. For example, on Debian x86_64 open the file <tt>Configure</tt> in an editor, copy <tt>linux-x86_64</tt>, name it <tt>linux-x86_64-rpath</tt>, and make the following change to add the <tt>-rpath</tt> option. Notice the addition of <tt>-Wl,-rpath=...</tt> in two places.

<pre>"linux-x86_64-rpath", "gcc:-m64 -DL_ENDIAN -O3 -Wall -Wl,-rpath=/usr/local/ssl/lib::
-D_REENTRANT::-Wl,-rpath=/usr/local/ssl/lib -ldl:SIXTY_FOUR_BIT_LONG RC4_CHUNK DES_INT DES_UNROLL:
${x86_64_asm}:elf:dlfcn:linux-shared:-fPIC:-m64:.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR):::64",</pre>

Above, fields 2 and 6 were changed. They correspond to <tt>$cflag</tt> and <tt>$ldflag</tt> in OpenSSL's builds system.

Then, Configure with the new configuration:

<pre>$ ./Configure linux-x86_64-rpath shared no-ssl2 no-ssl3 no-comp \
--openssldir=/usr/local/ssl enable-ec_nistp_64_gcc_128</pre>

Finally, after <tt>make</tt>, verify the settings stuck:

<pre>$ readelf -d ./libssl.so | grep -i -E 'rpath|runpath'
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./libcrypto.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./apps/openssl | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]</pre>

Once you perform <tt>make install</tt>, then <tt>ldd</tt> will produce expected results:

<pre>$ ldd /usr/local/ssl/lib/libssl.so
linux-vdso.so.1 => (0x00007ffceff6c000)
ibcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007ff5eff96000)
...

$ ldd /usr/local/ssl/bin/openssl
linux-vdso.so.1 => (0x00007ffc30d3a000)
libssl.so.1.0.0 => /usr/local/ssl/lib/libssl.so.1.0.0 (0x00007f9e8372e000)
libcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007f9e832c0000)
...</pre>

=== FIPS Capable Library ===

If you want to use FIPS validated cryptography, you download, build and install the FIPS Object Module (<tt>openssl-fips-2.0.5.tar.gz</tt>) according to the [https://www.openssl.org/docs/fips/UserGuide-2.0.pdf FIPS User Guide 2.0] and [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.pdf FIPS 140-2 Security Policy]. You then download, build and install the FIPS Capable Library (<tt>openssl-1.0.1e.tar.gz</tt>).

When configuring the FIPS Capable Library, you must use <tt>fips</tt> as an option:

<pre>./config fips <other options ...></pre>

If you are configuring the FIPS Capable Library with only prime curves (<tt>openssl-fips-ecp-2.0.5.tar.gz</tt>), then you must configure with <tt>no-ec2m</tt>:

<pre>./config fips no-ec2m <other options ...></pre>

=== Compile Time Checking ===

If you disable an option during configure, you can check if it's available through <tt>OPENSSL_NO_*</tt> defines. OpenSSL writes the configure options to <tt><openssl/opensslconf.h></tt>. For example, if you want to know if SSLv3 is available, then you would perform the following in your code:

<pre>#include <openssl/opensslconf.h>
...

#if !defined(OPENSSL_NO_SSL3)
/* SSLv3 is available */
#endif</pre>

== Compilation ==

After configuring the library, you should run <tt>make</tt>. If prompted, there's usually no need to <tt>make depend</tt> since you are building from a clean download.

==== Quick ====

<pre>./config <nowiki><options ...> --openssldir=/usr/local/ssl</nowiki>
make
make test
sudo make install</pre>

Various options can be found examining the <tt>Configure</tt> file (there is a well commented block at its top). OpenSSL ships with SSLv2, SSLv3 and Compression enabled by default (see <tt>my $disabled</tt>), so you might want to use <tt>no-ssl2 no-ssl3</tt>, <tt>no-ssl3</tt>, and <tt>no-comp</tt>.

== Platfom specific ==

=== Linux ===

==== Intel ====

==== ARM ====

==== X32 (ILP32) ====

X32 uses the 32-bit data model (ILP32) on x86_64/amd64. To properly configure for X32 under current OpenSSL distributions, you must use <tt>Configure</tt> and use the x32 triplet:

<pre># ./Configure LIST | grep x32
linux-x32
...</pre>

Then:

<pre># ./Configure linux-x32
Configuring OpenSSL version 1.1.0-pre6-dev (0x0x10100006L)
no-asan [default] OPENSSL_NO_ASAN (skip dir)
...
Configuring for linux-x32
CC =gcc
CFLAG =-Wall -O3 -pthread -mx32 -DL_ENDIAN
SHARED_CFLAG =-fPIC
...</pre>

If using an amd64-compatible processor and GCC with that supports <tt>__uint128_t</tt>, then you usually add <tt>enable-ec_nistp_64_gcc_128 </tt> in addition to your other flags.

=== Windows ===
3noch wrote a VERY good guide in 2012 [https://web.archive.org/web/20161123004257/http://developer.covenanteyes.com/building-openssl-for-visual-studio// here] (PLEASE NOTE: the guide was written in 2012 and is no longer available at the original location; the link now points to an archived version at the Internet Archive Wayback Machine).

Like he said in his article, make absolutely sure to create separate directories for 32 and 64 bit versions.

==== W32 / Windows NT - Windows 9x ====

type INSTALL.W32

* you need Perl for Win32. Unless you will build on Cygwin, you will need ActiveState Perl, available from http://www.activestate.com/ActivePerl.
* one of the following C compilers:
** Visual C++
** Borland C
** GNU C (Cygwin or MinGW)
* Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ is required if you intend to utilize assembler modules. Note that NASM is now the only supported assembler.

==== W64 ====

Read first the INSTALL.W64 documentation note containing some specific 64bits information.
See also INSTALL.W32 that still provides additonnal build information common to both the 64 and 32 bit versions.

You may be surprised: the 64bit artefacts are indeed output in the out32* sub-directories and bear names ending *32.dll. Fact is the 64 bit compile target is so far an incremental change over the legacy 32bit windows target. Numerous compile flags are still labelled "32" although those do apply to both 32 and 64bit targets.

The important pre-requisites are to have PERL available (for essential file processing so as to prepare sources and scripts for the target OS) and of course a C compiler like Microsoft Visual Studio for C/C++. Also note the procedure changed at OpenSSL 1.1.0 and is more streamlined. Also see [https://stackoverflow.com/q/39076244/608639 Why there is no ms\do_ms.bat after perl Configure VC-WIN64A] on Stack Overflow.

=== OpenSSL 1.1.0 ===

For OpenSSL 1.1.0 and above perform these steps:

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# Extract the source files to your folder, here <code>cd c:\myPath\openssl</code>
# Launch Visual Studio tool x64 Cross Tools Command prompt
# Goto your defined folder <code>cd c:\myPath\openssl</code>
# Configure for the target OS with <code>perl Configure VC-WIN64A</code> or other configurations to be found in the INSTALL file (e.g. UNIX targets).
## For instance: <code>perl Configure VC-WIN64A</code>.
# (''Optional'') In case you compiled before on 32 or 64-bits, make sure you run <code>nmake clean</code> to prevent trouble across 32 and 64-bits which share output folder.
# Now build with: <code>nmake</code>
# Output can be found in the '''root''' of your folder as '''libcrypto-1_1x64.dll''' and '''libssl-1_1-x64.dll''' (with all the build additionals such as .pdb .lik or static .lib). You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers libcrypto-1_1x64.dll | more</code>, and look at the FILE HEADER section.
# Test the code using the 'test' make target, by running <code>nmake test</code>.
# Reminder, clean your code to prevent issues the next time you compile for a different target. See step 7.

==== Windows CE ====
'' Not specified ''

=== OpenSSL 1.0.2 ===

For OpenSSL 1.0.2 and earlier the procedure is as follows.

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# launch a Visual Studio tool x64 Cross Tools Command prompt
# change to the directory where you have copied openssl sources <code>cd c:\myPath\openssl</code>
# configure for the target OS with the command <code>perl Configure VC-WIN64A</code>. You may also be interested to set more configuration options as documented in the general INSTALL note (for UNIX targets). For instance: <code>perl Configure VC-WIN64A</code>.
# prepare the target environment with the command: <code>ms\do_win64a</code>
# ensure you start afresh and notably without linkable products from a previous 32bit compile (as 32 and 64 bits compiling still share common directories) with the command: <code>nmake -f ms\ntdll.mak clean</code> for the DLL target and <code>nmake -f ms\nt.mak clean</code> for static libraries.
# build the code with: <code>nmake -f ms\ntdll.mak</code> (respectively <code>nmake -f ms\nt.mak</code> )
# the artefacts will be found in sub directories out32dll and out32dll.dbg (respectively out32 and out32.dbg for static libraries). The libcrypto and ssl libraries are still named libeay32.lib and ssleay32.lib, and associated includes in inc32 ! You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers out32dll/libeay32.lib | more</code>, and look at the FILE HEADER section.
# test the code using the various *test.exe programs in out32dll. Use the 'test' make target to run all tests as in <code>nmake -f ms\ntdll.mak test</code>
# we recommend that you move/copy needed includes and libraries from the "32" directories under a new explicit directory tree for 64bit applications from where you will import and link your target applications, similar to that explained in INSTALL.W32.

==== Windows CE ====

=== OS X ===

The earlier discussion presented a lot of information (and some of it had OS X information). Here are the TLDR versions to configure, build and install the library.

If configuring for 64-bit OS X, then use a command similar to:

<pre>./Configure darwin64-x86_64-cc shared enable-ec_nistp_64_gcc_128 no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macos-x86_64
make depend
sudo make install</pre>

If configuring for 32-bit OS X, then use a command similar to:

<pre>./Configure darwin-i386-cc shared no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macosx-i386
make depend
sudo make install</pre>

If you want to build a multiarch OpenSSL library, then see this answer on Stack Overflow: [http://stackoverflow.com/a/25531033/608639 Build Multiarch OpenSSL on OS X].

=== iOS ===

The following builds OpenSSL for iOS using the iPhoneOS SDK. The configuration avoids the dynamic library the DSO interface and engines.

If you run <tt>make install</tt>, then the headers will be installed in <tt>/usr/local/openssl-ios/include</tt> and libraries will be installed in <tt>/usr/local/openssl-ios/lib</tt>.

==== 32-bit ====

For OpenSSL 1.1.0 and above, a 32-bit iOS cross-compiles uses the <tt>ios-cross</tt> target, and options similar to <tt>--prefix=/usr/local/openssl-ios</tt>.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT OPENSSL_BN_ASM_GF2m SHA1_ASM SHA256_ASM SHA512_ASM AES_ASM BSAES_ASM GHASH_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

If you are working with OpenSSL 1.0.2 or below, then use the <tt>iphoneos-cross</tt> target.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure iphoneos-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios
Configuring for iphoneos-cross
no-dso [option]
no-engine [option] OPENSSL_NO_ENGINE (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-hw [option] OPENSSL_NO_HW
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS (skip dir)
no-zlib [default]
no-zlib-dynamic [default]
IsMK1MF=0
CC =clang
CFLAG =-DOPENSSL_THREADS -D_REENTRANT -O3 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fomit-frame-pointer -fno-common
...</pre>

==== 64-bit ====

For OpenSSL 1.1.0 , a 64-bit iOS cross-compiles uses the <tt>ios64-cross</tt> target, and <tt>--prefix=/usr/local/openssl-ios64</tt>. <tt>ios64-cross</tt>. There is no built-in 64-bit iOS support for OpenSSL 1.0.2 or below.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios64-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios64

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios64-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT SHA1_ASM SHA256_ASM SHA512_ASM VPAES_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

=== Android ===

Visit [[Android]] and [[FIPS Library and Android]].

=== More ===

==== VAX/VMS ====

I you wonder what are files ending with .com like test/testca.com those are VAX/VMX scripts.
This code is still maintained.

==== OS/2 ====

==== NetWare ====
5.x 6.x

==== HP-UX ====
[[HP-UX Itanium FIPS and OpenSSL build]]

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be useful to detect either <tt>OPENSSL_init_ssl</tt> or <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Shell level]]
[[Category:Installation]]
[[Category:Compilation]]

Cryptogams SHA

2021-03-14T06:10:26Z

Jwalton: Add info on Apple M1 builds.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 SHA-1 implementation. According to the head notes the ARMv4 implementation runs around 6.5 cycles per byte (cpb). Typical C/C++ implementations run around 10 to 20 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>sha1-armv4.h</tt> and <tt>sha1-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' sha1-armv4.h sha1-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation hashes full SHA blocks. You are responsible for things like padding and side channel counter-measures.

If you experience ''"unexpected reloc type 0x03"'' when building a shared object then see [https://sourceware.org/ml/binutils/2019-05/msg00287.html What does unexpected reloc type 0x03 mean?] on the Binutils mailing list.

==Obtain Source Files==

There are two source files you need for Cryptogams SHA. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/sha/asm/sha1-armv4-large.pl <tt>sha1-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/sha/asm/sha1-armv4-large.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>sha1-armv4-large.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>sha1-armv4-large.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>sha1-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl sha1-armv4-large.pl linux32 sha1-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>sha1-armv4</tt> happens to have the requirement.

<pre>$ cat sha1-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' sha1-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' sha1-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>sha1-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>sha1-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c sha1-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S
$ nm sha1-armv4.o
00000000 T sha1_block_data_order</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble sha1-armv4.o
sha1-armv4.o: file format elf32-littlearm

Disassembly of section .text:

00000000 <sha1_block_data_order>:
0: e92d5ff0 push {r4, r5, r6, r7, r8, r9, sl, fp, ip, lr}
4: e0812302 add r2, r1, r2, lsl #6
8: e89000f8 ldm r0, {r3, r4, r5, r6, r7}
c: e59f858c ldr r8, [pc, #1420] ; 5a0 <sha1_block_data_order+0x5a0>
10: e1a0e00d mov lr, sp
14: e24dd03c sub sp, sp, #60 ; 0x3c
18: e1a05f65 ror r5, r5, #30
1c: e1a06f66 ror r6, r6, #30

...</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. Fortunately there is one function of interest called <tt>sha1_block_data_order</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>sha1_block_data_order</tt>.

<pre>openssl$ grep -nIR sha1_block_data_order | grep '\.c'
crypto/evp/e_sha_cbc_hmac_sha1.c:95: void sha1_block_data_order(void *c, const void *p, size_t len);
crypto/evp/e_sha_cbc_hmac_sha1.c:115: sha1_block_data_order(c, ptr, len / SHA_CBLOCK);
crypto/evp/e_sha_cbc_hmac_sha1.c:615: sha1_block_data_order(&key->md, data, 1);
crypto/evp/e_sha_cbc_hmac_sha1.c:631: sha1_block_data_order(&key->md, data, 1);
...
</pre>

We need several more symbols, and and they are <tt>OPENSSL_armcap_P</tt>, <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

<pre>$ grep -nIR OPENSSL_armcap_P
...
crypto/armcap.c:20:unsigned int OPENSSL_armcap_P = 0;</pre>

Lather, rinse, repeat for <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use. While it is not obvious, the <tt>len</tt> parameter from [[#Determine_API|Determine API]] is a block count, not a byte count.

<pre>/* Header file for use with Cryptogam's ARMv4 SHA1. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_SHA. */

#ifndef CRYPTOGAMS_SHA1_ARMV4_H
#define CRYPTOGAMS_SHA1_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

extern unsigned int OPENSSL_armcap_P;
void sha1_block_data_order(void *state, const void *data, size_t blocks);

/* Auxval caps */
#ifndef HWCAP_NEON
# define HWCAP_NEON (1 << 12)
#endif
#ifndef HWCAP_SHA1
# define HWCAP_SHA1 (1 << 5)
#endif

/* OpenSSL caps */
#define ARMV7_NEON (1<<0)
#define ARMV8_SHA1 (1<<3)

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_SHA1_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's SHA with your program.

<pre>$ gcc -std=c99 sha1-armv4-test.c ./sha1-armv4.o -o sha1-armv4-test.exe
$ ./sha1-armv4-test.exe
SHA1 hash of empty message: DA39A3EE5E6B4B0D...
Success!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

/* empty message with padding */
uint8_t message[64];
memset(message, 0x00, sizeof(message));
message[0] = 0x80;

/* initial state */
uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

sha1_block_data_order(state, message, 1);

const uint8_t b1 = (uint8_t)(state[0] >> 24);
const uint8_t b2 = (uint8_t)(state[0] >> 16);
const uint8_t b3 = (uint8_t)(state[0] >> 8);
const uint8_t b4 = (uint8_t)(state[0] >> 0);
const uint8_t b5 = (uint8_t)(state[1] >> 24);
const uint8_t b6 = (uint8_t)(state[1] >> 16);
const uint8_t b7 = (uint8_t)(state[1] >> 8);
const uint8_t b8 = (uint8_t)(state[1] >> 0);

/* DA39A3EE5E6B4B0D... */
printf("SHA1 hash of empty message: ");
printf("%02X%02X%02X%02X%02X%02X%02X%02X...\n",
b1, b2, b3, b4, b5, b6, b7, b8);

int success = ((b1 == 0xDA) && (b2 == 0x39) && (b3 == 0xA3) && (b4 == 0xEE) &&
(b5 == 0x5E) && (b6 == 0x6B) && (b7 == 0x4B) && (b8 == 0x0D));

if (success)
printf("Success!\n");
else
printf("Failure!\n");

return (success != 0 ? 0 : 1);
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>sha1_block_data_order</tt> is the names of function in the source code, and they will show up in the object file and when compiled and in the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for SHA-1 you should rename <tt>sha1_block_data_order</tt> and <tt>OPENSSL_armcap_P</tt>. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' sha1_armv4.h sha1_armv4.S
sed -i 's/sha1_block_data_order/MYLIB_sha1_block_data_order/g' sha1_armv4.h sha1_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* set processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

const unsigned int STEPS = 128;
uint8_t* buf = (uint8_t*)malloc(STEPS*64+64);
memset(buf, 0x00, 16);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
sha1_block_data_order(state, buf, idx+1);
total += 64*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 1 GHz */
const double cpuFreq = 1000.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a [https://www.amazon.com/gp/product/B07D4L7GXZ Libre Computer Tritium H3] with a Cortex-A7 Sun7i SoC running at 1 GHz. A C/C++ SHA implementation runs about 22 cpb on the dev-board. Notice <tt>sha1-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -std=c99 -march=armv7 -c sha1-armv4.S -o sha1-armv7.o
$ gcc -O3 -std=c99 sha1-armv7-test.c sha1-armv7.o -o sha1-armv7-test.exe
$ ./sha1-armv7-test.exe
180994048 bytes
57.59 mbs
16.56 cpb</pre>

== iOS Builds ==

<tt>sha1-armv4</tt> can be configured for iOS. Simply use <tt>ios32</tt> or <tt>ios64</tt> instead of <tt>linux32</tt> as shown below.

<pre>$ perl sha1-armv4-large.pl ios32 sha1-armv4.S
$ clang -arch armv7 sha1-armv4.S -c</pre>

And then:

<pre>$ nm sha1-armv4.o
000012d0 s OPENSSL_armcap_P
00000004 C _OPENSSL_armcap_P
00000000 T _sha1_block_data_order
00001100 t sha1_block_data_order_armv8
00000560 t sha1_block_data_order_neon

$ otool -tV sha1-armv4.o
sha1-armv4.o:
(__TEXT,__text) section
_sha1_block_data_order:
00000000 f8dfc4ec ldr.w r12, [pc, #0x4ec]
00000004 f2af0308 subw r3, pc, #0x8
00000008 f853c00c ldr.w r12, [r3, r12]
0000000c f8dcc000 ldr.w r12, [r12]
00000010 f01c0f08 tst.w r12, #0x8
00000014 f0418074 bne.w sha1_block_data_order_armv8
00000018 f01c0f01 tst.w r12, #0x1
0000001c f04082a0 bne.w sha1_block_data_order_neon
00000020 e92d5ff0 push.w {r4, r5, r6, r7, r8, r9, r10, r11, r12, lr}
...</pre>

== ARMv8 Builds ==

If you need SHA for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>sha1-armv8.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl sha1-armv8.pl linux64 sha1-armv8.S; then
echo "Failed to translate SHA source file"
exit 1
fi</pre>

<tt>sha1-armv8.pl</tt> provides the following function:

* <tt>sha1_block_armv8</tt>

If you are building for an Apple M1 you may need to use flavor <tt>ios64</tt>. The translate script does not handle <tt>osx64</tt> properly.

[[Category:Cryptogams]]

Cryptogams AES

2021-03-14T06:09:53Z

Jwalton: Add info on Apple M1 builds.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 AES implementation. According to the head notes the ARMv4 implementation runs around 22 to 40 cycles per byte (cpb). Typical C/C++ implementations run around 50 to 80 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>aes-armv4.h</tt> and <tt>aes-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' aes-armv4.h aes-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation operates in ECB mode and encrypts or decrypts full AES blocks. You are responsible for things like padding and side channel counter-measures.

At the moment Clang is miscompiling <tt>aes-armv4.S</tt>. Also see [https://bugs.llvm.org/show_bug.cgi?id=38133 LLVM Issue 38133]. You can work around the problem by compiling <tt>aes-armv4.S</tt> with <tt>-mthumb</tt>, but all data must be aligned. If you don't use aligned buffers then a <tt>SIGBUS</tt> could occur.

==Obtain Source Files==

There are two source files you need for Cryptogams AES. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/aes/asm/aes-armv4.pl <tt>aes-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/aes/asm/aes-armv4.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>aes-armv4.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>aes-armv4.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>aes-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl aes-armv4.pl linux32 aes-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>aes-armv4</tt> happens to have the requirement.

<pre>$ cat aes-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' aes-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' aes-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>aes-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>aes-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c aes-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c aes-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv5t -c aes-armv4.S
$ nm aes-armv4.o
000011c0 T AES_decrypt
00000540 T AES_encrypt
00000b60 T AES_set_decrypt_key
00000b80 T AES_set_enc2dec_key
00000820 T AES_set_encrypt_key
00000cc0 t AES_Td
00000000 t AES_Te
000012c0 t _armv4_AES_decrypt
00000640 t _armv4_AES_encrypt
00000b80 t _armv4_AES_set_enc2dec_key
00000820 t _armv4_AES_set_encrypt_key</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble aes-armv4.o
aes-armv4.o: file format elf32-littlearm
...

00000b60 <AES_set_decrypt_key>:
b60: e52de004 push {lr} ; (str lr, [sp, #-4]!)
b64: ebffff2d bl 820 <AES_set_encrypt_key>
b68: e3300000 teq r0, #0
b6c: e49de004 pop {lr} ; (ldr lr, [sp], #4)
b70: 1afffff9 bne b5c <AES_set_encrypt_key+0x33c>
b74: e1a00002 mov r0, r2
b78: e1a01002 mov r1, r2
b7c: eaffffff b b80 <AES_set_enc2dec_key>

...</pre>

And trace it back to the source code in <tt>aes-armv4.S</tt>.

<pre>.globl AES_set_decrypt_key
.type AES_set_decrypt_key,%function
.align 5
AES_set_decrypt_key:
str lr,[sp,#-4]! @ push lr
bl _armv4_AES_set_encrypt_key
teq r0,#0
ldr lr,[sp],#4 @ pop lr
bne .Labrt

mov r0,r2 @ AES_set_encrypt_key preserves r2,
mov r1,r2 @ which is AES_KEY *key
b _armv4_AES_set_enc2dec_key
.size AES_set_decrypt_key,.-AES_set_decrypt_key</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. The functions of interest are <tt>AES_set_encrypt_key</tt>, <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>AES_set_encrypt_key</tt>.

<pre>openssl$ grep -nIR AES_set_encrypt_key | grep '\.c'
...
crypto/aes/aes_core.c:632:int AES_set_encrypt_key(const unsigned char *userKey, const int bits,</pre>

Examining <tt>aes_core.c:632</tt> reveals the following.

<pre>openssl$ cat -n crypto/aes/aes_core.c
...
632 int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
633 AES_KEY *key)
634 {
...
728 return 0;
729 }</pre>

The next piece of information to discover is <tt>AES_KEY</tt>. Again a quick <tt>grep</tt> leads you to <tt>aes_key_st</tt>.

<pre>openssl$ grep -nIR AES_KEY | grep typedef
include/openssl/aes.h:39:typedef struct aes_key_st AES_KEY;

openssl$ cat -n include/openssl/aes.h
...

31 struct aes_key_st {
32 # ifdef AES_LONG
33 unsigned long rd_key[4 * (AES_MAXNR + 1)];
34 # else
35 unsigned int rd_key[4 * (AES_MAXNR + 1)];
36 # endif
37 int rounds;
38 };
39 typedef struct aes_key_st AES_KEY;</pre>

Finally, you need <tt>AES_MAXNR</tt> from <tt>aes.h</tt>.

<pre>openssl$ grep -IR AES_MAXNR | grep define
include/openssl/aes.h:# define AES_MAXNR 14</pre>

Lather, rinse repeat for <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>. <tt>AES_encrypt</tt> can be found at <tt>crypto/aes/aes_core.c:787</tt>.

<pre>openssl$ grep -nIR AES_encrypt | grep '\.c'
...
crypto/aes/aes_core.c:787:void AES_encrypt(...)

openssl$ cat -n crypto/aes/aes_core.c
...
783 /*
784 * Encrypt a single block
785 * in and out can overlap
786 */
787 void AES_encrypt(const unsigned char *in, unsigned char *out,
788 const AES_KEY *key) {</pre>

And <tt>AES_decrypt</tt> can be found at <tt>aes_core.c:978</tt>.

<pre>openssl$ grep -nIR AES_decrypt | grep '\.c'
...
crypto/aes/aes_core.c:978:void AES_decrypt(...)

openssl$ cat -n crypto/aes/aes_core.c

974 /*
975 * Decrypt a single block
976 * in and out can overlap
977 */
978 void AES_decrypt(const unsigned char *in, unsigned char *out,
979 const AES_KEY *key)
980 {
</pre>

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use.

<pre>/* Header file for use with Cryptogam's ARMv4 AES. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_AES. */

#ifndef CRYPTOGAMS_AES_ARMV4_H
#define CRYPTOGAMS_AES_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

#define AES_MAXNR 14

typedef struct AES_KEY_st {
unsigned int rd_key[4 * (AES_MAXNR + 1)];
int rounds;
} AES_KEY;

int AES_set_encrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
int AES_set_decrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
void AES_encrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);
void AES_decrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_AES_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's AES with your program.

<pre>$ gcc -std=c99 aes-armv4-test.c ./aes-armv4.o -o aes-armv4-test.exe
$ ./aes-armv4-test.exe
Encrypted plaintext!
Decrypted ciphertext!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "aes-armv4.h"

int main(int argc, char* argv[])
{
/* Test key from FIPS 197 */
const uint8_t kb[] = {
0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

const uint8_t pb[] = {
0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a
};

const uint8_t cb[] = {
0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97
};

/* Scratch */
uint8_t buf[16];
int result;

/********************************************/

AES_KEY ekey;
result = AES_set_encrypt_key(kb, sizeof(kb)*8, & ekey);
assert(result == 0);

AES_encrypt(pb, buf, &ekey);
if (memcmp(cb, buf, 16) == 0)
printf("Encrypted plaintext!\n");
else
printf("Failed to encrypt plaintext!\n");

/********************************************/

AES_KEY dkey;
result = AES_set_decrypt_key(kb, sizeof(kb)*8, & dkey);
assert(result == 0);

AES_decrypt(cb, buf, &dkey);
if (memcmp(pb, buf, 16) == 0)
printf("Decrypted ciphertext!\n");
else
printf("Failed to decrypt ciphertext!\n");

return 0;
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>AES_set_encrypt_key</tt> and <tt>AES_set_decrypt_key</tt> are the names of two functions in the source code, and they will show up in the object file and when compiled and the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for AES you should rename all <tt>AES_*</tt> names. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_decrypt/MYLIB_AES_decrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_encrypt/MYLIB_AES_encrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_decrypt_key/MYLIB_AES_set_decrypt_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_enc2dec_key/MYLIB_AES_set_enc2dec_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_encrypt_key/MYLIB_AES_set_encrypt_key/g' aes_armv4.h aes_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include "aes-armv4.h"

typedef unsigned char byte;

int main(int argc, char* argv[])
{
const unsigned int STEPS = 128;
byte* buf = (byte*)malloc(STEPS*16+16);
memset(buf, 0x00, 16);

AES_KEY ekey;
(void)AES_set_encrypt_key(buf, 16*8, &ekey);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
AES_encrypt(&buf[idx+i], &buf[idx+i+1], &ekey);
total += 16*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 950 MHz */
const double cpuFreq = 950.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a BananaPi with a Cortex-A7 Sun7i SoC running at 950 MHz. A C/C++ AES implementation runs about 65 cpb on the dev-board. Notice <tt>aes-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -march=armv7 -c aes-armv4.S -o aes-armv7.o
$ gcc -O3 -std=c99 aes-armv7-test.c aes-armv7.o -o aes-armv7-test.exe
$ ./aes-armv7-test.exe
78426112 bytes
24.93 mbs
36.34 cpb</pre>

And the following is from a Wandboard Dual with a NXP i.MX6 Cortex-A9 running at 1 GHz. A C/C++ implementation runs around 40 cpb.

<pre>$ ./aes-armv7-test.exe
106029056 bytes
33.80 mbs
26.80 cpb</pre>

== Autotools ==

If you are using Autotools you can add the following to <tt>configure.ac</tt> and <tt>Makefile.am</tt> to conditionally compile <tt>aes-armv4.S</tt> for A-32 platforms. You will need to detect ARM A-32 and set <tt>IS_ARM32</tt> to non-0. Also see [https://www.gnu.org/software/automake/manual/html_node/Assembly-Support.html Automake Assembly Support] in section 8.13 of the manual.

First, the <tt>configure.ac</tt> recipe:

<pre># Set ASM tools
AC_SUBST([CCAS], [$CC])
AC_SUBST([CCASFLAGS], [$CFLAGS])

# Used by Makefile.am to compile aes-armv4.S
if test "$IS_ARM32" != "0"; then

## Save CFLAGS
SAVED_CFLAGS="$CFLAGS"

CFLAGS="-march=armv7-a -Wa,--noexecstack"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then

AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])

else

CFLAGS="-march=armv7-a"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then
AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])
else
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi
fi

## Restore CFLAGS
CFLAGS="$SAVED_CFLAGS"
else
# Required for other platforms
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi</pre>

Second, the <tt>Makefile.am</tt> recipe:

<pre>if CRYPTOGAMS_AES

aes_armv4_la_SOURCES = aes-armv4.S
aes_armv4_la_CCASFLAGS = $(AM_CFLAGS) $(CRYPTOGAMS_AES)

pkginclude_HEADERS += aes-armv4.h

endif</pre>

== ARMv8 Builds ==

If you need AES for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>aesv8-armx.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl aesv8-armx.pl linux64 armx_aes.S; then
echo "Failed to translate AES source file"
exit 1
fi</pre>

<tt>aesv8-armx.pl</tt> provides the following functions:

* <tt>aes_v8_set_encrypt_key</tt>
* <tt>aes_v8_set_decrypt_key</tt>
* <tt>aes_v8_encrypt</tt>
* <tt>aes_v8_decrypt</tt>

If you are building for an Apple M1 you may need to use flavor <tt>ios64</tt>. The translate script does not handle <tt>osx64</tt> properly.

[[Category:Cryptogams]]

Cryptogams SHA

2021-03-12T15:23:17Z

Jwalton: Whitespace check-in.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 SHA-1 implementation. According to the head notes the ARMv4 implementation runs around 6.5 cycles per byte (cpb). Typical C/C++ implementations run around 10 to 20 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>sha1-armv4.h</tt> and <tt>sha1-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' sha1-armv4.h sha1-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation hashes full SHA blocks. You are responsible for things like padding and side channel counter-measures.

If you experience ''"unexpected reloc type 0x03"'' when building a shared object then see [https://sourceware.org/ml/binutils/2019-05/msg00287.html What does unexpected reloc type 0x03 mean?] on the Binutils mailing list.

==Obtain Source Files==

There are two source files you need for Cryptogams SHA. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/sha/asm/sha1-armv4-large.pl <tt>sha1-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/sha/asm/sha1-armv4-large.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>sha1-armv4-large.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>sha1-armv4-large.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>sha1-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl sha1-armv4-large.pl linux32 sha1-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>sha1-armv4</tt> happens to have the requirement.

<pre>$ cat sha1-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' sha1-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' sha1-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>sha1-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>sha1-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c sha1-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S
$ nm sha1-armv4.o
00000000 T sha1_block_data_order</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble sha1-armv4.o
sha1-armv4.o: file format elf32-littlearm

Disassembly of section .text:

00000000 <sha1_block_data_order>:
0: e92d5ff0 push {r4, r5, r6, r7, r8, r9, sl, fp, ip, lr}
4: e0812302 add r2, r1, r2, lsl #6
8: e89000f8 ldm r0, {r3, r4, r5, r6, r7}
c: e59f858c ldr r8, [pc, #1420] ; 5a0 <sha1_block_data_order+0x5a0>
10: e1a0e00d mov lr, sp
14: e24dd03c sub sp, sp, #60 ; 0x3c
18: e1a05f65 ror r5, r5, #30
1c: e1a06f66 ror r6, r6, #30

...</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. Fortunately there is one function of interest called <tt>sha1_block_data_order</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>sha1_block_data_order</tt>.

<pre>openssl$ grep -nIR sha1_block_data_order | grep '\.c'
crypto/evp/e_sha_cbc_hmac_sha1.c:95: void sha1_block_data_order(void *c, const void *p, size_t len);
crypto/evp/e_sha_cbc_hmac_sha1.c:115: sha1_block_data_order(c, ptr, len / SHA_CBLOCK);
crypto/evp/e_sha_cbc_hmac_sha1.c:615: sha1_block_data_order(&key->md, data, 1);
crypto/evp/e_sha_cbc_hmac_sha1.c:631: sha1_block_data_order(&key->md, data, 1);
...
</pre>

We need several more symbols, and and they are <tt>OPENSSL_armcap_P</tt>, <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

<pre>$ grep -nIR OPENSSL_armcap_P
...
crypto/armcap.c:20:unsigned int OPENSSL_armcap_P = 0;</pre>

Lather, rinse, repeat for <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use. While it is not obvious, the <tt>len</tt> parameter from [[#Determine_API|Determine API]] is a block count, not a byte count.

<pre>/* Header file for use with Cryptogam's ARMv4 SHA1. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_SHA. */

#ifndef CRYPTOGAMS_SHA1_ARMV4_H
#define CRYPTOGAMS_SHA1_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

extern unsigned int OPENSSL_armcap_P;
void sha1_block_data_order(void *state, const void *data, size_t blocks);

/* Auxval caps */
#ifndef HWCAP_NEON
# define HWCAP_NEON (1 << 12)
#endif
#ifndef HWCAP_SHA1
# define HWCAP_SHA1 (1 << 5)
#endif

/* OpenSSL caps */
#define ARMV7_NEON (1<<0)
#define ARMV8_SHA1 (1<<3)

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_SHA1_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's SHA with your program.

<pre>$ gcc -std=c99 sha1-armv4-test.c ./sha1-armv4.o -o sha1-armv4-test.exe
$ ./sha1-armv4-test.exe
SHA1 hash of empty message: DA39A3EE5E6B4B0D...
Success!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

/* empty message with padding */
uint8_t message[64];
memset(message, 0x00, sizeof(message));
message[0] = 0x80;

/* initial state */
uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

sha1_block_data_order(state, message, 1);

const uint8_t b1 = (uint8_t)(state[0] >> 24);
const uint8_t b2 = (uint8_t)(state[0] >> 16);
const uint8_t b3 = (uint8_t)(state[0] >> 8);
const uint8_t b4 = (uint8_t)(state[0] >> 0);
const uint8_t b5 = (uint8_t)(state[1] >> 24);
const uint8_t b6 = (uint8_t)(state[1] >> 16);
const uint8_t b7 = (uint8_t)(state[1] >> 8);
const uint8_t b8 = (uint8_t)(state[1] >> 0);

/* DA39A3EE5E6B4B0D... */
printf("SHA1 hash of empty message: ");
printf("%02X%02X%02X%02X%02X%02X%02X%02X...\n",
b1, b2, b3, b4, b5, b6, b7, b8);

int success = ((b1 == 0xDA) && (b2 == 0x39) && (b3 == 0xA3) && (b4 == 0xEE) &&
(b5 == 0x5E) && (b6 == 0x6B) && (b7 == 0x4B) && (b8 == 0x0D));

if (success)
printf("Success!\n");
else
printf("Failure!\n");

return (success != 0 ? 0 : 1);
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>sha1_block_data_order</tt> is the names of function in the source code, and they will show up in the object file and when compiled and in the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for SHA-1 you should rename <tt>sha1_block_data_order</tt> and <tt>OPENSSL_armcap_P</tt>. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' sha1_armv4.h sha1_armv4.S
sed -i 's/sha1_block_data_order/MYLIB_sha1_block_data_order/g' sha1_armv4.h sha1_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* set processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

const unsigned int STEPS = 128;
uint8_t* buf = (uint8_t*)malloc(STEPS*64+64);
memset(buf, 0x00, 16);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
sha1_block_data_order(state, buf, idx+1);
total += 64*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 1 GHz */
const double cpuFreq = 1000.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a [https://www.amazon.com/gp/product/B07D4L7GXZ Libre Computer Tritium H3] with a Cortex-A7 Sun7i SoC running at 1 GHz. A C/C++ SHA implementation runs about 22 cpb on the dev-board. Notice <tt>sha1-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -std=c99 -march=armv7 -c sha1-armv4.S -o sha1-armv7.o
$ gcc -O3 -std=c99 sha1-armv7-test.c sha1-armv7.o -o sha1-armv7-test.exe
$ ./sha1-armv7-test.exe
180994048 bytes
57.59 mbs
16.56 cpb</pre>

== iOS Builds ==

<tt>sha1-armv4</tt> can be configured for iOS. Simply use <tt>ios32</tt> or <tt>ios64</tt> instead of <tt>linux32</tt> as shown below.

<pre>$ perl sha1-armv4-large.pl ios32 sha1-armv4.S
$ clang -arch armv7 sha1-armv4.S -c</pre>

And then:

<pre>$ nm sha1-armv4.o
000012d0 s OPENSSL_armcap_P
00000004 C _OPENSSL_armcap_P
00000000 T _sha1_block_data_order
00001100 t sha1_block_data_order_armv8
00000560 t sha1_block_data_order_neon

$ otool -tV sha1-armv4.o
sha1-armv4.o:
(__TEXT,__text) section
_sha1_block_data_order:
00000000 f8dfc4ec ldr.w r12, [pc, #0x4ec]
00000004 f2af0308 subw r3, pc, #0x8
00000008 f853c00c ldr.w r12, [r3, r12]
0000000c f8dcc000 ldr.w r12, [r12]
00000010 f01c0f08 tst.w r12, #0x8
00000014 f0418074 bne.w sha1_block_data_order_armv8
00000018 f01c0f01 tst.w r12, #0x1
0000001c f04082a0 bne.w sha1_block_data_order_neon
00000020 e92d5ff0 push.w {r4, r5, r6, r7, r8, r9, r10, r11, r12, lr}
...</pre>

== ARMv8 Builds ==

If you need SHA for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>sha1-armv8.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl sha1-armv8.pl linux64 sha1-armv8.S; then
echo "Failed to translate SHA source file"
exit 1
fi</pre>

<tt>sha1-armv8.pl</tt> provides the following functions:

* <tt>sha1_block_armv8</tt>

[[Category:Cryptogams]]

Cryptogams SHA

2021-03-12T15:00:41Z

Jwalton: Use linux64, not linux32, for ARMv8 builds.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 SHA-1 implementation. According to the head notes the ARMv4 implementation runs around 6.5 cycles per byte (cpb). Typical C/C++ implementations run around 10 to 20 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>sha1-armv4.h</tt> and <tt>sha1-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' sha1-armv4.h sha1-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation hashes full SHA blocks. You are responsible for things like padding and side channel counter-measures.

If you experience ''"unexpected reloc type 0x03"'' when building a shared object then see [https://sourceware.org/ml/binutils/2019-05/msg00287.html What does unexpected reloc type 0x03 mean?] on the Binutils mailing list.

==Obtain Source Files==

There are two source files you need for Cryptogams SHA. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/sha/asm/sha1-armv4-large.pl <tt>sha1-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/sha/asm/sha1-armv4-large.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>sha1-armv4-large.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>sha1-armv4-large.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>sha1-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl sha1-armv4-large.pl linux32 sha1-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>sha1-armv4</tt> happens to have the requirement.

<pre>$ cat sha1-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' sha1-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' sha1-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>sha1-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>sha1-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c sha1-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S
$ nm sha1-armv4.o
00000000 T sha1_block_data_order</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble sha1-armv4.o
sha1-armv4.o: file format elf32-littlearm

Disassembly of section .text:

00000000 <sha1_block_data_order>:
0: e92d5ff0 push {r4, r5, r6, r7, r8, r9, sl, fp, ip, lr}
4: e0812302 add r2, r1, r2, lsl #6
8: e89000f8 ldm r0, {r3, r4, r5, r6, r7}
c: e59f858c ldr r8, [pc, #1420] ; 5a0 <sha1_block_data_order+0x5a0>
10: e1a0e00d mov lr, sp
14: e24dd03c sub sp, sp, #60 ; 0x3c
18: e1a05f65 ror r5, r5, #30
1c: e1a06f66 ror r6, r6, #30

...</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. Fortunately there is one function of interest called <tt>sha1_block_data_order</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>sha1_block_data_order</tt>.

<pre>openssl$ grep -nIR sha1_block_data_order | grep '\.c'
crypto/evp/e_sha_cbc_hmac_sha1.c:95: void sha1_block_data_order(void *c, const void *p, size_t len);
crypto/evp/e_sha_cbc_hmac_sha1.c:115: sha1_block_data_order(c, ptr, len / SHA_CBLOCK);
crypto/evp/e_sha_cbc_hmac_sha1.c:615: sha1_block_data_order(&key->md, data, 1);
crypto/evp/e_sha_cbc_hmac_sha1.c:631: sha1_block_data_order(&key->md, data, 1);
...
</pre>

We need several more symbols, and and they are <tt>OPENSSL_armcap_P</tt>, <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

<pre>$ grep -nIR OPENSSL_armcap_P
...
crypto/armcap.c:20:unsigned int OPENSSL_armcap_P = 0;</pre>

Lather, rinse, repeat for <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use. While it is not obvious, the <tt>len</tt> parameter from [[#Determine_API|Determine API]] is a block count, not a byte count.

<pre>/* Header file for use with Cryptogam's ARMv4 SHA1. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_SHA. */

#ifndef CRYPTOGAMS_SHA1_ARMV4_H
#define CRYPTOGAMS_SHA1_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

extern unsigned int OPENSSL_armcap_P;
void sha1_block_data_order(void *state, const void *data, size_t blocks);

/* Auxval caps */
#ifndef HWCAP_NEON
# define HWCAP_NEON (1 << 12)
#endif
#ifndef HWCAP_SHA1
# define HWCAP_SHA1 (1 << 5)
#endif

/* OpenSSL caps */
#define ARMV7_NEON (1<<0)
#define ARMV8_SHA1 (1<<3)

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_SHA1_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's SHA with your program.

<pre>$ gcc -std=c99 sha1-armv4-test.c ./sha1-armv4.o -o sha1-armv4-test.exe
$ ./sha1-armv4-test.exe
SHA1 hash of empty message: DA39A3EE5E6B4B0D...
Success!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

/* empty message with padding */
uint8_t message[64];
memset(message, 0x00, sizeof(message));
message[0] = 0x80;

/* initial state */
uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

sha1_block_data_order(state, message, 1);

const uint8_t b1 = (uint8_t)(state[0] >> 24);
const uint8_t b2 = (uint8_t)(state[0] >> 16);
const uint8_t b3 = (uint8_t)(state[0] >> 8);
const uint8_t b4 = (uint8_t)(state[0] >> 0);
const uint8_t b5 = (uint8_t)(state[1] >> 24);
const uint8_t b6 = (uint8_t)(state[1] >> 16);
const uint8_t b7 = (uint8_t)(state[1] >> 8);
const uint8_t b8 = (uint8_t)(state[1] >> 0);

/* DA39A3EE5E6B4B0D... */
printf("SHA1 hash of empty message: ");
printf("%02X%02X%02X%02X%02X%02X%02X%02X...\n",
b1, b2, b3, b4, b5, b6, b7, b8);

int success = ((b1 == 0xDA) && (b2 == 0x39) && (b3 == 0xA3) && (b4 == 0xEE) &&
(b5 == 0x5E) && (b6 == 0x6B) && (b7 == 0x4B) && (b8 == 0x0D));

if (success)
printf("Success!\n");
else
printf("Failure!\n");

return (success != 0 ? 0 : 1);
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>sha1_block_data_order</tt> is the names of function in the source code, and they will show up in the object file and when compiled and in the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for SHA-1 you should rename <tt>sha1_block_data_order</tt> and <tt>OPENSSL_armcap_P</tt>. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' sha1_armv4.h sha1_armv4.S
sed -i 's/sha1_block_data_order/MYLIB_sha1_block_data_order/g' sha1_armv4.h sha1_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* set processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

const unsigned int STEPS = 128;
uint8_t* buf = (uint8_t*)malloc(STEPS*64+64);
memset(buf, 0x00, 16);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
sha1_block_data_order(state, buf, idx+1);
total += 64*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 1 GHz */
const double cpuFreq = 1000.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a [https://www.amazon.com/gp/product/B07D4L7GXZ Libre Computer Tritium H3] with a Cortex-A7 Sun7i SoC running at 1 GHz. A C/C++ SHA implementation runs about 22 cpb on the dev-board. Notice <tt>sha1-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -std=c99 -march=armv7 -c sha1-armv4.S -o sha1-armv7.o
$ gcc -O3 -std=c99 sha1-armv7-test.c sha1-armv7.o -o sha1-armv7-test.exe
$ ./sha1-armv7-test.exe
180994048 bytes
57.59 mbs
16.56 cpb</pre>

== iOS Builds ==

<tt>sha1-armv4</tt> can be configured for iOS. Simply use <tt>ios32</tt> or <tt>ios64</tt> instead of <tt>linux32</tt> as shown below.

<pre>$ perl sha1-armv4-large.pl ios32 sha1-armv4.S
$ clang -arch armv7 sha1-armv4.S -c</pre>

And then:

<pre>$ nm sha1-armv4.o
000012d0 s OPENSSL_armcap_P
00000004 C _OPENSSL_armcap_P
00000000 T _sha1_block_data_order
00001100 t sha1_block_data_order_armv8
00000560 t sha1_block_data_order_neon

$ otool -tV sha1-armv4.o
sha1-armv4.o:
(__TEXT,__text) section
_sha1_block_data_order:
00000000 f8dfc4ec ldr.w r12, [pc, #0x4ec]
00000004 f2af0308 subw r3, pc, #0x8
00000008 f853c00c ldr.w r12, [r3, r12]
0000000c f8dcc000 ldr.w r12, [r12]
00000010 f01c0f08 tst.w r12, #0x8
00000014 f0418074 bne.w sha1_block_data_order_armv8
00000018 f01c0f01 tst.w r12, #0x1
0000001c f04082a0 bne.w sha1_block_data_order_neon
00000020 e92d5ff0 push.w {r4, r5, r6, r7, r8, r9, r10, r11, r12, lr}
...</pre>

== ARMv8 Builds ==

If you need SHA for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>sha1-armv8.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl sha1-armv8.pl linux64 sha1-armv8.S; then
echo "Failed to translate SHA source file"
exit 1
fi</pre>

<tt>sha1-armv8.pl</tt> provides the following functions:

* <tt>sha1_block_armv8</tt>

[[Category:Cryptogams]]

Cryptogams AES

2021-03-12T15:00:18Z

Jwalton: Use linux64, not linux32, for ARMv8 builds.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 AES implementation. According to the head notes the ARMv4 implementation runs around 22 to 40 cycles per byte (cpb). Typical C/C++ implementations run around 50 to 80 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>aes-armv4.h</tt> and <tt>aes-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' aes-armv4.h aes-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation operates in ECB mode and encrypts or decrypts full AES blocks. You are responsible for things like padding and side channel counter-measures.

At the moment Clang is miscompiling <tt>aes-armv4.S</tt>. Also see [https://bugs.llvm.org/show_bug.cgi?id=38133 LLVM Issue 38133]. You can work around the problem by compiling <tt>aes-armv4.S</tt> with <tt>-mthumb</tt>, but all data must be aligned. If you don't use aligned buffers then a <tt>SIGBUS</tt> could occur.

==Obtain Source Files==

There are two source files you need for Cryptogams AES. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/aes/asm/aes-armv4.pl <tt>aes-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/aes/asm/aes-armv4.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>aes-armv4.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>aes-armv4.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>aes-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl aes-armv4.pl linux32 aes-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>aes-armv4</tt> happens to have the requirement.

<pre>$ cat aes-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' aes-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' aes-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>aes-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>aes-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c aes-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c aes-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv5t -c aes-armv4.S
$ nm aes-armv4.o
000011c0 T AES_decrypt
00000540 T AES_encrypt
00000b60 T AES_set_decrypt_key
00000b80 T AES_set_enc2dec_key
00000820 T AES_set_encrypt_key
00000cc0 t AES_Td
00000000 t AES_Te
000012c0 t _armv4_AES_decrypt
00000640 t _armv4_AES_encrypt
00000b80 t _armv4_AES_set_enc2dec_key
00000820 t _armv4_AES_set_encrypt_key</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble aes-armv4.o
aes-armv4.o: file format elf32-littlearm
...

00000b60 <AES_set_decrypt_key>:
b60: e52de004 push {lr} ; (str lr, [sp, #-4]!)
b64: ebffff2d bl 820 <AES_set_encrypt_key>
b68: e3300000 teq r0, #0
b6c: e49de004 pop {lr} ; (ldr lr, [sp], #4)
b70: 1afffff9 bne b5c <AES_set_encrypt_key+0x33c>
b74: e1a00002 mov r0, r2
b78: e1a01002 mov r1, r2
b7c: eaffffff b b80 <AES_set_enc2dec_key>

...</pre>

And trace it back to the source code in <tt>aes-armv4.S</tt>.

<pre>.globl AES_set_decrypt_key
.type AES_set_decrypt_key,%function
.align 5
AES_set_decrypt_key:
str lr,[sp,#-4]! @ push lr
bl _armv4_AES_set_encrypt_key
teq r0,#0
ldr lr,[sp],#4 @ pop lr
bne .Labrt

mov r0,r2 @ AES_set_encrypt_key preserves r2,
mov r1,r2 @ which is AES_KEY *key
b _armv4_AES_set_enc2dec_key
.size AES_set_decrypt_key,.-AES_set_decrypt_key</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. The functions of interest are <tt>AES_set_encrypt_key</tt>, <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>AES_set_encrypt_key</tt>.

<pre>openssl$ grep -nIR AES_set_encrypt_key | grep '\.c'
...
crypto/aes/aes_core.c:632:int AES_set_encrypt_key(const unsigned char *userKey, const int bits,</pre>

Examining <tt>aes_core.c:632</tt> reveals the following.

<pre>openssl$ cat -n crypto/aes/aes_core.c
...
632 int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
633 AES_KEY *key)
634 {
...
728 return 0;
729 }</pre>

The next piece of information to discover is <tt>AES_KEY</tt>. Again a quick <tt>grep</tt> leads you to <tt>aes_key_st</tt>.

<pre>openssl$ grep -nIR AES_KEY | grep typedef
include/openssl/aes.h:39:typedef struct aes_key_st AES_KEY;

openssl$ cat -n include/openssl/aes.h
...

31 struct aes_key_st {
32 # ifdef AES_LONG
33 unsigned long rd_key[4 * (AES_MAXNR + 1)];
34 # else
35 unsigned int rd_key[4 * (AES_MAXNR + 1)];
36 # endif
37 int rounds;
38 };
39 typedef struct aes_key_st AES_KEY;</pre>

Finally, you need <tt>AES_MAXNR</tt> from <tt>aes.h</tt>.

<pre>openssl$ grep -IR AES_MAXNR | grep define
include/openssl/aes.h:# define AES_MAXNR 14</pre>

Lather, rinse repeat for <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>. <tt>AES_encrypt</tt> can be found at <tt>crypto/aes/aes_core.c:787</tt>.

<pre>openssl$ grep -nIR AES_encrypt | grep '\.c'
...
crypto/aes/aes_core.c:787:void AES_encrypt(...)

openssl$ cat -n crypto/aes/aes_core.c
...
783 /*
784 * Encrypt a single block
785 * in and out can overlap
786 */
787 void AES_encrypt(const unsigned char *in, unsigned char *out,
788 const AES_KEY *key) {</pre>

And <tt>AES_decrypt</tt> can be found at <tt>aes_core.c:978</tt>.

<pre>openssl$ grep -nIR AES_decrypt | grep '\.c'
...
crypto/aes/aes_core.c:978:void AES_decrypt(...)

openssl$ cat -n crypto/aes/aes_core.c

974 /*
975 * Decrypt a single block
976 * in and out can overlap
977 */
978 void AES_decrypt(const unsigned char *in, unsigned char *out,
979 const AES_KEY *key)
980 {
</pre>

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use.

<pre>/* Header file for use with Cryptogam's ARMv4 AES. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_AES. */

#ifndef CRYPTOGAMS_AES_ARMV4_H
#define CRYPTOGAMS_AES_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

#define AES_MAXNR 14

typedef struct AES_KEY_st {
unsigned int rd_key[4 * (AES_MAXNR + 1)];
int rounds;
} AES_KEY;

int AES_set_encrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
int AES_set_decrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
void AES_encrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);
void AES_decrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_AES_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's AES with your program.

<pre>$ gcc -std=c99 aes-armv4-test.c ./aes-armv4.o -o aes-armv4-test.exe
$ ./aes-armv4-test.exe
Encrypted plaintext!
Decrypted ciphertext!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "aes-armv4.h"

int main(int argc, char* argv[])
{
/* Test key from FIPS 197 */
const uint8_t kb[] = {
0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

const uint8_t pb[] = {
0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a
};

const uint8_t cb[] = {
0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97
};

/* Scratch */
uint8_t buf[16];
int result;

/********************************************/

AES_KEY ekey;
result = AES_set_encrypt_key(kb, sizeof(kb)*8, & ekey);
assert(result == 0);

AES_encrypt(pb, buf, &ekey);
if (memcmp(cb, buf, 16) == 0)
printf("Encrypted plaintext!\n");
else
printf("Failed to encrypt plaintext!\n");

/********************************************/

AES_KEY dkey;
result = AES_set_decrypt_key(kb, sizeof(kb)*8, & dkey);
assert(result == 0);

AES_decrypt(cb, buf, &dkey);
if (memcmp(pb, buf, 16) == 0)
printf("Decrypted ciphertext!\n");
else
printf("Failed to decrypt ciphertext!\n");

return 0;
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>AES_set_encrypt_key</tt> and <tt>AES_set_decrypt_key</tt> are the names of two functions in the source code, and they will show up in the object file and when compiled and the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for AES you should rename all <tt>AES_*</tt> names. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_decrypt/MYLIB_AES_decrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_encrypt/MYLIB_AES_encrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_decrypt_key/MYLIB_AES_set_decrypt_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_enc2dec_key/MYLIB_AES_set_enc2dec_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_encrypt_key/MYLIB_AES_set_encrypt_key/g' aes_armv4.h aes_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include "aes-armv4.h"

typedef unsigned char byte;

int main(int argc, char* argv[])
{
const unsigned int STEPS = 128;
byte* buf = (byte*)malloc(STEPS*16+16);
memset(buf, 0x00, 16);

AES_KEY ekey;
(void)AES_set_encrypt_key(buf, 16*8, &ekey);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
AES_encrypt(&buf[idx+i], &buf[idx+i+1], &ekey);
total += 16*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 950 MHz */
const double cpuFreq = 950.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a BananaPi with a Cortex-A7 Sun7i SoC running at 950 MHz. A C/C++ AES implementation runs about 65 cpb on the dev-board. Notice <tt>aes-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -march=armv7 -c aes-armv4.S -o aes-armv7.o
$ gcc -O3 -std=c99 aes-armv7-test.c aes-armv7.o -o aes-armv7-test.exe
$ ./aes-armv7-test.exe
78426112 bytes
24.93 mbs
36.34 cpb</pre>

And the following is from a Wandboard Dual with a NXP i.MX6 Cortex-A9 running at 1 GHz. A C/C++ implementation runs around 40 cpb.

<pre>$ ./aes-armv7-test.exe
106029056 bytes
33.80 mbs
26.80 cpb</pre>

== Autotools ==

If you are using Autotools you can add the following to <tt>configure.ac</tt> and <tt>Makefile.am</tt> to conditionally compile <tt>aes-armv4.S</tt> for A-32 platforms. You will need to detect ARM A-32 and set <tt>IS_ARM32</tt> to non-0. Also see [https://www.gnu.org/software/automake/manual/html_node/Assembly-Support.html Automake Assembly Support] in section 8.13 of the manual.

First, the <tt>configure.ac</tt> recipe:

<pre># Set ASM tools
AC_SUBST([CCAS], [$CC])
AC_SUBST([CCASFLAGS], [$CFLAGS])

# Used by Makefile.am to compile aes-armv4.S
if test "$IS_ARM32" != "0"; then

## Save CFLAGS
SAVED_CFLAGS="$CFLAGS"

CFLAGS="-march=armv7-a -Wa,--noexecstack"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then

AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])

else

CFLAGS="-march=armv7-a"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then
AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])
else
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi
fi

## Restore CFLAGS
CFLAGS="$SAVED_CFLAGS"
else
# Required for other platforms
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi</pre>

Second, the <tt>Makefile.am</tt> recipe:

<pre>if CRYPTOGAMS_AES

aes_armv4_la_SOURCES = aes-armv4.S
aes_armv4_la_CCASFLAGS = $(AM_CFLAGS) $(CRYPTOGAMS_AES)

pkginclude_HEADERS += aes-armv4.h

endif</pre>

== ARMv8 Builds ==

If you need AES for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>aesv8-armx.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl aesv8-armx.pl linux64 armx_aes.S; then
echo "Failed to translate AES source file"
exit 1
fi</pre>

<tt>aesv8-armx.pl</tt> provides the following functions:

* <tt>aes_v8_set_encrypt_key</tt>
* <tt>aes_v8_set_decrypt_key</tt>
* <tt>aes_v8_encrypt</tt>
* <tt>aes_v8_decrypt</tt>

[[Category:Cryptogams]]

Cryptogams AES

2021-03-12T14:53:11Z

Jwalton: Update title for ARMv8 AES builds.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 AES implementation. According to the head notes the ARMv4 implementation runs around 22 to 40 cycles per byte (cpb). Typical C/C++ implementations run around 50 to 80 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>aes-armv4.h</tt> and <tt>aes-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' aes-armv4.h aes-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation operates in ECB mode and encrypts or decrypts full AES blocks. You are responsible for things like padding and side channel counter-measures.

At the moment Clang is miscompiling <tt>aes-armv4.S</tt>. Also see [https://bugs.llvm.org/show_bug.cgi?id=38133 LLVM Issue 38133]. You can work around the problem by compiling <tt>aes-armv4.S</tt> with <tt>-mthumb</tt>, but all data must be aligned. If you don't use aligned buffers then a <tt>SIGBUS</tt> could occur.

==Obtain Source Files==

There are two source files you need for Cryptogams AES. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/aes/asm/aes-armv4.pl <tt>aes-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/aes/asm/aes-armv4.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>aes-armv4.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>aes-armv4.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>aes-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl aes-armv4.pl linux32 aes-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>aes-armv4</tt> happens to have the requirement.

<pre>$ cat aes-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' aes-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' aes-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>aes-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>aes-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c aes-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c aes-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv5t -c aes-armv4.S
$ nm aes-armv4.o
000011c0 T AES_decrypt
00000540 T AES_encrypt
00000b60 T AES_set_decrypt_key
00000b80 T AES_set_enc2dec_key
00000820 T AES_set_encrypt_key
00000cc0 t AES_Td
00000000 t AES_Te
000012c0 t _armv4_AES_decrypt
00000640 t _armv4_AES_encrypt
00000b80 t _armv4_AES_set_enc2dec_key
00000820 t _armv4_AES_set_encrypt_key</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble aes-armv4.o
aes-armv4.o: file format elf32-littlearm
...

00000b60 <AES_set_decrypt_key>:
b60: e52de004 push {lr} ; (str lr, [sp, #-4]!)
b64: ebffff2d bl 820 <AES_set_encrypt_key>
b68: e3300000 teq r0, #0
b6c: e49de004 pop {lr} ; (ldr lr, [sp], #4)
b70: 1afffff9 bne b5c <AES_set_encrypt_key+0x33c>
b74: e1a00002 mov r0, r2
b78: e1a01002 mov r1, r2
b7c: eaffffff b b80 <AES_set_enc2dec_key>

...</pre>

And trace it back to the source code in <tt>aes-armv4.S</tt>.

<pre>.globl AES_set_decrypt_key
.type AES_set_decrypt_key,%function
.align 5
AES_set_decrypt_key:
str lr,[sp,#-4]! @ push lr
bl _armv4_AES_set_encrypt_key
teq r0,#0
ldr lr,[sp],#4 @ pop lr
bne .Labrt

mov r0,r2 @ AES_set_encrypt_key preserves r2,
mov r1,r2 @ which is AES_KEY *key
b _armv4_AES_set_enc2dec_key
.size AES_set_decrypt_key,.-AES_set_decrypt_key</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. The functions of interest are <tt>AES_set_encrypt_key</tt>, <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>AES_set_encrypt_key</tt>.

<pre>openssl$ grep -nIR AES_set_encrypt_key | grep '\.c'
...
crypto/aes/aes_core.c:632:int AES_set_encrypt_key(const unsigned char *userKey, const int bits,</pre>

Examining <tt>aes_core.c:632</tt> reveals the following.

<pre>openssl$ cat -n crypto/aes/aes_core.c
...
632 int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
633 AES_KEY *key)
634 {
...
728 return 0;
729 }</pre>

The next piece of information to discover is <tt>AES_KEY</tt>. Again a quick <tt>grep</tt> leads you to <tt>aes_key_st</tt>.

<pre>openssl$ grep -nIR AES_KEY | grep typedef
include/openssl/aes.h:39:typedef struct aes_key_st AES_KEY;

openssl$ cat -n include/openssl/aes.h
...

31 struct aes_key_st {
32 # ifdef AES_LONG
33 unsigned long rd_key[4 * (AES_MAXNR + 1)];
34 # else
35 unsigned int rd_key[4 * (AES_MAXNR + 1)];
36 # endif
37 int rounds;
38 };
39 typedef struct aes_key_st AES_KEY;</pre>

Finally, you need <tt>AES_MAXNR</tt> from <tt>aes.h</tt>.

<pre>openssl$ grep -IR AES_MAXNR | grep define
include/openssl/aes.h:# define AES_MAXNR 14</pre>

Lather, rinse repeat for <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>. <tt>AES_encrypt</tt> can be found at <tt>crypto/aes/aes_core.c:787</tt>.

<pre>openssl$ grep -nIR AES_encrypt | grep '\.c'
...
crypto/aes/aes_core.c:787:void AES_encrypt(...)

openssl$ cat -n crypto/aes/aes_core.c
...
783 /*
784 * Encrypt a single block
785 * in and out can overlap
786 */
787 void AES_encrypt(const unsigned char *in, unsigned char *out,
788 const AES_KEY *key) {</pre>

And <tt>AES_decrypt</tt> can be found at <tt>aes_core.c:978</tt>.

<pre>openssl$ grep -nIR AES_decrypt | grep '\.c'
...
crypto/aes/aes_core.c:978:void AES_decrypt(...)

openssl$ cat -n crypto/aes/aes_core.c

974 /*
975 * Decrypt a single block
976 * in and out can overlap
977 */
978 void AES_decrypt(const unsigned char *in, unsigned char *out,
979 const AES_KEY *key)
980 {
</pre>

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use.

<pre>/* Header file for use with Cryptogam's ARMv4 AES. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_AES. */

#ifndef CRYPTOGAMS_AES_ARMV4_H
#define CRYPTOGAMS_AES_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

#define AES_MAXNR 14

typedef struct AES_KEY_st {
unsigned int rd_key[4 * (AES_MAXNR + 1)];
int rounds;
} AES_KEY;

int AES_set_encrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
int AES_set_decrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
void AES_encrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);
void AES_decrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_AES_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's AES with your program.

<pre>$ gcc -std=c99 aes-armv4-test.c ./aes-armv4.o -o aes-armv4-test.exe
$ ./aes-armv4-test.exe
Encrypted plaintext!
Decrypted ciphertext!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "aes-armv4.h"

int main(int argc, char* argv[])
{
/* Test key from FIPS 197 */
const uint8_t kb[] = {
0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

const uint8_t pb[] = {
0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a
};

const uint8_t cb[] = {
0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97
};

/* Scratch */
uint8_t buf[16];
int result;

/********************************************/

AES_KEY ekey;
result = AES_set_encrypt_key(kb, sizeof(kb)*8, & ekey);
assert(result == 0);

AES_encrypt(pb, buf, &ekey);
if (memcmp(cb, buf, 16) == 0)
printf("Encrypted plaintext!\n");
else
printf("Failed to encrypt plaintext!\n");

/********************************************/

AES_KEY dkey;
result = AES_set_decrypt_key(kb, sizeof(kb)*8, & dkey);
assert(result == 0);

AES_decrypt(cb, buf, &dkey);
if (memcmp(pb, buf, 16) == 0)
printf("Decrypted ciphertext!\n");
else
printf("Failed to decrypt ciphertext!\n");

return 0;
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>AES_set_encrypt_key</tt> and <tt>AES_set_decrypt_key</tt> are the names of two functions in the source code, and they will show up in the object file and when compiled and the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for AES you should rename all <tt>AES_*</tt> names. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_decrypt/MYLIB_AES_decrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_encrypt/MYLIB_AES_encrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_decrypt_key/MYLIB_AES_set_decrypt_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_enc2dec_key/MYLIB_AES_set_enc2dec_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_encrypt_key/MYLIB_AES_set_encrypt_key/g' aes_armv4.h aes_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include "aes-armv4.h"

typedef unsigned char byte;

int main(int argc, char* argv[])
{
const unsigned int STEPS = 128;
byte* buf = (byte*)malloc(STEPS*16+16);
memset(buf, 0x00, 16);

AES_KEY ekey;
(void)AES_set_encrypt_key(buf, 16*8, &ekey);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
AES_encrypt(&buf[idx+i], &buf[idx+i+1], &ekey);
total += 16*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 950 MHz */
const double cpuFreq = 950.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a BananaPi with a Cortex-A7 Sun7i SoC running at 950 MHz. A C/C++ AES implementation runs about 65 cpb on the dev-board. Notice <tt>aes-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -march=armv7 -c aes-armv4.S -o aes-armv7.o
$ gcc -O3 -std=c99 aes-armv7-test.c aes-armv7.o -o aes-armv7-test.exe
$ ./aes-armv7-test.exe
78426112 bytes
24.93 mbs
36.34 cpb</pre>

And the following is from a Wandboard Dual with a NXP i.MX6 Cortex-A9 running at 1 GHz. A C/C++ implementation runs around 40 cpb.

<pre>$ ./aes-armv7-test.exe
106029056 bytes
33.80 mbs
26.80 cpb</pre>

== Autotools ==

If you are using Autotools you can add the following to <tt>configure.ac</tt> and <tt>Makefile.am</tt> to conditionally compile <tt>aes-armv4.S</tt> for A-32 platforms. You will need to detect ARM A-32 and set <tt>IS_ARM32</tt> to non-0. Also see [https://www.gnu.org/software/automake/manual/html_node/Assembly-Support.html Automake Assembly Support] in section 8.13 of the manual.

First, the <tt>configure.ac</tt> recipe:

<pre># Set ASM tools
AC_SUBST([CCAS], [$CC])
AC_SUBST([CCASFLAGS], [$CFLAGS])

# Used by Makefile.am to compile aes-armv4.S
if test "$IS_ARM32" != "0"; then

## Save CFLAGS
SAVED_CFLAGS="$CFLAGS"

CFLAGS="-march=armv7-a -Wa,--noexecstack"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then

AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])

else

CFLAGS="-march=armv7-a"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then
AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])
else
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi
fi

## Restore CFLAGS
CFLAGS="$SAVED_CFLAGS"
else
# Required for other platforms
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi</pre>

Second, the <tt>Makefile.am</tt> recipe:

<pre>if CRYPTOGAMS_AES

aes_armv4_la_SOURCES = aes-armv4.S
aes_armv4_la_CCASFLAGS = $(AM_CFLAGS) $(CRYPTOGAMS_AES)

pkginclude_HEADERS += aes-armv4.h

endif</pre>

== ARMv8 Builds ==

If you need AES for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>aesv8-armx.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl aesv8-armx.pl linux32 armx_aes.S; then
echo "Failed to translate AES source file"
exit 1
fi</pre>

<tt>aesv8-armx.pl</tt> provides the following functions:

* <tt>aes_v8_set_encrypt_key</tt>
* <tt>aes_v8_set_decrypt_key</tt>
* <tt>aes_v8_encrypt</tt>
* <tt>aes_v8_decrypt</tt>

[[Category:Cryptogams]]

Cryptogams SHA

2021-03-12T14:52:23Z

Jwalton: Add info on ARMv8 programs.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 SHA-1 implementation. According to the head notes the ARMv4 implementation runs around 6.5 cycles per byte (cpb). Typical C/C++ implementations run around 10 to 20 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>sha1-armv4.h</tt> and <tt>sha1-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' sha1-armv4.h sha1-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation hashes full SHA blocks. You are responsible for things like padding and side channel counter-measures.

If you experience ''"unexpected reloc type 0x03"'' when building a shared object then see [https://sourceware.org/ml/binutils/2019-05/msg00287.html What does unexpected reloc type 0x03 mean?] on the Binutils mailing list.

==Obtain Source Files==

There are two source files you need for Cryptogams SHA. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/sha/asm/sha1-armv4-large.pl <tt>sha1-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/sha/asm/sha1-armv4-large.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>sha1-armv4-large.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>sha1-armv4-large.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>sha1-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl sha1-armv4-large.pl linux32 sha1-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>sha1-armv4</tt> happens to have the requirement.

<pre>$ cat sha1-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' sha1-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' sha1-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>sha1-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>sha1-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c sha1-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S
$ nm sha1-armv4.o
00000000 T sha1_block_data_order</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble sha1-armv4.o
sha1-armv4.o: file format elf32-littlearm

Disassembly of section .text:

00000000 <sha1_block_data_order>:
0: e92d5ff0 push {r4, r5, r6, r7, r8, r9, sl, fp, ip, lr}
4: e0812302 add r2, r1, r2, lsl #6
8: e89000f8 ldm r0, {r3, r4, r5, r6, r7}
c: e59f858c ldr r8, [pc, #1420] ; 5a0 <sha1_block_data_order+0x5a0>
10: e1a0e00d mov lr, sp
14: e24dd03c sub sp, sp, #60 ; 0x3c
18: e1a05f65 ror r5, r5, #30
1c: e1a06f66 ror r6, r6, #30

...</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. Fortunately there is one function of interest called <tt>sha1_block_data_order</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>sha1_block_data_order</tt>.

<pre>openssl$ grep -nIR sha1_block_data_order | grep '\.c'
crypto/evp/e_sha_cbc_hmac_sha1.c:95: void sha1_block_data_order(void *c, const void *p, size_t len);
crypto/evp/e_sha_cbc_hmac_sha1.c:115: sha1_block_data_order(c, ptr, len / SHA_CBLOCK);
crypto/evp/e_sha_cbc_hmac_sha1.c:615: sha1_block_data_order(&key->md, data, 1);
crypto/evp/e_sha_cbc_hmac_sha1.c:631: sha1_block_data_order(&key->md, data, 1);
...
</pre>

We need several more symbols, and and they are <tt>OPENSSL_armcap_P</tt>, <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

<pre>$ grep -nIR OPENSSL_armcap_P
...
crypto/armcap.c:20:unsigned int OPENSSL_armcap_P = 0;</pre>

Lather, rinse, repeat for <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use. While it is not obvious, the <tt>len</tt> parameter from [[#Determine_API|Determine API]] is a block count, not a byte count.

<pre>/* Header file for use with Cryptogam's ARMv4 SHA1. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_SHA. */

#ifndef CRYPTOGAMS_SHA1_ARMV4_H
#define CRYPTOGAMS_SHA1_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

extern unsigned int OPENSSL_armcap_P;
void sha1_block_data_order(void *state, const void *data, size_t blocks);

/* Auxval caps */
#ifndef HWCAP_NEON
# define HWCAP_NEON (1 << 12)
#endif
#ifndef HWCAP_SHA1
# define HWCAP_SHA1 (1 << 5)
#endif

/* OpenSSL caps */
#define ARMV7_NEON (1<<0)
#define ARMV8_SHA1 (1<<3)

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_SHA1_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's SHA with your program.

<pre>$ gcc -std=c99 sha1-armv4-test.c ./sha1-armv4.o -o sha1-armv4-test.exe
$ ./sha1-armv4-test.exe
SHA1 hash of empty message: DA39A3EE5E6B4B0D...
Success!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

/* empty message with padding */
uint8_t message[64];
memset(message, 0x00, sizeof(message));
message[0] = 0x80;

/* initial state */
uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

sha1_block_data_order(state, message, 1);

const uint8_t b1 = (uint8_t)(state[0] >> 24);
const uint8_t b2 = (uint8_t)(state[0] >> 16);
const uint8_t b3 = (uint8_t)(state[0] >> 8);
const uint8_t b4 = (uint8_t)(state[0] >> 0);
const uint8_t b5 = (uint8_t)(state[1] >> 24);
const uint8_t b6 = (uint8_t)(state[1] >> 16);
const uint8_t b7 = (uint8_t)(state[1] >> 8);
const uint8_t b8 = (uint8_t)(state[1] >> 0);

/* DA39A3EE5E6B4B0D... */
printf("SHA1 hash of empty message: ");
printf("%02X%02X%02X%02X%02X%02X%02X%02X...\n",
b1, b2, b3, b4, b5, b6, b7, b8);

int success = ((b1 == 0xDA) && (b2 == 0x39) && (b3 == 0xA3) && (b4 == 0xEE) &&
(b5 == 0x5E) && (b6 == 0x6B) && (b7 == 0x4B) && (b8 == 0x0D));

if (success)
printf("Success!\n");
else
printf("Failure!\n");

return (success != 0 ? 0 : 1);
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>sha1_block_data_order</tt> is the names of function in the source code, and they will show up in the object file and when compiled and in the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for SHA-1 you should rename <tt>sha1_block_data_order</tt> and <tt>OPENSSL_armcap_P</tt>. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' sha1_armv4.h sha1_armv4.S
sed -i 's/sha1_block_data_order/MYLIB_sha1_block_data_order/g' sha1_armv4.h sha1_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* set processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

const unsigned int STEPS = 128;
uint8_t* buf = (uint8_t*)malloc(STEPS*64+64);
memset(buf, 0x00, 16);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
sha1_block_data_order(state, buf, idx+1);
total += 64*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 1 GHz */
const double cpuFreq = 1000.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a [https://www.amazon.com/gp/product/B07D4L7GXZ Libre Computer Tritium H3] with a Cortex-A7 Sun7i SoC running at 1 GHz. A C/C++ SHA implementation runs about 22 cpb on the dev-board. Notice <tt>sha1-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -std=c99 -march=armv7 -c sha1-armv4.S -o sha1-armv7.o
$ gcc -O3 -std=c99 sha1-armv7-test.c sha1-armv7.o -o sha1-armv7-test.exe
$ ./sha1-armv7-test.exe
180994048 bytes
57.59 mbs
16.56 cpb</pre>

== iOS Builds ==

<tt>sha1-armv4</tt> can be configured for iOS. Simply use <tt>ios32</tt> or <tt>ios64</tt> instead of <tt>linux32</tt> as shown below.

<pre>$ perl sha1-armv4-large.pl ios32 sha1-armv4.S
$ clang -arch armv7 sha1-armv4.S -c</pre>

And then:

<pre>$ nm sha1-armv4.o
000012d0 s OPENSSL_armcap_P
00000004 C _OPENSSL_armcap_P
00000000 T _sha1_block_data_order
00001100 t sha1_block_data_order_armv8
00000560 t sha1_block_data_order_neon

$ otool -tV sha1-armv4.o
sha1-armv4.o:
(__TEXT,__text) section
_sha1_block_data_order:
00000000 f8dfc4ec ldr.w r12, [pc, #0x4ec]
00000004 f2af0308 subw r3, pc, #0x8
00000008 f853c00c ldr.w r12, [r3, r12]
0000000c f8dcc000 ldr.w r12, [r12]
00000010 f01c0f08 tst.w r12, #0x8
00000014 f0418074 bne.w sha1_block_data_order_armv8
00000018 f01c0f01 tst.w r12, #0x1
0000001c f04082a0 bne.w sha1_block_data_order_neon
00000020 e92d5ff0 push.w {r4, r5, r6, r7, r8, r9, r10, r11, r12, lr}
...</pre>

== ARMv8 Builds ==

If you need SHA for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>sha1-armv8.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl sha1-armv8.pl linux32 sha1-armv8.S; then
echo "Failed to translate SHA source file"
exit 1
fi</pre>

<tt>sha1-armv8.pl</tt> provides the following functions:

* <tt>sha1_block_armv8</tt>

[[Category:Cryptogams]]

Cryptogams AES

2021-03-12T14:48:31Z

Jwalton: Add info on ARMv8 programs.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 AES implementation. According to the head notes the ARMv4 implementation runs around 22 to 40 cycles per byte (cpb). Typical C/C++ implementations run around 50 to 80 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>aes-armv4.h</tt> and <tt>aes-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' aes-armv4.h aes-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation operates in ECB mode and encrypts or decrypts full AES blocks. You are responsible for things like padding and side channel counter-measures.

At the moment Clang is miscompiling <tt>aes-armv4.S</tt>. Also see [https://bugs.llvm.org/show_bug.cgi?id=38133 LLVM Issue 38133]. You can work around the problem by compiling <tt>aes-armv4.S</tt> with <tt>-mthumb</tt>, but all data must be aligned. If you don't use aligned buffers then a <tt>SIGBUS</tt> could occur.

==Obtain Source Files==

There are two source files you need for Cryptogams AES. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/aes/asm/aes-armv4.pl <tt>aes-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/aes/asm/aes-armv4.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>aes-armv4.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>aes-armv4.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>aes-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl aes-armv4.pl linux32 aes-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>aes-armv4</tt> happens to have the requirement.

<pre>$ cat aes-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' aes-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' aes-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>aes-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>aes-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c aes-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c aes-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv5t -c aes-armv4.S
$ nm aes-armv4.o
000011c0 T AES_decrypt
00000540 T AES_encrypt
00000b60 T AES_set_decrypt_key
00000b80 T AES_set_enc2dec_key
00000820 T AES_set_encrypt_key
00000cc0 t AES_Td
00000000 t AES_Te
000012c0 t _armv4_AES_decrypt
00000640 t _armv4_AES_encrypt
00000b80 t _armv4_AES_set_enc2dec_key
00000820 t _armv4_AES_set_encrypt_key</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble aes-armv4.o
aes-armv4.o: file format elf32-littlearm
...

00000b60 <AES_set_decrypt_key>:
b60: e52de004 push {lr} ; (str lr, [sp, #-4]!)
b64: ebffff2d bl 820 <AES_set_encrypt_key>
b68: e3300000 teq r0, #0
b6c: e49de004 pop {lr} ; (ldr lr, [sp], #4)
b70: 1afffff9 bne b5c <AES_set_encrypt_key+0x33c>
b74: e1a00002 mov r0, r2
b78: e1a01002 mov r1, r2
b7c: eaffffff b b80 <AES_set_enc2dec_key>

...</pre>

And trace it back to the source code in <tt>aes-armv4.S</tt>.

<pre>.globl AES_set_decrypt_key
.type AES_set_decrypt_key,%function
.align 5
AES_set_decrypt_key:
str lr,[sp,#-4]! @ push lr
bl _armv4_AES_set_encrypt_key
teq r0,#0
ldr lr,[sp],#4 @ pop lr
bne .Labrt

mov r0,r2 @ AES_set_encrypt_key preserves r2,
mov r1,r2 @ which is AES_KEY *key
b _armv4_AES_set_enc2dec_key
.size AES_set_decrypt_key,.-AES_set_decrypt_key</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. The functions of interest are <tt>AES_set_encrypt_key</tt>, <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>AES_set_encrypt_key</tt>.

<pre>openssl$ grep -nIR AES_set_encrypt_key | grep '\.c'
...
crypto/aes/aes_core.c:632:int AES_set_encrypt_key(const unsigned char *userKey, const int bits,</pre>

Examining <tt>aes_core.c:632</tt> reveals the following.

<pre>openssl$ cat -n crypto/aes/aes_core.c
...
632 int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
633 AES_KEY *key)
634 {
...
728 return 0;
729 }</pre>

The next piece of information to discover is <tt>AES_KEY</tt>. Again a quick <tt>grep</tt> leads you to <tt>aes_key_st</tt>.

<pre>openssl$ grep -nIR AES_KEY | grep typedef
include/openssl/aes.h:39:typedef struct aes_key_st AES_KEY;

openssl$ cat -n include/openssl/aes.h
...

31 struct aes_key_st {
32 # ifdef AES_LONG
33 unsigned long rd_key[4 * (AES_MAXNR + 1)];
34 # else
35 unsigned int rd_key[4 * (AES_MAXNR + 1)];
36 # endif
37 int rounds;
38 };
39 typedef struct aes_key_st AES_KEY;</pre>

Finally, you need <tt>AES_MAXNR</tt> from <tt>aes.h</tt>.

<pre>openssl$ grep -IR AES_MAXNR | grep define
include/openssl/aes.h:# define AES_MAXNR 14</pre>

Lather, rinse repeat for <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>. <tt>AES_encrypt</tt> can be found at <tt>crypto/aes/aes_core.c:787</tt>.

<pre>openssl$ grep -nIR AES_encrypt | grep '\.c'
...
crypto/aes/aes_core.c:787:void AES_encrypt(...)

openssl$ cat -n crypto/aes/aes_core.c
...
783 /*
784 * Encrypt a single block
785 * in and out can overlap
786 */
787 void AES_encrypt(const unsigned char *in, unsigned char *out,
788 const AES_KEY *key) {</pre>

And <tt>AES_decrypt</tt> can be found at <tt>aes_core.c:978</tt>.

<pre>openssl$ grep -nIR AES_decrypt | grep '\.c'
...
crypto/aes/aes_core.c:978:void AES_decrypt(...)

openssl$ cat -n crypto/aes/aes_core.c

974 /*
975 * Decrypt a single block
976 * in and out can overlap
977 */
978 void AES_decrypt(const unsigned char *in, unsigned char *out,
979 const AES_KEY *key)
980 {
</pre>

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use.

<pre>/* Header file for use with Cryptogam's ARMv4 AES. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_AES. */

#ifndef CRYPTOGAMS_AES_ARMV4_H
#define CRYPTOGAMS_AES_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

#define AES_MAXNR 14

typedef struct AES_KEY_st {
unsigned int rd_key[4 * (AES_MAXNR + 1)];
int rounds;
} AES_KEY;

int AES_set_encrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
int AES_set_decrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
void AES_encrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);
void AES_decrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_AES_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's AES with your program.

<pre>$ gcc -std=c99 aes-armv4-test.c ./aes-armv4.o -o aes-armv4-test.exe
$ ./aes-armv4-test.exe
Encrypted plaintext!
Decrypted ciphertext!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "aes-armv4.h"

int main(int argc, char* argv[])
{
/* Test key from FIPS 197 */
const uint8_t kb[] = {
0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

const uint8_t pb[] = {
0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a
};

const uint8_t cb[] = {
0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97
};

/* Scratch */
uint8_t buf[16];
int result;

/********************************************/

AES_KEY ekey;
result = AES_set_encrypt_key(kb, sizeof(kb)*8, & ekey);
assert(result == 0);

AES_encrypt(pb, buf, &ekey);
if (memcmp(cb, buf, 16) == 0)
printf("Encrypted plaintext!\n");
else
printf("Failed to encrypt plaintext!\n");

/********************************************/

AES_KEY dkey;
result = AES_set_decrypt_key(kb, sizeof(kb)*8, & dkey);
assert(result == 0);

AES_decrypt(cb, buf, &dkey);
if (memcmp(pb, buf, 16) == 0)
printf("Decrypted ciphertext!\n");
else
printf("Failed to decrypt ciphertext!\n");

return 0;
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>AES_set_encrypt_key</tt> and <tt>AES_set_decrypt_key</tt> are the names of two functions in the source code, and they will show up in the object file and when compiled and the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for AES you should rename all <tt>AES_*</tt> names. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_decrypt/MYLIB_AES_decrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_encrypt/MYLIB_AES_encrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_decrypt_key/MYLIB_AES_set_decrypt_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_enc2dec_key/MYLIB_AES_set_enc2dec_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_encrypt_key/MYLIB_AES_set_encrypt_key/g' aes_armv4.h aes_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include "aes-armv4.h"

typedef unsigned char byte;

int main(int argc, char* argv[])
{
const unsigned int STEPS = 128;
byte* buf = (byte*)malloc(STEPS*16+16);
memset(buf, 0x00, 16);

AES_KEY ekey;
(void)AES_set_encrypt_key(buf, 16*8, &ekey);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
AES_encrypt(&buf[idx+i], &buf[idx+i+1], &ekey);
total += 16*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 950 MHz */
const double cpuFreq = 950.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a BananaPi with a Cortex-A7 Sun7i SoC running at 950 MHz. A C/C++ AES implementation runs about 65 cpb on the dev-board. Notice <tt>aes-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -march=armv7 -c aes-armv4.S -o aes-armv7.o
$ gcc -O3 -std=c99 aes-armv7-test.c aes-armv7.o -o aes-armv7-test.exe
$ ./aes-armv7-test.exe
78426112 bytes
24.93 mbs
36.34 cpb</pre>

And the following is from a Wandboard Dual with a NXP i.MX6 Cortex-A9 running at 1 GHz. A C/C++ implementation runs around 40 cpb.

<pre>$ ./aes-armv7-test.exe
106029056 bytes
33.80 mbs
26.80 cpb</pre>

== Autotools ==

If you are using Autotools you can add the following to <tt>configure.ac</tt> and <tt>Makefile.am</tt> to conditionally compile <tt>aes-armv4.S</tt> for A-32 platforms. You will need to detect ARM A-32 and set <tt>IS_ARM32</tt> to non-0. Also see [https://www.gnu.org/software/automake/manual/html_node/Assembly-Support.html Automake Assembly Support] in section 8.13 of the manual.

First, the <tt>configure.ac</tt> recipe:

<pre># Set ASM tools
AC_SUBST([CCAS], [$CC])
AC_SUBST([CCASFLAGS], [$CFLAGS])

# Used by Makefile.am to compile aes-armv4.S
if test "$IS_ARM32" != "0"; then

## Save CFLAGS
SAVED_CFLAGS="$CFLAGS"

CFLAGS="-march=armv7-a -Wa,--noexecstack"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then

AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])

else

CFLAGS="-march=armv7-a"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then
AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])
else
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi
fi

## Restore CFLAGS
CFLAGS="$SAVED_CFLAGS"
else
# Required for other platforms
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi</pre>

Second, the <tt>Makefile.am</tt> recipe:

<pre>if CRYPTOGAMS_AES

aes_armv4_la_SOURCES = aes-armv4.S
aes_armv4_la_CCASFLAGS = $(AM_CFLAGS) $(CRYPTOGAMS_AES)

pkginclude_HEADERS += aes-armv4.h

endif</pre>

== ARMv8 ==

If you need AES for ARMv8 devices, which includes aarch64 and aarch32, then use <tt>aesv8-armx.pl</tt>. You would use something like this in your scripts:

<pre>if ! perl aesv8-armx.pl linux32 armx_aes.S; then
echo "Failed to translate AES source file"
exit 1
fi</pre>

<tt>aesv8-armx.pl</tt> provides the following functions:

* <tt>aes_v8_set_encrypt_key</tt>
* <tt>aes_v8_set_decrypt_key</tt>
* <tt>aes_v8_encrypt</tt>
* <tt>aes_v8_decrypt</tt>

[[Category:Cryptogams]]

License

2020-07-22T13:35:17Z

Jwalton: Update License terms. State current requirement to comply with both licenses.

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 license] is a combination of OpenSSL and Apache-style license. Both licenses must be complied with.

For OpenSSL 3.0 we are moving to purely an Apache 2.0 license; see our [https://www.openssl.org/blog/blog/categories/license/ blog posts].

We do not accept patches through the Wiki.

== 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]]

Compilation and Installation

2020-03-10T05:52:09Z

Jwalton: Add info on NO_FORK option.

The following page is a combination of the <tt>INSTALL</tt> file provided with the OpenSSL library and notes from the field. If you have questions about what you are doing or seeing, then you should consult <tt>INSTALL</tt> since it contains the commands and specifies the behavior by the development team.

OpenSSL uses a custom build system to configure the library. Configuration will allow the library to set up the recursive makefiles from <tt>makefile.org</tt>. Once configured, you use <tt>make</tt> to build the library. You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

You must use a C compiler to build the OpenSSL library. You cannot use a C++ compiler. Later, once the library is built, it is OK to create user programs with a C++ compiler. But the library proper must be built with a C compiler.

There are two generations of build system. First is the build system used in OpenSSL 1.0.2 and below. The instructions below apply to it. Second is the build system for OpenSSL 1.1.0 and above. The instructions are similar, but not the same. For example, the second generation abandons the monolithic <tt>Configure</tt> and places individual configurations in the <tt>Configurations</tt> directory. Also, the second generation is more platform agnostic and uses templates to produce a final, top level build file (<tt>Makefile</tt>, <tt>descrip.mms</tt>, what have you).

After you configure and build the library, you should always perform a <tt>make test</tt> to ensure the library performs as expected under its self tests. If you are building OpenSSL 1.1.0 and above, then you will also need PERL 5.10 or higher (see <tt>README.PERL</tt> for details).

OpenSSL's build system does not rely upon <tt>autotools</tt> or <tt>libtool</tt>. Also see [http://www.openssl.org/support/faq.html#MISC5 Why aren't tools like 'autoconf' and 'libtool' used?] in the OpenSSL FAQ.

== Retrieve source code ==

The OpenSSL source code can be downloaded from [http://www.openssl.org/source/ OpenSSL Source Tarballs] or any suitable [http://www.openssl.org/source/mirror.html ftp mirror]. There are various versions including stable as well as unstable versions.

The source code is managed via Git. Its referred to as Master. The repository is

: git://git.openssl.org/openssl.git

The source is also available via a [https://github.com/openssl/openssl GitHub] mirror. This repository is updated every 15 minutes.

* [[Use_of_Git|Accessing OpenSSL source code via Git]]

== Configuration ==

OpenSSL is configured for a particular platform with protocol and behavior options using <tt>Configure</tt> and <tt>config</tt>.

You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

=== Supported Platforms ===

You can run <tt>Configure LIST</tt> to see a list of available platforms.

<pre>$ ./Configure LIST
BC-32
BS2000-OSD
BSD-generic32
BSD-generic64
BSD-ia64
BSD-sparc64
BSD-sparcv8
BSD-x86
BSD-x86-elf
BSD-x86_64
Cygwin
Cygwin-x86_64
DJGPP
...</pre>

If your platform is not listed, then use a similar platform and tune the <tt>$cflags</tt> and <tt>$ldflags</tt> by making a copy of the configure line and giving it its own name. <tt>$cflags</tt> and <tt>$ldflags</tt> correspond to fields 2 and 6 in a configure line. An example of using a similar configure line is presented in [[Compilation_and_Installation#Using_RPATHs|Using RPATHs]].

=== Configure & Config ===

You use <tt>Configure</tt> and <tt>config</tt> to tune the compile and installation process through options and switches. The difference between is <tt>Configure</tt> properly handles the host-arch-compiler triplet, and <tt>config</tt> does not. <tt>config</tt> attempts to guess the triplet, so its a lot like autotool's <tt>config.guess</tt>.

You can usually use <tt>config</tt> and it will do the right thing (from Ubuntu 13.04, x64):

<pre>$ ./config
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring for linux-x86_64
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

Mac OS X can have issues (its often a neglected platform), and you will have to use <tt>Configure</tt>:

<pre> ./Configure darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

You can also configure on Darwin by exporting <tt>KERNEL_BITS</tt>:

<pre>$ export KERNEL_BITS=64
$ ./config shared no-ssl2 no-ssl3 enable-ec_nistp_64_gcc_128 --openssldir=/usr/local/ssl/macosx-x64/
Operating system: i686-apple-darwinDarwin Kernel Version 12.5.0: Sun Sep 29 13:33:47 PDT 2013; root:xnu-2050.48.12~1/RELEASE_X86_64
Configuring for darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

If you provide a option not known to configure or ask for help, then you get a brief help message:

<pre>$ ./Configure --help
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]</pre>

And if you supply an unknown triplet:

<pre>$ ./Configure darwin64-x86_64-clang
Configuring for darwin64-x86_64-clang
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]

pick os/compiler from:
BC-32 BS2000-OSD BSD-generic32 BSD-generic64 BSD-ia64 BSD-sparc64 BSD-sparcv8
BSD-x86 BSD-x86-elf BSD-x86_64 Cygwin Cygwin-pre1.3 DJGPP MPE/iX-gcc OS2-EMX
...

NOTE: If in doubt, on Unix-ish systems use './config'.</pre>

=== Dependencies ===

If you are prompted to run <tt>make depend</tt>, then you must do so. For OpenSSL 1.0.2 and below, its required to update the standard distribution once configuration options change.

<pre>Since you've disabled or enabled at least one algorithm, you need to do
the following before building:

make depend
</pre>

OpenSSL 1.1.0 and above performs the dependency step for you, so you should not see the message. However, you should perform a <tt>make clean</tt> to ensure the list of objects files is accurate after a reconfiguration.

== Configure Options ==

OpenSSL has been around a long time, and it carries around a lot of cruft. For example, from above, SSLv2 is enabled by default. SSLv2 is completely broken, and you should disable it during configuration. You can disable protocols and provide other options through <tt>Configure</tt> and <tt>config</tt>, and the following lists some of them.

'''Note''': if you specify a non-existent option, then the configure scripts will proceed without warning. For example, if you inadvertently specify '''no-sslv2''' rather than '''no-ssl2 no-ssl3''', the script will configure ''with'' SSLv2 and ''without'' warning for the unknown no-sslv2.

'''Note''': when building a shared object, both the static archive and shared objects are built. You do not need to do anything special to build both when '''shared''' is specified.

{| class="wikitable sortable" border="1"
|+ OpenSSL Library Options
|-
! scope="col" width="150px" | Option
! scope="col" class="unsortable" | Description
|-
| --prefix=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| --openssldir=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| -d || Debug build of the library. Optimizations are disabled (no <tt>-O3</tt> or similar) and <tt>libefence</tt> is used (<tt>apt-get install electric-fence</tt> or <tt>yum install electric-fence</tt>). TODO: Any other features?
|-
| shared || Build a shared object in addition to the static archive. You probably need a [[#Using_RPATHs|RPATH]] when enabling <tt>shared</tt> to ensure <tt>openssl</tt> uses the correct <tt>libssl</tt> and <tt>libcrypto</tt> after installation.
|-
| enable-ec_nistp_64_gcc_128 || Use on little endian platforms when GCC supports <tt>__uint128_t</tt>. ECDH is about 2 to 4 times faster. Not enabled by default because <tt>Configure</tt> can't determine it. Enable it if your compiler defines <tt>__SIZEOF_INT128__</tt>, the CPU is little endian and it tolerates unaligned data access.
|-
| enable-capieng || Enables the Microsoft CAPI engine on Windows platforms. Used to access the Windows Certificate Store. Also see [http://openssl.6102.n7.nabble.com/Using-Windows-certificate-store-through-OpenSSL-td46788.html Using Windows certificate store through OpenSSL] on the OpenSSL developer list.
|-
| no-ssl2 || Disables SSLv2. <tt>OPENSSL_NO_SSL2</tt> will be defined in the OpenSSL headers.
|-
| no-ssl3 || Disables SSLv3. <tt>OPENSSL_NO_SSL3</tt> will be defined in the OpenSSL headers.
|-
| no-comp || Disables compression independent of <tt>zlib</tt>. <tt>OPENSSL_NO_COMP</tt> will be defined in the OpenSSL headers.
|-
| no-idea || Disables IDEA algorithm. Unlike RC5 and MDC2, IDEA is enabled by default
|-
| no-asm || Disables assembly language routines (and uses C routines)
|-
| no-dtls || Disables DTLS in OpenSSL 1.1.0 and above
|-
| no-dtls1 || Disables DTLS in OpenSSL 1.0.2 and below
|-
| no-shared || Disables shared objects (only a static library is created)
|-
| no-hw || Disables hardware support (useful on mobile devices)
|-
| no-engine || Disables hardware support (useful on mobile devices)
|-
| no-threads || Disables threading support.
|-
| no-dso || Disables the OpenSSL DSO API (the library offers a shared object abstraction layer). If you disable DSO, then you must disable Engines also
|-
| no-err || Removes all error function names and error reason text to reduce footprint
|-
| no-npn/no-nextprotoneg || Disables Next Protocol Negotiation (NPN). Use <tt>no-nextprotoneg</tt> for 1.1.0 and above; and <tt>no-npn</tt> otherwise
|-
| no-psk || Disables Preshared Key (PSK). PSK provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-srp || Disables Secure Remote Password (SRP). SRP provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-ec2m || Used when configuring FIPS Capable Library with a FIPS Object Module that only includes prime curves. That is, use this switch if you use <tt>openssl-fips-ecp-2.0.5</tt>.
|-
| no-weak-ssl-ciphers || Disables RC4. Available in OpenSSL 1.1.0 and above.
|-
| -DXXX || Defines XXX. For example, <tt>-DOPENSSL_NO_HEARTBEATS</tt>.
|-
| -DPEDANTIC || Defines PEDANTIC. The library will avoid some undefined behavior, like casting an unaligned byte array to a different pointer type. This define should be used if building OpenSSL with undefined behavior sanitizer (<tt>-fsanitize=undefined</tt>).
|-
| -DOPENSSL_USE_IPV6=0 || Disables IPv6. Useful if OpenSSL encounters incorrect or inconsistent platform headers and mistakenly enables IPv6. Must be passed to <tt>Configure</tt> manually.
|-
| -DNO_FORK || Defines NO_FORK. Disables calls to <tt>fork</tt>. Useful for operating systems like AppleTVOS, WatchOS, AppleTVSimulator and WatchSimulator.
|-
| -L''something'', -l''something'', -K''something'', -Wl,''something'' || Linker options, will become part of LDFLAGS.
|-
| -''anythingelse'', +''anythingelse'' || Compiler options, will become part of CFLAGS.
|}

'''''Note''''': on older OSes, like CentOS 5, BSD 5, and Windows XP or Vista, you will need to configure with <tt>no-async</tt> when building OpenSSL 1.1.0 and above. The configuration system does not detect lack of the Posix feature on the platforms.

'''''Note''''': you can verify compiler support for <tt>__uint128_t</tt> with the following:

<pre># gcc -dM -E - </dev/null | grep __SIZEOF_INT128__
#define __SIZEOF_INT128__ 16</pre>

=== PREFIX and OPENSSLDIR ===

<tt>--prefix</tt> and <tt>--openssldir</tt> control the configuration of installed components. The behavior and interactions of <tt>--prefix</tt> and <tt>--openssldir</tt> are slightly different between OpenSSL 1.0.2 and below, and OpenSSL 1.1.0 and above.

The '''''rule of thumb''''' to use when you want something that "just works" for all recent versions of OpenSSL, including OpenSSL 1.0.2 and 1.1.0, is:

* specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>
* set <tt>--prefix</tt> and <tt>--openssldir</tt> to the same location

One word of caution is ''avoid'' <tt>--prefix=/usr</tt> when OpenSSL versions are '''''not''''' [[Binary_Compatibility|binary compatible]]. You will replace the distro's version of OpenSSL with your version of OpenSSL. It will most likely break everything, including the package management system.

'''OpenSSL 1.0.2 and below'''

It is usually ''not'' necessary to specify <tt>--prefix</tt>. If <tt>--prefix</tt> is ''not'' specified, then <tt>--openssldir</tt> is used. However, specifying ''only'' <tt>--prefix</tt> may result in broken builds because the 1.0.2 build system attempts to build in a FIPS configuration.

You can ''omit'' If <tt>--prefix</tt> and use <tt>--openssldir</tt>. In this case, the paths for <tt>--openssldir</tt> will be used during configuration. If <tt>--openssldir</tt> is not specified, the the default <tt>/usr/local/ssl</tt> is used.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

'''OpenSSL 1.1.0 and above'''

OpenSSL 1.1.0 changed the behavior of install rules. You should specify both <tt>--prefix</tt> and <tt>--openssldir</tt> to ensure <tt>make install</tt> works as expected.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

=== Debug Configuration ===

From the list above, its possible to quickly configure a "debug" build with <tt>./config -d</tt>. However, you can often get into a more amicable state ''without'' the [http://en.wikipedia.org/wiki/Electric_Fence Electric Fence] dependency by issuing:

<pre>$ ./config no-asm -g3 -O0 -fno-omit-frame-pointer -fno-inline-functions
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring OpenSSL version 1.1.0-pre5-dev (0x0x10100005L)
no-asm [option] OPENSSL_NO_ASM
...
Configuring for linux-x86_64
IsMK1MF =no
CC =gcc
CFLAG =-Wall -O3 -pthread -m64 -DL_ENDIAN -g3 -O0 -fno-omit-frame-pointer
...</pre>

Don't be alarmed about both <tt>-O3</tt> and <tt>-O0</tt>. The last setting ''"sticks"'', and that's the <tt>-O0</tt>.

If you are working in Visual Studio and you can't step into library calls, then see [http://stackoverflow.com/q/38249235 Step into not working, but can force stepping after some asm steps] on Stack Overflow.

=== Modifying Build Settings ===

Sometimes you need to work around OpenSSL's selections for building the library. For example, you might want to use <tt>-Os</tt> for a mobile device (rather than <tt>-O3</tt>), or you might want to use the <tt>clang</tt> compiler (rather than <tt>gcc</tt>).

In case like these, its often easier to modify <tt>Configure</tt> and <tt>Makefile.org</tt> rather than trying to add targets to the configure scripts. Below is a patch that modifies <tt>Configure</tt> and <tt>Makefile.org</tt> for use under the iOS 7.0 SDK (which lacks <tt>gcc</tt> in <tt>/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/</tt>):

* Modifies <tt>Configure</tt> to use <tt>clang</tt>
* Modifies <tt>Makefile.org</tt> to use <tt>clang</tt>
* Modifies <tt>CFLAG</tt> to use <tt>-Os</tt>
* Modifies <tt>MAKEDEPPROG</tt> to use <tt>$(CC) -M</tt>

Setting and resetting of <tt>LANG</tt> is required on Mac OSX to work around a <tt>sed</tt> bug or limitation.

<pre>OLD_LANG=$LANG
unset LANG

sed -i "" 's|\"iphoneos-cross\"\,\"llvm-gcc\:-O3|\"iphoneos-cross\"\,\"clang\:-Os|g' Configure
sed -i "" 's/CC= cc/CC= clang/g' Makefile.org
sed -i "" 's/CFLAG= -O/CFLAG= -Os/g' Makefile.org
sed -i "" 's/MAKEDEPPROG=makedepend/MAKEDEPPROG=$(CC) -M/g' Makefile.org

export LANG=$OLD_LANG</pre>

After modification, be sure to dclean and configure again so the new settings are picked up:

<pre>make dclean

./config
make depend
make all
...</pre>

=== Using RPATHs ===

<tt>RPATH</tt>'s are supported by default on the BSD platforms, but not others. If you are working on Linux and compatibles, then you have to manually add an RPATH. One of the easiest ways to add a <tt>RPATH</tt> is to configure with it as shown below.

<pre>./config -Wl,-rpath=/usr/local/ssl/lib</pre>

'''''Note well''''': you should use a RPATH when building both OpenSSL and your program. If you don't add a RPATH to both, then your program could runtime-link to the wrong version of OpenSSL.

You can also add an <tt>RPATH</tt> by hard coding the <tt>RPATH</tt> into a configure line. For example, on Debian x86_64 open the file <tt>Configure</tt> in an editor, copy <tt>linux-x86_64</tt>, name it <tt>linux-x86_64-rpath</tt>, and make the following change to add the <tt>-rpath</tt> option. Notice the addition of <tt>-Wl,-rpath=...</tt> in two places.

<pre>"linux-x86_64-rpath", "gcc:-m64 -DL_ENDIAN -O3 -Wall -Wl,-rpath=/usr/local/ssl/lib::
-D_REENTRANT::-Wl,-rpath=/usr/local/ssl/lib -ldl:SIXTY_FOUR_BIT_LONG RC4_CHUNK DES_INT DES_UNROLL:
${x86_64_asm}:elf:dlfcn:linux-shared:-fPIC:-m64:.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR):::64",</pre>

Above, fields 2 and 6 were changed. They correspond to <tt>$cflag</tt> and <tt>$ldflag</tt> in OpenSSL's builds system.

Then, Configure with the new configuration:

<pre>$ ./Configure linux-x86_64-rpath shared no-ssl2 no-ssl3 no-comp \
--openssldir=/usr/local/ssl enable-ec_nistp_64_gcc_128</pre>

Finally, after <tt>make</tt>, verify the settings stuck:

<pre>$ readelf -d ./libssl.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./libcrypto.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./apps/openssl | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]</pre>

Once you perform <tt>make install</tt>, then <tt>ldd</tt> will produce expected results:

<pre>$ ldd /usr/local/ssl/lib/libssl.so
linux-vdso.so.1 => (0x00007ffceff6c000)
ibcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007ff5eff96000)
...

$ ldd /usr/local/ssl/bin/openssl
linux-vdso.so.1 => (0x00007ffc30d3a000)
libssl.so.1.0.0 => /usr/local/ssl/lib/libssl.so.1.0.0 (0x00007f9e8372e000)
libcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007f9e832c0000)
...</pre>

=== FIPS Capable Library ===

If you want to use FIPS validated cryptography, you download, build and install the FIPS Object Module (<tt>openssl-fips-2.0.5.tar.gz</tt>) according to the [https://www.openssl.org/docs/fips/UserGuide-2.0.pdf FIPS User Guide 2.0] and [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.pdf FIPS 140-2 Security Policy]. You then download, build and install the FIPS Capable Library (<tt>openssl-1.0.1e.tar.gz</tt>).

When configuring the FIPS Capable Library, you must use <tt>fips</tt> as an option:

<pre>./config fips <other options ...></pre>

If you are configuring the FIPS Capable Library with only prime curves (<tt>openssl-fips-ecp-2.0.5.tar.gz</tt>), then you must configure with <tt>no-ec2m</tt>:

<pre>./config fips no-ec2m <other options ...></pre>

=== Compile Time Checking ===

If you disable an option during configure, you can check if it's available through <tt>OPENSSL_NO_*</tt> defines. OpenSSL writes the configure options to <tt><openssl/opensslconf.h></tt>. For example, if you want to know if SSLv3 is available, then you would perform the following in your code:

<pre>#include <openssl/opensslconf.h>
...

#if !defined(OPENSSL_NO_SSL3)
/* SSLv3 is available */
#endif</pre>

== Compilation ==

After configuring the library, you should run <tt>make</tt>. If prompted, there's usually no need to <tt>make depend</tt> since you are building from a clean download.

==== Quick ====

<pre>./config <nowiki><options ...> --openssldir=/usr/local/ssl</nowiki>
make
make test
sudo make install</pre>

Various options can be found examining the <tt>Configure</tt> file (there is a well commented block at its top). OpenSSL ships with SSLv2, SSLv3 and Compression enabled by default (see <tt>my $disabled</tt>), so you might want to use <tt>no-ssl2 no-ssl3</tt>, <tt>no-ssl3</tt>, and <tt>no-comp</tt>.

== Platfom specific ==

=== Linux ===

==== Intel ====

==== ARM ====

==== X32 (ILP32) ====

X32 uses the 32-bit data model (ILP32) on x86_64/amd64. To properly configure for X32 under current OpenSSL distributions, you must use <tt>Configure</tt> and use the x32 triplet:

<pre># ./Configure LIST | grep x32
linux-x32
...</pre>

Then:

<pre># ./Configure linux-x32
Configuring OpenSSL version 1.1.0-pre6-dev (0x0x10100006L)
no-asan [default] OPENSSL_NO_ASAN (skip dir)
...
Configuring for linux-x32
CC =gcc
CFLAG =-Wall -O3 -pthread -mx32 -DL_ENDIAN
SHARED_CFLAG =-fPIC
...</pre>

If using an amd64-compatible processor and GCC with that supports <tt>__uint128_t</tt>, then you usually add <tt>enable-ec_nistp_64_gcc_128 </tt> in addition to your other flags.

=== Windows ===
3noch wrote a VERY good guide in 2012 [https://web.archive.org/web/20161123004257/http://developer.covenanteyes.com/building-openssl-for-visual-studio// here] (PLEASE NOTE: the guide was written in 2012 and is no longer available at the original location; the link now points to an archived version at the Internet Archive Wayback Machine).

Like he said in his article, make absolutely sure to create separate directories for 32 and 64 bit versions.

==== W32 / Windows NT - Windows 9x ====

type INSTALL.W32

* you need Perl for Win32. Unless you will build on Cygwin, you will need ActiveState Perl, available from http://www.activestate.com/ActivePerl.
* one of the following C compilers:
** Visual C++
** Borland C
** GNU C (Cygwin or MinGW)
* Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ is required if you intend to utilize assembler modules. Note that NASM is now the only supported assembler.

==== W64 ====

Read first the INSTALL.W64 documentation note containing some specific 64bits information.
See also INSTALL.W32 that still provides additonnal build information common to both the 64 and 32 bit versions.

You may be surprised: the 64bit artefacts are indeed output in the out32* sub-directories and bear names ending *32.dll. Fact is the 64 bit compile target is so far an incremental change over the legacy 32bit windows target. Numerous compile flags are still labelled "32" although those do apply to both 32 and 64bit targets.

The important pre-requisites are to have PERL available (for essential file processing so as to prepare sources and scripts for the target OS) and of course a C compiler like Microsoft Visual Studio for C/C++. Also note the procedure changed at OpenSSL 1.1.0 and is more streamlined. Also see [https://stackoverflow.com/q/39076244/608639 Why there is no ms\do_ms.bat after perl Configure VC-WIN64A] on Stack Overflow.

=== OpenSSL 1.1.0 ===

For OpenSSL 1.1.0 and above perform these steps:

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# Extract the source files to your folder, here <code>cd c:\myPath\openssl</code>
# Launch Visual Studio tool x64 Cross Tools Command prompt
# Goto your defined folder <code>cd c:\myPath\openssl</code>
# Configure for the target OS with <code>perl Configure VC-WIN64A</code> or other configurations to be found in the INSTALL file (e.g. UNIX targets).
## For instance: <code>perl Configure VC-WIN64A</code>.
# (''Optional'') In case you compiled before on 32 or 64-bits, make sure you run <code>nmake clean</code> to prevent trouble across 32 and 64-bits which share output folder.
# Now build with: <code>nmake</code>
# Output can be found in the '''root''' of your folder as '''libcrypto-1_1x64.dll''' and '''libssl-1_1-x64.dll''' (with all the build additionals such as .pdb .lik or static .lib). You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers libcrypto-1_1x64.dll | more</code>, and look at the FILE HEADER section.
# Test the code using the 'test' make target, by running <code>nmake test</code>.
# Reminder, clean your code to prevent issues the next time you compile for a different target. See step 7.

==== Windows CE ====
'' Not specified ''

=== OpenSSL 1.0.2 ===

For OpenSSL 1.0.2 and earlier the procedure is as follows.

# Ensure you have perl installed on your machine (e.g. ActiveState or Strawberry), and available on your %PATH%
# Ensure you have NASM installed on your machine, and available on your %PATH%
# launch a Visual Studio tool x64 Cross Tools Command prompt
# change to the directory where you have copied openssl sources <code>cd c:\myPath\openssl</code>
# configure for the target OS with the command <code>perl Configure VC-WIN64A</code>. You may also be interested to set more configuration options as documented in the general INSTALL note (for UNIX targets). For instance: <code>perl Configure VC-WIN64A</code>.
# prepare the target environment with the command: <code>ms\do_win64a</code>
# ensure you start afresh and notably without linkable products from a previous 32bit compile (as 32 and 64 bits compiling still share common directories) with the command: <code>nmake -f ms\ntdll.mak clean</code> for the DLL target and <code>nmake -f ms\nt.mak clean</code> for static libraries.
# build the code with: <code>nmake -f ms\ntdll.mak</code> (respectively <code>nmake -f ms\nt.mak</code> )
# the artefacts will be found in sub directories out32dll and out32dll.dbg (respectively out32 and out32.dbg for static libraries). The libcrypto and ssl libraries are still named libeay32.lib and ssleay32.lib, and associated includes in inc32 ! You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers out32dll/libeay32.lib | more</code>, and look at the FILE HEADER section.
# test the code using the various *test.exe programs in out32dll. Use the 'test' make target to run all tests as in <code>nmake -f ms\ntdll.mak test</code>
# we recommend that you move/copy needed includes and libraries from the "32" directories under a new explicit directory tree for 64bit applications from where you will import and link your target applications, similar to that explained in INSTALL.W32.

==== Windows CE ====

=== OS X ===

The earlier discussion presented a lot of information (and some of it had OS X information). Here are the TLDR versions to configure, build and install the library.

If configuring for 64-bit OS X, then use a command similar to:

<pre>./Configure darwin64-x86_64-cc shared enable-ec_nistp_64_gcc_128 no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macos-x86_64
make depend
sudo make install</pre>

If configuring for 32-bit OS X, then use a command similar to:

<pre>./Configure darwin-i386-cc shared no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macosx-i386
make depend
sudo make install</pre>

If you want to build a multiarch OpenSSL library, then see this answer on Stack Overflow: [http://stackoverflow.com/a/25531033/608639 Build Multiarch OpenSSL on OS X].

=== iOS ===

The following builds OpenSSL for iOS using the iPhoneOS SDK. The configuration avoids the dynamic library the DSO interface and engines.

If you run <tt>make install</tt>, then the headers will be installed in <tt>/usr/local/openssl-ios/include</tt> and libraries will be installed in <tt>/usr/local/openssl-ios/lib</tt>.

==== 32-bit ====

For OpenSSL 1.1.0 and above, a 32-bit iOS cross-compiles uses the <tt>ios-cross</tt> target, and options similar to <tt>--prefix=/usr/local/openssl-ios</tt>.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT OPENSSL_BN_ASM_GF2m SHA1_ASM SHA256_ASM SHA512_ASM AES_ASM BSAES_ASM GHASH_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

If you are working with OpenSSL 1.0.2 or below, then use the <tt>iphoneos-cross</tt> target.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure iphoneos-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios
Configuring for iphoneos-cross
no-dso [option]
no-engine [option] OPENSSL_NO_ENGINE (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-hw [option] OPENSSL_NO_HW
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS (skip dir)
no-zlib [default]
no-zlib-dynamic [default]
IsMK1MF=0
CC =clang
CFLAG =-DOPENSSL_THREADS -D_REENTRANT -O3 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fomit-frame-pointer -fno-common
...</pre>

==== 64-bit ====

For OpenSSL 1.1.0 , a 64-bit iOS cross-compiles uses the <tt>ios64-cross</tt> target, and <tt>--prefix=/usr/local/openssl-ios64</tt>. <tt>ios64-cross</tt>. There is no built-in 64-bit iOS support for OpenSSL 1.0.2 or below.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios64-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios64

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios64-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT SHA1_ASM SHA256_ASM SHA512_ASM VPAES_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

=== Android ===

Visit [[Android]] and [[FIPS Library and Android]].

=== More ===

==== VAX/VMS ====

I you wonder what are files ending with .com like test/testca.com those are VAX/VMX scripts.
This code is still maintained.

==== OS/2 ====

==== NetWare ====
5.x 6.x

==== HP-UX ====
[[HP-UX Itanium FIPS and OpenSSL build]]

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be useful to detect either <tt>OPENSSL_init_ssl</tt> or <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Shell level]]
[[Category:Installation]]
[[Category:Compilation]]

Self Test Failures

2020-02-09T16:17:01Z

Jwalton: Add info on OpenSSL 1.1.x

The OpenSSL library includes a test suite that exercises components from both <tt>libcrypto.a</tt> and <tt>libssl.a</tt>. Ensuring the library builds and executes its tests properly is a keystone to using the library.

This page will show you how to isolate the test and the cause under many conditions. The more information you can supply with a bug report or pull request, the easier it is for the team to identify the failure or accept proposed changes. Also see [http://www.openssl.org/docs/faq.html#BUILD17 Item 17. I think I've found a bug, what should I do?] in the OpenSSL FAQ.

Generally speaking, there are two generations of self tests. The first generation is from OpenSSL 1.0.2 and below. The second generation is from OpenSSL 1.1.0 and above. This page focuses on the second generation, or OpenSSL 1.1.0 and above.

You can sometimes isolate a bug with <tt>no-asm</tt>, and sometimes with <tt>-O0</tt> or <tt>-O1</tt>. Ideally the bug will be present with no optimizations (<tt>-O0</tt>), but sometimes it takes some compiler analysis to tickle it (<tt>-O1</tt>).

== OpenSSL 1.1.0 ==

===Build the Library===

The first thing you should do after verifying the bug is to create a debug build of the OpenSSL library and attempt to reproduce it.

TODO: provide instrcutions.

===Build the Test===

You typically run <tt>make test</tt> to validate the library after <tt>make</tt>'ing.

<pre>$ make test
...

make[1]: Entering directory '/home/test_user/openssl-1.1.1d'
make[1]: Leaving directory '/home/test_user/openssl-1.1.1d'
make[1]: Entering directory '/home/test_user/openssl-1.1.1d'
( cd test; \
mkdir -p test-runs; \
SRCTOP=../. \
BLDTOP=../. \
RESULT_D=test-runs \
PERL="/usr/bin/perl" \
EXE_EXT= \
OPENSSL_ENGINES=`cd .././engines 2>/dev/null && pwd` \
OPENSSL_DEBUG_MEMORY=on \
/usr/bin/perl .././test/run_tests.pl )
../test/recipes/01-test_abort.t .................... ok
../test/recipes/01-test_sanity.t ................... ok
...
../test/recipes/15-test_dh.t ....................... ok
../test/recipes/15-test_dsa.t ...................... ok
../test/recipes/15-test_ec.t ....................... Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/5 subtests
../test/recipes/15-test_ecdsa.t .................... Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/1 subtests
../test/recipes/15-test_ecparam.t .................. Dubious, test returned 2 (wstat 512, 0x200)
Failed 2/134 subtests
../test/recipes/15-test_genrsa.t ................... ok
../test/recipes/15-test_mp_rsa.t ................... ok
../test/recipes/15-test_out_option.t ............... ok
../test/recipes/15-test_rsa.t ...................... ok
../test/recipes/15-test_rsapss.t ................... ok
...</pre>

=== Debug the Test ===

You can run a specific test by setting <tt>PERL5LIB</tt> and <tt>TOP</tt> variables as shown below.

<pre># From the root of the OpenSSL directory
$ PERL5LIB=util/perl TOP=$PWD perl test/recipes/15-test_ec.t
1..5
ok 1 - require '/home/test_user/openssl-1.1.1d/test/recipes/tconversion.pl';
# Subtest: /home/test_user/openssl-1.1.1d/test/ectest
1..11
crypto/ec/ecp_nistp521.c:144:15: runtime error: load of misaligned address 0x7ffec57b10b7 for type 'limb', which requires 8 byte alignment
0x7ffec57b10b7: note: pointer points here
c2 31 7e 7e f9 9b 42 6a 85 c1 b3 48 33 de a8 ff a2 27 c1 1d fe 28 59 e7 ef 77 5e 4b a1 ba 3d 4d
^
/home/test_user/openssl-1.1.1d/util/shlib_wrap.sh /home/test_user/openssl-1.1.1d/test/ectest => 1
not ok 2 - running ectest
# Failed test 'running ectest'
# at test/recipes/15-test_ec.t line 23.
# Subtest: ec conversions -- private key
1..10
ok 1 - initializing
...</pre>

=== Debug an Engine ===

TODO: provide instructions

== OpenSSL 1.0.2 ==

The instructions that follow help determine a failue in OpenSSL 1.0.2 and below. As of January 2020, OpenSSL 1.0.2 is end of life. You should move to OpenSSL 1.1.x as soon as possible.

===Build the Library===

The first thing you should do after verifying the bug is to create a debug build of the OpenSSL library and attempt to reproduce it. Creating a debug build is as easy as using <tt>-d</tt> configure argument. In the output below, notice <tt>-d</tt> caused the library to reduce optimizations (<tt>-O0</tt>) and increase debugging information (<tt>-g</tt>). However, the debugging information will lack symbolic constants because <tt>-g3</tt> was not used:

<pre>$ ./config -d
Operating system: i86pc-whatever-solaris2
Configuring for solaris64-x86_64-gcc
...
CC =gcc
CFLAG =-m64 -Wall -DL_ENDIAN -O0 -g -pthread -DFILIO_H -Wa,--noexecstack
...</pre>

To ensure most of your preferred flags are used, perform the following. Not all flags will be honored, but its an improvement over <tt>-d</tt>. The <tt>-DNDEBUG</tt> is used to ensure Posix's <tt>assert</tt> does not crash your program while under the debugger.

<pre>$ ./config no-asm -DNDEBUG -g3 -O0 -fno-omit-frame-pointer
Operating system: i86pc-whatever-solaris2
Configuring for solaris64-x86_64-gcc
...
CC =gcc
CFLAG =-m64 -Wall -DL_ENDIAN -O3 -pthread -DFILIO_H -g3 -O0 -fno-omit-frame-pointer
...</pre>

After configuring, run <tt>make</tt> as usual.

===Build the Test===

You typically run <tt>make test</tt> to validate the library after <tt>make</tt>'ing. Since you already know there's a problem, you can build the problem test with the following. The command below is an example for tracking down a failure in the HMAC test suite

<pre>$ VERBOSE=1 make TESTS="test_hmac" test
...

( cd test; \
SRCTOP=../. \
BLDTOP=../. \
PERL="/usr/local/bin/perl" \
EXE_EXT= \
OPENSSL_ENGINES=.././engines \
/usr/local/bin/perl .././test/run_tests.pl test_hmac )
../test/recipes/05-test_hmac.t ..
1..1
test 0 ok
test 1 ok
test 2 ok
test 3 ok
test 4 ok
test 5 ok
test 6 ok
../util/shlib_wrap.sh ./hmactest => 0
ok 1 - running hmactest
ok
All tests successful.
Files=1, Tests=1, 0 wallclock secs ( 0.03 usr 0.01 sys + 0.06 cusr 0.02 csys = 0.12 CPU)
Result: PASS
`test' is up to date.</pre>

=== Debug the Test ===

The executable for <tt>test_hmac</tt> is created from the source <tt>05-test_hmac.t</tt>, and it will be located at <tt>./test/buildtest_hmac</tt>:

<pre>$ file ./test/buildtest_hmac
./test/buildtest_hmac: ELF 64-bit LSB executable AMD64 Version 1, dynamically linked, not stripped</pre>

You can manually execute the test with the following. Note that <tt>$PWD</tt> is the root of the OpenSSL distribution, and the libraries are put on path using <tt>LD_LIBRARY_PATH</tt>.

<pre>$ LD_LIBRARY_PATH=".:$LD_LIBRARY_PATH" test/hmactest
^C
$</pre>

You can run the test under a debugger with the following. As can be seen, the execution results in a loop between lines 184 and 189.

<pre>$ LD_LIBRARY_PATH=".:$LD_LIBRARY_PATH" gdb test/hmactest
GNU gdb (GDB) 7.6
...
Reading symbols from .../openssl/test/hmactest...done.

(gdb) r
Starting program: /export/home/jwalton/openssl/test/hmactest
[Thread debugging using libthread_db enabled]

^C
Program received signal SIGINT, Interrupt.
OPENSSL_cleanse () at crypto/x86_64cpuid.s:184
184 testq $7,%rdi

(gdb) where
#0 OPENSSL_cleanse () at crypto/x86_64cpuid.s:184
#1 0xffff80ffba0eabec in hmac_ctx_cleanup (ctx=0x412ac0)
at crypto/hmac/hmac.c:144
#2 0xffff80ffba0eac6f in HMAC_CTX_reset (ctx=0x412ac0)
at crypto/hmac/hmac.c:160
#3 0xffff80ffba0eab68 in HMAC_CTX_new () at crypto/hmac/hmac.c:129
#4 0xffff80ffba0eae2e in HMAC (evp_md=0xffff80ffba1afec0 <md5_md>,
key=0x412700 <test>, key_len=0,
d=0x412714 <test+20> "More text test vectors to stuff up EBCDIC machines :-)", n=54, md=0xffff80ffba1c8100 <m.9561> "", md_len=0x0)
at crypto/hmac/hmac.c:209
#5 0x0000000000401a65 in main (argc=1, argv=0xffff80ffbffffa28)
at test/hmactest.c:105

(gdb) s
185 jz .Laligned
(gdb)
186 movb %al,(%rdi)
(gdb)
187 leaq -0(%rsi),%rsi
(gdb)
188 leaq 0(%rdi),%rdi
(gdb)
189 jmp .Lot
(gdb)
184 testq $7,%rdi
(gdb)
185 jz .Laligned
(gdb)
186 movb %al,(%rdi)
(gdb)
187 leaq -0(%rsi),%rsi
(gdb)
188 leaq 0(%rdi),%rdi
(gdb)
189 jmp .Lot</pre>

=== Debug an Engine ===

If you are testing an OpenSSL engine, then the procedures and paths are slightly different.

You manually build the engine with:

<pre>$ cd test
$ make test/afalgtest</pre>

You can run the engine test under a debugger with the following:

<pre>$ OPENSSL_ENGINES=../engines/afalg gdb ./afalgtest</pre>

Library Initialization

2020-01-29T03:50:00Z

Jwalton: Add section on OpenSSL_config and OPENSSL_init_crypto.

This page discusses OpenSSL library initialization when using the <tt>libssl</tt> and <tt>libcrypto</tt> components.

There are two ways to initialize the OpenSSL library, and they depend on the version of the library you are using. If you are using OpenSSL 1.0.2 or below, then you would use <tt>SSL_library_init</tt>. If you are using OpenSSL 1.1.0 or above, then the library will initialize itself automatically. Optionally you can explicitly initialise it using <tt>OPENSSL_init_ssl</tt> or <tt>OPENSSL_init_crypto</tt>. A compatibility macro exists in <tt>ssl.h</tt> that maps <tt>SSL_library_init</tt> to <tt>OPENSSL_init_ssl</tt>, so you can continue to use <tt>SSL_library_init</tt> if desired. Also see ''[http://mta.openssl.org/pipermail/openssl-dev/2016-February/005491.html SSL_library_init]'' on the OpenSSL-dev mailing list.

The rest of this page discusses initializing the library in 1.0.2. If you are using 1.1.0 or above then you don't need to take any further steps.

If you fail to initialize the library in 1.0.2, then you will experience unexplained errors like <tt>SSL_CTX_new</tt> returning <tt>NULL</tt>, error messages like <tt>SSL_CTX_new:library has no ciphers</tt> and <tt>alert handshake failure</tt> with no shared ciphers.

Below is a list of some initialization calls you might encounter in code or documentation. Unfortunately, all the initialization function return a useless values (for example, always 1) or are void functions. There is no way to determine if a failure occurred.

* SSL_library_init
* OpenSSL_add_ssl_algorithms
* OpenSSL_add_all_algorithms
* SSL_load_error_strings
* ERR_load_crypto_strings
 

== libssl Initialization ==

<tt>libssl</tt> should be initialized with calls to <tt>SSL_library_init</tt> and <tt>SSL_load_error_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.

If you are supporting both pre-1.1.0 and post-1.1.0 version of the OpenSSL library and you want to take control of <tt>SSL_library_init</tt> and <tt>OPENSSL_init_ssl</tt>, then you can perform:

<pre>#include <openssl/opensslv.h>
...

#if OPENSSL_VERSION_NUMBER < 0x10100000L
SSL_library_init();
#else
OPENSSL_init_ssl(0, NULL);
#endif</pre>

When you call <tt>libssl</tt>, the function will also initialize <tt>libcrypto</tt> components. There are two corner cases discussed in later sections. The first corner case is static locks, and second is <tt>OPENSSL_config</tt>.

<tt>OpenSSL_add_ssl_algorithms</tt> is a <tt>#define</tt> for <tt>SSL_library_init</tt>. You only need to call one or the other. If you want to print error strings using OpenSSL's built in functions, then call <tt>SSL_load_error_strings</tt>.

The <tt>SSL_library_init</tt> function loads the algorithms use by <tt>libssl</tt>. Below is an excerpt from <tt>ssl_algs.c</tt> (with some additional formatting for clarity).

<pre>int SSL_library_init(void)
{

#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cbc());
EVP_add_cipher(EVP_des_ede3_cbc());
#endif
#ifndef OPENSSL_NO_IDEA
EVP_add_cipher(EVP_idea_cbc());
#endif
...

#ifndef OPENSSL_NO_COMP
(void)SSL_COMP_get_compression_methods();
#endif

...

/* initialize cipher/digest methods table */
ssl_load_ciphers();

return(1);
}</pre>

The call to <tt>ssl_load_ciphers</tt> simply builds a table for use in the library. The following is from <tt>ssl_ciph.c</tt> (with some additional formatting for clarity).

<pre>void ssl_load_ciphers(void)
{
ssl_cipher_methods[SSL_ENC_DES_IDX] = EVP_get_cipherbyname(SN_des_cbc);
ssl_cipher_methods[SSL_ENC_3DES_IDX] = EVP_get_cipherbyname(SN_des_ede3_cbc);
...
ssl_digest_methods[SSL_MD_MD5_IDX] = EVP_get_digestbyname(SN_md5);
ssl_mac_secret_size[SSL_MD_MD5_IDX] = EVP_MD_size(ssl_digest_methods[SSL_MD_MD5_IDX]);
...
ssl_digest_methods[SSL_MD_SHA384_IDX] = EVP_get_digestbyname(SN_sha384);
ssl_mac_secret_size[SSL_MD_SHA384_IDX] = EVP_MD_size(ssl_digest_methods[SSL_MD_SHA384_IDX]);
...
}</pre>

=== Library Apps ===

The following examines how the OpenSSL development team uses initialization in the OpenSSL utilities.

<tt>s_client</tt> initializes itself with the following calls:
* OpenSSL_add_ssl_algorithms
* SSL_load_error_strings

<tt>s_server</tt> initializes itself with the following calls:
* SSL_load_error_strings();
* OpenSSL_add_ssl_algorithms();

<tt>s_time</tt> initializes itself with the following calls:
* OpenSSL_add_ssl_algorithms();

<tt>state_machine</tt> initializes itself with the following calls:
* SSL_library_init();
* OpenSSL_add_ssl_algorithms();
* SSL_load_error_strings();
* ERR_load_crypto_strings();

== libcrypto Initialization ==

<tt>libcrypto</tt> should be initialized with calls to <tt>OpenSSL_add_all_algorithms</tt> and <tt>ERR_load_crypto_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.

The <tt>OPENSSL_add_all_algorithms</tt> function is <tt>#define</tt>'d to either <tt>OPENSSL_add_all_algorithms_conf</tt> or <tt>OPENSSL_add_all_algorithms_noconf</tt> depending upon the value of <tt>OPENSSL_LOAD_CONF</tt>. A typical installation does ''not'' define <tt>OPENSSL_LOAD_CONF</tt>, which means <tt>OPENSSL_add_all_algorithms_noconf</tt> is used. Below is an excerpt from <tt>c_all.c</tt> (with some additional formatting for clarity).

<pre>void OPENSSL_add_all_algorithms_noconf(void)
{
/*
* For the moment OPENSSL_cpuid_setup does something
* only on IA-32, but we reserve the option for all
* platforms...
*/
OPENSSL_cpuid_setup();
OpenSSL_add_all_ciphers();
OpenSSL_add_all_digests();
...
}</pre>

<tt>OpenSSL_add_all_ciphers</tt> looks a lot like <tt>SSL_library_init</tt> from the <tt>libssl</tt> initialization routines (sans the call to <tt>ssl_load_ciphers</tt>). Below is an excerpt from <tt>c_allc.c</tt> (with some additional formatting for clarity).

<pre>void OpenSSL_add_all_ciphers(void)
{

#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cfb());
EVP_add_cipher(EVP_des_cfb1());
EVP_add_cipher(EVP_des_cfb8());
EVP_add_cipher(EVP_des_ede_cfb());
EVP_add_cipher(EVP_des_ede3_cfb());
EVP_add_cipher(EVP_des_ede3_cfb1());
EVP_add_cipher(EVP_des_ede3_cfb8());
...
#endif

#ifndef OPENSSL_NO_RC4
EVP_add_cipher(EVP_rc4());
EVP_add_cipher(EVP_rc4_40());
# ifndef OPENSSL_NO_MD5
EVP_add_cipher(EVP_rc4_hmac_md5());
# endif
#endif

...

/* Note: there is no call to ssl_load_ciphers() here */
}</pre>

Finally, [http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html <tt>OpenSSL_add_all_algorithms(3)</tt>] offers the following advice:

<blockquote>Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a statically linked executable can be quite large. If this is important it is possible to just add the required ciphers and digests.</blockquote>

If you want the small footprint, then call <tt>EVP_add_cipher</tt> with the ciphers and algorithms you need (and nothing more).

=== Library Apps ===

The following examines how the OpenSSL development team uses initialization in the OpenSSL utilities.

<tt>enc</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();

<tt>dec</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();

<tt>pkcs8</tt> initializes itself with the following calls:
* ERR_load_crypto_strings();
* OpenSSL_add_all_algorithms();

<tt>cms_sign</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();
* ERR_load_crypto_strings();

<tt>cms_ver</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();
* ERR_load_crypto_strings();

== OpenSSL_config ==

If you are supporting early and late versions of the library and need to call <tt>OpenSSL_config</tt> or <tt>OPENSSL_init_crypto</tt>, then the following is roughly equivalent.

<pre>#include <openssl/crypto.h>
...

#if OPENSSL_VERSION_NUMBER < 0x10001000L
OPENSSL_config(NULL);
#else
OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG |
OPENSSL_INIT_ADD_ALL_CIPHERS |
OPENSSL_INIT_ADD_ALL_DIGESTS);
#endif</pre>

== ENGINEs and RDRAND ==

A call to <tt>ENGINE_load_builtin_engines</tt> loads all built-in engines, including those for <tt>AES_NI</tt> instructions and <tt>RDRAND</tt>. After the call, OpenSSL will use the engines for AES encryption and random number generation, if available. In this case, <tt>RDRAND</tt> will be the only source of random numbers.

If you are concerned over possible <tt>RDRAND</tt> tampering, then you should explicitly call <tt>RAND_set_rand_engine(NULL)</tt> after loading all engines. If another module in the program happens to call <tt>ENGINE_load_builtin_engines</tt> again, then you will go back to using <tt>RDRAND</tt>.

You can also call <tt>ENGINE_unregister_RAND</tt> followed by <tt>ENGINE_register_all_complete</tt> to unregister <tt>RDRAND</tt> as default random number generator implementation.

To avoid accidental use of <tt>RDRAND</tt>, you can build OpenSSL with <tt>OPENSSL_NO_RDRAND</tt> defined. This is the preferred method to avoid all use of <tt>RDRAND</tt>.

Future version of the library will change the default behavior. That is, in the future, you will have to explicitly call <tt>ENGINE_load_rdrand</tt> if you want to use <tt>RDRAND</tt>. The change has been checked in, but its only available through <tt>git</tt> at the moment.

For the full discussion, see coderman's ''[http://seclists.org/fulldisclosure/2013/Dec/99 RDRAND used directly when default engines loaded in openssl-1.0.1-beta1 through openssl-1.0.1e]''.

== Static Locks ==

If your program is multi-threaded, then you will need to install the static locks. The static locks are used for extensively for <tt>libssl</tt>, and used in the random number generator for <tt>libcrypto</tt>. The locks should be installed '''''after''''' the calling:

* SSL_library_init
* OpenSSL_add_ssl_algorithms
* OpenSSL_add_all_algorithms
* SSL_load_error_strings
* ERR_load_crypto_strings

See [http://stackoverflow.com/a/42856544/608639 Multithreaded program using OpenSSL and locks randomly crashes] on Stack Overflow and [http://www.openssl.org/docs/crypto/threads.html threads(3)] for details until the wiki is updated with an example.

== OPENSSL_config ==

<tt>OPENSSL_config</tt> and <tt>OPENSSL_noconfig</tt> loads and unloads <tt>openssl.cnf</tt>. More correctly, a call to <tt>OPENSSL_config(NULL)</tt> loads the default configuration in <tt>openssl.cnf</tt>, <tt>OPENSSL_config(filename)</tt> loads another configuration, and <tt>OPENSSL_noconfig</tt> unlods a configuration.

<tt>OPENSSL_config</tt> may (or may not) be called depending upon how the OpenSSL library was configured, and it depends on whether <tt>OPENSSL_LOAD_CONF</tt> was defined. Because <tt>OPENSSL_config</tt> may (or may not) be called, your program may or may not need to make the call to <tt>OPENSSL_config</tt>. If, for example, your program is dynamically loading an ENGINE from <tt>OPENSSL_config</tt>, then you will need to ensure a call to <tt>OPENSSL_config</tt>.

You can check the value of <tt>OPENSSL_LOAD_CONF</tt> by <tt>cat</tt>'ing you<tt><nowiki><openssl/opensslconf.h></nowiki></tt>. You can then decide to call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt> based upon the definition (or lack threof) for <tt>OPENSSL_LOAD_CONF</tt>.

<pre>$ cat /usr/local/ssl/include/openssl/opensslconf.h | grep -i load
$</pre>

Here are the rules you should observe. In either case, your program should not depend upon the OpenSSL library and get into a known state.

* If you need something from <tt>openssl.cnf</tt>, then call <tt>OPENSSL_config</tt>. Don't depend on the library to do it for you.
* If you don't need something from <tt>openssl.cnf</tt> (or its mucking up you program), then call <tt>OPENSSL_noconfig</tt>. The library may have called <tt>OPENSSL_config</tt> for you.

== Engines ==

If your application needs to use engines, then it should either call call <tt>ENGINE_load_builtin_engines</tt> or <tt>OPENSSL_config</tt> to load the built-in engines (including dynamically configured engines from <tt>openssl.cnf</tt>).

Engines are are automatically loaded (or not loaded) based on the definition of <tt>OPENSSL_LOAD_CONF</tt> (or lack of definition). You should not depend on library behavior, so you should call <tt>OPENSSL_config</tt> or <tt>ENGINE_load_builtin_engines</tt> if you need engines.

You can also load a particular engine if you know what you want to use. <tt>eng_all.c</tt> lists the built-in engines you can load. For example, the following loads the <tt>rdrand</tt> engine provided for some Intel CPUs.

<pre>unsigned long err = 0;
int rc = 0;

OPENSSL_cpuid_setup();
ENGINE_load_rdrand();

ENGINE* eng = ENGINE_by_id("rdrand");
if(NULL == eng) handleFailure();

rc = ENGINE_init(eng);
if(1 != rc) handleFailure();

rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
if(1 != rc) handleFailure();

/* OK to proceed */
...

ENGINE_finish(eng);
ENGINE_free(eng);
ENGINE_cleanup();</pre>

If you want an engine to provide all incumbent functionality for the OpenSSL library, then then call <tt>ENGINE_register_complete</tt> after loading the engine. Incumbent functionality is determined by the manufacturer and includes includes RSA, DSA, DH, ECDH, MD, and RAND operations. See <tt>eng_all.c</tt>, <tt>eng_fat.c</tt>, and [http://www.openssl.org/docs/crypto/engine.html engine(3)] for details.

<pre>ENGINE* eng = ENGINE_by_id("XXX");
if(!(eng->flags & ENGINE_FLAGS_NO_REGISTER_ALL))
ENGINE_register_complete(eng);</pre>

== Cleanup ==

How to cleanup the library arises on occasion. Its often in the context of running a program under a memory checker like Valgrind.

OpenSSL does not provide a <tt>SSL_library_uninit</tt> or <tt>SSL_library_cleanup</tt> function (also see [http://rt.openssl.org/Ticket/Display.html?id=3824&user=guest&pass=guest Issue #3824, FEATURE: Please provide a function to unintialize the library]). To cleanup the library the library call the following functions:

* FIPS_mode_set(0);
* ENGINE_cleanup();
* CONF_modules_unload(1);
* EVP_cleanup();
* CRYPTO_cleanup_all_ex_data();
* ERR_remove_state();
* ERR_free_strings();

'''Note:''' ERR_remove_state() was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state() was introduced. ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the thread handling functionality was entirely rewritten.

<tt>CRYPTO_cleanup_all_ex_data</tt> and <tt>ERR_remove_state</tt> should be called on each thread, and not just the main thread.

The above list is a minimum to call. You will still need to cleanup Diffie-Hellman parameters, server contexts, static locks, etc.

After cleanup, you may have some memory leaks due to dynamic allocation of private static variables like <tt>ssl_comp_methods</tt>. This is a well known issue (see [http://rt.openssl.org/Ticket/Display.html?id=2561&user=guest&pass=guest Issue #2561, Memory leak with SSL built-in compressions]).

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be usful to detect either <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Examples]]

FIPS Library and Android

2019-12-03T07:23:30Z

Jwalton: Add info on sourcing.

This document will provide instructions for building the OpenSSL FIPS Object Module and OpenSSL FIPS Capable library for Android devices. The FIPS Object Module provides validated cryptography, and the FIPS Capable Library uses the validated cryptography. As an OpenSSL developer, you will use the library the same as in the past – except you must call <tt>FIPS_mode_set</tt> to enter FIPS mode and engage the validated cryptography. If you are ''not'' doing business in US Federal and ''don't'' need FIPS validated cryptography, then see [[Android]] wiki page.

The FIPS Object Module, <tt>fipscanister.o</tt>, is a sequestered container of object code and data built from source code. The sources, object code and data are strictly controlled by the OpenSSL FIPS 140-2 Security Policy. No changes can be made to the procedure for building the FIPS Object Module, and no changes can be made to the sources. If you need to make changes to the FIPS Object Module, you will need to engage the OpenSSL Foundation for a separate validation.

The FIPS Capable Library is comprised of <tt>libcrypto</tt> and <tt>libssl</tt>. They are the same libraries you have been using for years. The FIPS Capable Library is tolerant of changes to procedures and source code. You are allowed to modify them within reason, as long as the changes do not adversely affect the FIPS Object Module.

This guide is intended to be informative and easy to use. In case of discrepancies between this document and the OpenSSL FIPS Security Policy, the Security Policy will prevail. You can download the Security Policy from http://www.openssl.org/docs/fips/.

The script <tt>setenv-android.sh</tt> is sourced. Sourcing ensures the variables set in the script are available to other scripts that are run later in the process. If you shell does not provide the source command, then use <tt>. ./setenv-android.sh</tt> (note the leading dot).

The instructions that follow depend upon a properly configured Android NDK and SDK. The NDK is used to compile programs and link the OpenSSL library; while SDK tools are used to push programs to a device. Be sure <tt>ANDROID_NDK_ROOT</tt> and <tt>ANDROID_SDK_ROOT</tt> are set properly, and the SDK's tools and platform-tools are available.

==Executive Summary==

Use the following commands to build and install the OpenSSL FIPS Object Module and OpenSSL FIPS Capable library. Before running the commands download openssl-1.0.1e.tar.gz, openssl-fips-2.0.5.tar.gz and [[Media:setenv-android.sh|setenv-android.sh]]; place the files in the same directory (the 'root' directory mentioned below); ensure ANDROID_NDK_ROOT is set; and verify setenv-android.sh suites your taste. ANDROID_API and ANDROID_TOOLCHAIN will be set by the setenv-android.sh 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-fips-2.0.5/
$ rm -rf openssl-1.0.1e/
$ tar xzf openssl-fips-2.0.5.tar.gz
$ tar xzf openssl-1.0.1e.tar.gz
$ chmod a+x setenv-android.sh</pre>

=== Build the FIPS Object Module ===

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

$ ./config
$ make
$ sudo make install

# Execute after install
$ sudo -E cp $FIPS_SIG /usr/local/ssl/fips-2.0/bin
$ sudo -E mv /usr/local/ssl/fips-2.0/ /usr/local/ssl/$ANDROID_API</pre>

=== Build the FIPS Capable Library ===

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

$ perl -pi -e 's/install: all install_docs install_sw/install: install_docs install_sw/g' Makefile.org
$ ./config fips shared no-ssl2 no-ssl3 no-comp no-hw no-engine --openssldir=/usr/local/ssl/$ANDROID_API \
--with-fipsdir=/usr/local/ssl/$ANDROID_API --with-fipslibdir=/usr/local/ssl/$ANDROID_API/lib/

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

== OpenSSL FIPS Components ==

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 FIPS Object Module and FIPS Capable 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
# Set the Incore utility PATH
# Build the FIPS Object Module
# Build the FIPS Capable Library

=== Acquire the Required Files ===

First, obtain the base files from http://www.openssl.org/source/:
* openssl-1.0.1e.tar.gz
* openssl-fips-2.0.5.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]]

In addition to the required and auxiliary files, there are two test programs available. Download them from below (see Downloads section) or http://openssl.com/fips/2.0/platforms/android/.
* [[Media:Fips_hmac.c|fips_hmac.c]]
* [[Media:Fips-test.c|fips-test.c]]

openssl-fips-2.0.5.tar.gz includes the FIPS Object Module. openssl-1.0.1e.tar.gz includes the FIPS Capable Library. setenv-android.sh is used to set the cross-compilation environment. fips_hmac.c is used to test the static and dynamic libraries on the device.

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

<pre>android-openssl-fips $ ls -l
-rw-r--r-- 1 2718 Jun 23 17:54 fips_hmac.c
-rw-r--r-- 1 4459777 Jun 15 03:32 openssl-1.0.1e.tar.gz
-rw-r--r-- 1 1442754 Jun 23 16:37 openssl-fips-2.0.5.tar.gz
-rwxr-xr-x 1 6760 Jun 23 01:52 setenv-android.sh</pre>

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

setenv-android.sh 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 ANDROID_NDK_ROOT 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 FIPS Object Module and FIPS Capable library, and then unpack fresh files. Also ensure the script is executable.

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

=== Set the Incore Utility Path ===

The incore utility is a shell script used by fipsld to embed the FIPS Object Module's expected fingerprint in the OpenSSL shared object or program. The script is located in openssl-fips-2.0.5/util, and you must ensure incore can be found by fipsld.

Since openssl-fips-2.0.5/util is probably not included as one of the directories in the search list specified by the PATH environment variable, the OpenSSL library allows you to specify its path via FIPS_SIG. Export FIPS_SIG as follows by executing find from your working directory. Below, the root directory (PWD) is /home/user/android-openssl-fips/.

<pre>$ export FIPS_SIG=`find $PWD -name incore`
$ echo $FIPS_SIG
/home/user/android-openssl-fips/openssl-fips-2.0.5/util/incore</pre>

If incore is already installed in a known location, you can use it from there instead:

<pre>$ export FIPS_SIG=`find /usr/local/ssl -name incore`
$ echo $FIPS_SIG
/usr/local/ssl/android-14/bin/incore</pre>

=== Build the FIPS Object Module ===

The FIPS Object Module provides the validated cryptography for the OpenSSL library. This section of the document will guide you through the creation of the FIPS Object Module. The Module is governed by the FIPS 140-2 program requirements and you cannot deviate from the OpenSSL FIPS 140-2 Security Policy during any stage during handling, from acquisition, through building, to installation.

The FIPS Object Module build procedures use the cross-compilation tools supplied in the NDK. It does not use Android.mk and friends. A shell script is used to set the environment for the cross-compilation, and you might need to adjust the script to suit your taste.

To compile the FIPS Object Module for the embedded platform, perform the following steps. You cannot specify any arguments to config or make. Note the leading '.' when running the setenv-android.sh script. If you have any errors from the script, then you should fix them before proceeding.

<pre>$ . ./setenv-android.sh
$ cd openssl-fips-2.0.5/
$ ./config
$ make</pre>

After make completes, verify fipscanister.o was built for the embedded architecture.

<pre>$ find . -name fipscanister.o
./fips/fipscanister.o
$ readelf -h ./fips/fipscanister.o | grep -i 'class\|machine'
Class: ELF32
Machine: ARM</pre>

Finally, install the library. You must run make install without arguments.

<pre>$ sudo make install</pre>

After installing the FIPS Object Module, the four files of interest can be found in the lib/ directory.

<pre>$ ls /usr/local/ssl/fips-2.0/lib/
fipscanister.o fipscanister.o.sha1 fips_premain.c fips_premain.c.sha1</pre>

Once installed, you are outside the scope of FIPS 140-2 and allowed to move the library as long as it remains protected.

<pre>$ sudo mv /usr/local/ssl/fips-2.0/ /usr/local/ssl/android-14
$ ls /usr/local/ssl/
android-14</pre>

The android-14 is the API level you are building for, and is needed if you have multiple OpenSSL libraries installed (for example, you might have macosx, iphoneos, and android-14 in /usr/local/ssl). You can retrieve the API level from ANDROID_API, which was set in the setenv-android.sh script:

<pre>$ echo $ANDROID_API
android-14</pre>

Finally, copy incore into the installation directory. This will allow you to delete the temporary folders in your working area (openssl-fips-2.0.5 and openssl-1.0.1e) once the libraries are installed.

<pre>$ find . -name incore
./util/incore
$ sudo cp ./util/incore /usr/local/ssl/android-14/bin/
$ ls /usr/local/ssl/android-14/bin/
fipsld fips_standalone_sha1 incore</pre>

=== Build the FIPS Capable Library ===

The FIPS Capable Library is a standard OpenSSL distribution that can use the validated cryptography provided by the FIPS Object Module. This section of the document will guide you through the creation of the the FIPS Capable Library. You are allowed to modify the FIPS Capable Library within reason, as long as it does not adversely affect the FIPS Object Module.

The FIPS Capable version of the library can operate with or without FIPS validated cryptography. It handles all the details of operation while in FIPS mode after you successfully call FIPS_mode_set. If you don't call FIPS_mode_set, the library will still operate as expected; but it will not be using validated cryptography.
Its recommended that you build the shared object since Android will load and link it out of the box. If you build a static library, then you will have to build a wrapper shared object around the static archive.

The FIPS Capable Makefile (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 FIPS Capable library, you must issue config fips, 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. shared will build and install both the shared object and static archive. You should specify --openssldir, --with-fipsdir and --with-fipslibdir to ensure the FIPS Capable build system finds components from the FIPS Object Module.

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

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

Next, fix the makefile and run configure.

<pre>$ perl -pi -e 's/install: all install_docs install_sw/install: install_docs install_sw/g' Makefile.org
$ ./config fips shared no-ssl2 no-ssl3 no-comp no-hw no-engine --openssldir=/usr/local/ssl/android-14/ \
--with-fipsdir=/usr/local/ssl/android-14/ --with-fipslibdir=/usr/local/ssl/android-14/lib/</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>

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>

== Testing the OpenSSL Libraries ==

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 using fips_hmac, which is a test program to calculate a hmac over the files given as arguments.

The test program is built in a cross-compilation environment, just like the FIPS Object Module and FIPS Capable library. To begin, set the Android environment and verify ANDROID_SYSROOT. Note the leading '.' when running the setenv-android.sh script. If you have any errors from the script, then you should fix them before proceeding.

<pre>$ . ./setenv-android.sh
$ echo $ANDROID_SYSROOT
/opt/android-ndk-r8e/platforms/android-14/arch-arm</pre>

=== Linking with the Shared Object ===

Linking with the shared object is easiest. That's because the FIPS Capable library build process takes care of a number of items for you, including running fipsld on the shared object. The downside to dynamic linking is you have to push the program and shared object to the device and modify the loader path before executing.

The command below compiles fips_hmac.c using ANDROID_SYSROOT and the shared object (libcrypto.so). ANDROID_SYSROOT specifies the location of Android's headers and libraries, and is set using setenv-android.sh.

<pre>$ arm-linux-androideabi-gcc --sysroot="$ANDROID_SYSROOT" -I/usr/local/ssl/android-14/include \
fips_hmac.c -o fips_hmac.exe /usr/local/ssl/android-14/lib/libcrypto.so</pre>

There's no need to run fipsld on a program which dynamically links to the OpenSSL library.

Once the program is built, push it to the device and execute it. The hashes produced by the test program will vary with the files being digested.

<pre># Copy the program and shared library to the Android device
$ adb push fips_hmac.exe /data/local/tmp/
303 KB/s (18548 bytes in 0.059s)
$ adb push libcrypto.so.1.0.0 /data/local/tmp
1106 KB/s (2154620 bytes in 1.900s)

# Execute the program on the Android device
$ adb shell
shell@android: $ cd /data/local/tmp
shell@android: $ LD_LIBRARY_PATH=./; ./fips_hmac.exe -v fips_hmac.exe
FIPS mode enabled
f178788e8a439dbaaa760ef774e8d92e01d2440e</pre>

=== Linking with the Static Archive ===

Linking against the static library is more challenging. That's because you have to set two variables – CC and FIPSLD_CC and compile with the modified CC. They must be exported because fipsld uses them in child shells. Behind the scenes, fipsld will compile and link fips_premain.c, modify the libcrypto archive, assemble the final program, and embed the fingerprint.

<pre>$ export CC=`find /usr/local/ssl/$ANDROID_API -name fipsld`
$ echo $CC
/usr/local/ssl/android-14/bin/fipsld
$ export FIPSLD_CC="$ANDROID_TOOLCHAIN/arm-linux-androideabi-gcc"
$ echo $FIPSLD_CC
/opt/android-ndk-r8e/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc</pre>

Finally, compile and link as normal using CC. The command below compiles fips_hmac.c using ANDROID_SYSROOT and the static archive (libcrypto.a). ANDROID_SYSROOT specifies the location of Android's headers and libraries, and is set using setenv-android.sh.

<pre>$ $CC --sysroot="$ANDROID_SYSROOT" -I/usr/local/ssl/android-14/include fips-test.c \
-o fips-test.exe /usr/local/ssl/android-14/lib/libcrypto.a</pre>

You can use fipsld to create an object file rather than compile and link. In this case, fipsld will simply pass all arguments to arm-linux-androideabi-gcc.

<pre>$ $CC --sysroot="$ANDROID_SYSROOT" -I/usr/local/ssl/android-14/include -c fips-test.c</pre>

Once the program is built, push it to the device and execute it.
The hashes produced by the test program will vary with the files being digested.

<pre># Copy the program to the Android device
$ adb push fips_hmac.exe /data/local/tmp
1099 KB/s (1462276 bytes in 1.298s)

# Execute the program on the Android device
$ adb shell
shell@android: $ cd /data/local/tmp
shell@android: $ fips_hmac.exe -v fips_hmac.exe
FIPS mode enabled
a7518364fbba32cca0df974ee646e8a13833eb3d</pre>

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

=== FIPS Object Module ===

Once the FIPS Object Module and FIPS Capable Library are installed, you can safely delete the source directories. The headers, libraries and programs (such as fipsld and incore) are located in sub-directories of <tt>/usr/local/ssl/<platform></tt>.

If you don't care about FIPS 140-2 and just want to build the library for Android, then see [[Android|OpenSSL and Android]].

=== 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:OpenSSL_FIPS_Library_and_Android_Guide.pdf|OpenSSL FIPS Library and Android Guide]] - this page as a PDF document.

[[Media:OpenSSL-FIPS-Android.tar.gz|OpenSSL-FIPS-Android.tar.gz]] - Roll-up of the files provided on this page.

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

[[Media:Fips_hmac.c|fips_hmac.c]] - test program to mac files given as program arguments.

[[Media:Fips-test.c|fips-test.c]] - test program to dump critical FIPS parameters.

[[Category:FIPS 140]]

Android

2019-12-03T07:22:45Z

Jwalton: Add info on sourcing.

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

The script <tt>setenv-android.sh</tt> is sourced. Sourcing ensures the variables set in the script are available to other scripts that are run later in the process. If you shell does not provide the source command, then use <tt>. ./setenv-android.sh</tt> (note the leading dot).

''NOTE'': The instructions on this page are for older versions of OpenSSL (they should work for OpenSSL 1.0.2). For OpenSSL 1.1.1 see the INSTALL and NOTES.ANDROID files in the source distribution.

==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
$ source ./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>$ source ./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.

Talk:Compilation and Installation

2019-10-04T23:31:54Z

Jwalton: Created page with "== Page has grown too large == Hi Everyone. I think this page has grown too large and should be separated into separate pages. It has become messy and hard to organize the in..."

== Page has grown too large ==

Hi Everyone. I think this page has grown too large and should be separated into separate pages. It has become messy and hard to organize the information.

Painting with a broad brush, leave "Compilation and Installation" as the main landing page. Always refer to it from external places, like Stack Overflow. At "Compilation and Installation" include the basic information, like intro discussion of various platforms and the Unix/Linux options. Then, create separate subpages for specific platforms, like Linux, OS X, Windows, Windows CE, etc. "Compilation and Installation" provides a link to each subpage.

Does anyone have any thoughts?

[[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 23:31, 4 October 2019 (UTC)

Compilation and Installation

2019-10-04T12:33:42Z

Jwalton: Add additional information

The following page is a combination of the <tt>INSTALL</tt> file provided with the OpenSSL library and notes from the field. If you have questions about what you are doing or seeing, then you should consult <tt>INSTALL</tt> since it contains the commands and specifies the behavior by the development team.

OpenSSL uses a custom build system to configure the library. Configuration will allow the library to set up the recursive makefiles from <tt>makefile.org</tt>. Once configured, you use <tt>make</tt> to build the library. You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

You must use a C compiler to build the OpenSSL library. You cannot use a C++ compiler. Later, once the library is built, it is OK to create user programs with a C++ compiler. But the library proper must be built with a C compiler.

There are two generations of build system. First is the build system used in OpenSSL 1.0.2 and below. The instructions below apply to it. Second is the build system for OpenSSL 1.1.0 and above. The instructions are similar, but not the same. For example, the second generation abandons the monolithic <tt>Configure</tt> and places individual configurations in the <tt>Configurations</tt> directory. Also, the second generation is more platform agnostic and uses templates to produce a final, top level build file (<tt>Makefile</tt>, <tt>descrip.mms</tt>, what have you).

After you configure and build the library, you should always perform a <tt>make test</tt> to ensure the library performs as expected under its self tests. If you are building OpenSSL 1.1.0 and above, then you will also need PERL 5.10 or higher (see <tt>README.PERL</tt> for details).

OpenSSL's build system does not rely upon <tt>autotools</tt> or <tt>libtool</tt>. Also see [http://www.openssl.org/support/faq.html#MISC5 Why aren't tools like 'autoconf' and 'libtool' used?] in the OpenSSL FAQ.

== Retrieve source code ==

The OpenSSL source code can be downloaded from [http://www.openssl.org/source/ OpenSSL Source Tarballs] or any suitable [http://www.openssl.org/source/mirror.html ftp mirror]. There are various versions including stable as well as unstable versions.

The source code is managed via Git. Its referred to as Master. The repository is

: git://git.openssl.org/openssl.git

The source is also available via a [https://github.com/openssl/openssl GitHub] mirror. This repository is updated every 15 minutes.

* [[Use_of_Git|Accessing OpenSSL source code via Git]]

== Configuration ==

OpenSSL is configured for a particular platform with protocol and behavior options using <tt>Configure</tt> and <tt>config</tt>.

You should avoid custom build systems because they often miss details, like each architecture and platform has a unique <tt>opensslconf.h</tt> and <tt>bn.h</tt> generated by <tt>Configure</tt>.

=== Supported Platforms ===

You can run <tt>Configure LIST</tt> to see a list of available platforms.

<pre>$ ./Configure LIST
BC-32
BS2000-OSD
BSD-generic32
BSD-generic64
BSD-ia64
BSD-sparc64
BSD-sparcv8
BSD-x86
BSD-x86-elf
BSD-x86_64
Cygwin
Cygwin-x86_64
DJGPP
...</pre>

If your platform is not listed, then use a similar platform and tune the <tt>$cflags</tt> and <tt>$ldflags</tt> by making a copy of the configure line and giving it its own name. <tt>$cflags</tt> and <tt>$ldflags</tt> correspond to fields 2 and 6 in a configure line. An example of using a similar configure line is presented in [[Compilation_and_Installation#Using_RPATHs|Using RPATHs]].

=== Configure & Config ===

You use <tt>Configure</tt> and <tt>config</tt> to tune the compile and installation process through options and switches. The difference between is <tt>Configure</tt> properly handles the host-arch-compiler triplet, and <tt>config</tt> does not. <tt>config</tt> attempts to guess the triplet, so its a lot like autotool's <tt>config.guess</tt>.

You can usually use <tt>config</tt> and it will do the right thing (from Ubuntu 13.04, x64):

<pre>$ ./config
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring for linux-x86_64
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

Mac OS X can have issues (its often a neglected platform), and you will have to use <tt>Configure</tt>:

<pre> ./Configure darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-ec_nistp_64_gcc_128 [default] OPENSSL_NO_EC_NISTP_64_GCC_128 (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

You can also configure on Darwin by exporting <tt>KERNEL_BITS</tt>:

<pre>$ export KERNEL_BITS=64
$ ./config shared no-ssl2 no-ssl3 enable-ec_nistp_64_gcc_128 --openssldir=/usr/local/ssl/macosx-x64/
Operating system: i686-apple-darwinDarwin Kernel Version 12.5.0: Sun Sep 29 13:33:47 PDT 2013; root:xnu-2050.48.12~1/RELEASE_X86_64
Configuring for darwin64-x86_64-cc
Configuring for darwin64-x86_64-cc
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-jpake [experimental] OPENSSL_NO_JPAKE (skip dir)
no-krb5 [krb5-flavor not specified] OPENSSL_NO_KRB5
...</pre>

If you provide a option not known to configure or ask for help, then you get a brief help message:

<pre>$ ./Configure --help
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]</pre>

And if you supply an unknown triplet:

<pre>$ ./Configure darwin64-x86_64-clang
Configuring for darwin64-x86_64-clang
Usage: Configure [no-<cipher> ...] [enable-<cipher> ...] [experimental-<cipher> ...]
[-Dxxx] [-lxxx] [-Lxxx] [-fxxx] [-Kxxx] [no-hw-xxx|no-hw] [[no-]threads] [[no-]shared]
[[no-]zlib|zlib-dynamic] [no-asm] [no-dso] [no-krb5] [sctp] [386] [--prefix=DIR]
[--openssldir=OPENSSLDIR] [--with-xxx[=vvv]] [--test-sanity] os/compiler[:flags]

pick os/compiler from:
BC-32 BS2000-OSD BSD-generic32 BSD-generic64 BSD-ia64 BSD-sparc64 BSD-sparcv8
BSD-x86 BSD-x86-elf BSD-x86_64 Cygwin Cygwin-pre1.3 DJGPP MPE/iX-gcc OS2-EMX
...

NOTE: If in doubt, on Unix-ish systems use './config'.</pre>

=== Dependencies ===

If you are prompted to run <tt>make depend</tt>, then you must do so. For OpenSSL 1.0.2 and below, its required to update the standard distribution once configuration options change.

<pre>Since you've disabled or enabled at least one algorithm, you need to do
the following before building:

make depend
</pre>

OpenSSL 1.1.0 and above performs the dependency step for you, so you should not see the message. However, you should perform a <tt>make clean</tt> to ensure the list of objects files is accurate after a reconfiguration.

== Configure Options ==

OpenSSL has been around a long time, and it carries around a lot of cruft. For example, from above, SSLv2 is enabled by default. SSLv2 is completely broken, and you should disable it during configuration. You can disable protocols and provide other options through <tt>Configure</tt> and <tt>config</tt>, and the following lists some of them.

'''Note''': if you specify a non-existent option, then the configure scripts will proceed without warning. For example, if you inadvertently specify '''no-sslv2''' rather than '''no-ssl2 no-ssl3''', the script will configure ''with'' SSLv2 and ''without'' warning for the unknown no-sslv2.

'''Note''': when building a shared object, both the static archive and shared objects are built. You do not need to do anything special to build both when '''shared''' is specified.

{| class="wikitable sortable" border="1"
|+ OpenSSL Library Options
|-
! scope="col" width="150px" | Option
! scope="col" class="unsortable" | Description
|-
| --prefix=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| --openssldir=XXX || See [[#PREFIX_and_OPENSSLDIR|PREFIX and OPENSSLDIR]] in the next section (below).
|-
| -d || Debug build of the library. Optimizations are disabled (no <tt>-O3</tt> or similar) and <tt>libefence</tt> is used (<tt>apt-get install electric-fence</tt> or <tt>yum install electric-fence</tt>). TODO: Any other features?
|-
| shared || Build a shared object in addition to the static archive. You probably need a [[#Using_RPATHs|RPATH]] when enabling <tt>shared</tt> to ensure <tt>openssl</tt> uses the correct <tt>libssl</tt> and <tt>libcrypto</tt> after installation.
|-
| enable-ec_nistp_64_gcc_128 || Use on little endian platforms when GCC supports <tt>__uint128_t</tt>. ECDH is about 2 to 4 times faster. Not enabled by default because <tt>Configure</tt> can't determine it. Enable it if your compiler defines <tt>__SIZEOF_INT128__</tt>, the CPU is little endian and it tolerates unaligned data access.
|-
| enable-capieng || Enables the Microsoft CAPI engine on Windows platforms. Used to access the Windows Certificate Store. Also see [http://openssl.6102.n7.nabble.com/Using-Windows-certificate-store-through-OpenSSL-td46788.html Using Windows certificate store through OpenSSL] on the OpenSSL developer list.
|-
| no-ssl2 || Disables SSLv2. <tt>OPENSSL_NO_SSL2</tt> will be defined in the OpenSSL headers.
|-
| no-ssl3 || Disables SSLv3. <tt>OPENSSL_NO_SSL3</tt> will be defined in the OpenSSL headers.
|-
| no-comp || Disables compression independent of <tt>zlib</tt>. <tt>OPENSSL_NO_COMP</tt> will be defined in the OpenSSL headers.
|-
| no-idea || Disables IDEA algorithm. Unlike RC5 and MDC2, IDEA is enabled by default
|-
| no-asm || Disables assembly language routines (and uses C routines)
|-
| no-dtls || Disables DTLS in OpenSSL 1.1.0 and above
|-
| no-dtls1 || Disables DTLS in OpenSSL 1.0.2 and below
|-
| no-shared || Disables shared objects (only a static library is created)
|-
| no-hw || Disables hardware support (useful on mobile devices)
|-
| no-engine || Disables hardware support (useful on mobile devices)
|-
| no-threads || Disables threading support.
|-
| no-dso || Disables the OpenSSL DSO API (the library offers a shared object abstraction layer). If you disable DSO, then you must disable Engines also
|-
| no-err || Removes all error function names and error reason text to reduce footprint
|-
| no-npn/no-nextprotoneg || Disables Next Protocol Negotiation (NPN). Use <tt>no-nextprotoneg</tt> for 1.1.0 and above; and <tt>no-npn</tt> otherwise
|-
| no-psk || Disables Preshared Key (PSK). PSK provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-srp || Disables Secure Remote Password (SRP). SRP provides mutual authentication independent of trusted authorities, but its rarely offered or used
|-
| no-ec2m || Used when configuring FIPS Capable Library with a FIPS Object Module that only includes prime curves. That is, use this switch if you use <tt>openssl-fips-ecp-2.0.5</tt>.
|-
| no-weak-ssl-ciphers || Disables RC4. Available in OpenSSL 1.1.0 and above.
|-
| -DXXX || Defines XXX. For example, <tt>-DOPENSSL_NO_HEARTBEATS</tt>.
|-
| -DPEDANTIC || Defines PEDANTIC. The library will avoid some undefined behavior, like casting an unaligned byte array to a different pointer type. This define should be used if building OpenSSL with undefined behavior sanitizer (<tt>-fsanitize=undefined</tt>).
|-
| -DOPENSSL_USE_IPV6=0 || Disables IPv6. Useful if OpenSSL encounters incorrect or inconsistent platform headers and mistakenly enables IPv6. Must be passed to <tt>Configure</tt> manually.
|-
| -L''something'', -l''something'', -K''something'', -Wl,''something'' || Linker options, will become part of LDFLAGS.
|-
| -''anythingelse'', +''anythingelse'' || Compiler options, will become part of CFLAGS.
|}

'''''Note''''': on older OSes, like CentOS 5, BSD 5, and Windows XP or Vista, you will need to configure with <tt>no-async</tt> when building OpenSSL 1.1.0 and above. The configuration system does not detect lack of the Posix feature on the platforms.

'''''Note''''': you can verify compiler support for <tt>__uint128_t</tt> with the following:

<pre># gcc -dM -E - </dev/null | grep __SIZEOF_INT128__
#define __SIZEOF_INT128__ 16</pre>

=== PREFIX and OPENSSLDIR ===

<tt>--prefix</tt> and <tt>--openssldir</tt> control the configuration of installed components. The behavior and interactions of <tt>--prefix</tt> and <tt>--openssldir</tt> are slightly different between OpenSSL 1.0.2 and below, and OpenSSL 1.1.0 and above.

The '''''rule of thumb''''' to use when you want something that "just works" for all recent versions of OpenSSL, including OpenSSL 1.0.2 and 1.1.0, is:

* specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>
* set <tt>--prefix</tt> and <tt>--openssldir</tt> to the same location

One word of caution is ''avoid'' <tt>--prefix=/usr</tt> when OpenSSL versions are '''''not''''' [[Binary_Compatibility|binary compatible]]. You will replace the distro's version of OpenSSL with your version of OpenSSL. It will most likely break everything, including the package management system.

'''OpenSSL 1.0.2 and below'''

It is usually ''not'' necessary to specify <tt>--prefix</tt>. If <tt>--prefix</tt> is ''not'' specified, then <tt>--openssldir</tt> is used. However, specifying ''only'' <tt>--prefix</tt> may result in broken builds because the 1.0.2 build system attempts to build in a FIPS configuration.

You can ''omit'' If <tt>--prefix</tt> and use <tt>--openssldir</tt>. In this case, the paths for <tt>--openssldir</tt> will be used during configuration. If <tt>--openssldir</tt> is not specified, the the default <tt>/usr/local/ssl</tt> is used.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

'''OpenSSL 1.1.0 and above'''

OpenSSL 1.1.0 changed the behavior of install rules. You should specify both <tt>--prefix</tt> and <tt>--openssldir</tt> to ensure <tt>make install</tt> works as expected.

The takeaway is <tt>/usr/local/ssl</tt> is used by default, and it can be overridden with ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>. The rule of thumb applies for path overrides: specify ''both'' <tt>--prefix</tt> and <tt>--openssldir</tt>.

=== Debug Configuration ===

From the list above, its possible to quickly configure a "debug" build with <tt>./config -d</tt>. However, you can often get into a more amicable state ''without'' the [http://en.wikipedia.org/wiki/Electric_Fence Electric Fence] dependency by issuing:

<pre>$ ./config no-asm -g3 -O0 -fno-omit-frame-pointer -fno-inline-functions
Operating system: x86_64-whatever-linux2
Configuring for linux-x86_64
Configuring OpenSSL version 1.1.0-pre5-dev (0x0x10100005L)
no-asm [option] OPENSSL_NO_ASM
...
Configuring for linux-x86_64
IsMK1MF =no
CC =gcc
CFLAG =-Wall -O3 -pthread -m64 -DL_ENDIAN -g3 -O0 -fno-omit-frame-pointer
...</pre>

Don't be alarmed about both <tt>-O3</tt> and <tt>-O0</tt>. The last setting ''"sticks"'', and that's the <tt>-O0</tt>.

If you are working in Visual Studio and you can't step into library calls, then see [http://stackoverflow.com/q/38249235 Step into not working, but can force stepping after some asm steps] on Stack Overflow.

=== Modifying Build Settings ===

Sometimes you need to work around OpenSSL's selections for building the library. For example, you might want to use <tt>-Os</tt> for a mobile device (rather than <tt>-O3</tt>), or you might want to use the <tt>clang</tt> compiler (rather than <tt>gcc</tt>).

In case like these, its often easier to modify <tt>Configure</tt> and <tt>Makefile.org</tt> rather than trying to add targets to the configure scripts. Below is a patch that modifies <tt>Configure</tt> and <tt>Makefile.org</tt> for use under the iOS 7.0 SDK (which lacks <tt>gcc</tt> in <tt>/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/</tt>):

* Modifies <tt>Configure</tt> to use <tt>clang</tt>
* Modifies <tt>Makefile.org</tt> to use <tt>clang</tt>
* Modifies <tt>CFLAG</tt> to use <tt>-Os</tt>
* Modifies <tt>MAKEDEPPROG</tt> to use <tt>$(CC) -M</tt>

Setting and resetting of <tt>LANG</tt> is required on Mac OSX to work around a <tt>sed</tt> bug or limitation.

<pre>OLD_LANG=$LANG
unset LANG

sed -i "" 's|\"iphoneos-cross\"\,\"llvm-gcc\:-O3|\"iphoneos-cross\"\,\"clang\:-Os|g' Configure
sed -i "" 's/CC= cc/CC= clang/g' Makefile.org
sed -i "" 's/CFLAG= -O/CFLAG= -Os/g' Makefile.org
sed -i "" 's/MAKEDEPPROG=makedepend/MAKEDEPPROG=$(CC) -M/g' Makefile.org

export LANG=$OLD_LANG</pre>

After modification, be sure to dclean and configure again so the new settings are picked up:

<pre>make dclean

./config
make depend
make all
...</pre>

=== Using RPATHs ===

<tt>RPATH</tt>'s are supported by default on the BSD platforms, but not others. If you are working on Linux and compatibles, then you have to manually add an RPATH. One of the easiest ways to add a <tt>RPATH</tt> is to configure with it as shown below.

<pre>./config -Wl,-rpath=/usr/local/ssl/lib</pre>

'''''Note well''''': you should use a RPATH when building both OpenSSL and your program. If you don't add a RPATH to both, then your program could runtime-link to the wrong version of OpenSSL.

You can also add an <tt>RPATH</tt> by hard coding the <tt>RPATH</tt> into a configure line. For example, on Debian x86_64 open the file <tt>Configure</tt> in an editor, copy <tt>linux-x86_64</tt>, name it <tt>linux-x86_64-rpath</tt>, and make the following change to add the <tt>-rpath</tt> option. Notice the addition of <tt>-Wl,-rpath=...</tt> in two places.

<pre>"linux-x86_64-rpath", "gcc:-m64 -DL_ENDIAN -O3 -Wall -Wl,-rpath=/usr/local/ssl/lib::
-D_REENTRANT::-Wl,-rpath=/usr/local/ssl/lib -ldl:SIXTY_FOUR_BIT_LONG RC4_CHUNK DES_INT DES_UNROLL:
${x86_64_asm}:elf:dlfcn:linux-shared:-fPIC:-m64:.so.\$(SHLIB_MAJOR).\$(SHLIB_MINOR):::64",</pre>

Above, fields 2 and 6 were changed. They correspond to <tt>$cflag</tt> and <tt>$ldflag</tt> in OpenSSL's builds system.

Then, Configure with the new configuration:

<pre>$ ./Configure linux-x86_64-rpath shared no-ssl2 no-ssl3 no-comp \
--openssldir=/usr/local/ssl enable-ec_nistp_64_gcc_128</pre>

Finally, after <tt>make</tt>, verify the settings stuck:

<pre>$ readelf -d ./libssl.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./libcrypto.so | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]
$ readelf -d ./apps/openssl | grep -i rpath
0x000000000000000f (RPATH) Library rpath: [/usr/local/ssl/lib]</pre>

Once you perform <tt>make install</tt>, then <tt>ldd</tt> will produce expected results:

<pre>$ ldd /usr/local/ssl/lib/libssl.so
linux-vdso.so.1 => (0x00007ffceff6c000)
ibcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007ff5eff96000)
...

$ ldd /usr/local/ssl/bin/openssl
linux-vdso.so.1 => (0x00007ffc30d3a000)
libssl.so.1.0.0 => /usr/local/ssl/lib/libssl.so.1.0.0 (0x00007f9e8372e000)
libcrypto.so.1.0.0 => /usr/local/ssl/lib/libcrypto.so.1.0.0 (0x00007f9e832c0000)
...</pre>

=== FIPS Capable Library ===

If you want to use FIPS validated cryptography, you download, build and install the FIPS Object Module (<tt>openssl-fips-2.0.5.tar.gz</tt>) according to the [https://www.openssl.org/docs/fips/UserGuide-2.0.pdf FIPS User Guide 2.0] and [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.pdf FIPS 140-2 Security Policy]. You then download, build and install the FIPS Capable Library (<tt>openssl-1.0.1e.tar.gz</tt>).

When configuring the FIPS Capable Library, you must use <tt>fips</tt> as an option:

<pre>./config fips <other options ...></pre>

If you are configuring the FIPS Capable Library with only prime curves (<tt>openssl-fips-ecp-2.0.5.tar.gz</tt>), then you must configure with <tt>no-ec2m</tt>:

<pre>./config fips no-ec2m <other options ...></pre>

=== Compile Time Checking ===

If you disable an option during configure, you can check if it's available through <tt>OPENSSL_NO_*</tt> defines. OpenSSL writes the configure options to <tt><openssl/opensslconf.h></tt>. For example, if you want to know if SSLv3 is available, then you would perform the following in your code:

<pre>#include <openssl/opensslconf.h>
...

#if !defined(OPENSSL_NO_SSL3)
/* SSLv3 is available */
#endif</pre>

== Compilation ==

After configuring the library, you should run <tt>make</tt>. If prompted, there's usually no need to <tt>make depend</tt> since you are building from a clean download.

==== Quick ====

<pre>./config <nowiki><options ...> --openssldir=/usr/local/ssl</nowiki>
make
make test
sudo make install</pre>

Various options can be found examining the <tt>Configure</tt> file (there is a well commented block at its top). OpenSSL ships with SSLv2, SSLv3 and Compression enabled by default (see <tt>my $disabled</tt>), so you might want to use <tt>no-ssl2 no-ssl3</tt>, <tt>no-ssl3</tt>, and <tt>no-comp</tt>.

== Platfom specific ==

=== Linux ===

==== Intel ====

==== ARM ====

==== X32 (ILP32) ====

X32 uses the 32-bit data model (ILP32) on x86_64/amd64. To properly configure for X32 under current OpenSSL distributions, you must use <tt>Configure</tt> and use the x32 triplet:

<pre># ./Configure LIST | grep x32
linux-x32
...</pre>

Then:

<pre># ./Configure linux-x32
Configuring OpenSSL version 1.1.0-pre6-dev (0x0x10100006L)
no-asan [default] OPENSSL_NO_ASAN (skip dir)
...
Configuring for linux-x32
CC =gcc
CFLAG =-Wall -O3 -pthread -mx32 -DL_ENDIAN
SHARED_CFLAG =-fPIC
...</pre>

If using an amd64-compatible processor and GCC with that supports <tt>__uint128_t</tt>, then you usually add <tt>enable-ec_nistp_64_gcc_128 </tt> in addition to your other flags.

=== Windows ===
3noch wrote a VERY good guide [http://developer.covenanteyes.com/building-openssl-for-visual-studio/ here].
Like he said in his article, make absolutely sure to create separate directories for 32 and 64 bit versions.

==== W32 / Windows NT - Windows 9x ====

type INSTALL.W32

* you need Perl for Win32. Unless you will build on Cygwin, you will need ActiveState Perl, available from http://www.activestate.com/ActivePerl.
* one of the following C compilers:
** Visual C++
** Borland C
** GNU C (Cygwin or MinGW)
* Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ is required if you intend to utilize assembler modules. Note that NASM is now the only supported assembler.

==== W64 ====

Read first the INSTALL.W64 documentation note containing some specific 64bits information.
See also INSTALL.W32 that still provides additonnal build information common to both the 64 and 32 bit versions.

You may be surprised: the 64bit artefacts are indeed output in the out32* sub-directories and bear names ending *32.dll. Fact is the 64 bit compile target is so far an incremental change over the legacy 32bit windows target. Numerous compile flags are still labelled "32" although those do apply to both 32 and 64bit targets.

The important pre-requisites are to have PERL available (for essential file processing so as to prepare sources and scripts for the target OS) and of course a C compiler like Microsoft Visual Studio for C/C++. Also note the procedure changed at OpenSSL 1.1.0 and is more streamlined. Also see [https://stackoverflow.com/q/39076244/608639 Why there is no ms\do_ms.bat after perl Configure VC-WIN64A] on Stack Overflow.

=== OpenSSL 1.1.0 ===

=== OpenSSL 1.0.2 ===

For OpenSSL 1.0.2 and earlier the procedure is as follows.

# launch a Visual Studio tool x64 Cross Tools Command prompt
# change to the directory where you have copied openssl sources <code>cd c:\myPath\openssl</code>
# configure for the target OS with the command <code>perl Configure VC-WIN64A</code>. You may also be interested to set more configuration options as documented in the general INSTALL note (for UNIX targets). For instance: <code>perl Configure no-asm VC-WIN64A</code>.
# prepare the target environment with the command: <code>ms\do_win64a</code>
# ensure you start afresh and notably without linkable products from a previous 32bit compile (as 32 and 64 bits compiling still share common directories) with the command: <code>nmake -f ms\ntdll.mak clean</code> for the DLL target and <code>nmake -f ms\nt.mak clean</code> for static libraries.
# build the code with: <code>nmake -f ms\ntdll.mak</code> (respectively <code>nmake -f ms\nt.mak</code> )
# the artefacts will be found in sub directories out32dll and out32dll.dbg (respectively out32 and out32.dbg for static libraries). The libcrypto and ssl libraries are still named libeay32.lib and ssleay32.lib, and associated includes in inc32 ! You may check this is true 64bit code using the Visual Studio tool 'dumpbin'. For instance <code>dumpbin /headers out32dll/libeay32.lib | more</code>, and look at the FILE HEADER section.
# test the code using the various *test.exe programs in out32dll. Use the 'test' make target to run all tests as in <code>nmake -f ms\ntdll.mak test</code>
# we recommend that you move/copy needed includes and libraries from the "32" directories under a new explicit directory tree for 64bit applications from where you will import and link your target applications, similar to that explained in INSTALL.W32.

==== Windows CE ====

=== OS X ===

The earlier discussion presented a lot of information (and some of it had OS X information). Here are the TLDR versions to configure, build and install the library.

If configuring for 64-bit OS X, then use a command similar to:

<pre>./Configure darwin64-x86_64-cc shared enable-ec_nistp_64_gcc_128 no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macos-x86_64
make depend
sudo make install</pre>

If configuring for 32-bit OS X, then use a command similar to:

<pre>./Configure darwin-i386-cc shared no-ssl2 no-ssl3 no-comp --openssldir=/usr/local/ssl/macosx-i386
make depend
sudo make install</pre>

If you want to build a multiarch OpenSSL library, then see this answer on Stack Overflow: [http://stackoverflow.com/a/25531033/608639 Build Multiarch OpenSSL on OS X].

=== iOS ===

The following builds OpenSSL for iOS using the iPhoneOS SDK. The configuration avoids the dynamic library the DSO interface and engines.

If you run <tt>make install</tt>, then the headers will be installed in <tt>/usr/local/openssl-ios/include</tt> and libraries will be installed in <tt>/usr/local/openssl-ios/lib</tt>.

==== 32-bit ====

For OpenSSL 1.1.0 and above, a 32-bit iOS cross-compiles uses the <tt>ios-cross</tt> target, and options similar to <tt>--prefix=/usr/local/openssl-ios</tt>.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch armv7 -mios-version-min=6.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT OPENSSL_BN_ASM_GF2m SHA1_ASM SHA256_ASM SHA512_ASM AES_ASM BSAES_ASM GHASH_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

If you are working with OpenSSL 1.0.2 or below, then use the <tt>iphoneos-cross</tt> target.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure iphoneos-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios
Configuring for iphoneos-cross
no-dso [option]
no-engine [option] OPENSSL_NO_ENGINE (skip dir)
no-gmp [default] OPENSSL_NO_GMP (skip dir)
no-hw [option] OPENSSL_NO_HW
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS (skip dir)
no-zlib [default]
no-zlib-dynamic [default]
IsMK1MF=0
CC =clang
CFLAG =-DOPENSSL_THREADS -D_REENTRANT -O3 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fomit-frame-pointer -fno-common
...</pre>

==== 64-bit ====

For OpenSSL 1.1.0 , a 64-bit iOS cross-compiles uses the <tt>ios64-cross</tt> target, and <tt>--prefix=/usr/local/openssl-ios64</tt>. <tt>ios64-cross</tt>. There is no built-in 64-bit iOS support for OpenSSL 1.0.2 or below.

<pre>$ export CC=clang;
$ export CROSS_TOP=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer
$ export CROSS_SDK=iPhoneOS.sdk
$ export PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin:$PATH"

$ ./Configure ios64-cross no-shared no-dso no-hw no-engine --prefix=/usr/local/openssl-ios64

Configuring OpenSSL version 1.1.1-dev (0x10101000L)
no-afalgeng [forced] OPENSSL_NO_AFALGENG
no-asan [default] OPENSSL_NO_ASAN
no-dso [option]
no-dynamic-engine [forced]
...
no-weak-ssl-ciphers [default] OPENSSL_NO_WEAK_SSL_CIPHERS
no-zlib [default]
no-zlib-dynamic [default]
Configuring for ios64-cross

PERL =perl
PERLVERSION =5.16.2 for darwin-thread-multi-2level
HASHBANGPERL =/usr/bin/env perl
CC =clang
CFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
CXX =c++
CXXFLAG =-O3 -D_REENTRANT -arch arm64 -mios-version-min=7.0.0 -isysroot $(CROSS_TOP)/SDKs/$(CROSS_SDK) -fno-common
DEFINES =NDEBUG OPENSSL_THREADS OPENSSL_NO_DYNAMIC_ENGINE OPENSSL_PIC OPENSSL_BN_ASM_MONT SHA1_ASM SHA256_ASM SHA512_ASM VPAES_ASM ECP_NISTZ256_ASM POLY1305_ASM
...</pre>

=== Android ===

Visit [[Android]] and [[FIPS Library and Android]].

=== More ===

==== VAX/VMS ====

I you wonder what are files ending with .com like test/testca.com those are VAX/VMX scripts.
This code is still maintained.

==== OS/2 ====

==== NetWare ====
5.x 6.x

==== HP-UX ====
[[HP-UX Itanium FIPS and OpenSSL build]]

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be useful to detect either <tt>OPENSSL_init_ssl</tt> or <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Shell level]]
[[Category:Installation]]
[[Category:Compilation]]

User talk:Pauli

2019-09-15T04:00:01Z

Jwalton: /* KDF Changes */

== KDF Changes ==
I think the [modified] KDF example may be too new for most users of OpenSSL. For example, it appears OSSL_PARAM is part of an upcoming release: https://www.openssl.org/docs/manmaster/man3/OSSL_PARAM.html .

I think the new example is going to cause confusion for most users rather than helping them. Also, answers on Stack Overflow a pointing back to the wiki and the old example.

Perhaps you can add the new example as a distinct second example, and clearly state it is part of the OpenSSL 3.0 API.

[[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 00:14, 15 September 2019 (UTC)

: Shouldn't this be discussed on the discussion tab of the page that was changed? That would probably make it a little easier for the rest of us to understand what's going on, rather than this random discussion added to a user page that doesn't even exist...
: --[[User:Levitte|Levitte]] ([[User talk:Levitte|talk]]) 03:57, 15 September 2019 (UTC)

:: Yeah, I was trying to have a sidebar to encourage an edit. Sorry about that.
::
:: [[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 04:00, 15 September 2019 (UTC)

User talk:Jwalton

2019-09-15T01:04:00Z

Jwalton:

Not sure if I am replying correctly.

The EVP KDF APIs have never been in a release. There is no example of their use that works on anything except master and the existing example didn't work. The use of ctrl functions was removed because of the upcoming changes and a general drift to OSSL_PARAMs instead.

Earlier releases of OpenSSL required either calling the KDF functions directly or using the PKEY interface kludge.

: No, you're not replying correctly. You should reply on the thread and not start a new one on a different page.
:
: Removing the exiting information was the wrong choice. Add a new example with the new information. Since a user will have two examples to chose from, explain when to use the new example.
:
: [[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 00:57, 15 September 2019 (UTC)

User talk:Jwalton

2019-09-15T00:57:29Z

Jwalton:

Not sure if I am replying correctly.

The EVP KDF APIs have never been in a release. There is no example of their use that works on anything except master and the existing example didn't work. The use of ctrl functions was removed because of the upcoming changes and a general drift to OSSL_PARAMs instead.

Earlier releases of OpenSSL required either calling the KDF functions directly or using the PKEY interface kludge.

: No, you're not replying correctly. You should reply on the thread and not start a new one on a different page.
:
: Removing the exiting information was the wrong choice. Add a new example with the new information.
:
: [[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 00:57, 15 September 2019 (UTC)

User talk:Jwalton

2019-09-15T00:57:16Z

Jwalton:

2019-07-11T01:17:17Z

Jwalton: Add KDF example; stop redirect to Key Agreement page.

Key derivation is the process of deriving one or more secret keys from a secret value such as a password or a passphrase. Several key derivation algoirthms have been standardized, and they are usually referred to a Key Derivation Functions (KDFs). KDFs include PBKDF2 from RFC 2898, HKDF form RFC 5869 and Scrypt from RFC 7914. OpenSSL provides PBKDF2, Scrypt, HKDF, ANSI X9.42 and ANSI X9.63 by way of <tt>EVP_KDF</tt>.

Not all key derivation functions are available in all versions of OpenSSL. OpenSSL 1.0.2 and below provide WWW, XXX, YYY and ZZZ. OpenSSL 1.1.0 and above provide WWW, XXX, YYY and ZZZ. TODO: fill in the pieces here and talk about changes.

== HKDF key derivation ==

The following program derives a key using HKDF from RFC 5869. HKDF was designed by Krawczyk and Eronen, and it is state of the art in expand-then-extract key derivation algorithms. It is usually a good choice when you need a KDF. The program below was taken from the OpenSSL man pages.

HKDF takes three parameter:

<tt>secret</tt> - private information to use during derivation, like a password or passphrase. The parameter is set using <tt>EVP_KDF_CTRL_SET_KEY</tt>.

<tt>salt</tt> - possibly public information to use during derivation. <tt>salt</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_SET_SALT</tt>.

<tt>info</tt> - additional, possibly public information to use during derivation. <tt>info</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_ADD_HKDF_INFO</tt>.

<pre>#include <openssl/evp.h>
#include <openssl/kdf.h>

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char* argv[])
{
EVP_KDF_CTX *kctx = NULL;
unsigned char out[32];

kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);

if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
error("EVP_KDF_CTRL_SET_MD");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
error("EVP_KDF_CTRL_SET_SALT");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
error("EVP_KDF_CTRL_SET_KEY");
}
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
error("EVP_KDF_CTRL_ADD_HKDF_INFO");
}
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
error("EVP_KDF_derive");
}

/* Use the 32 bytes as a Key and IV */
const unsigned char *key = out+0;
const unsigned char *iv = out+16;

printf("Key: ");
for (size_t i=0; i<16; ++i)
printf("%02x ", key[i]);
printf("\n");

printf("IV: ");
for (size_t i=0; i<16; ++i)
printf("%02x ", iv[i]);
printf("\n");

EVP_KDF_CTX_free(kctx);

return 0;
}</pre>

You can compile the program using C99 with the following command.

<pre>openssl$ gcc -std=c99 test.c -o test.exe -l:libcrypto.a -pthread -ldl
openssl$</pre>

Running the program results in the following output.

<pre>$ ./test.exe
Key: 2a c4 36 9f 52 59 96 f8 de 13 73 1f 56 22 4f 34
IV: df 0e 4c 96 ca a9 3b fd ec cf 23 7b 50 39 c8 db</pre>

EVP Symmetric Encryption and Decryption

2019-07-04T21:59:59Z

Jwalton: Whitespace.

{{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]].

The complete source code of the following example can be downloaded as [[Media:evp-symmetric-encrypt.c|evp-symmetric-encrypt.c]].

==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, depending 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|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]]

EVP Symmetric Encryption and Decryption

2019-07-04T21:40:28Z

Jwalton: Cleanup link.

EVP Authenticated Encryption and Decryption

2019-06-05T04:48:04Z

Jwalton: Add additional information.

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

The EVP interface supports the ability to perform authenticated encryption and decryption, as well as the option to attach unencrypted, associated data to the message. Such Authenticated-Encryption with Associated-Data (AEAD) schemes provide confidentiality by encrypting the data, and also provide authenticity assurances by creating a MAC tag over the encrypted data. The MAC tag will ensure the data is not accidentally altered or maliciously tampered during transmission and storage.

There are a number of AEAD modes of operation. The modes include EAX, CCM and GCM mode. Using AEAD modes is nearly identical to using standard symmetric encryption modes like CBC, CFB and OFB modes.

As with standard symmetric encryption you will need to know the following:

* Algorithm (currently only AES is supported)
* Mode (currently only GCM and CCM are supported)
* Key
* Initialisation Vector (IV)

In addition you can (optionally) provide some ''Additional Authenticated Data'' (AAD). The AAD data is not encrypted, and is typically passed to the recipient in plaintext along with the ciphertext. An example of AAD is the IP address and port number in a IP header used with IPsec.

The output from the encryption operation will be the ciphertext, and a tag. The tag is subsequently used during the decryption operation to ensure that the ciphertext and AAD have not been tampered with.

The OpenSSL manual describes the usage of the GCM and CCM modes here: [[Manual:EVP_EncryptInit(3)#GCM_Mode]].

The complete source code of the following examples can be downloaded as [[Media:evp-gcm-encrypt.c|evp-gcm-encrypt.c]] resp. [[Media:evp-ccm-encrypt.c|evp-ccm-encrypt.c]].

==Authenticated Encryption using GCM mode==

Encryption is performed in much the same way as for symmetric encryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_EncryptUpdate, with the output buffer set to NULL
* Once private data has been added using EVP_EncryptUpdate (non-NULL output buffer), you cannot add AAD data
* After the EVP_EncryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl retrieves the tag

See the code below for an example:
<pre>
int gcm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *ciphertext,
unsigned char *tag)
{
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. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/*
* Set IV length if default 12 bytes (96 bits) is not appropriate
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
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. Normally ciphertext bytes may be written at
* this stage, but this does not occur in GCM mode
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, 16, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using GCM mode==

Again, the decryption operation is much the same as for normal symmetric decryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_DecryptUpdate, with the output buffer set to NULL
* Prior to the EVP_DecryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl provides the tag
* A non positive return value from EVP_DecryptFinal_ex should be considered as a failure to authenticate ciphertext and/or AAD. It does not necessarily indicate a more serious error.

See the code example below:

<pre>
int gcm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

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

/* Initialise the decryption operation. */
if(!EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/* Set IV length. Not necessary if this is 12 bytes (96 bits) */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(!EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(!EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

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

/* Set expected tag value. Works in OpenSSL 1.0.1d and later */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, 16, tag))
handleErrors();

/*
* Finalise the decryption. A positive return value indicates success,
* anything else is a failure - the plaintext is not trustworthy.
*/
ret = EVP_DecryptFinal_ex(ctx, plaintext + len, &len);

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
plaintext_len += len;
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

==Authenticated Encryption using CCM mode==

Encryption with CCM mode is much the same as for encryption with GCM but with some additional things to bear in mind.
* you can only call EVP_EncryptUpdate once for AAD and once for the plaintext.
* The total plaintext length must be passed to EVP_EncryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)

See the code below for an example:
<pre>
int ccm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv,
unsigned char *ciphertext,
unsigned char *tag)
{
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. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/*
* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example.
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set tag length */
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, NULL);

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total plaintext length */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, NULL, plaintext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or one times as required */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

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

/*
* Finalise the encryption. Normally ciphertext bytes may be written at
* this stage, but this does not occur in CCM mode.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG, 14, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using CCM mode==

Decryption with CCM mode is much the same as for decryption with CCM but with some additional things to bear in mind.
* you can only call EVP_DecryptUpdate once for AAD and once for the plaintext.
* The total ciphertext length must be passed to EVP_DecryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)
* The tag verify is performed when you call the final EVP_DecryptUpdate and is reflected by the return value: there is no call to EVP_DecryptFinal.

See the code below for an example:
<pre>
int ccm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

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

/* Initialise the decryption operation. */
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set expected tag value. */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, tag))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total ciphertext length */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, NULL, ciphertext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or more times as required */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

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

plaintext_len = len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

== Potential Issue in AES/GCM ==

Early versions of the authenticated encryption interface required using a 0-sized array (not a NULL array) to arrive at the proper authentication tag '''''when''''' the authentication tag size was ''not'' a multiple of the block size (for example, an authentication tag size of 20 bytes). For more information on the issue and the work-arounds, see [http://rt.openssl.org/Ticket/Display.html?id=2859 Issue #2859: Possible bug in AES GCM mode] and [http://groups.google.com/d/msg/mailing.openssl.users/idg9Z22MYZs/Jqlo8dA-2tMJ Possible bug in GCM/GMAC with (just) AAD of size unequal to block size].

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [[EVP Symmetric 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]]

EVP Authenticated Encryption and Decryption

2019-06-05T04:46:58Z

Jwalton: Add additional information.

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

The EVP interface supports the ability to perform authenticated encryption and decryption, as well as the option to attach unencrypted, associated data to the message. Such Authenticated-Encryption with Associated-Data (AEAD) schemes provide confidentiality by encrypting the data, and also provide authenticity assurances by creating a MAC tag over the encrypted data. The MAC tag will ensure the data is not accidentally altered or maliciously tampered during transmission and storage.

There are a number of AEAD modes of operation. The modes include EAX, CCM and GCM mode. Using AEAD modes is nearly identical to using standard symmetric encryption modes like CBC, CFB and OFB modes.

As with standard symmetric encryption you will need to know the following:

* Algorithm (currently only AES is supported)
* Mode (currently only GCM and CCM are supported)
* Key
* Initialisation Vector (IV)

In addition you can (optionally) provide some ''Additional Authenticated Data'' (AAD). The AAD data is not encrypted, and is typically passed to the recipient in plaintext along with the ciphertext. An example of AAD is the IP address and port number in a IP header used with IPsec.

The output from the encryption operation will be the ciphertext, and a tag. The tag is subsequently used during the decryption operation to ensure that the ciphertext and AAD have not been tampered with.

The OpenSSL manual describes the usage of the GCM and CCM modes here: [[Manual:EVP_EncryptInit(3)#GCM_Mode]].

The complete source code of the following examples can be downloaded as [[Media:evp-gcm-encrypt.c|evp-gcm-encrypt.c]] resp. [[Media:evp-ccm-encrypt.c|evp-ccm-encrypt.c]].

==Authenticated Encryption using GCM mode==

Encryption is performed in much the same way as for symmetric encryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_EncryptUpdate, with the output buffer set to NULL
* Once private data has been added, you cannot add AAD data
* After the EVP_EncryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl retrieves the tag

See the code below for an example:
<pre>
int gcm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *ciphertext,
unsigned char *tag)
{
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. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/*
* Set IV length if default 12 bytes (96 bits) is not appropriate
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
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. Normally ciphertext bytes may be written at
* this stage, but this does not occur in GCM mode
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, 16, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using GCM mode==

Again, the decryption operation is much the same as for normal symmetric decryption as described [[EVP Symmetric Encryption and Decryption|here]]. The main differences are:
* You may optionally pass through an IV length using EVP_CIPHER_CTX_ctrl
* AAD data is passed through in zero or more calls to EVP_DecryptUpdate, with the output buffer set to NULL
* Prior to the EVP_DecryptFinal_ex call a new call to EVP_CIPHER_CTX_ctrl provides the tag
* A non positive return value from EVP_DecryptFinal_ex should be considered as a failure to authenticate ciphertext and/or AAD. It does not necessarily indicate a more serious error.

See the code example below:

<pre>
int gcm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv, int iv_len,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

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

/* Initialise the decryption operation. */
if(!EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, NULL, NULL))
handleErrors();

/* Set IV length. Not necessary if this is 12 bytes (96 bits) */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, iv_len, NULL))
handleErrors();

/* Initialise key and IV */
if(!EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/*
* Provide any AAD data. This can be called zero or more times as
* required
*/
if(!EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

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

/* Set expected tag value. Works in OpenSSL 1.0.1d and later */
if(!EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, 16, tag))
handleErrors();

/*
* Finalise the decryption. A positive return value indicates success,
* anything else is a failure - the plaintext is not trustworthy.
*/
ret = EVP_DecryptFinal_ex(ctx, plaintext + len, &len);

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
plaintext_len += len;
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

==Authenticated Encryption using CCM mode==

Encryption with CCM mode is much the same as for encryption with GCM but with some additional things to bear in mind.
* you can only call EVP_EncryptUpdate once for AAD and once for the plaintext.
* The total plaintext length must be passed to EVP_EncryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)

See the code below for an example:
<pre>
int ccm_encrypt(unsigned char *plaintext, int plaintext_len,
unsigned char *aad, int aad_len,
unsigned char *key,
unsigned char *iv,
unsigned char *ciphertext,
unsigned char *tag)
{
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. */
if(1 != EVP_EncryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/*
* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example.
*/
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set tag length */
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, NULL);

/* Initialise key and IV */
if(1 != EVP_EncryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total plaintext length */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, NULL, plaintext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or one times as required */
if(1 != EVP_EncryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

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

/*
* Finalise the encryption. Normally ciphertext bytes may be written at
* this stage, but this does not occur in CCM mode.
*/
if(1 != EVP_EncryptFinal_ex(ctx, ciphertext + len, &len))
handleErrors();
ciphertext_len += len;

/* Get the tag */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG, 14, tag))
handleErrors();

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

return ciphertext_len;
}
</pre>

==Authenticated Decryption using CCM mode==

Decryption with CCM mode is much the same as for decryption with CCM but with some additional things to bear in mind.
* you can only call EVP_DecryptUpdate once for AAD and once for the plaintext.
* The total ciphertext length must be passed to EVP_DecryptUpdate (only needed if AAD is passed)
* Optionally the tag and IV length can also be passed. If they are not then the defaults are used (12 bytes for AES tags, and 7 bytes for AES IVs)
* The tag verify is performed when you call the final EVP_DecryptUpdate and is reflected by the return value: there is no call to EVP_DecryptFinal.

See the code below for an example:
<pre>
int ccm_decrypt(unsigned char *ciphertext, int ciphertext_len,
unsigned char *aad, int aad_len,
unsigned char *tag,
unsigned char *key,
unsigned char *iv,
unsigned char *plaintext)
{
EVP_CIPHER_CTX *ctx;
int len;
int plaintext_len;
int ret;

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

/* Initialise the decryption operation. */
if(1 != EVP_DecryptInit_ex(ctx, EVP_aes_256_ccm(), NULL, NULL, NULL))
handleErrors();

/* Setting IV len to 7. Not strictly necessary as this is the default
* but shown here for the purposes of this example */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, 7, NULL))
handleErrors();

/* Set expected tag value. */
if(1 != EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, 14, tag))
handleErrors();

/* Initialise key and IV */
if(1 != EVP_DecryptInit_ex(ctx, NULL, NULL, key, iv))
handleErrors();

/* Provide the total ciphertext length */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, NULL, ciphertext_len))
handleErrors();

/* Provide any AAD data. This can be called zero or more times as required */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, aad, aad_len))
handleErrors();

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

plaintext_len = len;

/* Clean up */
EVP_CIPHER_CTX_free(ctx);

if(ret > 0) {
/* Success */
return plaintext_len;
} else {
/* Verify failed */
return -1;
}
}
</pre>

== Potential Issue in AES/GCM ==

Early versions of the authenticated encryption interface required using a 0-sized array (not a NULL array) to arrive at the proper authentication tag '''''when''''' the authentication tag size was ''not'' a multiple of the block size (for example, an authentication tag size of 20 bytes). For more information on the issue and the work-arounds, see [http://rt.openssl.org/Ticket/Display.html?id=2859 Issue #2859: Possible bug in AES GCM mode] and [http://groups.google.com/d/msg/mailing.openssl.users/idg9Z22MYZs/Jqlo8dA-2tMJ Possible bug in GCM/GMAC with (just) AAD of size unequal to block size].

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [[EVP Symmetric 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]]

Cryptogams AES

2019-05-25T14:33:21Z

Jwalton: Remove alignment from discussion. Alignment is handled by the module.

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 AES implementation. According to the head notes the ARMv4 implementation runs around 22 to 40 cycles per byte (cpb). Typical C/C++ implementations run around 50 to 80 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>aes-armv4.h</tt> and <tt>aes-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' aes-armv4.h aes-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation operates in ECB mode and encrypts or decrypts full AES blocks. You are responsible for things like padding and side channel counter-measures.

At the moment Clang is miscompiling <tt>aes-armv4.S</tt>. Also see [https://bugs.llvm.org/show_bug.cgi?id=38133 LLVM Issue 38133]. You can work around the problem by compiling <tt>aes-armv4.S</tt> with <tt>-mthumb</tt>, but all data must be aligned. If you don't use aligned buffers then a <tt>SIGBUS</tt> could occur.

==Obtain Source Files==

There are two source files you need for Cryptogams AES. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/aes/asm/aes-armv4.pl <tt>aes-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/aes/asm/aes-armv4.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>aes-armv4.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>aes-armv4.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>aes-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl aes-armv4.pl linux32 aes-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>aes-armv4</tt> happens to have the requirement.

<pre>$ cat aes-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' aes-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' aes-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>aes-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>aes-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c aes-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c aes-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv5t -c aes-armv4.S
$ nm aes-armv4.o
000011c0 T AES_decrypt
00000540 T AES_encrypt
00000b60 T AES_set_decrypt_key
00000b80 T AES_set_enc2dec_key
00000820 T AES_set_encrypt_key
00000cc0 t AES_Td
00000000 t AES_Te
000012c0 t _armv4_AES_decrypt
00000640 t _armv4_AES_encrypt
00000b80 t _armv4_AES_set_enc2dec_key
00000820 t _armv4_AES_set_encrypt_key</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble aes-armv4.o
aes-armv4.o: file format elf32-littlearm
...

00000b60 <AES_set_decrypt_key>:
b60: e52de004 push {lr} ; (str lr, [sp, #-4]!)
b64: ebffff2d bl 820 <AES_set_encrypt_key>
b68: e3300000 teq r0, #0
b6c: e49de004 pop {lr} ; (ldr lr, [sp], #4)
b70: 1afffff9 bne b5c <AES_set_encrypt_key+0x33c>
b74: e1a00002 mov r0, r2
b78: e1a01002 mov r1, r2
b7c: eaffffff b b80 <AES_set_enc2dec_key>

...</pre>

And trace it back to the source code in <tt>aes-armv4.S</tt>.

<pre>.globl AES_set_decrypt_key
.type AES_set_decrypt_key,%function
.align 5
AES_set_decrypt_key:
str lr,[sp,#-4]! @ push lr
bl _armv4_AES_set_encrypt_key
teq r0,#0
ldr lr,[sp],#4 @ pop lr
bne .Labrt

mov r0,r2 @ AES_set_encrypt_key preserves r2,
mov r1,r2 @ which is AES_KEY *key
b _armv4_AES_set_enc2dec_key
.size AES_set_decrypt_key,.-AES_set_decrypt_key</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. The functions of interest are <tt>AES_set_encrypt_key</tt>, <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>AES_set_encrypt_key</tt>.

<pre>openssl$ grep -nIR AES_set_encrypt_key | grep '\.c'
...
crypto/aes/aes_core.c:632:int AES_set_encrypt_key(const unsigned char *userKey, const int bits,</pre>

Examining <tt>aes_core.c:632</tt> reveals the following.

<pre>openssl$ cat -n crypto/aes/aes_core.c
...
632 int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
633 AES_KEY *key)
634 {
...
728 return 0;
729 }</pre>

The next piece of information to discover is <tt>AES_KEY</tt>. Again a quick <tt>grep</tt> leads you to <tt>aes_key_st</tt>.

<pre>openssl$ grep -nIR AES_KEY | grep typedef
include/openssl/aes.h:39:typedef struct aes_key_st AES_KEY;

openssl$ cat -n include/openssl/aes.h
...

31 struct aes_key_st {
32 # ifdef AES_LONG
33 unsigned long rd_key[4 * (AES_MAXNR + 1)];
34 # else
35 unsigned int rd_key[4 * (AES_MAXNR + 1)];
36 # endif
37 int rounds;
38 };
39 typedef struct aes_key_st AES_KEY;</pre>

Finally, you need <tt>AES_MAXNR</tt> from <tt>aes.h</tt>.

<pre>openssl$ grep -IR AES_MAXNR | grep define
include/openssl/aes.h:# define AES_MAXNR 14</pre>

Lather, rinse repeat for <tt>AES_set_decrypt_key</tt>, <tt>AES_encrypt</tt> and <tt>AES_decrypt</tt>. <tt>AES_encrypt</tt> can be found at <tt>crypto/aes/aes_core.c:787</tt>.

<pre>openssl$ grep -nIR AES_encrypt | grep '\.c'
...
crypto/aes/aes_core.c:787:void AES_encrypt(...)

openssl$ cat -n crypto/aes/aes_core.c
...
783 /*
784 * Encrypt a single block
785 * in and out can overlap
786 */
787 void AES_encrypt(const unsigned char *in, unsigned char *out,
788 const AES_KEY *key) {</pre>

And <tt>AES_decrypt</tt> can be found at <tt>aes_core.c:978</tt>.

<pre>openssl$ grep -nIR AES_decrypt | grep '\.c'
...
crypto/aes/aes_core.c:978:void AES_decrypt(...)

openssl$ cat -n crypto/aes/aes_core.c

974 /*
975 * Decrypt a single block
976 * in and out can overlap
977 */
978 void AES_decrypt(const unsigned char *in, unsigned char *out,
979 const AES_KEY *key)
980 {
</pre>

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use.

<pre>/* Header file for use with Cryptogam's ARMv4 AES. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_AES. */

#ifndef CRYPTOGAMS_AES_ARMV4_H
#define CRYPTOGAMS_AES_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

#define AES_MAXNR 14

typedef struct AES_KEY_st {
unsigned int rd_key[4 * (AES_MAXNR + 1)];
int rounds;
} AES_KEY;

int AES_set_encrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
int AES_set_decrypt_key(const unsigned char *userKey, const int bits, AES_KEY *key);
void AES_encrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);
void AES_decrypt(const unsigned char *in, unsigned char *out, const AES_KEY *key);

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_AES_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's AES with your program.

<pre>$ gcc -std=c99 aes-armv4-test.c ./aes-armv4.o -o aes-armv4-test.exe
$ ./aes-armv4-test.exe
Encrypted plaintext!
Decrypted ciphertext!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "aes-armv4.h"

int main(int argc, char* argv[])
{
/* Test key from FIPS 197 */
const uint8_t kb[] = {
0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c
};

const uint8_t pb[] = {
0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a
};

const uint8_t cb[] = {
0x3a, 0xd7, 0x7b, 0xb4, 0x0d, 0x7a, 0x36, 0x60,
0xa8, 0x9e, 0xca, 0xf3, 0x24, 0x66, 0xef, 0x97
};

/* Scratch */
uint8_t buf[16];
int result;

/********************************************/

AES_KEY ekey;
result = AES_set_encrypt_key(kb, sizeof(kb)*8, & ekey);
assert(result == 0);

AES_encrypt(pb, buf, &ekey);
if (memcmp(cb, buf, 16) == 0)
printf("Encrypted plaintext!\n");
else
printf("Failed to encrypt plaintext!\n");

/********************************************/

AES_KEY dkey;
result = AES_set_decrypt_key(kb, sizeof(kb)*8, & dkey);
assert(result == 0);

AES_decrypt(cb, buf, &dkey);
if (memcmp(pb, buf, 16) == 0)
printf("Decrypted ciphertext!\n");
else
printf("Failed to decrypt ciphertext!\n");

return 0;
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>AES_set_encrypt_key</tt> and <tt>AES_set_decrypt_key</tt> are the names of two functions in the source code, and they will show up in the object file and when compiled and the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for AES you should rename all <tt>AES_*</tt> names. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_decrypt/MYLIB_AES_decrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_encrypt/MYLIB_AES_encrypt/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_decrypt_key/MYLIB_AES_set_decrypt_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_enc2dec_key/MYLIB_AES_set_enc2dec_key/g' aes_armv4.h aes_armv4.S
sed -i 's/AES_set_encrypt_key/MYLIB_AES_set_encrypt_key/g' aes_armv4.h aes_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include "aes-armv4.h"

typedef unsigned char byte;

int main(int argc, char* argv[])
{
const unsigned int STEPS = 128;
byte* buf = (byte*)malloc(STEPS*16+16);
memset(buf, 0x00, 16);

AES_KEY ekey;
(void)AES_set_encrypt_key(buf, 16*8, &ekey);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
AES_encrypt(&buf[idx+i], &buf[idx+i+1], &ekey);
total += 16*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 950 MHz */
const double cpuFreq = 950.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a BananaPi with a Cortex-A7 Sun7i SoC running at 950 MHz. A C/C++ AES implementation runs about 65 cpb on the dev-board. Notice <tt>aes-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -march=armv7 -c aes-armv4.S -o aes-armv7.o
$ gcc -O3 -std=c99 aes-armv7-test.c aes-armv7.o -o aes-armv7-test.exe
$ ./aes-armv7-test.exe
78426112 bytes
24.93 mbs
36.34 cpb</pre>

And the following is from a Wandboard Dual with a NXP i.MX6 Cortex-A9 running at 1 GHz. A C/C++ implementation runs around 40 cpb.

<pre>$ ./aes-armv7-test.exe
106029056 bytes
33.80 mbs
26.80 cpb</pre>

== Autotools ==

If you are using Autotools you can add the following to <tt>configure.ac</tt> and <tt>Makefile.am</tt> to conditionally compile <tt>aes-armv4.S</tt> for A-32 platforms. You will need to detect ARM A-32 and set <tt>IS_ARM32</tt> to non-0. Also see [https://www.gnu.org/software/automake/manual/html_node/Assembly-Support.html Automake Assembly Support] in section 8.13 of the manual.

First, the <tt>configure.ac</tt> recipe:

<pre># Set ASM tools
AC_SUBST([CCAS], [$CC])
AC_SUBST([CCASFLAGS], [$CFLAGS])

# Used by Makefile.am to compile aes-armv4.S
if test "$IS_ARM32" != "0"; then

## Save CFLAGS
SAVED_CFLAGS="$CFLAGS"

CFLAGS="-march=armv7-a -Wa,--noexecstack"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then

AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])

else

CFLAGS="-march=armv7-a"
AC_MSG_CHECKING([if $CC supports $CFLAGS])
AC_COMPILE_IFELSE(
[AC_LANG_PROGRAM([])],
[AC_MSG_RESULT([yes]); AC_SUBST([tr_RESULT], [1])],
[AC_MSG_RESULT([no]); AC_SUBST([tr_RESULT], [0])]
)

if test "$tr_RESULT" = "1"; then
AM_CONDITIONAL([CRYPTOGAMS_AES], [true])
AC_SUBST([CRYPTOPGAMS_FLAGS], [$CFLAGS])
else
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi
fi

## Restore CFLAGS
CFLAGS="$SAVED_CFLAGS"
else
# Required for other platforms
AM_CONDITIONAL([CRYPTOGAMS_AES], [false])
fi</pre>

Second, the <tt>Makefile.am</tt> recipe:

<pre>if CRYPTOGAMS_AES

aes_armv4_la_SOURCES = aes-armv4.S
aes_armv4_la_CCASFLAGS = $(AM_CFLAGS) $(CRYPTOGAMS_AES)

pkginclude_HEADERS += aes-armv4.h

endif</pre>

[[Category:Cryptogams]]