diff options
Diffstat (limited to 'doc/rst/legacy/reference/nss_initialize/index.rst')
| -rw-r--r-- | doc/rst/legacy/reference/nss_initialize/index.rst | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/doc/rst/legacy/reference/nss_initialize/index.rst b/doc/rst/legacy/reference/nss_initialize/index.rst new file mode 100644 index 000000000..cc2ce0746 --- /dev/null +++ b/doc/rst/legacy/reference/nss_initialize/index.rst @@ -0,0 +1,113 @@ +.. _mozilla_projects_nss_reference_nss_initialize: + +NSS_Initialize +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + NSS_Initialize - initialize NSS. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: eval + + SECStatus NSS_Initialize(const char *configdir, + const char *certPrefix, + const char *keyPrefix, + const char *secmodName, + PRUint32 flags); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``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 <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``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: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSS_Initialize`` returns SECSuccess on success, or SECFailure on failure. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: eval + + #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: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS_Init, NSS_InitReadWrite, NSS_NoDB_Init, NSS_Shutdown
\ No newline at end of file |