Pkcs #11: Cryptographic Token Interface Standard rsa laboratories

8.2. Slot and token types

• CK_SLOT_ID; CK_SLOT_ID_PTR

typedef CK_ULONG CK_SLOT_ID;

• CK_SLOT_INFO; CK_SLOT_INFO_PTR

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;

The following table defines the flags field:

Table , 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

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;
The fields of the structure have the following meanings:

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 )

The following table defines the flags field:

• 
  Creating/modifying/deleting any object on the token.
  
• 
  Creating/modifying/deleting a token object on the token.
  
• 
  Changing the SO’s PIN.
  
• 
  Changing the normal user’s PIN.
  

These values are defined as

#define CK_UNAVAILABLE_INFORMATION (~0UL)

#define CK_EFFECTIVELY_INFINITE 0

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;
.

.

.

== 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 {

.

.

}
CK_TOKEN_INFO_PTR is a pointer to a CK_TOKEN_INFO.