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