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............................................................................................................................. 47
CK_SESSION_HANDLE; CK_SESSION_HANDLE_PTR.................................................................47
CK_USER_TYPE.................................................................................................................................48
CK_STATE...........................................................................................................................................48
CK_SESSION_INFO; CK_SESSION_INFO_PTR.............................................................................48
I.4 OBJECT TYPES.............................................................................................................................. 49
CK_OBJECT_HANDLE; CK_OBJECT_HANDLE_PTR...................................................................49
CK_OBJECT_CLASS; CK_OBJECT_CLASS_PTR...........................................................................50
CK_HW_FEATURE_TYPE.................................................................................................................50
CK_KEY_TYPE...................................................................................................................................51
CK_CERTIFICATE_TYPE..................................................................................................................51
CK_ATTRIBUTE_TYPE......................................................................................................................52
CK_ATTRIBUTE; CK_ATTRIBUTE_PTR..........................................................................................53
CK_DATE............................................................................................................................................54
I.5 DATA TYPES FOR MECHANISMS..................................................................................................... 55
CK_MECHANISM_TYPE; CK_MECHANISM_TYPE_PTR..............................................................55
CK_MECHANISM; CK_MECHANISM_PTR.....................................................................................59
CK_MECHANISM_INFO; CK_MECHANISM_INFO_PTR..............................................................60
I.6 FUNCTION TYPES.......................................................................................................................... 62
CK_RV.................................................................................................................................................62
CK_NOTIFY........................................................................................................................................64
CK_C_XXX..........................................................................................................................................65
CK_FUNCTION_LIST; CK_FUNCTION_LIST_PTR; CK_FUNCTION_LIST_PTR_PTR..............65
I.7 LOCKING-RELATED TYPES.............................................................................................................67
CK_CREATEMUTEX..........................................................................................................................67
CK_DESTROYMUTEX........................................................................................................................67
CK_LOCKMUTEX and CK_UNLOCKMUTEX.................................................................................68
CK_C_INITIALIZE_ARGS; CK_C_INITIALIZE_ARGS_PTR...........................................................69
APPENDIX J: OBJECTS...........................................................................................................................71
J.1 CREATING, MODIFYING, AND COPYING OBJECTS.............................................................................72
J.1.1 Creating objects..........................................................................................................................72
J.1.2 Modifying objects.......................................................................................................................74
J.1.3 Copying objects..........................................................................................................................74
J.2 COMMON ATTRIBUTES.................................................................................................................. 75
J.3 HARDWARE FEATURE OBJECTS..................................................................................................... 75
J.3.1 Clock Objects..............................................................................................................................76
Copyright © 1994-2001 RSA Security Inc. Revision 1, November 2001
错误！未定义样式。 III
J.3.2 Monotonic Counter Objects.......................................................................................................77
J.4 STORAGE OBJECTS........................................................................................................................ 78
J.5 DATA OBJECTS............................................................................................................................. 78
J.6 CERTIFICATE OBJECTS................................................................................................................... 80
J.6.1 X.509 attribute certificate objects..............................................................................................82
J.7 KEY OBJECTS................................................................................................................................ 84
J.8 PUBLIC KEY OBJECTS.................................................................................................................... 86
J.8.1 RSA public key objects...............................................................................................................87
J.8.2 DSA public key objects...............................................................................................................88
J.8.3 ECDSA public key objects..........................................................................................................89
J.8.4 Diffie-Hellman public key objects..............................................................................................90
J.8.5 X9.42 Diffie-Hellman public key objects...................................................................................91
J.8.6 KEA public key objects...............................................................................................................92
J.9 PRIVATE KEY OBJECTS.................................................................................................................. 93
J.9.1 RSA private key objects..............................................................................................................96
J.9.2 DSA private key objects..............................................................................................................98
J.9.3 Elliptic curve private key objects...............................................................................................99
J.9.4 Diffie-Hellman private key objects..........................................................................................100
J.9.5 X9.42 Diffie-Hellman private key objects................................................................................101
J.9.6 KEA private key objects...........................................................................................................103
J.10 SECRET KEY OBJECTS................................................................................................................ 104
J.10.1 Generic secret key objects......................................................................................................106
J.10.2 RC2 secret key objects............................................................................................................106
J.10.3 RC4 secret key objects............................................................................................................107
J.10.4 RC5 secret key objects............................................................................................................108
J.10.5 AES secret key objects............................................................................................................108
J.10.6 DES secret key objects...........................................................................................................109
J.10.7 DES2 secret key objects.........................................................................................................110
J.10.8 DES3 secret key objects.........................................................................................................111
J.10.9 CAST secret key objects.........................................................................................................111
J.10.10 CAST3 secret key objects.....................................................................................................112
J.10.11 CAST128 (CAST5) secret key objects..................................................................................113
J.10.12 IDEA secret key objects.......................................................................................................113
J.10.13 CDMF secret key objects.....................................................................................................114
J.10.14 SKIPJACK secret key objects..............................................................................................115
J.10.15 BATON secret key objects....................................................................................................116
J.10.16 JUNIPER secret key objects................................................................................................117
J.11 DOMAIN PARAMETER OBJECTS...................................................................................................119
J.11.1 DSA domain parameter objects..............................................................................................120
J.11.2 Diffie-Hellman domain parameter objects............................................................................121
J.11.3 X9.42 Diffie-Hellman domain parameters objects................................................................122
APPENDIX K: FUNCTIONS..................................................................................................................124
K.1 FUNCTION RETURN VALUES.......................................................................................................125
K.1.1 Universal Cryptoki function return values.............................................................................125
K.1.2 Cryptoki function return values for functions that use a session handle..............................126
K.1.3 Cryptoki function return values for functions that use a token.............................................127
K.1.4 Special return value for application-supplied callbacks.......................................................127
K.1.5 Special return values for mutex-handling functions..............................................................128
K.1.6 All other Cryptoki function return values..............................................................................128
K.1.7 More on relative priorities of Cryptoki errors.......................................................................135
K.1.8 Error code “gotchas”.............................................................................................................136
K.2 CONVENTIONS FOR FUNCTIONS RETURNING OUTPUT IN A VARIABLE-LENGTH BUFFER..................136
K.3 DISCLAIMER CONCERNING SAMPLE CODE...................................................................................137
K.4 GENERAL-PURPOSE FUNCTIONS..................................................................................................137
C_Initialize........................................................................................................................................137
Revision 1, November 2001 Copyright © 1994-2001 RSA Security Inc.
IV PKCS #11 V2.11: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD
C_Finalize..........................................................................................................................................139
C_GetInfo...........................................................................................................................................140
C_GetFunctionList............................................................................................................................141
K.5 SLOT AND TOKEN MANAGEMENT FUNCTIONS..............................................................................141
C_GetSlotList.....................................................................................................................................141
C_GetSlotInfo....................................................................................................................................143
C_GetTokenInfo.................................................................................................................................144
C_WaitForSlotEvent..........................................................................................................................145
C_GetMechanismList........................................................................................................................146
C_GetMechanismInfo........................................................................................................................148
C_InitToken.......................................................................................................................................148
C_InitPIN...........................................................................................................................................150
C_SetPIN...........................................................................................................................................151
K.6 SESSION MANAGEMENT FUNCTIONS............................................................................................153
C_OpenSession..................................................................................................................................153
C_CloseSession..................................................................................................................................154
C_CloseAllSessions...........................................................................................................................155
C_GetSessionInfo..............................................................................................................................156
C_GetOperationState........................................................................................................................157
C_SetOperationState.........................................................................................................................158
C_Login..............................................................................................................................................161
C_Logout...........................................................................................................................................162
K.7 OBJECT MANAGEMENT FUNCTIONS.............................................................................................163
C_CreateObject.................................................................................................................................164
C_CopyObject....................................................................................................................................166
C_DestroyObject...............................................................................................................................168
C_GetObjectSize................................................................................................................................168
C_GetAttributeValue.........................................................................................................................169
C_SetAttributeValue..........................................................................................................................172
C_FindObjectsInit.............................................................................................................................173
C_FindObjects...................................................................................................................................174
C_FindObjectsFinal..........................................................................................................................174
K.8 ENCRYPTION FUNCTIONS........................................................................................................... 175
C_EncryptInit....................................................................................................................................175
C_Encrypt..........................................................................................................................................176
C_EncryptUpdate..............................................................................................................................177
C_EncryptFinal.................................................................................................................................178
K.9 DECRYPTION FUNCTIONS........................................................................................................... 180
C_DecryptInit....................................................................................................................................180
C_Decrypt..........................................................................................................................................181
C_DecryptUpdate..............................................................................................................................182
C_DecryptFinal.................................................................................................................................183
K.10 MESSAGE DIGESTING FUNCTIONS.............................................................................................. 185
C_DigestInit.......................................................................................................................................185
C_Digest............................................................................................................................................185
C_DigestUpdate................................................................................................................................186
C_DigestKey......................................................................................................................................187
C_DigestFinal....................................................................................................................................187
K.11 SIGNING AND MACING FUNCTIONS..........................................................................................189
C_SignInit..........................................................................................................................................189
C_Sign................................................................................................................................................190
C_SignUpdate....................................................................................................................................191
C_SignFinal.......................................................................................................................................191
C_SignRecoverInit.............................................................................................................................192
C_SignRecover..................................................................................................................................193
K.12 FUNCTIONS FOR VERIFYING SIGNATURES AND MACS...............................................................194
Copyright © 1994-2001 RSA Security Inc. Revision 1, November 2001
错误！未定义样式。 V
C_VerifyInit.......................................................................................................................................194
C_Verify.............................................................................................................................................195
C_VerifyUpdate.................................................................................................................................196
C_VerifyFinal....................................................................................................................................196
C_VerifyRecoverInit..........................................................................................................................198
C_VerifyRecover................................................................................................................................198
K.13 DUAL-FUNCTION CRYPTOGRAPHIC FUNCTIONS..........................................................................200
C_DigestEncryptUpdate....................................................................................................................200
C_DecryptDigestUpdate...................................................................................................................203
C_SignEncryptUpdate.......................................................................................................................206
C_DecryptVerifyUpdate....................................................................................................................209
K.14 KEY MANAGEMENT FUNCTIONS................................................................................................212
C_GenerateKey..................................................................................................................................213
C_GenerateKeyPair..........................................................................................................................214
C_WrapKey........................................................................................................................................216
C_UnwrapKey...................................................................................................................................218
C_DeriveKey......................................................................................................................................220
K.15 RANDOM NUMBER GENERATION FUNCTIONS.............................................................................222
C_SeedRandom..................................................................................................................................222
C_GenerateRandom..........................................................................................................................223
K.16 PARALLEL FUNCTION MANAGEMENT FUNCTIONS.......................................................................224
C_GetFunctionStatus........................................................................................................................224
C_CancelFunction.............................................................................................................................224
K.17 CALLBACK FUNCTIONS............................................................................................................ 224
K.17.1 Surrender callbacks...............................................................................................................224
K.17.2 Vendor-defined callbacks......................................................................................................225
APPENDIX L: MECHANISMS..............................................................................................................225
L.1 RSA MECHANISMS..................................................................................................................... 230
L.1.1 PKCS #1 RSA key pair generation..........................................................................................230
L.1.2 X9.31 RSA key pair generation................................................................................................230
L.1.3 PKCS #1 RSA...........................................................................................................................231
L.1.4 PKCS #1 RSA OAEP mechanism parameters.........................................................................232
CK_RSA_PKCS_MGF_TYPE; CK_RSA_PKCS_MGF_TYPE_PTR...............................................232
CK_RSA_PKCS_OAEP_SOURCE_TYPE; CK_RSA_PKCS_OAEP_SOURCE_TYPE_PTR.........233
CK_RSA_PKCS_OAEP_PARAMS; CK_RSA_PKCS_OAEP_PARAMS_PTR................................233
L.1.5 PKCS #1 RSA OAEP................................................................................................................234
L.1.6 PKCS #1 RSA PSS mechanism parameters.............................................................................235
CK_RSA_PKCS_PSS_PARAMS; CK_RSA_PKCS_PSS_PARAMS_PTR........................................235
L.1.7 PKCS #1 RSA PSS....................................................................................................................236
L.1.8 ISO/IEC 9796 RSA...................................................................................................................236
L.1.9 X.509 (raw) RSA.......................................................................................................................237
L.1.10 ANSI X9.31 RSA.....................................................................................................................239
L.1.11 PKCS #1 RSA signature with MD2, MD5, SHA-1, RIPE-MD 128 or RIPE-MD 160.........240
L.1.12 PKCS #1 RSA PSS signature with SHA-1.............................................................................241
L.1.13 ANSI X9.31 RSA signature with SHA-1.................................................................................242
L.2 DSA MECHANISMS..................................................................................................................... 242
L.2.1 DSA key pair generation..........................................................................................................242
L.2.2 DSA domain parameter generation.........................................................................................243
L.2.3 DSA without hashing................................................................................................................243
L.2.4 DSA with SHA-1.......................................................................................................................244
L.2.5 FORTEZZA timestamp.............................................................................................................245
L.3 ABOUT ELLIPTIC CURVE............................................................................................................ 245
L.4 ELLIPTIC CURVE MECHANISMS.................................................................................................... 246
L.4.1 Elliptic curve key pair generation...........................................................................................246
L.4.2 ECDSA without hashing...........................................................................................................247
Revision 1, November 2001 Copyright © 1994-2001 RSA Security Inc.
- 1
- 2
- 3
- 4
前往页