Blame INSTALL

Packit Service 084de1
 OPENSSL INSTALLATION
Packit Service 084de1
 --------------------
Packit Service 084de1
Packit Service 084de1
 This document describes installation on all supported operating
Packit Service 084de1
 systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
Packit Service 084de1
 and Windows).
Packit Service 084de1
Packit Service 084de1
 To install OpenSSL, you will need:
Packit Service 084de1
Packit Service 084de1
  * A make implementation
Packit Service 084de1
  * Perl 5 with core modules (please read NOTES.PERL)
Packit Service 084de1
  * The perl module Text::Template (please read NOTES.PERL)
Packit Service 084de1
  * an ANSI C compiler
Packit Service 084de1
  * a development environment in the form of development libraries and C
Packit Service 084de1
    header files
Packit Service 084de1
  * a supported operating system
Packit Service 084de1
Packit Service 084de1
 For additional platform specific requirements, solutions to specific
Packit Service 084de1
 issues and other details, please read one of these:
Packit Service 084de1
Packit Service 084de1
  * NOTES.UNIX (any supported Unix like system)
Packit Service 084de1
  * NOTES.VMS (OpenVMS)
Packit Service 084de1
  * NOTES.WIN (any supported Windows)
Packit Service 084de1
  * NOTES.DJGPP (DOS platform with DJGPP)
Packit Service 084de1
  * NOTES.ANDROID (obviously Android [NDK])
Packit Service 084de1
Packit Service 084de1
 Notational conventions in this document
Packit Service 084de1
 ---------------------------------------
Packit Service 084de1
Packit Service 084de1
 Throughout this document, we use the following conventions in command
Packit Service 084de1
 examples:
Packit Service 084de1
Packit Service 084de1
 $ command                      Any line starting with a dollar sign
Packit Service 084de1
                                ($) is a command line.
Packit Service 084de1
Packit Service 084de1
 { word1 | word2 | word3 }      This denotes a mandatory choice, to be
Packit Service 084de1
                                replaced with one of the given words.
Packit Service 084de1
                                A simple example would be this:
Packit Service 084de1
Packit Service 084de1
                                $ echo { FOO | BAR | COOKIE }
Packit Service 084de1
Packit Service 084de1
                                which is to be understood as one of
Packit Service 084de1
                                these:
Packit Service 084de1
Packit Service 084de1
                                $ echo FOO
Packit Service 084de1
                                - or -
Packit Service 084de1
                                $ echo BAR
Packit Service 084de1
                                - or -
Packit Service 084de1
                                $ echo COOKIE
Packit Service 084de1
Packit Service 084de1
 [ word1 | word2 | word3 ]      Similar to { word1 | word2 | word3 }
Packit Service 084de1
                                except it's optional to give any of
Packit Service 084de1
                                those.  In addition to the examples
Packit Service 084de1
                                above, this would also be valid:
Packit Service 084de1
Packit Service 084de1
                                $ echo
Packit Service 084de1
Packit Service 084de1
 {{ target }}                   This denotes a mandatory word or
Packit Service 084de1
                                sequence of words of some sort.  A
Packit Service 084de1
                                simple example would be this:
Packit Service 084de1
Packit Service 084de1
                                $ type {{ filename }}
Packit Service 084de1
Packit Service 084de1
                                which is to be understood to use the
Packit Service 084de1
                                command 'type' on some file name
Packit Service 084de1
                                determined by the user.
Packit Service 084de1
Packit Service 084de1
 [[ options ]]                  Similar to {{ target }}, but is
Packit Service 084de1
                                optional.
Packit Service 084de1
Packit Service 084de1
 Note that the notation assumes spaces around {, }, [, ], {{, }} and
Packit Service 084de1
 [[, ]].  This is to differentiate from OpenVMS directory
Packit Service 084de1
 specifications, which also use [ and ], but without spaces.
Packit Service 084de1
Packit Service 084de1
 Quick Start
Packit Service 084de1
 -----------
Packit Service 084de1
Packit Service 084de1
 If you want to just get on with it, do:
Packit Service 084de1
Packit Service 084de1
  on Unix (again, this includes Mac OS/X):
Packit Service 084de1
Packit Service 084de1
    $ ./config
Packit Service 084de1
    $ make
Packit Service 084de1
    $ make test
Packit Service 084de1
    $ make install
Packit Service 084de1
Packit Service 084de1
  on OpenVMS:
Packit Service 084de1
Packit Service 084de1
    $ @config
Packit Service 084de1
    $ mms
Packit Service 084de1
    $ mms test
Packit Service 084de1
    $ mms install
Packit Service 084de1
Packit Service 084de1
  on Windows (only pick one of the targets for configuration):
Packit Service 084de1
Packit Service 084de1
    $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
Packit Service 084de1
    $ nmake
Packit Service 084de1
    $ nmake test
Packit Service 084de1
    $ nmake install
Packit Service 084de1
Packit Service 084de1
 Note that in order to perform the install step above you need to have
Packit Service 084de1
 appropriate permissions to write to the installation directory.
Packit Service 084de1
Packit Service 084de1
 If any of these steps fails, see section Installation in Detail below.
Packit Service 084de1
Packit Service 084de1
 This will build and install OpenSSL in the default location, which is:
Packit Service 084de1
Packit Service 084de1
  Unix:    normal installation directories under /usr/local
Packit Service 084de1
  OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
Packit Service 084de1
           OpenSSL version number with underscores instead of periods.
Packit Service 084de1
  Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL
Packit Service 084de1
Packit Service 084de1
 The installation directory should be appropriately protected to ensure
Packit Service 084de1
 unprivileged users cannot make changes to OpenSSL binaries or files, or install
Packit Service 084de1
 engines. If you already have a pre-installed version of OpenSSL as part of
Packit Service 084de1
 your Operating System it is recommended that you do not overwrite the system
Packit Service 084de1
 version and instead install to somewhere else.
Packit Service 084de1
Packit Service 084de1
 If you want to install it anywhere else, run config like this:
Packit Service 084de1
Packit Service 084de1
  On Unix:
Packit Service 084de1
Packit Service 084de1
    $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
Packit Service 084de1
Packit Service 084de1
  On OpenVMS:
Packit Service 084de1
Packit Service 084de1
    $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
Packit Service 084de1
Packit Service 084de1
 (Note: if you do add options to the configuration command, please make sure
Packit Service 084de1
 you've read more than just this Quick Start, such as relevant NOTES.* files,
Packit Service 084de1
 the options outline below, as configuration options may change the outcome
Packit Service 084de1
 in otherwise unexpected ways)
Packit Service 084de1
Packit Service 084de1
Packit Service 084de1
 Configuration Options
Packit Service 084de1
 ---------------------
Packit Service 084de1
Packit Service 084de1
 There are several options to ./config (or ./Configure) to customize
Packit Service 084de1
 the build (note that for Windows, the defaults for --prefix and
Packit Service 084de1
 --openssldir depend in what configuration is used and what Windows
Packit Service 084de1
 implementation OpenSSL is built on.  More notes on this in NOTES.WIN):
Packit Service 084de1
Packit Service 084de1
  --api=x.y.z
Packit Service 084de1
                   Don't build with support for deprecated APIs below the
Packit Service 084de1
                   specified version number. For example "--api=1.1.0" will
Packit Service 084de1
                   remove support for all APIS that were deprecated in OpenSSL
Packit Service 084de1
                   version 1.1.0 or below. This is a rather specialized option
Packit Service 084de1
                   for developers. If you just intend to remove all deprecated
Packit Service 084de1
                   APIs entirely (up to the current version), it is easier
Packit Service 084de1
                   to add the 'no-deprecated' option instead (see below).
Packit Service 084de1
Packit Service 084de1
  --cross-compile-prefix=PREFIX
Packit Service 084de1
                   The PREFIX to include in front of commands for your
Packit Service 084de1
                   toolchain. It's likely to have to end with dash, e.g.
Packit Service 084de1
                   a-b-c- would invoke GNU compiler as a-b-c-gcc, etc.
Packit Service 084de1
                   Unfortunately cross-compiling is too case-specific to
Packit Service 084de1
                   put together one-size-fits-all instructions. You might
Packit Service 084de1
                   have to pass more flags or set up environment variables
Packit Service 084de1
                   to actually make it work. Android and iOS cases are
Packit Service 084de1
                   discussed in corresponding Configurations/15-*.conf
Packit Service 084de1
                   files. But there are cases when this option alone is
Packit Service 084de1
                   sufficient. For example to build the mingw64 target on
Packit Service 084de1
                   Linux "--cross-compile-prefix=x86_64-w64-mingw32-"
Packit Service 084de1
                   works. Naturally provided that mingw packages are
Packit Service 084de1
                   installed. Today Debian and Ubuntu users have option to
Packit Service 084de1
                   install a number of prepackaged cross-compilers along
Packit Service 084de1
                   with corresponding run-time and development packages for
Packit Service 084de1
                   "alien" hardware. To give another example
Packit Service 084de1
                   "--cross-compile-prefix=mipsel-linux-gnu-" suffices
Packit Service 084de1
                   in such case. Needless to mention that you have to
Packit Service 084de1
                   invoke ./Configure, not ./config, and pass your target
Packit Service 084de1
                   name explicitly. Also, note that --openssldir refers
Packit Service 084de1
                   to target's file system, not one you are building on.
