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 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. ii PKCS #11 V2.20: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD ♦ 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.............................................................................................................