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 may not be sufficient to use it; the PIN may also be needed.
   
   
2. Additional protection can be given to private keys and secret keys by marking them as "sensitive" or "nonextractable". Sensitive keys cannot be revealed in plaintext off the token, and nonextractable keys cannot be revealed off the token even when encrypted (though they can still be used as keys).
   
   

It is expected that access to private, sensitive, or nonextractable 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 may be passed through the operating system. This can make it 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 services other 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, a token may be involved in the "booting up" of the system.

We note that none of the attacks just described can compromise keys marked "sensitive," since a key that is sensitive will always remain sensitive. Similarly, a key that is unextractable cannot be modified to be extractable. However, during key generation, if a private key or secret key is not created as "sensitive" and "unextractable", a copy of the private key could be obtained by a rogue application before these attributes are set. It can therefore be 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 the following subsections, organized into categories, based on the kind of information they represent. The data types for holding parameters for various mechanisms, and the pointers to those parameters, are not described here; these types are described with the information on the mechanisms themselves, in Section .

General information

Cryptoki represents general information with the following types:

CK_VERSION

CK_VERSION is a structure that describes the version of a Cryptoki interface, a Cryptoki library, an SSL implementation, or the hardware or firmware version of a slot or token. 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 Cryptoki standard are always upwardly compatible within the same major version number.

CK_VERSION_PTR

CK_VERSION_PTR points to a CK_VERSION structure. It is implementation-dependent.

CK_INFO

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

typedef struct CK_INFO {
CK_VERSION cryptokiVersion;
CK_CHAR manufacturerID[32];
CK_FLAGS flags;
CK_CHAR libraryDescription[32];
CK_VERSION libraryVersion;
} CK_INFO;

cryptokiVersion	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
libraryDescription	character-string description of the library. Must be padded with the blank character (' ')
libraryVersion	Cryptoki library version number

For libraries written to the Cryptoki v2.0 document, the value of cryptokiVersion should be 2.0; the value of libraryVersion is the version number of the library software itself.

CK_INFO_PTR

CK_INFO_PTR points to a CK_INFO structure. It is implementation-dependent.

CK_NOTIFICATION

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

typedef CK_ULONG CK_NOTIFICATION;

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

#define CKN_SURRENDER 0
#define CKN_COMPLETE 1
#define CKN_DEVICE_REMOVED 2
#define CKN_TOKEN_INSERTION 3

The notifications have the following meanings:

CKN_SURRENDER Cryptoki is surrendering the execution of a function executing in serial so that the application may perform other operations. After performing any desired 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 has detected that the device underlying the token has been removed from the reader. Not all slots/tokens support this notification.

CKN_TOKEN_INSERTION Cryptoki has detected that the device underlying the token has been inserted into the reader. Not all slots/tokens support this notification.

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_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
} CK_SLOT_INFO;

slotDescription	character-string description of the slot. 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.
hardwareVersion	version number of the slot's hardware
firmwareVersion	version number of the slot's firmware

The following table defines the flags parameter:

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

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

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:

typedef struct CK_SESSION_INFO {
CK_SLOT_ID slotID;
CK_STATE state;
CK_FLAGS flags;
CK_ULONG ulDeviceError;
} 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
ulDeviceError	an error code defined by the cryptographic device. Used for errors not covered by Cryptoki.

The following table defines the flags parameter:

Table 7-3, Session Information Flags

Bit Flag	Mask	Meaning
CKF_EXCLUSIVE_SESSION	0x00000001	TRUE if the session is exclusive; FALSE if the session is shared
CKF_RW_SESSION	0x00000002	TRUE if the session is read/write; FALSE if the session is read-only
CKF_SERIAL_SESSION	0x00000004	TRUE if cryptographic functions are performed in serial with the application; FALSE if the functions may be performed in parallel with the application
CKF_INSERTION_CALLBACK	0x00000008	this flag is write-only, i.e., is supplied as an argument to a C_OpenSession call, but is never set in a session's CK_SESSION_INFO structure. It is TRUE if the call is a request for a token insertion callback, instead of being a request to open a session

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;