Packit Service 084de1
Packit Service 084de1
  --debug
Packit Service 084de1
                   Build OpenSSL with debugging symbols and zero optimization
Packit Service 084de1
                   level.
Packit Service 084de1
Packit Service 084de1
  --libdir=DIR
Packit Service 084de1
                   The name of the directory under the top of the installation
Packit Service 084de1
                   directory tree (see the --prefix option) where libraries will
Packit Service 084de1
                   be installed. By default this is "lib". Note that on Windows
Packit Service 084de1
                   only ".lib" files will be stored in this location. dll files
Packit Service 084de1
                   will always be installed to the "bin" directory.
Packit Service 084de1
Packit Service 084de1
  --openssldir=DIR
Packit Service 084de1
                   Directory for OpenSSL configuration files, and also the
Packit Service 084de1
                   default certificate and key store.  Defaults are:
Packit Service 084de1
Packit Service 084de1
                   Unix:           /usr/local/ssl
Packit Service 084de1
                   Windows:        C:\Program Files\Common Files\SSL
Packit Service 084de1
                                or C:\Program Files (x86)\Common Files\SSL
Packit Service 084de1
                   OpenVMS:        SYS$COMMON:[OPENSSL-COMMON]
Packit Service 084de1
Packit Service 084de1
  --prefix=DIR
Packit Service 084de1
                   The top of the installation directory tree.  Defaults are:
Packit Service 084de1
Packit Service 084de1
                   Unix:           /usr/local
Packit Service 084de1
                   Windows:        C:\Program Files\OpenSSL
Packit Service 084de1
                                or C:\Program Files (x86)\OpenSSL
Packit Service 084de1
                   OpenVMS:        SYS$COMMON:[OPENSSL-'version']
Packit Service 084de1
Packit Service 084de1
  --release
Packit Service 084de1
                   Build OpenSSL without debugging symbols. This is the default.
Packit Service 084de1
Packit Service 084de1
  --strict-warnings
Packit Service 084de1
                   This is a developer flag that switches on various compiler
Packit Service 084de1
                   options recommended for OpenSSL development. It only works
Packit Service 084de1
                   when using gcc or clang as the compiler. If you are
Packit Service 084de1
                   developing a patch for OpenSSL then it is recommended that
Packit Service 084de1
                   you use this option where possible.
Packit Service 084de1
Packit Service 084de1
  --with-zlib-include=DIR
Packit Service 084de1
                   The directory for the location of the zlib include file. This
Packit Service 084de1
                   option is only necessary if enable-zlib (see below) is used
Packit Service 084de1
                   and the include file is not already on the system include
Packit Service 084de1
                   path.
Packit Service 084de1
Packit Service 084de1
  --with-zlib-lib=LIB
Packit Service 084de1
                   On Unix: this is the directory containing the zlib library.
Packit Service 084de1
                   If not provided the system library path will be used.
Packit Service 084de1
                   On Windows: this is the filename of the zlib library (with or
Packit Service 084de1
                   without a path). This flag must be provided if the
Packit Service 084de1
                   zlib-dynamic option is not also used. If zlib-dynamic is used
Packit Service 084de1
                   then this flag is optional and a default value ("ZLIB1") is
Packit Service 084de1
                   used if not provided.
Packit Service 084de1
                   On VMS: this is the filename of the zlib library (with or
Packit Service 084de1
                   without a path). This flag is optional and if not provided
Packit Service 084de1
                   then "GNV$LIBZSHR", "GNV$LIBZSHR32" or "GNV$LIBZSHR64" is
Packit Service 084de1
                   used by default depending on the pointer size chosen.
Packit Service 084de1
Packit Service 084de1
Packit Service 084de1
  --with-rand-seed=seed1[,seed2,...]
Packit Service 084de1
                   A comma separated list of seeding methods which will be tried
Packit Service 084de1
                   by OpenSSL in order to obtain random input (a.k.a "entropy")
Packit Service 084de1
                   for seeding its cryptographically secure random number
Packit Service 084de1
                   generator (CSPRNG). The current seeding methods are:
Packit Service 084de1
Packit Service 084de1
                   os:         Use a trusted operating system entropy source.
Packit Service 084de1
                               This is the default method if such an entropy
Packit Service 084de1
                               source exists.
Packit Service 084de1
                   getrandom:  Use the L<getrandom(2)> or equivalent system
Packit Service 084de1
                               call.
Packit Service 084de1
                   devrandom:  Use the first device from the DEVRANDOM list
Packit Service 084de1
                               which can be opened to read random bytes. The
Packit Service 084de1
                               DEVRANDOM preprocessor constant expands to
Packit Service 084de1
                               "/dev/urandom","/dev/random","/dev/srandom" on
Packit Service 084de1
                               most unix-ish operating systems.
Packit Service 084de1
                   egd:        Check for an entropy generating daemon.
Packit Service 084de1
                   rdcpu:      Use the RDSEED or RDRAND command if provided by
Packit Service 084de1
                               the CPU.
Packit Service 084de1
                   librandom:  Use librandom (not implemented yet).
Packit Service 084de1
                   none:       Disable automatic seeding. This is the default
Packit Service 084de1
                               on some operating systems where no suitable
Packit Service 084de1
                               entropy source exists, or no support for it is
Packit Service 084de1
                               implemented yet.
Packit Service 084de1
Packit Service 084de1
                   For more information, see the section 'Note on random number
Packit Service 084de1
                   generation' at the end of this document.
Packit Service 084de1
Packit Service 084de1
  no-afalgeng
Packit Service 084de1
                   Don't build the AFALG engine. This option will be forced if
Packit Service 084de1
                   on a platform that does not support AFALG.
Packit Service 084de1
Packit Service 084de1
  enable-asan
Packit Service 084de1
                   Build with the Address sanitiser. This is a developer option
Packit Service 084de1
                   only. It may not work on all platforms and should never be
Packit Service 084de1
                   used in production environments. It will only work when used
Packit Service 084de1
                   with gcc or clang and should be used in conjunction with the
Packit Service 084de1
                   no-shared option.
Packit Service 084de1
Packit Service 084de1
  no-asm
Packit Service 084de1
                   Do not use assembler code. This should be viewed as
Packit Service 084de1
                   debugging/trouble-shooting option rather than production.
Packit Service 084de1
                   On some platforms a small amount of assembler code may
Packit Service 084de1
                   still be used even with this option.
Packit Service 084de1
Packit Service 084de1
  no-async
Packit Service 084de1
                   Do not build support for async operations.
Packit Service 084de1
Packit Service 084de1
  no-autoalginit
Packit Service 084de1
                   Don't automatically load all supported ciphers and digests.
Packit Service 084de1
                   Typically OpenSSL will make available all of its supported
Packit Service 084de1
                   ciphers and digests. For a statically linked application this
Packit Service 084de1
                   may be undesirable if small executable size is an objective.
Packit Service 084de1
                   This only affects libcrypto. Ciphers and digests will have to
Packit Service 084de1
                   be loaded manually using EVP_add_cipher() and
Packit Service 084de1
                   EVP_add_digest() if this option is used. This option will
Packit Service 084de1
                   force a non-shared build.
Packit Service 084de1
Packit Service 084de1
  no-autoerrinit
Packit Service 084de1
                   Don't automatically load all libcrypto/libssl error strings.
Packit Service 084de1
                   Typically OpenSSL will automatically load human readable
Packit Service 084de1
                   error strings. For a statically linked application this may
Packit Service 084de1
                   be undesirable if small executable size is an objective.
Packit Service 084de1
Packit Service 084de1
  no-autoload-config
Packit Service 084de1
                   Don't automatically load the default openssl.cnf file.
Packit Service 084de1
                   Typically OpenSSL will automatically load a system config
Packit Service 084de1
                   file which configures default ssl options.
Packit Service 084de1
Packit Service 084de1
  enable-buildtest-c++
Packit Service 084de1
                   While testing, generate C++ buildtest files that
Packit Service 084de1
                   simply check that the public OpenSSL header files
Packit Service 084de1
                   are usable standalone with C++.
Packit Service 084de1
Packit Service 084de1
                   Enabling this option demands extra care.  For any
Packit Service 084de1
                   compiler flag given directly as configuration
Packit Service 084de1
                   option, you must ensure that it's valid for both
Packit Service 084de1
                   the C and the C++ compiler.  If not, the C++ build
Packit Service 084de1
                   test will most likely break.  As an alternative,
Packit Service 084de1
                   you can use the language specific variables, CFLAGS
Packit Service 084de1
                   and CXXFLAGS.
Packit Service 084de1
Packit Service 084de1
  no-capieng
Packit Service 084de1
                   Don't build the CAPI engine. This option will be forced if
Packit Service 084de1
                   on a platform that does not support CAPI.
Packit Service 084de1
Packit Service 084de1
  no-cms
Packit Service 084de1
                   Don't build support for CMS features
Packit Service 084de1
Packit Service 084de1
  no-comp
Packit Service 084de1
                   Don't build support for SSL/TLS compression. If this option
Packit Service 084de1
                   is left enabled (the default), then compression will only
Packit Service 084de1
                   work if the zlib or zlib-dynamic options are also chosen.
Packit Service 084de1
Packit Service 084de1
  enable-crypto-mdebug
Packit Service 084de1
                   Build support for debugging memory allocated via
