NSS readme

readme.md

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 SSL v3-TLS 1.2 (experimental 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/nspr

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
• ninja

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/*.OBJ, where * will be a name dynamically derived from your system's architecture. 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.

---

Usage: build.sh [-hcgv] [-j <n>] [--test] [--fuzz] [--scan-build[=output]]
                [-m32] [--opt|-o]

-h            display this help and exit
-c            clean before build
-g            force a rebuild of gyp (and NSPR, because why not)
-j <n>        run at most <n> concurrent jobs
-v            verbose build
-m32          do a 32-bit build on a 64-bit system
--test        ignore map files and export everything we have
--fuzz        enable fuzzing mode. this always enables test builds
--scan-build  run the build with scan-build (scan-build has to be in the path)
              --scan-build=/out/path sets the output path for scan-build
--opt|-o      do an opt build

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)
• NSS_ENABLE_TLS_1_3=1 to enable TLS 1.3 support

The complete list of environment variables can be found here.

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. If you get name resolution errors, try to disable IPv6 on the loopback device, i.e. comment the lines starting with ::1 in your /etc/hosts .

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

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. Because NSS depends on the base library NSPR you should download the archive that combines both NSS and NSPR.

Contributing

Bugzilla 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.

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.

A more comprehensible overview of the NSS folder structure and API guidelines can be found here.

A few typos here, but this looks like a reasonable start.

"Once the build is done you the build output "

Please put "(recommended)" after USE_64=1.

Maybe suggest that people ping $HOST.$DOMSUF. How does NSS decide what the values are if they aren't set? hostname and hostname -d ? In which case I would recommend that the test command is ping ${HOST:-$(hostname)}.${DOMSUF:-$(hostname -d)}.

Runnning all tests will take a while!

Is there a command to run individual tests?

Make sure that the address $HOST.$DOMSUF on your computer is available

Would be great to quickly mention why that's necessary.

HOST=localhost
DOMSUF=localdomain

fwiw, I had to add localhost.localdomain to my /etc/hosts on OSX. Might be worth mentioning.

If you get name resolution errors, try to disable IPv6 on the loopback device.

I didn't really know how to do this.

Issues/suggestions from running through this readme today:

Is echo $HOST.$DOMSUF the best way to test if it's set on the machine?
I also had to add localhost.localdomain to the 127.0.0.1 localhost line in /etc/hosts (Debian 8 stable).

And issues with testing:
Explicit reminder to use USE_64=1 if you built with 64-bit libraries would be helpful. (Especially if you change the wording to recommend that env variable as suggested above.)

I couldn't finish running tests because of a password prompt (tried entering empty password and various passwords along the lines of "password"):

ssl.sh: running SSL3_RSA_WITH_RC4_128_MD5 ----------------------------
tstclnt -p 8443 -h localhost.localdomain -c c -V ssl3:ssl3  \
        -f -d ../client  -w nss < /home/user/dev/nss/tests/ssl/sslreq.dat
Enter Password or Pin for "NSS FIPS 140-2 Certificate DB":

Great start! A few thoughts:

The nss directory contains the following important subdirectories:

This seems a little too much information for someone just trying to build NSS the first time. Can we maybe move this down before or after the testing section?

However, all these tools are examples of how to write software that makes use of the NSS library.

So, actually, these definitely aren't great examples :) I wonder if we can somehow express that the code is horrible and most(?) of the commands are used for testing, but if you want to take a look, go and do it.

Once the build is done the build output is found in the directory ../dist/*.OBJ

I think this would helpful to share between the description of the new and old system. Building with GYP/Ninja currently doesn't tell you where to find things.

Make sure that the address $HOST.$DOMSUF on your computer is available

We don't actually need this for every test suite. ssl_gtests and bogo for example should run fine without it. Maybe we could move this down so that instructions for how to run newer suites are higher up, but then we might have to find out which test suites actually requires HOST+DOMSUF.

If you get name resolution errors, try to disable IPv6 on the loopback device, i.e. comment the lines starting with ::1 in your /etc/hosts .

This probably won't be an issue. As long as you put the name against 127.0.0.1, it should work. Maybe we should recommend a different name (e.g., nsstest.local) to avoid that problem.

NSS_TESTS=ssl_gtests ./all.sh

Note that you can run individual tests by changing to the subdirectory. I find that easier to explain (and type) than this version. The only difference is that you can't test multiple things at once.