Copyright 1994-2004 RSA Security Inc. License to copy this document is granted provided that it is
identified as “RSA Security Inc. Public-Key Cryptography Standards (PKCS)” in all material mentioning
or referencing this document.
PKCS #11 v2.20: Cryptographic Token Interface Standard
RSA Laboratories
28 June 2004
Table of Contents
1 INTRODUCTION ............................................................................................................................ 1
2 SCOPE ............................................................................................................................................... 2
3 REFERENCES.................................................................................................................................. 3
4 DEFINITIONS .................................................................................................................................. 7
5 SYMBOLS AND ABBREVIATIONS........................................................................................... 10
6 GENERAL OVERVIEW ............................................................................................................... 12
6.1 INTRODUCTION......................................................................................................................... 12
6.2 DESIGN GOALS ......................................................................................................................... 13
6.3 GENERAL MODEL ..................................................................................................................... 13
6.4 LOGICAL VIEW OF A TOKEN ...................................................................................................... 15
6.5 USERS ...................................................................................................................................... 16
6.6 APPLICATIONS AND THEIR USE OF CRYPTOKI ........................................................................... 17
6.6.1 Applications and processes ................................................................................................ 17
6.6.2 Applications and threads.................................................................................................... 18
6.7 SESSIONS.................................................................................................................................. 19
6.7.1 Read-only session states ..................................................................................................... 19
6.7.2 Read/write session states .................................................................................................... 20
6.7.3 Permitted object accesses by sessions ................................................................................ 21
6.7.4 Session events ..................................................................................................................... 22
6.7.5 Session handles and object handles.................................................................................... 23
6.7.6 Capabilities of sessions ...................................................................................................... 23
6.7.7 Example of use of sessions.................................................................................................. 24
6.8 SECONDARY AUTHENTICATION (DEPRECATED)........................................................................ 26
6.9 FUNCTION OVERVIEW............................................................................................................... 27
7 SECURITY CONSIDERATIONS ................................................................................................ 30
8 PLATFORM- AND COMPILER-DEPENDENT DIRECTIVES FOR C OR C++ ................. 31
8.1 STRUCTURE PACKING ............................................................................................................... 31
8.2 POINTER-RELATED MACROS ..................................................................................................... 32
♦
CK_PTR .................................................................................................................................. 32
♦
CK_DEFINE_FUNCTION...................................................................................................... 32
♦
CK_DECLARE_FUNCTION .................................................................................................. 32
♦
CK_DECLARE_FUNCTION_POINTER ................................................................................ 32
ii PKCS #11 V2.20: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD
Copyright © 2004 RSA Security Inc. June 2004
♦
CK_CALLBACK_FUNCTION ................................................................................................ 33
♦
NULL_PTR.............................................................................................................................. 33
8.3 SAMPLE PLATFORM- AND COMPILER-DEPENDENT CODE........................................................... 33
8.3.1 Win32.................................................................................................................................. 33
8.3.2 Win16.................................................................................................................................. 34
8.3.3 Generic UNIX..................................................................................................................... 35
9 GENERAL DATA TYPES............................................................................................................. 36
9.1 GENERAL INFORMATION .......................................................................................................... 36
♦
CK_VERSION; CK_VERSION_PTR ...................................................................................... 36
♦
CK_INFO; CK_INFO_PTR .................................................................................................... 37
♦
CK_NOTIFICATION .............................................................................................................. 38
9.2 SLOT AND TOKEN TYPES........................................................................................................... 38
♦
CK_SLOT_ID; CK_SLOT_ID_PTR........................................................................................ 38
♦
CK_SLOT_INFO; CK_SLOT_INFO_PTR.............................................................................. 39
♦
CK_TOKEN_INFO; CK_TOKEN_INFO_PTR....................................................................... 40
9.3 SESSION TYPES ......................................................................................................................... 46
♦
CK_SESSION_HANDLE; CK_SESSION_HANDLE_PTR ..................................................... 46
♦
CK_USER_TYPE ....................................................................................................................46
♦
CK_STATE .............................................................................................................................. 47
♦
CK_SESSION_INFO; CK_SESSION_INFO_PTR.................................................................. 47
9.4 OBJECT TYPES .......................................................................................................................... 48
♦
CK_OBJECT_HANDLE; CK_OBJECT_HANDLE_PTR ....................................................... 48
♦
CK_OBJECT_CLASS; CK_OBJECT_CLASS_PTR ............................................................... 48
♦
CK_HW_FEATURE_TYPE..................................................................................................... 49
♦
CK_KEY_TYPE....................................................................................................................... 49
♦
CK_CERTIFICATE_TYPE...................................................................................................... 50
♦
CK_ATTRIBUTE_TYPE.......................................................................................................... 50
♦
CK_ATTRIBUTE; CK_ATTRIBUTE_PTR.............................................................................. 51
♦
CK_DATE................................................................................................................................ 51
9.5 DATA TYPES FOR MECHANISMS ................................................................................................ 52
♦
CK_MECHANISM_TYPE; CK_MECHANISM_TYPE_PTR .................................................. 52
♦
CK_MECHANISM; CK_MECHANISM_PTR......................................................................... 52
♦
CK_MECHANISM_INFO; CK_MECHANISM_INFO_PTR .................................................. 53
9.6 FUNCTION TYPES...................................................................................................................... 54
♦
CK_RV..................................................................................................................................... 55
♦
CK_NOTIFY............................................................................................................................ 55
♦
CK_C_XXX.............................................................................................................................. 55
♦
CK_FUNCTION_LIST; CK_FUNCTION_LIST_PTR; CK_FUNCTION_LIST_PTR_PTR... 56
9.7 LOCKING-RELATED TYPES........................................................................................................ 58
♦
CK_CREATEMUTEX.............................................................................................................. 58
♦
CK_DESTROYMUTEX ........................................................................................................... 58
♦
CK_LOCKMUTEX and CK_UNLOCKMUTEX ..................................................................... 58
♦
CK_C_INITIALIZE_ARGS; CK_C_INITIALIZE_ARGS_PTR ............................................... 60
10 OBJECTS ........................................................................................................................................ 62
10.1 CREATING, MODIFYING, AND COPYING OBJECTS ...................................................................... 63
10.1.1 Creating objects............................................................................................................. 63
10.1.2 Modifying objects........................................................................................................... 65
10.1.3 Copying objects ............................................................................................................. 65
10.2 COMMON ATTRIBUTES.............................................................................................................. 66
10.3 HARDWARE FEATURE OBJECTS................................................................................................ 67
10.3.1 Definitions...................................................................................................................... 67
iii
June 2004 Copyright © 2004 RSA Security Inc.
10.3.2
Overview ........................................................................................................................67
10.3.3 Clock.............................................................................................................................. 67
10.3.4 Monotonic Counter Objects........................................................................................... 68
10.3.5 User Interface Objects ................................................................................................... 69
10.4 STORAGE OBJECTS ................................................................................................................... 71
10.5 DATA OBJECTS ......................................................................................................................... 72
10.5.1 Definitions...................................................................................................................... 72
10.5.2 Overview ........................................................................................................................72
10.6 CERTIFICATE OBJECTS.............................................................................................................. 73
10.6.1 Definitions...................................................................................................................... 73
10.6.2 Overview ........................................................................................................................73
10.6.3 X.509 public key certificate objects ............................................................................... 74
10.6.4 WTLS public key certificate objects............................................................................... 76
10.6.5 X.509 attribute certificate objects.................................................................................. 78
10.7 KEY OBJECTS ........................................................................................................................... 79
10.7.1 Definitions...................................................................................................................... 79
10.7.2 Overview ........................................................................................................................79
10.8 PUBLIC KEY OBJECTS................................................................................................................ 81
10.9 PRIVATE KEY OBJECTS ............................................................................................................. 82
10.10 SECRET KEY OBJECTS ............................................................................................................... 84
10.11 DOMAIN PARAMETER OBJECTS ................................................................................................. 87
10.11.1 Definitions...................................................................................................................... 87
10.11.2 Overview ........................................................................................................................87
10.12 MECHANISM OBJECTS............................................................................................................... 88
10.12.1 Definitions...................................................................................................................... 88
10.12.2 Overview ........................................................................................................................88
11 FUNCTIONS................................................................................................................................... 89
11.1 FUNCTION RETURN VALUES...................................................................................................... 90
11.1.1 Universal Cryptoki function return values .................................................................... 90
11.1.2 Cryptoki function return values for functions that use a session handle ....................... 91
11.1.3 Cryptoki function return values for functions that use a token...................................... 92
11.1.4 Special return value for application-supplied callbacks ............................................... 92
11.1.5 Special return values for mutex-handling functions ...................................................... 93
11.1.6 All other Cryptoki function return values ...................................................................... 93
11.1.7 More on relative priorities of Cryptoki errors............................................................. 100
11.1.8 Error code “gotchas”.................................................................................................. 101
11.2 CONVENTIONS FOR FUNCTIONS RETURNING OUTPUT IN A VARIABLE-LENGTH BUFFER ........... 101
11.3 DISCLAIMER CONCERNING SAMPLE CODE............................................................................... 102
11.4 GENERAL-PURPOSE FUNCTIONS.............................................................................................. 102
♦
C_Initialize ............................................................................................................................ 102
♦
C_Finalize ............................................................................................................................. 104
♦
C_GetInfo.............................................................................................................................. 105
♦
C_GetFunctionList ................................................................................................................ 106
11.5 SLOT AND TOKEN MANAGEMENT FUNCTIONS ......................................................................... 106
♦
C_GetSlotList ........................................................................................................................ 106
♦
C_GetSlotInfo........................................................................................................................ 108
♦
C_GetTokenInfo .................................................................................................................... 109
♦
C_WaitForSlotEvent ............................................................................................................. 110
♦
C_GetMechanismList ............................................................................................................ 111
♦
C_GetMechanismInfo............................................................................................................ 112
♦
C_InitToken........................................................................................................................... 113
♦
C_InitPIN .............................................................................................................................. 115
♦
C_SetPIN............................................................................................................................... 116
iv PKCS #11 V2.20: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD
Copyright © 2004 RSA Security Inc. June 2004
11.6
SESSION MANAGEMENT FUNCTIONS ....................................................................................... 117
♦
C_OpenSession...................................................................................................................... 117
♦
C_CloseSession ..................................................................................................................... 118
♦
C_CloseAllSessions............................................................................................................... 120
♦
C_GetSessionInfo .................................................................................................................. 120
♦
C_GetOperationState ............................................................................................................ 121
♦
C_SetOperationState............................................................................................................. 123
♦
C_Login................................................................................................................................. 125
♦
C_Logout............................................................................................................................... 127
11.7 OBJECT MANAGEMENT FUNCTIONS ........................................................................................ 128
♦
C_CreateObject..................................................................................................................... 128
♦
C_CopyObject ....................................................................................................................... 130
♦
C_DestroyObject................................................................................................................... 131
♦
C_GetObjectSize ................................................................................................................... 132
♦
C_GetAttributeValue............................................................................................................. 133
♦
C_SetAttributeValue.............................................................................................................. 135
♦
C_FindObjectsInit................................................................................................................. 136
♦
C_FindObjects ...................................................................................................................... 137
♦
C_FindObjectsFinal.............................................................................................................. 138
11.8 ENCRYPTION FUNCTIONS........................................................................................................ 139
♦
C_EncryptInit ........................................................................................................................ 139
♦
C_Encrypt.............................................................................................................................. 140
♦
C_EncryptUpdate.................................................................................................................. 141
♦
C_EncryptFinal..................................................................................................................... 141
11.9 DECRYPTION FUNCTIONS........................................................................................................ 144
♦
C_DecryptInit........................................................................................................................ 144
♦
C_Decrypt ............................................................................................................................. 145
♦
C_DecryptUpdate.................................................................................................................. 146
♦
C_DecryptFinal..................................................................................................................... 146
11.10 MESSAGE DIGESTING FUNCTIONS ........................................................................................... 148
♦
C_DigestInit .......................................................................................................................... 148
♦
C_Digest................................................................................................................................ 149
♦
C_DigestUpdate .................................................................................................................... 150
♦
C_DigestKey.......................................................................................................................... 150
♦
C_DigestFinal ....................................................................................................................... 151
11.11 SIGNING AND MACING FUNCTIONS........................................................................................ 152
♦
C_SignInit ............................................................................................................................. 152
♦
C_Sign ................................................................................................................................... 153
♦
C_SignUpdate ....................................................................................................................... 154
♦
C_SignFinal .......................................................................................................................... 154
♦
C_SignRecoverInit ................................................................................................................ 155
♦
C_SignRecover ...................................................................................................................... 156
11.12 FUNCTIONS FOR VERIFYING SIGNATURES AND MACS ............................................................ 157
♦
C_VerifyInit........................................................................................................................... 157
♦
C_Verify ................................................................................................................................ 158
♦
C_VerifyUpdate..................................................................................................................... 159
♦
C_VerifyFinal........................................................................................................................ 159
♦
C_VerifyRecoverInit.............................................................................................................. 161
♦
C_VerifyRecover ................................................................................................................... 161
11.13 DUAL-FUNCTION CRYPTOGRAPHIC FUNCTIONS ...................................................................... 163
♦
C_DigestEncryptUpdate ....................................................................................................... 163
♦
C_DecryptDigestUpdate ....................................................................................................... 165
v
June 2004 Copyright © 2004 RSA Security Inc.
♦
C_SignEncryptUpdate........................................................................................................... 169
♦
C_DecryptVerifyUpdate........................................................................................................ 171
11.14 KEY MANAGEMENT FUNCTIONS ............................................................................................. 174
♦
C_GenerateKey ..................................................................................................................... 175
♦
C_GenerateKeyPair .............................................................................................................. 176
♦
C_WrapKey ........................................................................................................................... 178
♦
C_UnwrapKey....................................................................................................................... 180
♦
C_DeriveKey ......................................................................................................................... 182
11.15 RANDOM NUMBER GENERATION FUNCTIONS .......................................................................... 184
♦
C_SeedRandom ..................................................................................................................... 184
♦
C_GenerateRandom .............................................................................................................. 184
11.16 PARALLEL FUNCTION MANAGEMENT FUNCTIONS ................................................................... 185
♦
C_GetFunctionStatus ............................................................................................................ 185
♦
C_CancelFunction ................................................................................................................ 186
11.17 CALLBACK FUNCTIONS........................................................................................................... 186
11.17.1 Surrender callbacks ..................................................................................................... 186
11.17.2 Vendor-defined callbacks ............................................................................................ 187
12 MECHANISMS ............................................................................................................................ 188
12.1 RSA ....................................................................................................................................... 193
12.1.1 Definitions.................................................................................................................... 193
12.1.2 RSA public key objects................................................................................................. 193
12.1.3 RSA private key objects................................................................................................ 194
12.1.4 PKCS #1 RSA key pair generation .............................................................................. 196
12.1.5 X9.31 RSA key pair generation.................................................................................... 197
12.1.6 PKCS #1 v1.5 RSA....................................................................................................... 197
12.1.7 PKCS #1 RSA OAEP mechanism parameters ............................................................. 198
♦
CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR.................................... 198
♦
CK_RSA_PKCS_OAEP_SOURCE_TYPE; CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR199
♦
CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR ..................... 200
12.1.8 PKCS #1 RSA OAEP ................................................................................................... 200
12.1.9 PKCS #1 RSA PSS mechanism parameters ................................................................. 201
♦
CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR............................. 201
12.1.10 PKCS #1 RSA PSS ....................................................................................................... 202
12.1.11 ISO/IEC 9796 RSA....................................................................................................... 203
12.1.12 X.509 (raw) RSA .......................................................................................................... 203
12.1.13 ANSI X9.31 RSA........................................................................................................... 205
12.1.14 PKCS #1 v1.5 RSA signature with MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512,
RIPE-MD 128 or RIPE-MD 160 .................................................................................................... 206
12.1.15 PKCS #1 RSA PSS signature with SHA-1, SHA-256, SHA-384 or SHA-512 .............. 207
12.1.16 ANSI X9.31 RSA signature with SHA-1 ....................................................................... 208
12.2 DSA....................................................................................................................................... 209
12.2.1 Definitions.................................................................................................................... 209
12.2.2 DSA public key objects ................................................................................................ 209
12.2.3 DSA private key objects ............................................................................................... 210
12.2.4 DSA domain parameter objects ................................................................................... 211
12.2.5 DSA key pair generation.............................................................................................. 212
12.2.6 DSA domain parameter generation ............................................................................. 212
12.2.7 DSA without hashing ................................................................................................... 213
12.2.8 DSA with SHA-1 .......................................................................................................... 213
12.2.9 FORTEZZA timestamp................................................................................................. 214
12.3 ELLIPTIC CURVE..................................................................................................................... 214
12.3.1 EC Signatures .............................................................................................................. 216
12.3.2 Definitions.................................................................................................................... 216
