View source for 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 [[Security_Policy#Platform_List|Platform List]]) and tagged with a release identifier to be published on [https://ftp.mozilla.org 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.

{| border="1" cellpadding="2"
|+
|-
!
NSS Cryptographic
Module Components
!
Library
Name
|-
| PKCS #11 || libsoftokn3
|-
| FREEBL || libfreebl3
|-
|}

<div class=note>'''Note''': Filename extensions (.so, .dll, .sl, or .dylib) depend upon the target operating environment. For some CPUs libfreebl3 is named libfreebl_''cpu-type''_3.</div>

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.

{| border="1" cellpadding="2"
|+
|-
!
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.

[[ Image:Fipsmod6.png ]]

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

[[ Image:Fipshw.png ]]

===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 <code>C_GetFunctionList</code> 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 <code>FC_GetFunctionList</code> and call the function pointers in that list. Here is the sample code using NSPR functions (declared in the header file <code>"prlink.h"</code>) for dynamic library loading and function symbol lookup:
<pre>
#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;
}
</pre>
To reiterate, the mode of operation of the NSS cryptographic module is determined by the second argument passed to the <code>PR_FindFunctionSymbol</code> function.
* For the non-FIPS Approved mode of operation, look up the standard PKCS #11 function <code>"C_GetFunctionList"</code>.
* For the FIPS Approved mode of operation, look up the alternative function <code>"FC_GetFunctionList"</code>.

===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.
* [[Section_4:_Finite_State_Model|Finite State Model and Description]]
* [http://www.mozilla.org/projects/security/pki/nss/fips/audit-design.html Design of Auditing in the NSS Software Cryptographic Module]
* [http://www.mozilla.org/projects/security/pki/nss/pcertdb.html Physical format of the certificate database]
* [http://www.mozilla.org/projects/security/pki/nss/devel/pk11wrap.pdf The pk11wrap layer and the softoken]
* [http://www.mozilla.org/projects/security/pki/nss/intro.html Introduction to NSS]
* [http://www.mozilla.org/projects/security/pki/nss/nss-guidelines.html 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