IBM 2 Return Code 4

CCA Release 2.54

Return Code 4

Figure A-3. Reason Codes for Return Code 4

Return

Code

Dec

Reason

Code

Dec (Hex) Meaning

4001 (001) The verification test failed.

4013 (00D) The key token has an initialization vector, and the

initialization_vector parameter value is nonzero. The verb

uses the value in the key token.

4016 (010) The rule array and the rule-array count are too small to

contain the complete result.

4017 (011) The requested ID is not present in any profile in the specified

cryptographic hardware component.

4019 (013) The financial PIN in a PIN block is not verified.

4158 (09E) The Key_Token_Change, Key_Record_Delete, or

Key_Record_Write verbs did not process any records.

4166 (0A6) The control vector is not valid because of parity bits,

anti-variant bits, or inconsistent KEK bits, or because bits 59 to

62 are not zero.

4179 (0B3) The control-vector keywords that are in the rule array are

ignored.

4283 (11B) The Cryptographic Coprocessor battery is low.

4287 (11F) The PIN-block format is not consistent.

4429 (1AD) The digital signature is not verified. The verb completed its

processing normally.

41024 (400) Sufficient shares have been processed to create a new

master-key.

42039 (7F7) At least one control vector bit cannot be parsed.

42042 (7FA) The supplied passphrase is invalid.

Appendix A. Return Codes and Reason Codes A-3

Contents

