Compilation and Installation

The following page is a combination of the INSTALL 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 INSTALL 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 makefile.org. Once configured, you use make to build the library. You should avoid custom build systems because they often miss details, like each architecture and platform has a unique opensslconf.h and bn.h generated by Configure.

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 Configure and places individual configurations in the Configurations directory. Also, the second generation is more platform agnostic and uses templates to produce a final, top level build file (Makefile, descrip.mms, what have you).

After you configure and build the library, you should always perform a make test 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 high (see README.PERL for details).

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

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

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

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

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

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

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 Configure and config, 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.

Debug build of the library. Optimizations are disabled (no -O3 or similar) and libefence is used (apt-get install electric-fence or yum install electric-fence). TODO: Any other features?

shared

Build a shared object in addition to the static archive. You probably need a RPATH when enabling shared to ensure openssl uses the correct libssl and libcrypto after installation.

enable-ec_nistp_64_gcc_128

Use on little endian platforms when GCC supports __uint128_t. ECDH is about 2 to 4 times faster. Not enabled by default because Configure can't determine it. Enable it if your compiler defines __SIZEOF_INT128__, the CPU is little endian and it tolerates unaligned data access.

Used when configuring FIPS Capable Library with a FIPS Object Module that only includes prime curves. That is, use this switch if you use openssl-fips-ecp-2.0.5.

no-weak-ssl-ciphers

Disables RC4. Available in OpenSSL 1.1.0 and above.

-DXXX

Defines XXX. For example, -DOPENSSL_NO_HEARTBEATS.

-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 (-fsanitize=undefined).

Note: on older OSes, like CentOS 5, BSD 5, and Windows XP or Vista, you will need to configure with no-async 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 __uint128_t with the following:

--prefix and --openssldir control the configuration of installed components. The behavior and interactions of --prefix and --openssldir 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--prefix and --openssldir

set --prefix and --openssldir to the same location

One word of caution is avoid--prefix=/usr when OpenSSL versions are notbinary 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 --prefix. If --prefix is not specified, then --openssldir is used. However, specifying only--prefix may result in broken builds because the 1.0.2 build system attempts to build in a FIPS configuration.

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

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

OpenSSL 1.1.0 and above

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

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

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

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

Modifies Configure to use clang

Modifies Makefile.org to use clang

Modifies CFLAG to use -Os

Modifies MAKEDEPPROG to use $(CC) -M

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

RPATH'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 RPATH is to configure with it as shown below.

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

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 RPATH by hard coding the RPATH into a configure line. For example, on Debian x86_64 open the file Configure in an editor, copy linux-x86_64, name it linux-x86_64-rpath, and make the following change to add the -rpath option. Notice the addition of -Wl,-rpath=... in two places.

If you want to use FIPS validated cryptography, you download, build and install the FIPS Object Module (openssl-fips-2.0.5.tar.gz) according to the FIPS User Guide 2.0 and FIPS 140-2 Security Policy. You then download, build and install the FIPS Capable Library (openssl-1.0.1e.tar.gz).

When configuring the FIPS Capable Library, you must use fips as an option:

./config fips <other options ...>

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

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

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

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

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

Using MS Visual Studio:

launch a Visual Studio tool x64 Cross Tools Command prompt

change to the directory where you have copied openssl sources cd c:\myPath\openssl

configure for the target OS with the command perl Configure VC-WIN64A. You may also be interested to set more configuration options as documented in the general INSTALL note (for UNIX targets). For instance: perl Configure no-asm VC-WIN64A.

prepare the target environment with the command: ms\do_win64a

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: nmake -f ms\ntdll.mak clean for the DLL target and nmake -f ms\nt.mak clean for static libraries.

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 dumpbin /headers out32dll/libeay32.lib | more, 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 nmake -f ms\ntdll.mak test

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.

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 OPENSSL_init_ssl or SSL_library_init from libssl. To craft a feature test for OpenSSL that recognizes both OPENSSL_init_ssl and SSL_library_init, you can use the following.