Cryptographic Token Interface Standard

PKCS#11

---

CK_TOKEN_INFO Reference

CK_TOKEN_INFO

CK_TOKEN_INFO provides information about a token. More...

Data Fields
CK_CHAR	label [32]
	application-defined label, assigned during token initialization. More...
CK_CHAR	manufacturerID [32]
	ID of the device manufacturer. More...
CK_CHAR	model [16]
	model of the device. More...
CK_CHAR	serialNumber [16]
	character-string serial number of the device. More...
CK_FLAGS	flags
	bit flags indicating capabilities and status of the device as defined below. More...
CK_ULONG	ulMaxSessionCount
	maximum number of sessions that can be opened with the token at one time. More...
CK_ULONG	ulSessionCount
	number of sessions that are currently open with the token. More...
CK_ULONG	ulMaxRwSessionCount
	maximum number of read/write sessions that can be opened with the token at one time. More...
CK_ULONG	ulRwSessionCount
	number of read/write sessions that are currently open with the token. More...
CK_ULONG	ulMaxPinLen
	maximum length in bytes of the PIN. More...
CK_ULONG	ulMinPinLen
	minimum length in bytes of the PIN. More...
CK_ULONG	ulTotalPublicMemory
	the total amount of memory in bytes in which public objects may be stored. More...
CK_ULONG	ulFreePublicMemory
	the amount of free (unused) memory in bytes for public objects. More...
CK_ULONG	ulTotalPrivateMemory
	the total amount of memory in bytes in which private objects may be stored. More...
CK_ULONG	ulFreePrivateMemory
	the amount of free (unused) memory in bytes for private objects. More...
CK_VERSION	hardwareVersion
	version number of hardware. More...
CK_VERSION	firmwareVersion
	version number of firmware. More...
CK_CHAR	utcTime [16]
	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). More...

---

Detailed Description

CK_TOKEN_INFO

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 (' ')
manufacturerID	ID of the device manufacturer. Must be padded with the blank character (' ')
model	model of the device. Must be padded with the blank character (' ')
serialNumber	character-string serial number of the device. Must be padded with the blank character (' ')
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
ulSessionCount	number of sessions that are currently open with the token
ulMaxRwSessionCount	maximum number of read/write sessions that can be opened with the token at one time
ulRwSessionCount	number of read/write sessions that are currently open with the token
ulMaxPinLen	maximum length in bytes of the PIN
ulMinPinLen	minimum length in bytes of the PIN
ulTotalPublicMemory	the total amount of memory in bytes in which public objects may be stored
ulFreePublicMemory	the amount of free (unused) memory in bytes for public objects
ulTotalPrivateMemory	the total amount of memory in bytes in which private objects may be stored
ulFreePrivateMemory	the amount of free (unused) memory in bytes for private objects
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 below)

The following table defines the flags parameter:

Table 7-2, 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
CKF_LOGIN_REQUIRED	0x00000004	TRUE if a user must be logged in to perform cryptographic functions
CKF_USER_PIN_INITIALIZED	0x00000008	TRUE if the normal user's PIN has been initialized
CKF_EXCLUSIVE_EXISTS	0x00000010	TRUE if an exclusive session exists
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_SUPPORTS_PARALLEL	0x00000080	TRUE if token supports parallel sessions through this Cryptoki library
CKF_PROTECTED_AUTHENTICATION_PATH	0x00000100	TRUE if token has a "protected authentication path", whereby a user can log in to 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 other actions:

• Creating/modifying an object on the token.
• Creating/modifying a token object on the token.
• Changing the SO's PIN.
• Changing the normal user's PIN. The ulMaxSessionCount, ulSessionCount, ulMaxRwSessionCount, ulRwSessionCount, ulMaxPinLen, ulMinPinLen, ulTotalPublicMemory, ulFreePublicMemory, ulTotalPrivateMemory, and ulFreePrivateMemory fields have a quirk in their interpretations. For each of these fields, it is possible for a token to return a special value which means, "I cannot/will not divulge that information." This value is the integer value -1, which (unfortunately) does not fit into a variable of type CK_ULONG. The upshot of all this is that the correct way to interpret (for example) the ulMaxSessionCount field is as follows:

CK_TOKEN_INFO info;
.
.
.
if ((CK_LONG) info.ulMaxSessionCount == -1) {
/* Token refuses to give value of ulMaxSessionCount */
.
.
.
} else {
/* info.ulMaxSessionCount really does contain what it should */
.
.
.
}

CK_TOKEN_INFO_PTR

CK_TOKEN_INFO_PTR points to a CK_TOKEN_INFO structure. It is implementation-dependent.

Session types

Cryptoki represents session information with the following types:

CK_SESSION_HANDLE

CK_SESSION_HANDLE is a Cryptoki-assigned value that identifies a session. It is defined as follows:

typedef CK_ULONG CK_SESSION_HANDLE;

CK_SESSION_HANDLE_PTR

CK_SESSION_HANDLE_PTR points to a CK_SESSION_HANDLE. It is implementation-dependent.

CK_USER_TYPE

CK_USER_TYPE holds the types of Cryptoki users described in Section . It is defined as follows:

typedef CK_ULONG CK_USER_TYPE;

For this version of Cryptoki, the following types of users are defined:

#define CKU_SO 0
#define CKU_USER 1

CK_STATE

CK_STATE holds the session state, as decribed in Sections and . It is defined as follows:

typedef CK_ULONG CK_STATE;

For this version of Cryptoki, the following session states are defined:

#define CKS_RO_PUBLIC_SESSION 0
#define CKS_RO_USER_FUNCTIONS 1
#define CKS_RW_PUBLIC_SESSION 2
#define CKS_RW_USER_FUNCTIONS 3
#define CKS_RW_SO_FUNCTIONS 4

CK_SESSION_INFO

CK_SESSION_INFO provides information about a session. It is defined as follows:

---

Field Documentation

CK_CHAR label[32]

application-defined label, assigned during token initialization. Must be padded with the blank character (' ')

CK_CHAR manufacturerID[32]

ID of the device manufacturer. Must be padded with the blank character (' ')

CK_CHAR model[16]

model of the device. Must be padded with the blank character (' ')

CK_CHAR serialNumber[16]

character-string serial number of the device. Must be padded with the blank character (' ')

CK_FLAGS flags

bit flags indicating capabilities and status of the device as defined below.

CK_ULONG ulMaxSessionCount

maximum number of sessions that can be opened with the token at one time.

CK_ULONG ulSessionCount

number of sessions that are currently open with the token.

CK_ULONG ulMaxRwSessionCount

maximum number of read/write sessions that can be opened with the token at one time.

CK_ULONG ulRwSessionCount

number of read/write sessions that are currently open with the token.

CK_ULONG ulMaxPinLen

maximum length in bytes of the PIN.

CK_ULONG ulMinPinLen

minimum length in bytes of the PIN.

CK_ULONG ulTotalPublicMemory

the total amount of memory in bytes in which public objects may be stored.

CK_ULONG ulFreePublicMemory

the amount of free (unused) memory in bytes for public objects.

CK_ULONG ulTotalPrivateMemory

the total amount of memory in bytes in which private objects may be stored.

CK_ULONG ulFreePrivateMemory

the amount of free (unused) memory in bytes for private objects.

CK_VERSION hardwareVersion

version number of hardware.

CK_VERSION firmwareVersion

version number of firmware.

CK_CHAR utcTime[16]

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 below)

---

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