[[ options ]]
-Note that the notation assumes spaces around {, }, [, ], {{, }} and
-[[, ]]. This is to differentiate from OpenVMS directory
+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
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.
+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
------------------
#### Installing to a different location
To install OpenSSL to a different location (for example into your home
-directory for testing purposes) run Configure as shown in the following
+directory for testing purposes) run `Configure` as shown in the following
examples.
On Unix:
Configuration Options
=====================
-There are several options to ./Configure to customize the build (note that
-for Windows, the defaults for `--prefix` and `--openssldir` depend in what
+There are several options to `./Configure` to customize the build (note that
+for Windows, the defaults for `--prefix` and `--openssldir` depend on what
configuration is used and what Windows implementation OpenSSL is built on.
-More notes on this in NOTES.WIN):
+More notes on this in [NOTES.WIN](NOTES.WIN)):
API Level
---------
Cross Compile Prefix
--------------------
- --cross-compile-prefix=PREFIX
+ --cross-compile-prefix=<PREFIX>
-The PREFIX to include in front of commands for your toolchain.
+The `<PREFIX>` to include in front of commands for your toolchain.
-It is 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
+It is 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
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 static libraries (`*.lib`) will
+this is `lib/`. Note that on Windows only static libraries (`*.lib`) will
be stored in this location. Shared libraries (`*.dll`) will always be
-installed to the "bin" directory.
+installed to the `bin/` directory.
### openssldir
**On Windows:** this is the filename of the zlib library (with or
without a path). This flag must be provided if the
-[zlib-dynamic](#zlib-dynamic) option is not also used. If zlib-dynamic is used
-then this flag is optional and defaults to "ZLIB1" if not provided.
+[zlib-dynamic](#zlib-dynamic) option is not also used. If `zlib-dynamic` is used
+then this flag is optional and defaults to `ZLIB1` 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.
+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.
Seeding the Random Generator
----------------------------
### devrandom
-Use the first device from the DEVRANDOM list which can be opened to read
-random bytes. The DEVRANDOM preprocessor constant expands to
+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"
### rdcpu
-Use the RDSEED or RDRAND command if provided by the CPU.
+Use the `RDSEED` or `RDRAND` command if provided by the CPU.
### librandom
Enable and Disable Features
---------------------------
-Feature options always come in pairs, an option to enable feature xxxx, and
+Feature options always come in pairs, an option to enable feature `xxxx`, and
and option to disable it:
[ enable-xxxx | no-xxxx ]
Whether a feature is enabled or disabled by default, depends on the feature.
In the following list, always the non-default variant is documented: if
-feature xxxx is disabled by default then enable-xxxx is documented and
-if feature xxxx is enabled by default then no-xxxx is documented.
+feature `xxxx` is disabled by default then `enable-xxxx` is documented and
+if feature `xxxx` is enabled by default then `no-xxxx` is documented.
### no-afalgeng
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.
+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
### no-autoload-config
-Don't automatically load the default openssl.cnf file.
+Don't automatically load the default `openssl.cnf` file.
Typically OpenSSL will automatically load a system config file which configures
default SSL options.
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.
+alternative, you can use the language specific variables, `CFLAGS` and `CXXFLAGS`.
### no-capieng
### no-cmp
-Don't build support for Certificate Management Protocol (CMP).
+Don't build support for Certificate Management Protocol (CMP)
+and Certificate Request Message Format (CRMF).
### no-cms
Don't build support for SSL/TLS compression.
If this option is enabled (the default), then compression will only work if
-the zlib or zlib-dynamic options are also chosen.
+the zlib or `zlib-dynamic` options are also chosen.
### enable-crypto-mdebug
-This now only enables the failed-malloc feature.
+This now only enables the `failed-malloc` feature.
### enable-crypto-mdebug-backtrace
Build the `/dev/crypto` engine.
This option is automatically selected on the BSD platform, in which case it can
-be disabled with no-devcryptoeng.
+be disabled with `no-devcryptoeng`.
### no-dynamic-engine
Don't build any dynamically loadable engines.
-This also implies 'no-dynamic-engine'.
+This also implies `no-dynamic-engine`.
### no-multiblock
### no-hw-padlock
-As synonyme for no-padlockeng. Deprecated and should not be used.
+As synonym for `no-padlockeng`. Deprecated and should not be used.
### no-pic
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
+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
+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.
+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
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
+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.
+"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.
-This adds the "-trace" option to s_client and s_server.
+This adds the `-trace` option to `s_client` and `s_server`.
### no-static-engine
Build with the Undefined Behaviour sanitiser (UBSAN).
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
+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-console
Don't build support for negotiating the specified SSL/TLS protocol.
-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.
+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-{ssl|ssl3|tls|tls1|tls1_1|tls1_2|tls1_3|dtls|dtls1|dtls1_2}-method
-Analogous to no-{protocol} but in addition do not build the methods for
+Analogous to `no-{protocol}` 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
+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.
+use `TLS_method()` instead.
### enable-{algorithm}
Build without support for the specified algorithm.
-The "ripemd" algorithm is deprecated and if used is synonymous with rmd160.
+The `ripemd` algorithm is deprecated and if used is synonymous with `rmd160`.
### Compiler-specific options
Additional options that are not otherwise recognised are passed through as
they are to the compiler as well. Unix-style options beginning with a
-'-' or '+' and Windows-style options beginning with a '/' are recognized.
+`-` or `+` and Windows-style options beginning with a `/` are recognized.
Again, consult your compiler documentation.
If the option contains arguments separated by spaces, then the URL-style
-notation %20 can be used for the space character in order to avoid having
-to quote the option. For example, -opt%20arg gets expanded to -opt arg.
+notation `%20` can be used for the space character in order to avoid having
+to quote the option. For example, `-opt%20arg` gets expanded to `-opt arg`.
In fact, any ASCII character can be encoded as %xx using its hexadecimal
encoding.
VAR=value
-Assign the given value to the environment variable VAR for Configure.
+Assign the given value to the environment variable `VAR` for `Configure`.
These work just like normal environment variable assignments, but are supported
on all platforms and are confined to the configuration scripts only.
AR, CC, CXX, CROSS_COMPILE, HASHBANGPERL, PERL, RANLIB, RC, and WINDRES
-For example, the following command will not see -DBAR:
+For example, the following command will not see `-DBAR`:
$ CPPFLAGS=-DBAR ./Configure -DCOOKIE
$ CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- ./Configure -DCOOKIE
-If CC is set, it is advisable to also set CXX to ensure both the C and C++
+If `CC` is set, it is advisable to also set `CXX` to ensure both the C and C++
compiler are in the same "family". This becomes relevant with
-'enable-external-tests' and 'enable-buildtest-c++'.
+`enable-external-tests` and `enable-buildtest-c++`.
### Reconfigure
Reconfigure from earlier data.
This fetches the previous command line options and environment from data
-saved in "configdata.pm" and runs the configuration process again, using
+saved in `configdata.pm` and runs the configuration process again, using
these options and environment. Note: NO other option is permitted together
-with "reconf". Note: The original configuration saves away values for ALL
+with `reconf`. Note: The original configuration saves away values for ALL
environment variables that were used, and if they weren't defined, they are
still saved away with information that they weren't originally defined.
This information takes precedence over environment variables that are
-----------------------------
The configuration script itself will say very little, and finishes by
-creating "configdata.pm". This perl module can be loaded by other scripts
+creating `configdata.pm`. This perl module can be loaded by other scripts
to find all the configuration data, and it can also be used as a script to
display all sorts of configuration data in a human readable form.
Please use the appropriate form for your platform.
Pick a suitable name from the list that matches your system. For most
-operating systems there is a choice between using "cc" or "gcc".
+operating systems there is a choice between using cc or gcc.
When you have identified your system (and if necessary compiler) use this
-name as the argument to Configure. For example, a "linux-elf" user would
+name as the argument to `Configure`. For example, a `linux-elf` user would
run:
$ ./Configure linux-elf [[ options ]]
### Creating your own Configuration
If your system isn't listed, you will have to create a configuration
-file named Configurations/{{ something }}.conf and add the correct
+file named `Configurations/{{ something }}.conf` and add the correct
configuration for your system. See the available configs as examples
and read [Configurations/README](Configurations/README)
and [Configurations/README.design](Configurations/README.design)
for more information.
-The generic configurations "cc" or "gcc" should usually work on 32 bit
+The generic configurations `cc` or `gcc` should usually work on 32 bit
Unix-like systems.
-Configure creates a build file (`Makefile` on Unix, `makefile` on Windows
-and `descrip.mms` on OpenVMS) from a suitable template in Configurations,
-and defines various macros in include/openssl/configuration.h (generated
-from include/openssl/configuration.h.in).
+`Configure` creates a build file (`Makefile` on Unix, `makefile` on Windows
+and `descrip.mms` on OpenVMS) from a suitable template in `Configurations/`,
+and defines various macros in `include/openssl/configuration.h` (generated
+from `include/openssl/configuration.h.in`.
### Out of Tree Builds
$ cd \temp-openssl
$ perl d:\PATH\TO\OPENSSL\SOURCE\Configure [[ options ]]
-Paths can be relative just as well as absolute. Configure will do its best
+Paths can be relative just as well as absolute. `Configure` will do its best
to translate them to relative paths whenever possible.
Build OpenSSL
$ mms ! (or mmk) OpenVMS
$ nmake # Windows
-This will build the OpenSSL libraries (libcrypto.a and libssl.a on
+This will build the OpenSSL libraries (`libcrypto.a` and `libssl.a` on
Unix, corresponding on other platforms) and the OpenSSL binary
-("openssl"). The libraries will be built in the top-level directory,
-and the binary will be in the "apps" subdirectory.
+(`openssl`). The libraries will be built in the top-level directory,
+and the binary will be in the `apps/` subdirectory.
If the build fails, take a look at the [Build Failures](#build-failures)
subsection of the [Troubleshooting](#troubleshooting) section.
appropriate permissions to write to the installation directory.
The above commands will install all the software components in this
-directory tree under PREFIX (the directory given with `--prefix` or
+directory tree under `<PREFIX>` (the directory given with `--prefix` or
its default):
### Unix / Linux / macOS
### OpenVMS
-'arch' is replaced with the architecture name, "Alpha" or "ia64",
-'sover' is replaced with the shared library version (0101 for 1.1), and
+'arch' is replaced with the architecture name, `Alpha` or `ia64`,
+'sover' is replaced with the shared library version (`0101` for 1.1), and
'pz' is replaced with the pointer size OpenSSL was built with:
[.EXE.'arch'] Contains the openssl binary.
A number of environment variables can be used to provide additional control
over the build process. Typically these should be defined prior to running
-Configure. Not all environment variables are relevant to all platforms.
+`Configure`. Not all environment variables are relevant to all platforms.
AR
The name of the ar executable to use.
The compiler to use. Configure will attempt to pick a default
compiler for your platform but this choice can be overridden
using this variable. Set it to the compiler executable you wish
- to use, e.g. "gcc" or "clang".
+ to use, e.g. gcc or clang.
CROSS_COMPILE
This environment variable has the same meaning as for the
Makefile Targets
----------------
-The Configure script generates a Makefile in a format relevant to the specific
+The `Configure` script generates a Makefile in a format relevant to the specific
platform. The Makefiles provide a number of targets that can be used. Not all
targets may be available on all platforms. Only the most common targets are
described here. Examine the Makefiles themselves for the full list.
Operating system: x86-whatever-minix
This system (minix) is not supported. See file INSTALL for details.
-Even if the automatic target selection by the `./Configure` script fails, chances
-are that you still might find a suitable target in the Configurations directory,
-which you can supply to the `./Configure` command, possibly after some adjustment.
+Even if the automatic target selection by the `./Configure` script fails,
+chances are that you still might find a suitable target in the `Configurations`
+directory, which you can supply to the `./Configure` command,
+possibly after some adjustment.
-The Configurations directory contains a lot of examples of such targets.
+The `Configurations/` directory contains a lot of examples of such targets.
The main configuration file is [10-main.conf][], which contains all targets that
are officially supported by the OpenSSL team. Other configuration files contain
targets contributed by other OpenSSL users. The list of targets can be found in
If you call `./Configure` without arguments, it will give you a list of all
known targets. Using `grep`, you can lookup the target definition in the
-Configurations directory. For example the "android-x86_64" can be found in
-Configurations/15-android.conf.
+`Configurations/` directory. For example the `android-x86_64` can be found in
+[Configurations/15-android.conf](Configurations/15-android.conf).
The directory contains two README files, which explain the general syntax and
-design of the configurations files.
+design of the configuration files.
- [Configurations/README](Configurations/README)
- [Configurations/README.design](Configurations/README.design)
$ nmake clean # Windows
Assembler error messages can sometimes be sidestepped by using the
-"no-asm" configuration option.
+`no-asm` configuration option.
Compiling parts of OpenSSL with gcc and others with the system compiler will
result in unresolved symbols on some systems.
Notes on multi-threading
------------------------
-For some systems, the OpenSSL Configure script knows what compiler options
+For some systems, the OpenSSL `Configure` script knows what compiler options
are needed to generate a library that is suitable for multi-threaded
applications. On these systems, support for multi-threading is enabled
-by default; use the "no-threads" option to disable (this should never be
+by default; use the `no-threads` option to disable (this should never be
necessary).
On other systems, to enable support for multi-threading, you will have
-to specify at least two options: "threads", and a system-dependent option.
-(The latter is "-D_REENTRANT" on various systems.) The default in this
+to specify at least two options: `threads`, and a system-dependent option.
+(The latter is `-D_REENTRANT` on various systems.) The default in this
case, obviously, is not to include support for multi-threading (but
-you can still use "no-threads" to suppress an annoying warning message
-from the Configure script.)
+you can still use `no-threads` to suppress an annoying warning message
+from the `Configure` script.)
OpenSSL provides built-in support for two threading models: pthreads (found on
most UNIX/Linux systems), and Windows threads. No other threading models are
supported. If your platform does not provide pthreads or Windows threads then
-you should Configure with the "no-threads" option.
+you should use `Configure` with the `no-threads` option.
Notes on shared libraries
-------------------------
-For most systems the OpenSSL Configure script knows what is needed to
+For most systems the OpenSSL `Configure` script knows what is needed to
build shared libraries for libcrypto and libssl. On these systems
the shared libraries will be created by default. This can be suppressed and
-only static libraries created by using the "no-shared" option. On systems
-where OpenSSL does not know how to build shared libraries the "no-shared"
+only static libraries created by using the `no-shared` option. On systems
+where OpenSSL does not know how to build shared libraries the `no-shared`
option will be forced and only static libraries will be created.
Shared libraries are named a little differently on different platforms.
One way or another, they all have the major OpenSSL version number as
-part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of
+part of the file name, i.e. for OpenSSL 1.1.x, `1.1` is somehow part of
the name.
-On most POSIX platforms, shared libraries are named libcrypto.so.1.1
-and libssl.so.1.1.
+On most POSIX platforms, shared libraries are named `libcrypto.so.1.1`
+and `libssl.so.1.1`.
-on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll
-with import libraries libcrypto.dll.a and libssl.dll.a.
+on Cygwin, shared libraries are named `cygcrypto-1.1.dll` and `cygssl-1.1.dll`
+with import libraries `libcrypto.dll.a` and `libssl.dll.a`.
On Windows build with MSVC or using MingW, shared libraries are named
-libcrypto-1_1.dll and libssl-1_1.dll for 32-bit Windows, libcrypto-1_1-x64.dll
-and libssl-1_1-x64.dll for 64-bit x86_64 Windows, and libcrypto-1_1-ia64.dll
-and libssl-1_1-ia64.dll for IA64 Windows. With MSVC, the import libraries
-are named libcrypto.lib and libssl.lib, while with MingW, they are named
-libcrypto.dll.a and libssl.dll.a.
+`libcrypto-1_1.dll` and `libssl-1_1.dll` for 32-bit Windows,
+`libcrypto-1_1-x64.dll` and `libssl-1_1-x64.dll` for 64-bit x86_64 Windows,
+and `libcrypto-1_1-ia64.dll` and `libssl-1_1-ia64.dll` for IA64 Windows.
+With MSVC, the import libraries are named `libcrypto.lib` and `libssl.lib`,
+while with MingW, they are named `libcrypto.dll.a` and `libssl.dll.a`.
On VMS, shareable images (VMS speak for shared libraries) are named
-ossl$libcrypto0101_shr.exe and ossl$libssl0101_shr.exe. However, when
+`ossl$libcrypto0101_shr.exe` and `ossl$libssl0101_shr.exe`. However, when
OpenSSL is specifically built for 32-bit pointers, the shareable images
-are named ossl$libcrypto0101_shr32.exe and ossl$libssl0101_shr32.exe
+are named `ossl$libcrypto0101_shr32.exe` and `ossl$libssl0101_shr32.exe`
instead, and when built for 64-bit pointers, they are named
-ossl$libcrypto0101_shr64.exe and ossl$libssl0101_shr64.exe.
+`ossl$libcrypto0101_shr64.exe` and `ossl$libssl0101_shr64.exe`.
Notes on random number generation
---------------------------------
randomness sources. This corresponds to the option `--with-rand-seed=os`.
II) On systems without such a suitable randomness source, automatic seeding
-and reseeding is disabled (--with-rand-seed=none) and it may be necessary
+and reseeding is disabled (`--with-rand-seed=none`) and it may be necessary
to install additional support software to obtain a random seed and reseed
-the CSPRNG manually. Please check out the manual pages for RAND_add(),
-RAND_bytes(), RAND_egd(), and the FAQ for more information.
+the CSPRNG manually. Please check out the manual pages for `RAND_add()`,
+`RAND_bytes()`, `RAND_egd()`, and the FAQ for more information.
<!-- Links -->
projects / openssl.git / commitdiff