index.rst (4290B)
1 .. _mozilla_projects_nss_reference_fc_initialize: 2 3 FC_Initialize 4 ============= 5 6 .. _name: 7 8 `Summary <#name>`__ 9 ------------------- 10 11 .. container:: 12 13 FC_Initialize - initialize the PKCS #11 library. 14 15 `Syntax <#syntax>`__ 16 -------------------- 17 18 .. container:: 19 20 .. code:: 21 22 CK_RV FC_Initialize(CK_VOID_PTR pInitArgs); 23 24 `Parameters <#parameters>`__ 25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 26 27 .. container:: 28 29 ``pInitArgs`` 30 Points to a ``CK_C_INITIALIZE_ARGS`` structure. 31 32 `Description <#description>`__ 33 ------------------------------ 34 35 .. container:: 36 37 ``FC_Initialize`` initializes the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module` 38 for the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_fips_mode_of_operation`. In 39 addition to creating the internal data structures, it performs the FIPS software integrity test 40 and power-up self-tests. 41 42 The ``pInitArgs`` argument must point to a ``CK_C_INITIALIZE_ARGS`` structure whose members 43 should have the following values: 44 45 - ``CreateMutex`` should be ``NULL``. 46 - ``DestroyMutex`` should be ``NULL``. 47 - ``LockMutex`` should be ``NULL``. 48 - ``UnlockMutex`` should be ``NULL``. 49 - ``flags`` should be ``CKF_OS_LOCKING_OK``. 50 - ``LibraryParameters`` should point to a string that contains the library parameters. 51 - ``pReserved`` should be ``NULL``. 52 53 The library parameters string has this format: 54 55 .. code:: 56 57 "configdir='dir' certPrefix='prefix1' keyPrefix='prefix2' secmod='file' flags= " 58 59 Here are some examples. 60 61 ``NSS_NoDB_Init("")``, which initializes NSS with no databases: 62 63 .. code:: 64 65 "configdir='' certPrefix='' keyPrefix='' secmod='' flags=readOnly,noCertDB,noMod 66 DB,forceOpen,optimizeSpace " 67 68 Mozilla Firefox initializes NSS with this string (on Windows): 69 70 .. code:: 71 72 "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" 73 74 See :ref:`mozilla_projects_nss_pkcs11_module_specs` for complete documentation of the library 75 parameters string. 76 77 .. _return_value: 78 79 `Return value <#return_value>`__ 80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 81 82 .. container:: 83 84 ``FC_Initialize`` returns the following return codes. 85 86 - ``CKR_OK``: library initialization succeeded. 87 - ``CKR_ARGUMENTS_BAD`` 88 89 - ``pInitArgs`` is ``NULL``. 90 - ``pInitArgs->LibraryParameters`` is ``NULL``. 91 - only some of the lock functions were provided by the application. 92 93 - ``CKR_CANT_LOCK``: the ``CKF_OS_LOCKING_OK`` flag is not set in ``pInitArgs->flags``. The NSS 94 cryptographic module always uses OS locking and doesn't know how to use the lock functions 95 provided by the application. 96 - ``CKR_CRYPTOKI_ALREADY_INITIALIZED``: the library is already initialized. 97 - ``CKR_DEVICE_ERROR`` 98 99 - We failed to create the OID tables, random number generator, or internal locks. (Note: we 100 probably should return ``CKR_HOST_MEMORY`` instead.) 101 - The software integrity test or power-up self-tests failed. The NSS cryptographic module is 102 in a fatal error state. 103 104 - ``CKR_HOST_MEMORY``: we ran out of memory. 105 106 `Examples <#examples>`__ 107 ------------------------ 108 109 .. container:: 110 111 .. code:: 112 113 #include <assert.h> 114 115 CK_FUNCTION_LIST_PTR pFunctionList; 116 CK_RV crv; 117 CK_C_INITIALIZE_ARGS initArgs; 118 119 crv = FC_GetFunctionList(&pFunctionList); 120 assert(crv == CKR_OK); 121 122 initArgs.CreateMutex = NULL; 123 initArgs.DestroyMutex = NULL; 124 initArgs.LockMutex = NULL; 125 initArgs.UnlockMutex = NULL; 126 initArgs.flags = CKF_OS_LOCKING_OK; 127 initArgs.LibraryParameters = "..."; 128 initArgs.pReserved = NULL; 129 130 /* invoke FC_Initialize as pFunctionList->C_Initialize */ 131 crv = pFunctionList->C_Initialize(&initArgs);