Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 110 insertions, 0 deletions

diff --git a/security/nss/doc/rst/legacy/reference/fc_inittoken/index.rst b/security/nss/doc/rst/legacy/reference/fc_inittoken/index.rst
new file mode 100644
index 0000000000..900e91c5e3
--- /dev/null
+++ b/security/nss/doc/rst/legacy/reference/fc_inittoken/index.rst
@@ -0,0 +1,110 @@
+.. _mozilla_projects_nss_reference_fc_inittoken:
+
+FC_InitToken
+============
+
+`Name <#name>`__
+~~~~~~~~~~~~~~~~
+
+.. container::
+
+   ``FC_InitToken()`` - initialize or re-initialize a token.
+
+`Syntax <#syntax>`__
+~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   .. code::
+
+      CK_RV FC_InitToken(
+        CK_SLOT_ID slotID,
+        CK_CHAR_PTR pPin,
+        CK_ULONG ulPinLen,
+        CK_CHAR_PTR pLabel
+      );
+
+`Parameters <#parameters>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   ``FC_InitToken()`` has the following parameters:
+
+   ``slotID``
+      the ID of the token's slot
+   ``pPin``
+      the password of the security officer (SO)
+   ``ulPinLen``
+      the length in bytes of the SO password
+   ``pLabel``
+      points to the label of the token, which must be padded with spaces to 32 bytes and not be
+      null-terminated
+
+`Description <#description>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   ``FC_InitToken()`` initializes a brand new token or re-initializes a token that was initialized
+   before.
+
+   Specifically, ``FC_InitToken()`` initializes or clears the key database, removes the password,
+   and then marks all the *user certs* in the certificate database as *non-user certs*. (User certs
+   are the certificates that have their associated private keys in the key database.)
+
+   A user must be able to call ``FC_InitToken()`` without logging into the token (to assume the NSS
+   User role) because either the user's password hasn't been set yet or the user forgets the
+   password and needs to blow away the password-encrypted private key database and start over.
+
+   .. note::
+
+      **Note:** The SO password should be the empty string, i.e., ``ulPinLen`` argument should be 0.
+      ``FC_InitToken()`` ignores the ``pLabel`` argument.
+
+.. _return_value:
+
+`Return value <#return_value>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   ``FC_InitToken()`` returns the following return codes.
+
+   -  ``CKR_OK``: token initialization succeeded.
+   -  ``CKR_SLOT_ID_INVALID``: slot ID is invalid.
+   -  ``CKR_TOKEN_WRITE_PROTECTED``
+
+      -  we don't have a reference to the key database (we failed to open the key database or we
+         have released our reference).
+
+   -  ``CKR_DEVICE_ERROR``: failed to reset the key database.
+
+.. _application_usage:
+
+`Application usage <#application_usage>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   ``FC_InitToken()`` is used to reset the password for the key database when the user forgets the
+   password.
+
+   -  The "Reset Password" button of the Mozilla Application Suite and SeaMonkey (in
+      Preferences->Privacy & Security->Master Passwords) calls ``FC_InitToken()``.
+   -  The "-T" (token reset) command of ``certutil`` calls ``FC_InitToken()``.
+
+   .. note::
+
+      **Note:** Resetting the password clears all permanent secret and private keys. You won't be
+      able to decrypt the data, such as Mozilla's stored passwords, that were encrypted using any of
+      those keys.
+
+.. _see_also:
+
+`See also <#see_also>`__
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   -  :ref:`mozilla_projects_nss_reference_fc_initpin`, `NSC_InitToken </en-US/NSC_InitToken>`__
\ No newline at end of file