index.rst (3655B)
1 .. _mozilla_projects_nss_reference_fc_gettokeninfo: 2 3 FC_GetTokenInfo 4 =============== 5 6 `Name <#name>`__ 7 ~~~~~~~~~~~~~~~~ 8 9 .. container:: 10 11 FC_GetTokenInfo - obtain information about a particular token in the system. 12 13 `Syntax <#syntax>`__ 14 ~~~~~~~~~~~~~~~~~~~~ 15 16 .. container:: 17 18 .. code:: 19 20 CK_RV FC_GetTokenInfo(CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR pInfo); 21 22 `Parameters <#parameters>`__ 23 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 24 25 .. container:: 26 27 ``FC_GetTokenInfo`` has two parameters: 28 29 ``slotID`` 30 the ID of the token's slot 31 ``pInfo`` 32 points to a `CK_TOKEN_INFO </en-US/CK_TOKEN_INFO>`__ structure 33 34 `Description <#description>`__ 35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36 37 .. container:: 38 39 ``FC_GetTokenInfo`` returns information about the token in the specified slot. On return, the 40 ``CK_TOKEN_INFO`` structure that ``pInfo`` points to has the following information: 41 42 - ``label``: the label of the token, assigned during token initialization, padded with spaces to 43 32 bytes and not null-terminated. 44 - ``manufacturerID``: ID of the device manufacturer, "Mozilla Foundation", padded with spaces to 45 32 characters and not null-terminated. 46 - ``model``: model of the device, "NSS 3", padded with spaces to 16 characters and not 47 null-terminated. 48 - ``serialNumber``: the device's serial number as a string, "0000000000000000", 16 characters 49 and not null-terminated. 50 - ``flags``: bit flags indicating capabilities and status of the device. 51 52 - ``CKF_RNG (0x00000001)``: this device has a random number generator 53 - ``CKF_WRITE_PROTECTED (0x00000002)``: this device is read-only 54 - ``CKF_LOGIN_REQUIRED (0x00000004)``: this device requires the user to log in to use some of 55 its services 56 - ``CKF_USER_PIN_INITIALIZED (0x00000008)``: the user's password has been initialized 57 - ``CKF_DUAL_CRYPTO_OPERATIONS (0x00000200)``: a single session with the token can perform 58 dual cryptographic operations 59 - ``CKF_TOKEN_INITIALIZED (0x00000400)``: the token has been initialized. If login is 60 required (which is true for the FIPS mode of operation), this flag means the user's 61 password has been initialized. 62 63 - ``ulSessionCount``: number of sessions that this application currently has open with the token 64 - ``ulRwSessionCount``: number of read/write sessions that this application currently has open 65 with the token 66 - ``hardwareVersion``: hardware version number, for example, 8.3 (``major=0x08, minor=0x03``), 67 which are the version numbers of the certificate and key databases, respectively. 68 - ``firmwareVersion``: firmware version number, 0.0 (``major=0x00, minor=0x00``). 69 70 A user may call ``FC_GetTokenInfo`` without logging into the token (to assume the NSS User role). 71 72 .. _return_value: 73 74 `Return value <#return_value>`__ 75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 76 77 .. container:: 78 79 ``CKR_OK`` 80 Token information was successfully copied. 81 ``CKR_CRYPTOKI_NOT_INITIALIZED`` 82 The PKCS #11 module library is not initialized. 83 ``CKR_SLOT_ID_INVALID`` 84 The specified slot number is out of the defined range of values. 85 86 .. note:: 87 88 FC_GetTokenInfo should return CKR_ARGUMENTS_BAD if pInfo is NULL. 89 90 `Examples <#examples>`__ 91 ~~~~~~~~~~~~~~~~~~~~~~~~ 92 93 .. container:: 94 95 Note the use of the ``%.32s`` format string to print the ``label`` and ``manufacturerID`` members 96 of the ``CK_TOKEN_INFO`` structure. 97 98 .. _see_also: 99 100 `See also <#see_also>`__ 101 ~~~~~~~~~~~~~~~~~~~~~~~~ 102 103 .. container:: 104 105 - :ref:`mozilla_projects_nss_reference_fc_getslotinfo`, 106 `NSC_GetTokenInfo </en-US/NSC_GetTokenInfo>`__