When an object is created or found on a token, Cryptoki assigns it an object handle for sessions to use to access it. A particular object on a token does not necessarily have a handle which is fixed for the lifetime of the object; however, if a particular session can use a particular handle to access a particular object, then that session will continue to be able to use that handle to acces that object as long as the session continues to exist, the object continues to exist, and the object continues to be accessible to the session.

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_ULONG CK_OBJECT_CLASS;

For this version of Cryptoki, the following classes of objects are defined:

#define CKO_DATA 0x00000000
#define CKO_CERTIFICATE 0x00000001
#define CKO_PUBLIC_KEY 0x00000002
#define CKO_PRIVATE_KEY 0x00000003
#define CKO_SECRET_KEY 0x00000004
#define CKO_VENDOR_DEFINED 0x80000000

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_ULONG CK_KEY_TYPE;

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

#define CKK_RSA 0x00000000
#define CKK_DSA 0x00000001
#define CKK_DH 0x00000002
#define CKK_ECDSA 0x00000003
#define CKK_MAYFLY 0x00000004
#define CKK_KEA 0x00000005
#define CKK_GENERIC_SECRET 0x00000010
#define CKK_RC2 0x00000011
#define CKK_RC4 0x00000012
#define CKK_DES 0x00000013
#define CKK_DES2 0x00000014
#define CKK_DES3 0x00000015
#define CKK_CAST 0x00000016
#define CKK_CAST3 0x00000017
#define CKK_CAST5 0x00000018
#define CKK_RC5 0x00000019
#define CKK_IDEA 0x0000001A
#define CKK_SKIPJACK 0x0000001B
#define CKK_BATON 0x0000001C
#define CKK_JUNIPER 0x0000001D
#define CKK_CDMF 0x0000001E
#define CKK_VENDOR_DEFINED 0x80000000

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_ULONG CK_CERTIFICATE_TYPE;

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

#define CKC_X_509 0x00000000
#define CKC_VENDOR_DEFINED 0x80000000

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_ULONG CK_ATTRIBUTE_TYPE;

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

#define CKA_CLASS 0x00000000
#define CKA_TOKEN 0x00000001
#define CKA_PRIVATE 0x00000002
#define CKA_LABEL 0x00000003
#define CKA_APPLICATION 0x00000010
#define CKA_VALUE 0x00000011
#define CKA_CERTIFICATE_TYPE 0x00000080
#define CKA_ISSUER 0x00000081
#define CKA_SERIAL_NUMBER 0x00000082
#define CKA_KEY_TYPE 0x00000100
#define CKA_SUBJECT 0x00000101
#define CKA_ID 0x00000102
#define CKA_SENSITIVE 0x00000103
#define CKA_ENCRYPT 0x00000104
#define CKA_DECRYPT 0x00000105
#define CKA_WRAP 0x00000106
#define CKA_UNWRAP 0x00000107
#define CKA_SIGN 0x00000108
#define CKA_SIGN_RECOVER 0x00000109
#define CKA_VERIFY 0x0000010A
#define CKA_VERIFY_RECOVER 0x0000010B
#define CKA_DERIVE 0x0000010C
#define CKA_START_DATE 0x00000110
#define CKA_END_DATE 0x00000111
#define CKA_MODULUS 0x00000120
#define CKA_MODULUS_BITS 0x00000121
#define CKA_PUBLIC_EXPONENT 0x00000122
#define CKA_PRIVATE_EXPONENT 0x00000123
#define CKA_PRIME_1 0x00000124
#define CKA_PRIME_2 0x00000125
#define CKA_EXPONENT_1 0x00000126
#define CKA_EXPONENT_2 0x00000127
#define CKA_COEFFICIENT 0x00000128
#define CKA_PRIME 0x00000130
#define CKA_SUBPRIME 0x00000131
#define CKA_BASE 0x00000132
#define CKA_VALUE_BITS 0x00000160
#define CKA_VALUE_LEN 0x00000161
#define CKA_EXTRACTABLE 0x00000162
#define CKA_LOCAL 0x00000163
#define CKA_NEVER_EXTRACTABLE 0x00000164
#define CKA_ALWAYS_SENSITIVE 0x00000165
#define CKA_MODIFIABLE 0x00000170
#define CKA_VENDOR_DEFINED 0x80000000

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_ULONG ulValueLen;
} CK_ATTRIBUTE;

