IBM PCI Cryptographic Coprocessor CCA Basic Services Reference and Guide Release 2.54 IBM iSeries PCICC Feature CCA Release 2.54 CCA Release 2.54 Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page xiii. | Thirteenth Edition (December, 2004) | This manual describes the IBM Common Cryptographic Architecture (CCA) Basic Services API, Release 2.54 as revised in | December 2004, implemented for the IBM eServer iSeries PCI Cryptographic Coprocessor hardware feature (#4801) and OS/400 | Option 35, CCA CSP. This Basic Services manual replaces the manuals for Releases 2.50, 2.51, 2.52, and 2.53. IBM does not stock publications at the address given below. This and other publications related to the IBM 4758 Coprocessor can be obtained in PDF format from the Library page at http://www.ibm.com/security/cryptocards. Readers’ comments can be communicated to IBM by using the Comments and Questions form located on the product Web site at http://www.ibm.com/security/cryptocards, or by sending a letter to: IBM Corporation Department VM9A Security Solutions and Technology 8501 IBM Drive Charlotte, NC 28262-8563 USA IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 1997, 2005. All rights reserved. Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. CCA Release 2.54 Contents Notices . xiii Trademarks . xiii About This Publication ................................ xv Revision History . xv Organization . xxii Related Publications . xxiii Cryptography Publications . xxiii Chapter 1. Introduction to Programming for the IBM CCA ......... 1-1 What CCA Services Are Available with the IBM 4758 ............... 1-1 An Overview of the CCA Environment ........................ 1-2 How Application Programs Obtain Service .................... 1-6 Overlapped Processing . 1-7 Host-side Key Caching ............................. 1-7 The Security API, Programming Fundamentals .................. 1-8 Verbs, Variables, and Parameters ........................ 1-8 Commonly Encountered Parameters ...................... 1-11 Parameters Common to All Verbs ...................... 1-11 Rule_Array and Other Keyword Parameters ................ 1-12 Key Tokens, Key Labels, and Key Identifiers ............... 1-12 How the Verbs Are Organized in the Remainder of the Book ......... 1-13 Chapter 2. CCA Node-Management and Access-Control .......... 2-1 CCA Access-Control . 2-2 Understanding Access Control .......................... 2-2 Role-Based Access Control ............................ 2-2 Understanding Roles . 2-3 Understanding Profiles . 2-4 Initializing and Managing the Access-Control System ............. 2-5 Access-Control Management and Initialization Verbs ............ 2-5 Permitting Changes to the Configuration ................... 2-5 Configuration and Greenwich Mean Time (GMT) .............. 2-6 Logging On and Logging Off ............................ 2-7 Use of Logon Context Information ....................... 2-8 Protecting Your Transaction Information ..................... 2-9 Controlling the Cryptographic Facility ........................ 2-9 Multi-Coprocessor Capability . 2-10 Multi-Coprocessor CCA Host Implementation ................. 2-11 OS/400 Multi-Coprocessor Support ..................... 2-11 AIX, Windows and OS/2 Multi-Coprocessor Support ........... 2-11 Understanding and Managing Master Keys .................... 2-12 Symmetric and Asymmetric Master-Keys ................... 2-13 Establishing Master Keys ............................ 2-13 Master-Key Considerations with Multiple CCA Coprocessors ........ 2-17 Access_Control_Initialization (CSUAACI) . 2-21 Access_Control_Maintenance (CSUAACM) . 2-24 Cryptographic_Facility_Control (CSUACFC) . 2-30 Cryptographic_Facility_Query (CSUACFQ) . 2-34 Cryptographic_Resource_Allocate (CSUACRA) . 2-44 Copyright IBM Corp. 1997, 2005 iii CCA Release 2.54 Cryptographic_Resource_Deallocate (CSUACRD) . 2-46 Key_Storage_Designate (CSUAKSD) . 2-48 Key_Storage_Initialization (CSNBKSI) . 2-50 Logon_Control (CSUALCT) . 2-52 Master_Key_Distribution (CSUAMKD) . 2-55 Master_Key_Process (CSNBMKP) . 2-59 Random_Number_Tests (CSUARNT) . 2-64 Chapter 3. RSA Key-Management . 3-1 RSA Key-Management . 3-1 Key Generation . 3-2 Key Import . 3-4 Reenciphering a Private Key Under an Updated Master-Key ......... 3-5 Using the PKA Keys ................................ 3-5 Using the Private Key at Multiple Nodes ..................... 3-6 Extracting a Public Key ............................... 3-6 Registering and Retaining a Public Key ..................... 3-6 PKA_Key_Generate (CSNDPKG) . 3-7 PKA_Key_Import (CSNDPKI) . 3-11 PKA_Key_Token_Build (CSNDPKB) . 3-14 PKA_Key_Token_Change (CSNDKTC) . 3-22 PKA_Public_Key_Extract (CSNDPKX) . 3-24 PKA_Public_Key_Hash_Register (CSNDPKH) . 3-26 PKA_Public_Key_Register (CSNDPKR) . 3-28 Chapter 4. Hashing and Digital Signatures ................... 4-1 Hashing . 4-1 Digital Signatures . 4-2 Digital_Signature_Generate (CSNDDSG) . 4-4 Digital_Signature_Verify (CSNDDSV) . 4-7 MDC_Generate (CSNBMDG) . 4-10 One_Way_Hash (CSNBOWH) . 4-13 Chapter 5. DES Key-Management . 5-1 Understanding CCA DES Key-Management .................... 5-2 Control Vectors . 5-4 Checking a Control Vector Before Processing a Cryptographic Command . 5-5 Key Types . 5-5 Key-Usage Restrictions . 5-6 Key Tokens, Key Labels, and Key Identifiers ................... 5-12 Key Tokens . 5-12 Key Labels . 5-14 Key Identifiers . 5-14 Using the Key-Processing and Key-Storage Verbs ............... 5-15 Installing and Verifying Keys ........................... 5-15 Generating Keys . 5-16 Exporting and Importing Keys, Symmetric Techniques ............ 5-18 Exporting and Importing Keys, Asymmetric Techniques ........... 5-19 Diversifying Keys . 5-19 Storing Keys in Key Storage ........................... 5-20 Security Precautions . 5-21 Clear_Key_Import (CSNBCKI) . 5-22 Control_Vector_Generate (CSNBCVG) . 5-24 Control_Vector_Translate (CSNBCVT) . 5-26 iv IBM 4758 CCA Basic Services, Release 2.54, February 2005 CCA Release 2.54 Cryptographic_Variable_Encipher (CSNBCVE) . 5-29 Data_Key_Export (CSNBDKX) . 5-31 Data_Key_Import (CSNBDKM) . 5-33 Diversified_Key_Generate (CSNBDKG) . 5-35 Key_Export (CSNBKEX) . 5-42 Key_Generate (CSNBKGN) . 5-44 Key-Type Specifications . 5-47 Key-Length Specification . 5-49 Key_Import (CSNBKIM) . 5-51 Key_Part_Import (CSNBKPI) . 5-54 Key_Test (CSNBKYT) . 5-58 Key_Token_Build (CSNBKTB) . 5-61 Key_Token_Change (CSNBKTC) . 5-64 Key_Token_Parse (CSNBKTP) . 5-66 Key_Translate (CSNBKTR) . 5-69 Multiple_Clear_Key_Import (CSNBCKM) . 5-71 PKA_Decrypt (CSNDPKD) . 5-73 PKA_Encrypt (CSNDPKE) . 5-75 PKA_Symmetric_Key_Export (CSNDSYX) . 5-78 PKA_Symmetric_Key_Generate (CSNDSYG) . 5-81 PKA_Symmetric_Key_Import (CSNDSYI) . 5-86 Prohibit_Export (CSNBPEX) . 5-90 Random_Number_Generate (CSNBRNG) . 5-91 Chapter 6. Data Confidentiality and Data Integrity .............. 6-1 Encryption and Message Authentication Codes .................. 6-1 Ensuring Data Confidentiality ........................... 6-1 Ensuring Data Integrity ............................... 6-3 MACing Segmented Data ............................ 6-3 Decipher (CSNBDEC) . 6-5 Encipher (CSNBENC) . 6-8 MAC_Generate (CSNBMGN) . 6-11 MAC_Verify (CSNBMVR) . 6-14 Chapter 7. Key-Storage Verbs . 7-1 Key Labels and Key-Storage Management ..................... 7-1 Key-Label Content . 7-2 DES_Key_Record_Create (CSNBKRC) ...................... 7-4 DES_Key_Record_Delete (CSNBKRD) ....................... 7-5 DES_Key_Record_List (CSNBKRL) ......................... 7-7 DES_Key_Record_Read (CSNBKRR) ....................... 7-9 DES_Key_Record_Write (CSNBKRW) ...................... 7-10 PKA_Key_Record_Create (CSNDKRC) ..................... 7-11 PKA_Key_Record_Delete (CSNDKRD) ...................... 7-13 PKA_Key_Record_List (CSNDKRL) ........................ 7-15 PKA_Key_Record_Read (CSNDKRR) ...................... 7-17 PKA_Key_Record_Write (CSNDKRW) ...................... 7-19 Retained_Key_Delete (CSNDRKD) ........................ 7-21 Retained_Key_List (CSNDRKL) .......................... 7-22 Chapter 8. Financial Services Support Verbs ................. 8-1 Processing Financial PINs .............................. 8-2 PIN-Verb Summary . 8-5 PIN-Calculation Method and PIN-Block Format Summary ......... 8-6 Contents v CCA Release 2.54 Providing Security for PINs ............................ 8-6 Using Specific Key Types and Key-Usage Bits to Help Ensure PIN Security . 8-7 Supporting Multiple PIN-Calculation Methods .................. 8-8 PIN-Calculation Methods . 8-8 Data_Array . 8-8 Supporting Multiple PIN-Block Formats and PIN-Extraction Methods ... 8-10 PIN Profile . 8-10 PIN-Extraction Methods . 8-12 Personal Account Number (PAN) ...................... 8-13 Working With EMV Smart Cards .......................... 8-13 Clear_PIN_Encrypt (CSNBCPE) . 8-15 Clear_PIN_Generate (CSNBPGN) . 8-18 Clear_PIN_Generate_Alternate (CSNBCPA) . 8-21 CVV_Generate (CSNBCSG) . ..