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`