1.. _mozilla_projects_nss_reference_nsc_inittoken:
2
3NSC_InitToken
4=============
5
6`Name <#name>`__
7~~~~~~~~~~~~~~~~
8
9.. container::
10
11   ``NSC_InitToken()`` - initialize or re-initialize a token.
12
13`Syntax <#syntax>`__
14~~~~~~~~~~~~~~~~~~~~
15
16.. container::
17
18   .. code:: eval
19
20      CK_RV NSC_InitToken(
21        CK_SLOT_ID slotID,
22        CK_CHAR_PTR pPin,
23        CK_ULONG ulPinLen,
24        CK_CHAR_PTR pLabel
25      );
26
27`Parameters <#parameters>`__
28~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29
30.. container::
31
32   ``NSC_InitToken()`` has the following parameters:
33
34   ``slotID``
35      the ID of the token's slot
36   ``pPin``
37      the password of the security officer (SO)
38   ``ulPinLen``
39      the length in bytes of the SO password
40   ``pLabel``
41      points to the label of the token, which must be padded with spaces to 32 bytes and not be
42      null-terminated
43
44`Description <#description>`__
45~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46
47.. container::
48
49   ``NSC_InitToken()`` initializes a brand new token or re-initializes a token that was initialized
50   before.
51
52   Specifically, ``NSC_InitToken()`` initializes or clears the key database, removes the password,
53   and then marks all the *user certs* in the certificate database as *non-user certs*. (User certs
54   are the certificates that have their associated private keys in the key database.)
55
56   .. note::
57
58      **Note:** The SO password should be the empty string, i.e., ``ulPinLen`` argument should be 0.
59      ``NSC_InitToken()`` ignores the ``pLabel`` argument.
60
61.. _return_value:
62
63`Return value <#return_value>`__
64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65
66.. container::
67
68   ``NSC_InitToken()`` returns the following return codes.
69
70   -  ``CKR_OK``: token initialization succeeded.
71   -  ``CKR_SLOT_ID_INVALID``: slot ID is invalid.
72   -  ``CKR_TOKEN_WRITE_PROTECTED``
73
74      -  slot ID is 1. (The non-FIPS mode has two slots: 1 and 2. The key database is in slot 2.
75         Slot 1 doesn't have a key database.)
76      -  we don't have a reference to the key database (we failed to open the key database or we
77         have released our reference).
78
79   -  ``CKR_DEVICE_ERROR``: failed to reset the key database.
80
81`Examples <#examples>`__
82~~~~~~~~~~~~~~~~~~~~~~~~
83
84.. container::
85
86.. _application_usage:
87
88`Application usage <#application_usage>`__
89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90
91.. container::
92
93   ``NSC_InitToken()`` is used to reset the password for the key database when the user forgets the
94   password.
95
96   -  The "Reset Password" button of the Mozilla Application Suite and SeaMonkey (in
97      **Preferences->Privacy & Security->Master Passwords**) calls ``NSC_InitToken()``.
98   -  The "-T" (token reset) command of ``certutil`` calls ``NSC_InitToken()``.
99
100   .. note::
101
102      **Note:** Resetting the password clears all permanent secret and private keys. You won't be
103      able to decrypt the data, such as Mozilla's stored passwords, that were encrypted using any of
104      those keys.
105
106.. _see_also:
107
108`See also <#see_also>`__
109~~~~~~~~~~~~~~~~~~~~~~~~
110
111.. container::
112
113   -  `NSC_InitPIN </en-US/NSC_InitPIN>`__, :ref:`mozilla_projects_nss_reference_fc_inittoken`