type	the attribute type
pValue	pointer to the value of the attribute
ulValueLen	length in bytes of the value

If an attribute has no value, then pValue = NULL_PTR, and ulValueLen = 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.

Data types for mechanisms

Cryptoki supports the following types for describing mechanisms and parameters to them:

CK_MECHANISM_TYPE

CK_MECHANISM_TYPE is a value that identifies a mechanism type. It is defined as follows:

typedef CK_ULONG CK_MECHANISM_TYPE;

For Cryptoki v2.0, the following mechanism types are defined:

#define CKM_RSA_PKCS_KEY_PAIR_GEN 0x00000000
#define CKM_RSA_PKCS 0x00000001
#define CKM_RSA_9796 0x00000002
#define CKM_RSA_X_509 0x00000003
#define CKM_MD2_RSA_PKCS 0x00000004
#define CKM_MD5_RSA_PKCS 0x00000005
#define CKM_SHA1_RSA_PKCS 0x00000006
#define CKM_DSA_KEY_PAIR_GEN 0x00000010
#define CKM_DSA 0x00000011
#define CKM_DSA_SHA1 0x00000012
#define CKM_DH_PKCS_KEY_PAIR_GEN 0x00000020
#define CKM_DH_PKCS_DERIVE 0x00000021
#define CKM_RC2_KEY_GEN 0x00000100
#define CKM_RC2_ECB 0x00000101
#define CKM_RC2_CBC 0x00000102
#define CKM_RC2_MAC 0x00000103
#define CKM_RC2_MAC_GENERAL 0x00000104
#define CKM_RC2_CBC_PAD 0x00000105
#define CKM_RC4_KEY_GEN 0x00000110
#define CKM_RC4 0x00000111
#define CKM_DES_KEY_GEN 0x00000120
#define CKM_DES_ECB 0x00000121
#define CKM_DES_CBC 0x00000122
#define CKM_DES_MAC 0x00000123
#define CKM_DES_MAC_GENERAL 0x00000124
#define CKM_DES_CBC_PAD 0x00000125
#define CKM_DES2_KEY_GEN 0x00000130
#define CKM_DES3_KEY_GEN 0x00000131
#define CKM_DES3_ECB 0x00000132
#define CKM_DES3_CBC 0x00000133
#define CKM_DES3_MAC 0x00000134
#define CKM_DES3_MAC_GENERAL 0x00000135
#define CKM_DES3_CBC_PAD 0x00000136
#define CKM_CDMF_KEY_GEN 0x00000140
#define CKM_CDMF_ECB 0x00000141
#define CKM_CDMF_CBC 0x00000142
#define CKM_CDMF_MAC 0x00000143
#define CKM_CDMF_MAC_GENERAL 0x00000144
#define CKM_CDMF_CBC_PAD 0x00000145
#define CKM_MD2 0x00000200
#define CKM_MD2_HMAC 0x00000201
#define CKM_MD2_HMAC_GENERAL 0x00000202
#define CKM_MD5 0x00000210
#define CKM_MD5_HMAC 0x00000211
#define CKM_MD5_HMAC_GENERAL 0x00000212
#define CKM_SHA_1 0x00000220
#define CKM_SHA_1_HMAC 0x00000221
#define CKM_SHA_1_HMAC_GENERAL 0x00000222
#define CKM_CAST_KEY_GEN 0x00000300
#define CKM_CAST_ECB 0x00000301
#define CKM_CAST_CBC 0x00000302
#define CKM_CAST_MAC 0x00000303
#define CKM_CAST_MAC_GENERAL 0x00000304
#define CKM_CAST_CBC_PAD 0x00000305
#define CKM_CAST3_KEY_GEN 0x00000310
#define CKM_CAST3_ECB 0x00000311
#define CKM_CAST3_CBC 0x00000312
#define CKM_CAST3_MAC 0x00000313
#define CKM_CAST3_MAC_GENERAL 0x00000314
#define CKM_CAST3_CBC_PAD 0x00000315
#define CKM_CAST5_KEY_GEN 0x00000320
#define CKM_CAST5_ECB 0x00000321
#define CKM_CAST5_CBC 0x00000322
#define CKM_CAST5_MAC 0x00000323
#define CKM_CAST5_MAC_GENERAL 0x00000324
#define CKM_CAST5_CBC_PAD 0x00000325
#define CKM_RC5_KEY_GEN 0x00000330
#define CKM_RC5_ECB 0x00000331
#define CKM_RC5_CBC 0x00000332
#define CKM_RC5_MAC 0x00000333
#define CKM_RC5_MAC_GENERAL 0x00000334
#define CKM_RC5_CBC_PAD 0x00000335
#define CKM_IDEA_KEY_GEN 0x00000340
#define CKM_IDEA_ECB 0x00000341
#define CKM_IDEA_CBC 0x00000342
#define CKM_IDEA_MAC 0x00000343
#define CKM_IDEA_MAC_GENERAL 0x00000344
#define CKM_IDEA_CBC_PAD 0x00000345
#define CKM_GENERIC_SECRET_KEY_GEN 0x00000350
#define CKM_CONCATENATE_BASE_AND_KEY 0x00000360
#define CKM_CONCATENATE_BASE_AND_DATA 0x00000362
#define CKM_CONCATENATE_DATA_AND_BASE 0x00000363
#define CKM_XOR_BASE_AND_DATA 0x00000364
#define CKM_EXTRACT_KEY_FROM_KEY 0x00000365
#define CKM_SSL3_PRE_MASTER_KEY_GEN 0x00000370
#define CKM_SSL3_MASTER_KEY_DERIVE 0x00000371
#define CKM_SSL3_KEY_AND_MAC_DERIVE 0x00000372
#define CKM_SSL3_MD5_MAC 0x00000380
#define CKM_SSL3_SHA1_MAC 0x00000381
#define CKM_MD5_KEY_DERIVATION 0x00000390
#define CKM_MD2_KEY_DERIVATION 0x00000391
#define CKM_SHA1_KEY_DERIVATION 0x00000392
#define CKM_PBE_MD2_DES_CBC 0x000003A0
#define CKM_PBE_MD5_DES_CBC 0x000003A1
#define CKM_PBE_MD5_CAST_CBC 0x000003A2
#define CKM_PBE_MD5_CAST3_CBC 0x000003A3
#define CKM_PBE_MD5_CAST5_CBC 0x000003A4
#define CKM_KEY_WRAP_LYNKS 0x00000400
#define CKM_KEY_WRAP_SET_OAEP 0x00000401
#define CKM_SKIPJACK_KEY_GEN 0x00001000
#define CKM_SKIPJACK_ECB64 0x00001001
#define CKM_SKIPJACK_CBC64 0x00001002
#define CKM_SKIPJACK_OFB64 0x00001003
#define CKM_SKIPJACK_CFB64 0x00001004
#define CKM_SKIPJACK_CFB32 0x00001005
#define CKM_SKIPJACK_CFB16 0x00001006
#define CKM_SKIPJACK_CFB8 0x00001007
#define CKM_SKIPJACK_WRAP 0x00001008
#define CKM_SKIPJACK_PRIVATE_WRAP 0x00001009
#define CKM_SKIPJACK_RELAYX 0x0000100a
#define CKM_KEA_KEY_PAIR_GEN 0x00001010
#define CKM_KEA_KEY_DERIVE 0x00001011
#define CKM_FORTEZZA_TIMESTAMP 0x00001020
#define CKM_BATON_KEY_GEN 0x00001030
#define CKM_BATON_ECB128 0x00001031
#define CKM_BATON_ECB96 0x00001032
#define CKM_BATON_CBC128 0x00001033
#define CKM_BATON_COUNTER 0x00001034
#define CKM_BATON_SHUFFLE 0x00001035
#define CKM_BATON_WRAP 0x00001036
#define CKM_ECDSA_KEY_PAIR_GEN 0x00001040
#define CKM_ECDSA 0x00001041
#define CKM_ECDSA_SHA1 0x00001042
#define CKM_MAYFLY_KEY_PAIR_GEN 0x00001050
#define CKM_MAYFLY_KEY_DERIVE 0x00001051
#define CKM_JUNIPER_KEY_GEN 0x00001060
#define CKM_JUNIPER_ECB128 0x00001061
#define CKM_JUNIPER_CBC128 0x00001062
#define CKM_JUNIPER_COUNTER 0x00001063
#define CKM_JUNIPER_SHUFFLE 0x00001064
#define CKM_JUNIPER_WRAP 0x00001065
#define CKM_FASTHASH 0x00001070
#define CKM_VENDOR_DEFINED 0x80000000

