1.. _mozilla_projects_nss_reference_fc_initpin:
2
3FC_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:: eval
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`