1738 lines
58 KiB
Raw Normal View History

Build and Install
This document describes installation on all supported operating
systems (the Unix/Linux family, including macOS), OpenVMS,
and Windows).
Table of Contents
- [Prerequisites](#prerequisites)
- [Notational Conventions](#notational-conventions)
- [Quick Installation Guide](#quick-installation-guide)
- [Building OpenSSL](#building-openssl)
- [Installing OpenSSL](#installing-openssl)
- [Configuration Options](#configuration-options)
- [API Level](#api-level)
- [Cross Compile Prefix](#cross-compile-prefix)
- [Build Type](#build-type)
- [Directories](#directories)
- [Compiler Warnings](#compiler-warnings)
- [ZLib Flags](#zlib-flags)
- [Seeding the Random Generator](#seeding-the-random-generator)
- [Setting the FIPS HMAC key](#setting-the-FIPS-HMAC-key)
- [Enable and Disable Features](#enable-and-disable-features)
- [Displaying configuration data](#displaying-configuration-data)
- [Installation Steps in Detail](#installation-steps-in-detail)
- [Configure](#configure-openssl)
- [Build](#build-openssl)
- [Test](#test-openssl)
- [Install](#install-openssl)
- [Advanced Build Options](#advanced-build-options)
- [Environment Variables](#environment-variables)
- [Makefile Targets](#makefile-targets)
- [Running Selected Tests](#running-selected-tests)
- [Troubleshooting](#troubleshooting)
- [Configuration Problems](#configuration-problems)
- [Build Failures](#build-failures)
- [Test Failures](#test-failures)
- [Notes](#notes)
- [Notes on multi-threading](#notes-on-multi-threading)
- [Notes on shared libraries](#notes-on-shared-libraries)
- [Notes on random number generation](#notes-on-random-number-generation)
To install OpenSSL, you will need:
* A "make" implementation
* Perl 5 with core modules (please read [](
* The Perl module `Text::Template` (please read [](
* an ANSI C compiler
* a development environment in the form of development libraries and C
header files
* a supported operating system
For additional platform specific requirements, solutions to specific
issues and other details, please read one of these:
* []( - notes for Unix like systems
* []( - notes related to OpenVMS
* [NOTES-Windows.txt](NOTES-Windows.txt) - notes related to the Windows platform
* []( - building for DOS with DJGPP
* []( - building for Android platforms (using NDK)
* []( - testing with Valgrind
* [NOTES-Perl.m]( - some notes on Perl
Notational conventions
Throughout this document, we use the following conventions.
Any line starting with a dollar sign is a command line.
$ command
The dollar sign indicates the shell prompt and is not to be entered as
part of the command.
Several words in curly braces separated by pipe characters indicate a
**mandatory choice**, to be replaced with one of the given words.
For example, the line
$ echo { WORD1 | WORD2 | WORD3 }
represents one of the following three commands
$ echo WORD1
- or -
$ echo WORD2
- or -
$ echo WORD3
One or several words in square brackets separated by pipe characters
denote an **optional choice**. It is similar to the mandatory choice,
but it can also be omitted entirely.
So the line
$ echo [ WORD1 | WORD2 | WORD3 ]
represents one of the four commands
$ echo WORD1
- or -
$ echo WORD2
- or -
$ echo WORD3
- or -
$ echo
**Mandatory arguments** are enclosed in double curly braces.
A simple example would be
$ type {{ filename }}
which is to be understood to use the command `type` on some file name
determined by the user.
**Optional Arguments** are enclosed in double square brackets.
[[ options ]]
Note that the notation assumes spaces around `{`, `}`, `[`, `]`, `{{`, `}}` and
`[[`, `]]`. This is to differentiate from OpenVMS directory
specifications, which also use [ and ], but without spaces.
Quick Installation Guide
If you just want to get OpenSSL installed without bothering too much
about the details, here is the short version of how to build and install
OpenSSL. If any of the following steps fails, please consult the
[Installation in Detail](#installation-steps-in-detail) section below.
Building OpenSSL
Use the following commands to configure, build and test OpenSSL.
The testing is optional, but recommended if you intend to install
OpenSSL for production use.
### Unix / Linux / macOS
$ ./Configure
$ make
$ make test
### OpenVMS
Use the following commands to build OpenSSL:
$ perl Configure
$ mms
$ mms test
### Windows
If you are using Visual Studio, open a Developer Command Prompt and
issue the following commands to build OpenSSL.
$ perl Configure
$ nmake
$ nmake test
As mentioned in the [Choices](#choices) section, you need to pick one
of the four Configure targets in the first command.
Most likely you will be using the `VC-WIN64A` target for 64bit Windows
binaries (AMD64) or `VC-WIN32` for 32bit Windows binaries (X86).
The other two options are `VC-WIN64I` (Intel IA64, Itanium) and
`VC-CE` (Windows CE) are rather uncommon nowadays.
Installing OpenSSL
The following commands will install OpenSSL to a default system location.
**Danger Zone:** even if you are impatient, please read the following two
paragraphs carefully before you install OpenSSL.
For security reasons the default system location is by default not writable
for unprivileged users. So for the final installation step administrative
privileges are required. The default system location and the procedure to
obtain administrative privileges depends on the operating system.
It is recommended to compile and test OpenSSL with normal user privileges
and use administrative privileges only for the final installation step.
On some platforms OpenSSL is preinstalled as part of the Operating System.
In this case it is highly recommended not to overwrite the system versions,
because other applications or libraries might depend on it.
To avoid breaking other applications, install your copy of OpenSSL to a
[different location](#installing-to-a-different-location) which is not in
the global search path for system libraries.
Finally, if you plan on using the FIPS module, you need to read the
[Post-installation Notes](#post-installation-notes) further down.
### Unix / Linux / macOS
Depending on your distribution, you need to run the following command as
root user or prepend `sudo` to the command:
$ make install
By default, OpenSSL will be installed to
More precisely, the files will be installed into the subdirectories
depending on the file type, as it is custom on Unix-like operating systems.
### OpenVMS
Use the following command to install OpenSSL.
$ mms install
By default, OpenSSL will be installed to
where 'version' is the OpenSSL version number with underscores instead
of periods.
### Windows
If you are using Visual Studio, open the Developer Command Prompt _elevated_
and issue the following command.
$ nmake install
The easiest way to elevate the Command Prompt is to press and hold down
the both the `<CTRL>` and `<SHIFT>` key while clicking the menu item in the
task menu.
The default installation location is
C:\Program Files\OpenSSL
for native binaries, or
1999-04-30 20:22:59 +02:00
C:\Program Files (x86)\OpenSSL
for 32bit binaries on 64bit Windows (WOW64).
#### Installing to a different location
To install OpenSSL to a different location (for example into your home
directory for testing purposes) run `Configure` as shown in the following
On Unix:
$ ./Configure --prefix=/opt/openssl --openssldir=/usr/local/ssl
On OpenVMS:
$ perl Configure --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
Note: if you do add options to the configuration command, please make sure
you've read more than just this Quick Start, such as relevant `NOTES-*` files,
the options outline below, as configuration options may change the outcome
in otherwise unexpected ways.
Configuration Options
There are several options to `./Configure` to customize the build (note that
for Windows, the defaults for `--prefix` and `--openssldir` depend on what
configuration is used and what Windows implementation OpenSSL is built on.
More notes on this in [NOTES-Windows.txt](NOTES-Windows.txt):
API Level
Build the OpenSSL libraries to support the API for the specified version.
If [no-deprecated](#no-deprecated) is also given, don't build with support
for deprecated APIs in or below the specified version number. For example,
--api=1.1.0 no-deprecated
will remove support for all APIs that were deprecated in OpenSSL version
1.1.0 or below. This is a rather specialized option for developers.
If you just intend to remove all deprecated APIs up to the current version
entirely, just specify [no-deprecated](#no-deprecated).
If `--api` isn't given, it defaults to the current (minor) OpenSSL version.
Cross Compile Prefix
The `<PREFIX>` to include in front of commands for your toolchain.
It is likely to have to end with dash, e.g. `a-b-c-` would invoke GNU compiler
as `a-b-c-gcc`, etc. Unfortunately cross-compiling is too case-specific to put
together one-size-fits-all instructions. You might have to pass more flags or
set up environment variables to actually make it work. Android and iOS cases
are discussed in corresponding `Configurations/15-*.conf` files. But there are
cases when this option alone is sufficient. For example to build the mingw64
target on Linux `--cross-compile-prefix=x86_64-w64-mingw32-` works. Naturally
provided that mingw packages are installed. Today Debian and Ubuntu users
have option to install a number of prepackaged cross-compilers along with
corresponding run-time and development packages for "alien" hardware. To give
another example `--cross-compile-prefix=mipsel-linux-gnu-` suffices in such
For cross compilation, you must [configure manually](#manual-configuration).
Also, note that `--openssldir` refers to target's file system, not one you are
building on.
Build Type
Build OpenSSL with debugging symbols and zero optimization level.
Build OpenSSL without debugging symbols. This is the default.
### libdir
The name of the directory under the top of the installation directory tree
(see the `--prefix` option) where libraries will be installed. By default
this is `lib/`. Note that on Windows only static libraries (`*.lib`) will
be stored in this location. Shared libraries (`*.dll`) will always be
installed to the `bin/` directory.
### openssldir
Directory for OpenSSL configuration files, and also the default certificate
and key store. Defaults are:
Unix: /usr/local/ssl
Windows: C:\Program Files\Common Files\SSL
For 32bit Windows applications on Windows 64bit (WOW64), always replace
`C:\Program Files` by `C:\Program Files (x86)`.
### prefix
The top of the installation directory tree. Defaults are:
Unix: /usr/local
Windows: C:\Program Files\OpenSSL
Compiler Warnings
This is a developer flag that switches on various compiler options recommended
for OpenSSL development. It only works when using gcc or clang as the compiler.
If you are developing a patch for OpenSSL then it is recommended that you use
this option where possible.
ZLib Flags
### with-zlib-include
The directory for the location of the zlib include file. This option is only
necessary if [zlib](#zlib) is used and the include file is not
already on the system include path.
### with-zlib-lib
**On Unix**: this is the directory containing the zlib library.
If not provided the system library path will be used.
**On Windows:** this is the filename of the zlib library (with or
without a path). This flag must be provided if the
[zlib-dynamic](#zlib-dynamic) option is not also used. If `zlib-dynamic` is used
then this flag is optional and defaults to `ZLIB1` if not provided.
**On VMS:** this is the filename of the zlib library (with or without a path).
This flag is optional and if not provided then `GNV$LIBZSHR`, `GNV$LIBZSHR32`
or `GNV$LIBZSHR64` is used by default depending on the pointer size chosen.
Seeding the Random Generator
A comma separated list of seeding methods which will be tried by OpenSSL
in order to obtain random input (a.k.a "entropy") for seeding its
cryptographically secure random number generator (CSPRNG).
The current seeding methods are:
### os
Use a trusted operating system entropy source.
This is the default method if such an entropy source exists.
### getrandom
Use the [getrandom(2)][man-getrandom] or equivalent system call.
### devrandom
Use the first device from the `DEVRANDOM` list which can be opened to read
random bytes. The `DEVRANDOM` preprocessor constant expands to
on most unix-ish operating systems.
### egd
Check for an entropy generating daemon.
This source is ignored by the FIPS provider.
### rdcpu
Use the `RDSEED` or `RDRAND` command if provided by the CPU.
### librandom
Use librandom (not implemented yet).
This source is ignored by the FIPS provider.
### none
Disable automatic seeding. This is the default on some operating systems where
no suitable entropy source exists, or no support for it is implemented yet.
This option is ignored by the FIPS provider.
For more information, see the section [Notes on random number generation][rng]
at the end of this document.
[rng]: #notes-on-random-number-generation
Setting the FIPS HMAC key
As part of its self-test validation, the FIPS module must verify itself
by performing a SHA-256 HMAC computation on itself. The default key is
the SHA256 value of "the holy handgrenade of antioch" and is sufficient
for meeting the FIPS requirements.
To change the key to a different value, use this flag. The value should
be a hex string no more than 64 characters.
Enable and Disable Features
Feature options always come in pairs, an option to enable feature
`xxxx`, and an option to disable it:
[ enable-xxxx | no-xxxx ]
Whether a feature is enabled or disabled by default, depends on the feature.
In the following list, always the non-default variant is documented: if
feature `xxxx` is disabled by default then `enable-xxxx` is documented and
if feature `xxxx` is enabled by default then `no-xxxx` is documented.
### no-afalgeng
Don't build the AFALG engine.
This option will be forced on a platform that does not support AFALG.
### enable-ktls
Build with Kernel TLS support.
This option will enable the use of the Kernel TLS data-path, which can improve
performance and allow for the use of sendfile and splice system calls on
TLS sockets. The Kernel may use TLS accelerators if any are available on the
system. This option will be forced off on systems that do not support the
Kernel TLS data-path.
### enable-asan
Build with the Address sanitiser.
This is a developer option only. It may not work on all platforms and should
never be used in production environments. It will only work when used with
gcc or clang and should be used in conjunction with the [no-shared](#no-shared)
### no-acvp_tests
Do not build support for Automated Cryptographic Validation Protocol (ACVP)
This is required for FIPS validation purposes. Certain ACVP tests require
access to algorithm internals that are not normally accessible.
Additional information related to ACVP can be found at
### no-asm
Do not use assembler code.
This should be viewed as debugging/troubleshooting option rather than for
production use. On some platforms a small amount of assembler code may still
be used even with this option.
### no-async
Do not build support for async operations.
### no-autoalginit
Don't automatically load all supported ciphers and digests.
Typically OpenSSL will make available all of its supported ciphers and digests.
For a statically linked application this may be undesirable if small executable
size is an objective. This only affects libcrypto. Ciphers and digests will
have to be loaded manually using `EVP_add_cipher()` and `EVP_add_digest()`
if this option is used. This option will force a non-shared build.
### no-autoerrinit
Don't automatically load all libcrypto/libssl error strings.
Typically OpenSSL will automatically load human readable error strings. For a
statically linked application this may be undesirable if small executable size
is an objective.
### no-autoload-config
Don't automatically load the default `openssl.cnf` file.
Typically OpenSSL will automatically load a system config file which configures
default SSL options.
### enable-buildtest-c++
While testing, generate C++ buildtest files that simply check that the public
OpenSSL header files are usable standalone with C++.
Enabling this option demands extra care. For any compiler flag given directly
as configuration option, you must ensure that it's valid for both the C and
the C++ compiler. If not, the C++ build test will most likely break. As an
alternative, you can use the language specific variables, `CFLAGS` and `CXXFLAGS`.
### no-bulk
Build only some minimal set of features.
This is a developer option used internally for CI build tests of the project.
### no-capieng
Don't build the CAPI engine.
This option will be forced if on a platform that does not support CAPI.
### no-cmp
Don't build support for Certificate Management Protocol (CMP)
and Certificate Request Message Format (CRMF).
### no-cms
Don't build support for Cryptographic Message Syntax (CMS).
### no-comp
Don't build support for SSL/TLS compression.
If this option is enabled (the default), then compression will only work if
the zlib or `zlib-dynamic` options are also chosen.
### enable-crypto-mdebug
This now only enables the `failed-malloc` feature.
### enable-crypto-mdebug-backtrace
This is a no-op; the project uses the compiler's address/leak sanitizer instead.
### no-ct
Don't build support for Certificate Transparency (CT).
### no-deprecated
Don't build with support for deprecated APIs up until and including the version
given with `--api` (or the current version, if `--api` wasn't specified).
### no-dgram
Don't build support for datagram based BIOs.
Selecting this option will also force the disabling of DTLS.
### no-dso
Don't build support for loading Dynamic Shared Objects (DSO)
### enable-devcryptoeng
Build the `/dev/crypto` engine.
This option is automatically selected on the BSD platform, in which case it can
be disabled with `no-devcryptoeng`.
### no-dynamic-engine
Don't build the dynamically loaded engines.
This only has an effect in a shared build.
### no-ec
Don't build support for Elliptic Curves.
### no-ec2m
Don't build support for binary Elliptic Curves
### enable-ec_nistp_64_gcc_128
Enable support for optimised implementations of some commonly used NIST
elliptic curves.
This option is only supported on platforms:
- with little-endian storage of non-byte types
- that tolerate misaligned memory references
- where the compiler:
- supports the non-standard type `__uint128_t`
- defines the built-in macro `__SIZEOF_INT128__`
### enable-egd
Build support for gathering entropy from the Entropy Gathering Daemon (EGD).
### no-engine
Don't build support for loading engines.
### no-err
Don't compile in any error strings.
### enable-external-tests
Enable building of integration with external test suites.
This is a developer option and may not work on all platforms. The following
external test suites are currently supported:
- BoringSSL test suite
- Python PYCA/Cryptography test suite
- krb5 test suite
See the file [test/](test/
for further details.
### no-filenames
Don't compile in filename and line number information (e.g. for errors and
memory allocation).
### no-fips
Don't compile the FIPS provider
### no-fips-securitychecks
Don't perform FIPS module run-time checks related to enforcement of security
parameters such as minimum security strength of keys.
### enable-fuzz-libfuzzer, enable-fuzz-afl
Build with support for fuzzing using either libfuzzer or AFL.
These are developer options only. They may not work on all platforms and
should never be used in production environments.
See the file [fuzz/](fuzz/ for further details.
### no-gost
Don't build support for GOST based ciphersuites.
Note that if this feature is enabled then GOST ciphersuites are only available
if the GOST algorithms are also available through loading an externally supplied
### no-legacy
Don't build the legacy provider.
Disabling this also disables the legacy algorithms: MD2 (already disabled by default).
### no-makedepend
Don't generate dependencies.
### no-module
Don't build any dynamically loadable engines.
This also implies `no-dynamic-engine`.
### no-multiblock
Don't build support for writing multiple records in one go in libssl
Note: this is a different capability to the pipelining functionality.
### no-nextprotoneg
Don't build support for the Next Protocol Negotiation (NPN) TLS extension.
### no-ocsp
Don't build support for Online Certificate Status Protocol (OCSP).
### no-padlockeng
Don't build the padlock engine.
### no-hw-padlock
As synonym for `no-padlockeng`. Deprecated and should not be used.