Mechanism types CKM_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their mechanism types through the PKCS process.

CK_MECHANISM_TYPE_PTR

CK_MECHANISM_TYPE_PTR points to a CK_MECHANISM_TYPE structure. It is implementation-dependent.

CK_MECHANISM

CK_MECHANISM is a structure that specifies a particular mechanism. It is defined as follows:

typedef struct CK_MECHANISM {
CK_MECHANISM_TYPE mechanism;
CK_VOID_PTR pParameter;
CK_ULONG ulParameterLen;
} CK_MECHANISM;

mechanism	the type of mechanism
pParameter	pointer to the parameter if required by the mechanism
usParameterLen	length in bytes of the parameter

Note that pParameter is a "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_MECHANISM_PTR

CK_MECHANISM_PTR points to a CK_MECHANISM structure. It is implementation-dependent.

CK_MECHANISM_INFO

CK_MECHANISM_INFO is a structure that provides information about a particular mechanism. It is defined as follows:

typedef struct CK_MECHANISM_INFO {
CK_ULONG ulMinKeySize;
CK_ULONG ulMaxKeySize;
CK_FLAGS flags;
} CK_MECHANISM_INFO;

ulMinKeySize	the minimum size of the key for the mechanism
ulMaxKeySize	the maximum size of the key for the mechanism
flags	bit flags specifying mechanism capabilities

