doc: revamp the INSTALL file

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10545)

1 files changed, 1651 insertions, 1183 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 36f271787d..01726a16ab 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,1339 +1,1807 @@
- OPENSSL INSTALLATION
- --------------------
 
- This document describes installation on all supported operating
- systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
- and Windows).
+Build and Install
+=================
+
+This document describes installation on all supported operating
+systems (the Unix/Linux family, including macOS), OpenVMS,
+and Windows).
+
+Table of Contents
+=================
+
+ - [Prerequisites](#prerequisites)
+ - [Notational Conventions](#notational-conventions)
+ - [Quick Installation Guide](#quick-installation-guide)
+    - [Building OpenSSL](#building-openssl)
+    - [Installing OpenSSL](#installing-openssl)
+ - [Configuration Options](#configuration-options)
+    - [API Level](#api-level)
+    - [Cross Compile Prefix](#cross-compile-prefix)
+    - [Build Type](#build-type)
+    - [Directories](#directories)
+    - [Compiler Warnings](#compiler-warnings)
+    - [ZLib Flags](#zlib-flags)
+    - [Seeding the Random Generator](#seeding-the-random-generator)
+    - [Enable and Disable Features](#enable-and-disable-features)
+    - [Displaying configuration data](#displaying-configuration-data)
+ - [Installation Steps in Detail](#installation-steps-in-detail)
+    - [Configure](#configure-openssl)
+    - [Build](#build-openssl)
+    - [Test](#test-openssl)
+    - [Install](#install-openssl)
+ - [Advanced Build Options](#advanced-build-options)
+    - [Environment Variables](#environment-variables)
+    - [Makefile Targets](#makefile-targets)
+    - [Running Selected Tests](#running-selected-tests)
+ - [Troubleshooting](#troubleshooting)
+    - [Configuration Problems](#configuration-problems)
+    - [Build Failures](#build-failures)
+    - [Test Failures](#test-failures)
+ - [Notes](#notes)
+    - [Notes on multi-threading](#notes-on-multi-threading)
+    - [Notes on shared libraries](#notes-on-shared-libraries)
+    - [Notes on random number generation](#notes-on-random-number-generation)
 
- To install OpenSSL, you will need:
 
-  * A make implementation
-  * Perl 5 with core modules (please read NOTES.PERL)
-  * The perl module Text::Template (please read NOTES.PERL)
-  * an ANSI C compiler
-  * a development environment in the form of development libraries and C
-    header files
-  * a supported operating system
+Prerequisites
+=============
 
- For additional platform specific requirements, solutions to specific
- issues and other details, please read one of these:
+To install OpenSSL, you will need:
 
-  * NOTES.UNIX (any supported Unix like system)
-  * NOTES.VMS (OpenVMS)
-  * NOTES.WIN (any supported Windows)
-  * NOTES.DJGPP (DOS platform with DJGPP)
-  * NOTES.ANDROID (obviously Android [NDK])
-  * NOTES.VALGRIND (testing with Valgrind)
+ * A make implementation
+ * Perl 5 with core modules (please read [NOTES.PERL](NOTES.PERL))
+ * The Perl module Text::Template (please read [NOTES.PERL](NOTES.PERL))
+ * an ANSI C compiler
+ * a development environment in the form of development libraries and C
+   header files
+ * a supported operating system
 
- Notational conventions in this document
- ---------------------------------------
+For additional platform specific requirements, solutions to specific
+issues and other details, please read one of these:
 
- Throughout this document, we use the following conventions in command
- examples:
+ * [NOTES.UNIX](NOTES.UNIX) - notes for Unix like systems
+ * [NOTES.VMS](NOTES.VMS) - notes related to OpenVMS
+ * [NOTES.WIN](NOTES.WIN) - notes related to the Windows platform
+ * [NOTES.DJGPP](NOTES.DJGPP) - building for DOS with DJGPP
+ * [NOTES.ANDROID](NOTES.ANDROID) - building for Android platforms (using NDK)
+ * [NOTES.VALGRIND](NOTES.VALGRIND) - testing with Valgrind
+ * [NOTES.PERL](NOTES.PERL) - some notes on Perl
 
- $ command                      Any line starting with a dollar sign
-                                ($) is a command line.
 
- { word1 | word2 | word3 }      This denotes a mandatory choice, to be
-                                replaced with one of the given words.
-                                A simple example would be this:
+Notational conventions
+======================
 
-                                $ echo { FOO | BAR | COOKIE }
+Throughout this document, we use the following conventions.
 
-                                which is to be understood as one of
-                                these:
+Commands
+--------
 
-                                $ echo FOO
-                                - or -
-                                $ echo BAR
-                                - or -
-                                $ echo COOKIE
+Any line starting with a dollar sign is a command line.
 
- [ word1 | word2 | word3 ]      Similar to { word1 | word2 | word3 }
-                                except it's optional to give any of
-                                those.  In addition to the examples
-                                above, this would also be valid:
+    $ command
 
-                                $ echo
+The dollar sign indicates the shell prompt and is not to be entered as
+part of the command.
 
- {{ target }}                   This denotes a mandatory word or
-                                sequence of words of some sort.  A
-                                simple example would be this:
+Choices
+-------
 
-                                $ type {{ filename }}
+Several words in curly braces separated by pipe characters indicate a
+**mandatory choice**, to be replaced with one of the given words.
+For example, the line
 
-                                which is to be understood to use the
-                                command 'type' on some file name
-                                determined by the user.
+    $ echo { WORD1 | WORD2 | WORD3 }
 
- [[ options ]]                  Similar to {{ target }}, but is
-                                optional.
+represents one of the following three commands
 
- Note that the notation assumes spaces around {, }, [, ], {{, }} and
- [[, ]].  This is to differentiate from OpenVMS directory
- specifications, which also use [ and ], but without spaces.
+    $ echo WORD1
+    - or -
+    $ echo WORD2
+    - or -
+    $ echo WORD3
 
- Quick Start
- -----------
+One or several words in square brackets separated by pipe characters
+denote an **optional choice**.  It is similar to the mandatory choice,
+but it can also be omitted entirely.
 
- If you want to just get on with it, do:
+So the line
 
-  on Unix (again, this includes Mac OS/X):
+    $ echo [ WORD1 | WORD2 | WORD3 ]
+
+represents one of the four commands
+
+    $ echo WORD1
+    - or -
+    $ echo WORD2
+    - or -
+    $ echo WORD3
+    - or -
+    $ echo
+
+Arguments
+---------
+
+**Mandatory arguments** are enclosed in double curly braces.
+A simple example would be
+
+    $ type {{ filename }}
+
+which is to be understood to use the command `type` on some file name
+determined by the user.
+
+
+**Optional Arguments** are enclosed in double square brackets.
+
+    [[ options ]]
+
+Note that the notation assumes spaces around {, }, [, ], {{, }} and
+[[, ]].  This is to differentiate from OpenVMS directory
+specifications, which also use [ and ], but without spaces.
+
+
+Quick Installation Guide
+========================
+
+If you just want to get OpenSSL installed without bothering too much
+about the details, here is the short version of how to build and install
+OpenSSL.  If any of the following steps fails, please consult the
+[Installation in Detail](#installation-in-detail) section below.
+
+Building OpenSSL
+----------------
+
+Use the following commands to configure, build and test OpenSSL.
+The testing is optional, but recommended if you intend to install
+OpenSSL for production use.
+
+### Unix / Linux / macOS ###
 
     $ ./config
     $ make
     $ make test
-    $ make install
 
-  on OpenVMS:
+### OpenVMS ###
+
+Use the following commands to build OpenSSL:
 
     $ @config
     $ mms
     $ mms test
-    $ mms install
 
-  on Windows (only pick one of the targets for configuration):
+### Windows ###
+
+If you are using Visual Studio, open a Developer Command Prompt and
+and issue the following commands to build OpenSSL.
 
     $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
     $ nmake
     $ nmake test
+
+As mentioned in the [Choices](#choices) section, you need to pick one
+of the four Configure targets in the first command.
+
+Most likely you will be using the VC-WIN64A target for 64bit Windows
+binaries (AMD64) or VC-WIN32 for 32bit Windows binaries (X86).
+The other two options are VC_WIN64I (Intel IA64, Itanium) and
+VC-CE (Windows CE) are rather uncommon nowadays.
+
+Installing OpenSSL
+------------------
+
+The following commands will install OpenSSL to a default system location.
+
+**Danger Zone:** even if you are impatient, please read the following two
+paragraphs carefully before you install OpenSSL.
+
+For security reasons the default system location is by default not writable
+for unprivileged users.  So for the final installation step administrative
+privileges are required.  The default system location and the procedure to
+obtain administrative privileges depends on the operating sytem.
+It is recommended to compile and test OpenSSL with normal user privileges
+and use administrative privileges only for the final installation step.
+
+On some platforms OpenSSL is preinstalled as part of the Operating System.
+In this case it is highly recommended not to overwrite the system versions,
+because other applications or libraries might depend on it.
+To avoid breaking other applications, install your copy of OpenSSL to a
+[different location](#installing-to-a-different-location) which is not in
+the global search path for system libraries.
+
+### Unix / Linux / macOS ###
+
+Depending on your distribution, you need to run the following command as
+root user or prepend `sudo` to the command:
+
+    $ make install
+
+By default, OpenSSL will be installed to
+
+    /usr/local
+
+More precisely, the files will be installed into the  subdirectories
+
+    /usr/local/bin
+    /usr/local/lib
+    /usr/local/include
+    ...
+
+depending on the file type, as it is custom on Unix-like operating systems.
+
+### OpenVMS ###
+
+Use the following command to install OpenSSL.
+
+    $ mms install
+
+By default, OpenSSL will be installed to
+
+    SYS$COMMON:[OPENSSL-'version'...]
+
+where 'version' is the OpenSSL version number with underscores instead
+of periods.
+
+### Windows ###
+
+If you are using Visual Studio, open the Developer Command Prompt _elevated_
+and issue the following command.
+
     $ nmake install
 
- Note that in order to perform the install step above you need to have
- appropriate permissions to write to the installation directory.
+The easiest way to elevate the Command Prompt is to press and hold down
+the both the `<CTRL>` and `<SHIFT>` key while clicking the menu item in the
+task menu.
+
+The default installation location is
+
+    C:\Program Files\OpenSSL
 
- If any of these steps fails, see section Installation in Detail below.
+for native binaries, or
 
- This will build and install OpenSSL in the default location, which is:
+    C:\Program Files (x86)\OpenSSL
 
-  Unix:    normal installation directories under /usr/local
-  OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
-           OpenSSL version number with underscores instead of periods.
-  Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL
+for 32bit binaries on 64bit Windows (WOW64).
 
- The installation directory should be appropriately protected to ensure
- unprivileged users cannot make changes to OpenSSL binaries or files, or install
- engines. If you already have a pre-installed version of OpenSSL as part of
- your Operating System it is recommended that you do not overwrite the system
- version and instead install to somewhere else.
 
- If you want to install it anywhere else, run config like this:
+#### Installing to a different location ####
 
-  On Unix:
+To install OpenSSL to a different location (for example into your home
+directory for testing purposes) run config like this:
+
+**On Unix**
 
     $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
 
-  On OpenVMS:
+**On OpenVMS**
 
     $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
 
- (Note: if you do add options to the configuration command, please make sure
- you've read more than just this Quick Start, such as relevant NOTES.* files,
- the options outline below, as configuration options may change the outcome
- in otherwise unexpected ways)
-
-
- Configuration Options
- ---------------------
-
- There are several options to ./config (or ./Configure) to customize
- the build (note that for Windows, the defaults for --prefix and
- --openssldir depend in what configuration is used and what Windows
- implementation OpenSSL is built on.  More notes on this in NOTES.WIN):
-
-  --api=x.y[.z]
-                   Build the OpenSSL libraries to support the API for
-                   the specified version.  If "no-deprecated" is also
-                   given, don't build with support for deprecated APIs
-                   in or below the specified version number. For example
-                   "--api=1.1.0" with "no-deprecated" will remove
-                   support for all APIS that were deprecated in
-                   OpenSSL version 1.1.0 or below.
-                   This is a rather specialized option for developers.
-                   If you just intend to remove all deprecated APIs
-                   entirely (up to the current version), only specify
-                   "-no-deprecated" (see below).
-                   If "--api" isn't given, it defaults to the current
-                   OpenSSL minor version.
-
-  --cross-compile-prefix=PREFIX
-                   The PREFIX to include in front of commands for your
-                   toolchain. It's likely to have to end with dash, e.g.
-                   a-b-c- would invoke GNU compiler as a-b-c-gcc, etc.
-                   Unfortunately cross-compiling is too case-specific to
-                   put together one-size-fits-all instructions. You might
-                   have to pass more flags or set up environment variables
-                   to actually make it work. Android and iOS cases are
-                   discussed in corresponding Configurations/15-*.conf
-                   files. But there are cases when this option alone is
-                   sufficient. For example to build the mingw64 target on
-                   Linux "--cross-compile-prefix=x86_64-w64-mingw32-"
-                   works. Naturally provided that mingw packages are
-                   installed. Today Debian and Ubuntu users have option to
-                   install a number of prepackaged cross-compilers along
-                   with corresponding run-time and development packages for
-                   "alien" hardware. To give another example
-                   "--cross-compile-prefix=mipsel-linux-gnu-" suffices
-                   in such case. Needless to mention that you have to
-                   invoke ./Configure, not ./config, and pass your target
-                   name explicitly. Also, note that --openssldir refers
-                   to target's file system, not one you are building on.
-
-  --debug
-                   Build OpenSSL with debugging symbols and zero optimization
-                   level.
-
-  --libdir=DIR
-                   The name of the directory under the top of the installation
-                   directory tree (see the --prefix option) where libraries will
-                   be installed. By default this is "lib". Note that on Windows
-                   only ".lib" files will be stored in this location. dll files
-                   will always be installed to the "bin" directory.
-
-  --openssldir=DIR
-                   Directory for OpenSSL configuration files, and also the
-                   default certificate and key store.  Defaults are:
-
-                   Unix:           /usr/local/ssl
-                   Windows:        C:\Program Files\Common Files\SSL
-                                or C:\Program Files (x86)\Common Files\SSL
-                   OpenVMS:        SYS$COMMON:[OPENSSL-COMMON]
-
-  --prefix=DIR
-                   The top of the installation directory tree.  Defaults are:
-
-                   Unix:           /usr/local
-                   Windows:        C:\Program Files\OpenSSL
-                                or C:\Program Files (x86)\OpenSSL
-                   OpenVMS:        SYS$COMMON:[OPENSSL-'version']
-
-  --release
-                   Build OpenSSL without debugging symbols. This is the default.
-
-  --strict-warnings
-                   This is a developer flag that switches on various compiler
-                   options recommended for OpenSSL development. It only works
-                   when using gcc or clang as the compiler. If you are
-                   developing a patch for OpenSSL then it is recommended that
-                   you use this option where possible.
-
-  --with-zlib-include=DIR
-                   The directory for the location of the zlib include file. This
-                   option is only necessary if enable-zlib (see below) is used
-                   and the include file is not already on the system include
-                   path.
-
-  --with-zlib-lib=LIB
-                   On Unix: this is the directory containing the zlib library.
-                   If not provided the system library path will be used.
-                   On Windows: this is the filename of the zlib library (with or
-                   without a path). This flag must be provided if the
-                   zlib-dynamic 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.
-                   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 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.
-
-  enable-ktls
-                   Build with Kernel TLS support. This option will enable the
-                   use of the Kernel TLS data-path, which can improve
-                   performance and allow for the use of sendfile and splice
-                   system calls on TLS sockets. The Kernel may use TLS
-                   accelerators if any are available on the system.
-                   This option will be forced off on systems that do not support
-                   the Kernel TLS data-path.
-
-  enable-asan
-                   Build with the Address sanitiser. This is a developer option
-                   only. It may not work on all platforms and should never be
-                   used in production environments. It will only work when used
-                   with gcc or clang and should be used in conjunction with the
-                   no-shared option.
-
-  no-asm
-                   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.
-
-  no-autoalginit
-                   Don't automatically load all supported ciphers and digests.
-                   Typically OpenSSL will make available all of its supported
-                   ciphers and digests. For a statically linked application this
-                   may be undesirable if small executable size is an objective.
-                   This only affects libcrypto. Ciphers and digests will have to
-                   be loaded manually using EVP_add_cipher() and
-                   EVP_add_digest() if this option is used. This option will
-                   force a non-shared build.
-
-  no-autoerrinit
-                   Don't automatically load all libcrypto/libssl error strings.
-                   Typically OpenSSL will automatically load human readable
-                   error strings. For a statically linked application this may
-                   be undesirable if small executable size is an objective.
-
-  no-autoload-config
-                   Don't automatically load the default openssl.cnf file.
-                   Typically OpenSSL will automatically load a system config
-                   file which configures default ssl options.
-
-  enable-buildtest-c++
-                   While testing, generate C++ buildtest files that
-                   simply check that the public OpenSSL header files
-                   are usable standalone with C++.
-
-                   Enabling this option demands extra care.  For any
-                   compiler flag given directly as configuration
-                   option, you must ensure that it's valid for both
-                   the C and the C++ compiler.  If not, the C++ build
-                   test will most likely break.  As an alternative,
-                   you can use the language specific variables, CFLAGS
-                   and CXXFLAGS.
-
-  no-capieng
-                   Don't build the CAPI engine. This option will be forced if
-                   on a platform that does not support CAPI.
-
-  no-cmp
-                   Don't build support for CMP features
-
-  no-cms
-                   Don't build support for CMS features
-
-  no-comp
-                   Don't build support for SSL/TLS compression. If this option
-                   is left enabled (the default), then compression will only
-                   work if the zlib or zlib-dynamic options are also chosen.
-
-  enable-crypto-mdebug
-                   This now only enables the failed-malloc feature.
-
-  enable-crypto-mdebug-backtrace
-                   This is a no-op; the project uses the compiler's
-                   address/leak sanitizer instead.
-
-  no-ct
-                   Don't build support for Certificate Transparency.
-
-  no-deprecated
-                   Don't build with support for deprecated APIs up
-                   until and including the version given with
-                   "--api" (or the current version of "--api" wasn't
-                   given).
-
-  no-dgram
-                   Don't build support for datagram based BIOs. Selecting this
-                   option will also force the disabling of DTLS.
-
-  no-dso
-                   Don't build support for loading Dynamic Shared Objects.
-
-  enable-devcryptoeng
-                   Build the /dev/crypto engine.  It is automatically selected
-                   on BSD implementations, in which case it can be disabled with
-                   no-devcryptoeng.
-
-  no-dynamic-engine
-                   Don't build the dynamically loaded engines. This only has an
-                   effect in a "shared" build
-
-  no-ec
-                   Don't build support for Elliptic Curves.
-
-  no-ec2m
-                   Don't build support for binary Elliptic Curves
-
-  enable-ec_nistp_64_gcc_128
-                   Enable support for optimised implementations of some commonly
-                   used NIST elliptic curves.
-                   This 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
-                   Gathering Daemon).
-
-  no-engine
-                   Don't build support for loading engines.
-
-  no-err
-                   Don't compile in any error strings.
-
-  enable-external-tests
-                   Enable building of integration with external test suites.
-                   This is a developer option and may not work on all platforms.
-                   The only supported external test suite at the current time is
-                   the BoringSSL test suite. See the file test/README.external
-                   for further details.
-
-  no-filenames
-                   Don't compile in filename and line number information (e.g.
-                   for errors and memory allocation).
-
-  no-fips
-                   Don't compile the FIPS module
-
-  enable-fuzz-libfuzzer, enable-fuzz-afl
-                   Build with support for fuzzing using either libfuzzer or AFL.
-                   These are developer options only. They may not work on all
-                   platforms and should never be used in production environments.
-                   See the file fuzz/README.md for further details.
-
-  no-gost
-                   Don't build support for GOST based ciphersuites. Note that
-                   if this feature is enabled then GOST ciphersuites are only
-                   available if the GOST algorithms are also available through
-                   loading an externally supplied engine.
-
-  no-legacy
-                   Don't build the legacy provider. Disabling this also disables
-                   the legacy algorithms: MD2 (already disabled by default).
-
-  no-makedepend
-                   Don't generate dependencies.
-
-  no-module
-                   Don't build any dynamically loadable engines.  This also
-                   implies 'no-dynamic-engine'.
-
-  no-multiblock
-                   Don't build support for writing multiple records in one
-                   go in libssl (Note: this is a different capability to the
-                   pipelining functionality).
-
-  no-nextprotoneg
-                   Don't build support for the NPN TLS extension.
-
-  no-ocsp
-                   Don't build support for OCSP.
-
-  no-padlockeng
-  no-hw-padlock
-                   Don't build the padlock engine.
-                   ('no-hw-padlock' is deprecated and should not be used)
-
-  no-pic
-                   Don't build with support for Position Independent Code.
-
-  no-pinshared     By default OpenSSL will attempt to stay in memory until the
-                   process exits. This is so that libcrypto and libssl can be
-                   properly cleaned up automatically via an "atexit()" handler.
-                   The handler is registered by libcrypto and cleans up both
-                   libraries. On some platforms the atexit() handler will run on
-                   unload of libcrypto (if it has been dynamically loaded)
-                   rather than at process exit. This option can be used to stop
-                   OpenSSL from attempting to stay in memory until the process
-                   exits. This could lead to crashes if either libcrypto or
-                   libssl have already been unloaded at the point
-                   that the atexit handler is invoked, e.g. on a platform which
-                   calls atexit() on unload of the library, and libssl is
-                   unloaded before libcrypto then a crash is likely to happen.
-                   Applications can suppress running of the atexit() handler at
-                   run time by using the OPENSSL_INIT_NO_ATEXIT option to
-                   OPENSSL_init_crypto(). See the man page for it for further
-                   details.
-
-  no-posix-io
-                   Don't use POSIX IO capabilities.
-
-  no-psk
-                   Don't build support for Pre-Shared Key based ciphersuites.
-
-  no-rdrand
-                   Don't use hardware RDRAND capabilities.
-
-  no-rfc3779
-                   Don't build support for RFC3779 ("X.509 Extensions for IP
-                   Addresses and AS Identifiers")
-
-  sctp
-                   Build support for SCTP
-
-  no-shared
-                   Do not create shared libraries, only static ones.  See "Note
-                   on shared libraries" below.
-
-  no-sock
-                   Don't build support for socket BIOs
-
-  no-srp
-                   Don't build support for SRP or SRP based ciphersuites.
-
-  no-srtp
-                   Don't build SRTP support
-
-  no-sse2
-                   Exclude SSE2 code paths from 32-bit x86 assembly modules.
-                   Normally SSE2 extension is detected at run-time, but the
-                   decision whether or not the machine code will be executed
-                   is taken solely on CPU capability vector. This means that
-                   if you happen to run OS kernel which does not support SSE2
-                   extension on Intel P4 processor, then your application
-                   might be exposed to "illegal instruction" exception.
-                   There might be a way to enable support in kernel, e.g.
-                   FreeBSD kernel can  be compiled with CPU_ENABLE_SSE, and
-                   there is a way to disengage SSE2 code paths upon application
-                   start-up, but if you aim for wider "audience" running
-                   such kernel, consider no-sse2. Both the 386 and
-                   no-asm options imply no-sse2.
-
-  enable-ssl-trace
-                   Build with the SSL Trace capabilities (adds the "-trace"
-                   option to s_client and s_server).
-
-  no-static-engine
-                   Don't build the statically linked engines. This only
-                   has an impact when not built "shared".
-
-  no-stdio
-                   Don't use anything from the C header file "stdio.h" that
-                   makes use of the "FILE" type. Only libcrypto and libssl can
-                   be built in this way. Using this option will suppress
-                   building the command line applications. Additionally since
-                   the OpenSSL tests also use the command line applications the
-                   tests will also be skipped.
-
-  no-tests
-                   Don't build test programs or run any test.
-
-  no-threads
-                   Don't try to build with support for multi-threaded
-                   applications.
-
-  threads
-                   Build with support for multi-threaded applications. Most
-                   platforms will enable this by default. However if on a
-                   platform where this is not the case then this will usually
-                   require additional system-dependent options! See "Note on
-                   multi-threading" below.
-
-  enable-trace
-                   Build with support for the integrated tracing api. See manual pages
-                   OSSL_trace_set_channel(3) and OSSL_trace_enabled(3) for details.
-
-  no-ts
-                   Don't build Time Stamping Authority support.
-
-  enable-ubsan
-                   Build with the Undefined Behaviour sanitiser. This is a
-                   developer option only. It may not work on all platforms and
-                   should never be used in production environments. It will only
-                   work when used with gcc or clang and should be used in
-                   conjunction with the "-DPEDANTIC" option (or the
-                   --strict-warnings option).
-
-  no-ui
-                   Don't build with the "UI" capability (i.e. the set of
-                   features enabling text based prompts).
-
-  enable-unit-test
-                   Enable additional unit test APIs. This should not typically
-                   be used in production deployments.
-
-  no-uplink
-                   Don't build support for UPLINK interface.
-
-  enable-weak-ssl-ciphers
-                   Build support for SSL/TLS ciphers that are considered "weak"
-                   (e.g. RC4 based ciphersuites).
-
-  zlib
-                   Build with support for zlib compression/decompression.
-
-  zlib-dynamic
-                   Like "zlib", but has OpenSSL load the zlib library
-                   dynamically when needed.  This is only supported on systems
-                   where loading of shared libraries is supported.
-
-  386
-                   In 32-bit x86 builds, when generating assembly modules,
-                   use the 80386 instruction set only (the default x86 code
-                   is more efficient, but requires at least a 486). Note:
-                   This doesn't affect code generated by compiler, you're
-                   likely to complement configuration command line with
-                   suitable compiler-specific option.
-
-  no-<prot>
-                   Don't build support for negotiating the specified SSL/TLS
-                   protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2,
-                   tls1_3, dtls, dtls1 or dtls1_2). If "no-tls" is selected then
-                   all of tls1, tls1_1, tls1_2 and tls1_3 are disabled.
-                   Similarly "no-dtls" will disable dtls1 and dtls1_2. The
-                   "no-ssl" option is synonymous with "no-ssl3". Note this only
-                   affects version negotiation. OpenSSL will still provide the
-                   methods for applications to explicitly select the individual
-                   protocol versions.
-
-  no-<prot>-method
-                   As for no-<prot> but in addition do not build the methods for
-                   applications to explicitly select individual protocol
-                   versions. Note that there is no "no-tls1_3-method" option
-                   because there is no application method for TLSv1.3. Using
-                   individual protocol methods directly is deprecated.
-                   Applications should use TLS_method() instead.
-
-  enable-<alg>
-                   Build with support for the specified algorithm, where <alg>
-                   is one of: md2 or rc5.
-
-  no-<alg>
-                   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, siv, 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
-                   passed through to the compiler to allow you to define
-                   preprocessor symbols, specify additional libraries, library
-                   directories or other compiler options. It might be worth
-                   noting that some compilers generate code specifically for
-                   processor the compiler currently executes on. This is not
-                   necessarily what you might have in mind, since it might be
-                   unsuitable for execution on other, typically older,
-                   processor. Consult your compiler documentation.
-
-                   Take note of the VAR=value documentation below and how
-                   these flags interact with those variables.
-
-  -xxx, +xxx, /xxx
-                   Additional options that are not otherwise recognised are
-