z/OS Version 2.Release 4 Cryptographic Services Integrated Cryptographic Service Facility Writing PKCS #11 Applications IBM SC14-7510-07 Note Before using this information and the product it supports, read the information in “Notices” on page 105. This edition applies to ICSF FMID HCR77D1 and Version 2 Release 4 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: 2021-06-22 © Copyright International Business Machines Corporation 2007, 2021. 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 V2R2 - z/OS V2R4 (FMID HCR77D1).......................xiii Changes made in Cryptographic Support for z/OS V2R2 - z/OS V2R3 (FMID HCR77D0).......................xiv Changes made in Cryptographic Support for z/OS V2R1 - z/OS V2R3 (FMID HCR77C1)....................... xiv Changes made in Cryptographic Support for z/OS V2R1 - z/OS V2R2 (FMID HCR77C0)........................ 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....................................................................................................................................... 10 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 Additional manifest constants for Dilithium quantum-safe algorithm support.......................................30 iii Objects and attributes supported............................................................................................................. 31 Library, slot, and token information.......................................................................................................... 50 Functions supported..................................................................................................................................51 Standard functions supported ............................................................................................................ 51 Non-standard functions supported..................................................................................................... 62 Non-standard mechanisms supported................................................................................................63 Enterprise PKCS #11 coprocessors.......................................................................................................... 64 Key algorithms/usages that are unsupported or disallowed by the Enterprise PKCS #11 coprocessors .................................................................................................................................. 64 PKCS #11 Coprocessor Access Control Points................................................................................... 65 Standard compliance modes............................................................................................................... 69 Function return codes................................................................................................................................70 Troubleshooting PKCS #11 applications.................................................................................................. 71 Chapter 3. Sample PKCS #11 C programs ............................................................ 73 Running the pre-compiled version of testpkcs11.....................................................................................73 Steps for running the pre-compiled version of testpkcs11................................................................ 73 Building sample PKCS #11 applications from source code..................................................................... 74 Chapter 4. Regional cryptographic servers........................................................... 77 Regional cryptographic server key types and mechanisms supported....................................................77 CKM_IBM_SM2.................................................................................................................................... 79 CKM_IBM_SM2_ENCRYPT...................................................................................................................79 CKM_IBM_SM2_KEY_PAIR_GEN.........................................................................................................80 CKM_IBM_SM2_SM3..........................................................................................................................