PKCS #11 v2.11: Cryptographic Token Interface Standard
RSA Laboratories
Revision 1
November 2001
Table of Contents
APPENDIX A: INTRODUCTION..............................................................................................................1
APPENDIX B: SCOPE.................................................................................................................................2
APPENDIX C: REFERENCES...................................................................................................................3
APPENDIX D: DEFINITIONS....................................................................................................................6
APPENDIX E: SYMBOLS AND ABBREVIATIONS..............................................................................8
APPENDIX F: GENERAL OVERVIEW.................................................................................................12
F.1 DESIGN GOALS....................................................................................................................................12
F.2 GENERAL MODEL................................................................................................................................12
F.3 LOGICAL VIEW OF A TOKEN................................................................................................................14
F.4 USERS..................................................................................................................................................15
F.5 APPLICATIONS AND THEIR USE OF CRYPTOKI.....................................................................................16
F.5.1 Applications and processes........................................................................................................16
F.5.2 Applications and threads...........................................................................................................17
F.6 SESSIONS.............................................................................................................................................18
F.6.1 Read-only session states............................................................................................................18
F.6.2 Read/write session states...........................................................................................................19
F.6.3 Permitted object accesses by sessions.......................................................................................20
F.6.4 Session events.............................................................................................................................21
F.6.5 Session handles and object handles..........................................................................................22
F.6.6 Capabilities of sessions..............................................................................................................22
F.6.7 Example of use of sessions.........................................................................................................23
F.7 SECONDARY AUTHENTICATION (DEPRECATED)..................................................................................26
F.7.1 Using keys protected by secondary authentication...................................................................26
F.7.2 Generating private keys protected by secondary authentication.............................................27
F.7.3 Changing the secondary authentication PIN value..................................................................27
F.7.4 Secondary authentication PIN collection mechanisms.............................................................27
F.8 FUNCTION OVERVIEW..........................................................................................................................28
APPENDIX G: SECURITY CONSIDERATIONS..................................................................................31
APPENDIX H: PLATFORM- AND COMPILER-DEPENDENT DIRECTIVES FOR C OR C++. 32
H.1 STRUCTURE PACKING.........................................................................................................................32
H.2 POINTER-RELATED MACROS...............................................................................................................33
CK_PTR...............................................................................................................................................33
Copyright 1994-2001 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 #1 v2.11 r1 001-903053-211-001-000
II PKCS #11 V2.11: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD
CK_DEFINE_FUNCTION..................................................................................................................33
CK_DECLARE_FUNCTION...............................................................................................................33
CK_DECLARE_FUNCTION_POINTER............................................................................................33
CK_CALLBACK_FUNCTION............................................................................................................34
NULL_PTR..........................................................................................................................................34
H.3 SAMPLE PLATFORM- AND COMPILER-DEPENDENT CODE.....................................................................35
H.3.1 Win32.........................................................................................................................................35
H.3.2 Win16.........................................................................................................................................36
H.3.3 Generic UNIX............................................................................................................................36
APPENDIX I: GENERAL DATA TYPES...............................................................................................37
I.1 GENERAL INFORMATION......................................................................................................................37
CK_VERSION; CK_VERSION_PTR..................................................................................................37
CK_INFO; CK_INFO_PTR................................................................................................................38
CK_NOTIFICATION...........................................................................................................................39
I.2 SLOT AND TOKEN TYPES......................................................................................................................39
CK_SLOT_ID; CK_SLOT_ID_PTR....................................................................................................39
CK_SLOT_INFO; CK_SLOT_INFO_PTR..........................................................................................40
CK_TOKEN_INFO; CK_TOKEN_INFO_PTR..................................................................................41
I.3 SESSION TYPES.....................................................................................................................................48
CK_SESSION_HANDLE; CK_SESSION_HANDLE_PTR.................................................................48
CK_USER_TYPE.................................................................................................................................48
CK_STATE...........................................................................................................................................49
CK_SESSION_INFO; CK_SESSION_INFO_PTR.............................................................................49
I.4 OBJECT TYPES......................................................................................................................................50
CK_OBJECT_HANDLE; CK_OBJECT_HANDLE_PTR...................................................................50
CK_OBJECT_CLASS; CK_OBJECT_CLASS_PTR...........................................................................50
CK_HW_FEATURE_TYPE.................................................................................................................51
CK_KEY_TYPE...................................................................................................................................51
CK_CERTIFICATE_TYPE..................................................................................................................52
CK_ATTRIBUTE_TYPE......................................................................................................................53
CK_ATTRIBUTE; CK_ATTRIBUTE_PTR..........................................................................................54
CK_DATE............................................................................................................................................55
I.5 DATA TYPES FOR MECHANISMS............................................................................................................55
CK_MECHANISM_TYPE; CK_MECHANISM_TYPE_PTR..............................................................55
CK_MECHANISM; CK_MECHANISM_PTR.....................................................................................60
CK_MECHANISM_INFO; CK_MECHANISM_INFO_PTR..............................................................60
I.6 FUNCTION TYPES..................................................................................................................................63
CK_RV.................................................................................................................................................63
CK_NOTIFY........................................................................................................................................65
CK_C_XXX..........................................................................................................................................66
CK_FUNCTION_LIST; CK_FUNCTION_LIST_PTR; CK_FUNCTION_LIST_PTR_PTR..............66
I.7 LOCKING-RELATED TYPES....................................................................................................................68
CK_CREATEMUTEX..........................................................................................................................68
CK_DESTROYMUTEX........................................................................................................................68
CK_LOCKMUTEX and CK_UNLOCKMUTEX.................................................................................69
CK_C_INITIALIZE_ARGS; CK_C_INITIALIZE_ARGS_PTR...........................................................70
APPENDIX J: OBJECTS...........................................................................................................................72
J.1 CREATING, MODIFYING, AND COPYING OBJECTS.................................................................................73
J.1.1 Creating objects..........................................................................................................................73
J.1.2 Modifying objects.......................................................................................................................75
J.1.3 Copying objects..........................................................................................................................75
J.2 COMMON ATTRIBUTES.........................................................................................................................76
J.3 HARDWARE FEATURE OBJECTS...........................................................................................................76
J.3.1 Clock Objects..............................................................................................................................77
Copyright © 1994-2001 RSA Security Inc. Revision 1, November 2001
III
J.3.2 Monotonic Counter Objects.......................................................................................................78
J.4 STORAGE OBJECTS...............................................................................................................................79
J.5 DATA OBJECTS.....................................................................................................................................79
J.6 CERTIFICATE OBJECTS..........................................................................................................................81
J.6.1 X.509 attribute certificate objects..............................................................................................83
J.7 KEY OBJECTS.......................................................................................................................................85
J.8 PUBLIC KEY OBJECTS...........................................................................................................................87
J.8.1 RSA public key objects...............................................................................................................88
J.8.2 DSA public key objects...............................................................................................................89
J.8.3 ECDSA public key objects..........................................................................................................90
J.8.4 Diffie-Hellman public key objects..............................................................................................91
J.8.5 X9.42 Diffie-Hellman public key objects...................................................................................92
J.8.6 KEA public key objects...............................................................................................................93
J.9 PRIVATE KEY OBJECTS.........................................................................................................................94
J.9.1 RSA private key objects..............................................................................................................97
J.9.2 DSA private key objects..............................................................................................................99
J.9.3 Elliptic curve private key objects.............................................................................................100
J.9.4 Diffie-Hellman private key objects..........................................................................................101
J.9.5 X9.42 Diffie-Hellman private key objects................................................................................102
J.9.6 KEA private key objects...........................................................................................................104
J.10 SECRET KEY OBJECTS.......................................................................................................................105
J.10.1 Generic secret key objects......................................................................................................107
J.10.2 RC2 secret key objects............................................................................................................107
J.10.3 RC4 secret key objects............................................................................................................108
J.10.4 RC5 secret key objects............................................................................................................109
J.10.5 AES secret key objects............................................................................................................109
J.10.6 DES secret key objects...........................................................................................................110
J.10.7 DES2 secret key objects.........................................................................................................111
J.10.8 DES3 secret key objects.........................................................................................................112
J.10.9 CAST secret key objects.........................................................................................................112
J.10.10 CAST3 secret key objects.....................................................................................................113
J.10.11 CAST128 (CAST5) secret key objects..................................................................................114
J.10.12 IDEA secret key objects.......................................................................................................114
J.10.13 CDMF secret key objects.....................................................................................................115
J.10.14 SKIPJACK secret key objects..............................................................................................116
J.10.15 BATON secret key objects....................................................................................................117
J.10.16 JUNIPER secret key objects................................................................................................118
J.11 DOMAIN PARAMETER OBJECTS.........................................................................................................120
J.11.1 DSA domain parameter objects..............................................................................................121
J.11.2 Diffie-Hellman domain parameter objects............................................................................122
J.11.3 X9.42 Diffie-Hellman domain parameters objects................................................................123
APPENDIX K: FUNCTIONS..................................................................................................................125
K.1 FUNCTION RETURN VALUES..............................................................................................................126
K.1.1 Universal Cryptoki function return values.............................................................................126
K.1.2 Cryptoki function return values for functions that use a session handle..............................127
K.1.3 Cryptoki function return values for functions that use a token.............................................128
K.1.4 Special return value for application-supplied callbacks.......................................................128
K.1.5 Special return values for mutex-handling functions..............................................................129
K.1.6 All other Cryptoki function return values..............................................................................129
K.1.7 More on relative priorities of Cryptoki errors.......................................................................136
K.1.8 Error code “gotchas”.............................................................................................................137
K.2 CONVENTIONS FOR FUNCTIONS RETURNING OUTPUT IN A VARIABLE-LENGTH BUFFER...................137
K.3 DISCLAIMER CONCERNING SAMPLE CODE........................................................................................138
K.4 GENERAL-PURPOSE FUNCTIONS........................................................................................................138
C_Initialize........................................................................................................................................138
Revision 1, November 2001 Copyright © 1994-2001 RSA Security Inc.
IV PKCS #11 V2.11: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD
C_Finalize..........................................................................................................................................140
C_GetInfo...........................................................................................................................................141
C_GetFunctionList............................................................................................................................142
K.5 SLOT AND TOKEN MANAGEMENT FUNCTIONS...................................................................................142
C_GetSlotList.....................................................................................................................................142
C_GetSlotInfo....................................................................................................................................144
C_GetTokenInfo.................................................................................................................................145
C_WaitForSlotEvent..........................................................................................................................146
C_GetMechanismList........................................................................................................................147
C_GetMechanismInfo........................................................................................................................149
C_InitToken.......................................................................................................................................149
C_InitPIN...........................................................................................................................................151
C_SetPIN...........................................................................................................................................152
K.6 SESSION MANAGEMENT FUNCTIONS.................................................................................................154
C_OpenSession..................................................................................................................................154
C_CloseSession..................................................................................................................................155
C_CloseAllSessions...........................................................................................................................156
C_GetSessionInfo..............................................................................................................................157
C_GetOperationState........................................................................................................................158
C_SetOperationState.........................................................................................................................159
C_Login..............................................................................................................................................162
C_Logout...........................................................................................................................................163
K.7 OBJECT MANAGEMENT FUNCTIONS..................................................................................................164
C_CreateObject.................................................................................................................................165
C_CopyObject....................................................................................................................................167
C_DestroyObject...............................................................................................................................169
C_GetObjectSize................................................................................................................................169
C_GetAttributeValue.........................................................................................................................170
C_SetAttributeValue..........................................................................................................................173
C_FindObjectsInit.............................................................................................................................174
C_FindObjects...................................................................................................................................175
C_FindObjectsFinal..........................................................................................................................175
K.8 ENCRYPTION FUNCTIONS..................................................................................................................176
C_EncryptInit....................................................................................................................................176
C_Encrypt..........................................................................................................................................177
C_EncryptUpdate..............................................................................................................................178
C_EncryptFinal.................................................................................................................................179
K.9 DECRYPTION FUNCTIONS..................................................................................................................181
C_DecryptInit....................................................................................................................................181
C_Decrypt..........................................................................................................................................182
C_DecryptUpdate..............................................................................................................................183
C_DecryptFinal.................................................................................................................................184
K.10 MESSAGE DIGESTING FUNCTIONS...................................................................................................186
C_DigestInit.......................................................................................................................................186
C_Digest............................................................................................................................................186
C_DigestUpdate................................................................................................................................187
C_DigestKey......................................................................................................................................188
C_DigestFinal....................................................................................................................................188
K.11 SIGNING AND MACING FUNCTIONS...............................................................................................190
C_SignInit..........................................................................................................................................190
C_Sign................................................................................................................................................191
C_SignUpdate....................................................................................................................................192
C_SignFinal.......................................................................................................................................192
C_SignRecoverInit.............................................................................................................................193
C_SignRecover..................................................................................................................................194
K.12 FUNCTIONS FOR VERIFYING SIGNATURES AND MACS...................................................................195
Copyright © 1994-2001 RSA Security Inc. Revision 1, November 2001
V
C_VerifyInit.......................................................................................................................................195
C_Verify.............................................................................................................................................196
C_VerifyUpdate.................................................................................................................................197
C_VerifyFinal....................................................................................................................................197
C_VerifyRecoverInit..........................................................................................................................199
C_VerifyRecover................................................................................................................................199
K.13 DUAL-FUNCTION CRYPTOGRAPHIC FUNCTIONS..............................................................................201
C_DigestEncryptUpdate....................................................................................................................201
C_DecryptDigestUpdate...................................................................................................................204
C_SignEncryptUpdate.......................................................................................................................207
C_DecryptVerifyUpdate....................................................................................................................210
K.14 KEY MANAGEMENT FUNCTIONS......................................................................................................213
C_GenerateKey..................................................................................................................................214
C_GenerateKeyPair..........................................................................................................................215
C_WrapKey........................................................................................................................................217
C_UnwrapKey...................................................................................................................................219
C_DeriveKey......................................................................................................................................221
K.15 RANDOM NUMBER GENERATION FUNCTIONS..................................................................................223
C_SeedRandom..................................................................................................................................223
C_GenerateRandom..........................................................................................................................224
K.16 PARALLEL FUNCTION MANAGEMENT FUNCTIONS...........................................................................225
C_GetFunctionStatus........................................................................................................................225
C_CancelFunction.............................................................................................................................225
K.17 CALLBACK FUNCTIONS...................................................................................................................225
K.17.1 Surrender callbacks...............................................................................................................225
K.17.2 Vendor-defined callbacks......................................................................................................226
APPENDIX L: MECHANISMS..............................................................................................................226
L.1 RSA MECHANISMS............................................................................................................................231
L.1.1 PKCS #1 RSA key pair generation..........................................................................................231
L.1.2 X9.31 RSA key pair generation................................................................................................231
L.1.3 PKCS #1 RSA...........................................................................................................................232
L.1.4 PKCS #1 RSA OAEP mechanism parameters.........................................................................233
CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR...............................................233
CK_RSA_PKCS_OAEP_SOURCE_TYPE; CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR.........234
CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR................................234
L.1.5 PKCS #1 RSA OAEP................................................................................................................235
L.1.6 PKCS #1 RSA PSS mechanism parameters.............................................................................236
CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR........................................236
L.1.7 PKCS #1 RSA PSS....................................................................................................................237
L.1.8 ISO/IEC 9796 RSA...................................................................................................................237
L.1.9 X.509 (raw) RSA.......................................................................................................................238
L.1.10 ANSI X9.31 RSA.....................................................................................................................240
L.1.11 PKCS #1 RSA signature with MD2, MD5, SHA-1, RIPE-MD 128 or RIPE-MD 160.........241
L.1.12 PKCS #1 RSA PSS signature with SHA-1.............................................................................242
L.1.13 ANSI X9.31 RSA signature with SHA-1.................................................................................243
L.2 DSA MECHANISMS............................................................................................................................243
L.2.1 DSA key pair generation..........................................................................................................243
L.2.2 DSA domain parameter generation.........................................................................................244
L.2.3 DSA without hashing................................................................................................................244
L.2.4 DSA with SHA-1.......................................................................................................................245
L.2.5 FORTEZZA timestamp.............................................................................................................246
L.3 ABOUT ELLIPTIC CURVE...................................................................................................................246
L.4 ELLIPTIC CURVE MECHANISMS..........................................................................................................247
L.4.1 Elliptic curve key pair generation...........................................................................................247
L.4.2 ECDSA without hashing...........................................................................................................248
Revision 1, November 2001 Copyright © 1994-2001 RSA Security Inc.
评论3