tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

index.rst (2125B)

      1 .. _mozilla_projects_nss_reference_fc_initpin:
      2 
      3 FC_InitPIN
      4 ==========
      5 
      6 `Name <#name>`__
      7 ~~~~~~~~~~~~~~~~
      8 
      9 .. container::
     10 
     11   ``FC_InitPIN()`` - Initialize the user's PIN.
     12 
     13 `Syntax <#syntax>`__
     14 ~~~~~~~~~~~~~~~~~~~~
     15 
     16 .. container::
     17 
     18   .. code::
     19 
     20      CK_RV FC_InitPIN(
     21        CK_SESSION_HANDLE hSession,
     22        CK_CHAR_PTR pPin,
     23        CK_ULONG ulPinLen
     24      );
     25 
     26 `Parameters <#parameters>`__
     27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     28 
     29 .. container::
     30 
     31   ``FC_InitPIN()`` takes three parameters:
     32 
     33   ``hSession``
     34      [Input] Session handle.
     35   ``pPin``
     36      [Input] Pointer to the PIN being set.
     37   ``ulPinLen``
     38      [Input] Length of the PIN.
     39 
     40 `Description <#description>`__
     41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     42 
     43 .. container::
     44 
     45   ``FC_InitPIN()`` initializes the normal user's PIN.
     46 
     47   ``FC_InitPIN()`` must be called when the PKCS #11 Security Officer (SO) is logged into the token
     48   and the session is read/write, that is, the session must be in the "R/W SO Functions" state
     49   (``CKS_RW_SO_FUNCTIONS``). The role of the PKCS #11 SO is to initialize a token and to initialize
     50   the normal user's PIN. In the NSS cryptographic module, one uses the empty string password ("")
     51   to log in as the PKCS #11 SO. The module only allows the PKCS #11 SO to log in if the normal
     52   user's PIN has not yet been set or has been reset.
     53 
     54 .. _return_value:
     55 
     56 `Return value <#return_value>`__
     57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     58 
     59 .. container::
     60 
     61   ``FC_InitPIN()`` returns the following return codes.
     62 
     63   -  ``CKR_OK``: normal user's PIN initialization succeeded.
     64   -  ``CKR_SESSION_HANDLE_INVALID``: the session handle is invalid.
     65   -  ``CKR_USER_NOT_LOGGED_IN``: the session is not in the "R/W SO Functions" state.
     66   -  ``CKR_PIN_INVALID``: the PIN has an invalid UTF-8 character.
     67   -  ``CKR_PIN_LEN_RANGE``: the PIN is too short, too long, or too weak (doesn't have enough
     68      character types).
     69   -  ``CKR_DEVICE_ERROR``: normal user's PIN is already initialized.
     70 
     71 .. _see_also:
     72 
     73 `See also <#see_also>`__
     74 ~~~~~~~~~~~~~~~~~~~~~~~~
     75 
     76 .. container::
     77 
     78   -  `NSC_InitPIN </en-US/NSC_InitPIN>`__, :ref:`mozilla_projects_nss_reference_fc_setpin`