For some mechanisms, the ulMinKeySize and ulMaxKeySize fields have meaningless values.

The following table defines the flags parameter:

Table 7-4, Mechanism Information Flags

Bit Flag	Mask	Meaning
CKF_HW	0x00000001	TRUE if the mechanism is performed by the device; FALSE if the mechanism is performed in software
CKF_ENCRYPT	0x00000100	TRUE if the mechanism can be used with C_EncryptInit
CKF_DECRYPT	0x00000200	TRUE if the mechanism can be used with C_DecryptInit
CKF_DIGEST	0x00000400	TRUE if the mechanism can be used with C_DigestInit
CKF_SIGN	0x00000800	TRUE if the mechanism can be used with C_SignInit
CKF_SIGN_RECOVER	0x00001000	TRUE if the mechanism can be used with C_SignRecoverInit
CKF_VERIFY	0x00002000	TRUE if the mechanism can be used with C_VerifyInit
CKF_VERIFY_RECOVER	0x00004000	TRUE if the mechanism can be used with C_VerifyRecoverInit
CKF_GENERATE	0x00008000	TRUE if the mechanism can be used with C_GenerateKey
CKF_GENERATE_KEY_PAIR	0x00010000	TRUE if the mechanism can be used with C_GenerateKeyPair
CKF_WRAP	0x00020000	TRUE if the mechanism can be used with C_WrapKey
CKF_UNWRAP	0x00040000	TRUE if the mechanism can be used with C_UnwrapKey
CKF_DERIVE	0x00080000	TRUE if the mechanism can be used with C_DeriveKey
CKF_EXTENSION	0x80000000	TRUE if an extension to the flags; FALSE if no extensions. Must be FALSE for this version.

