-
OPENSSL INSTALLATION
--------------------
This document describes installation on all supported operating
- systems (the Linux/Unix family, OpenVMS and Windows)
+ systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
+ and Windows).
To install OpenSSL, you will need:
* NOTES.VMS (OpenVMS)
* NOTES.WIN (any supported Windows)
* NOTES.DJGPP (DOS platform with DJGPP)
+ * NOTES.ANDROID (obviously Android [NDK])
Notational conventions in this document
---------------------------------------
If you want to just get on with it, do:
- on Unix:
+ on Unix (again, this includes Mac OS/X):
$ ./config
$ make
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/10-main.cf
- sections. But there are cases when this option alone is
+ 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
"--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.
+ name explicitly. Also, note that --openssldir refers
+ to target's file system, not one you are building on.
--debug
- Build OpenSSL with debugging symbols.
+ Build OpenSSL with debugging symbols and zero optimization
+ level.
--libdir=DIR
The name of the directory under the top of the installation
without a path). This flag must be provided if the
zlib-dynamic option is not also used. If zlib-dynamic is used
then this flag is optional and a default value ("ZLIB1") is
- used if not provided.
+ used 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.
+
+ --with-rand-seed=seed1[,seed2,...]
+ 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 L<getrandom(2)> or equivalent system
+ call.
+ devrandom: Use the the first device from the DEVRANDOM list
+ which can be opened to read random bytes. The
+ DEVRANDOM preprocessor constant expands to
+ "/dev/urandom","/dev/random","/dev/srandom" on
+ most unix-ish operating systems.
+ egd: Check for an entropy generating daemon.
+ rdcpu: Use the RDSEED or RDRAND command if provided by
+ the CPU.
+ librandom: Use librandom (not implemented yet).
+ 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.
+
+ For more information, see the section 'Note on random number
+ generation' at the end of this document.
+
no-afalgeng
Don't build the AFALG engine. This option will be forced if
on a platform that does not support AFALG.
no-shared option.
no-asm
- Do not use assembler code. On some platforms a small amount
- of assembler code may still be used.
+ Do not use assembler code. This should be viewed as
+ debugging/trouble-shooting option rather than production.
+ 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.
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.
no-capieng
Don't build the CAPI engine. This option will be forced if
enable-ec_nistp_64_gcc_128
Enable support for optimised implementations of some commonly
- used NIST elliptic curves. This is only supported on some
- platforms.
+ used NIST elliptic curves.
+ This 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 EGD (Entropy
require additional system-dependent options! See "Note on
multi-threading" below.
- enable-tls13downgrade
- TODO(TLS1.3): Make this enabled by default and remove the
- option when TLSv1.3 is out of draft
- TLSv1.3 offers a downgrade protection mechanism. This is
- implemented but disabled by default. It should not typically
- be enabled except for testing purposes. Otherwise this could
- cause problems if a pre-RFC version of OpenSSL talks to an
- RFC implementation (it will erroneously be detected as a
- downgrade).
-
no-ts
Don't build Time Stamping Authority support.
Build without support for the specified algorithm, where
<alg> is one of: aria, bf, blake2, camellia, cast, chacha,
cmac, des, dh, dsa, ecdh, ecdsa, idea, md4, mdc2, ocb,
- poly1305, rc2, rc4, rmd160, scrypt, seed, siphash, sm3, sm4
- or whirlpool. The "ripemd" algorithm is deprecated and if
- used is synonymous with rmd160.
+ poly1305, rc2, rc4, rmd160, scrypt, seed, siphash, sm2, sm3,
+ sm4 or whirlpool. The "ripemd" algorithm is deprecated and
+ if used is synonymous with rmd160.
-Dxxx, -Ixxx, -Wp, -lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static
These system specific options will be recognised and
CPPDEFINES List of CPP macro definitions, separated
by a platform specific character (':' or
space for Unix, ';' for Windows, ',' for
- VMS). This can be used in place of -D.
+ VMS). This can be used instead of using
+ -D (or what corresponds to that on your
+ compiler) in CPPFLAGS.
CPPINCLUDES List of CPP inclusion directories, separated
the same way as for CPPDEFINES. This can
- be used in place of -I.
+ be used instead of -I (or what corresponds
+ to that on your compiler) in CPPFLAGS.
HASHBANGPERL Perl invocation to be inserted after '#!'
- in public perl scripts.
+ in public perl scripts (only relevant on
+ Unix).
LD The program linker (not used on Unix, $(CC)
is used there).
LDFLAGS Flags for the shared library, DSO and
Windows, and as a comma separated list of
libraries on VMS.
RANLIB The library archive indexer.
- RC The Windows resources manipulator.
- RCFLAGS Flags for the Windows reources manipulator.
+ RC The Windows resource compiler.
+ RCFLAGS Flags for the Windows resource compiler.
RM The command to remove files and directories.
These cannot be mixed with compiling / linking flags given
$ nmake TESTS='test_rsa test_dsa' test # Windows
And of course, you can combine (Unix example shown):
-
+
$ make VERBOSE=1 TESTS='test_rsa test_dsa' test
You can find the list of available tests like this:
command symbols.
[.SYSTEST] Contains the installation verification procedure.
[.HTML] Contains the HTML rendition of the manual pages.
-
+
Additionally, install will add the following directories under
OPENSSLDIR (the directory given with --openssldir or its default)
BUILDFILE
Use a different build file name than the platform default
- ("Makefile" on Unixly platforms, "makefile" on native Windows,
+ ("Makefile" on Unix-like platforms, "makefile" on native Windows,
"descrip.mms" on OpenVMS). This requires that there is a
corresponding build file template. See Configurations/README
for further information.
part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of
the name.
- On most POSIXly platforms, shared libraries are named libcrypto.so.1.1
+ On most POSIX platforms, shared libraries are named libcrypto.so.1.1
and libssl.so.1.1.
on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll
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
+ internal CSPRNG. If not properly seeded, the internal CSPRNG 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 a random seed.
- Please check out the manual pages for RAND_add(), RAND_bytes(), RAND_egd(),
- and the FAQ for more information.
+ The seeding method can be configured using the --with-rand-seed option,
+ which can be used to specify a comma separated list of seed methods.
+ However in most cases OpenSSL will choose a suitable default method,
+ so it is not necessary to explicitly provide this option. Note also
+ that not all methods are available on all platforms.
+
+ I) On operating systems which provide a suitable randomness source (in
+ form of a system call or system device), OpenSSL will use the optimal
+ available method to seed the CSPRNG from the operating system's
+ randomness sources. This corresponds to the option --with-rand-seed=os.
+
+ II) On systems without such a suitable randomness source, automatic seeding
+ and reseeding is disabled (--with-rand-seed=none) and it may be necessary
+ to install additional support software to obtain a random seed and reseed
+ the CSPRNG manually. Please check out the manual pages for RAND_add(),
+ RAND_bytes(), RAND_egd(), and the FAQ for more information.