Cryptographic Token Interface Standard

PKCS#11


Slot and token types

Cryptoki represents slot and token information with the following types:

CK_SLOT_ID; CK_SLOT_ID_PTR

CK_SLOT_ID is a Cryptoki-assigned value that identifies a slot. It is defined as follows:

typedef CK_ULONG CK_SLOT_ID;

A list of CK_SLOT_IDs is returned by C_GetSlotList. A priori, any value of CK_SLOT_ID can be a valid slot identifier"in particular, a system may have a slot identified by the value 0. It need not have such a slot, however.

CK_SLOT_ID_PTR is a pointer to a CK_SLOT_ID.

CK_SLOT_INFO; CK_SLOT_INFO_PTR

CK_SLOT_INFO provides information about a slot. It is defined as follows:

typedef struct CK_SLOT_INFO {
CK_CHAR slotDescription[64];
CK_CHAR manufacturerID[32];
CK_FLAGS flags;
CK_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
} CK_SLOT_INFO;

slotDescriptioncharacter-string description of the slot. Must be padded with the blank character (' '). Should ''not'' be null-terminated.
manufacturerIDID of the slot manufacturer. Must be padded with the blank character (' '). Should ''not'' be null-terminated.
flagsbits flags that provide capabilities of the slot. The flags are defined below
hardwareVersionversion number of the slot's hardware
firmwareVersionversion number of the slot's firmware

The following table defines the flags field:

Table 9, Slot Information Flags
Bit Flag Mask Meaning
CKF_TOKEN_PRESENT 0x00000001 TRUE if a token is present in the slot (e.g., a device is in the reader)
CKF_REMOVABLE_DEVICE 0x00000002 TRUE if the reader supports removable devices
CKF_HW_SLOT 0x00000004 TRUE if the slot is a hardware slot, as opposed to a software slot implementing a "soft token"

For a given slot, the value of the CKF_REMOVABLE_DEVICE flag never changes. In addition, if this flag is not set for a given slot, then the CKF_TOKEN_PRESENT flag for that slot is always set. That is, if a slot does not support a removable device, then that slot always has a token in it.

CK_SLOT_INFO_PTR is a pointer to a CK_SLOT_INFO.

CK_TOKEN_INFO; CK_TOKEN_INFO_PTR

CK_TOKEN_INFO provides information about a token. It is defined as follows:

typedef struct CK_TOKEN_INFO {
CK_CHAR label[32];
CK_CHAR manufacturerID[32];
CK_CHAR model[16];
CK_CHAR serialNumber[16];
CK_FLAGS flags;
CK_ULONG ulMaxSessionCount;
CK_ULONG ulSessionCount;
CK_ULONG ulMaxRwSessionCount;
CK_ULONG ulRwSessionCount;
CK_ULONG ulMaxPinLen;
CK_ULONG ulMinPinLen;
CK_ULONG ulTotalPublicMemory;
CK_ULONG ulFreePublicMemory;
CK_ULONG ulTotalPrivateMemory;
CK_ULONG ulFreePrivateMemory;
CK_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
CK_CHAR utcTime[16];
} CK_TOKEN_INFO;

labelapplication-defined label, assigned during token initialization. Must be padded with the blank character (' '). Should ''not'' be null-terminated.
manufacturerIDID of the device manufacturer. Must be padded with the blank character (' '). Should ''not'' be null-terminated.
modelmodel of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated.
serialNumbercharacter-string serial number of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated.
flagsbit flags indicating capabilities and status of the device as defined below
ulMaxSessionCountmaximum number of sessions that can be opened with the token at one time by a single application (see note below)
ulSessionCountnumber of sessions that this application currently has open with the token (see note below)
ulMaxRwSessionCountmaximum number of read/write sessions that can be opened with the token at one time by a single application (see note below)
ulRwSessionCountnumber of read/write sessions that this application currently has open with the token (see note below)
ulMaxPinLenmaximum length in bytes of the PIN
ulMinPinLenminimum length in bytes of the PIN
ulTotalPublicMemorythe total amount of memory on the token in bytes in which public objects may be stored (see note below)
ulFreePublicMemorythe amount of free (unused) memory on the token in bytes for public objects (see note below)
ulTotalPrivateMemorythe total amount of memory on the token in bytes in which private objects may be stored (see note below)
ulFreePrivateMemorythe amount of free (unused) memory on the token in bytes for private objects (see note below)
hardwareVersionversion number of hardware
firmwareVersionversion number of firmware
utcTimecurrent 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)

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:

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_TOKEN_INFO info;
.
.
.
if ((CK_LONG) info.ulMaxSessionCount

== CK_UNAVAILABLE_INFORMATION) {

/* Token refuses to give value of ulMaxSessionCount */
.
.
.
} else if (info.ulMaxSessionCount == CK_EFFECTIVELY_INFINITE) {
/* Application can open as many sessions as it wants */
.
.
.
} else {
/* ulMaxSessionCount really does contain what it should */
.
.
.
}

CK_TOKEN_INFO_PTR is a pointer to a CK_TOKEN_INFO.


RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v201