![]() | Cryptographic Token Interface Standard |
PKCS#11 |
If a device does not have a tamper-proof environment or protected memory in which to store private and sensitive objects, the device may encrypt the objects with a master key which is perhaps derived from the user's PIN. The particular mechanism for protecting private objects is left to the device implementation, however.
Based on these features it should be possible to design applications in such a way that the token can provide adequate security for the objects the applications manage.
Of course, cryptography is only one element of security, and the token is only one component in a system. While the token itself may be secure, one must also consider the security of the operating system by which the application interfaces to it, especially since the PIN is passed through the operating system. It is easy for a rogue application on the operating system to obtain the PIN; it is also possible that other devices monitoring communication lines to the cryptographic device can obtain the PIN. Rogue applications and devices may also change the commands sent to the cryptographic device to obtain other services than what the application requested.
It is important to be sure that the system is secure against such attack. Cryptoki may well play a role here, for instance if a token is involved in the "booting up" of the system.
It is important to note that none of the attacks just described can compromise objects marked "sensitive," since the "sensitive" attribute cannot be changed once set. However, during key generation, before a private key is marked "sensitive," a copy of the private key could be obtained by the rogue application, so it is important to generate keys in a more trusted environment, than the environment in which one performs normal operations.
An application may also want to be sure that the token is "legitimate" in some sense (for a variety of reasons, including export restrictions). This is outside the scope of the present standard, but it can be achieved by distributing the token with a built-in, certified public/private-key pair, by which the token can prove its identity. The certificate would be signed by an authority (presumably the one indicating that the token is "legitimate"), whose public key is known to the application. The application would verify the certificate, and challenge the token to prove its identity by signing a time-varying message with its built-in private key.
Once a normal user has been authenticated to the token, Cryptoki does not restrict which cryptographic operations the user may perform. The user may perform any operation supported by the token.
Data types
Cryptoki's data types are described in following subsections, organized into categories, based on the kind of information they represent.
General information
Cryptoki represents general information with the following types.
typedef struct CK_VERSION { CK_BYTE major; CK_BYTE minor; } CK_VERSION;
major | major version number, the integer portion of the version |
minor | minor version number, the hundredths portion of the version |
For version 1.0, major = 1 and minor = For version 2.1, major = 2 and minor = 10. Minor revisions of the standard are always upwardly compatible within the same major version number.
typedef struct CK_INFO { CK_VERSION version; CK_CHAR manufacturerID[32]; CK_FLAGS flags; } CK_INFO;
version | Cryptoki interface version number, for compatibility with future revisions of this interface |
manufacturerID | ID of the Cryptoki library manufacturer; must be padded with the blank character (' ') |
flags | bit flags reserved for future versions; must be zero for this version CK_INFO_PTR |
CK_INFO_PTR points to a CK_INFO structure. It is implementation dependent.
typedef enum CK_NOTIFICATION { CKN_SURRENDER, CKN_COMPLETE, CKN_DEVICE_REMOVED } CK_NOTIFICATION;
The notifications have the following meanings:
CKN_SURRENDER Cryptoki is surrendering the execution of a function so that the application may perform other operations. After performing such operations, the application should indicate to Cryptoki whether to continue or cancel the function.
CKN_COMPLETE A function running in parallel has completed.
CKN_DEVICE_REMOVED Cryptoki detected that the device underlying the token has been removed from the reader (assuming the token has the capability)
Slot and token types
Cryptoki represents slot and token information with the following types.
typedef CK_ULONG CK_SLOT_ID;
A CK_SLOT_ID is returned by C_GetSlotList.
typedef struct CK_SLOT_INFO { CK_CHAR slotDescription[64]; CK_CHAR manufacturerID[32]; CK_FLAGS flags; } CK_SLOT_INFO;
slotDescription | character-string description of the slot (the type of interface between the device and the computer); must be padded with the blank character (' ') |
manufacturerID | ID of the "slot" manufacturer; must be padded with the blank character (' ') |
flags | bits flags that provide capabilities of the slot. |
The following table defines the flags.
Table 7-1, Slot Information Flags
Bit Flag | Mask | Meaning |
CKF_TOKEN_PRESENT | 0x0001 | TRUE if a token is present in the slot (e.g., a device is in the reader) |
CKF_REMOVABLE_DEVICE | 0x0002 | TRUE if the reader supports removable devices |
CKF_HW_SLOT | 0x0004 | TRUE if the slot is a hardware slot as opposed to a software slot implementing a "soft token" |
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_USHORT usMaxSessionCount; CK_USHORT usSessionCount; CK_USHORT usMaxRwSessionCount; CK_USHORT usRwSessionCount; CK_USHORT usMaxPinLen; CK_USHORT usMinPinLen; CK_ULONG ulTotalPublicMemory; CK_ULONG ulFreePublicMemory; CK_ULONG ulTotalPrivateMemory; CK_ULONG ulFreePrivateMemory; } CK_TOKEN_INFO;
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 |
usMaxSessionCount | maximum number of sessions that can be opened with the token at one time |
usSessionCount | number of sessions that are currently open with the token |
usMaxRwSessionCount | maximum number of read/write sessions that can be opened with the token at one time |
usRwSessionCount | number of read/write sessions that are currently open with the token |
usMaxPinLen | maximum length in bytes of the PIN |
usMinPinLen | minimum length in bytes of the PIN |
ulTotalPublicMemory | the total amount of memory in bytes occupied by public objects |
ulFreePublicMemory | the amount of free (unused) memory in bytes for public objects |
ulTotalPrivateMemory | the total amount of memory in bytes occupied by private objects |
ulFreePrivateMemory | the amount of free (unused) memory in bytes for private objects |
The flags parameter is defined as follows:
Table 7-2, Token Information Flags
Bit Flag | Mask | Meaning |
CKF_RNG | 0x0001 | TRUE if the token has its own random number generator |
CKF_WRITE_PROTECTED | 0x0002 | TRUE if the token is write-protected |
CKF_LOGIN_REQUIRED | 0x0004 | TRUE if a user must be logged in to perform cryptographic functions |
CKF_USER_PIN_INITIALIZED | 0x0008 | TRUE if the normal user's PIN has been initialized |
CKF_EXCLUSIVE_EXISTS | 0x0010 | TRUE if an exclusive session exists |
Session types
Cryptoki represents session information with the following types.
typedef CK_ULONG CK_SESSION_HANDLE;
typedef enum CK_USER_TYPE { CKU_SO, /* Security Officer */ CKU_USER /* Normal user */ } CK_USER_TYPE;
typedef enum CK_STATE { CKS_RW_PUBLIC_SESSION, CKS_RW_USER_FUNCTIONS, CKS_RO_PUBLIC_SESSION, CKS_RO_SO_FUNCTIONS, CKS_RO_USER_FUNCTIONS } CK_STATE;
typedef struct CK_SESSION_INFO { CK_SLOT_ID slotID; CK_STATE state; CK_FLAGS flags; CK_USHORT usDeviceError; } CK_SESSION_INFO;
slotID | ID of the slot that interfaces with the token |
state | the state of the session |
flags | bit flags that define the type of session; the flags are defined below |
usDeviceError | an error code defined by the cryptographic device. Used for errors not covered by Cryptoki. |
The flags are defined in the following table.
Table 7-3, Session Information Flags
Bit Flag | Mask | Meaning |
CKF_EXCLUSIVE_SESSION | 0x0001 | TRUE if the session is exclusive; FALSE if the session is shared |
CKF_RW_SESSION | 0x0002 | TRUE if the session is read/write; FALSE if the session is read-only |
CKF_SERIAL_SESSION | 0x0004 | TRUE if cryptographic functions are performed in serial with the application; FALSE if the functions may be performed in parallel with the application |
Object types
Cryptoki represents object information with the following types.
typedef CK_ULONG CK_OBJECT_HANDLE;
The handle is assigned by Cryptoki when an object is created. The handle for an object is unique among all objects in the token at a given time, and remains constant until the object is destroyed.
Cryptoki considers an object handle valid if and only if the object exists and is accessible to the application. In particular, object handles for private objects are valid if only if a user is logged in.
typedef CK_USHORT CK_OBJECT_CLASS;
For this version of Cryptoki, the following classed of objects are defined:
#define CKO_DATA 0x0000 #define CKO_CERTIFICATE 0x0001 #define CKO_PUBLIC_KEY 0x0002 #define CKO_PRIVATE_KEY 0x0003 #define CKO_SECRET_KEY 0x0004 #define CKO_VENDOR_DEFINED 0x8000
Object classes CKO_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their object classes through the PKCS process.
typedef CK_USHORT CK_KEY_TYPE;
For this version of Cryptoki, the following key types are defined:
#define CKK_RSA 0x0000 #define CKK_DSA 0x0001 #define CKK_DH 0x0002 #define CKK_GENERIC_SECRET 0x0010 #define CKK_RC2 0x0011 #define CKK_RC4 0x0012 #define CKK_DES 0x0013 #define CKK_DES2 0x0014 #define CKK_DES3 0x0015 #define CKK_VENDOR_DEFINED 0x8000
Key types CKK_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their key types through the PKCS process.
typedef CK_USHORT CK_CERTIFICATE_TYPE;
For this version of Cryptoki, the following certificate types are defined:
#define CKC_X_509 0x0000 #define CKC_VENDOR_DEFINED 0x8000
Certificate types CKC_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their certificate types through the PKCS process.
typedef CK_USHORT CK_ATTRIBUTE_TYPE;
For this version of Cryptoki, the following attribute types are defined:
#define CKA_CLASS 0x0000 #define CKA_TOKEN 0x0001 #define CKA_PRIVATE 0x0002 #define CKA_LABEL 0x0003 #define CKA_APPLICATION 0x0010 #define CKA_VALUE 0x0011 #define CKA_CERTIFICATE_TYPE 0x0080 #define CKA_ISSUER 0x0081 #define CKA_SERIAL_NUMBER 0x0082 #define CKA_KEY_TYPE 0x0100 #define CKA_SUBJECT 0x0101 #define CKA_ID 0x0102 #define CKA_SENSITIVE 0x0103 #define CKA_ENCRYPT 0x0104 #define CKA_DECRYPT 0x0105 #define CKA_WRAP 0x0106 #define CKA_UNWRAP 0x0107 #define CKA_SIGN 0x0108 #define CKA_SIGN_RECOVER 0x0109 #define CKA_VERIFY 0x010A #define CKA_VERIFY_RECOVER 0x010B #define CKA_DERIVE 0x010C #define CKA_MODULUS 0x0120 #define CKA_MODULUS_BITS 0x0121 #define CKA_PUBLIC_EXPONENT 0x0122 #define CKA_PRIVATE_EXPONENT 0x0123 #define CKA_PRIME_1 0x0124 #define CKA_PRIME_2 0x0125 #define CKA_EXPONENT_1 0x0126 #define CKA_EXPONENT_2 0x0127 #define CKA_COEFFICIENT 0x0128 #define CKA_PRIME 0x0130 #define CKA_SUBPRIME 0x0131 #define CKA_BASE 0x0132 #define CKA_VALUE_BITS 0x0160 #define CKA_VALUE_LEN 0x0161 #define CKA_VENDOR_DEFINED 0x8000
Section defines the attributes for each object class. Attribute types CKA_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their attribute types through the PKCS process.
typedef struct CK_ATTRIBUTE { CK_ATTRIBUTE_TYPE type; CK_VOID_PTR pValue; CK_USHORT usValueLen; } CK_ATTRIBUTE;
type | the attribute type |
pValue | pointer to the value of the attribute |
usValueLen | length in bytes of the value |
If an attribute has no value, then pValue = NULL_PTR, and usValueLen = 0. An array of CK_ATTRIBUTEs is called a "template" and is used for creating, manipulating and searching for objects. Note that pValue is an "void" pointer, facilitating the passing of arbitrary values. Both the application and Cryptoki library must ensure that the pointer can be safely cast to the expected type (e.g., without word-alignment errors).
year | the year ("1900" - "9999") |
month | the month ("01" - "12") |
day | the day ("01" - "31") |
The fields hold numeric characters from the character set in Table 4 -3, not the literal byte values.