Packit Service 084de1
                   OPENSSL_malloc() or OPENSSL_zalloc().
Packit Service 084de1
Packit Service 084de1
  enable-crypto-mdebug-backtrace
Packit Service 084de1
                   As for crypto-mdebug, but additionally provide backtrace
Packit Service 084de1
                   information for allocated memory.
Packit Service 084de1
                   TO BE USED WITH CARE: this uses GNU C functionality, and
Packit Service 084de1
                   is therefore not usable for non-GNU config targets.  If
Packit Service 084de1
                   your build complains about the use of '-rdynamic' or the
Packit Service 084de1
                   lack of header file execinfo.h, this option is not for you.
Packit Service 084de1
                   ALSO NOTE that even though execinfo.h is available on your
Packit Service 084de1
                   system (through Gnulib), the functions might just be stubs
Packit Service 084de1
                   that do nothing.
Packit Service 084de1
Packit Service 084de1
  no-ct
Packit Service 084de1
                   Don't build support for Certificate Transparency.
Packit Service 084de1
Packit Service 084de1
  no-deprecated
Packit Service 084de1
                   Don't build with support for any deprecated APIs. This is the
Packit Service 084de1
                   same as using "--api" and supplying the latest version
Packit Service 084de1
                   number.
Packit Service 084de1
Packit Service 084de1
  no-dgram
Packit Service 084de1
                   Don't build support for datagram based BIOs. Selecting this
Packit Service 084de1
                   option will also force the disabling of DTLS.
Packit Service 084de1
Packit Service 084de1
  no-dso
Packit Service 084de1
                   Don't build support for loading Dynamic Shared Objects.
Packit Service 084de1
Packit Service 084de1
  enable-devcryptoeng
Packit Service 084de1
                   Build the /dev/crypto engine.  It is automatically selected
Packit Service 084de1
                   on BSD implementations, in which case it can be disabled with
Packit Service 084de1
                   no-devcryptoeng.
Packit Service 084de1
Packit Service 084de1
  no-dynamic-engine
Packit Service 084de1
                   Don't build the dynamically loaded engines. This only has an
Packit Service 084de1
                   effect in a "shared" build
Packit Service 084de1
Packit Service 084de1
  no-ec
Packit Service 084de1
                   Don't build support for Elliptic Curves.
Packit Service 084de1
Packit Service 084de1
  no-ec2m
Packit Service 084de1
                   Don't build support for binary Elliptic Curves
Packit Service 084de1
Packit Service 084de1
  enable-ec_nistp_64_gcc_128
Packit Service 084de1
                   Enable support for optimised implementations of some commonly
Packit Service 084de1
                   used NIST elliptic curves.
Packit Service 084de1
                   This is only supported on platforms:
Packit Service 084de1
                   - with little-endian storage of non-byte types
Packit Service 084de1
                   - that tolerate misaligned memory references
Packit Service 084de1
                   - where the compiler:
Packit Service 084de1
                     - supports the non-standard type __uint128_t
Packit Service 084de1
                     - defines the built-in macro __SIZEOF_INT128__
Packit Service 084de1
Packit Service 084de1
  enable-egd
Packit Service 084de1
                   Build support for gathering entropy from EGD (Entropy
Packit Service 084de1
                   Gathering Daemon).
Packit Service 084de1
Packit Service 084de1
  no-engine
Packit Service 084de1
                   Don't build support for loading engines.
Packit Service 084de1
Packit Service 084de1
  no-err
Packit Service 084de1
                   Don't compile in any error strings.
Packit Service 084de1
Packit Service 084de1
  enable-external-tests
Packit Service 084de1
                   Enable building of integration with external test suites.
Packit Service 084de1
                   This is a developer option and may not work on all platforms.
Packit Service 084de1
                   The only supported external test suite at the current time is
Packit Service 084de1
                   the BoringSSL test suite. See the file test/README.external
Packit Service 084de1
                   for further details.
Packit Service 084de1
Packit Service 084de1
  no-filenames
Packit Service 084de1
                   Don't compile in filename and line number information (e.g.
Packit Service 084de1
                   for errors and memory allocation).
Packit Service 084de1
Packit Service 084de1
  enable-fuzz-libfuzzer, enable-fuzz-afl
Packit Service 084de1
                   Build with support for fuzzing using either libfuzzer or AFL.
Packit Service 084de1
                   These are developer options only. They may not work on all
Packit Service 084de1
                   platforms and should never be used in production environments.
Packit Service 084de1
                   See the file fuzz/README.md for further details.
Packit Service 084de1
Packit Service 084de1
  no-gost
Packit Service 084de1
                   Don't build support for GOST based ciphersuites. Note that
Packit Service 084de1
                   if this feature is enabled then GOST ciphersuites are only
Packit Service 084de1
                   available if the GOST algorithms are also available through
Packit Service 084de1
                   loading an externally supplied engine.
Packit Service 084de1
Packit Service 084de1
  no-hw-padlock
Packit Service 084de1
                   Don't build the padlock engine.
Packit Service 084de1
Packit Service 084de1
  no-makedepend
Packit Service 084de1
                   Don't generate dependencies.
Packit Service 084de1
Packit Service 084de1
  no-multiblock
Packit Service 084de1
                   Don't build support for writing multiple records in one
Packit Service 084de1
                   go in libssl (Note: this is a different capability to the
Packit Service 084de1
                   pipelining functionality).
Packit Service 084de1
Packit Service 084de1
  no-nextprotoneg
Packit Service 084de1
                   Don't build support for the NPN TLS extension.
Packit Service 084de1
Packit Service 084de1
  no-ocsp
Packit Service 084de1
                   Don't build support for OCSP.
Packit Service 084de1
Packit Service 084de1
  no-pic
Packit Service 084de1
                   Don't build with support for Position Independent Code.
Packit Service 084de1
Packit Service 084de1
  no-pinshared     By default OpenSSL will attempt to stay in memory until the
Packit Service 084de1
                   process exits. This is so that libcrypto and libssl can be
Packit Service 084de1
                   properly cleaned up automatically via an "atexit()" handler.
Packit Service 084de1
                   The handler is registered by libcrypto and cleans up both
Packit Service 084de1
                   libraries. On some platforms the atexit() handler will run on
Packit Service 084de1
                   unload of libcrypto (if it has been dynamically loaded)
Packit Service 084de1
                   rather than at process exit. This option can be used to stop
Packit Service 084de1
                   OpenSSL from attempting to stay in memory until the process
Packit Service 084de1
                   exits. This could lead to crashes if either libcrypto or
Packit Service 084de1
                   libssl have already been unloaded at the point
Packit Service 084de1
                   that the atexit handler is invoked, e.g. on a platform which
Packit Service 084de1
                   calls atexit() on unload of the library, and libssl is
Packit Service 084de1
                   unloaded before libcrypto then a crash is likely to happen.
Packit Service 084de1
                   Applications can suppress running of the atexit() handler at
Packit Service 084de1
                   run time by using the OPENSSL_INIT_NO_ATEXIT option to
Packit Service 084de1
                   OPENSSL_init_crypto(). See the man page for it for further
Packit Service 084de1
                   details.
Packit Service 084de1
Packit Service 084de1
  no-posix-io
Packit Service 084de1
                   Don't use POSIX IO capabilities.
Packit Service 084de1
Packit Service 084de1
  no-psk
Packit Service 084de1
                   Don't build support for Pre-Shared Key based ciphersuites.
Packit Service 084de1
Packit Service 084de1
  no-rdrand
Packit Service 084de1
                   Don't use hardware RDRAND capabilities.
Packit Service 084de1
Packit Service 084de1
  no-rfc3779
Packit Service 084de1
                   Don't build support for RFC3779 ("X.509 Extensions for IP
Packit Service 084de1
                   Addresses and AS Identifiers")
Packit Service 084de1
Packit Service 084de1
  sctp
Packit Service 084de1
                   Build support for SCTP
Packit Service 084de1
Packit Service 084de1
  no-shared
Packit Service 084de1
                   Do not create shared libraries, only static ones.  See "Note
Packit Service 084de1
                   on shared libraries" below.
Packit Service 084de1
Packit Service 084de1
  no-sock
Packit Service 084de1
                   Don't build support for socket BIOs
Packit Service 084de1
Packit Service 084de1
  no-srp
Packit Service 084de1
                   Don't build support for SRP or SRP based ciphersuites.
Packit Service 084de1
Packit Service 084de1
  no-srtp
Packit Service 084de1
                   Don't build SRTP support
Packit Service 084de1
Packit Service 084de1
  no-sse2
Packit Service 084de1
                   Exclude SSE2 code paths from 32-bit x86 assembly modules.
Packit Service 084de1
                   Normally SSE2 extension is detected at run-time, but the
Packit Service 084de1
                   decision whether or not the machine code will be executed
Packit Service 084de1
                   is taken solely on CPU capability vector. This means that
Packit Service 084de1
                   if you happen to run OS kernel which does not support SSE2
Packit Service 084de1
                   extension on Intel P4 processor, then your application
Packit Service 084de1
                   might be exposed to "illegal instruction" exception.
Packit Service 084de1
                   There might be a way to enable support in kernel, e.g.
Packit Service 084de1
                   FreeBSD kernel can  be compiled with CPU_ENABLE_SSE, and
Packit Service 084de1
                   there is a way to disengage SSE2 code paths upon application
