PKCS #11 v2.11 Draft 1: Cryptographic Token Interface Standard RSA Laboratories November 2000 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............................................................... 26 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 Copyright 1994-1999 2000 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. 003-903053-210-000-000 ii PKCS #11 V2.11 DRAFT 10: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD 8.1 STRUCTURE PACKING.................................................................................................................. 32 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 ............................................................. 34 8.3.1 Win32 .................................................................................................................................... 34 8.3.2 Win16 .................................................................................................................................... 35 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 .................................................................................................................38 9.2 SLOT AND TOKEN TYPES ............................................................................................................. 39 ♦ CK_SLOT_ID; CK_SLOT_ID_PTR .......................................................................................... 39 ♦ CK_SLOT_INFO; CK_SLOT_INFO_PTR ................................................................................ 39 ♦ CK_TOKEN_INFO; CK_TOKEN_INFO_PTR ......................................................................... 41 9.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 9.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 9.5 DATA TYPES FOR MECHANISMS................................................................................................... 54 ♦ CK_MECHANISM_TYPE; CK_MECHANISM_TYPE_PTR ..................................................... 54 ♦ CK_MECHANISM; CK_MECHANISM_PTR............................................................................ 58 ♦ CK_MECHANISM_INFO; CK_MECHANISM_INFO_PTR ..................................................... 58 9.6 FUNCTION TYPES ........................................................................................................................ 60 ♦ CK_RV ....................................................................................................................................... 61