index.rst (4407B)
1 .. _mozilla_projects_nss_reference_nss_initialize: 2 3 NSS_Initialize 4 ============== 5 6 `Name <#name>`__ 7 ~~~~~~~~~~~~~~~~ 8 9 .. container:: 10 11 NSS_Initialize - initialize NSS. 12 13 `Syntax <#syntax>`__ 14 ~~~~~~~~~~~~~~~~~~~~ 15 16 .. container:: 17 18 .. code:: 19 20 SECStatus NSS_Initialize(const char *configdir, 21 const char *certPrefix, 22 const char *keyPrefix, 23 const char *secmodName, 24 PRUint32 flags); 25 26 `Parameters <#parameters>`__ 27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 28 29 .. container:: 30 31 ``NSS_Initialize`` has five parameters: 32 33 ``configdir`` 34 [in] the directory where the certificate, key, and module databases live. To-do: document the 35 "sql:" prefix. 36 ``certPrefix`` 37 [in] prefix added to the beginning of the certificate database, for example, "https-server1-". 38 ``keyPrefix`` 39 [in] prefix added to the beginning of the key database, for example, "https-server1-". 40 ``secmodName`` 41 [in] name of the security module database, usually "secmod.db". 42 ``flags`` 43 [in] bit flags that specify how NSS should be initialized. 44 45 `Description <#description>`__ 46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 47 48 .. container:: 49 50 ``NSS_Initialize`` initializes NSS. It is more flexible than ``NSS_Init``, ``NSS_InitReadWrite``, 51 and ``NSS_NoDB_Init``. If any of those simpler NSS initialization functions suffices for your 52 needs, call that instead. 53 54 The ``flags`` parameter is a bitwise OR of the following flags: 55 56 - NSS_INIT_READONLY - Open the databases read only. 57 - NSS_INIT_NOCERTDB - Don't open the cert DB and key DB's, just initialize the volatile certdb. 58 - NSS_INIT_NOMODDB - Don't open the security module DB, just initialize the PKCS #11 module. 59 - NSS_INIT_FORCEOPEN - Continue to force initializations even if the databases cannot be opened. 60 - NSS_INIT_NOROOTINIT - Don't try to look for the root certs module automatically. 61 - NSS_INIT_OPTIMIZESPACE - Optimize for space instead of speed. Use smaller tables and caches. 62 - NSS_INIT_PK11THREADSAFE - only load PKCS#11 modules that are thread-safe, i.e., that support 63 locking - either OS locking or NSS-provided locks . If a PKCS#11 module isn't thread-safe, 64 don't serialize its calls; just don't load it instead. This is necessary if another piece of 65 code is using the same PKCS#11 modules that NSS is accessing without going through NSS, for 66 example, the Java SunPKCS11 provider. 67 - NSS_INIT_PK11RELOAD - ignore the CKR_CRYPTOKI_ALREADY_INITIALIZED error when loading PKCS#11 68 modules. This is necessary if another piece of code is using the same PKCS#11 modules that NSS 69 is accessing without going through NSS, for example, Java SunPKCS11 provider. 70 - NSS_INIT_NOPK11FINALIZE - never call C_Finalize on any PKCS#11 module. This may be necessary 71 in order to ensure continuous operation and proper shutdown sequence if another piece of code 72 is using the same PKCS#11 modules that NSS is accessing without going through NSS, for 73 example, Java SunPKCS11 provider. The following limitation applies when this is set 74 : SECMOD_WaitForAnyTokenEvent will not use C_WaitForSlotEvent, in order to prevent the need 75 for C_Finalize. This call will be emulated instead. 76 - NSS_INIT_RESERVED - Currently has no effect, but may be used in the future to trigger better 77 cooperation between PKCS#11 modules used by both NSS and the Java SunPKCS11 provider. This 78 should occur after a new flag is defined for C_Initialize by the PKCS#11 working group. 79 - NSS_INIT_COOPERATE - Sets the above four recommended options for applications that use both 80 NSS and the Java SunPKCS11 provider. 81 82 .. _return_value: 83 84 `Return value <#return_value>`__ 85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 86 87 .. container:: 88 89 ``NSS_Initialize`` returns SECSuccess on success, or SECFailure on failure. 90 91 `Examples <#examples>`__ 92 ~~~~~~~~~~~~~~~~~~~~~~~~ 93 94 .. container:: 95 96 .. code:: 97 98 #include <nss.h> 99 100 SECStatus rv; 101 const char *configdir; 102 103 configdir = ...; /* application-specific */ 104 rv = NSS_Initialize(configdir, "", "", SECMOD_DB, NSS_INIT_NOROOTINIT | NSS_INIT_OPTIMIZESPACE); 105 106 .. _see_also: 107 108 `See also <#see_also>`__ 109 ~~~~~~~~~~~~~~~~~~~~~~~~ 110 111 .. container:: 112 113 - NSS_Init, NSS_InitReadWrite, NSS_NoDB_Init, NSS_Shutdown