Packit Service 084de1
                   start-up, but if you aim for wider "audience" running
Packit Service 084de1
                   such kernel, consider no-sse2. Both the 386 and
Packit Service 084de1
                   no-asm options imply no-sse2.
Packit Service 084de1
Packit Service 084de1
  enable-ssl-trace
Packit Service 084de1
                   Build with the SSL Trace capabilities (adds the "-trace"
Packit Service 084de1
                   option to s_client and s_server).
Packit Service 084de1
Packit Service 084de1
  no-static-engine
Packit Service 084de1
                   Don't build the statically linked engines. This only
Packit Service 084de1
                   has an impact when not built "shared".
Packit Service 084de1
Packit Service 084de1
  no-stdio
Packit Service 084de1
                   Don't use anything from the C header file "stdio.h" that
Packit Service 084de1
                   makes use of the "FILE" type. Only libcrypto and libssl can
Packit Service 084de1
                   be built in this way. Using this option will suppress
Packit Service 084de1
                   building the command line applications. Additionally since
Packit Service 084de1
                   the OpenSSL tests also use the command line applications the
Packit Service 084de1
                   tests will also be skipped.
Packit Service 084de1
Packit Service 084de1
  no-tests
Packit Service 084de1
                   Don't build test programs or run any test.
Packit Service 084de1
Packit Service 084de1
  no-threads
Packit Service 084de1
                   Don't try to build with support for multi-threaded
Packit Service 084de1
                   applications.
Packit Service 084de1
Packit Service 084de1
  threads
Packit Service 084de1
                   Build with support for multi-threaded applications. Most
Packit Service 084de1
                   platforms will enable this by default. However if on a
Packit Service 084de1
                   platform where this is not the case then this will usually
Packit Service 084de1
                   require additional system-dependent options! See "Note on
Packit Service 084de1
                   multi-threading" below.
Packit Service 084de1
Packit Service 084de1
  no-ts
Packit Service 084de1
                   Don't build Time Stamping Authority support.
Packit Service 084de1
Packit Service 084de1
  enable-ubsan
Packit Service 084de1
                   Build with the Undefined Behaviour sanitiser. This is a
Packit Service 084de1
                   developer option only. It may not work on all platforms and
Packit Service 084de1
                   should never be used in production environments. It will only
Packit Service 084de1
                   work when used with gcc or clang and should be used in
Packit Service 084de1
                   conjunction with the "-DPEDANTIC" option (or the
Packit Service 084de1
                   --strict-warnings option).
Packit Service 084de1
Packit Service 084de1
  no-ui-console
Packit Service 084de1
                   Don't build with the "UI" console method (i.e. the "UI"
Packit Service 084de1
                   method that enables text based console prompts).
Packit Service 084de1
Packit Service 084de1
  enable-unit-test
Packit Service 084de1
                   Enable additional unit test APIs. This should not typically
Packit Service 084de1
                   be used in production deployments.
Packit Service 084de1
Packit Service 084de1
  enable-weak-ssl-ciphers
Packit Service 084de1
                   Build support for SSL/TLS ciphers that are considered "weak"
Packit Service 084de1
                   (e.g. RC4 based ciphersuites).
Packit Service 084de1
Packit Service 084de1
  zlib
Packit Service 084de1
                   Build with support for zlib compression/decompression.
Packit Service 084de1
Packit Service 084de1
  zlib-dynamic
Packit Service 084de1
                   Like "zlib", but has OpenSSL load the zlib library
Packit Service 084de1
                   dynamically when needed.  This is only supported on systems
Packit Service 084de1
                   where loading of shared libraries is supported.
Packit Service 084de1
Packit Service 084de1
  386
Packit Service 084de1
                   In 32-bit x86 builds, when generating assembly modules,
Packit Service 084de1
                   use the 80386 instruction set only (the default x86 code
Packit Service 084de1
                   is more efficient, but requires at least a 486). Note:
Packit Service 084de1
                   This doesn't affect code generated by compiler, you're
Packit Service 084de1
                   likely to complement configuration command line with
Packit Service 084de1
                   suitable compiler-specific option.
Packit Service 084de1
Packit Service 084de1
  no-<prot>
Packit Service 084de1
                   Don't build support for negotiating the specified SSL/TLS
Packit Service 084de1
                   protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2,
Packit Service 084de1
                   tls1_3, dtls, dtls1 or dtls1_2). If "no-tls" is selected then
Packit Service 084de1
                   all of tls1, tls1_1, tls1_2 and tls1_3 are disabled.
Packit Service 084de1
                   Similarly "no-dtls" will disable dtls1 and dtls1_2. The
Packit Service 084de1
                   "no-ssl" option is synonymous with "no-ssl3". Note this only
Packit Service 084de1
                   affects version negotiation. OpenSSL will still provide the
Packit Service 084de1
                   methods for applications to explicitly select the individual
Packit Service 084de1
                   protocol versions.
Packit Service 084de1
Packit Service 084de1
  no-<prot>-method
Packit Service 084de1
                   As for no-<prot> but in addition do not build the methods for
Packit Service 084de1
                   applications to explicitly select individual protocol
Packit Service 084de1
                   versions. Note that there is no "no-tls1_3-method" option
Packit Service 084de1
                   because there is no application method for TLSv1.3. Using
Packit Service 084de1
                   individual protocol methods directly is deprecated.
Packit Service 084de1
                   Applications should use TLS_method() instead.
Packit Service 084de1
Packit Service 084de1
  enable-<alg>
Packit Service 084de1
                   Build with support for the specified algorithm, where <alg>
Packit Service 084de1
                   is one of: md2 or rc5.
Packit Service 084de1
Packit Service 084de1
  no-<alg>
Packit Service 084de1
                   Build without support for the specified algorithm, where
Packit Service 084de1
                   <alg> is one of: aria, bf, blake2, camellia, cast, chacha,
Packit Service 084de1
                   cmac, des, dh, dsa, ecdh, ecdsa, idea, md4, mdc2, ocb,
Packit Service 084de1
                   poly1305, rc2, rc4, rmd160, scrypt, seed, siphash, sm2, sm3,
Packit Service 084de1
                   sm4 or whirlpool.  The "ripemd" algorithm is deprecated and
Packit Service 084de1
                   if used is synonymous with rmd160.
Packit Service 084de1
Packit Service 084de1
  -Dxxx, -Ixxx, -Wp, -lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static
Packit Service 084de1
                   These system specific options will be recognised and
Packit Service 084de1
                   passed through to the compiler to allow you to define
Packit Service 084de1
                   preprocessor symbols, specify additional libraries, library
Packit Service 084de1
                   directories or other compiler options. It might be worth
Packit Service 084de1
                   noting that some compilers generate code specifically for
Packit Service 084de1
                   processor the compiler currently executes on. This is not
Packit Service 084de1
                   necessarily what you might have in mind, since it might be
Packit Service 084de1
                   unsuitable for execution on other, typically older,
Packit Service 084de1
                   processor. Consult your compiler documentation.
Packit Service 084de1
Packit Service 084de1
                   Take note of the VAR=value documentation below and how
Packit Service 084de1
                   these flags interact with those variables.
Packit Service 084de1
Packit Service 084de1
  -xxx, +xxx, /xxx
Packit Service 084de1
                   Additional options that are not otherwise recognised are
Packit Service 084de1
                   passed through as they are to the compiler as well.
Packit Service 084de1
                   Unix-style options beginning with a '-' or '+' and
Packit Service 084de1
                   Windows-style options beginning with a '/' are recognized.
Packit Service 084de1
                   Again, consult your compiler documentation.
Packit Service 084de1
Packit Service 084de1
                   If the option contains arguments separated by spaces,
Packit Service 084de1
                   then the URL-style notation %20 can be used for the space
Packit Service 084de1
                   character in order to avoid having to quote the option.
Packit Service 084de1
                   For example, -opt%20arg gets expanded to -opt arg.
Packit Service 084de1
                   In fact, any ASCII character can be encoded as %xx using its
Packit Service 084de1
                   hexadecimal encoding.
Packit Service 084de1
Packit Service 084de1
                   Take note of the VAR=value documentation below and how
Packit Service 084de1
                   these flags interact with those variables.
Packit Service 084de1
Packit Service 084de1
  VAR=value
Packit Service 084de1
                   Assignment of environment variable for Configure.  These
Packit Service 084de1
                   work just like normal environment variable assignments,
Packit Service 084de1
                   but are supported on all platforms and are confined to
Packit Service 084de1
                   the configuration scripts only.  These assignments override
Packit Service 084de1
                   the corresponding value in the inherited environment, if
Packit Service 084de1
                   there is one.
Packit Service 084de1
Packit Service 084de1
                   The following variables are used as "make variables" and
Packit Service 084de1
                   can be used as an alternative to giving preprocessor,
Packit Service 084de1
                   compiler and linker options directly as configuration.
Packit Service 084de1
                   The following variables are supported:
Packit Service 084de1
Packit Service 084de1
                   AR              The static library archiver.
Packit Service 084de1
                   ARFLAGS         Flags for the static library archiver.
Packit Service 084de1
                   AS              The assembler compiler.
Packit Service 084de1
                   ASFLAGS         Flags for the assembler compiler.
Packit Service 084de1
                   CC              The C compiler.
Packit Service 084de1
                   CFLAGS          Flags for the C compiler.
