1# Network Security Services 2 3Network Security Services (NSS) is a set of libraries designed to support 4cross-platform development of security-enabled client and server 5applications. NSS supports TLS 1.2, TLS 1.3, PKCS #5, PKCS#7, 6PKCS #11, PKCS #12, S/MIME, X.509 v3 certificates, and other security 7standards. 8 9## Getting started 10 11In order to get started create a new directory on that you will be uses as your 12local work area, and check out NSS and NSPR. (Note that there's no git mirror of 13NSPR and you require mercurial to get the latest NSPR source.) 14 15 git clone https://github.com/nss-dev/nss.git 16 hg clone https://hg.mozilla.org/projects/nspr 17 18NSS can also be cloned with mercurial 19 20 hg clone https://hg.mozilla.org/projects/nss 21 22## Building NSS 23 24**This build system is under development. It does not yet support all the 25features or platforms that NSS supports. To build on anything other than Mac or 26Linux please use the legacy build system as described below.** 27 28Build requirements: 29 30* [gyp](https://gyp.gsrc.io/) 31* [ninja](https://ninja-build.org/) 32 33After changing into the NSS directory a typical build is done as follows 34 35 ./build.sh 36 37Once the build is done the build output is found in the directory 38`../dist/Debug` for debug builds and `../dist/Release` for opt builds. 39Exported header files can be found in the `include` directory, library files in 40directory `lib`, and tools in directory `bin`. In order to run the tools, set 41your system environment to use the libraries of your build from the "lib" 42directory, e.g., using the `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH`. 43 44See [help.txt](https://hg.mozilla.org/projects/nss/raw-file/tip/help.txt) for 45more information on using build.sh. 46 47## Building NSS (legacy build system) 48 49After changing into the NSS directory a typical build of 32-bit NSS is done as 50follows: 51 52 make nss_build_all 53 54The following environment variables might be useful: 55 56* `BUILD_OPT=1` to get an optimised build 57 58* `USE_64=1` to get a 64-bit build (recommended) 59 60The complete list of environment variables can be found 61[here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Reference/NSS_environment_variables). 62 63To clean the build directory run: 64 65 make nss_clean_all 66 67## Tests 68 69### Setup 70 71Make sure that the address `$HOST.$DOMSUF` on your computer is available. This 72is necessary because NSS tests generate certificates and establish TLS 73connections, which requires a fully qualified domain name. 74You can test this by 75calling `ping $HOST.$DOMSUF`. If this is working, you're all set. If it's not, 76set or export: 77 78 HOST=nss 79 DOMSUF=local 80 81Note that you might have to add `nss.local` to `/etc/hosts` if it's not 82there. The entry should look something like `127.0.0.1 nss.local nss`. 83 84### Running tests 85 86**Runnning all tests will take a while!** 87 88 cd tests 89 ./all.sh 90 91Make sure that all environment variables set for the build are set while running 92the tests as well. Test results are published in the folder 93`../../test_results/`. 94 95Individual tests can be run with the `NSS_TESTS` environment variable, 96e.g. `NSS_TESTS=ssl_gtests ./all.sh` or by changing into the according directory 97and running the bash script there `cd ssl_gtests && ./ssl_gtests.sh`. The 98following tests are available: 99 100 cipher lowhash libpkix cert dbtests tools fips sdr crmf smime ssl ocsp merge pkits chains ec gtests ssl_gtests bogo policy 101 102To make tests run faster it's recommended to set `NSS_CYCLES=standard` to run 103only the standard cycle. 104 105## Releases 106 107NSS releases can be found at [Mozilla's download 108server](https://ftp.mozilla.org/pub/security/nss/releases/). Because NSS depends 109on the base library NSPR you should download the archive that combines both NSS 110and NSPR. 111 112## Contributing 113 114[Bugzilla](https://bugzilla.mozilla.org/) is used to track NSS development and 115bugs. File new bugs in the NSS product. 116 117A list with good first bugs to start with are [listed 118here](https://bugzilla.mozilla.org/buglist.cgi?keywords=good-first-bug%2C%20&keywords_type=allwords&list_id=13238861&resolution=---&query_format=advanced&product=NSS). 119 120### NSS Folder Structure 121 122The nss directory contains the following important subdirectories: 123 124- `coreconf` contains the build logic. 125 126- `lib` contains all library code that is used to create the runtime libraries. 127 128- `cmd` contains a set of various tool programs that are built with NSS. Several 129 tools are general purpose and can be used to inspect and manipulate the 130 storage files that software using the NSS library creates and modifies. Other 131 tools are only used for testing purposes. 132 133- `test` and `gtests` contain the NSS test suite. While `test` contains shell 134 scripts to drive test programs in `cmd`, `gtests` holds a set of 135 [gtests](https://github.com/google/googletest). 136 137A more comprehensible overview of the NSS folder structure and API guidelines 138can be found 139[here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/NSS_API_Guidelines). 140 141## Build mechanisms related to FIPS compliance 142 143NSS supports build configurations for FIPS-140 compliance, and alternative build 144configurations that disable functionality specific to FIPS-140 compliance. 145 146This section documents the environment variables and build parameters that 147control these configurations. 148 149### Build FIPS startup tests 150 151The C macro NSS_NO_INIT_SUPPORT controls the FIPS startup self tests. 152If NSS_NO_INIT_SUPPORT is defined, the startup tests are disabled. 153 154The legacy build system (make) by default disables these tests. 155To enable these tests, set environment variable NSS_FORCE_FIPS=1 at build time. 156 157The gyp build system by default disables these tests. 158To enable these tests, pass parameter --enable-fips to build.sh. 159 160### Building either FIPS compliant or alternative compliant code 161 162The C macro NSS_FIPS_DISABLED can be used to disable some FIPS compliant code 163and enable alternative implementations. 164 165The legacy build system (make) never defines NSS_FIPS_DISABLED and always uses 166the FIPS compliant code. 167 168The gyp build system by default defines NSS_FIPS_DISABLED. 169To use the FIPS compliant code, pass parameter --enable-fips to build.sh. 170 171### Test execution 172 173The NSS test suite may contain tests that are included, excluded, or are 174different based on the FIPS build configuration. To execute the correct tests, 175it's necessary to determine which build configuration was used. 176 177The legacy build system (make) uses environment variables to control all 178aspects of the build configuration, including FIPS build configuration. 179 180Because the gyp build system doesn't use environment variables to control the 181build configuration, the NSS tests cannot rely on environment variables to 182determine the build configuration. 183 184A helper binary named nss-build-flags is produced as part of the NSS build, 185which prints the C macro symbols that were defined at build time, and which are 186relevant to test execution. 187