From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- .../doc/rst/legacy/reference/fc_initpin/index.rst | 78 ++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 security/nss/doc/rst/legacy/reference/fc_initpin/index.rst (limited to 'security/nss/doc/rst/legacy/reference/fc_initpin/index.rst') diff --git a/security/nss/doc/rst/legacy/reference/fc_initpin/index.rst b/security/nss/doc/rst/legacy/reference/fc_initpin/index.rst new file mode 100644 index 0000000000..fc083b9e0a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_initpin/index.rst @@ -0,0 +1,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 `__, :ref:`mozilla_projects_nss_reference_fc_setpin` \ No newline at end of file -- cgit v1.2.3