FIPS Module Specification

This is a draft document

Cryptographic Module Specification

The NSS cryptographic module is a cryptographic library that presents an application program interface (API) based on the PKCS #11 standard to applications. The NSS cryptographic module is compiled and built for specific platforms (see the Platform List section of the Security Policy) and tagged with a release identifier to be published on ftp.mozilla.org. The release compliant with FIPS 140-2 is version 3.11.4.

Functions that are being certified include Triple DES(KO 1,2,3 56/112/168), AES(128/192/256), SHS (SHA-1, SHA-256, SHA-384, SHA-512), HMAC, RNG, DSA (512-1024), RSA (1024-8092), and ECDSA.

Module Components

The NSS cryptographic module is a software cryptographic implementation. No hardware or firmware components are included. All input to the module is via function arguments; all output is returned to the caller either as return codes or as updated memory objects pointed to by some of the arguments.

NSS Cryptographic Module Components	Library Name
PKCS #11	libsoftokn3
FREEBL	libfreebl3
nssdbm	libnssdbm3

Note: Filename extensions (.so, .dll, .sl, or .dylib) depend upon the target operating environment. For some CPUs libfreebl3 is named libfreebl_cpu-type_3.

The NSS cryptographic module depends on the following Netscape Portable Runtime (NSPR) libraries outside the cryptographic boundary. The NSPR libraries provide platform abstraction and utility functions.

NSS Cryptographic Module Dependencies	Library Name
NSPR (platform abstraction layer)	libnspr4
PLC (NSPR string functions)	libplc4
PLDS (NSPR hashtables and arena pools)	libplds4

The Cryptographic Boundary

The NSS cryptographic module is a multiple-chip standalone cryptographic module. The physical boundary of the NSS cryptographic module is the enclosure of the general purpose computer it runs on, including any hardware or software that inputs, processes, or outputs important security parameters that could lead to the compromise of sensitive information if not properly controlled.

The NSS cryptographic module implements the PKCS #11 (Cryptoki) API. The API itself defines the logical cryptographic boundary, thus all implementation is inside the boundary. The diagram below shows the relationship of the layers.

Hardware Diagram

The block diagram below shows the hardware components of a general purpose computer and their interconnections. The dotted line marks the physical cryptographic boundary.

Approved Mode of Operation

The NSS cryptographic module has two modes of operation: non-FIPS Approved mode and FIPS Approved mode. The FIPS Approved mode is designed specifically for FIPS 140-2, and allows applications using the NSS cryptographic module to operate in a strictly FIPS mode.

By default the NSS cryptographic module operates in the non-FIPS Approved mode, meaning that if an application calls the standard PKCS #11 function C_GetFunctionList and calls the function pointers in that list, it gets the non-FIPS Approved mode. To operate the NSS cryptographic module in the FIPS Approved mode, an application must call the alternative function FC_GetFunctionList and call the function pointers in that list. Here is the sample code using NSPR functions (declared in the header file "prlink.h") for dynamic library loading and function symbol lookup:

#include "prlink.h"
#include "cryptoki.h"
#include <assert.h>
#include <stdio.h>

/*
 * An extension of the CK_C_INITIALIZE_ARGS structure for the
 * NSS cryptographic module. The 'LibraryParameters' field is
 * used to pass instance-specific information to the library
 * (like where to find its config files, etc).
 */
typedef struct CK_C_INITIALIZE_ARGS_NSS {
    CK_CREATEMUTEX CreateMutex;
    CK_DESTROYMUTEX DestroyMutex;
    CK_LOCKMUTEX LockMutex;
    CK_UNLOCKMUTEX UnlockMutex;
    CK_FLAGS flags;
    CK_CHAR_PTR *LibraryParameters;
    CK_VOID_PTR pReserved;
} CK_C_INITIALIZE_ARGS_NSS;

int main()
{
    char *libname;
    PRLibrary *lib;
    CK_C_GetFunctionList pC_GetFunctionList;
    CK_FUNCTION_LIST_PTR pFunctionList;
    CK_RV rv;
    CK_C_INITIALIZE_ARGS_NSS initArgs;
    CK_INFO info;
    PRStatus status;

    /* Get the platform-dependent library name of the NSS cryptographic module */
    libname = PR_GetLibraryName(NULL, "softokn3");
    assert(libname != NULL);
    lib = PR_LoadLibrary(libname);
    assert(lib != NULL);
    PR_FreeLibraryName(libname);

    pC_GetFunctionList = (CK_C_GetFunctionList) PR_FindFunctionSymbol(lib,
        "FC_GetFunctionList");
    assert(pC_GetFunctionList != NULL);
    rv = (*pC_GetFunctionList)(&pFunctionList);
    assert(rv == CKR_OK);

    /* Call FC_Foo as pFunctionList->C_Foo */

    initArgs.CreateMutex = NULL;
    initArgs.DestroyMutex = NULL;
    initArgs.LockMutex = NULL;
    initArgs.UnlockMutex = NULL;
    initArgs.flags = CKF_OS_LOCKING_OK;
    initArgs.LibraryParameters = (CK_CHAR_PTR *)
        "configdir='.' certPrefix='' keyPrefix='' secmod='secmod.db' flags= ";
    initArgs.pReserved = NULL;
    rv = pFunctionList->C_Initialize(&initArgs);
    assert(rv == CKR_OK);

    rv = pFunctionList->C_GetInfo(&info);
    assert(rv == CKR_OK);
    printf("General information about the PKCS #11 library:\n");
    printf("    PKCS #11 version: %d.%d\n",
        (int)info.cryptokiVersion.major, (int)info.cryptokiVersion.minor);
    printf("    manufacturer ID: %.32s\n", info.manufacturerID);
    printf("    flags: 0x%08lX\n", info.flags);
    printf("    library description: %.32s\n", info.libraryDescription);
    printf("    library version: %d.%d\n",
        (int)info.libraryVersion.major, (int)info.libraryVersion.minor);
    printf("\n");

    rv = pFunctionList->C_Finalize(NULL);
    assert(rv == CKR_OK);

    status = PR_UnloadLibrary(lib);
    assert(status == PR_SUCCESS);
    return 0;
}

To reiterate, the mode of operation of the NSS cryptographic module is determined by the second argument passed to the PR_FindFunctionSymbol function.

• For the non-FIPS Approved mode of operation, look up the standard PKCS #11 function "C_GetFunctionList".
• For the FIPS Approved mode of operation, look up the alternative function "FC_GetFunctionList".

Design Specification

The design of the software components of the NSS cryptographic module is specified in the following documents. Some of these documents cover the larger NSS project, of which the NSS cryptographic module is a component.

• Finite State Model and Description
• Design of Auditing in the NSS Software Cryptographic Module
• Physical format of the certificate database
• NSS shared DB
• The pk11wrap layer and the softoken
• Introduction to NSS
• NSS API Guidelines

Security-Related Information

Security-related information whose disclosure or modification can compromise the security of the NSS cryptographic module includes:

• secret and private cryptographic keys (both plaintext and encrypted)
• passwords
• audited events, audit data