index.rst (3170B)
1 .. _mozilla_projects_nss_reference_fc_inittoken: 2 3 FC_InitToken 4 ============ 5 6 `Name <#name>`__ 7 ~~~~~~~~~~~~~~~~ 8 9 .. container:: 10 11 ``FC_InitToken()`` - initialize or re-initialize a token. 12 13 `Syntax <#syntax>`__ 14 ~~~~~~~~~~~~~~~~~~~~ 15 16 .. container:: 17 18 .. code:: 19 20 CK_RV FC_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 ``FC_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 ``FC_InitToken()`` initializes a brand new token or re-initializes a token that was initialized 50 before. 51 52 Specifically, ``FC_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 A user must be able to call ``FC_InitToken()`` without logging into the token (to assume the NSS 57 User role) because either the user's password hasn't been set yet or the user forgets the 58 password and needs to blow away the password-encrypted private key database and start over. 59 60 .. note:: 61 62 **Note:** The SO password should be the empty string, i.e., ``ulPinLen`` argument should be 0. 63 ``FC_InitToken()`` ignores the ``pLabel`` argument. 64 65 .. _return_value: 66 67 `Return value <#return_value>`__ 68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 69 70 .. container:: 71 72 ``FC_InitToken()`` returns the following return codes. 73 74 - ``CKR_OK``: token initialization succeeded. 75 - ``CKR_SLOT_ID_INVALID``: slot ID is invalid. 76 - ``CKR_TOKEN_WRITE_PROTECTED`` 77 78 - we don't have a reference to the key database (we failed to open the key database or we 79 have released our reference). 80 81 - ``CKR_DEVICE_ERROR``: failed to reset the key database. 82 83 .. _application_usage: 84 85 `Application usage <#application_usage>`__ 86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 87 88 .. container:: 89 90 ``FC_InitToken()`` is used to reset the password for the key database when the user forgets the 91 password. 92 93 - The "Reset Password" button of the Mozilla Application Suite and SeaMonkey (in 94 Preferences->Privacy & Security->Master Passwords) calls ``FC_InitToken()``. 95 - The "-T" (token reset) command of ``certutil`` calls ``FC_InitToken()``. 96 97 .. note:: 98 99 **Note:** Resetting the password clears all permanent secret and private keys. You won't be 100 able to decrypt the data, such as Mozilla's stored passwords, that were encrypted using any of 101 those keys. 102 103 .. _see_also: 104 105 `See also <#see_also>`__ 106 ~~~~~~~~~~~~~~~~~~~~~~~~ 107 108 .. container:: 109 110 - :ref:`mozilla_projects_nss_reference_fc_initpin`, `NSC_InitToken </en-US/NSC_InitToken>`__