- [Compiler Warnings](#compiler-warnings)
- [ZLib Flags](#zlib-flags)
- [Seeding the Random Generator](#seeding-the-random-generator)
+ - [Setting the FIPS HMAC key](#setting-the-FIPS-HMAC-key)
- [Enable and Disable Features](#enable-and-disable-features)
- [Displaying configuration data](#displaying-configuration-data)
- [Installation Steps in Detail](#installation-steps-in-detail)
- [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)
+ - [Notes on assembler modules compilation](#notes-on-assembler-modules-compilation)
Prerequisites
=============
To install OpenSSL, you will need:
* 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))
+ * Perl 5 with core modules (please read [NOTES-PERL.md](NOTES-PERL.md))
+ * The Perl module `Text::Template` (please read [NOTES-PERL.md](NOTES-PERL.md))
* an ANSI C compiler
* a development environment in the form of development libraries and C
header files
For additional platform specific requirements, solutions to specific
issues and other details, please read one of these:
- * [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
+ * [Notes for UNIX-like platforms](NOTES-UNIX.md)
+ * [Notes for Android platforms](NOTES-ANDROID.md)
+ * [Notes for Windows platforms](NOTES-WINDOWS.md)
+ * [Notes for the DOS platform with DJGPP](NOTES-DJGPP.md)
+ * [Notes for the OpenVMS platform](NOTES-VMS.md)
+ * [Notes on Perl](NOTES-PERL.md)
+ * [Notes on Valgrind](NOTES-VALGRIND.md)
Notational conventions
======================
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.
+[Installation in Detail](#installation-steps-in-detail) section below.
Building OpenSSL
----------------
### Windows
If you are using Visual Studio, open a Developer Command Prompt and
-and issue the following commands to build OpenSSL.
+issue the following commands to build OpenSSL.
$ perl Configure
$ nmake
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.
+obtain administrative privileges depends on the operating system.
It is recommended to compile and test OpenSSL with normal user privileges
and use administrative privileges only for the final installation step.
By default, OpenSSL will be installed to
- SYS$COMMON:[OPENSSL-'version'...]
-
-where 'version' is the OpenSSL version number with underscores instead
-of periods.
+ SYS$COMMON:[OPENSSL]
### Windows
directory for testing purposes) run `Configure` as shown in the following
examples.
+The options `--prefix` and `--openssldir` are explained in further detail in
+[Directories](#directories) below, and the values used here are mere examples.
+
On Unix:
$ ./Configure --prefix=/opt/openssl --openssldir=/usr/local/ssl
$ perl Configure --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,
+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.
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](NOTES.WIN)):
+For more information, see the [Notes for Windows platforms](NOTES-WINDOWS.md).
API Level
---------
Unix: /usr/local
Windows: C:\Program Files\OpenSSL
- OpenVMS: SYS$COMMON:[OPENSSL-'version']
+ OpenVMS: SYS$COMMON:[OPENSSL]
Compiler Warnings
-----------------
--with-zlib-include=DIR
The directory for the location of the zlib include file. This option is only
-necessary if [enable-zlib](#enable-zlib) is used and the include file is not
+necessary if [zlib](#zlib) is used and the include file is not
already on the system include path.
### with-zlib-lib
### egd
Check for an entropy generating daemon.
+This source is ignored by the FIPS provider.
### rdcpu
### librandom
Use librandom (not implemented yet).
+This source is ignored by the FIPS provider.
### 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.
+This option is ignored by the FIPS provider.
For more information, see the section [Notes on random number generation][rng]
at the end of this document.
[rng]: #notes-on-random-number-generation
+Setting the FIPS HMAC key
+-------------------------
+
+ --fips-key=value
+
+As part of its self-test validation, the FIPS module must verify itself
+by performing a SHA-256 HMAC computation on itself. The default key is
+the SHA256 value of "the holy handgrenade of antioch" and is sufficient
+for meeting the FIPS requirements.
+
+To change the key to a different value, use this flag. The value should
+be a hex string no more than 64 characters.
+
Enable and Disable Features
---------------------------
-Feature options always come in pairs, an option to enable feature `xxxx`, and
-and option to disable it:
+Feature options always come in pairs, an option to enable feature
+`xxxx`, and an option to disable it:
[ enable-xxxx | no-xxxx ]
gcc or clang and should be used in conjunction with the [no-shared](#no-shared)
option.
-### no-acvp_tests
+### enable-acvp-tests
-Do not build support for Automated Cryptographic Validation Protocol (ACVP)
+Build support for Automated Cryptographic Validation Protocol (ACVP)
tests.
This is required for FIPS validation purposes. Certain ACVP tests require
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-bulk
+
+Build only some minimal set of features.
+This is a developer option used internally for CI build tests of the project.
+
+### no-cached-fetch
+
+Never cache algorithms when they are fetched from a provider. Normally, a
+provider indicates if the algorithms it supplies can be cached or not. Using
+this option will reduce run-time memory usage but it also introduces a
+significant performance penalty. This option is primarily designed to help
+with detecting incorrect reference counting.
+
### no-capieng
Don't build the CAPI engine.
This is a developer option and may not work on all platforms. The following
external test suites are currently supported:
- - BoringSSL test suite
+ - GOST engine test suite
- Python PYCA/Cryptography test suite
- krb5 test suite
-See the file [test/README.external](test/README.external) for further details.
+See the file [test/README-external.md](test/README-external.md)
+for further details.
### no-filenames
Don't compile in filename and line number information (e.g. for errors and
memory allocation).
-### no-fips
+### enable-fips
+
+Build (and install) the FIPS provider
-Don't compile the FIPS provider
+### no-fips-securitychecks
+
+Don't perform FIPS module run-time checks related to enforcement of security
+parameters such as minimum security strength of keys.
### enable-fuzz-libfuzzer, enable-fuzz-afl
### 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
+this by default. However, if on a platform where this is not the case then this
will usually require additional system-dependent options!
See [Notes on multi-threading](#notes-on-multi-threading) below.
If your system isn't listed, you will have to create a configuration
file named `Configurations/{{ something }}.conf` and add the correct
configuration for your system. See the available configs as examples
-and read [Configurations/README](Configurations/README)
-and [Configurations/README.design](Configurations/README.design)
+and read [Configurations/README.md](Configurations/README.md) and
+[Configurations/README-design.md](Configurations/README-design.md)
for more information.
The generic configurations `cc` or `gcc` should usually work on 32 bit
**Warning:** you MUST run the tests from an unprivileged account (or disable
your privileges temporarily if your platform allows it).
-See the file [test/README.md](test/README.md) for further details.
+See [test/README.md](test/README.md) for further details how run tests.
+
+See [test/README-dev.md](test/README-dev.md) for guidelines on adding tests.
Install OpenSSL
---------------
### OpenVMS
-'arch' is replaced with the architecture name, `Alpha` or `ia64`,
+'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:
Use a different build file name than the platform default
("Makefile" on Unix-like platforms, "makefile" on native Windows,
"descrip.mms" on OpenVMS). This requires that there is a
- corresponding build file template. See Configurations/README
+ corresponding build file template.
+ See [Configurations/README.md](Configurations/README.md)
for further information.
CC
templates for those platforms. The database is comprised of
".conf" files in the Configurations directory. The build
file templates reside there as well as ".tmpl" files. See the
- file Configurations/README for further information about the
- format of ".conf" files as well as information on the ".tmpl"
- files.
+ file [Configurations/README.md](Configurations/README.md)
+ for further information about the format of ".conf" files
+ as well as information on the ".tmpl" files.
In addition to the standard ".conf" and ".tmpl" files, it is
- possible to create your own ".conf" and ".tmpl" files and store
- them locally, outside the OpenSSL source tree. This environment
- variable can be set to the directory where these files are held
- and will be considered by Configure before it looks in the
- standard directories.
+ possible to create your own ".conf" and ".tmpl" files and
+ store them locally, outside the OpenSSL source tree.
+ This environment variable can be set to the directory where
+ these files are held and will be considered by Configure
+ before it looks in the standard directories.
PERL
The name of the Perl executable to use when building OpenSSL.
Only install the OpenSSL man pages (Unix only).
install_html_docs
- Only install the OpenSSL html documentation.
+ Only install the OpenSSL HTML documentation.
+
+ install_fips
+ Install the FIPS provider module configuration file.
list-tests
Prints a list of all the self test names.
$ ./Configure
Operating system: x86-whatever-minix
- This system (minix) is not supported. See file INSTALL for details.
+ This system (minix) is not supported. See file INSTALL.md 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`
possibly after some adjustment.
The `Configurations/` directory contains a lot of examples of such targets.
-The main configuration file is [10-main.conf][], which contains all targets that
+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
a Perl list `my %targets = ( ... )`.
The directory contains two README files, which explain the general syntax and
design of the configuration files.
- - [Configurations/README](Configurations/README)
- - [Configurations/README.design](Configurations/README.design)
+ - [Configurations/README.md](Configurations/README.md)
+ - [Configurations/README-design.md](Configurations/README-design.md)
-If you need further help, try to search the [openssl-users][] mailing list
-or the [GitHub Issues][] for existing solutions. If you don't find anything,
-you can [raise an issue][] to ask a question yourself.
+If you need further help, try to search the [openssl-users] mailing list
+or the [GitHub Issues] for existing solutions. If you don't find anything,
+you can [raise an issue] to ask a question yourself.
-More about our support resources can be found in the [SUPPORT][] file.
+More about our support resources can be found in the [SUPPORT] file.
### Configuration Errors
read the error message carefully and try to figure out whether you made
a mistake (e.g., by providing a wrong option), or whether the script is
working incorrectly. If you think you encountered a bug, please
-[raise an issue][] on GitHub to file a bug report.
+[raise an issue] on GitHub to file a bug report.
Along with a short description of the bug, please provide the complete
configure command line and the relevant output including the error message.
$ mms clean ! (or mmk) OpenVMS
$ nmake clean # Windows
-Assembler error messages can sometimes be sidestepped by using the
-`no-asm` configuration option.
+Assembler error messages can sometimes be sidestepped by using the `no-asm`
+configuration option. See also [notes](#notes-on-assembler-modules-compilation).
Compiling parts of OpenSSL with gcc and others with the system compiler will
result in unresolved symbols on some systems.
-If you are still having problems, try to search the [openssl-users][] mailing
-list or the [GitHub Issues][] for existing solutions. If you think you
-encountered an OpenSSL bug, please [raise an issue][] to file a bug report.
+If you are still having problems, try to search the [openssl-users] mailing
+list or the [GitHub Issues] for existing solutions. If you think you
+encountered an OpenSSL bug, please [raise an issue] to file a bug report.
Please take the time to review the existing issues first; maybe the bug was
already reported or has already been fixed.
You may want increased verbosity, that can be accomplished as described in
section [Test Failures of test/README.md](test/README.md#test-failures).
-You may want to selectively specify which test(s) to perform. This can be done
-sing the `make` variable `TESTS` as described in section [Running Selected Tests
-of test/README.md](test/README.md#running-selected-tests).
+You may also want to selectively specify which test(s) to perform. This can be
+done using the `make` variable `TESTS` as described in section [Running
+Selected Tests of test/README.md](test/README.md#running-selected-tests).
If you find a problem with OpenSSL itself, try removing any
compiler optimization flags from the `CFLAGS` line in the Makefile and
supported. If your platform does not provide pthreads or Windows threads then
you should use `Configure` with the `no-threads` option.
+For pthreads, all locks are non-recursive. In addition, in a debug build,
+the mutex attribute `PTHREAD_MUTEX_ERRORCHECK` is used. If this is not
+available on your platform, you might have to add
+`-DOPENSSL_NO_MUTEX_ERRORCHECK` to your `Configure` invocation.
+(On Linux `PTHREAD_MUTEX_ERRORCHECK` is an enum value, so a built-in
+ifdef test cannot be used.)
+
Notes on shared libraries
-------------------------
The seeding method can be configured using the `--with-rand-seed` option,
which can be used to specify a comma separated list of seed methods.
-However in most cases OpenSSL will choose a suitable default method,
+However, in most cases OpenSSL will choose a suitable default method,
so it is not necessary to explicitly provide this option. Note also
-that not all methods are available on all platforms.
+that not all methods are available on all platforms. The FIPS provider will
+silently ignore seed sources that were not validated.
I) On operating systems which provide a suitable randomness source (in
form of a system call or system device), OpenSSL will use the optimal
the CSPRNG manually. Please check out the manual pages for `RAND_add()`,
`RAND_bytes()`, `RAND_egd()`, and the FAQ for more information.
+Notes on assembler modules compilation
+--------------------------------------
+
+Compilation of some code paths in assembler modules might depend on whether the
+current assembler version supports certain ISA extensions or not. Code paths
+that use the AES-NI, PCLMULQDQ, SSSE3, and SHA extensions are always assembled.
+Apart from that, the minimum requirements for the assembler versions are shown
+in the table below:
+
+| ISA extension | GNU as | nasm | llvm |
+|---------------|--------|--------|---------|
+| AVX | 2.19 | 2.09 | 3.0 |
+| AVX2 | 2.22 | 2.10 | 3.1 |
+| ADCX/ADOX | 2.23 | 2.10 | 3.3 |
+| AVX512 | 2.25 | 2.11.8 | 3.6 (*) |
+| AVX512IFMA | 2.26 | 2.11.8 | 6.0 (*) |
+| VAES | 2.30 | 2.13.3 | 6.0 (*) |
+
+---
+
+(*) Even though AVX512 support was implemented in llvm 3.6, prior to version 7.0
+an explicit -march flag was apparently required to compile assembly modules. But
+then the compiler generates processor-specific code, which in turn contradicts
+the idea of performing dispatch at run-time, which is facilitated by the special
+variable `OPENSSL_ia32cap`. For versions older than 7.0, it is possible to work
+around the problem by forcing the build procedure to use the following script:
+
+ #!/bin/sh
+ exec clang -no-integrated-as "$@"
+
+instead of the real clang. In which case it doesn't matter what clang version
+is used, as it is the version of the GNU assembler that will be checked.
+
+---
+
<!-- Links -->
[openssl-users]:
projects / openssl.git / blobdiff