Packit Service 084de1
                   CXX             The C++ compiler.
Packit Service 084de1
                   CXXFLAGS        Flags for the C++ compiler.
Packit Service 084de1
                   CPP             The C/C++ preprocessor.
Packit Service 084de1
                   CPPFLAGS        Flags for the C/C++ preprocessor.
Packit Service 084de1
                   CPPDEFINES      List of CPP macro definitions, separated
Packit Service 084de1
                                   by a platform specific character (':' or
Packit Service 084de1
                                   space for Unix, ';' for Windows, ',' for
Packit Service 084de1
                                   VMS).  This can be used instead of using
Packit Service 084de1
                                   -D (or what corresponds to that on your
Packit Service 084de1
                                   compiler) in CPPFLAGS.
Packit Service 084de1
                   CPPINCLUDES     List of CPP inclusion directories, separated
Packit Service 084de1
                                   the same way as for CPPDEFINES.  This can
Packit Service 084de1
                                   be used instead of -I (or what corresponds
Packit Service 084de1
                                   to that on your compiler) in CPPFLAGS.
Packit Service 084de1
                   HASHBANGPERL    Perl invocation to be inserted after '#!'
Packit Service 084de1
                                   in public perl scripts (only relevant on
Packit Service 084de1
                                   Unix).
Packit Service 084de1
                   LD              The program linker (not used on Unix, $(CC)
Packit Service 084de1
                                   is used there).
Packit Service 084de1
                   LDFLAGS         Flags for the shared library, DSO and
Packit Service 084de1
                                   program linker.
Packit Service 084de1
                   LDLIBS          Extra libraries to use when linking.
Packit Service 084de1
                                   Takes the form of a space separated list
Packit Service 084de1
                                   of library specifications on Unix and
Packit Service 084de1
                                   Windows, and as a comma separated list of
Packit Service 084de1
                                   libraries on VMS.
Packit Service 084de1
                   RANLIB          The library archive indexer.
Packit Service 084de1
                   RC              The Windows resource compiler.
Packit Service 084de1
                   RCFLAGS         Flags for the Windows resource compiler.
Packit Service 084de1
                   RM              The command to remove files and directories.
Packit Service 084de1
Packit Service 084de1
                   These cannot be mixed with compiling / linking flags given
Packit Service 084de1
                   on the command line.  In other words, something like this
Packit Service 084de1
                   isn't permitted.
Packit Service 084de1
Packit Service 084de1
                       ./config -DFOO CPPFLAGS=-DBAR -DCOOKIE
Packit Service 084de1
Packit Service 084de1
                   Backward compatibility note:
Packit Service 084de1
Packit Service 084de1
                   To be compatible with older configuration scripts, the
Packit Service 084de1
                   environment variables are ignored if compiling / linking
Packit Service 084de1
                   flags are given on the command line, except for these:
Packit Service 084de1
Packit Service 084de1
                   AR, CC, CXX, CROSS_COMPILE, HASHBANGPERL, PERL, RANLIB, RC
Packit Service 084de1
                   and WINDRES
Packit Service 084de1
Packit Service 084de1
                   For example, the following command will not see -DBAR:
Packit Service 084de1
Packit Service 084de1
                        CPPFLAGS=-DBAR ./config -DCOOKIE
Packit Service 084de1
Packit Service 084de1
                   However, the following will see both set variables:
Packit Service 084de1
Packit Service 084de1
                        CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- \
Packit Service 084de1
                        ./config -DCOOKIE
Packit Service 084de1
Packit Service 084de1
                   If CC is set, it is advisable to also set CXX to ensure
Packit Service 084de1
                   both C and C++ compilers are in the same "family".  This
Packit Service 084de1
                   becomes relevant with 'enable-external-tests' and
Packit Service 084de1
                   'enable-buildtest-c++'.
Packit Service 084de1
Packit Service 084de1
  reconf
Packit Service 084de1
  reconfigure
Packit Service 084de1
                   Reconfigure from earlier data.  This fetches the previous
Packit Service 084de1
                   command line options and environment from data saved in
Packit Service 084de1
                   "configdata.pm", and runs the configuration process again,
Packit Service 084de1
                   using these options and environment.
Packit Service 084de1
                   Note: NO other option is permitted together with "reconf".
Packit Service 084de1
                   This means that you also MUST use "./Configure" (or
Packit Service 084de1
                   what corresponds to that on non-Unix platforms) directly
Packit Service 084de1
                   to invoke this option.
Packit Service 084de1
                   Note: The original configuration saves away values for ALL
Packit Service 084de1
                   environment variables that were used, and if they weren't
Packit Service 084de1
                   defined, they are still saved away with information that
Packit Service 084de1
                   they weren't originally defined.  This information takes
Packit Service 084de1
                   precedence over environment variables that are defined
Packit Service 084de1
                   when reconfiguring.
Packit Service 084de1
Packit Service 084de1
 Displaying configuration data
Packit Service 084de1
 -----------------------------
Packit Service 084de1
Packit Service 084de1
 The configuration script itself will say very little, and finishes by
Packit Service 084de1
 creating "configdata.pm".  This perl module can be loaded by other scripts
Packit Service 084de1
 to find all the configuration data, and it can also be used as a script to
Packit Service 084de1
 display all sorts of configuration data in a human readable form.
Packit Service 084de1
Packit Service 084de1
 For more information, please do:
Packit Service 084de1
Packit Service 084de1
       $ ./configdata.pm --help                         # Unix
Packit Service 084de1
Packit Service 084de1
       or
Packit Service 084de1
Packit Service 084de1
       $ perl configdata.pm --help                      # Windows and VMS
Packit Service 084de1
Packit Service 084de1
 Installation in Detail
Packit Service 084de1
 ----------------------
Packit Service 084de1
Packit Service 084de1
 1a. Configure OpenSSL for your operation system automatically:
Packit Service 084de1
Packit Service 084de1
     NOTE: This is not available on Windows.
Packit Service 084de1
Packit Service 084de1
       $ ./config [[ options ]]                         # Unix
Packit Service 084de1
Packit Service 084de1
       or
Packit Service 084de1
Packit Service 084de1
       $ @config [[ options ]]                          ! OpenVMS
Packit Service 084de1
Packit Service 084de1
     For the remainder of this text, the Unix form will be used in all
Packit Service 084de1
     examples, please use the appropriate form for your platform.
Packit Service 084de1
Packit Service 084de1
     This guesses at your operating system (and compiler, if necessary) and
Packit Service 084de1
     configures OpenSSL based on this guess. Run ./config -t to see
Packit Service 084de1
     if it guessed correctly. If you want to use a different compiler, you
Packit Service 084de1
     are cross-compiling for another platform, or the ./config guess was
Packit Service 084de1
     wrong for other reasons, go to step 1b. Otherwise go to step 2.
Packit Service 084de1
Packit Service 084de1
     On some systems, you can include debugging information as follows:
Packit Service 084de1
Packit Service 084de1
       $ ./config -d [[ options ]]
Packit Service 084de1
Packit Service 084de1
 1b. Configure OpenSSL for your operating system manually
Packit Service 084de1
Packit Service 084de1
     OpenSSL knows about a range of different operating system, hardware and
Packit Service 084de1
     compiler combinations. To see the ones it knows about, run
Packit Service 084de1
Packit Service 084de1
       $ ./Configure                                    # Unix
Packit Service 084de1
Packit Service 084de1
       or
Packit Service 084de1
Packit Service 084de1
       $ perl Configure                                 # All other platforms
Packit Service 084de1
Packit Service 084de1
     For the remainder of this text, the Unix form will be used in all
Packit Service 084de1
     examples, please use the appropriate form for your platform.
Packit Service 084de1
Packit Service 084de1
     Pick a suitable name from the list that matches your system. For most
Packit Service 084de1
     operating systems there is a choice between using "cc" or "gcc".  When
Packit Service 084de1
     you have identified your system (and if necessary compiler) use this name
Packit Service 084de1
     as the argument to Configure. For example, a "linux-elf" user would
Packit Service 084de1
     run:
Packit Service 084de1
Packit Service 084de1
       $ ./Configure linux-elf [[ options ]]
Packit Service 084de1
Packit Service 084de1
     If your system isn't listed, you will have to create a configuration
Packit Service 084de1
     file named Configurations/{{ something }}.conf and add the correct
Packit Service 084de1
     configuration for your system. See the available configs as examples
Packit Service 084de1
     and read Configurations/README and Configurations/README.design for
Packit Service 084de1
     more information.
Packit Service 084de1
Packit Service 084de1
     The generic configurations "cc" or "gcc" should usually work on 32 bit
Packit Service 084de1
     Unix-like systems.
Packit Service 084de1
Packit Service 084de1
     Configure creates a build file ("Makefile" on Unix, "makefile" on Windows
Packit Service 084de1
     and "descrip.mms" on OpenVMS) from a suitable template in Configurations,
Packit Service 084de1
     and defines various macros in include/openssl/opensslconf.h (generated from
Packit Service 084de1
     include/openssl/opensslconf.h.in).
Packit Service 084de1
Packit Service 084de1
 1c. Configure OpenSSL for building outside of the source tree.
Packit Service 084de1
Packit Service 084de1
     OpenSSL can be configured to build in a build directory separate from
Packit Service 084de1
     the directory with the source code.  It's done by placing yourself in