Main Page Contents iv Page vi Page viii Figures x Page Page Notices Trademarks xiv About This Publication Revision History Revision History CCA Release 2.54 Eleventh Edition, April, 2004, CCA Support Program, Release 2.52 xvi Tenth Edition, February 2004, CCA Support Program, Release 2.51 Ninth Edition, Revised September, 2003, CCA Support Program, Release 2.41 Ninth Edition, Revised August 2002, CCA Support Program, Release 2.41 Revision History CCA Release 2.54 Eighth Edition, Revised, CCA Support Program, Release 2.41 xviii Eighth Edition, CCA Support Program, Release 2.41 Seventh Edition, CCA Support Program, Release 2.40 Revision History CCA Release 2.54 Sixth Edition, CCA Support Program, Release 2.30/2.31 xx Fifth Edition, CCA Support Program, Release 2.30 Organization xxii Related Publications Cryptography Publications xxiv Chapter 1. Introduction to Programming for the IBM CCA What CCA Services Are Available with the IBM 4758 An Overview of the CCA Environment 1-2 Page 1-4 Page How Application Programs Obtain Service 1-6 Overlapped Processing Host-side Key Caching The Security API, Programming Fundamentals 1-8 Verbs, Variables, and Parameters Page 1-10 Commonly Encountered Parameters Parameters Common to All Verbs Rule_Array and Other Keyword Parameters 1-12 Key Tokens, Key Labels, and Key Identifiers How the Verbs Are Organized in the Remainder of the Book 1-14 Chapter 2. CCA Node-Management and Access-Control Figure 2-1. CCA Node, Access-Control, and Master-Key Management Verbs 2-2 CCA Access-Control Understanding Access Control Role-Based Access Control Understanding Roles Understanding Profiles 2-4 Initializing and Managing the Access-Control System Access-Control Management and Initialization Verbs Permitting Changes to the Configuration Configuration and Greenwich Mean Time (GMT) 2-6 Logging On and Logging Off Use of Logon Context Information 2-8 Protecting Your Transaction Information Controlling the Cryptographic Facility 2-10 Multi-Coprocessor Capability Multi-Coprocessor CCA Host Implementation OS/400 Multi-Coprocessor Support AIX, Windows and OS/2 Multi-Coprocessor Support Understanding and Managing Master Keys 2-12 Symmetric and Asymmetric Master-Keys Establishing Master Keys 2-14 Page 2-16 Master-Key Considerations with Multiple CCA Coprocessors 2-18 Page 2-20 Access_Control_Initialization (CSUAACI) Restrictions Format Parameters Access_Control_Initialization 2-22 Access_Control_Maintenance 2-24 Access_Control_Maintenance (CSUAACM) Restrictions Format Access_Control_Maintenance 2-26 Access_Control_Maintenance 2-28 Page Cryptographic_Facility_Control 2-30 Cryptographic_Facility_Control (CSUACFC) Restrictions Format Cryptographic_Facility_Control 2-32 Cryptographic_Facility_Query 2-34 Cryptographic_Facility_Query (CSUACFQ) Restrictions Format Cryptographic_Facility_Query 2-36 Cryptographic_Facility_Query 2-38 Cryptographic_Facility_Query 2-40 Cryptographic_Facility_Query 2-42 Page Cryptographic_Resource_Allocate 2-44 Cryptographic_Resource_Allocate (CSUACRA) Restrictions Format Cryptographic_Resource_Deallocate 2-46 Cryptographic_Resource_Deallocate (CSUACRD) Restrictions Format Key_Storage_Designate 2-48 Key_Storage_Designate (CSUAKSD) Restrictions Format Page Key_Storage_Initialization 2-50 Key_Storage_Initialization (CSNBKSI) Restrictions Format Logon_Control 2-52 Logon_Control (CSUALCT) Restrictions Format Logon_Control 2-54 Master_Key_Distribution (CSUAMKD) Master_Key_Distribution 2-56 Master_Key_Distribution 2-58 Master_Key_Process (CSNBMKP) Master_Key_Process 2-60 Master_Key_Process 2-62 Random_Number_Tests 2-64 Random_Number_Tests (CSUARNT) Restrictions Format Page Page Chapter 3. RSA Key-Management RSA Key-Management Key Generation Page Key Import 3-4 Reenciphering a Private Key Under an Updated Master-Key Using the PKA Keys Using the Private Key at Multiple Nodes 3-6 Extracting a Public Key Registering and Retaining a Public Key PKA_Key_Generate (CSNDPKG) PKA_Key_Generate 3-8 PKA_Key_Generate 3-10 PKA_Key_Import (CSNDPKI) Restrictions Format PKA_Key_Import 3-12 Page PKA_Key_Token_Build 3-14 PKA_Key_Token_Build (CSNDPKB) PKA_Key_Token_Build 3-16 Figure 3-3 (Page 1 of 2). PKA_Key_Token_Build Key-Values-Structure Contents PKA_Key_Token_Build 3-18 PKA_Key_Token_Build 3-20 Page PKA_Key_Token_Change 3-22 PKA_Key_Token_Change (CSNDKTC) Restrictions Format PKA_Public_Key_Extract 3-24 PKA_Public_Key_Extract (CSNDPKX) Restrictions Format PKA_Public_Key_Hash_Register 3-26 PKA_Public_Key_Hash_Register (CSNDPKH) Restrictions Format PKA_Public_Key_Register 3-28 PKA_Public_Key_Register (CSNDPKR) Restrictions Format Page Page Chapter 4. Hashing and Digital Signatures Hashing 4-2 Digital Signatures Digital_Signature_Generate 4-4 Digital_Signature_Generate (CSNDDSG) Restrictions Format Digital_Signature_Generate 4-6 Digital_Signature_Verify (CSNDDSV) Restrictions Format Parameters Digital_Signature_Verify 4-8 MDC_Generate 4-10 MDC_Generate (CSNBMDG) Restrictions MDC_Generate 4-12 One_Way_Hash (CSNBOWH) Restrictions Format One_Way_Hash 4-14 Page Page Chapter 5. DES Key-Management Figure 5-1 (Page 1 of 2). Basic CCA DESKey-Management Verbs Understanding CCA DES Key-Management 5-2 Page 5-4 Control Vectors Checking a Control Vector Before Processing a Cryptographic Command Key Types Key-Usage Restrictions 5-6 5-8 Figure 5-4. Control_Vector_Generate and Key_Token_Build CV Keyword Combinations 5-10 Page Key Tokens, Key Labels, and Key Identifiers 5-12 Key Tokens Key Labels 5-14 Key Identifiers Using the Key-Processing and Key-Storage Verbs Installing and Verifying Keys Generating Keys 5-16 Page Exporting and Importing Keys, Symmetric Techniques 5-18 Exporting and Importing Keys, Asymmetric Techniques Diversifying Keys Storing Keys in Key Storage 5-20 Security Precautions Clear_Key_Import 5-22 Clear_Key_Import (CSNBCKI) Restrictions Format Page Control_Vector_Generate 5-24 Control_Vector_Generate (CSNBCVG) Restrictions Format Control_Vector_Translate 5-26 Control_Vector_Translate (CSNBCVT) Restrictions Format Page Page Cryptographic_Variable_Encipher (CSNBCVE) Restrictions Format Cryptographic_Variable_Encipher 5-30 Data_Key_Export (CSNBDKX) Restrictions Format Parameters Data_Key_Export 5-32 Data_Key_Import (CSNBDKM) Data_Key_Import 5-34 Diversified_Key_Generate (CSNBDKG) Diversified_Key_Generate 5-36 Diversified_Key_Generate 5-38 Diversified_Key_Generate 5-40 Page Key_Export 5-42 Key_Export (CSNBKEX) Restrictions Key_Generate 5-44 Key_Generate (CSNBKGN) Restrictions Key_Generate 5-46 Key-Type Specifications Key_Generate 5-48 Figure 5-12. Key_Type and Key_Form Keywords for a Key Pair Key-Length Specification Key_Generate key-length the verb uses when you supply eight space characters with the key_length parameter. 5-50 Figure 5-13. Key Lengths by Key Type Key_Import (CSNBKIM) Key_Import 5-52 Page Key_Part_Import 5-54 Key_Part_Import (CSNBKPI) Key_Part_Import 5-56 Key_Test 5-58 Key_Test (CSNBKYT) Key_Test 5-60 Key_Token_Build (CSNBKTB) Restrictions Format Key_Token_Build 5-62 Key_Token_Change 5-64 Key_Token_Change (CSNBKTC) Restrictions Format Key_Token_Parse 5-66 Key_Token_Parse (CSNBKTP) Restrictions Format Key_Token_Parse 5-68 Key_Translate (CSNBKTR) Restrictions Format Key_Translate 5-70 Multiple_Clear_Key_Import (CSNBCKM) Restrictions Format Parameters Multiple_Clear_Key_Import 5-72 PKA_Decrypt (CSNDPKD) Restrictions Format Parameters PKA_Decrypt 5-74 PKA_Encrypt (CSNDPKE) Restrictions Format Parameters PKA_Encrypt 5-76 Page PKA_Symmetric_Key_Export 5-78 PKA_Symmetric_Key_Export (CSNDSYX) Restrictions Format PKA_Symmetric_Key_Export 5-80 PKA_Symmetric_Key_Generate (CSNDSYG) PKA_Symmetric_Key_Generate 5-82 PKA_Symmetric_Key_Generate 5-84 PKA_Symmetric_Key_Import 5-86 PKA_Symmetric_Key_Import (CSNDSYI) PKA_Symmetric_Key_Import 5-88 Page Prohibit_Export 5-90 Prohibit_Export (CSNBPEX) Restrictions Format Random_Number_Generate (CSNBRNG) Restrictions Format Parameters Page Chapter 6. Data Confidentiality and Data Integrity Encryption and Message Authentication Codes Ensuring Data Confidentiality 6-2 Ensuring Data Integrity MACing Segmented Data Page Decipher (CSNBDEC) Restrictions Format Parameters Decipher 6-6 Page Encipher 6-8 Encipher (CSNBENC) Restrictions Format Encipher 6-10 MAC_Generate (CSNBMGN) Restrictions MAC_Generate 6-12 MAC_Verify 6-14 MAC_Verify (CSNBMVR) Restrictions MAC_Verify 6-16 Chapter 7. Key-Storage Verbs Key Labels and Key-Storage Management Key-Label Content 7-2 DES_Key_Record_Create DES_Key_Record_Create (CSNBKRC) 7-4 Restrictions Format Parameters DES_Key_Record_Delete (CSNBKRD) Restrictions Format Parameters Page DES_Key_Record_List (CSNBKRL) Restrictions Format Parameters DES_Key_Record_List 7-8 DES_Key_Record_Read (CSNBKRR) Restrictions Format Parameters Required Commands DES_Key_Record_Write (CSNBKRW) 7-10 Restrictions Format Parameters PKA_Key_Record_Create (CSNDKRC) Restrictions Format Parameters PKA_Key_Record_Create 7-12 PKA_Key_Record_Delete (CSNDKRD) Restrictions Format Parameters Page PKA_Key_Record_List (CSNDKRL) Restrictions Format Parameters PKA_Key_Record_List 7-16 PKA_Key_Record_Read (CSNDKRR) Restrictions Format Parameters Page PKA_Key_Record_Write (CSNDKRW) Restrictions Format Parameters PKA_Key_Record_Write 7-20 Retained_Key_Delete (CSNDRKD) Restrictions Format Parameters Required Commands Retained_Key_List (CSNDRKL) 7-22 Restrictions Format Parameters Page Page Chapter 8. Financial Services Support Verbs Processing Financial PINs 8-2 Page Figure 8-2. Financial PIN Verbs 8-4 PIN-Verb Summary PIN-Calculation Method and PIN-Block Format Summary 8-6 Providing Security for PINs Using Specific Key Types and Key-Usage Bits to Help Ensure PIN Security Supporting Multiple PIN-Calculation Methods 8-8 PIN-Calculation Methods Data_Array Page Supporting Multiple PIN-Block Formats and PIN-Extraction Methods 8-10 PIN Profile Page PIN-Extraction Methods 8-12 Personal Account Number (PAN) Working With EMV Smart Cards Page Clear_PIN_Encrypt (CSNBCPE) Restrictions Clear_PIN_Encrypt 8-16 Clear_PIN_Generate 8-18 Clear_PIN_Generate (CSNBPGN) Clear_PIN_Generate 8-20 Clear_PIN_Generate_Alternate (CSNBCPA) Clear_PIN_Generate_Alternate 8-22 Clear_PIN_Generate_Alternate 8-24 When using the NL-PIN-1 keyword, identify the following elements in the data array: Clear_PIN_Generate_Alternate 8-26 CVV_Generate (CSNBCSG) Restrictions Format Parameters CVV_Generate 8-28 CVV_Verify 8-30 CVV_Verify (CSNBCSV) Restrictions Format CVV_Verify 8-32 Encrypted_PIN_Generate (CSNBEPG) Encrypted_PIN_Generate 8-34 Encrypted_PIN_Generate 8-36 Encrypted_PIN_Translate (CSNBPTR) Encrypted_PIN_Translate 8-38 Encrypted_PIN_Translate 8-40 Encrypted_PIN_Verify 8-42 Encrypted_PIN_Verify (CSNBPVR) Encrypted_PIN_Verify 8-44 Encrypted_PIN_Verify 8-46 Encrypted_PIN_Verify 8-48 Key_Encryption_Translate (CSNBKET) Key_Encryption_Translate 8-50 PIN_Change/Unblock 8-52 PIN_Change/Unblock (CSNBPCU) PIN_Change/Unblock 8-54 PIN_Change/Unblock 8-56 PIN_Change/Unblock 8-58 Secure_Messaging_for_Keys (CSNBSKY) Secure_Messaging_for_Keys 8-60 Secure_Messaging_for_PINs 8-62 Secure_Messaging_for_PINs (CSNBSPN) Secure_Messaging_for_PINs 8-64 SET_Block_Compose 8-66 SET_Block_Compose (CSNDSBC) Restrictions Format SET_Block_Compose 8-68 Page SET_Block_Decompose 8-70 SET_Block_Decompose (CSNDSBD) Restrictions SET_Block_Decompose 8-72 SET_Block_Decompose 8-74 Transaction_Validation (CSNBTRV) Restrictions Format Parameters Transaction_Validation 8-76 Page Page Appendix A. Return Codes and Reason Codes Return Codes Reason Codes Return Code 0 Return Code 4 Return Code 8 A-4 Page A-6 Page A-8 Page Return Code 12 A-10 Return Code 16 Page Appendix B. Data Structures Key Tokens Master Key Verification Pattern Token-Validation Value and Record-Validation Value B-2 Null Key-Token DES Key-Tokens Internal DES Key-Token Page External DES Key-Token Figure B-4. External DES Key-Token Format, Version X'00' Figure B-5. External DES Key-Token Format, Version X'01' RSA PKA Key-Tokens B-6 RSA Key-Token Sections PKA Key-Token Integrity B-8 Number Representation in PKA Key-Tokens Figure B-8. RSA Key-Token Header Figure B-9. RSA Private Key, 1024-Bit Modulus-Exponent Format B-10 Figure B-10 (Page 1 of 2). Private Key, 2048-BitChinese-Remainder Format Figure B-10 (Page 2 of 2). Private Key, 2048-BitChinese-Remainder Format B-12 Figure B-11. RSA Private Key, 1024-Bit Modulus-Exponent Format with OPK Figure B-12 (Page 1 of 2). RSA Private Key,Chinese-Remainder Format withOPK B-14 Figure B-12 (Page 2 of 2). RSA Private Key,Chinese-Remainder Format withOPK Figure B-13. RSA Public Key B-16 Figure B-14. RSA Private-Key Name Page Figure B-17. RSA Public-Key Certificate(s) Optional Information Subsection Header B-18 Figure B-18. RSA Public-Key Certificate(s) User Data TLV Figure B-19. RSA Public-Key Certificate(s) Environment Identifier (EID) TLV Figure B-21. RSA Public-Key Certificate(s) Signature Subsection B-20 RSA Private-Key Blinding Information: Figure B-22. RSA Private-Key Blinding Information Chaining-Vector Records Key-Storage Records Figure B-24. Key-Storage-File Header, Record 1 (not OS/400) B-22 Figure B-25. Key-Storage File Header, Record 2 (not OS/400) Figure B-26. Key-Record Format in Key Storage (not OS/400) Figure B-27. DES Key-Record Format, OS/400 Key Storage B-24 Figure B-28. PKA Key-Record Format, OS/400 Key Storage Key_Record_List Data Set Figure B-29 (Page 2 of 2). Key-Record-List Data SetFormat (Other ThanOS/400) B-26 Figure B-30 (Page 1 of 2). Key-Record-List Data SetFormat (OS/400 only) Figure B-30 (Page 2 of 2). Key-Record-List Data SetFormat (OS/400 only) B-28 Access-Control Data Structures Role Structure Basic Structure of a Role Aggregate Role Structure B-30 Access-Control-Point List Default Role Contents Profile Structure B-32 This section describes the data structures related to user profiles. Basic Structure of a Profile Aggregate Profile Structure Authentication Data Structure Page Page Examples of the Data Structures B-36 Passphrase authentication data User Profile Aggregate Profile Structure Access-Control-Point List B-38 Role Data Structure Aggregate Role Data Structure B-40 Master Key Shares Data Formats Figure B-46. Cloning Information Token Data Structure Figure B-47. Master Key Share TLV Figure B-48. Cloning Information Signature TLV Function Control Vector B-42 Figure B-49 (Page 2 of 2). FCV Distribution Structure Page Appendix C. CCA Control-Vector Definitions and Key Encryption DES Control-Vector Values C-2 Page C-4 Page C-6 Key-Form Bits, fff and FFF Specifying a Control-Vector-Base Value C-8 Page C-10 Page CCA Key Encryption and Decryption Processes C-12 CCA DES Key Encryption and Decryption Processes CCA RSA Private Key Encryption and Decryption Process Appendix C. CCA Control-Vector Definitions and Key Encryption C-13 Figure C-4. Multiply-Enciphering and Multiply-Deciphering CCA Keys PKA92 Key Format and Encryption Process C-14 Page Encrypting a Key_Encrypting Key in the NL-EPP-5 Format C-16 Changing Control Vectors Changing Control Vectors with the Pre-Exclusive-OR Technique Page C-18 Page Changing Control Vectors with the Control_Vector_Translate Verb C-20 Providing the Control Information for Testing the Control Vectors Mask Array Preparation Page Figure C-8. Control_Vector_Translate Verb Mask_Array Processing C-22 Selecting the Key-Half Processing Mode When the Target Key-Token CV Is Null C-24 Control_Vector_Translate Example Appendix D. Algorithms and Processes Cryptographic Key Verification Techniques Master Key Verification Algorithms SHA-1 Based Master Key Verification Method CCA DES-Key Verification Algorithm Encrypt Zeros DES Key Verification Algorithm Modification Detection Code (MDC) Calculation Methods Notation Used in Calculations D-4 MDC-1 Calculation MDC-2 Calculation MDC-4 Calculation Ciphering Methods General Data Encryption Processes D-6 Single-DES and Triple-DES for General Data ANSI X3.106 Cipher Block Chaining (CBC) Method ANSI X9.23 D-8 Page Triple-DES Ciphering Algorithms D-10 Figure D-7. Triple-DES CBC Encryption Process Figure D-8. Triple-DES CBC Decryption Process Figure D-9. EDE Algorithm D-12 Figure D-10. DED Process MAC Calculation Methods D-14 RSA Key-Pair Generation D-16 Access-Control Algorithms Passphrase Verification Protocol Design Criteria Page D-18 Master-Key-Splitting Algorithm Formatting Hashes and Keys in Public-Key Cryptography ANSI X9.31 Hash Format PKCS #1 Formats D-20 Appendix E. Financial System Verbs Calculation Methods and Data Formats E-2 PIN-Calculation Methods IBM 3624 PIN-Calculation Method IBM 3624 PIN Offset Calculation Method E-4 Netherlands PIN-1 Calculation Method IBM German Bank Pool Institution PIN-Calculation Method E-6 VISA PIN Validation Value (PVV) Calculation Method Interbank PIN-Calculation Method E-8 PIN-Block Formats 3624 PIN-Block Format ISO-0 PIN-Block Format E-10 ISO-1 PIN-Block Format ISO-2 PIN-Block Format E-12 UKPT Calculation Methods Deriving an ANSI X9.24 Unique-Key-Per-Transaction Key E-14 Performing the Special Encryption and Special Decryption Processes CVV and CVC Method E-16 VISA and EMV-Related Smart Card Formats and Processes Derivation of the Smart-Card-Specific Authentication Code Constructing the PIN-block for Transporting an EMV Smart-Card PIN Derivation of the CCA TDES-XOR Session Key E-18 Derivation of the EMV TDESEMVn Tree-Based Session-Key PIN-Block Self-encryption Page Appendix F. Verb List Figure F-1 (Page 1 of 3). Security API Verbsin Supported Environments Figure F-1 (Page 2 of 3). Security API Verbsin Supported Environments F-2 Figure F-1 (Page 3 of 3). Security API Verbsin Supported Environments Page Appendix G. Access-Control-Point Codes G-2 Figure G-1 (Page 1 of 4). Supported CCA Commands Appendix G. Access-Control-Point Codes G-3 Figure G-1 (Page 2 of 4). Supported CCA Commands G-4 Figure G-1 (Page 3 of 4). Supported CCA Commands Appendix G. Access-Control-Point Codes G-5 Figure G-1 (Page 4 of 4). Supported CCA Commands | | Page List of Abbreviations X-2 Glossary A B X-4 C D E F G H X-6 I J K N O P R S X-8 T U V W Numerics Page Index A B C D X-12 E F H I X-14 K L M X-16 N O P S T U V X