d5957691f2
A few things were out of date and a few things were missing. Also some formatting updates. Reviewed-by: Richard Levitte <levitte@openssl.org>
466 lines
18 KiB
Text
466 lines
18 KiB
Text
|
|
OPENSSL INSTALLATION
|
|
--------------------
|
|
|
|
[Installation on DOS (with djgpp), MacOS (before MacOS X)
|
|
and NetWare is described in INSTALL.DJGPP, INSTALL.MacOS
|
|
and INSTALL.NW.
|
|
|
|
This document describes installation on the main supported operating
|
|
systems, currently the Linux/Unix family, OpenVMS and Windows.]
|
|
|
|
To install OpenSSL, you will need:
|
|
|
|
* make
|
|
* Perl 5 with core modules (please read README.PERL)
|
|
* The perl module Text::Template (please read README.PERL)
|
|
* an ANSI C compiler
|
|
* a development environment in the form of development libraries and C
|
|
header files
|
|
* a supported operating system
|
|
|
|
For more details regarding specific platforms, there are these notes
|
|
available:
|
|
|
|
* NOTES.VMS (OpenVMS)
|
|
* NOTES.WIN (any Windows except for Windows CE)
|
|
|
|
Quick Start
|
|
-----------
|
|
|
|
If you want to just get on with it, do:
|
|
|
|
on Unix:
|
|
|
|
$ ./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
|
|
|
|
[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 ('major'_'minor').
|
|
Windows: currently don't have an install function <TBA>
|
|
|
|
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]
|
|
|
|
|
|
Configuration Options
|
|
---------------------
|
|
|
|
There are several options to ./config (or ./Configure) to customize
|
|
the build:
|
|
|
|
--prefix=DIR The top of the installation directory tree. Defaults are:
|
|
|
|
Unix: /usr/local
|
|
OpenVMS: SYS$COMMON:[OPENSSL-'version']
|
|
|
|
--openssldir=DIR Directory for OpenSSL configuration files, and also the
|
|
default certificate and key store. Defaults are:
|
|
|
|
Unix: PREFIX/ssl (PREFIX is given by --prefix)
|
|
OpenVMS: SYS$COMMON:[SSL]
|
|
|
|
--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.
|
|
|
|
no-deprecated Don't build with support for any deprecated APIs. This is the
|
|
same as using "--api" and supplying the latest version
|
|
number.
|
|
|
|
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.
|
|
|
|
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-threads Don't try to build with support for multi-threaded
|
|
applications.
|
|
|
|
threads Build with support for multi-threaded applications.
|
|
This will usually require additional system-dependent
|
|
options! See "Note on multi-threading" below.
|
|
|
|
no-zlib Don't try to build with support for zlib compression and
|
|
decompression.
|
|
|
|
zlib Build with support for zlib compression/decompression.
|
|
|
|
zlib-dynamic Like "zlib", but has OpenSSL load the zlib library
|
|
dynamically when needed. This is only supported on systems
|
|
where loading of shared libraries is supported. This is the
|
|
default choice.
|
|
|
|
no-shared Don't try to create shared libraries.
|
|
|
|
shared In addition to the usual static libraries, create shared
|
|
libraries on platforms where it's supported. See "Note on
|
|
shared libraries" below.
|
|
|
|
no-asm Do not use assembler code.
|
|
|
|
386 On Intel hardware, use the 80386 instruction set only
|
|
(the default x86 code is more efficient, but requires at
|
|
least a 486). Note: Use compiler flags for any other CPU
|
|
specific configuration, e.g. "-m32" to build x86 code on
|
|
an x64 system.
|
|
|
|
no-sse2 Exclude SSE2 code pathes. Normally SSE2 extension is
|
|
detected at run-time, but the decision whether or not the
|
|
machine code will be executed is taken solely on CPU
|
|
capability vector. This means that if you happen to run OS
|
|
kernel which does not support SSE2 extension on Intel P4
|
|
processor, then your application might be exposed to
|
|
"illegal instruction" exception. There might be a way
|
|
to enable support in kernel, e.g. FreeBSD kernel can be
|
|
compiled with CPU_ENABLE_SSE, and there is a way to
|
|
disengage SSE2 code pathes upon application start-up,
|
|
but if you aim for wider "audience" running such kernel,
|
|
consider no-sse2. Both 386 and no-asm options above imply
|
|
no-sse2.
|
|
|
|
no-<alg> Build without the specified algorithm (bf, cast, des, dh,
|
|
dsa, hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
|
|
|
|
-Dxxx, -lxxx, These system specific options will be passed through to the
|
|
-Lxxx, -fxxx, compiler to allow you to define preprocessor symbols, specify
|
|
-mXXX, -Kxxx additional libraries, library directories or other compiler
|
|
options.
|
|
|
|
|
|
Installation in Detail
|
|
----------------------
|
|
|
|
1a. Configure OpenSSL for your operation system automatically:
|
|
|
|
NOTE: This is not available on Windows.
|
|
|
|
$ ./config [options] # Unix
|
|
|
|
or
|
|
|
|
$ @config [options] ! OpenVMS
|
|
|
|
For the remainder of this text, the Unix form will be used in all
|
|
examples, please use the appropriate form for your platform.
|
|
|
|
This guesses at your operating system (and compiler, if necessary) and
|
|
configures OpenSSL based on this guess. Run ./config -t to see
|
|
if it guessed correctly. If you want to use a different compiler, you
|
|
are cross-compiling for another platform, or the ./config guess was
|
|
wrong for other reasons, go to step 1b. Otherwise go to step 2.
|
|
|
|
On some systems, you can include debugging information as follows:
|
|
|
|
$ ./config -d [options]
|
|
|
|
1b. Configure OpenSSL for your operating system manually
|
|
|
|
OpenSSL knows about a range of different operating system, hardware and
|
|
compiler combinations. To see the ones it knows about, run
|
|
|
|
$ ./Configure # Unix
|
|
|
|
or
|
|
|
|
$ perl Configure # All other platforms
|
|
|
|
For the remainder of this text, the Unix form will be used in all
|
|
examples, please use the appropriate form for your platform.
|
|
|
|
Pick a suitable name from the list that matches your system. For most
|
|
operating systems there is a choice between using "cc" or "gcc". When
|
|
you have identified your system (and if necessary compiler) use this name
|
|
as the argument to Configure. For example, a "linux-elf" user would
|
|
run:
|
|
|
|
$ ./Configure linux-elf [options]
|
|
|
|
If your system isn't listed, you will have to create a configuration
|
|
file named Configurations/{something}.conf and add the correct
|
|
configuration for your system. See the available configs as examples
|
|
and read Configurations/README and Configurations/README.design for
|
|
more information.
|
|
|
|
The generic configurations "cc" or "gcc" should usually work on 32 bit
|
|
Unix-like systems.
|
|
|
|
Configure creates a build file ("Makefile" on Unix and "descrip.mms"
|
|
on OpenVMS) from a suitable template in Configurations, and
|
|
defines various macros in crypto/opensslconf.h (generated from
|
|
crypto/opensslconf.h.in).
|
|
|
|
1c. Configure OpenSSL for building outside of the source tree.
|
|
|
|
OpenSSL can be configured to build in a build directory separate from
|
|
the directory with the source code. It's done by placing yourself in
|
|
some other directory and invoking the configuration commands from
|
|
there.
|
|
|
|
Unix example:
|
|
|
|
$ mkdir /var/tmp/openssl-build
|
|
$ cd /var/tmp/openssl-build
|
|
$ /PATH/TO/OPENSSL/SOURCE/config [options]
|
|
|
|
or
|
|
|
|
$ /PATH/TO/OPENSSL/SOURCE/Configure [target] [options]
|
|
|
|
OpenVMS example:
|
|
|
|
$ set default sys$login:
|
|
$ create/dir [.tmp.openssl-build]
|
|
$ set default [.tmp.openssl-build]
|
|
$ @[PATH.TO.OPENSSL.SOURCE]config {options}
|
|
|
|
or
|
|
|
|
$ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
|
|
|
|
Windows example:
|
|
|
|
$ C:
|
|
$ mkdir \temp-openssl
|
|
$ cd \temp-openssl
|
|
$ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {target} {options}
|
|
|
|
Paths can be relative just as well as absolute. Configure will
|
|
do its best to translate them to relative paths whenever possible.
|
|
|
|
2. Build OpenSSL by running:
|
|
|
|
$ make # Unix
|
|
$ mms ! (or mmk) OpenVMS
|
|
$ nmake # Windows
|
|
|
|
This will build the OpenSSL libraries (libcrypto.a and libssl.a on
|
|
Unix, corresponding on other platforms) and the OpenSSL binary
|
|
("openssl"). The libraries will be built in the top-level directory,
|
|
and the binary will be in the "apps" subdirectory.
|
|
|
|
If the build fails, look at the output. There may be reasons for
|
|
the failure that aren't problems in OpenSSL itself (like missing
|
|
standard headers). If it is a problem with OpenSSL itself, please
|
|
report the problem to <rt@openssl.org> (note that your message
|
|
will be recorded in the request tracker publicly readable at
|
|
https://www.openssl.org/community/index.html#bugs and will be
|
|
forwarded to a public mailing list). Please check out the request
|
|
tracker. Maybe the bug was already reported or has already been
|
|
fixed.
|
|
|
|
[If you encounter assembler error messages, try the "no-asm"
|
|
configuration option as an immediate fix.]
|
|
|
|
Compiling parts of OpenSSL with gcc and others with the system
|
|
compiler will result in unresolved symbols on some systems.
|
|
|
|
3. After a successful build, the libraries should be tested. Run:
|
|
|
|
$ make test # Unix
|
|
$ mms test ! OpenVMS
|
|
$ nmake test # Windows
|
|
|
|
If some tests fail, look at the output. There may be reasons for
|
|
the failure that isn't a problem in OpenSSL itself (like a
|
|
malfunction with Perl). You may want increased verbosity, that
|
|
can be accomplished like this:
|
|
|
|
$ HARNESS_VERBOSE=yes make test # Unix
|
|
|
|
$ DEFINE HARNESS_VERBOSE YES
|
|
$ mms test ! OpenVMS
|
|
|
|
$ set HARNESS_VERBOSE=yes
|
|
$ nmake test # Windows
|
|
|
|
If you want to run just one or a few specific tests, you can use
|
|
the make variable TESTS to specify them, like this:
|
|
|
|
$ make TESTS='test_rsa test_dsa' test # Unix
|
|
$ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS
|
|
$ nmake TESTS='test_rsa test_dsa' test # Windows
|
|
|
|
And of course, you can combine (Unix example shown):
|
|
|
|
$ HARNESS_VERBOSE=yes make TESTS='test_rsa test_dsa' test
|
|
|
|
You can find the list of available tests like this:
|
|
|
|
$ make list-tests # Unix
|
|
$ mms list-tests ! OpenVMS
|
|
$ nmake list-tests # Windows
|
|
|
|
Have a look at the manual for the perl module Test::Harness to
|
|
see what other HARNESS_* variables there are.
|
|
|
|
If you find a problem with OpenSSL itself, try removing any
|
|
compiler optimization flags from the CFLAGS line in Makefile and
|
|
run "make clean; make" or corresponding.
|
|
|
|
Please send a bug reports to <rt@openssl.org>.
|
|
|
|
4. If everything tests ok, install OpenSSL with
|
|
|
|
$ make install # Unix
|
|
$ mms install ! OpenVMS
|
|
|
|
This will install all the software components in this directory
|
|
tree under PREFIX (the directory given with --prefix or its
|
|
default):
|
|
|
|
Unix:
|
|
|
|
bin/ Contains the openssl binary and a few other
|
|
utility scripts.
|
|
include/openssl
|
|
Contains the header files needed if you want
|
|
to build your own programs that use libcrypto
|
|
or libssl.
|
|
lib Contains the OpenSSL library files.
|
|
lib/engines Contains the OpenSSL dynamically loadable engines.
|
|
share/man/{man1,man3,man5,man7}
|
|
Contains the OpenSSL man-pages.
|
|
share/doc/openssl/html/{man1,man3,man5,man7}
|
|
Contains the HTML rendition of the man-pages.
|
|
|
|
OpenVMS ('arch' is replaced with the architecture name, "Alpha"
|
|
or "ia64"):
|
|
|
|
[.EXE.'arch'] Contains the openssl binary and a few other
|
|
utility scripts.
|
|
[.include.openssl]
|
|
Contains the header files needed if you want
|
|
to build your own programs that use libcrypto
|
|
or libssl.
|
|
[.LIB.'arch'] Contains the OpenSSL library files.
|
|
[.ENGINES.'arch']
|
|
Contains the OpenSSL dynamically loadable engines.
|
|
[.SYS$STARTUP] Contains startup, login and shutdown scripts.
|
|
These define appropriate logical names and
|
|
command symbols.
|
|
|
|
|
|
Additionally, install will add the following directories under
|
|
OPENSSLDIR (the directory given with --openssldir or its default)
|
|
for you convenience:
|
|
|
|
certs Initially empty, this is the default location
|
|
for certificate files.
|
|
private Initially empty, this is the default location
|
|
for private key files.
|
|
misc Various scripts.
|
|
|
|
Package builders who want to configure the library for standard
|
|
locations, but have the package installed somewhere else so that
|
|
it can easily be packaged, can use
|
|
|
|
$ make DESTDIR=/tmp/package-root install # Unix
|
|
$ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
|
|
|
|
The specified destination directory will be prepended to all
|
|
installation target paths.
|
|
|
|
Compatibility issues with previous OpenSSL versions:
|
|
|
|
* COMPILING existing applications
|
|
|
|
OpenSSL 1.1 hides a number of structures that were previously
|
|
open. This includes all internal libssl structures and a number
|
|
of EVP types. Accessor functions have been added to allow
|
|
controlled access to the structures' data.
|
|
|
|
This means that some software needs to be rewritten to adapt to
|
|
the new ways of doing things. This often amounts to allocating
|
|
an instance of a structure explicitly where you could previously
|
|
allocate them on the stack as automatic variables, and using the
|
|
provided accessor functions where you would previously access a
|
|
structure's field directly.
|
|
|
|
<TBA>
|
|
|
|
Some APIs have changed as well. However, older APIs have been
|
|
preserved when possible.
|
|
|
|
|
|
Note on multi-threading
|
|
-----------------------
|
|
|
|
For some systems, the OpenSSL Configure script knows what compiler options
|
|
are needed to generate a library that is suitable for multi-threaded
|
|
applications. On these systems, support for multi-threading is enabled
|
|
by default; use the "no-threads" option to disable (this should never be
|
|
necessary).
|
|
|
|
On other systems, to enable support for multi-threading, you will have
|
|
to specify at least two options: "threads", and a system-dependent option.
|
|
(The latter is "-D_REENTRANT" on various systems.) The default in this
|
|
case, obviously, is not to include support for multi-threading (but
|
|
you can still use "no-threads" to suppress an annoying warning message
|
|
from the Configure script.)
|
|
|
|
OpenSSL provides built-in support for two threading models: pthreads (found on
|
|
most UNIX/Linux systems), and Windows threads. No other threading models are
|
|
supported. If your platform does not provide pthreads or Windows threads then
|
|
you should Configure with the "no-threads" option.
|
|
|
|
Note on shared libraries
|
|
------------------------
|
|
|
|
Shared libraries have certain caveats. Binary backward compatibility
|
|
can't be guaranteed before OpenSSL version 1.0. The only reason to
|
|
use them would be to conserve memory on systems where several programs
|
|
are using OpenSSL.
|
|
|
|
For most systems, the OpenSSL Configure script knows what is needed to
|
|
build shared libraries for libcrypto and libssl. On these systems,
|
|
the shared libraries are currently not created by default, but giving
|
|
the option "shared" will get them created.
|
|
|
|
Note on random number generation
|
|
--------------------------------
|
|
|
|
Availability of cryptographically secure random numbers is required for
|
|
secret key generation. OpenSSL provides several options to seed the
|
|
internal PRNG. If not properly seeded, the internal PRNG will refuse
|
|
to deliver random bytes and a "PRNG not seeded error" will occur.
|
|
On systems without /dev/urandom (or similar) device, it may be necessary
|
|
to install additional support software to obtain random seed.
|
|
Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
|
|
and the FAQ for more information.
|
|
|