FC_Initialize¶
Summary¶
FC_Initialize - initialize the PKCS #11 library.
Syntax¶
CK_RV FC_Initialize(CK_VOID_PTR pInitArgs);
Parameters¶
pInitArgs
Points to a
CK_C_INITIALIZE_ARGS
structure.
Description¶
FC_Initialize
initializes the NSS cryptographic module
for the FIPS mode of operation. In
addition to creating the internal data structures, it performs the FIPS software integrity test
and power-up self-tests.
The pInitArgs
argument must point to a CK_C_INITIALIZE_ARGS
structure whose members
should have the following values:
CreateMutex
should beNULL
.DestroyMutex
should beNULL
.LockMutex
should beNULL
.UnlockMutex
should beNULL
.flags
should beCKF_OS_LOCKING_OK
.LibraryParameters
should point to a string that contains the library parameters.pReserved
should beNULL
.
The library parameters string has this format:
"configdir='dir' certPrefix='prefix1' keyPrefix='prefix2' secmod='file' flags= "
Here are some examples.
NSS_NoDB_Init("")
, which initializes NSS with no databases:
"configdir='' certPrefix='' keyPrefix='' secmod='' flags=readOnly,noCertDB,noMod
DB,forceOpen,optimizeSpace "
Mozilla Firefox initializes NSS with this string (on Windows):
"configdir='C:\\Documents and Settings\\wtc\\Application Data\\Mozilla\\Firefox\\Profiles\\default.7tt' certPrefix='' keyPrefix='' secmod='secmod.db' flags=optimizeSpace manufacturerID='Mozilla.org' libraryDescription='PSM Internal Crypto Services' cryptoTokenDescription='Generic Crypto Services' dbTokenDescription='Software Security Device' cryptoSlotDescription='PSM Internal Cryptographic Services' dbSlotDescription='PSM Private Keys' FIPSSlotDescription='PSM Internal FIPS-140-1 Cryptographic Services' FIPSTokenDescription='PSM FIPS-140-1 User Private Key Services' minPS=0"
See PKCS #11 Module Specs for complete documentation of the library parameters string.
Return value¶
FC_Initialize
returns the following return codes.
CKR_OK
: library initialization succeeded.CKR_ARGUMENTS_BAD
pInitArgs
isNULL
.pInitArgs->LibraryParameters
isNULL
.only some of the lock functions were provided by the application.
CKR_CANT_LOCK
: theCKF_OS_LOCKING_OK
flag is not set inpInitArgs->flags
. The NSS cryptographic module always uses OS locking and doesn’t know how to use the lock functions provided by the application.CKR_CRYPTOKI_ALREADY_INITIALIZED
: the library is already initialized.CKR_DEVICE_ERROR
We failed to create the OID tables, random number generator, or internal locks. (Note: we probably should return
CKR_HOST_MEMORY
instead.)The software integrity test or power-up self-tests failed. The NSS cryptographic module is in a fatal error state.
CKR_HOST_MEMORY
: we ran out of memory.
Examples¶
#include <assert.h>
CK_FUNCTION_LIST_PTR pFunctionList;
CK_RV crv;
CK_C_INITIALIZE_ARGS initArgs;
crv = FC_GetFunctionList(&pFunctionList);
assert(crv == CKR_OK);
initArgs.CreateMutex = NULL;
initArgs.DestroyMutex = NULL;
initArgs.LockMutex = NULL;
initArgs.UnlockMutex = NULL;
initArgs.flags = CKF_OS_LOCKING_OK;
initArgs.LibraryParameters = "...";
initArgs.pReserved = NULL;
/* invoke FC_Initialize as pFunctionList->C_Initialize */
crv = pFunctionList->C_Initialize(&initArgs);