Packit Service 084de1
     some other directory and invoking the configuration commands from
Packit Service 084de1
     there.
Packit Service 084de1
Packit Service 084de1
     Unix example:
Packit Service 084de1
Packit Service 084de1
       $ mkdir /var/tmp/openssl-build
Packit Service 084de1
       $ cd /var/tmp/openssl-build
Packit Service 084de1
       $ /PATH/TO/OPENSSL/SOURCE/config [[ options ]]
Packit Service 084de1
Packit Service 084de1
       or
Packit Service 084de1
Packit Service 084de1
       $ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]]
Packit Service 084de1
Packit Service 084de1
     OpenVMS example:
Packit Service 084de1
Packit Service 084de1
       $ set default sys$login:
Packit Service 084de1
       $ create/dir [.tmp.openssl-build]
Packit Service 084de1
       $ set default [.tmp.openssl-build]
Packit Service 084de1
       $ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]]
Packit Service 084de1
Packit Service 084de1
       or
Packit Service 084de1
Packit Service 084de1
       $ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]]
Packit Service 084de1
Packit Service 084de1
     Windows example:
Packit Service 084de1
Packit Service 084de1
       $ C:
Packit Service 084de1
       $ mkdir \temp-openssl
Packit Service 084de1
       $ cd \temp-openssl
Packit Service 084de1
       $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]]
Packit Service 084de1
Packit Service 084de1
     Paths can be relative just as well as absolute.  Configure will
Packit Service 084de1
     do its best to translate them to relative paths whenever possible.
Packit Service 084de1
Packit Service 084de1
  2. Build OpenSSL by running:
Packit Service 084de1
Packit Service 084de1
       $ make                                           # Unix
Packit Service 084de1
       $ mms                                            ! (or mmk) OpenVMS
Packit Service 084de1
       $ nmake                                          # Windows
Packit Service 084de1
Packit Service 084de1
     This will build the OpenSSL libraries (libcrypto.a and libssl.a on
Packit Service 084de1
     Unix, corresponding on other platforms) and the OpenSSL binary
Packit Service 084de1
     ("openssl"). The libraries will be built in the top-level directory,
Packit Service 084de1
     and the binary will be in the "apps" subdirectory.
Packit Service 084de1
Packit Service 084de1
     Troubleshooting:
Packit Service 084de1
Packit Service 084de1
     If the build fails, look at the output.  There may be reasons
Packit Service 084de1
     for the failure that aren't problems in OpenSSL itself (like
Packit Service 084de1
     missing standard headers).
Packit Service 084de1
Packit Service 084de1
     If the build succeeded previously, but fails after a source or
Packit Service 084de1
     configuration change, it might be helpful to clean the build tree
Packit Service 084de1
     before attempting another build. Use this command:
Packit Service 084de1
Packit Service 084de1
       $ make clean                                     # Unix
Packit Service 084de1
       $ mms clean                                      ! (or mmk) OpenVMS
Packit Service 084de1
       $ nmake clean                                    # Windows
Packit Service 084de1
Packit Service 084de1
     Assembler error messages can sometimes be sidestepped by using the
Packit Service 084de1
     "no-asm" configuration option.
Packit Service 084de1
Packit Service 084de1
     Compiling parts of OpenSSL with gcc and others with the system
Packit Service 084de1
     compiler will result in unresolved symbols on some systems.
Packit Service 084de1
Packit Service 084de1
     If you are still having problems you can get help by sending an email
Packit Service 084de1
     to the openssl-users email list (see
Packit Service 084de1
     https://www.openssl.org/community/mailinglists.html for details). If
Packit Service 084de1
     it is a bug with OpenSSL itself, please open an issue on GitHub, at
Packit Service 084de1
     https://github.com/openssl/openssl/issues. Please review the existing
Packit Service 084de1
     ones first; maybe the bug was already reported or has already been
Packit Service 084de1
     fixed.
Packit Service 084de1
Packit Service 084de1
  3. After a successful build, the libraries should be tested. Run:
Packit Service 084de1
Packit Service 084de1
       $ make test                                      # Unix
Packit Service 084de1
       $ mms test                                       ! OpenVMS
Packit Service 084de1
       $ nmake test                                     # Windows
Packit Service 084de1
Packit Service 084de1
     NOTE: you MUST run the tests from an unprivileged account (or
Packit Service 084de1
     disable your privileges temporarily if your platform allows it).
Packit Service 084de1
Packit Service 084de1
     If some tests fail, look at the output.  There may be reasons for
Packit Service 084de1
     the failure that isn't a problem in OpenSSL itself (like a
Packit Service 084de1
     malfunction with Perl).  You may want increased verbosity, that
Packit Service 084de1
     can be accomplished like this:
Packit Service 084de1
Packit Service 084de1
       $ make VERBOSE=1 test                            # Unix
Packit Service 084de1
Packit Service 084de1
       $ mms /macro=(VERBOSE=1) test                    ! OpenVMS
Packit Service 084de1
Packit Service 084de1
       $ nmake VERBOSE=1 test                           # Windows
Packit Service 084de1
Packit Service 084de1
     If you want to run just one or a few specific tests, you can use
Packit Service 084de1
     the make variable TESTS to specify them, like this:
Packit Service 084de1
Packit Service 084de1
       $ make TESTS='test_rsa test_dsa' test            # Unix
Packit Service 084de1
       $ mms/macro="TESTS=test_rsa test_dsa" test       ! OpenVMS
Packit Service 084de1
       $ nmake TESTS='test_rsa test_dsa' test           # Windows
Packit Service 084de1
Packit Service 084de1
     And of course, you can combine (Unix example shown):
Packit Service 084de1
Packit Service 084de1
       $ make VERBOSE=1 TESTS='test_rsa test_dsa' test
Packit Service 084de1
Packit Service 084de1
     You can find the list of available tests like this:
Packit Service 084de1
Packit Service 084de1
       $ make list-tests                                # Unix
Packit Service 084de1
       $ mms list-tests                                 ! OpenVMS
Packit Service 084de1
       $ nmake list-tests                               # Windows
Packit Service 084de1
Packit Service 084de1
     Have a look at the manual for the perl module Test::Harness to
Packit Service 084de1
     see what other HARNESS_* variables there are.
Packit Service 084de1
Packit Service 084de1
     If you find a problem with OpenSSL itself, try removing any
Packit Service 084de1
     compiler optimization flags from the CFLAGS line in Makefile and
Packit Service 084de1
     run "make clean; make" or corresponding.
Packit Service 084de1
Packit Service 084de1
     To report a bug please open an issue on GitHub, at
Packit Service 084de1
     https://github.com/openssl/openssl/issues.
Packit Service 084de1
Packit Service 084de1
     For more details on how the make variables TESTS can be used,
Packit Service 084de1
     see section TESTS in Detail below.
Packit Service 084de1
Packit Service 084de1
  4. If everything tests ok, install OpenSSL with
Packit Service 084de1
Packit Service 084de1
       $ make install                                   # Unix
Packit Service 084de1
       $ mms install                                    ! OpenVMS
Packit Service 084de1
       $ nmake install                                  # Windows
Packit Service 084de1
Packit Service 084de1
     Note that in order to perform the install step above you need to have
Packit Service 084de1
     appropriate permissions to write to the installation directory.
Packit Service 084de1
Packit Service 084de1
     The above commands will install all the software components in this
Packit Service 084de1
     directory tree under PREFIX (the directory given with --prefix or its
Packit Service 084de1
     default):
Packit Service 084de1
Packit Service 084de1
       Unix:
Packit Service 084de1
Packit Service 084de1
         bin/           Contains the openssl binary and a few other
Packit Service 084de1
                        utility scripts.
Packit Service 084de1
         include/openssl
Packit Service 084de1
                        Contains the header files needed if you want
Packit Service 084de1
                        to build your own programs that use libcrypto
Packit Service 084de1
                        or libssl.
Packit Service 084de1
         lib            Contains the OpenSSL library files.
Packit Service 084de1
         lib/engines    Contains the OpenSSL dynamically loadable engines.
Packit Service 084de1
Packit Service 084de1
         share/man/man1 Contains the OpenSSL command line man-pages.
Packit Service 084de1
         share/man/man3 Contains the OpenSSL library calls man-pages.
Packit Service 084de1
         share/man/man5 Contains the OpenSSL configuration format man-pages.
Packit Service 084de1
         share/man/man7 Contains the OpenSSL other misc man-pages.
Packit Service 084de1
Packit Service 084de1
         share/doc/openssl/html/man1
Packit Service 084de1
         share/doc/openssl/html/man3
Packit Service 084de1
         share/doc/openssl/html/man5
Packit Service 084de1
         share/doc/openssl/html/man7
Packit Service 084de1
                        Contains the HTML rendition of the man-pages.
Packit Service 084de1
Packit Service 084de1
       OpenVMS ('arch' is replaced with the architecture name, "Alpha"
Packit Service 084de1
       or "ia64", 'sover' is replaced with the shared library version
Packit Service 084de1
       (0101 for 1.1), and 'pz' is replaced with the pointer size
Packit Service 084de1
       OpenSSL was built with):
Packit Service 084de1
Packit Service 084de1
         [.EXE.'arch']  Contains the openssl binary.
Packit Service 084de1
         [.EXE]         Contains a few utility scripts.
Packit Service 084de1
         [.include.openssl]
