z/OS Version 2 Release 3 Cryptographic Services Integrated Cryptographic Service Facility Writing PKCS #11 Applications IBM SC14-7510-04 Note Before using this information and the product it supports, read the information in “Notices” on page 101. This edition applies to ICSF FMID HCR77C0 and Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: 2019-06-24 © Copyright International Business Machines Corporation 2007, 2019. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Tables................................................................................................................. vii About this document.............................................................................................ix Who should read this document................................................................................................................. ix How this document is organized.................................................................................................................ix How to use this document.......................................................................................................................... ix Where to find more information...................................................................................................................x IBM Crypto Education.............................................................................................................................x How to send your comments to IBM.......................................................................xi If you have a technical problem..................................................................................................................xi Summary of changes...........................................................................................xiii Changes made in Cryptographic Support for z/OS V2R1 - z/OS V2R2 (FMID HCR77C0)....................... xiii Changes made in Cryptographic Support for z/OS V1R13 - z/OS V2R2 (FMID HCR77B1).....................xiii Changes made in Enhanced Cryptographic Support for z/OS V1R13 - z/OS V2R1 (FMID HCR77B0)....xiv Changes made in Cryptographic Support for z/OS V1R13-V2R1 (FMID HCR77A1)................................ xv Chapter 1. Overview of z/OS support for PKCS #11.................................................1 Tokens.......................................................................................................................................................... 1 Secure key PKCS #11.............................................................................................................................2 The token data set (TKDS)......................................................................................................................2 Controlling token access and key policy................................................................................................2 Managing tokens ....................................................................................................................................7 Sample scenario for setting up z/OS PKCS #11 tokens........................................................................ 7 Sample scenario for controlling clear key processing .......................................................................... 9 Auditing PKCS #11 functions...................................................................................................................... 9 Component trace for PKCS #11 functions................................................................................................10 Object types............................................................................................................................................... 10 Session objects.....................................................................................................................................10 Token objects....................................................................................................................................... 11 Operating in compliance with FIPS 140-2................................................................................................11 Requiring signature verification for ICSF module CSFINPV2............................................................. 13 Requiring FIPS 140-2 compliance from all z/OS PKCS #11 applications.......................................... 14 Requiring FIPS 140-2 compliance from select z/OS PKCS #11 applications....................................15 Preparing to use PKCS #11 applications.................................................................................................. 16 Tasks for the system programmer....................................................................................................... 16 Tasks for the security administrator.................................................................................................... 17 Tasks for the auditor.............................................................................................................................17 Tasks for application programmers..................................................................................................... 17 Optional Crypto Express adapters.............................................................................................................17 Chapter 2. The C API........................................................................................... 19 Using the C API.......................................................................................................................................... 19 Deleting z/OS PKCS #11 tokens.......................................................................................................... 19 Environment......................................................................................................................................... 19 Cross memory considerations............................................................................................................. 20 Key types and mechanisms supported..................................................................................................... 20 Objects and attributes supported............................................................................................................. 29 iii Library, slot, and token information.......................................................................................................... 47 Functions supported..................................................................................................................................48 Standard functions supported ............................................................................................................ 48 Non-standard functions supported..................................................................................................... 59 Non-standard mechanisms supported................................................................................................60 Enterprise PKCS #11 coprocessors.......................................................................................................... 61 Key algorithms/usages that are unsupported or disallowed by the Enterprise PKCS #11 coprocessors .................................................................................................................................. 61 PKCS #11 Coprocessor Access Control Points................................................................................... 62 Standard compliance modes............................................................................................................... 66 Function return codes................................................................................................................................66 Troubleshooting PKCS #11 applications.................................................................................................. 67 Chapter 3. Sample PKCS #11 C programs ............................................................ 69 Running the pre-compiled version of testpkcs11.....................................................................................69 Steps for running the pre-compiled version of testpkcs11................................................................ 69 Building sample PKCS #11 applications from source code..................................................................... 70 Chapter 4. Regional cryptographic servers........................................................... 73 Regional cryptographic server key types and mechanisms supported....................................................73 CKM_IBM_SM2.....................................................................................................................................75 CKM_IBM_SM2_ENCRYPT...................................................................................................................75 CKM_IBM_SM2_KEY_PAIR_GEN.........................................................................................................76 CKM_IBM_SM2_SM3........................................................................................................................... 76 CKM_IBM_SM3.....................................................................................................................................77