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


Data Fields

CK_UTF8CHAR label [32]
 application-defined label, assigned during token initialization. More...

CK_UTF8CHAR manufacturerID [32]
 ID of the device manufacturer. More...

CK_UTF8CHAR 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 by a single application (see note below). More...

CK_ULONG ulSessionCount
 number of sessions that this application currently has open with the token (see note below). More...

CK_ULONG ulMaxRwSessionCount
 maximum number of read/write sessions that can be opened with the token at one time by a single application (see note below). More...

CK_ULONG ulRwSessionCount
 number of read/write sessions that this application currently has open with the token (see note below). 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 on the token in bytes in which public objects may be stored (see note below). More...

CK_ULONG ulFreePublicMemory
 the amount of free (unused) memory on the token in bytes for public objects (see note below). More...

CK_ULONG ulTotalPrivateMemory
 the total amount of memory on the token in bytes in which private objects may be stored (see note below). More...

CK_ULONG ulFreePrivateMemory
 the amount of free (unused) memory on the token in bytes for private objects (see note below). 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_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 below)

The following table defines the flags field: 








 Table 11, 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_InitToken or an equivalent mechanism outside the scope of this standard. Calling C_InitToken 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. (Deprecated; new implementations MUST NOT set this flag)   


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 cause 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, or the PIN has been expired by the card.    


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 cause it to become locked.    


CKF_SO_PIN_LOCKED 0x00400000 True if the SO PIN has been locked. SO 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, or the PIN has been expired by the card.    


CKF_ERROR_STATE 0x01000000 True if the token failed a FIPS 140-2 self-test and entered an error state.  

 



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_COUNT_LOW, CKF_USER_PIN_COUNT_LOW, CKF_USER_PIN_FINAL_TRY, and CKF_SO_PIN_FINAL_TRY  flags may always be set to false if the token does not support the functionality or will not reveal the information because of its security policy.


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. If a PIN is set to the default value, or has expired, the appropriate CKF_USER_PIN_TO_BE_CHANGED or CKF_SO_PIN_TO_BE_CHANGED flag is set to true. When either of these flags are true, logging in with the corresponding PIN will succeed, but only the C_SetPIN function can be called. Calling any other function that required the user to be logged in will cause CKR_PIN_EXPIRED to be returned until C_SetPIN is called successfully.


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.


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. 



Field Documentation





  

    
      

        

           CK_UTF8CHAR label[32]
      

    		
  





  

    
       
    
    



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

  







  

    
      

        

           CK_UTF8CHAR manufacturerID[32]
      

    		
  





  

    
       
    
    



ID of the device manufacturer. Must be padded with the blank character (' '). Should ''not'' be null-terminated.     

  







  

    
      

        

           CK_UTF8CHAR model[16]
      

    		
  





  

    
       
    
    



model of the device. Must be padded with the blank character (' '). Should ''not'' be null-terminated.     

  







  

    
      

        

           CK_CHAR serialNumber[16]
      

    		
  





  

    
       
    
    



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

  







  

    
      

        

           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 by a single application (see note below).     

  







  

    
      

        

           CK_ULONG ulSessionCount
      

    		
  





  

    
       
    
    



number of sessions that this application currently has open with the token (see note below).     

  







  

    
      

        

           CK_ULONG ulMaxRwSessionCount
      

    		
  





  

    
       
    
    



maximum number of read/write sessions that can be opened with the token at one time by a single application (see note below).     

  







  

    
      

        

           CK_ULONG ulRwSessionCount
      

    		
  





  

    
       
    
    



number of read/write sessions that this application currently has open with the token (see note below).     

  







  

    
      

        

           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 on the token in bytes in which public objects may be stored (see note below).     

  







  

    
      

        

           CK_ULONG ulFreePublicMemory
      

    		
  





  

    
       
    
    



the amount of free (unused) memory on the token in bytes for public objects (see note below).     

  







  

    
      

        

           CK_ULONG ulTotalPrivateMemory
      

    		
  





  

    
       
    
    



the total amount of memory on the token in bytes in which private objects may be stored (see note below).     

  







  

    
      

        

           CK_ULONG ulFreePrivateMemory
      

    		
  





  

    
       
    
    



the amount of free (unused) memory on the token in bytes for private objects (see note below).     

  







  

    
      

        

           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 - v230