NSS_Initialize

Name

NSS_Initialize - initialize NSS.

Syntax

SECStatus NSS_Initialize(const char *configdir,
                         const char *certPrefix,
                         const char *keyPrefix,
                         const char *secmodName,
                         PRUint32 flags);

Parameters

NSS_Initialize has five parameters:

configdir
[in] the directory where the certificate, key, and module databases live. To-do: document the "sql:" prefix.
certPrefix
[in] prefix added to the beginning of the certificate database, for example, "https-server1-".
keyPrefix
[in] prefix added to the beginning of the key database, for example, "https-server1-".
secmodName
[in] name of the security module database, usually "secmod.db".
flags
[in] bit flags that specify how NSS should be initialized.

Description

NSS_Initialize initializes NSS. It is more flexible than NSS_Init, NSS_InitReadWrite, and NSS_NoDB_Init. If any of those simpler NSS initialization functions suffices for your needs, call that instead.

The flags parameter is a bitwise OR of the following flags:

  • NSS_INIT_READONLY - Open the databases read only.
  • NSS_INIT_NOCERTDB - Don't open the cert DB and key DB's, just¬†initialize the volatile certdb.
  • NSS_INIT_NOMODDB¬†- Don't open the security module DB, just¬†initialize the ¬†PKCS #11 module.
  • NSS_INIT_FORCEOPEN - Continue to force initializations even if the¬†databases cannot be opened.
  • NSS_INIT_NOROOTINIT - Don't try to look for the root certs module¬†automatically.
  • NSS_INIT_OPTIMIZESPACE - Optimize for space instead of speed. Use smaller tables and caches.
  • NSS_INIT_PK11THREADSAFE - only load PKCS#11 modules that are¬†thread-safe, i.e., that support locking - either OS¬†locking or NSS-provided locks . If a PKCS#11¬†module isn't thread-safe, don't serialize its¬†calls; just don't load it instead. This is necessary¬†if another piece of code is using the same PKCS#11¬†modules that NSS is accessing without going through¬†NSS, for example, the Java SunPKCS11 provider.
  • NSS_INIT_PK11RELOAD - ignore the CKR_CRYPTOKI_ALREADY_INITIALIZED¬†error when loading PKCS#11 modules. This is necessary¬†if another piece of code is using the same PKCS#11¬†modules that NSS is accessing without going through¬†NSS, for example, Java SunPKCS11 provider.
  • NSS_INIT_NOPK11FINALIZE - never call C_Finalize on any¬†PKCS#11 module. This may be necessary in order to¬†ensure continuous operation and proper shutdown¬†sequence if another piece of code is using the same¬†PKCS#11 modules that NSS is accessing without going¬†through NSS, for example, Java SunPKCS11 provider.¬†The following limitation applies when this is set :¬†SECMOD_WaitForAnyTokenEvent will not use¬†C_WaitForSlotEvent, in order to prevent the need for¬†C_Finalize. This call will be emulated instead.
  • NSS_INIT_RESERVED - Currently has no effect, but may be used in the¬†future to trigger better cooperation between PKCS#11¬†modules used by both NSS and the Java SunPKCS11¬†provider. This should occur after a new flag is defined¬†for C_Initialize by the PKCS#11 working group.
  • NSS_INIT_COOPERATE - Sets the above four recommended options for applications that¬†use both NSS and the Java SunPKCS11 provider.

Return value

NSS_Initialize returns SECSuccess on success, or SECFailure on failure.

Examples

#include <nss.h>

SECStatus rv;
const char *configdir;

configdir = ...;  /* application-specific */
rv = NSS_Initialize(configdir, "", "", SECMOD_DB, NSS_INIT_NOROOTINIT | NSS_INIT_OPTIMIZESPACE);

See also

  • NSS_Init, NSS_InitReadWrite, NSS_NoDB_Init, NSS_Shutdown