Network Security Services (NSS)

Network Security Services (NSS) is a set of libraries designed to support cross-platform development of security-enabled client and server applications.

By integrating NSS, applications can support various security standards, including:

• SSL v3
• TLS
• PKCS #5, PKCS #7, PKCS #11, and PKCS #12
• S/MIME
• X.509 v3 certificates

NSS is licensed under the Mozilla Public License v2 (MPLv2).

Trust attributes are modified using the -t argument. There are three categories for each certificate, expressed in the order: SSL, email, object signing.

For each category, you can use one of the following codes:

• p: Valid peer
• P: Trusted peer (implies p)
• c: Valid CA
• C: Trusted CA (implies c)
• T: Trusted CA for client authentication (SSL server only)

Attributes are comma-separated and enclosed in quotes. For example, -t "TC,C,T" sets attributes for all three categories.

Note: The u flag (indicating a private key is associated) is dynamic and cannot be set via certutil.

When using the -d argument, you can specify the directory containing the database files. You can also specify the database type using a prefix:

• sql:: Requests the newer SQLite-based database (cert9.db, key4.db, etc.).
• dbm:: Requests the legacy database (cert8.db, key3.db, etc.).

If no prefix is provided, certutil uses the NSS_DEFAULT_DB_TYPE environment variable. If that is not set, sql: is the default.

# Example using the SQLite database prefix
certutil -L -d sql:/path/to/database

NSS uses opaque data structures to allow the library to modify the size and format of internal data without breaking binary compatibility for existing applications.

To implement or interact with an opaque structure, the definition must be hidden in a private header, while only the typedef is exposed in the public header.

Pattern:

1. Public Header: Contains only the typedef of the structure name.
2. Private Header: Contains the actual struct definition with the Str suffix.

This ensures that external code can hold a pointer to the type but cannot access its internal fields directly, preventing dependency on the structure's layout.

// In the public header:
typedef struct SECMyOpaqueDataStr SECMyOpaqueData;

// In the private header:
struct SECMyOpaqueDataStr {
    unsigned long myPrivateData1;
    unsigned long myPrivateData2;
    char *myName;
};

The --fuzz=tls build mode enables 'Totally Lacking Security' mode. This mode mocks out various cryptographic checks that would otherwise block a fuzzer from reaching deep code paths (e.g., in TLS handshakes or PKCS #7 parsing).

To register a specific target to use this mode, create a file named <target>-no_fuzzer_mode.options in the fuzz/options/ directory.

NSS is organized into multiple libraries, each operating within a specific layer of the system. To use NSS, you must identify the correct library based on your requirements. Each library is defined by its:

• Layer: The primary architectural layer in which the library operates.
• Directory: The specific location of the library's source code within the NSS tree.
• Public Headers: The set of header files containing the types and functions that are exposed to higher-level APIs.

When integrating NSS into your project, ensure you include the appropriate public headers for the layer you are targeting.

This directory contains a combined C extraction of the libcrux ML-KEM (FIPS 203) and ML-DSA (FIPS 204) implementations.

Key Characteristics

• Shared Runtime: ML-KEM and ML-DSA share a single copy of the SHA-3/Keccak code (libcrux_sha3_portable.c) and the combined_core.c runtime to reduce duplication.
• Self-Contained: The vendored .c files have no dependencies on NSS or NSPR.
• Isolated Scope: The files are compiled into a single libcrux static library with an isolated include scope. This prevents header collisions (specifically krml/... or eurydice_glue.h) with the HACL* extraction found in lib/freebl/verified/.

Consumers

The primary consumers of this code are the freebl wrappers:

• lib/freebl/kyber.c (for ML-KEM)
• lib/freebl/ml_dsa.c (for ML-DSA)

Understanding the NSS directory layout:

• coreconf/: Contains the build logic.
• lib/: Contains all library code used to create runtime libraries.
• cmd/: Contains tool programs built with NSS. Some are for inspecting/manipulating storage files, others are for testing.
• test/: Contains shell scripts that drive test programs located in cmd/.
• gtests/: Contains the GoogleTest suite.

When writing tests, always use the TEST_F() macro instead of TEST().

Using TEST_F() ensures that the compiler validates the test case name against the fixture class. If you use TEST(), the compiler will not catch typos in the test case name, which can lead to silent failures or incorrect test execution.

The authoritative source for the NSS root store is the certdata.txt file. This file consists of 'certificate blocks' and 'trust blocks' that define a 'root' (a certificate paired with its trust bits).

• Blocks: Delimited by a blank line. Comments start with #.
• Certificate Blocks: Identified by the line CKA_CLASS CK_OBJECT_CLASS CKO_CERTIFICATE.
• Trust Blocks: Identified by the line CKA_CLASS CK_OBJECT_CLASS CKO_NSS_TRUST.

Other lines within a block describe the PKCS#11 object attributes.