FIPS Module Specification: Difference between revisions

FIPS Module Specification (view source)

Revision as of 23:29, 12 July 2006

1,947 bytes added , 12 July 2006

→‎Approved Mode of Operation

Wtchang

canmove, Confirmed users

937

edits

@@ Line 64: / Line 64: @@
 ===Approved Mode of Operation===
-In order to run the NSS module in the FIPS Approved mode, an attribute must be explicitly set on the module. This can be done programmatically with a call to [http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/pk11wrap/pk11util.c.dep.html#SECMOD_DeleteInternalModule SECMOD_DeleteInternalModule()] (with the module to delete being the internal module):
+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 for dynamic library loading and function symbol lookup:
 <pre>
-    SECMODModule *internal;
+#include "prlink.h"
-    SECStatus rv;
+#include "cryptoki.h"
+#include <assert.h>
+#include <stdio.h>
-     internal = SECMOD_GetInternalModule();
+typedef struct CK_C_INITIALIZE_ARGS_NSS {
-     if (!internal) {
+    CK_CREATEMUTEX CreateMutex;
-         /* handle error */
+    CK_DESTROYMUTEX DestroyMutex;
-     }
+    CK_LOCKMUTEX LockMutex;
-     rv = SECMOD_DeleteInternalModule(internal->commonName);
+    CK_UNLOCKMUTEX UnlockMutex;
-     if (rv != SECSuccess) {
+    CK_FLAGS flags;
-         /* handle error */
+     /* 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;
+}
 </pre>
-or by running the NSS module utility [http://www.mozilla.org/projects/security/pki/nss/tools/modutil.html '''modutil''']. An example command line is below:
-    modutil -fips true -dbdir <i>directory</i>
-where <code><i>directory</i></code> is the directory that contains the NSS databases.
-The setting is permanent for the NSS module and all subsequent invocations of NSS functions using that NSS database directory will be in FIPS mode. The module can be taken out of FIPS mode by substituting <code>false</code> for <code>true</code> in the command above. The state of the module can be checked with:
-    modutil -chkfips true -dbdir <i>directory</i>
-where <code><i>directory</i></code> is the directory that contains the NSS databases, or with a call to [http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/pk11wrap/pk11util.c.dep.html#PK11_IsFIPS PK11_IsFIPS()].
 ===Design Specification===

FIPS Module Specification: Difference between revisions

FIPS Module Specification (view source)

Revision as of 23:29, 12 July 2006

Navigation menu

Search