Bug 1409516, NSS Tests detect FIPS buildconfiguration using certutil --build-flags. gyp builds with --enable-fips enable init tests. Enable cert_rsa_exponent test. Add Linux64 FIPS gyp build to taskcluster/CI. r=franziskus

1 files changed, 47 insertions, 0 deletions

diff --git a/readme.md b/readme.md
index 41e8b4b16..17b99e805 100644
--- a/readme.md
+++ b/readme.md
@@ -137,3 +137,50 @@ The nss directory contains the following important subdirectories:
 A more comprehensible overview of the NSS folder structure and API guidelines
 can be found
 [here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/NSS_API_Guidelines).
+
+## Build mechanisms related to FIPS compliance
+
+NSS supports build configurations for FIPS-140 compliance, and alternative build
+configurations that disable functionality specific to FIPS-140 compliance.
+
+This section documents the environment variables and build parameters that
+control these configurations.
+
+### Build FIPS startup tests
+
+The C macro NSS_NO_INIT_SUPPORT controls the FIPS startup self tests.
+If NSS_NO_INIT_SUPPORT is defined, the startup tests are disabled.
+
+The legacy build system (make) by default disables these tests.
+To enable these tests, set environment variable NSS_FORCE_FIPS=1 at build time.
+
+The gyp build system by default disables these tests.
+To enable these tests, pass parameter --enable-fips to build.sh.
+
+### Building either FIPS compliant or alternative compliant code
+
+The C macro NSS_FIPS_DISABLED can be used to disable some FIPS compliant code
+and enable alternative implementations.
+
+The legacy build system (make) never defines NSS_FIPS_DISABLED and always uses
+the FIPS compliant code.
+
+The gyp build system by default defines NSS_FIPS_DISABLED.
+To use the FIPS compliant code, pass parameter --enable-fips to build.sh.
+
+### Test execution
+
+The NSS test suite may contain tests that are included, excluded, or are
+different based on the FIPS build configuration. To execute the correct tests,
+it's necessary to determine which build configuration was used.
+
+The legacy build system (make) uses environment variables to control all
+aspects of the build configuration, including FIPS build configuration.
+
+Because the gyp build system doesn't use environment variables to control the
+build configuration, the NSS tests cannot rely on environment variables to
+determine the build configuration.
+
+A helper binary named nss-build-flags is produced as part of the NSS build,
+which prints the C macro symbols that were defined at build time, and which are
+relevant to test execution.