security/nss/readme.md

   1 # Network Security Services
   2
   3 Network Security Services (NSS) is a set of libraries designed to support
   4 cross-platform development of security-enabled client and server
   5 applications. NSS supports TLS 1.2, TLS 1.3, PKCS #5, PKCS#7,
   6 PKCS #11, PKCS #12, S/MIME, X.509 v3 certificates, and other security
   7 standards.
   8
   9 ## Getting started
  10
  11 In order to get started create a new directory on that you will be uses as your
  12 local work area, and check out NSS and NSPR. (Note that there's no git mirror of
  13 NSPR 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
  18 NSS 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
  25 features or platforms that NSS supports. To build on anything other than Mac or
  26 Linux please use the legacy build system as described below.**
  27
  28 Build requirements:
  29
  30 * [gyp](https://gyp.gsrc.io/)
  31 * [ninja](https://ninja-build.org/)
  32
  33 After changing into the NSS directory a typical build is done as follows
  34
  35     ./build.sh
  36
  37 Once the build is done the build output is found in the directory
  38 `../dist/Debug` for debug builds and `../dist/Release` for opt builds.
  39 Exported header files can be found in the `include` directory, library files in
  40 directory `lib`, and tools in directory `bin`. In order to run the tools, set
  41 your system environment to use the libraries of your build from the "lib"
  42 directory, e.g., using the `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH`.
  43
  44 See [help.txt](https://hg.mozilla.org/projects/nss/raw-file/tip/help.txt) for
  45 more information on using build.sh.
  46
  47 ## Building NSS (legacy build system)
  48
  49 After changing into the NSS directory a typical build of 32-bit NSS is done as
  50 follows:
  51
  52     make nss_build_all
  53
  54 The 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
  60 The 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
  63 To clean the build directory run:
  64
  65     make nss_clean_all
  66
  67 ## Tests
  68
  69 ### Setup
  70
  71 Make sure that the address `$HOST.$DOMSUF` on your computer is available. This
  72 is necessary because NSS tests generate certificates and establish TLS
  73 connections, which requires a fully qualified domain name.
  74 You can test this by
  75 calling `ping $HOST.$DOMSUF`. If this is working, you're all set.  If it's not,
  76 set or export:
  77
  78     HOST=nss
  79     DOMSUF=local
  80
  81 Note that you might have to add `nss.local` to `/etc/hosts` if it's not
  82 there. 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
  91 Make sure that all environment variables set for the build are set while running
  92 the tests as well.  Test results are published in the folder
  93 `../../test_results/`.
  94
  95 Individual tests can be run with the `NSS_TESTS` environment variable,
  96 e.g. `NSS_TESTS=ssl_gtests ./all.sh` or by changing into the according directory
  97 and running the bash script there `cd ssl_gtests && ./ssl_gtests.sh`.  The
  98 following 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
 102 To make tests run faster it's recommended to set `NSS_CYCLES=standard` to run
 103 only the standard cycle.
 104
 105 ## Releases
 106
 107 NSS releases can be found at [Mozilla's download
 108 server](https://ftp.mozilla.org/pub/security/nss/releases/). Because NSS depends
 109 on the base library NSPR you should download the archive that combines both NSS
 110 and NSPR.
 111
 112 ## Contributing
 113
 114 [Bugzilla](https://bugzilla.mozilla.org/) is used to track NSS development and
 115 bugs. File new bugs in the NSS product.
 116
 117 A list with good first bugs to start with are [listed
 118 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).
 119
 120 ### NSS Folder Structure
 121
 122 The 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
 137 A more comprehensible overview of the NSS folder structure and API guidelines
 138 can 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
 143 NSS supports build configurations for FIPS-140 compliance, and alternative build
 144 configurations that disable functionality specific to FIPS-140 compliance.
 145
 146 This section documents the environment variables and build parameters that
 147 control these configurations.
 148
 149 ### Build FIPS startup tests
 150
 151 The C macro NSS_NO_INIT_SUPPORT controls the FIPS startup self tests.
 152 If NSS_NO_INIT_SUPPORT is defined, the startup tests are disabled.
 153
 154 The legacy build system (make) by default disables these tests.
 155 To enable these tests, set environment variable NSS_FORCE_FIPS=1 at build time.
 156
 157 The gyp build system by default disables these tests.
 158 To enable these tests, pass parameter --enable-fips to build.sh.
 159
 160 ### Building either FIPS compliant or alternative compliant code
 161
 162 The C macro NSS_FIPS_DISABLED can be used to disable some FIPS compliant code
 163 and enable alternative implementations.
 164
 165 The legacy build system (make) never defines NSS_FIPS_DISABLED and always uses
 166 the FIPS compliant code.
 167
 168 The gyp build system by default defines NSS_FIPS_DISABLED.
 169 To use the FIPS compliant code, pass parameter --enable-fips to build.sh.
 170
 171 ### Test execution
 172
 173 The NSS test suite may contain tests that are included, excluded, or are
 174 different based on the FIPS build configuration. To execute the correct tests,
 175 it's necessary to determine which build configuration was used.
 176
 177 The legacy build system (make) uses environment variables to control all
 178 aspects of the build configuration, including FIPS build configuration.
 179
 180 Because the gyp build system doesn't use environment variables to control the
 181 build configuration, the NSS tests cannot rely on environment variables to
 182 determine the build configuration.
 183
 184 A helper binary named nss-build-flags is produced as part of the NSS build,
 185 which prints the C macro symbols that were defined at build time, and which are
 186 relevant to test execution.