Source code
Revision control
Copy as Markdown
Other Tools
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build
NSS uses GYP + Ninja as its primary build system, driven by `build.sh` (or the `mach` wrapper):
```sh
./build.sh # debug build → ../dist/Debug/
./build.sh -o # optimized build → ../dist/Release/
./build.sh -c # clean + build
./mach build # equivalent wrapper
```
Common flags:
- `--asan` / `--msan` / `--ubsan` — sanitizer builds
- `--fuzz` / `--fuzz=tls` — fuzzing builds
- `--enable-fips` — FIPS-140 mode
- `--disable-tests` — skip building test binaries
- `-t <arch>` — cross-compile (x64, ia32, aarch64, …)
Output lands in `out/[Debug|Release]/` (build artifacts) and `../dist/[Debug|Release]/` (headers, libs, binaries).
A legacy Make-based build (`make nss_build_all`) also exists via `coreconf/` but GYP is preferred for new work.
## Tests
```sh
cd tests && ./all.sh # full test suite
NSS_TESTS=ssl_gtests ./all.sh # single suite
NSS_TESTS=ssl_gtests NSS_CYCLES=standard ./all.sh # skip stress cycles
./mach tests ssl_gtests # mach wrapper
```
Available suites: `cipher`, `ssl`, `ssl_gtests`, `gtests`, `cert`, `smime`, `fips`, `ec`, `bogo`, `interop`, `policy`, and others. See `tests/all.sh` for the full list.
GTest binaries require a certificate database. Helper scripts create one and then invoke the binary:
```sh
# SSL gtests
./tests/ssl_gtests/ssl_gtest_db.sh ./ssl_gtest_certdb ../dist/Debug/bin/certutil
../dist/Debug/bin/ssl_gtests -d ./ssl_gtest_certdb
# Other gtests
./tests/gtests/gtest_db.sh ./gtest_certdb ../dist/Debug/bin/certutil
../dist/Debug/bin/pkcs11testmodule_gtest -d ./gtest_certdb # example
```
## Code formatting and linting
```sh
./mach clang-format # format changed files
./mach clang-format path/to/file.c # format specific file
./mach clang-tidy # static analysis
./mach clang-tidy --fix # auto-fix where possible
```
## Architecture
NSS is a layered cryptographic library. The dependency flows roughly bottom-up:
**`lib/freebl/`** — standalone cryptographic primitives (ciphers, hashes, RNG, EC). No NSS dependencies; can be linked independently. Hardware acceleration (AES-NI, CLMUL, AVX, etc.) is selected at this layer.
**`lib/softoken/`** — software PKCS#11 token built on freebl. This is the default cryptographic "device" NSS uses. Legacy database support is in `lib/softoken/legacydb/`.
**`lib/pk11wrap/`** — PKCS#11 abstraction layer. All cryptographic operations above freebl go through here, allowing hardware tokens and HSMs to be swapped in transparently.
**`lib/certdb/` + `lib/certhigh/`** — certificate database (SQLite via `lib/sqlite/`, or legacy DBM via `lib/dbm/`) and high-level certificate operations.
**`lib/cryptohi/`** — high-level signing, verification, and hashing APIs layered over pk11wrap.
**`lib/ssl/`** — TLS 1.2, TLS 1.3, and DTLS implementation. Depends on cryptohi, certdb, and pk11wrap.
**`lib/nss/`** — top-level initialization and the public NSS API surface.
**`lib/smime/`, `lib/pkcs7/`, `lib/pkcs12/`** — higher-level protocol/format support built on the certificate and crypto layers.
**`lib/mozpkix/`** — Mozilla's standalone C++ PKIX certificate chain validation library (also used by Firefox directly).
**`lib/ckfw/`** — Cryptoki Framework: infrastructure for building PKCS#11 modules.
The `cmd/` directory contains command-line tools (`certutil`, `modutil`, `bltest`, etc.) that exercise the public API and are also used by the test suite.
GTests live in `gtests/` (unit tests per module) and `tests/ssl_gtests/` (SSL integration gtests). Shell-based integration tests are in `tests/`.
## mach
`./mach` is a Python 3 script that wraps common tasks:
```sh
./mach commands # list all available commands
./mach coverage ssl_gtests # source coverage report for a suite
./mach fuzz-coverage # coverage for fuzzing targets
```
## Bugzilla and Phabricator
NSS tracks bugs in Bugzilla and uses Phabricator for code review. The `moz` MCP server gives direct access to both. The server is defined in `.mcp.json`; to enable it, create `.claude/settings.local.json` if it doesn't exist:
```json
{
"enableAllProjectMcpServers": true,
"enabledMcpjsonServers": ["moz"]
}
```
- `@moz:phabricator://revision/D{revision_id}` — retrieve a Phabricator revision and its review comments
To find the Phabricator revision ID for a local commit, look for a `Differential Revision: https://phabricator.services.mozilla.com/D<N>` line in the commit message:
```sh
git log -v -l 10 # git
hg log -l 10 # mercurial
```
Never submit or update a Phabricator revision without explicit user approval.
## NSPR
NSS depends on NSPR (Netscape Portable Runtime) for OS abstraction. By default the build looks for it at `../nspr/`. Alternatives:
- `--system-nspr` — use the system-installed NSPR
- `--with-nspr=<path>` — specify a path explicitly