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 Platform List) and tagged with a release identifier to be published on ftp.mozilla.org. The release compliant with FIPS 140-2 is version 3.11.5.
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* (one is selected at run time) |
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 NSS cryptographic module has two modes of operation: non-FIPS Approved mode (the default) 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. 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
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 run 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 for dynamic library loading and function symbol lookup:
#include "prlink.h"
#include "cryptoki.h"
#include <assert.h>
#include <stdio.h>
typedef struct CK_C_INITIALIZE_ARGS_NSS {
CK_CREATEMUTEX CreateMutex;
CK_DESTROYMUTEX DestroyMutex;
CK_LOCKMUTEX LockMutex;
CK_UNLOCKMUTEX UnlockMutex;
CK_FLAGS flags;
/* The official PKCS #11 spec does not have a 'LibraryParameters' field, but
* a reserved field. NSS needs a way to pass instance-specific information
* to the library (like where to find its config files, etc). This
* information is usually provided by the installer and passed uninterpreted
* by NSS to the library, though NSS does know the specifics of the softoken
* version of this parameter. Most compliant PKCS#11 modules expect this
* parameter to be NULL, and will return CKR_ARGUMENTS_BAD from
* C_Initialize if Library parameters is supplied. */
CK_CHAR_PTR *LibraryParameters;
/* This field is only present if the LibraryParameters is not NULL. It must
* be NULL in all cases */
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.
- Look up the standard PKCS #11 function
"C_GetFunctionList"for the non-FIPS Approved mode of operation. - Look up the alternative function
"FC_GetFunctionList"for the FIPS Approved mode of operation.
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
- Physical format of the certificate database
- 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