Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 186 insertions, 0 deletions

diff --git a/security/nss/readme.md b/security/nss/readme.md
new file mode 100644
index 0000000000..27f4c7fd06
--- /dev/null
+++ b/security/nss/readme.md
@@ -0,0 +1,186 @@
+# Network Security Services
+
+Network Security Services (NSS) is a set of libraries designed to support
+cross-platform development of security-enabled client and server
+applications. NSS supports TLS 1.2, TLS 1.3, PKCS #5, PKCS#7,
+PKCS #11, PKCS #12, S/MIME, X.509 v3 certificates, and other security
+standards.
+
+## Getting started
+
+In order to get started create a new directory on that you will be uses as your
+local work area, and check out NSS and NSPR. (Note that there's no git mirror of
+NSPR and you require mercurial to get the latest NSPR source.)
+
+    git clone https://github.com/nss-dev/nss.git
+    hg clone https://hg.mozilla.org/projects/nspr
+
+NSS can also be cloned with mercurial
+
+    hg clone https://hg.mozilla.org/projects/nss
+
+## Building NSS
+
+**This build system is under development. It does not yet support all the
+features or platforms that NSS supports. To build on anything other than Mac or
+Linux please use the legacy build system as described below.**
+
+Build requirements:
+
+* [gyp](https://gyp.gsrc.io/)
+* [ninja](https://ninja-build.org/)
+
+After changing into the NSS directory a typical build is done as follows
+
+    ./build.sh
+
+Once the build is done the build output is found in the directory
+`../dist/Debug` for debug builds and `../dist/Release` for opt builds.
+Exported header files can be found in the `include` directory, library files in
+directory `lib`, and tools in directory `bin`. In order to run the tools, set
+your system environment to use the libraries of your build from the "lib"
+directory, e.g., using the `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH`.
+
+See [help.txt](https://hg.mozilla.org/projects/nss/raw-file/tip/help.txt) for
+more information on using build.sh.
+
+## Building NSS (legacy build system)
+
+After changing into the NSS directory a typical build of 32-bit NSS is done as
+follows:
+
+    make nss_build_all
+
+The following environment variables might be useful:
+
+* `BUILD_OPT=1` to get an optimised build
+
+* `USE_64=1` to get a 64-bit build (recommended)
+
+The complete list of environment variables can be found
+[here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Reference/NSS_environment_variables).
+
+To clean the build directory run:
+
+    make nss_clean_all
+
+## Tests
+
+### Setup
+
+Make sure that the address `$HOST.$DOMSUF` on your computer is available. This
+is necessary because NSS tests generate certificates and establish TLS
+connections, which requires a fully qualified domain name.
+You can test this by
+calling `ping $HOST.$DOMSUF`. If this is working, you're all set.  If it's not,
+set or export:
+
+    HOST=nss
+    DOMSUF=local
+
+Note that you might have to add `nss.local` to `/etc/hosts` if it's not
+there. The entry should look something like `127.0.0.1 nss.local nss`.
+
+### Running tests
+
+**Runnning all tests will take a while!**
+
+    cd tests
+    ./all.sh
+
+Make sure that all environment variables set for the build are set while running
+the tests as well.  Test results are published in the folder
+`../../test_results/`.
+
+Individual tests can be run with the `NSS_TESTS` environment variable,
+e.g. `NSS_TESTS=ssl_gtests ./all.sh` or by changing into the according directory
+and running the bash script there `cd ssl_gtests && ./ssl_gtests.sh`.  The
+following tests are available:
+
+    cipher lowhash libpkix cert dbtests tools fips sdr crmf smime ssl ocsp merge pkits chains ec gtests ssl_gtests bogo policy
+
+To make tests run faster it's recommended to set `NSS_CYCLES=standard` to run
+only the standard cycle.
+
+## Releases
+
+NSS releases can be found at [Mozilla's download
+server](https://ftp.mozilla.org/pub/security/nss/releases/). Because NSS depends
+on the base library NSPR you should download the archive that combines both NSS
+and NSPR.
+
+## Contributing
+
+[Bugzilla](https://bugzilla.mozilla.org/) is used to track NSS development and
+bugs. File new bugs in the NSS product.
+
+A list with good first bugs to start with are [listed
+here](https://bugzilla.mozilla.org/buglist.cgi?keywords=good-first-bug%2C%20&keywords_type=allwords&list_id=13238861&resolution=---&query_format=advanced&product=NSS).
+
+### NSS Folder Structure
+
+The nss directory contains the following important subdirectories:
+
+- `coreconf` contains the build logic.
+
+- `lib` contains all library code that is used to create the runtime libraries.
+
+- `cmd` contains a set of various tool programs that are built with NSS. Several
+  tools are general purpose and can be used to inspect and manipulate the
+  storage files that software using the NSS library creates and modifies. Other
+  tools are only used for testing purposes.
+
+- `test` and `gtests` contain the NSS test suite. While `test` contains shell
+  scripts to drive test programs in `cmd`, `gtests` holds a set of
+  [gtests](https://github.com/google/googletest).
+
+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.