Compilation and Installation

From OpenSSLWiki
Revision as of 11:14, 23 June 2016 by Jwalton (talk | contribs) ("can also" -> "usually")
Jump to navigationJump to search

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.

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. Its currently available in Master through Git. 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.

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

OpenSSL's build system does not rely upon autotools or libtool. Also see Why aren't tools like 'autoconf' and 'libtool' used? in the OpenSSL FAQ.

Retrieve source code

The OpenSSL source code can be downloaded from OpenSSL Source Tarballs or any suitable 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 GitHub mirror. This repository is updated every 15 minutes.

Configuration

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

Supported Platforms

You can run Configure LIST to see a list of available platforms. 

$ ./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
...

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.

Configure & Config

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): 

$ ./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
    ...

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

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

You can also configure on Darwin by exporting KERNEL_BITS: 

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

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

$ ./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]

And if you supply an unknown triplet: 

$ ./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'.

Dependencies

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.

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 Configure and config, and the following lists some of them.

Note: it is not necessary to specify --prefix. If --prefix is not specified, then --openssldir is used. If --openssldir is not specified, the the default /usr/local/ssl is used.

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.

OpenSSL Library Options
Option Description
--openssldir=XXX The installation directory. If not specified, the library will be installed at /usr/local/ssl. Header will be located at /usr/local/ssl/include/openssl, and libraries located at /usr/local/ssl/lib.
-d 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
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.
enable-capieng Enables the Microsoft CAPI engine on Windows platforms. Used to access the Windows Certificate Store. Also see Using Windows certificate store through OpenSSL on the OpenSSL developer list.
no-ssl2 Disables SSLv2. OPENSSL_NO_SSL2 will be defined in the OpenSSL headers.
no-ssl3 Disables SSLv3. OPENSSL_NO_SSL3 will be defined in the OpenSSL headers.
no-comp Disables compression independent of zlib. OPENSSL_NO_COMP 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 (useful on mobile devices since carriers often block UDP)
no-shared Disables shared objects (only a static library is created)
no-hw Disables hardware support (useful on mobile devices)
no-engines 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 no-nextprotoneg for 1.1.0 and above; and no-npn 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 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.
-DOPENSSL_USE_IPV6=0 Disables IPv6. Useful if OpenSSL encounters incorrect or inconsistent platform headers and mistakenly enables IPv6. Must be passed to Configure manually.
-Lsomething, -lsomething, -Ksomething, -Wl,something Linker options, will become part of LDFLAGS.
-anythingelse, +anythingelse Compiler options, will become part of CFLAGS.

Note: to configure with -ansi, you will need the rollup patch detailed at Issue 4479: OS X 10.8 (x86_64): Compile errors when using "no-asm -ansi" and Issue 4480: Ubuntu 14 (x86_64): Compile errors and warnings when using "no-asm -ansi". Its the same patch and removes some cruft that's built up over the years that causes the failed compiles.

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: 

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

Debug Configuration

From the list above, its possible to quickly configure a "debug" build with ./config -d. However, you can often get into a more amicable state without the Electric Fence dependency by issuing: 

$ ./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
...

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

Modifying Build Settings

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. 

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

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

make dclean

./config
make depend
make all
...

Using RPATHs

RPATH's are supported by default on the BSD platforms, but not others. One of the easiest ways to add a RPATH is to perform: 

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

You can also add and 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, named it linux-x86_64-rpath, and make the following change to add the -rpath option. Notice the addition of -Wl,-rpath=... in two places. 

"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",

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

Then, Configure with the new configuration: 

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

Finally, after make, verify the settings stuck: 

$ 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]

Once you perform make install, then ldd will produce expected results: 

$ 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)
...

FIPS Capable Library

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: 

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

Compile Time Checking

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: 

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

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

Compilation

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

Quick

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

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 Configure and use the x32 triplet: 

# ./Configure LIST | grep x32
linux-x32
...

Then: 

# ./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
...

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

Windows

3noch wrote a VERY good guide 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++.

Using MS Visual Studio:

  1. launch a Visual Studio tool x64 Cross Tools Command prompt
  2. change to the directory where you have copied openssl sources cd c:\myPath\openssl
  3. 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.
  4. prepare the target environment with the command: ms\do_win64a
  5. 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.
  6. build the code with: nmake -f ms\ntdll.mak (respectively nmake -f ms\nt.mak )
  7. 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 'dumbin'. For instance dumpbin /headers out32dll/libeay32.lib | more, and look at the FILE HEADER section.
  8. 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
  9. 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

Mac

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: 

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

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

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

If you want to build a multiarch OpenSSL library, then see this answer on Stack Overflow: Build Multiarch OpenSSL on OS X.

iOS

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

Retrieved from "https://wiki.openssl.org/index.php?title=Compilation_and_Installation&oldid=2408"