Packit Service 084de1
                        Contains the header files needed if you want
Packit Service 084de1
                        to build your own programs that use libcrypto
Packit Service 084de1
                        or libssl.
Packit Service 084de1
         [.LIB.'arch']  Contains the OpenSSL library files.
Packit Service 084de1
         [.ENGINES'sover''pz'.'arch']
Packit Service 084de1
                        Contains the OpenSSL dynamically loadable engines.
Packit Service 084de1
         [.SYS$STARTUP] Contains startup, login and shutdown scripts.
Packit Service 084de1
                        These define appropriate logical names and
Packit Service 084de1
                        command symbols.
Packit Service 084de1
         [.SYSTEST]     Contains the installation verification procedure.
Packit Service 084de1
         [.HTML]        Contains the HTML rendition of the manual pages.
Packit Service 084de1
Packit Service 084de1
Packit Service 084de1
     Additionally, install will add the following directories under
Packit Service 084de1
     OPENSSLDIR (the directory given with --openssldir or its default)
Packit Service 084de1
     for you convenience:
Packit Service 084de1
Packit Service 084de1
         certs          Initially empty, this is the default location
Packit Service 084de1
                        for certificate files.
Packit Service 084de1
         private        Initially empty, this is the default location
Packit Service 084de1
                        for private key files.
Packit Service 084de1
         misc           Various scripts.
Packit Service 084de1
Packit Service 084de1
     The installation directory should be appropriately protected to ensure
Packit Service 084de1
     unprivileged users cannot make changes to OpenSSL binaries or files, or
Packit Service 084de1
     install engines. If you already have a pre-installed version of OpenSSL as
Packit Service 084de1
     part of your Operating System it is recommended that you do not overwrite
Packit Service 084de1
     the system version and instead install to somewhere else.
Packit Service 084de1
Packit Service 084de1
     Package builders who want to configure the library for standard
Packit Service 084de1
     locations, but have the package installed somewhere else so that
Packit Service 084de1
     it can easily be packaged, can use
Packit Service 084de1
Packit Service 084de1
       $ make DESTDIR=/tmp/package-root install         # Unix
Packit Service 084de1
       $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
Packit Service 084de1
Packit Service 084de1
     The specified destination directory will be prepended to all
Packit Service 084de1
     installation target paths.
Packit Service 084de1
Packit Service 084de1
  Compatibility issues with previous OpenSSL versions:
Packit Service 084de1
Packit Service 084de1
  *  COMPILING existing applications
Packit Service 084de1
Packit Service 084de1
     Starting with version 1.1.0, OpenSSL hides a number of structures
Packit Service 084de1
     that were previously open.  This includes all internal libssl
Packit Service 084de1
     structures and a number of EVP types.  Accessor functions have
Packit Service 084de1
     been added to allow controlled access to the structures' data.
Packit Service 084de1
Packit Service 084de1
     This means that some software needs to be rewritten to adapt to
Packit Service 084de1
     the new ways of doing things.  This often amounts to allocating
Packit Service 084de1
     an instance of a structure explicitly where you could previously
Packit Service 084de1
     allocate them on the stack as automatic variables, and using the
Packit Service 084de1
     provided accessor functions where you would previously access a
Packit Service 084de1
     structure's field directly.
Packit Service 084de1
Packit Service 084de1
     Some APIs have changed as well.  However, older APIs have been
Packit Service 084de1
     preserved when possible.
Packit Service 084de1
Packit Service 084de1
 Environment Variables
Packit Service 084de1
 ---------------------
Packit Service 084de1
Packit Service 084de1
 A number of environment variables can be used to provide additional control
Packit Service 084de1
 over the build process. Typically these should be defined prior to running
Packit Service 084de1
 config or Configure. Not all environment variables are relevant to all
Packit Service 084de1
 platforms.
Packit Service 084de1
Packit Service 084de1
 AR
Packit Service 084de1
                The name of the ar executable to use.
Packit Service 084de1
Packit Service 084de1
 BUILDFILE
Packit Service 084de1
                Use a different build file name than the platform default
Packit Service 084de1
                ("Makefile" on Unix-like platforms, "makefile" on native Windows,
Packit Service 084de1
                "descrip.mms" on OpenVMS).  This requires that there is a
Packit Service 084de1
                corresponding build file template.  See Configurations/README
Packit Service 084de1
                for further information.
Packit Service 084de1
Packit Service 084de1
 CC
Packit Service 084de1
                The compiler to use. Configure will attempt to pick a default
Packit Service 084de1
                compiler for your platform but this choice can be overridden
Packit Service 084de1
                using this variable. Set it to the compiler executable you wish
Packit Service 084de1
                to use, e.g. "gcc" or "clang".
Packit Service 084de1
Packit Service 084de1
 CROSS_COMPILE
Packit Service 084de1
                This environment variable has the same meaning as for the
Packit Service 084de1
                "--cross-compile-prefix" Configure flag described above. If both
Packit Service 084de1
                are set then the Configure flag takes precedence.
Packit Service 084de1
Packit Service 084de1
 NM
Packit Service 084de1
                The name of the nm executable to use.
Packit Service 084de1
Packit Service 084de1
 OPENSSL_LOCAL_CONFIG_DIR
Packit Service 084de1
                OpenSSL comes with a database of information about how it
Packit Service 084de1
                should be built on different platforms as well as build file
Packit Service 084de1
                templates for those platforms. The database is comprised of
Packit Service 084de1
                ".conf" files in the Configurations directory.  The build
Packit Service 084de1
                file templates reside there as well as ".tmpl" files. See the
Packit Service 084de1
                file Configurations/README for further information about the
Packit Service 084de1
                format of ".conf" files as well as information on the ".tmpl"
Packit Service 084de1
                files.
Packit Service 084de1
                In addition to the standard ".conf" and ".tmpl" files, it is
Packit Service 084de1
                possible to create your own ".conf" and ".tmpl" files and store
Packit Service 084de1
                them locally, outside the OpenSSL source tree. This environment
Packit Service 084de1
                variable can be set to the directory where these files are held
Packit Service 084de1
                and will be considered by Configure before it looks in the
Packit Service 084de1
                standard directories.
Packit Service 084de1
Packit Service 084de1
 PERL
Packit Service 084de1
                The name of the Perl executable to use when building OpenSSL.
Packit Service 084de1
                This variable is used in config script only. Configure on the
Packit Service 084de1
                other hand imposes the interpreter by which it itself was
Packit Service 084de1
                executed on the whole build procedure.
Packit Service 084de1
Packit Service 084de1
 HASHBANGPERL
Packit Service 084de1
                The command string for the Perl executable to insert in the
Packit Service 084de1
                #! line of perl scripts that will be publicly installed.
Packit Service 084de1
                Default: /usr/bin/env perl
Packit Service 084de1
                Note: the value of this variable is added to the same scripts
Packit Service 084de1
                on all platforms, but it's only relevant on Unix-like platforms.
Packit Service 084de1
Packit Service 084de1
 RC
Packit Service 084de1
                The name of the rc executable to use. The default will be as
Packit Service 084de1
                defined for the target platform in the ".conf" file. If not
Packit Service 084de1
                defined then "windres" will be used. The WINDRES environment
Packit Service 084de1
                variable is synonymous to this. If both are defined then RC
Packit Service 084de1
                takes precedence.
Packit Service 084de1
Packit Service 084de1
 RANLIB
Packit Service 084de1
                The name of the ranlib executable to use.
Packit Service 084de1
Packit Service 084de1
 WINDRES
Packit Service 084de1
                See RC.
Packit Service 084de1
Packit Service 084de1
 Makefile targets
Packit Service 084de1
 ----------------
Packit Service 084de1
Packit Service 084de1
 The Configure script generates a Makefile in a format relevant to the specific
Packit Service 084de1
 platform. The Makefiles provide a number of targets that can be used. Not all
Packit Service 084de1
 targets may be available on all platforms. Only the most common targets are
Packit Service 084de1
 described here. Examine the Makefiles themselves for the full list.
Packit Service 084de1
Packit Service 084de1
 all
Packit Service 084de1
                The default target to build all the software components.
Packit Service 084de1
Packit Service 084de1
 clean
Packit Service 084de1
                Remove all build artefacts and return the directory to a "clean"
Packit Service 084de1
                state.
Packit Service 084de1
Packit Service 084de1
 depend
Packit Service 084de1
                Rebuild the dependencies in the Makefiles. This is a legacy
Packit Service 084de1
                option that no longer needs to be used since OpenSSL 1.1.0.
Packit Service 084de1
Packit Service 084de1
 install
Packit Service 084de1
                Install all OpenSSL components.
Packit Service 084de1
Packit Service 084de1
 install_sw
Packit Service 084de1
                Only install the OpenSSL software components.
Packit Service 084de1
Packit Service 084de1
 install_docs
Packit Service 084de1
                Only install the OpenSSL documentation components.
Packit Service 084de1
Packit Service 084de1
 install_man_docs
Packit Service 084de1
                Only install the OpenSSL man pages (Unix only).
Packit Service 084de1
Packit Service 084de1
 install_html_docs
Packit Service 084de1
                Only install the OpenSSL html documentation.
Packit Service 084de1
Packit Service 084de1
 list-tests
Packit Service 084de1
                Prints a list of all the self test names.
Packit Service 084de1
Packit Service 084de1
 test
