Cryptographic Token Interface Standard

PKCS#11


Security considerations

As an interface to cryptographic devices, Cryptoki provides a basis for security in a computer or communications system. Two of the particular features of the interface that facilitate such security are the following:

  1. Access to private objects on the token, and possibly to cryptographic functions, requires a PIN. Thus possessing the cryptographic device that implements the token is not sufficient; the PIN is also needed.

  2. Maximum protection is given to objects marked "sensitive""they cannot be read from the token, nor exported through the cryptographic functions (though they can be used as keys).

It is expected that access to private and sensitive object by means other than Cryptoki (e.g., other programming interfaces, or reverse engineering of the device) would be difficult.

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.

CK_VERSION

CK_VERSION is a structure that describes the version of Cryptoki. It is defined as follows:

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.

CK_INFO

CK_INFO provides general information about Cryptoki. It is defined as follows:

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.

CK_NOTIFICATION

CK_NOTIFICATION enumerates the types of notifications that Cryptoki provides to an application. It is defined as follows:

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.

CK_SLOT_ID

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

typedef CK_ULONG CK_SLOT_ID;

A CK_SLOT_ID is returned by C_GetSlotList.

CK_SLOT_ID_PTR

CK_SLOT_ID_PTR points to a CK_SLOT_ID. It is implementation dependent.

CK_SLOT_INFO

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_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"

CK_SLOT_INFO_PTR

CK_SLOT_INFO_PTR points to a CK_SLOT_INFO structure. It is implementation dependent.

CK_TOKEN_INFO

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

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 enumerates the types of Cryptoki users described in Section . It is defined as follows:

typedef enum CK_USER_TYPE {
CKU_SO, /* Security Officer */
CKU_USER /* Normal user */
} CK_USER_TYPE;

CK_STATE

CK_STATE enumerates the session states decribed in Sections and . It is defined as follows:

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;

CK_SESSION_INFO

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

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

CK_SESSION_INFO_PTR

CK_SESSION_INFO_PTR points to a CK_SESSION_INFO structure. It is implementation dependent.

Object types

Cryptoki represents object information with the following types.

CK_OBJECT_HANDLE

CK_OBJECT_HANDLE is a token-specific identifier for an object. It is defined as follows:

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.

CK_OBJECT_HANDLE_PTR

CK_OBJECT_HANDLE_PTR points to a CK_OBJECT_HANDLE. It is implementation dependent.

CK_OBJECT_CLASS

CK_OBJECT_CLASS is a value that identifies the classes (or types) of objects that Cryptoki recognizes. It is defined as follows:

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.

CK_OBJECT_CLASS_PTR

CK_OBJECT_CLASS_PTR points to a CK_OBJECT_CLASS structure. It is implementation dependent.

CK_KEY_TYPE

CK_KEY_TYPE is a value that identifies a key type. It is defined as follows:

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.

CK_CERTIFICATE_TYPE

CK_CERTIFICATE_TYPE is a value that identifies a certificate type. It is defined as follows:

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.

CK_ATTRIBUTE_TYPE

CK_ATTRIBUTE_TYPE is a value that identifies an attribute type. It is defined as follows:

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.

CK_ATTRIBUTE

CK_ATTRIBUTE is a structure that includes the type, length and value of an attribute. It is defined as follows:

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

CK_ATTRIBUTE_PTR

CK_ATTRIBUTE_PTR points to a CK_ATTRIBUTE structure. It is implementation dependent.

CK_DATE

CK_DATE is a structure that defines a date. It is defined as follows:

typedef struct CK_DATE{
CK_CHAR year[4];
CK_CHAR month[2];
CK_CHAR day[2];
} CK_DATE;

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.


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