OPENSSL INSTALLATION
--------------------
This document describes installation on all supported operating
systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
and Windows).
To install OpenSSL, you will need:
* A make implementation
* Perl 5 with core modules (please read NOTES.PERL)
* The perl module Text::Template (please read NOTES.PERL)
* 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.UNIX (any supported Unix like system)
* NOTES.VMS (OpenVMS)
* NOTES.WIN (any supported Windows)
* NOTES.DJGPP (DOS platform with DJGPP)
* NOTES.ANDROID (obviously Android [NDK])
* NOTES.VALGRIND (testing with Valgrind)
Notational conventions in this document
---------------------------------------
Throughout this document, we use the following conventions in command
examples:
$ command Any line starting with a dollar sign
($) is a command line.
{ word1 | word2 | word3 } This denotes a mandatory choice, to be
replaced with one of the given words.
A simple example would be this:
$ echo { FOO | BAR | COOKIE }
which is to be understood as one of
these:
$ echo FOO
- or -
$ echo BAR
- or -
$ echo COOKIE
[ word1 | word2 | word3 ] Similar to { word1 | word2 | word3 }
except it's optional to give any of
those. In addition to the examples
above, this would also be valid:
$ echo
{{ target }} This denotes a mandatory word or
sequence of words of some sort. A
simple example would be this:
$ type {{ filename }}
which is to be understood to use the
command 'type' on some file name
determined by the user.
[[ options ]] Similar to {{ target }}, but is
optional.
Note that the notation assumes spaces around {, }, [, ], {{, }} and
[[, ]]. This is to differentiate from OpenVMS directory
specifications, which also use [ and ], but without spaces.
Quick Start
-----------
If you want to just get on with it, do:
on Unix (again, this includes Mac OS/X):
$ ./config
$ make
$ make test
$ make install
on OpenVMS:
$ @config
$ mms
$ mms test
$ mms install
on Windows (only pick one of the targets for configuration):
$ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
$ nmake
$ nmake test
$ nmake install
Note that in order to perform the install step above you need to have
appropriate permissions to write to the installation directory.
If any of these steps fails, see section Installation in Detail below.
This will build and install OpenSSL in the default location, which is:
Unix: normal installation directories under /usr/local
OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
OpenSSL version number with underscores instead of periods.
Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL
The installation directory should be appropriately protected to ensure
unprivileged users cannot make changes to OpenSSL binaries or files, or install
engines. If you already have a pre-installed version of OpenSSL as part of
your Operating System it is recommended that you do not overwrite the system
version and instead install to somewhere else.
If you want to install it anywhere else, run config like this:
On Unix:
$ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
On OpenVMS:
$ @config --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 ./config (or ./Configure) to customize
the build (note that for Windows, the defaults for --prefix and
--openssldir depend in what configuration is used and what Windows
implementation OpenSSL is built on. More notes on this in NOTES.WIN):
--api=x.y.z
Don't build with support for deprecated APIs below the
specified version number. For example "--api=1.1.0" 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 entirely (up to the current version), it is easier
to add the 'no-deprecated' option instead (see below).
--cross-compile-prefix=PREFIX
The PREFIX to include in front of commands for your
toolchain. It's 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 case. Needless to mention that you have to
invoke ./Configure, not ./config, and pass your target
name explicitly. Also, note that --openssldir refers
to target's file system, not one you are building on.
--debug
Build OpenSSL with debugging symbols and zero optimization
level.
--libdir=DIR
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 ".lib" files will be stored in this location. dll files
will always be installed to the "bin" directory.
--openssldir=DIR
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
or C:\Program Files (x86)\Common Files\SSL
OpenVMS: SYS$COMMON:[OPENSSL-COMMON]
--prefix=DIR
The top of the installation directory tree. Defaults are:
Unix: /usr/local
Windows: C:\Program Files\OpenSSL
or C:\Program Files (x86)\OpenSSL
OpenVMS: SYS$COMMON:[OPENSSL-'version']
--release
Build OpenSSL without debugging symbols. This is the default.
--strict-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.
--with-zlib-include=DIR
The directory for the location of the zlib include file. This
option is only necessary if enable-zlib (see bel