| Cryptographic Token Interface Standard |
PKCS#11
|
CK_TOKEN_INFO Reference
CK_TOKEN_INFO; CK_TOKEN_INFO_PTR
CK_TOKEN_INFO provides information about a token.
More...
Detailed Description
CK_TOKEN_INFO; CK_TOKEN_INFO_PTR
CK_TOKEN_INFO provides information about a token. It is defined as follows: label | application-defined label, assigned during token initialization. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
manufacturerID | ID of the device manufacturer. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
model | model of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
serialNumber | character-string serial number of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
flags | bit flags indicating capabilities and status of the device as defined below |
ulMaxSessionCount | maximum number of sessions that can be opened with the token at one time by a single application (see note below) |
ulSessionCount | number of sessions that this application currently has open with the token (see note below) |
ulMaxRwSessionCount | maximum number of read/write sessions that can be opened with the token at one time by a single application (see note below) |
ulRwSessionCount | number of read/write sessions that this application currently has open with the token (see note below) |
ulMaxPinLen | maximum length in bytes of the PIN |
ulMinPinLen | minimum length in bytes of the PIN |
ulTotalPublicMemory | the total amount of memory on the token in bytes in which public objects may be stored (see note below) |
ulFreePublicMemory | the amount of free (unused) memory on the token in bytes for public objects (see note below) |
ulTotalPrivateMemory | the total amount of memory on the token in bytes in which private objects may be stored (see note below) |
ulFreePrivateMemory | the amount of free (unused) memory on the token in bytes for private objects (see note below) |
hardwareVersion | version number of hardware |
firmwareVersion | version number of firmware |
utcTime | current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved '0' characters). The value of this field only makes sense for tokens equipped with a clock, as indicated in the token information flags (see Table 10) |
The following table defines the flags field:
Table 10, Token Information Flags
Bit Flag | Mask | Meaning |
CKF_RNG | 0x00000001 | TRUE if the token has its own random number generator |
CKF_WRITE_PROTECTED | 0x00000002 | TRUE if the token is write-protected (see below) |
CKF_LOGIN_REQUIRED | 0x00000004 | TRUE if there are some cryptographic functions that a user must be logged in to perform |
CKF_USER_PIN_INITIALIZED | 0x00000008 | TRUE if the normal user's PIN has been initialized |
CKF_RESTORE_KEY_NOT_NEEDED | 0x00000020 | TRUE if a successful save of a session's cryptographic operations state always contains all keys needed to restore the state of the session |
CKF_CLOCK_ON_TOKEN | 0x00000040 | TRUE if token has its own hardware clock |
CKF_PROTECTED_AUTHENTICATION_PATH | 0x00000100 | TRUE if token has a "protected authentication path", whereby a user can log into the token without passing a PIN through the Cryptoki library |
CKF_DUAL_CRYPTO_OPERATIONS | 0x00000200 | TRUE if a single session with the token can perform dual cryptographic operations (see Section 11.13) |
CKF_TOKEN_INITIALIZED | 0x00000400 | TRUE if the token has been initialized using C_InitializeToken or an equivalent mechanism outside the scope of this standard. Calling C_InitializeToken when this flag is set will cause the token to be reinitialized. |
CKF_SECONDARY_AUTHENTICATION | 0x00000800 | TRUE if the token supports secondary authentication for private key objects. |
CKF_USER_PIN_COUNT_LOW | 0x00010000 | TRUE if an incorrect user login PIN has been entered at least once since the last successful authentication. |
CKF_USER_PIN_FINAL_TRY | 0x00020000 | TRUE if supplying an incorrect user PIN will it to become locked. |
CKF_USER_PIN_LOCKED | 0x00040000 | TRUE if the user PIN has been locked. User login to the token is not possible. |
CKF_USER_PIN_TO_BE_CHANGED | 0x00080000 | TRUE if the user PIN value is the default value set by token initialization or manufacturing. |
CKF_SO_PIN_COUNT_LOW | 0x00100000 | TRUE if an incorrect SO login PIN has been entered at least once since the last successful authentication. |
CKF_SO_PIN_FINAL_TRY | 0x00200000 | TRUE if supplying an incorrect SO PIN will it to become locked. |
CKF_SO_PIN_LOCKED | 0x00400000 | TRUE if the user PIN has been locked. User login to the token is not possible. |
CKF_SO_PIN_TO_BE_CHANGED | 0x00800000 | TRUE if the SO PIN value is the default value set by token initialization or manufacturing. |
Exactly what the CKF_WRITE_PROTECTED flag means is not specified in Cryptoki. An application may be unable to perform certain actions on a write-protected token; these actions can include any of the following, among others:
The CKF_USER_PIN_TO_BE_CHANGED and CKF_SO_PIN_TO_BE_CHANGED flags may always be set to FALSE if the token does not support the functionality.
Note: The fields ulMaxSessionCount, ulSessionCount, ulMaxRwSessionCount, ulRwSessionCount, ulTotalPublicMemory, ulFreePublicMemory, ulTotalPrivateMemory, and ulFreePrivateMemory can have the special value CK_UNAVAILABLE_INFORMATION, which means that the token and/or library is unable or unwilling to provide that information. In addition, the fields ulMaxSessionCount and ulMaxRwSessionCount can have the special value CK_EFFECTIVELY_INFINITE, which means that there is no practical limit on the number of sessions (resp. R/W sessions) an application can have open with the token.
These values are defined as
#define CK_UNAVAILABLE_INFORMATION (~0UL)
#define CK_EFFECTIVELY_INFINITE 0
It is important to check these fields for these special values. This is particularly true for CK_EFFECTIVELY_INFINITE, since an application seeing this value in the ulMaxSessionCount or ulMaxRwSessionCount field would otherwise conclude that it can't open any sessions with the token, which is far from being the case.
The upshot of all this is that the correct way to interpret (for example) the ulMaxSessionCount field is something along the lines of the following:
== CK_UNAVAILABLE_INFORMATION) {
CK_TOKEN_INFO_PTR is a pointer to a CK_TOKEN_INFO.
Field Documentation
|
application-defined label, assigned during token initialization. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
|
ID of the device manufacturer. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
|
model of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
|
character-string serial number of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated. |
|
bit flags indicating capabilities and status of the device as defined below. |
|
maximum number of sessions that can be opened with the token at one time by a single application (see note below). |
|
number of sessions that this application currently has open with the token (see note below). |
|
maximum number of read/write sessions that can be opened with the token at one time by a single application (see note below). |
|
number of read/write sessions that this application currently has open with the token (see note below). |
|
maximum length in bytes of the PIN. |
|
minimum length in bytes of the PIN. |
|
the total amount of memory on the token in bytes in which public objects may be stored (see note below). |
|
the amount of free (unused) memory on the token in bytes for public objects (see note below). |
|
the total amount of memory on the token in bytes in which private objects may be stored (see note below). |
|
the amount of free (unused) memory on the token in bytes for private objects (see note below). |
|
version number of hardware. |
|
version number of firmware. |
|
current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved '0' characters). The value of this field only makes sense for tokens equipped with a clock, as indicated in the token information flags (see Table 10) |
RSA Security Inc. Public-Key Cryptography Standards -
PKCS#11 - v210