1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
.. _mozilla_projects_nss_reference_fc_initialize:
FC_Initialize
=============
.. _name:
`Summary <#name>`__
-------------------
.. container::
FC_Initialize - initialize the PKCS #11 library.
`Syntax <#syntax>`__
--------------------
.. container::
.. code::
CK_RV FC_Initialize(CK_VOID_PTR pInitArgs);
`Parameters <#parameters>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
``pInitArgs``
Points to a ``CK_C_INITIALIZE_ARGS`` structure.
`Description <#description>`__
------------------------------
.. container::
``FC_Initialize`` initializes the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module`
for the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_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 be ``NULL``.
- ``DestroyMutex`` should be ``NULL``.
- ``LockMutex`` should be ``NULL``.
- ``UnlockMutex`` should be ``NULL``.
- ``flags`` should be ``CKF_OS_LOCKING_OK``.
- ``LibraryParameters`` should point to a string that contains the library parameters.
- ``pReserved`` should be ``NULL``.
The library parameters string has this format:
.. code::
"configdir='dir' certPrefix='prefix1' keyPrefix='prefix2' secmod='file' flags= "
Here are some examples.
``NSS_NoDB_Init("")``, which initializes NSS with no databases:
.. code::
"configdir='' certPrefix='' keyPrefix='' secmod='' flags=readOnly,noCertDB,noMod
DB,forceOpen,optimizeSpace "
Mozilla Firefox initializes NSS with this string (on Windows):
.. code::
"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 :ref:`mozilla_projects_nss_pkcs11_module_specs` for complete documentation of the library
parameters string.
.. _return_value:
`Return value <#return_value>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
``FC_Initialize`` returns the following return codes.
- ``CKR_OK``: library initialization succeeded.
- ``CKR_ARGUMENTS_BAD``
- ``pInitArgs`` is ``NULL``.
- ``pInitArgs->LibraryParameters`` is ``NULL``.
- only some of the lock functions were provided by the application.
- ``CKR_CANT_LOCK``: the ``CKF_OS_LOCKING_OK`` flag is not set in ``pInitArgs->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 <#examples>`__
------------------------
.. container::
.. code::
#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);
|