CK_MECHANISM_INFO_PTR

CK_MECHANISM_INFO_PTR points to a CK_MECHANISM_INFO structure. It is implementation-dependent.

Function types

Cryptoki represents information about functions with the following data types:

CK_ENTRY

CK_ENTRY is not really a type. Rather, it is a string used provided to a C compiler in a given environment to produce an entry into Cryptoki (i.e., a Cryptoki function). It is implementation-dependent. For a Win32 Cryptoki .dll, it might be "__declspec( dllexport)". For a Win16 Cryptoki .dll, it might be "_export _far _pascal". For a Unix library, it might be "".

CK_RV

CK_RV is a value that identifies the return value of a Cryptoki function. It is defined as follows:

typedef CK_ULONG CK_RV;

For this version of Cryptoki, the following return values are defined:

#define CKR_OK 0x00000000
#define CKR_CANCEL 0x00000001
#define CKR_HOST_MEMORY 0x00000002
#define CKR_SLOT_ID_INVALID 0x00000003
#define CKR_GENERAL_ERROR 0x00000005
#define CKR_FUNCTION_FAILED 0x00000006
#define CKR_ATTRIBUTE_READ_ONLY 0x00000010
#define CKR_ATTRIBUTE_SENSITIVE 0x00000011
#define CKR_ATTRIBUTE_TYPE_INVALID 0x00000012
#define CKR_ATTRIBUTE_VALUE_INVALID 0x00000013
#define CKR_DATA_INVALID 0x00000020
#define CKR_DATA_LEN_RANGE 0x00000021
#define CKR_DEVICE_ERROR 0x00000030
#define CKR_DEVICE_MEMORY 0x00000031
#define CKR_DEVICE_REMOVED 0x00000032
#define CKR_ENCRYPTED_DATA_INVALID 0x00000040
#define CKR_ENCRYPTED_DATA_LEN_RANGE 0x00000041
#define CKR_FUNCTION_CANCELED 0x00000050
#define CKR_FUNCTION_NOT_PARALLEL 0x00000051
#define CKR_FUNCTION_PARALLEL 0x00000052
#define CKR_FUNCTION_NOT_SUPPORTED 0x00000054
#define CKR_KEY_HANDLE_INVALID 0x00000060
#define CKR_KEY_SIZE_RANGE 0x00000062
#define CKR_KEY_TYPE_INCONSISTENT 0x00000063
#define CKR_KEY_NOT_NEEDED 0x00000064
#define CKR_KEY_CHANGED 0x00000065
#define CKR_KEY_NEEDED 0x00000066
#define CKR_KEY_INDIGESTIBLE 0x00000067
#define CKR_KEY_FUNCTION_NOT_PERMITTED 0x00000068
#define CKR_KEY_NOT_WRAPPABLE 0x00000069
#define CKR_KEY_UNEXTRACTABLE 0x0000006A
#define CKR_MECHANISM_INVALID 0x00000070
#define CKR_MECHANISM_PARAM_INVALID 0x00000071
#define CKR_OBJECT_HANDLE_INVALID 0x00000082
#define CKR_OPERATION_ACTIVE 0x00000090
#define CKR_OPERATION_NOT_INITIALIZED 0x00000091
#define CKR_PIN_INCORRECT 0x000000A0
#define CKR_PIN_INVALID 0x000000A1
#define CKR_PIN_LEN_RANGE 0x000000A2
#define CKR_SESSION_CLOSED 0x000000B0
#define CKR_SESSION_COUNT 0x000000B1
#define CKR_SESSION_EXCLUSIVE_EXISTS 0x000000B2
#define CKR_SESSION_HANDLE_INVALID 0x000000B3
#define CKR_SESSION_PARALLEL_NOT_SUPPORTED 0x000000B4
#define CKR_SESSION_READ_ONLY 0x000000B5
#define CKR_SESSION_EXISTS 0x000000B6
#define CKR_SESSION_READ_ONLY_EXISTS 0x000000B7
#define CKR_SESSION_READ_WRITE_SO_EXISTS 0x000000B8
#define CKR_SIGNATURE_INVALID 0x000000C0
#define CKR_SIGNATURE_LEN_RANGE 0x000000C1
#define CKR_TEMPLATE_INCOMPLETE 0x000000D0
#define CKR_TEMPLATE_INCONSISTENT 0x000000D1
#define CKR_TOKEN_NOT_PRESENT 0x000000E0
#define CKR_TOKEN_NOT_RECOGNIZED 0x000000E1
#define CKR_TOKEN_WRITE_PROTECTED 0x000000E2
#define CKR_UNWRAPPING_KEY_HANDLE_INVALID 0x000000F0
#define CKR_UNWRAPPING_KEY_SIZE_RANGE 0x000000F1
#define CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT 0x000000F2
#define CKR_USER_ALREADY_LOGGED_IN 0x00000100
#define CKR_USER_NOT_LOGGED_IN 0x00000101
#define CKR_USER_PIN_NOT_INITIALIZED 0x00000102
#define CKR_USER_TYPE_INVALID 0x00000103
#define CKR_WRAPPED_KEY_INVALID 0x00000110
#define CKR_WRAPPED_KEY_LEN_RANGE 0x00000112
#define CKR_WRAPPING_KEY_HANDLE_INVALID 0x00000113
#define CKR_WRAPPING_KEY_SIZE_RANGE 0x00000114
#define CKR_WRAPPING_KEY_TYPE_INCONSISTENT 0x00000115
#define CKR_RANDOM_SEED_NOT_SUPPORTED 0x00000120
#define CKR_RANDOM_NO_RNG 0x00000121
#define CKR_INSERTION_CALLBACK_NOT_SUPPORTED 0x00000141
#define CKR_BUFFER_TOO_SMALL 0x00000150
#define CKR_SAVED_STATE_INVALID 0x00000160
#define CKR_INFORMATION_SENSITIVE 0x00000170
#define CKR_STATE_UNSAVEABLE 0x00000180
#define CKR_VENDOR_DEFINED 0x80000000

