PKCS #11 V2.11: Cryptographic Token Interface Standard
Total Page:16
File Type:pdf, Size:1020Kb
PKCS #11 v2.11: Cryptographic Token Interface Standard RSA Laboratories Revision 1 ¾ November 2001 Table of Contents 1. INTRODUCTION................................................................................................................................................1 2. SCOPE..................................................................................................................................................................2 3. REFERENCES ......................................................................................................................................................3 4. DEFINITIONS......................................................................................................................................................6 5. SYMBOLS AND ABBREVIATIONS..............................................................................................................9 6. GENERAL OVERVIEW ...................................................................................................................................12 6.1 DESIGN GOALS................................................................................................................................................12 6.2 GENERAL MODEL..........................................................................................................................................12 6.3 LOGICAL VIEW OF A TOKEN........................................................................................................................14 6.4 USERS...............................................................................................................................................................15 6.5 APPLICATIONS AND THEIR USE OF CRYPTOKI.......................................................................................16 6.5.1 Applications and processes ............................................................................................................16 6.5.2 Applications and threads................................................................................................................17 6.6 SESSIONS.........................................................................................................................................................18 6.6.1 Read-only session states..................................................................................................................18 6.6.2 Read/write session states.................................................................................................................19 6.6.3 Permitted object accesses by sessions...........................................................................................20 6.6.4 Session events....................................................................................................................................21 6.6.5 Session handles and object handles..............................................................................................22 6.6.6 Capabilities of sessions...................................................................................................................22 6.6.7 Example of use of sessions...............................................................................................................23 6.7 SECONDARY AUTHENTICATION (DEPRECATED) ...................................................................................26 6.7.1 Using keys protected by secondary authentication...................................................................27 6.7.2 Generating private keys protected by secondary authentication...........................................27 6.7.3 Changing the secondary authentication PIN value ..................................................................27 6.7.4 Secondary authentication PIN collection mechanisms.............................................................28 6.8 FUNCTION OVERVIEW..................................................................................................................................28 7. SECURITY CONSIDERATIONS ...................................................................................................................31 8. PLATFORM- AND COMPILER-DEPENDENT DIRECTIVES FOR C OR C++ ...................................32 8.1 STRUCTURE PACKING..................................................................................................................................32 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 8.2 POINTER-RELATED MACROS.......................................................................................................................33 ¨ CK_PTR ...................................................................................................................................................33 ¨ CK_DEFINE_FUNCTION ....................................................................................................................33 ¨ CK_DECLARE_FUNCTION ................................................................................................................33 ¨ CK_DECLARE_FUNCTION_POINTER ............................................................................................33 ¨ CK_CALLBACK_FUNCTION..............................................................................................................34 ¨ NULL_PTR...............................................................................................................................................34 8.3 SAMPLE PLATFORM- AND COMPILER-DEPENDENT CODE....................................................................35 8.3.1 Win32 ..................................................................................................................................................35 8.3.2 Win16 ..................................................................................................................................................36 8.3.3 Generic UNIX.....................................................................................................................................36 9. GENERAL DATA TYPES ................................................................................................................................37 9.1 GENERAL INFORMATION.............................................................................................................................37 ¨ CK_VERSION; CK_VERSION_PTR...................................................................................................37 ¨ CK_INFO; CK_INFO_PTR ..................................................................................................................38 ¨ CK_NOTIFICATION ..............................................................................................................................39 9.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 9.3 SESSION TYPES..............................................................................................................................................49 ¨ CK_SESSION_HANDLE; CK_SESSION_HANDLE_PTR ..............................................................49 ¨ CK_USER_TYPE....................................................................................................................................49 ¨ CK_STATE...............................................................................................................................................49 ¨ CK_SESSION_INFO; CK_SESSION_INFO_PTR............................................................................50 9.4 OBJECT TYPES...............................................................................................................................................50 ¨ CK_OBJECT_HANDLE; CK_OBJECT_HANDLE_PTR.................................................................50 ¨ CK_OBJECT_CLASS; CK_OBJECT_CLASS_PTR.........................................................................51 ¨ CK_HW_FEATURE_TYPE ...................................................................................................................51 ¨ CK_KEY_TYPE.......................................................................................................................................52 ¨ CK_CERTIFICATE_TYPE....................................................................................................................53 ¨ CK_ATTRIBUTE_TYPE.........................................................................................................................53 ¨ CK_ATTRIBUTE; CK_ATTRIBUTE_PTR ..........................................................................................55 ¨ CK_DATE ................................................................................................................................................55 9.5 DATA