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
|
.. _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
|