Packit Service 084de1
                Build and run the OpenSSL self tests.
Packit Service 084de1
Packit Service 084de1
 uninstall
Packit Service 084de1
                Uninstall all OpenSSL components.
Packit Service 084de1
Packit Service 084de1
 reconfigure
Packit Service 084de1
 reconf
Packit Service 084de1
                Re-run the configuration process, as exactly as the last time
Packit Service 084de1
                as possible.
Packit Service 084de1
Packit Service 084de1
 update
Packit Service 084de1
                This is a developer option. If you are developing a patch for
Packit Service 084de1
                OpenSSL you may need to use this if you want to update
Packit Service 084de1
                automatically generated files; add new error codes or add new
Packit Service 084de1
                (or change the visibility of) public API functions. (Unix only).
Packit Service 084de1
Packit Service 084de1
 TESTS in Detail
Packit Service 084de1
 ---------------
Packit Service 084de1
Packit Service 084de1
 The make variable TESTS supports a versatile set of space separated tokens
Packit Service 084de1
 with which you can specify a set of tests to be performed.  With a "current
Packit Service 084de1
 set of tests" in mind, initially being empty, here are the possible tokens:
Packit Service 084de1
Packit Service 084de1
 alltests       The current set of tests becomes the whole set of available
Packit Service 084de1
                tests (as listed when you do 'make list-tests' or similar).
Packit Service 084de1
 xxx            Adds the test 'xxx' to the current set of tests.
Packit Service 084de1
 -xxx           Removes 'xxx' from the current set of tests.  If this is the
Packit Service 084de1
                first token in the list, the current set of tests is first
Packit Service 084de1
                assigned the whole set of available tests, effectively making
Packit Service 084de1
                this token equivalent to TESTS="alltests -xxx".
Packit Service 084de1
 nn             Adds the test group 'nn' (which is a number) to the current
Packit Service 084de1
                set of tests.
Packit Service 084de1
 -nn            Removes the test group 'nn' from the current set of tests.
Packit Service 084de1
                If this is the first token in the list, the current set of
Packit Service 084de1
                tests is first assigned the whole set of available tests,
Packit Service 084de1
                effectively making this token equivalent to
Packit Service 084de1
                TESTS="alltests -xxx".
Packit Service 084de1
Packit Service 084de1
 Also, all tokens except for "alltests" may have wildcards, such as *.
Packit Service 084de1
 (on Unix and Windows, BSD style wildcards are supported, while on VMS,
Packit Service 084de1
 it's VMS style wildcards)
Packit Service 084de1
Packit Service 084de1
 Example: All tests except for the fuzz tests:
Packit Service 084de1
Packit Service 084de1
 $ make TESTS=-test_fuzz test
Packit Service 084de1
Packit Service 084de1
 or (if you want to be explicit)
Packit Service 084de1
Packit Service 084de1
 $ make TESTS='alltests -test_fuzz' test
Packit Service 084de1
Packit Service 084de1
 Example: All tests that have a name starting with "test_ssl" but not those
Packit Service 084de1
 starting with "test_ssl_":
Packit Service 084de1
Packit Service 084de1
 $ make TESTS='test_ssl* -test_ssl_*' test
Packit Service 084de1
Packit Service 084de1
 Example: Only test group 10:
Packit Service 084de1
Packit Service 084de1
 $ make TESTS='10'
Packit Service 084de1
Packit Service 084de1
 Example: All tests except the slow group (group 99):
Packit Service 084de1
Packit Service 084de1
 $ make TESTS='-99'
Packit Service 084de1
Packit Service 084de1
 Example: All tests in test groups 80 to 99 except for tests in group 90:
Packit Service 084de1
Packit Service 084de1
 $ make TESTS='[89]? -90'
Packit Service 084de1
Packit Service 084de1
 Note on multi-threading
Packit Service 084de1
 -----------------------
Packit Service 084de1
Packit Service 084de1
 For some systems, the OpenSSL Configure script knows what compiler options
Packit Service 084de1
 are needed to generate a library that is suitable for multi-threaded
Packit Service 084de1
 applications.  On these systems, support for multi-threading is enabled
Packit Service 084de1
 by default; use the "no-threads" option to disable (this should never be
Packit Service 084de1
 necessary).
Packit Service 084de1
Packit Service 084de1
 On other systems, to enable support for multi-threading, you will have
Packit Service 084de1
 to specify at least two options: "threads", and a system-dependent option.
Packit Service 084de1
 (The latter is "-D_REENTRANT" on various systems.)  The default in this
Packit Service 084de1
 case, obviously, is not to include support for multi-threading (but
Packit Service 084de1
 you can still use "no-threads" to suppress an annoying warning message
Packit Service 084de1
 from the Configure script.)
Packit Service 084de1
Packit Service 084de1
 OpenSSL provides built-in support for two threading models: pthreads (found on
Packit Service 084de1
 most UNIX/Linux systems), and Windows threads. No other threading models are
Packit Service 084de1
 supported. If your platform does not provide pthreads or Windows threads then
Packit Service 084de1
 you should Configure with the "no-threads" option.
Packit Service 084de1
Packit Service 084de1
 Notes on shared libraries
Packit Service 084de1
 -------------------------
Packit Service 084de1
Packit Service 084de1
 For most systems the OpenSSL Configure script knows what is needed to
Packit Service 084de1
 build shared libraries for libcrypto and libssl. On these systems
Packit Service 084de1
 the shared libraries will be created by default. This can be suppressed and
Packit Service 084de1
 only static libraries created by using the "no-shared" option. On systems
Packit Service 084de1
 where OpenSSL does not know how to build shared libraries the "no-shared"
Packit Service 084de1
 option will be forced and only static libraries will be created.
Packit Service 084de1
Packit Service 084de1
 Shared libraries are named a little differently on different platforms.
Packit Service 084de1
 One way or another, they all have the major OpenSSL version number as
Packit Service 084de1
 part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of
Packit Service 084de1
 the name.
Packit Service 084de1
Packit Service 084de1
 On most POSIX platforms, shared libraries are named libcrypto.so.1.1
Packit Service 084de1
 and libssl.so.1.1.
Packit Service 084de1
Packit Service 084de1
 on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll
Packit Service 084de1
 with import libraries libcrypto.dll.a and libssl.dll.a.
Packit Service 084de1
Packit Service 084de1
 On Windows build with MSVC or using MingW, shared libraries are named
Packit Service 084de1
 libcrypto-1_1.dll and libssl-1_1.dll for 32-bit Windows, libcrypto-1_1-x64.dll
Packit Service 084de1
 and libssl-1_1-x64.dll for 64-bit x86_64 Windows, and libcrypto-1_1-ia64.dll
Packit Service 084de1
 and libssl-1_1-ia64.dll for IA64 Windows.  With MSVC, the import libraries
Packit Service 084de1
 are named libcrypto.lib and libssl.lib, while with MingW, they are named
Packit Service 084de1
 libcrypto.dll.a and libssl.dll.a.
Packit Service 084de1
Packit Service 084de1
 On VMS, shareable images (VMS speak for shared libraries) are named
Packit Service 084de1
 ossl$libcrypto0101_shr.exe and ossl$libssl0101_shr.exe.  However, when
Packit Service 084de1
 OpenSSL is specifically built for 32-bit pointers, the shareable images
Packit Service 084de1
 are named ossl$libcrypto0101_shr32.exe and ossl$libssl0101_shr32.exe
Packit Service 084de1
 instead, and when built for 64-bit pointers, they are named
Packit Service 084de1
 ossl$libcrypto0101_shr64.exe and ossl$libssl0101_shr64.exe.
Packit Service 084de1
Packit Service 084de1
 Note on random number generation
Packit Service 084de1
 --------------------------------
Packit Service 084de1
Packit Service 084de1
 Availability of cryptographically secure random numbers is required for
Packit Service 084de1
 secret key generation. OpenSSL provides several options to seed the
Packit Service 084de1
 internal CSPRNG. If not properly seeded, the internal CSPRNG will refuse
Packit Service 084de1
 to deliver random bytes and a "PRNG not seeded error" will occur.
Packit Service 084de1
Packit Service 084de1
 The seeding method can be configured using the --with-rand-seed option,
Packit Service 084de1
 which can be used to specify a comma separated list of seed methods.
Packit Service 084de1
 However in most cases OpenSSL will choose a suitable default method,
Packit Service 084de1
 so it is not necessary to explicitly provide this option. Note also
Packit Service 084de1
 that not all methods are available on all platforms.
Packit Service 084de1
Packit Service 084de1
 I) On operating systems which provide a suitable randomness source (in
Packit Service 084de1
 form  of a system call or system device), OpenSSL will use the optimal
Packit Service 084de1
 available  method to seed the CSPRNG from the operating system's
Packit Service 084de1
 randomness sources. This corresponds to the option --with-rand-seed=os.
Packit Service 084de1
Packit Service 084de1
 II) On systems without such a suitable randomness source, automatic seeding
Packit Service 084de1
 and reseeding is disabled (--with-rand-seed=none) and it may be necessary
Packit Service 084de1
 to install additional support software to obtain a random seed and reseed
Packit Service 084de1
 the CSPRNG manually.  Please check out the manual pages for RAND_add(),
Packit Service 084de1
 RAND_bytes(), RAND_egd(), and the FAQ for more information.