Section defines the meaning of each CK_RV value. Return values CKR_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their return values through the PKCS process.

CK_NOTIFY

CK_NOTIFY is the type of a pointer to a function used by Cryptoki to perform notification callbacks. It is implementation-dependent, but it is typically defined as follows, where CK_PTR is the C string used to create function pointers (e.g., "*"):

typedef CK_RV (CK_ENTRY * CK_NOTIFY)(
CK_SESSION_HANDLE hSession,
CK_NOTIFICATION event,
CK_VOID_PTR pApplication
);

The arguments to a notification callback function have the following meanings:

hSession The handle of the session performing the callback

event The type of notification callback

pApplication An application-defined value. This is the same value as was passed to C_OpenSession to open the session performing the callback

Cryptoki also defines an entire family of other function pointer types. For each function C_XXX in the Cryptoki API (there are 67 such functions in Cryptoki v2.0; see Section for detailed information about each of them), Cryptoki defines a type CK_C_XXX, which is a pointer to a function of C_XXX 's type.

CK_FUNCTION_LIST

CK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each function in the Cryptoki API. It is defined as follows:

typedef struct CK_FUNCTION_LIST {
CK_VERSION version;
CK_C_Initialize C_Initialize;
CK_C_Finalize C_Finalize;
CK_C_GetInfo C_GetInfo;
CK_C_GetFunctionList C_GetFunctionList;
CK_C_GetSlotList C_GetSlotList;
CK_C_GetSlotInfo C_GetSlotInfo;
CK_C_GetTokenInfo C_GetTokenInfo;
CK_C_GetMechanismList C_GetMechanismList;
CK_C_GetMechanismInfo C_GetMechanismInfo;
CK_C_InitToken C_InitToken;
CK_C_InitPIN C_InitPIN;
CK_C_SetPIN C_SetPIN;
CK_C_OpenSession C_OpenSession;
CK_C_CloseSession C_CloseSession;
CK_C_CloseAllSessions C_CloseAllSessions;
CK_C_GetSessionInfo C_GetSessionInfo;
CK_C_GetOperationState C_GetOperationState;
CK_C_SetOperationState C_SetOperationState;
CK_C_Login C_Login;
CK_C_Logout C_Logout;
CK_C_CreateObject C_CreateObject;
CK_C_CopyObject C_CopyObject;
CK_C_DestroyObject C_DestroyObject;
CK_C_GetObjectSize C_GetObjectSize;
CK_C_GetAttributeValue C_GetAttributeValue;
CK_C_SetAttributeValue C_SetAttributeValue;
CK_C_FindObjectsInit C_FindObjectsInit;
CK_C_FindObjects C_FindObjects;
CK_C_FindObjectsFinal C_FindObjectsFinal;
CK_C_EncryptInit C_EncryptInit;
CK_C_Encrypt C_Encrypt;
CK_C_EncryptUpdate C_EncryptUpdate;
CK_C_EncryptFinal C_EncryptFinal;
CK_C_DecryptInit C_DecryptInit;
CK_C_Decrypt C_Decrypt;
CK_C_DecryptUpdate C_DecryptUpdate;
CK_C_DecryptFinal C_DecryptFinal;
CK_C_DigestInit C_DigestInit;
CK_C_Digest C_Digest;
CK_C_DigestUpdate C_DigestUpdate;
CK_C_DigestKey C_DigestKey;
CK_C_DigestFinal C_DigestFinal;
CK_C_SignInit C_SignInit;
CK_C_Sign C_Sign;
CK_C_SignUpdate C_SignUpdate;
CK_C_SignFinal C_SignFinal;
CK_C_SignRecoverInit C_SignRecoverInit;
CK_C_SignRecover C_SignRecover;
CK_C_VerifyInit C_VerifyInit;
CK_C_Verify C_Verify;
CK_C_VerifyUpdate C_VerifyUpdate;
CK_C_VerifyFinal C_VerifyFinal;
CK_C_VerifyRecoverInit C_VerifyRecoverInit;
CK_C_VerifyRecover C_VerifyRecover;
CK_C_DigestEncryptUpdate C_DigestEncryptUpdate;
CK_C_DecryptDigestUpdate C_DecryptDigestUpdate;
CK_C_SignEncryptUpdate C_SignEncryptUpdate;
CK_C_DecryptVerifyUpdate C_DecryptVerifyUpdate;
CK_C_GenerateKey C_GenerateKey;
CK_C_GenerateKeyPair C_GenerateKeyPair;
CK_C_WrapKey C_WrapKey;
CK_C_UnwrapKey C_UnwrapKey;
CK_C_DeriveKey C_DeriveKey;
CK_C_SeedRandom C_SeedRandom;
CK_C_GenerateRandom C_GenerateRandom;
CK_C_GetFunctionStatus C_GetFunctionStatus;
CK_C_CancelFunction C_CancelFunction;
} CK_FUNCTION_LIST;

CK_FUNCTION_LIST_PTR

CK_FUNCTION_LIST_PTR points to a CK_FUNCTION_LIST. It is implementation-dependent.

CK_FUNCTION_LIST_PTR_PTR

CK_FUNCTION_LIST_PTR_PTR points to a CK_FUNCTION_LIST_PTR. It is implementation-dependent.

---

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