Source code
Revision control
Copy as Markdown
Other Tools
(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)
:::{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);
```
:::