IBM Computer Hardware 2 User Manual

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  
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  
The Security API, Programming Fundamentals  
Verbs, Variables, and Parameters  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7  
. . . . . . . . . . . . . . . . . . 1-8  
. . . . . . . . . . . . . . . . . . . . . . . . 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  
. . . . . . . . . . . . . . . . . . . . . . . . . . 2-2  
Role-Based Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2  
Understanding Access Control  
Understanding Roles  
Understanding Profiles  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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  
Understanding and Managing Master Keys . . . . . . . . . . . . . . . . . . . . 2-12  
Symmetric and Asymmetric Master-Keys . . . . . . . . . . . . . . . . . . . 2-13  
Establishing Master Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13  
. . . . . . . . . . . 2-11  
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  
RSA Key-Management  
Key Generation  
. . . . . . . . . . . . . . . . . . . . . . . . 3-1  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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)  
PKA_Encrypt (CSNDPKE)  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-73  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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)  
Random_Number_Generate (CSNBRNG)  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-90  
. . . . . . . . . . . . . . . . . . . . 5-91  
Chapter 6. Data Confidentiality and Data Integrity  
Encryption and Message Authentication Codes  
Ensuring Data Confidentiality  
. . . . . . . . . . . . . . 6-1  
. . . . . . . . . . . . . . . . . . 6-1  
. . . . . . . . . . . . . . . . . . . . . . . . . . . 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)  
DES_Key_Record_Write (CSNBKRW) . . . . . . . . . . . . . . . . . . . . . . 7-10  
PKA_Key_Record_Create (CSNDKRC) . . . . . . . . . . . . . . . . . . . . . 7-11  
. . . . . . . . . . . . . . . . . . . . . . . 7-9  
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  
PIN-Verb Summary  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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  
Supporting Multiple PIN-Calculation Methods . . . . . . . . . . . . . . . . . . 8-8  
PIN-Calculation Methods  
Data_Array  
Supporting Multiple PIN-Block Formats and PIN-Extraction Methods  
PIN Profile  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8  
. . . 8-10  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10  
PIN-Extraction Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12  
. . . . . . . . . . . . . . . . . . . . . . 8-13  
Personal Account Number (PAN)  
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)  
CVV_Verify (CSNBCSV)  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-30  
Encrypted_PIN_Generate (CSNBEPG) . . . . . . . . . . . . . . . . . . . . . . 8-33  
Encrypted_PIN_Translate (CSNBPTR)  
Encrypted_PIN_Verify (CSNBPVR)  
. . . . . . . . . . . . . . . . . . . . . . 8-37  
. . . . . . . . . . . . . . . . . . . . . . . . 8-42  
|
Key_Encryption_Translate (CSNBKET) . . . . . . . . . . . . . . . . . . . . . . 8-49  
PIN_Change/Unblock (CSNBPCU) . . . . . . . . . . . . . . . . . . . . . . . . . 8-52  
Secure_Messaging_for_Keys (CSNBSKY) . . . . . . . . . . . . . . . . . . . . 8-59  
Secure_Messaging_for_PINs (CSNBSPN) . . . . . . . . . . . . . . . . . . . . 8-62  
SET_Block_Compose (CSNDSBC)  
. . . . . . . . . . . . . . . . . . . . . . . . 8-66  
SET_Block_Decompose (CSNDSBD) . . . . . . . . . . . . . . . . . . . . . . . 8-70  
Transaction_Validation (CSNBTRV) . . . . . . . . . . . . . . . . . . . . . . . . 8-75  
Appendix A. Return Codes and Reason Codes . . . . . . . . . . . . . . . A-1  
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
A-1  
A-1  
A-2  
A-3  
A-4  
Reason Codes  
Return Code 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Return Code 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Return Code 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Return Code 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10  
Return Code 16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11  
Appendix B. Data Structures  
Key Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
. . . . . . . . . . . . . . . . . . . . . . . . . .  
B-1  
B-1  
Master Key Verification Pattern . . . . . . . . . . . . . . . . . . . . . . . . . B-1  
Token-Validation Value and Record-Validation Value  
. . . . . . . . . . . .  
B-2  
B-2  
B-3  
B-3  
Null Key-Token  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
DES Key-Tokens  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Internal DES Key-Token  
. . . . . . . . . . . . . . . . . . . . . . . . . . .  
External DES Key-Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
RSA Key-Token Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7  
. . . . . . . . . . . . . . . . . . . . . . . . . . .  
RSA PKA Key-Tokens  
B-6  
B-8  
PKA Key-Token Integrity  
Number Representation in PKA Key-Tokens . . . . . . . . . . . . . . . . B-8  
Chaining-Vector Records  
Key-Storage Records  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-20  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21  
Key_Record_List Data Set  
Access-Control Data Structures  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-25  
. . . . . . . . . . . . . . . . . . . . . . . . . . B-28  
Role Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-29  
Basic Structure of a Role . . . . . . . . . . . . . . . . . . . . . . . . . . . B-29  
vi IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Aggregate Role Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . B-30  
Access-Control-Point List . . . . . . . . . . . . . . . . . . . . . . . . . . . B-30  
Default Role Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-31  
Profile Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32  
Basic Structure of a Profile . . . . . . . . . . . . . . . . . . . . . . . . . . B-32  
Aggregate Profile Structure . . . . . . . . . . . . . . . . . . . . . . . . . . B-33  
Authentication Data Structure  
Examples of the Data Structures . . . . . . . . . . . . . . . . . . . . . . . . B-36  
Passphrase authentication data . . . . . . . . . . . . . . . . . . . . . . . B-36  
. . . . . . . . . . . . . . . . . . . . . . . . B-33  
User Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-36  
Aggregate Profile Structure . . . . . . . . . . . . . . . . . . . . . . . . . . B-37  
Access-Control-Point List . . . . . . . . . . . . . . . . . . . . . . . . . . . B-38  
Role Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-39  
Aggregate Role Data Structure . . . . . . . . . . . . . . . . . . . . . . . . B-40  
Master Key Shares Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . B-41  
Function Control Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-42  
Appendix C. CCA Control-Vector Definitions and Key Encryption . . . . C-1  
DES Control-Vector Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1  
Key-Form Bits, ‘fff’ and ‘FFF’ . . . . . . . . . . . . . . . . . . . . . . . . . C-7  
Specifying a Control-Vector-Base Value . . . . . . . . . . . . . . . . . . . . . . C-7  
CCA Key Encryption and Decryption Processes . . . . . . . . . . . . . . . . . C-12  
CCA DES Key Encryption and Decryption Processes . . . . . . . . . . . . C-12  
CCA RSA Private Key Encryption and Decryption Process . . . . . . . . . C-12  
PKA92 Key Format and Encryption Process . . . . . . . . . . . . . . . . . . . C-14  
Encrypting a Key_Encrypting Key in the NL-EPP-5 Format  
. . . . . . . . . . C-16  
Changing Control Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-16  
Changing Control Vectors with the Pre-Exclusive-OR Technique . . . . . . C-16  
Changing Control Vectors with the Control_Vector_Translate Verb  
. . . . C-20  
Providing the Control Information for Testing the Control Vectors . . . . C-20  
Mask Array Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-20  
Selecting the Key-Half Processing Mode . . . . . . . . . . . . . . . . . . C-23  
When the Target Key-Token CV Is Null . . . . . . . . . . . . . . . . . . . C-24  
Control_Vector_Translate Example  
. . . . . . . . . . . . . . . . . . . . . C-24  
Appendix D. Algorithms and Processes . . . . . . . . . . . . . . . . . . . . D-1  
Cryptographic Key Verification Techniques . . . . . . . . . . . . . . . . . . . . D-1  
Master Key Verification Algorithms . . . . . . . . . . . . . . . . . . . . . . . D-1  
SHA-1 Based Master Key Verification Method . . . . . . . . . . . . . . . D-1  
S/390 Based Master Key Verification Method  
Asymmetric Master Key MDC-Based Verification Method  
. . . . . . . . . . . . . . . D-2  
. . . . . . . . D-2  
Key Token Verification Patterns . . . . . . . . . . . . . . . . . . . . . . . D-2  
CCA DES-Key Verification Algorithm . . . . . . . . . . . . . . . . . . . . . . D-2  
Encrypt Zeros DES Key Verification Algorithm  
. . . . . . . . . . . . . . . . D-3  
Modification Detection Code (MDC) Calculation Methods . . . . . . . . . . . . D-3  
Notation Used in Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . D-4  
MDC-1 Calculation  
MDC-2 Calculation  
MDC-4 Calculation  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5  
Ciphering Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5  
. . . . . . . . . . . . . . . . . . . . . . D-6  
General Data Encryption Processes  
Single-DES and Triple-DES for General Data . . . . . . . . . . . . . . . D-6  
ANSI X3.106 Cipher Block Chaining (CBC) Method . . . . . . . . . . . . D-7  
ANSI X9.23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-7  
Contents vii  
CCA Release 2.54  
Triple-DES Ciphering Algorithms  
. . . . . . . . . . . . . . . . . . . . . . . . D-10  
MAC Calculation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-13  
RSA Key-Pair Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-15  
Access-Control Algorithms  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-16  
. . . . . . . . . . . . . . . . . . . . . . . . D-16  
Passphrase Verification Protocol  
Design Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-16  
Description of the Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . D-16  
Master-Key-Splitting Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . D-18  
Formatting Hashes and Keys in Public-Key Cryptography . . . . . . . . . . . D-19  
ANSI X9.31 Hash Format  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . D-19  
PKCS #1 Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-19  
Appendix E. Financial System Verbs Calculation Methods and Data  
Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
. . . . . . . . . . . . . . . . . . . . . . .  
. . . . . . . . . . . . . . . . . . .  
E-1  
E-2  
E-3  
E-4  
PIN-Calculation Methods  
IBM 3624 PIN-Calculation Method  
IBM 3624 PIN Offset Calculation Method  
Netherlands PIN-1 Calculation Method . . . . . . . . . . . . . . . . . . . . . E-5  
IBM German Bank Pool Institution PIN-Calculation Method . . . . . . . . . E-6  
VISA PIN Validation Value (PVV) Calculation Method . . . . . . . . . . . . E-7  
Interbank PIN-Calculation Method  
. . . . . . . . . . . . . . . . . . . . . . .  
E-8  
PIN-Block Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-9  
3624 PIN-Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-9  
ISO-0 PIN-Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-10  
ISO-1 PIN-Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-11  
ISO-2 PIN-Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-12  
UKPT Calculation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-13  
Deriving an ANSI X9.24 Unique-Key-Per-Transaction Key  
. . . . . . . . . E-13  
. . E-15  
CVV and CVC Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-16  
. . . . . . . . . E-17  
Performing the Special Encryption and Special Decryption Processes  
VISA and EMV-Related Smart Card Formats and Processes  
Derivation of the Smart-Card-Specific Authentication Code . . . . . . . . . E-17  
Constructing the PIN-block for Transporting an EMV Smart-Card PIN . . . E-17  
Derivation of the CCA TDES-XOR Session Key  
Derivation of the EMV TDESEMVn Tree-Based Session-Key . . . . . . . . E-18  
PIN-Block Self-encryption  
. . . . . . . . . . . . . . . E-18  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . E-19  
Appendix F. Verb List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1  
. . . . . . . . . . . . . . . . . . G-1  
List of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-11  
Appendix G. Access-Control-Point Codes  
Glossary  
X-3  
viii IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figures  
1-1. CCA Security API, Access Layer, Cryptographic Engine . . . . . . . . 1-3  
2-1. CCA Node, Access-Control, and Master-Key Management Verbs . . 2-1  
2-2. Coprocessor-to-Coprocessor Master-Key Cloning . . . . . . . . . . . 2-16  
2-3. Cryptographic_Facility_Query Information Returned in the Rule Array 2-36  
3-1. Public-Key Key-Administration Services  
3-2. PKA96 Verbs with Key-Token Flow . . . . . . . . . . . . . . . . . . . . 3-2  
3-3. PKA_Key_Token_Build Key-Values-Structure Contents . . . . . . . 3-17  
. . . . . . . . . . . . . . . . . 3-1  
3-4. PKA_Key_Token_Change Rule_Array Keywords . . . . . . . . . . . 3-22  
4-1. Hashing and Digital Signature Services . . . . . . . . . . . . . . . . . . 4-1  
4-2. MDC_Generate Rule_Array Keywords  
5-1. Basic CCA DES Key-Management Verbs  
. . . . . . . . . . . . . . . . . 4-11  
. . . . . . . . . . . . . . . . 5-1  
5-2. Flow of Cryptographic Command Processing in a Cryptographic  
Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5  
5-3. Key Types and Verb Usage  
. . . . . . . . . . . . . . . . . . . . . . . . 5-7  
5-4. Control_Vector_Generate and Key_Token_Build CV Keyword  
Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9  
5-5. Control Vector Key-Subtype and Key-Usage Keywords  
. . . . . . . 5-10  
. . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13  
5-6. Key_Token Contents  
5-7. Use of Key Tokens and Key Labels . . . . . . . . . . . . . . . . . . . 5-13  
5-8. Key-Processing Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16  
5-9. Key Exporting and Importing . . . . . . . . . . . . . . . . . . . . . . . 5-19  
5-10. Control_Vector_Translate Rule_Array Keywords  
. . . . . . . . . . . 5-27  
5-11. Key_Type and Key_Form Keywords for One Key . . . . . . . . . . . 5-48  
5-12. Key_Type and Key_Form Keywords for a Key Pair . . . . . . . . . . 5-49  
5-13. Key Lengths by Key Type  
. . . . . . . . . . . . . . . . . . . . . . . . 5-50  
5-14. Key_Part_Import Rule_Array Keywords . . . . . . . . . . . . . . . . . 5-56  
5-15. Key_Token_Build Rule_Array Keywords . . . . . . . . . . . . . . . . 5-62  
5-16. Key_Token_Change Rule_Array Keywords  
. . . . . . . . . . . . . . 5-65  
5-17. Key_Token_Parse Rule_Array Keywords . . . . . . . . . . . . . . . . 5-67  
5-18. Key_Token_Build Form Keywords . . . . . . . . . . . . . . . . . . . . 5-91  
6-1. Data Confidentiality and Data Integrity Verbs  
7-1. Key-Storage-Record Services  
7-2. DES_Key_Record_Delete Rule_Array Keywords . . . . . . . . . . . . 7-5  
7-3. PKA_Key_Record_Delete Rule_Array Keywords  
. . . . . . . . . . . . . . 6-1  
. . . . . . . . . . . . . . . . . . . . . . . 7-1  
. . . . . . . . . . . 7-13  
7-4. PKA_Key_Record_Write Rule_Array Keywords . . . . . . . . . . . . 7-20  
8-1. Financial Services Support Verbs . . . . . . . . . . . . . . . . . . . . . 8-1  
8-2. Financial PIN Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4  
8-3. PIN Verb, PIN-Calculation Method, and PIN-Block-Format Support  
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6  
8-4. Pad-Digit Specification by PIN-Block Format . . . . . . . . . . . . . . 8-11  
8-5. PIN-Extraction Method Keywords by PIN-Block Format  
. . . . . . . 8-12  
8-6. Clear_PIN_Generate_Alternate Rule_Array Keywords (First Element) 8-23  
8-7. Clear_PIN_Generate_Alternate Rule_Array Keywords (Second  
Element)  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24  
8-8. Encrypted_PIN_Generate Rule_Array Keywords  
8-9. Encrypted_PIN_Translate Rule_Array Keywords  
. . . . . . . . . . . 8-35  
. . . . . . . . . . . 8-40  
8-10. Encrypted_PIN_Translate Required Hardware Commands  
. . . . . 8-41  
8-11. Encrypted_PIN_Verify PIN-Extraction Method . . . . . . . . . . . . . 8-45  
A-1. Return Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1  
A-2. Reason Codes for Return Code 0 . . . . . . . . . . . . . . . . . . . . A-2  
Copyright IBM Corp. 1997, 2005  
ix  
CCA Release 2.54  
A-3. Reason Codes for Return Code 4 . . . . . . . . . . . . . . . . . . . . A-3  
A-4. Reason Codes for Return Code 8 . . . . . . . . . . . . . . . . . . . . A-4  
A-5. Reason Codes for Return Code 12 . . . . . . . . . . . . . . . . . . . A-10  
A-6. Reason Codes for Return Code 16 . . . . . . . . . . . . . . . . . . . A-11  
B-1. PKA Null Key-Token Format . . . . . . . . . . . . . . . . . . . . . . . B-2  
B-2. Internal DES Key-Token, Version 0 Format (Version 2 Software) . . B-3  
B-3. Internal DES Key-Token, Version 3 Format  
. . . . . . . . . . . . . .  
B-3  
B-4. External DES Key-Token Format, Version X'00' . . . . . . . . . . . B-5  
B-5. External DES Key-Token Format, Version X'01' . . . . . . . . . . . B-5  
B-6. Key-Token Flag Byte 1 . . . . . . . . . . . . . . . . . . . . . . . . . . B-6  
B-7. Key-Token Flag Byte 2 . . . . . . . . . . . . . . . . . . . . . . . . . . B-6  
B-8. RSA Key-Token Header  
B-9. RSA Private Key, 1024-Bit Modulus-Exponent Format . . . . . . . . B-10  
B-10. Private Key, 2048-Bit Chinese-Remainder Format  
. . . . . . . . . . . . . . . . . . . . . . . . .  
B-9  
. . . . . . . . . . B-11  
B-11. RSA Private Key, 1024-Bit Modulus-Exponent Format with OPK . . B-13  
B-12. RSA Private Key, Chinese-Remainder Format with OPK . . . . . . . B-14  
B-13. RSA Public Key  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-16  
B-14. RSA Private-Key Name . . . . . . . . . . . . . . . . . . . . . . . . . . B-16  
B-15. RSA Public-Key Certificate(s) Section Header . . . . . . . . . . . . . B-17  
B-16. RSA Public-Key Certificate(s) Public Key Subsection . . . . . . . . . B-17  
B-17. RSA Public-Key Certificate(s) Optional Information Subsection  
Header  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18  
B-18. RSA Public-Key Certificate(s) User Data TLV . . . . . . . . . . . . . B-18  
B-19. RSA Public-Key Certificate(s) Environment Identifier (EID) TLV . . . B-18  
B-20. RSA Public-Key Certificate(s) Serial Number TLV  
B-21. RSA Public-Key Certificate(s) Signature Subsection  
. . . . . . . . . . B-18  
. . . . . . . . . B-19  
B-22. RSA Private-Key Blinding Information . . . . . . . . . . . . . . . . . . B-20  
B-23. Cipher, MAC_Generate, and MAC_Verify Chaining-Vector Format . B-20  
B-24. Key-Storage-File Header, Record 1 (not OS/400) . . . . . . . . . . . B-22  
B-25. Key-Storage File Header, Record 2 (not OS/400) . . . . . . . . . . . B-23  
B-26. Key-Record Format in Key Storage (not OS/400) . . . . . . . . . . . B-23  
B-27. DES Key-Record Format, OS/400 Key Storage . . . . . . . . . . . . B-24  
B-28. PKA Key-Record Format, OS/400 Key Storage . . . . . . . . . . . . B-24  
B-29. Key-Record-List Data Set Format (Other Than OS/400) . . . . . . . B-25  
B-30. Key-Record-List Data Set Format (OS/400 only)  
. . . . . . . . . . . B-27  
B-31. Role Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-29  
B-32. Aggregate Role Structure with Header . . . . . . . . . . . . . . . . . B-30  
B-33. Access-Control-Point Structure . . . . . . . . . . . . . . . . . . . . . . B-31  
B-34. Functions Permitted in Default Role . . . . . . . . . . . . . . . . . . . B-31  
B-35. Profile Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32  
B-36. Layout of Profile Activation and Expiration Dates . . . . . . . . . . . B-32  
B-37. Aggregate Profile Structure with Header . . . . . . . . . . . . . . . . B-33  
B-38. Layout of the Authentication Data Field . . . . . . . . . . . . . . . . . B-34  
B-39. Authentication Data for Each Authentication Mechanism . . . . . . . B-35  
B-40. Passphrase Authentication Data Structure . . . . . . . . . . . . . . . B-36  
B-41. User Profile Data Structure . . . . . . . . . . . . . . . . . . . . . . . . B-37  
B-42. Aggregate Profile Structure . . . . . . . . . . . . . . . . . . . . . . . . B-38  
B-43. Access-Control-Point List . . . . . . . . . . . . . . . . . . . . . . . . . B-38  
B-44. Role Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-39  
B-45. Aggregate Role Data Structure  
. . . . . . . . . . . . . . . . . . . . . B-40  
B-46. Cloning Information Token Data Structure . . . . . . . . . . . . . . . B-41  
B-47. Master Key Share TLV . . . . . . . . . . . . . . . . . . . . . . . . . . B-41  
B-48. Cloning Information Signature TLV  
. . . . . . . . . . . . . . . . . . . B-41  
B-49. FCV Distribution Structure  
. . . . . . . . . . . . . . . . . . . . . . . . B-42  
x
IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
C-1. Key Classes  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2  
C-2. Key Type Default Control-Vector Values . . . . . . . . . . . . . . . . C-3  
C-3. Control-Vector-Base Bit Map . . . . . . . . . . . . . . . . . . . . . . . C-5  
C-4. Multiply-Enciphering and Multiply-Deciphering CCA Keys . . . . . . C-13  
C-5. PKA96 Clear DES Key Record  
C-6. NL-EPP-5 Key Record Format . . . . . . . . . . . . . . . . . . . . . . C-16  
C-7. Exchanging a Key with a Non-Control-Vector System . . . . . . . . C-18  
C-8. Control_Vector_Translate Verb Mask_Array Processing . . . . . . . C-22  
. . . . . . . . . . . . . . . . . . . . . C-14  
C-9. Control_Vector_Translate Verb Process  
D-1. Versions of the MDC Calculation Method  
. . . . . . . . . . . . . . . . C-23  
. . . . . . . . . . . . . . . D-3  
D-2. Triple-DES Data Encryption and Decryption . . . . . . . . . . . . . . D-6  
D-3. Enciphering Using the CBC Method . . . . . . . . . . . . . . . . . . . D-8  
D-4. Deciphering Using the CBC Method . . . . . . . . . . . . . . . . . . . D-8  
D-5. Enciphering Using the ANSI X9.23 Method  
D-6. Deciphering Using the ANSI X9.23 Method  
. . . . . . . . . . . . . . D-9  
. . . . . . . . . . . . . . D-9  
D-7. Triple-DES CBC Encryption Process . . . . . . . . . . . . . . . . . . D-11  
D-8. Triple-DES CBC Decryption Process . . . . . . . . . . . . . . . . . . D-11  
D-9. EDE Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-12  
D-10. DED Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-12  
D-11. MAC Calculation Method . . . . . . . . . . . . . . . . . . . . . . . . . D-14  
D-12. Example of Logon Key Computation  
. . . . . . . . . . . . . . . . . . D-16  
E-1. Financial PIN Calculation Methods, Data Formats, Other Items . . . E-1  
E-2. 3624 PIN-Block Format . . . . . . . . . . . . . . . . . . . . . . . . . . E-9  
E-3. ISO-0 PIN-Block Format  
E-4. ISO-1 PIN-Block Format  
E-5. ISO-2 PIN-Block Format  
. . . . . . . . . . . . . . . . . . . . . . . . . E-10  
. . . . . . . . . . . . . . . . . . . . . . . . . E-11  
. . . . . . . . . . . . . . . . . . . . . . . . . E-12  
E-6. CVV Track 2 Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . E-16  
F-1. Security API Verbs in Supported Environments . . . . . . . . . . . . . F-1  
G-1. Supported CCA Commands  
. . . . . . . . . . . . . . . . . . . . . . . G-2  
Figures xi  
CCA Release 2.54  
xii IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Notices  
References in this publication to IBM products, programs, or services do not imply  
that IBM intends to make these available in all countries in which IBM operates.  
Any reference to an IBM product, program, or service is not intended to state or  
imply that only IBM’s product, program, or service may be used. Any functionally  
equivalent product, program, or service that does not infringe any of IBM’s  
intellectual property rights or other legally protectable rights may be used instead of  
the IBM product, program, or service. Evaluation and verification of operation in  
conjunction with other products, programs, or services, except those expressly  
designated by IBM, are the user’s responsibility.  
IBM may have patents or pending patent applications covering subject matter in  
this document. The furnishing of this document does not give you any license to  
these patents. You can send license inquiries, in writing, to the IBM Director of  
Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 10594, USA.  
Trademarks  
The following terms, denoted by an asterisk (*) in this publication, are trademarks of  
the IBM Corporation in the United States or other countries or both:  
3090  
ACF/VTAM  
AIX  
AIX/6000  
Application System/400  
CICS  
Enterprise System/9000  
eServer  
AS/400  
Enterprise System/3090  
Enterprise System/9370  
ES/3090  
ES/9000  
ES/9370  
IBM  
IBM Registry  
iSeries  
MVS/DFP  
IBM World Registry  
Micro Channel  
MVS/ESA  
MVS/SP  
MVS/XA  
OS/2  
OS/400  
Personal System/2  
PS/2  
Operating System/2  
Operating System/400  
Personal Security  
pSeries  
PS/ValuePoint  
POWERstation  
RS/6000  
POWERserver  
RACF  
System/370  
System/390  
S/390 Multiprise  
XGA  
S/390 G3 Enterprise Server  
Systems Application Architecture  
xSeries  
zSeries  
Copyright IBM Corp. 1997, 2005  
xiii  
CCA Release 2.54  
The following terms, denoted by a double asterisk (**) in this publication, are the  
trademarks of other companies:  
Diebold  
Docutel  
MasterCard  
Pentium  
NCR  
Diebold Inc.  
Docutel  
MasterCard International, Inc.  
Intel Corporation  
National Cash Register Corporation  
RSA Data Security, Inc.  
RSA  
UNIX  
VISA  
SET  
UNIX Systems Laboratories, Inc.  
VISA International Service Association  
SET Secure Electronic Transaction LLC  
xiv IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Revision History  
About This Publication  
The manual is intended for systems and applications analysts and application  
programmers who will evaluate or create programs for the IBM 4758 Common  
Cryptographic Architecture (CCA) support for the IBM 4758 Models 002 and 023  
technology used with IBM eServer iSeries (OS/400) Option 35, CCA CSP on  
OS/400 systems. Please reference the IBM iSeries Web sites for the specific  
features and supported levels of software related to the IBM 4758 technology.  
|
|
Release 2.54 code applies only to the IBM eServer iSeries environment. PC  
servers and IBM eServer pSeries servers use Release 2.41 code. This manual  
includes corrections which apply to Releases 2.41, 2.50, 2.51, 2.52, and 2.53.  
Users of IBM 4758, Models 001 and 013, should refer to the CCA Basic Services  
Reference And Guide Release 1.31/1.32 for the IBM 4758 Models 001 and 013  
manual available on the product Web site.  
Prerequisite to using this manual is familiarity with the contents of the IBM 4758  
PCI Cryptographic Coprocessor General Information Manual that discusses topics  
important to the understanding of the information presented in this manual:  
The IBM 4758 PCI Cryptographic Coprocessor  
An overview of cryptography  
Supported cryptographic functions  
System hardware features and software  
Organization of the relevant publications.  
Revision History  
|
|
|
Thirteenth Edition, December, 2004, CCA Support Program,  
Release 2.54  
This edition replaces the December, 2004, Release 2.53 manual.  
|
|
|
|
Release 2.54 incorporates a new verb, Key_Encryption_Translate (CSNBKET) to  
translate an encrypted double-length, external DATA key (having an all-zero control  
vector) from CBC encryption to CCA key-encryption, and from CCA key-encryption  
to CBC encryption.  
|
|
|
Twelfth Edition, December, 2004, CCA Support Program,  
Release 2.53  
This edition replaces the April, 2004, Release 2.52 manual.  
|
Release 2.53 incorporates two changes to improve security.  
|
|
|
In order to use regeneration date to create a particular RSA private-public  
key-pair you must authorize a new control point. See the Required Commands  
section of the PKA_Key_Generate verb.  
|
|
|
If you attempt to use an RSA private key having the CLONE attribute, the  
PKA_Decrypt, PKA_Symmetric_Key_Import, and SET_Block_Decompose verbs  
will abnormally terminate with return code 8, reason code 64 (decimal).  
Copyright IBM Corp. 1997, 2005  
xv  
Revision History  
CCA Release 2.54  
Eleventh Edition, April, 2004, CCA Support Program,  
Release 2.52  
This revision to the February, 2004, edition of the IBM 4758 CCA Basic Services  
Reference and Guide for the IBM 4758 Models 002 and 023, Release 2.52,  
replaces the February, 2004, Release 2.51 edition. Incorporated changes include:  
Addition of a second set of issuer-master key parameters with revised  
processing in the PIN_Change/Unblock (CSNBPCU) verb. The processing  
changes are further described in “VISA and EMV-Related Smart Card Formats  
and Processes” on page E-17.  
Documentation of the RESETBAT rule-array keyword in the  
Cryptographic_Facility_Control verb (CSUACFC) you use to reset the indication  
of a low battery. This capability was added with Release 2.41.  
In Appendix A, removal of return code 12, reason code 093.  
Release 2.52 is only available for the IBM eServer iSeries. This manual includes  
changes for Release 2.41 and Release 2.51 users as described in the following  
sections.  
Tenth Edition, February 2004, CCA Support Program,  
Release 2.51  
This tenth edition of the IBM 4758 CCA Basic Services Reference and Guide  
Release 2.51 for the IBM 4758 Models 002 and 023 technology describes the  
Common Cryptographic Architecture (CCA) application programming interface (API)  
that is supported by the PCI Cryptographic Coprocessor feature available with  
IBM eServer iSeries and OS/400 Option 35, CCA CSP.  
The manual also includes updates and corrections to the previous editions for  
Release 2.50, Release 2.41 and earlier. The revision bar, as shown at the left,  
marks important changes and extensions to material previously published in the  
Ninth Edition of the Basic Services manual.  
Release 2.51 for the IBM eServer iSeries includes these additional and modified  
EMV-smart-card-related capabilities enhancing the earlier Release 2.50:  
1. Addition of the tree format key-diversification system, defined in the EMV 2000  
document, Annex A1.3, to the Diversified_Key_Generate and  
PIN_Change/Unblock verbs.  
2. The double-length issuer-master-key in the Diversified_Key_Generate and  
PIN_Change/Unblock verbs must have unequal halves.  
3. The issuer-master-key control-vector encoding is extended to support use of  
the DALL combination in the PIN_Change/Unblock verb.  
4. The key-generating key control-vector encoding is extended to support use of  
DDATA, DMAC, and DMV encodings provided the control vector for the  
generated key has a conforming control vector.  
5. Extension of the Message Authentication Code (MAC) MAC_Generate and  
MAC_Verify verbs to support EMV-required post-padding of a message.  
6. Corrected the order of the parameters on the Secure_Messaging_for_PINs  
verb. The PIN_encrypting_key_identifier follows the input_PIN_block  
parameter.  
Release 2.50 incorporated these capabilities and changes:  
xvi IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Revision History  
1. Functions in support of EMV-compatible smart-cards.  
Support of the PIN Change/Unblock function described in the VISA  
Integrated Circuit Card Specification Manual, Section C.11  
Support of the key-generation function used for secure messaging  
described in the VISA Integrated Circuit Card Specification Manual, Section  
B.4  
Encryption of PINs and keys for inclusion in smart-card transactions with  
EMV-compatible smart cards.  
This support is provided through:  
A new verb, PIN_Change/Unblock (CSNBPCU), to create a PIN block to  
change the PIN accepted by a smart card  
An extension to the Diversified_Key_Generate (CSNBDKG) verb enabling  
session-key generation for secure messaging  
A new verb, Secure_Messaging_for_Keys (CSNBSKY), to encrypt a key  
under a session key  
A new verb, Secure_Messaging_for_PINs (CSNBSPN), to encrypt a PIN  
under a session key  
The next item relating to ISO 9796-2 digital signature verification.  
2. An extension to the PKA_Encrypt (CSNDPKE) verb enabling verification of  
digital signatures with any hash formatting method (for example, ISO 9796-2)  
through the public-key enciphering of data in the zero-pad format.  
Ninth Edition, Revised September, 2003, CCA Support Program,  
Release 2.41  
This revised Release 2.41 manual, dated September, 2003, contains minor editorial  
changes and these corrections:  
Figure C-3 on page C-5 is changed to note that a SECMSG key is always  
double length (“fff” bits changed to “FFF”).  
Figure C-3 on page C-5 is changed to reflect that key-encrypting keys, bits  
35-37, must be B'000'. The text in item 2 of section “Specifying a  
Control-Vector-Base Value” on page C-7 which previously described these bits  
has been removed. Testing for these control vector bits has not been  
implemented.  
The padding for a Current Key Serial Number must be four bytes of X'00'  
rather than four space characters as previously stated in “Current Key Serial  
Number” on page 8-11.  
The revision bar, as shown at the left, marks the important changes.  
Ninth Edition, Revised August 2002, CCA Support Program,  
Release 2.41  
This revised Release 2.41 manual incorporates corrected information about the  
name for a Retained RSA key and other minor editorial changes.  
About This Publication xvii  
Revision History  
CCA Release 2.54  
Eighth Edition, Revised, CCA Support Program, Release 2.41  
This revised Release 2.41 manual incorporates additional information concerning  
access controls (see “CCA Access-Control” on page 2-2) and other minor editorial  
changes.  
Eighth Edition, CCA Support Program, Release 2.41  
The major items changed, extended, or added in Release 2.41 include:  
The Key_Export, Key_Import, Data_Key_Export, and Data_Key_Import now  
require the exporter or importer key to have unique key-halves when importing  
or exporting a key with unequal halves. You can regress to less-secure  
operation which does not enforce the restriction by activating an additional  
access control command point.  
The Key_Part_Import verb has been modified in two ways:  
– For double-length keys, unless a new access-control point is enabled in the  
governing role, the previously accumulated key-value and the resulting  
key-value must both have equal (“replicated”) key-halves or both have  
unequal key-halves. This test is ignored if the previously accumulated key  
has all key bits other than parity bits set to zero. This increases security by  
guaranteeing that the strength of the key is not modified when combining  
the new key part.  
“Replicated key-half” means that the first part (half) and the last half of a  
double-length DES key have equal values and thus performs as though the  
key were single length.  
– Additional keywords are added to the rule_array that permit enforcing  
separation between individuals who can update the accumulated key and  
one who can make the key operational (that is, switch off the control-vector  
key-part bit). Note that the Cryptographic Node Management utility is not  
updated to take advantage of this extension.  
The Encrypted_PIN_Generate verb (CSNBEPG) has be extended to include  
support of the 3624 PIN-calculation method through use of the IBM-PIN  
keyword.  
The Encrypted_PIN_Verify verb (CSNBPVR) has be extended to optionally  
enforce ensuring that PINs are four digits in length when using the VISA-PVV  
calculation method through the use of the VISAPVV4 keyword.  
Host-side key-caching, which has been performed since Release 2.10, can be  
switched off using an environment variable. This can be important where a key  
can be updated by one process, and used by one or more other concurrent  
processes. See “Host-side Key Caching” on page 1-7.  
Fixes have been applied to the Diversified_Key_Generate,  
Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs. The control vector  
checking is corrected to properly account for non-default control-vector values.  
The Encrypted_PIN_Translate verb now returns reason code 154 instead of 43.  
In Windows NT and 2000 environments, the code is repaired to permit  
multi-threaded support of multiple Coprocessors.  
New drivers are supplied for AIX which support 32-bit and 64-bit environments.  
The Cryptographic Node Management utility (CNM) is modified to prohibit use  
of key lengths greater than 1024-bits when performing master-key cloning. You  
xviii IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Revision History  
can create an application to to clone keys having any of the CSS, CSR, and  
SA keys longer than 1024-bits. See “Establishing Master Keys” on page 2-13.  
The PKA_Key_Token_Change verb now returns return code 0 and reason code  
0 if you request to update a key token that contains only a public key. A key  
token containing only a public key is legitimate, but the  
PKA_Key_Token_Change verb will have no effect on such a key token. The  
verb used to return reason code 8 if the token only contained public-key  
information.  
The command names listed in this book, in the IBM 4758 PCI Cryptographic  
Coprocessor CCA Support Program Installation Manual, and in the  
Cryptographic Node Management utility have been made the same.  
The Key_Token_Change and DES_Key_Record_Create verbs now work  
correctly with master keys having 3 unique parts (the CCA master keys are  
triple length).  
The diagnostic trace facility has been removed from the “SECY”  
DLL/shared-library. If tracing is required in the future for diagnostic purposes,  
IBM can supply tracing code upon customer agreement to install such code.  
Seventh Edition, CCA Support Program, Release 2.40  
The seventh edition of the IBM 4758 CCA Basic Services Reference and Guide  
Version 2.40 for the IBM 4758 Models 002 and 023 technology and describes the  
Common Cryptographic Architecture (CCA) application programming interface (API)  
that is supported by the CCA Support Program, Release 2.40, for the IBM PCI  
Cryptographic Coprocessor technology.  
Important changes and extensions to material previously published in the Basic  
Services manual:  
Release 2.40.  
The major items changed, extended, or added in Release 2.40 include:  
“Overlapped Processing” on page 1-7 describes restrictions on the number of  
concurrent calls to the CCA API. This is a publication-only change to describe  
the existing implementation.  
The timer function incorporated in the CP/Q++ control program employed by  
the CCA implementation is upgraded to keep proper time to the accuracy of the  
Coprocessor's electronics.  
Various performance enhancements have been incorporated in both the  
CP/Q++ control program and CCA code resulting in up to a 30% throughput  
change (especially for the PIN verbs).  
The IBM 4758 Coprocessor technology has always generated RSA CRT keys  
with the key-components p>q. Beginning with Release 2.40, imported keys  
having q>p will also be usable, but with a significant performance penalty since  
the inverse of U is calculated each time such a key is encountered.  
ANSI X9.24 Unique-Key-Per-Transaction support is added including the UKPT  
control vector bit on KEYGENKY key types and extensions to the  
Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs. Also, a number of  
editorial changes are incorporated in Chapter 8, “Financial Services Support  
Verbs.”  
About This Publication xix  
Revision History  
CCA Release 2.54  
The PKA_Symmetric_Key_Export, PKA_Symmetric_Key_Generate, and  
PKA_Symmetric_Key_Import verbs are updated to include support of the  
“OAEP” key-wrapping technique as specified in the RSA PKCS#1-v2.0  
specification.  
The action associated with the derivation-counter in control vector bits 12-14 in  
the Diversified_Key_Generate verb when using the TDES-ENC and TDES-DEC  
keywords is described on page 5-37.  
Weak-key checking in the Master_Key_Process verb is corrected. Note that  
obtaining a weak key from a random process is an incredibly rare event.  
The Key_Test verb is updated to correctly process the ENC-ZERO method in  
all cases.  
The RSA key token format descriptions have updated and corrected  
information, see “RSA PKA Key-Tokens” on page B-6. The blinding  
information fields are removed from the description of private key section types  
X'06' and X'08'. This information is not required since blinding is not used  
due to the electronic design of the IBM 4758 Models 002 and 023  
Coprocessors.  
Control vector user-definition bits 4 and 5 are reserved for use by User Defined  
Extension code (UDX) and are not tested or set by the standard CCA product.  
Bit 61 will prevent the standard CCA implementation from actively using a key,  
however, a key with this control vector can be generated, exported, and  
imported. See C-11.  
Corrected checking of the old-DES-master-key when updating master keys.  
Corrected the Transaction_Validation verb when encountering lower-case rule  
array keywords.  
Corrected initialization of CCA within the Coprocessor so that in a  
multi-Coprocessor installation the host system will only attempt to access  
CCA-initialized Coprocessors.  
Corrected the processing of a version 0 external private key token.  
Corrected the Encrypted_PIN_Translate PIN extraction process to use the  
input-PIN-profile specified extraction method (rather than a method specified in  
the output profile).  
Corrected the PKA_Symmetric_Key_Import verb when processing  
double-length keys using the ZERO-PAD option.  
Sixth Edition, CCA Support Program, Release 2.30/2.31  
This is the sixth edition of the IBM 4758 CCA Basic Services Reference and Guide  
Version 2.31 for the IBM 4758 Models 002 and 023 technology and describes the  
Common Cryptographic Architecture (CCA) application programming interface (API)  
that is supported by the CCA Support Program, Release 2.30/2.31, for the IBM PCI  
Cryptographic Coprocessor technology.  
There are no major items changed, extended, or added in Release 2.31.  
xx IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Fifth Edition, CCA Support Program, Release 2.30  
The fifth edition of the IBM 4758 CCA Basic Services Reference and Guide Version  
2.30 for the IBM 4758 Models 002 and 023 technology and describes the Common  
Cryptographic Architecture (CCA) application programming interface (API) that is  
supported by the CCA Support Program, Release 2.30, for the IBM PCI  
Cryptographic Coprocessor technology.  
These items have been changed, extended, or added in Release 2.30:  
1. Formal support for AIX and Windows 2000  
2. Under application programming control, multiple Coprocessors can be used to  
implement the CCA. The implementation extends the function previously  
available on the IBM OS/400 platform. See the discussion and these verbs:  
“Multi-Coprocessor Capability” on page 2-10  
Cryptographic_Resource_Allocate (CSUACRA, page 2-44)  
Cryptographic_Resource_Deallocate (CSUACRD, page 2-46).  
Note: IBM has limited objectives for the support provided in Release 2.30.  
The approach to multiple-Coprocessor support may be revised in a subsequent  
release, possibly with changes to the API provided in the current release.  
3. Added verb Random_Number_Tests (CSUARNT, page 2-46) so that you can  
test the random number generator and to cause the Coprocessor to run the  
FIPS-mandated known-answer tests.  
4. Extended these verbs with ANSI X9.31 capabilities:  
Digital_Signature_Generate (CSNDDSG, page 4-4)  
Digital_Signature_Verify (CSNDDSV, page 4-7).  
5. Added support of the RIPEMD160 algorithm. See verb One_Way_Hash  
(CSNBOWH, page 4-13).  
Also modified the verb to employ the Coprocessor's SHA-1 engine when  
calculating the SHA-1 hash for longer text strings.  
6. Added support of the IBM DES-based MDC-2 and MDC-4 hashing processes.  
See the MDC_Generate (CSNBMDG, page 4-10) verb.  
7. Added additional diversified key support and supporting key types. See verb  
Diversified_Key_Generate (CSNBDKG, page 5-35), and the related descriptions  
of key types and control vectors at “Key-Usage Restrictions” on page 5-6 and  
Appendix C, “CCA Control-Vector Definitions and Key Encryption.”  
Also extended these verbs to support the additional DKYGENKY and SECMSG  
key types:  
Control_Vector_Generate (CSNBCVG, page 5-24)  
Key_Token_Build (CSNBKTB, page 5-61)  
Key_Token_Parse (CSNBKTP, page 5-66).  
8. Added support for generating and validating the American Express card  
security codes (CSC) with the Transaction_Validation (CSNBTRV, page 8-75)  
verb.  
About This Publication xxi  
CCA Release 2.54  
Organization  
This manual includes:  
Chapter 1, “Introduction to Programming for the IBM CCA” presents an  
introduction to programming for the CCA application programming interface and  
products.  
Chapter 2, “CCA Node-Management and Access-Control” provides a basic  
explanation of the access-control system implemented within the hardware.  
The chapter also explains the master-key concept and administration, and  
introduces CCA DES key-management.  
Chapter 3, “RSA Key-Management” explains how to generate and distribute  
RSA keys between CCA nodes and with other RSA implementations.  
Chapter 4, “Hashing and Digital Signatures” explains how to protect and  
confirm the integrity of data using data hashing and digital signatures.  
Chapter 5, “DES Key-Management” explains basic DES key-management  
services available with CCA.  
Chapter 6, “Data Confidentiality and Data Integrity” explains how to encipher  
data using DES and how to verify the integrity of data using the DES-based  
Message Authentication Code (MAC) process. The ciphering and MACing  
services are described.  
Chapter 7, “Key-Storage Verbs” explains how to use key labels and how to  
employ key storage.  
Chapter 8, “Financial Services Support Verbs” explains services for the  
cryptographic portions of the Secure Electronic Transaction (SET) protocol and  
PIN-processing services.  
These appendices are included:  
Appendix A, “Return Codes and Reason Codes” describes the return codes  
and reason codes issued by the Coprocessor.  
Appendix B, “Data Structures” describes the various data structures for key  
token, chaining-vector records, key-storage records, and the key-record-list  
data set.  
Appendix C, “CCA Control-Vector Definitions and Key Encryption” describes  
the control-vector bits and provides rules for the construction of a control  
vector.  
Appendix D, “Algorithms and Processes” describes in further detail the  
algorithms and processes mentioned in this book.  
Appendix E, “Financial System Verbs Calculation Methods and Data Formats”  
describes processes and formats implemented by the PIN-processing support.  
xxii IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Related Publications  
In addition to the manuals listed below, you may wish to refer to other CCA product  
publications which may be of use with applications and systems you might develop  
for use with the IBM 4758 product. While there is substantial commonality in the  
API supported by the CCA products, and while this manual seeks to guide you to a  
common subset supported by all CCA products, other individual product  
publications may provide further insight into potential issues of compatibility.  
IBM 4758 PCI Cryptographic Coprocessor All of the IBM 4758-related  
publications can be obtained from the Library page that you can reach  
from the IBM 4758 home page at:  
http://www.ibm.com/security/cryptocards.  
IBM 4758 PCI Cryptographic Coprocessor General Information Manual  
The General Information manual is suggested reading prior to reading  
this manual.  
IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Guide  
Describes the installation of the CCA Support Program and the  
operation of the Cryptographic Node Management utility.  
IBM 4758 PCI Cryptographic Coprocessor Installation Manual  
Describes the physical installation of the IBM 4758 and the  
battery-changing procedure.  
Building a High-Performance Programmable, Secure Coprocessor  
A research paper describing the security aspects and code loading  
controls of the IBM 4758.  
Custom Programming for the IBM 4758 The Library portion of the IBM 4758 Web  
site also includes programming information for creating applications that  
perform within the IBM 4758. See the reference to Custom  
Programming under the Publications heading. The IBM 4758 Web site  
is located at http://www.ibm.com/security/cryptocards.  
IBM Transaction Security System Products The product publications for the IBM  
4753, IBM 4754, IBM 4755, and the IBM Personal Securitycard can  
also be found under Publications on the IBM 4758 Library Web page;  
start at http://www.ibm.com/security/cryptocards.  
IBM S/390 Integrated Cryptography Hardware and Software These manuals  
provide a starting point for additional information:  
GC23-3972, OS/390 V2R4.0 ICSF Overview  
SC23-3976, OS/390 ICSF Programming Guide.  
Cryptography Publications  
The following publications describe cryptographic standards, research, and  
practices relevant to the Coprocessor:  
Applied Cryptography: Protocols, Algorithms, and Source Code in C, Second  
Edition, Bruce Schneier, John Wiley & Sons, Inc. ISBN 0-471-12845-7 or ISBN  
0-471-11709-9  
IBM Systems Journal Volume 30 Number 2, 1991, G321-0103  
IBM Systems Journal Volume 32 Number 3, 1993, G321-5521  
About This Publication xxiii  
CCA Release 2.54  
IBM Journal of Research and Development Volume 38 Number 2, 1994,  
G322-0191  
USA Federal Information Processing Standard (FIPS):  
Data Encryption Standard, 46-1-1988  
Secure Hash Algorithm, 180-1, May 31, 1994  
Cryptographic Module Security, 140-1.  
PKCS #1&v2.0: RSA Cryptography Standard, RSA Laboratories, October 1,  
1998.  
Obtain from http://www.rsasecurity.com/rsalabs/pkcs.  
ISO 9796 Digital Signal Standard  
Internet Engineering Taskforce RFC 1321, April 1992, MD5  
Secure Electronic Transaction** Protocol Version 1.0, May 31, 1997.  
xxiv IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 1. Introduction to Programming for the IBM CCA  
This chapter introduces you to the IBM Common Cryptographic Architecture (CCA)  
application programming interface (API). This chapter explains some basic  
concepts you use to obtain cryptographic and other services from the PCI  
Cryptographic Coprocessor and its CCA Support Program feature. Before  
continuing, please review the “About This Publication” on page xv and first become  
familiar with prerequisite information as described in that section.  
In this chapter you can read about:  
What CCA services are available with the IBM 4758  
An overview of the CCA environment  
The Security API, programming fundamentals  
How the verbs are organized in the remainder of the book.  
What CCA Services Are Available with the IBM 4758  
CCA products provide a variety of cryptographic processes and data-security  
techniques. Your application program can call verbs (services) to perform these  
types of functions:  
Encrypt and decrypt information, generally using the DES algorithm in the  
cipher block chaining (CBC) mode to enable data confidentiality  
Hash data to obtain a digest, or process the data to obtain a message  
authentication code (MAC), that is useful in demonstrating data integrity  
Form and validate digital signatures to demonstrate both data integrity and  
non-repudiation  
Generate, encrypt, translate, and verify finance industry personal identification  
numbers (PINs) and transaction validation messages with a comprehensive set  
of PIN-processing services  
Manage the various keys necessary to perform the above operations. CCA is  
especially strong and versatile in this area. Inadequate key-management  
techniques are a major source of weakness in many other cryptographic  
implementations.  
Administrative services for controlling the initialization and operation of the CCA  
node.  
This book describes the many available services in the following chapters. The  
services are grouped by topic and within a chapter are listed in alphabetical order  
by name. Each chapter opens with an introduction to the services found in that  
chapter.  
The remainder of this chapter provides an overview of the structure of a CCA  
cryptographic node and introduces some important concepts and terms.  
Copyright IBM Corp. 1997, 2005  
1-1  
CCA Release 2.54  
An Overview of the CCA Environment  
Figure 1-1 on page 1-3 provides a conceptual framework for positioning the CCA  
Security API. Application programs make procedure calls to the API to obtain  
cryptographic and related I/O services. The CCA API is designed so that a call can  
be issued from essentially any high-level programming language. The call, or  
request, is forwarded to the cryptographic-services access layer and receives a  
synchronous response. That is, your application program loses control until the  
access layer returns a response at the conclusion of processing your request.  
The products that implement the CCA API consist of both hardware and software  
components. The software consists of application development support and  
runtime software components.  
The application development support software primarily consists of language  
bindings that can be included in new applications to assist in accessing  
services available at the API. Language bindings are provided for the C  
programming language. The OS/400 Option 35, CCA CSP feature also  
provides language bindings for COBOL, RPG, and CL.1  
The runtime software can be divided into the following categories:  
– Service-requesting programs, including utility programs and application  
programs  
– An “agent” function that is logically part of the calling application program or  
utility  
– An environment-dependent request routing function  
– The server environment that gives access to the cryptographic engine.  
Generally, the cryptographic engine is implemented in a hardware device that  
includes a general-purpose processor and often also includes specialized  
cryptographic electronics. These components are encapsulated in a protective  
environment to enhance security.  
The utility programs include support for administering the hardware access-controls,  
administering DES and public-key cryptographic keys, and configuring the software  
support. See the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program  
Installation Manual, for a description of the utility programs provided with the  
Cryptographic Adapter Services licensed software.  
No utility programs are available for the CCA support on the IBM eServer iSeries  
platform. There are sample programs available for your consideration that  
administer hardware access-control and manage DES and public-key cryptographic  
keys. If you have Internet access, refer to these topics by following the OS/400 link  
from the CCA support page of the product Web site,  
http://www.ibm.com/security/cryptocards.  
You can create application programs that use the products via the CCA API, or you  
can purchase applications from IBM or other sources that use the products. This  
book is the primary source of information for designing systems and application  
programs that use the CCA API with the IBM 4758 Coprocessor.  
1
For availability of the various OS/400 code levels, see the eServer iSeries OS/400 Web site.  
1-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure 1-1. CCA Security API, Access Layer, Cryptographic Engine  
IBM 4758 PCI Cryptographic Coprocessor: The Coprocessor provides a secure  
programming and hardware environment wherein DES and RSA processes are  
performed. The CCA support program enables applications to employ a set of  
DES- and RSA-based cryptographic services utilizing the IBM 4758 hardware.  
Such services include:  
RSA key-pair generation  
Digital signature generation and verification  
Cryptographic key wrapping and unwrapping, including the SET-standardized  
“OAEP” key-wrapping process  
Data encryption and MAC generation/verification  
PIN processing for the financial services industry  
Other services, including DES key-management based on CCA's  
control-vector-enforced key separation.  
CCA: IBM has created the IBM Common Cryptographic Architecture (CCA) as the  
basis for a consistent cryptographic product family. Implementations of this  
architecture were first released in 1989, and it has been extended throughout the  
years. The IBM 4758 and its CCA support program feature are a recent CCA  
product offering that today implements a portion of those functions available with  
older products as well as many new services such as the support of the SET**  
protocol.  
Chapter 1. Introduction to Programming for the IBM CCA 1-3  
CCA Release 2.54  
Applications employ the CCA security API to obtain services from and to manage  
the operation of a cryptographic system that meets CCA architecture specifications.  
Cryptographic Engine: The CCA architecture defines a cryptographic subsystem  
that contains a cryptographic engine operating within a protected boundary. See  
Figure 1-1 on page 1-3. The Coprocessor's tamper-resistant, tamper-responding  
environment provides physical security for this boundary, and the CCA architecture  
provides the concomitant logical security needed for the full protection of critical  
information.  
Access Control: Each CCA node has an access-control system enforced by the  
hardware and protected software. This access-control system permits you to  
determine whether programs and persons can use the cryptographic and  
data-storage services. Although your computing environment may be considered  
open, the specialized processing environment provided by the cryptographic engine  
can be kept secure; selected services are provided only when logon requirements  
are met. The access-control decisions are performed within the secured  
environment of the cryptographic engine and cannot be subverted by rogue code  
that might run on the main computing platform.  
Coprocessor Certification: After quality checking a newly manufactured  
Coprocessor, IBM loads and certifies the embedded software. Following the  
loading of basic, authenticated software, the Coprocessor generates an RSA  
key-pair and retains the private key within the cryptographic engine. The  
associated public key is signed by a key securely held at the manufacturing facility,  
and then the signed device key is stored within the Coprocessor. The  
manufacturing facility key has itself been signed by a securely held key unique to  
the IBM 4758 product line.  
The private key within the Coprocessor—known as the device private key—is  
retained in the Coprocessor. From this time on, the Coprocessor sets all  
security-relevant keys and data items to zero if tampering is detected or if the  
Coprocessor batteries are removed. This zeroization is irreversible and will  
result in the permanent loss of the factory-certified device key, the device private  
key, and all other data stored in battery-protected memory. Certain critical data  
stored in the Coprocessor flash memory is encrypted. The key used to encrypt  
such data is itself retained in the battery protected memory that is zeroized upon a  
tamper detection event.  
Master Key: When using the CCA architecture, working keys—including session  
keys and the RSA private keys used at a node to form digital signatures or to  
unwrap other keys—are generally stored outside of the cryptographic-engine  
protected environment. These working keys are wrapped (DES triple-enciphered)  
by a master key. The master key is held in the clear (not enciphered) within the  
cryptographic engine.  
The number of keys a node can use is restricted only by the storage capabilities of  
the node, not by the finite amount of storage within the Coprocessor secure  
module. In addition, keys can be used by other cryptographic nodes that have the  
same master-key data. This feature is useful in high-availability or high-throughput  
environments where multiple cryptographic processors must function in parallel.  
1-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Establishing a Master Key: To protect working keys, the master key must be  
generated and initialized in a secure manner. One method uses the internal  
random-number generator for the source of the master key. In this case, the  
master key is never external to the node as an entity, and no other node will have  
the same master key2 unless master-key cloning is authorized and in use. If the  
Coprocessor detects tampering and destroys the master key, there is no way to  
recover the working keys that it wrapped.  
Another master-key-establishment method enables authorized users to enter  
multiple, separate 168-bit key parts into the cryptographic engine. As each part is  
entered, that part is exclusive-ORed with the contents of the new master-key  
register. When all parts have been accumulated, a separate command is issued to  
promote the contents of the current master-key register to the old master-key  
register, and to promote the contents of the new master-key register to the current  
master-key register.  
A master key can be “cloned” (copied) from one IBM 4758 CCA node to another  
IBM 4758 CCA node through a process of master-key-shares distribution. This  
process is protected through the use of digital certificates and authorizations.  
Under this process, the master key can be reconstituted in one or more additional  
IBM 4758s through the transport of encrypted shares of the master key.  
“Understanding and Managing Master Keys” on page 2-12 provides additional  
detail about master-key management.  
CCA Verbs: Application and utility programs (requestors) obtain service from the  
CCA support program by issuing service requests (“verb calls” or “procedure calls”)  
to the runtime subsystem. To fulfill these requests, the support program obtains  
service from the Coprocessor software and hardware.  
The available services are collectively described as the CCA security API. All of  
the software and hardware accessed through the CCA security API should be  
considered an integrated subsystem. A command processor performs the verb  
request within the cryptographic engine.  
Commands and Access Control: In order to ensure that only designated  
individuals (or programs) can execute sensitive commands such as master-key  
loading, each command processor interrogates one or more control-point values  
within the cryptographic engine access-control system for permission to perform the  
request.  
The access-control system includes roles. Each role defines the permissible  
control points for users associated with that role. The access-control system also  
supports user profiles that are referenced by a user ID. Each profile associates the  
user ID with a role, logon verification method and authentication information, and a  
logon session-key. Within a host process, one and only one profile, and thus role,  
can be logged on at a time. In the absence of a logged-on user, a default role  
defines the permitted commands (via the control points in the role) that a process  
can use.  
168  
2
Unless, out of the 2  
possible values, another node randomly generates the same master-key data.  
Chapter 1. Introduction to Programming for the IBM CCA 1-5  
CCA Release 2.54  
The Coprocessor supports multiple logons by different users from different host  
processes. The Coprocessor also supports requests from multiple threads within a  
single host process.  
A user is logged on and off by the Logon_Control verb. During logon, the  
Logon_Control verb establishes a logon session key. This key is held in  
user-process memory space and in the cryptographic engine. All verbs append  
and verify a MAC based on this key on verb control information exchanged with the  
cryptographic engine. Logoff causes the cryptographic engine to destroy its copy of  
the session key and to mark the user profile as not active.  
“CCA Access-Control” on page 2-2 provides a further explanation of the  
access-control system, and 2-52 provides details about the logon verb.  
How Application Programs Obtain Service  
Application programs and utility programs (requestors) obtain services from the  
security product by issuing service requests (verb calls) to the runtime subsystem  
of software and hardware. These requests are in the form of procedure calls that  
must be programmed according to the rules of the language in which the  
application is coded. The services that are available are collectively described as  
the security API. All of the software and hardware accessed through the security  
API should be considered an integrated subsystem.  
When the cryptographic-services access layer receives requests concurrently from  
multiple application programs, it serializes the requests and returns a response for  
each request. There are other multiprocessing implications arising from the  
existence of a common master-key and a common key-storage facility -- these  
topics are covered later in this book.  
The way in which application programs and utilities are linked to the API services  
depends on the computing environment. In the AIX, and Windows 2000 and  
Windows/NT environments, the operating systems dynamically link application  
security API requests to the subsystem DLL code (AIX: shared library; OS/400:  
service program). Your choice of import library controls the use of 16-bit or 32-bit  
entry-point services. In the OS/400 environment, the CCA API is implemented in a  
set of 64-bit entry-point service programs, one for each security API verb. Details  
for linking to the API are covered in the guide book for the individual software  
products. For the AIX, and Windows NT/2000, see the IBM 4758 CCA Support  
Program Installation Manual. Details for linking to the API on the OS/400 platform  
can be found by following the OS/400 link from the CCA support page of the  
product Web site, http://www.ibm.com/security/cryptocards.  
Together, the security API DLL and the environment-dependent request routing  
mechanism act as an agent on behalf of the application and present a request to  
the server. Requests can be issued by one or more programs. Each request is  
processed by the server as a self-contained unit of work. The programming  
interface can be called concurrently by applications running as different processes.  
The API can be used by multiple threads in a process. The API is thread safe.  
In each server environment, a device driver provided by IBM supplies low-level  
control of the hardware and passes the request to the hardware device. Requests  
can require one or more I/O commands from the security server to the device driver  
and hardware.  
1-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The security server and a directory server manage key storage. Applications can  
store locally used cryptographic keys in a key-storage facility. This is especially  
useful for long-life keys. Keys stored in key storage are referenced through the use  
of a key label. Before deciding whether to use the key-storage facility or to let the  
application retain the keys, you must consider system design trade-off factors, such  
as key backup, the impact of master-key changing, the lifetime of a key, and so  
forth.  
Overlapped Processing  
Calls to the CCA API are synchronous; your program loses control until the verb  
completes. Multiple-process threads can make concurrent calls to the API. The  
CCA implementation for IBM OS/2 and for Windows NT and Windows 2000 restrict  
the number of concurrent outstanding calls for a Coprocessor to 32.3  
You can maximize throughput by organizing your application(s) to make multiple,  
overlapping calls to the CCA API. You can also increase throughput by employing  
multiple Coprocessors, each with CCA (see “Multi-Coprocessor Capability” on  
page 2-10). The limit of 32 concurrent CCA calls applies to each Coprocessor,  
and therefore with multiple Coprocessors you can have more than 32 outstanding  
CCA API calls.  
Within the Coprocessor, the CCA software is organized into multiple threads of  
processing. This multi-processing design is intended to enable concurrent use of  
the Coprocessor's main engine, PCI communications, DES and SHA-1 engine, and  
modular-exponentiation engine.  
Host-side Key Caching  
Beginning with Release 2, the CCA implementation provided caching of key records  
obtained from key storage within the CCA host code. However, the host cache is  
unique for each host process. If different host processes access the same key  
record, an update to a key record caused in one process will not affect the contents  
of the key cache held for other process(es). Beginning with Release 2.41, caching  
of key records within the key storage system can be suppressed so that all  
processes will access the most current key records. The techniques used to  
suppress key-record caching are discussed in the IBM 4758 PCI Cryptographic  
Coprocessor CCA Support Program Installation Manual.  
3
The limitation of 32 concurrent API calls does not apply to the implementation for AIX.  
Chapter 1. Introduction to Programming for the IBM CCA 1-7  
CCA Release 2.54  
The Security API, Programming Fundamentals  
You obtain CCA cryptographic services from the PCI Cryptographic Coprocessor  
through procedure calls to the CCA security application programming interface  
(API). Most of the services provided are considered an implementation of the IBM  
Common Cryptographic Architecture (CCA). Most of the extensions that differ from  
other IBM CCA implementations are in the area of the access-control services. If  
your application program will be used with other CCA products, you should  
compare the other-product literature for differences.  
Your application program requests a service through the security API by using a  
procedure call for a verb.4 The procedure call for a verb uses the standard syntax  
of a programming language, including the entry-point name of the verb, the  
parameters of the verb, and the variables for the parameters. Each verb has an  
entry-point name and a fixed-length parameter list. See the first page of each of  
the following chapters to learn what verbs are provided.  
The security API is designed for use with high-level languages, such as C, COBOL  
(OS/400), or RPG (OS/400), and for low-level languages, such as assembler. It is  
also designed to enable you to use the same verb entry-point names and variables  
in the various supported environments. Therefore, application code that you write  
for use in one environment generally can be ported to additional environments with  
minimal change.  
Verbs, Variables, and Parameters  
This section explains how each verb (service) is described in the reference material  
and provides an explanation of the characteristics of the security API.  
Each callable service, or verb, has an entry-point name and a fixed-length  
parameter list. The reference material describes each verb and includes the  
following information for each verb:  
Pseudonym  
Entry-point name  
Supported environment(s)  
Description  
Restrictions  
Format  
Parameters  
Hardware command requirements.  
Pseudonym and Entry-Point Name: Each verb has a pseudonym  
(general-language name) and an entry-point name (computer-language name).  
The entry-point name is used in your program to call the verb. Each verb's  
entry-point name begins with one of the following:  
CSNB  
CSND  
Generally the DES services  
RSA public-key services (PKA96)  
4
The term verb implies an action that an application program can initiate; other systems and publications might use the term  
callable service instead of verb.  
1-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
CSUA  
Cryptographic-node and hardware-control services.  
The last three letters in the entry-point name identify the specific service in a group  
and are often the first letters of the principal words in the verb pseudonym.  
Supported Environments: At the start of each verb description is a table that  
describes which CCA implementations support the verb. For example:  
Platform/  
Product  
OS/2  
X
AIX  
X
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
The table indicates which models of Coprocessor support the verb and which  
operating system platform(s) are supported. An X indicates that the verb is  
supported as described.  
Description: The verb is described in general terms. Be sure to read the  
parameter descriptions as these add additional detail. A Related Information  
section appears at the end of the verb material for a very few verbs.  
Restrictions: Restrictions are as noted.  
Format: The format section in each verb description lists the entry-point name on  
the first line in bold type. This is followed by the list of parameters for the verb.  
Generally the input/output direction in which the variable identified by the parameter  
is passed is listed along with the type of variable (integer or string), and the size,  
number, or other special information about the variable.  
The format section for each verb lists the parameters after the entry-point name in  
the sequence in which they must be coded.  
Parameters: All information that is exchanged between your application program  
and a verb is through the variables that are identified by the parameters in the  
procedure call. These parameters are pointers to the variables contained in  
application program storage that contain information to be exchanged with the verb.  
Each verb has a fixed-length parameter list, and though all parameters are not  
always used by the verb, they must be included in the call. The entry-point name  
and the parameters for each verb are shown in the following format:  
Parameter name  
Direction Data  
Type  
Length of Data  
entry_point_name  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Direction Data  
Type  
Integer  
Integer  
exit_data_length bytes  
length  
parameter_5  
parameter_6  
Direction Data  
Type  
length  
.
.
.
parameter_n  
Direction Data  
Type  
length  
The first four parameters are the same for all of the verbs. For a description of  
these parameters, see “Parameters Common to All Verbs” on page 1-11. The  
remaining parameters (parameter_5, parameter_6, ..., parameter_n) are unique for  
Chapter 1. Introduction to Programming for the IBM CCA 1-9  
CCA Release 2.54  
each verb. For descriptions of these parameters, see the definitions with the  
individual verbs.  
Variable Direction: The parameter descriptions use the following terms to identify  
the flow of information:  
Input  
The application program sends the variable to the verb (to the  
called routine)  
Output  
The verb returns the variable to the application program  
In/Output  
The application program sends the variable to the verb, or the verb  
returns the variable to the application program, or both.  
Variable Type: A variable that is identified by a verb parameter can be a single  
value or a one-dimensional array. If a parameter identifies an array, each data  
element of the array is of the same data type. If the number of elements in the  
array is variable, a preceding parameter identifies a variable that contains the  
actual number of elements in the associated array. Unless otherwise stated, a  
variable is a single value, not an array.  
For each verb, the parameter descriptions use the following terms to describe the  
type of variable:  
Integer A four-byte (32-bit), signed, two's-complement binary number.  
In the AIX and OS/400 environments, integer values are presented in  
four bytes in the sequence high-order to low-order (big endian). In the  
personal computer (Intel) environments, integer values are presented  
in four bytes in the sequence low-order to high-order (little endian).  
String A series of bytes where the sequence of the bytes must be maintained.  
Each byte can take on any bit configuration. The string consists only  
of the data bytes. No string terminators, field-length values, or  
type-casting parameters are included. Individual verbs can restrict the  
byte values within the string to characters or numerics.  
Character data must be encoded in the native character set of the  
computer where the data is used. Exceptions to this rule are noted  
where necessary.  
Array  
An array of values, which can be integers or strings. Only  
one-dimensional arrays are permitted. For information about the  
parameters that use arrays, see “Rule_Array and Other Keyword  
Parameters” on page 1-12.  
Variable Length: This is the length, in bytes, of the variable identified by the  
parameter being described. This length may be expressed as a specific number of  
bytes or it may be expressed in terms of the contents of another variable.  
For example, the length of the exit_data variable is expressed in this manner. The  
length of the exit_data string variable is specified in the exit_data_length variable.  
This length is shown in the parameter tables as “exit_data_length bytes,” The  
rule_array variable, on the other hand, is an array whose elements are eight-byte  
strings. The number of elements in the rule array is specified in the  
rule_array_count variable and its length is shown as “rule_array_count * 8 bytes.”  
Note: Variable lengths (integer, for example) that are implied by the variable data  
type are not shown in these tables.  
1-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Commonly Encountered Parameters  
Some parameters are common to all verbs, other parameters are used with many  
of the verbs. This section describes several groups of these parameters:  
Parameters common to all verbs  
Rule_array and other keyword parameters  
Key_identifiers, key_labels, and key_tokens.  
Parameters Common to All Verbs  
The first four parameters (return_code, reason_code, exit_data_length, and  
exit_data) are the same for all verbs. A parameter is an address pointer to the  
associated variable in application storage.  
entry_point_name  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
return_code  
The return_code parameter is a pointer to an integer value that expresses the  
general results of processing. See “Return Code and Reason Code Overview”  
for more information about return codes  
reason_code  
The reason_code parameter is a pointer to an integer value that expresses the  
specific results of processing. Each possible result is assigned a unique  
reason code value. See “Return Code and Reason Code Overview” for more  
information about reason codes.  
exit_data_length  
The exit_data_length parameter is a pointer to an integer value containing the  
length of the string (in bytes) that is returned by the exit_data value. The  
exit_data_length parameter should point to a value of zero to ensure  
compatibility with any future extension or other operating environment.  
exit_data  
The exit_data parameter is a pointer to a variable-length string that contains  
installation-exit-dependent data that is exchanged with a preprocessing user  
exit or a post-processing user exit.  
Note: The IBM 4758 CCA Support Program does not currently support user  
exits. The exit_data_length and exit_data variables must be declared in the  
parameter list. The exit_data_length parameter should be set to zero to ensure  
compatibility with any future extension or other operating environment.  
Return Code and Reason Code Overview: The return code provides a general  
indication of the results of verb processing and is the value that your application  
program should use in determining the course of further processing. The reason  
code provides more specific information about the outcome of verb processing.  
Note that reason code values generally differ between CCA product  
implementations. Therefore, the reason code values should generally be returned  
to individuals who can understand the implications in the context of your application  
on a specific platform.  
The return codes have these general meanings:  
Chapter 1. Introduction to Programming for the IBM CCA 1-11  
CCA Release 2.54  
Value  
Meaning  
0
Indicates normal completion; a few nonzero reason codes are associated with  
this return code.  
4
8
Indicates the verb processing completed, but without full success. For example,  
this return code can signal that a supplied PIN was found to be invalid.  
Indicates that the verb prematurely stopped processing. Generally the  
application programmer will need to investigate the problem and will need to  
know the associated reason code.  
12  
16  
Indicates that the verb prematurely stopped processing. The reason is most  
likely related to a problem in the setup of the hardware or in the configuration of  
the software.  
Indicates that the verb prematurely stopped processing. A processing error  
occurred in the product. If these errors persist, a repair of the hardware or a  
correction to the product software may be required.  
See Appendix A, “Return Codes and Reason Codes” for a detailed discussion of  
return codes and a complete list of all return and reason codes.  
Rule_Array and Other Keyword Parameters  
Rule_array parameters and some other parameters use keywords to transfer  
information. Generally, a rule array consists of a variable number of data elements  
that contain keywords that direct specific details of the verb process. Almost all  
keywords, in a rule array or otherwise, are eight bytes in length, and should be  
uppercase, left-justified, and padded with space characters. While some  
implementations can fold lowercase characters to uppercase, you should always  
code the keywords in uppercase.  
The number of keywords in a rule array is specified by a rule_array_count variable,  
an integer that defines the number of (eight-byte) elements in the array.  
In some cases, a rule_array is used to convey information other than keywords  
between your application and the server. This is, however, an exception.  
Key Tokens, Key Labels, and Key Identifiers  
Essentially all cryptographic operations employ one or more keys. In CCA, keys  
are retained within a structure called a key token. A verb parameter can point to a  
variable that contains a key token. Generally you do not need to be concerned  
with the details of a key token and can deal with it as an entity. See “Key Tokens”  
on page B-1 for a detailed description of the key-token structures.  
Keys are described as either internal, operational, or external, as follows:  
Internal  
A key that is encrypted for local use. The cryptographic engine will  
decrypt (unwrap) an internal key to use the key in a local operation.  
Once a key is entered into the system it is always encrypted  
(wrapped) if it appears outside of the protected environment of the  
cryptographic engine. The engine has a special key-encrypting key  
designated a master key. This key is held within the engine to wrap  
and unwrap locally used keys.  
Operational An internal key that is complete and ready for use. During entry of a  
key, the internal key-token can have a flag set that indicates the key  
information is incomplete.  
1-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
External  
A key that is either in the clear, or is encrypted (wrapped) by some  
key-encrypting key other than the master key. Generally, when a  
key is to be transported from place to place, or is to be held for a  
significant period of time, it is required to encrypt the key with a  
transport key. A key wrapped by a transport key-encrypting key is  
designated external.  
RSA public-keys are not encrypted values (in PKA96), and when not  
accompanied by private-key information, are retained in an external  
key-token.  
Internal key-tokens can be stored in a file that is maintained by the directory server.  
These key tokens are referenced by use of a key label. A key label is an  
alphanumeric string that you place in a variable and reference with a verb  
parameter.  
Verb descriptions specify how you can provide a key using these terms:  
Key token  
Key label  
The variable must contain a proper key-token structure.  
The variable must contain a key label string used to locate a key  
record in key storage.  
Key identifier The variable must contain either a key token or a key label. The  
first byte in the variable defines if the variable contains a key token  
or a key label. When the first byte is in the range X'20' through  
X'FE', the variable is processed as a key label. There are  
additional restrictions on the value of a key label. See “Key-Label  
Content” on page 7-2. The first byte in all key-token structures is in  
the range of X'01' to X'1F'. X'00' indicates a DES null key-token.  
X'FF' as the first byte of a key-related variable passed to the API  
raises an error condition.  
How the Verbs Are Organized in the Remainder of the Book  
Now that you have a basic understanding of the API, you can find these topics in  
the remainder of the book:  
Chapter 2, “CCA Node-Management and Access-Control” explains how the  
cryptographic engine and the rest of the cryptographic node is administered.  
There are four topics:  
– Access-control administration  
– Controlling the cryptographic facility  
– Multi-Coprocessor support  
– Master-key administration.  
Keeping cryptographic keys private or secret can be accomplished by retaining  
them in secure hardware. Keeping the keys in secure hardware can be  
inconvenient or impossible if there are a large number of keys, or the key has  
to be usable with more than one hardware device. In the CCA implementation,  
a master key is used to encrypt (wrap) locally used keys. The master key itself  
is securely installed within the cryptographic engine and cannot be retrieved as  
an entity from the engine.  
As you examine the verb descriptions throughout this book, you will see  
reference to “Required Commands.” Almost all of the verbs request the  
cryptographic engine (the “adapter” or “Coprocessor”) to perform one or more  
Chapter 1. Introduction to Programming for the IBM CCA 1-13  
CCA Release 2.54  
commands in the performance of the verb. Each of these commands has to be  
authorized for use. Access-control administration concerns managing these  
authorizations.  
Chapter 3, “RSA Key-Management” explains how you can generate and  
protect an RSA key-pair. The chapter also explains how you can control the  
distribution of the RSA private key for backup and archive purposes and to  
enable multiple cryptographic engines to use the key for performance or  
availability considerations. Related services for creating and parsing RSA  
key-tokens are also described.  
When you wish to backup an RSA private key, or supply the key to another  
node, you will use a double-length DES key-encrypting key, a transport key.  
You will find it useful to have a general understanding of the DES  
key-management concepts found in chapter Chapter 5, “DES  
Key-Management.”  
Chapter 4, “Hashing and Digital Signatures” explains how you can:  
– Provide for demonstrations of the integrity of data -- demonstrate that data  
has not been changed  
– Attribute data uniquely to the holder of a private key.  
These problems can be solved through the use of a digital signature. The  
chapter explains how you can hash data (obtain a number that is characteristic  
of the data, a digest) and how you can use this to obtain and validate a digital  
signature.  
Chapter 5, “DES Key-Management” explains the many services that are  
available to manage the generation, installation, and distribution of DES keys.  
An important aspect of DES key-management is the means by which these  
keys can be restricted to selected purposes. Deficiencies in key management  
are the main means by which a cryptographic system can be broken.  
Controlling the use of a key and its distribution is almost as important as  
keeping the key a secret. CCA employs a non-secret quantity, the control  
vector, to determine the use of a key and thus improve the security of a node.  
Control vectors are described in detail in Appendix C, “CCA Control-Vector  
Definitions and Key Encryption.”  
Chapter 6, “Data Confidentiality and Data Integrity” explains how you can  
encrypt data. The chapter also describes how you can use DES to  
demonstrate the integrity of data through the production and verification of  
message authentication codes.  
Chapter 7, “Key-Storage Verbs” explains how you can label, store, retrieve,  
and locate keys in the cryptographic-services access-layer-managed key  
storage.  
Chapter 8, “Financial Services Support Verbs” explains three groups of verbs  
of especial use in finance industry transaction processing:  
– Processing keys and information related to the Secure Electronic  
Transaction (SET) protocol  
– A suite of verbs for processing personal identification numbers (PIN) in  
various phases of automated teller machine and point-of-sale transaction  
processing  
– Verbs to generate and verify credit-card and debit-card validation codes.  
1-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 2. CCA Node-Management and Access-Control  
This chapter discusses:  
The access-control system that you can use to control who can perform various  
sensitive operations at what times  
Controlling the cryptographic facility  
Multi-Coprocessor support  
The CCA master-key, what it is, and how you manage the key  
How you can initialize the cryptographic key-storage that is managed by the  
support software.  
The verbs that you use to accomplish these tasks are listed in Figure 2-1.  
Figure 2-1. CCA Node, Access-Control, and Master-Key Management Verbs  
Verb  
Page  
2-21  
2-24  
2-30  
Service  
Entry  
Point  
Svc  
Lcn  
Access_Control_Initialization  
Access_Control_Maintenance  
Cryptographic_Facility_Control  
Initializes or updates access-control tables in the  
Coprocessor.  
CSUAACI  
CSUAACM  
CSUACFC  
E
E
E
Queries or controls installed roles and user  
profiles.  
Reinitializes the CCA application, sets the  
adapter clock, resets the intrusion latch, sets the  
CCA environment identifier (EID), sets the  
number of master-key shares required and  
possible for distributing the master key, loads  
the CCA function control vector (FCV) that  
manages international export and import  
regulation limitations.  
Cryptographic_Facility_Query  
2-34  
Retrieves information about the Coprocessor  
and the state of master-key-shares distribution  
processing.  
CSUACFQ  
E
Cryptographic_Resource_Allocate  
Cryptographic_Resource_Deallocate  
Key_Storage_Designate  
2-44  
2-46  
2-48  
2-50  
Connects subsequent calls to an alternative  
cryptographic resource (Coprocessor).  
CSUACRA  
CSUACRD  
CSUAKSD  
CSNBKSI  
S
S
Reverts subsequent calls to the default  
cryptographic resource (Coprocessor).  
Specifies the key-storage file used by the  
process.  
S
Key_Storage_Initialization  
Initializes one or the other of the key-storage  
files that can store DES or RSA (public/private)  
keys.  
S/E  
Logon_Control  
2-52  
2-55  
Logs on or off the Cryptographic Coprocessor.  
CSUALCT  
CSUAMKD  
E
E
Master_Key_Distribution  
Supports the distribution and reception of  
master-key shares.  
Master_Key_Process  
2-59  
Enables the introduction of a master key into the  
Coprocessor, the random generation of a  
master key, the setting and clearing of the  
master-key registers.  
CSNBMKP  
E
Random_Number_Tests  
2-64  
Enables tests of the random-number generator  
and performance of the FIPS-mandated  
known-answer tests.  
CSUARNT  
E
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Copyright IBM Corp. 1997, 2005  
2-1  
CCA Release 2.54  
CCA Access-Control  
This section describes these CCA access-control system topics:  
Understanding access control  
Role-based access control  
Initializing and managing the access-control system  
Logging on and logging off  
Protecting your transaction information.  
Understanding Access Control  
Access control is the process that determines which CCA services or “commands”1  
of the IBM 4758 PCI Cryptographic Coprocessor are available to a user at any  
given time. The system administrator can give users differing authority, so that  
some users have the ability to use CCA services that are not available to others.  
In addition, a given user's authority may be limited by parameters such as the time  
of day or the day of the week.  
Also see the discussion of Access Controls in Chapter 6 of the IBM 4758 PCI  
Cryptographic Coprocessor CCA Support Program Installation Manual.  
Role-Based Access Control  
The IBM 4758 CCA implementation uses role-based access control. In a  
role-based system, the administrator defines a set of roles, which correspond to the  
classes of Coprocessor users. Each user is enrolled by defining a user profile,  
which maps the user to one of the available roles. Profiles are described in  
“Understanding Profiles” on page 2-4.  
Note: For purposes of this discussion, a user is defined as either a human user or  
an automated, computerized process.  
As an example, a simple system might have the following three roles:  
General User A user class which includes all Coprocessor users who do not have  
any special privileges  
Key-Management Officer Those people who have the authority to change  
cryptographic keys for the Coprocessor  
Access-Control Administrator Those people who have the authority to enroll new  
users into the Coprocessor environment, and to modify the access rights of  
those users who are already enrolled.  
Normally, only a few users would be associated with the Key-Management Officer  
role, but there generally would be a large population of users associated with  
General User role. The Access-Control Administrator role would likely be limited to  
a single “super user” since he can make any change to the access control settings.  
In some cases, once the system is setup, it is desirable to delete all profiles linked  
to Access-Control Administrator roles to prevent further changes to the access  
controls.  
1
At the end of each CCA verb description you will find a list of commands that must be enabled to use specific capabilities of the  
CCA verb.  
2-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
A role-based system is more efficient than one in which the authority is assigned  
individually for each user. In general, users can be segregated into just a few  
different categories of access rights. The use of roles allows the administrator to  
define each of these categories just once, in the form of a role.  
Understanding Roles  
Each role defines the permissions and other characteristics associated with users  
having that role. The role contains the following information:  
Role ID A character string which defines the name of the role. This name is  
referenced in user profiles, to show which role defines the user's authority.  
Required User-Authentication Strength Level The access-control system is  
designed to allow a variety of user authentication mechanisms. Although the  
only one supported today is passphrase authentication, the design is ready for  
others that may be used in the future.  
All user-authentication mechanisms are given a strength rating, namely an  
integer value where zero is the minimum strength corresponding to no  
authentication at all. If the strength of the user's authentication mechanism is  
less than the required strength for the role, the user is not permitted to log on.  
Valid Time and Valid Days-of-Week These values define the times of the day and  
the days of the week when the users with this role are permitted to log on. If  
the current time is outside the values defined for the role, logon is not allowed.  
It is possible to choose values that let users log on at any time on any day of  
the week.  
Notes:  
1. Times are specified in Greenwich Mean Time (GMT).  
2. If you physically move a Coprocessor between time zones, remember that  
you must resynchronize the CCA-managed clock with the host-system  
clock.  
Permitted Commands A list defining which commands the user is allowed to  
perform in the Coprocessor. Each command corresponds to one of the  
primitive functions which collectively comprise the CCA implementation.  
Comment A 20-byte comment can be incorporated into the role for future  
reference.  
In addition, the role contains control and error-checking fields. The detailed layout  
of the role data-structure can be found in “Role Structure” on page B-29.  
The Default Role: Every CCA Coprocessor must have at least one role, called  
the default role. Any user who has not logged on and been authenticated will  
operate with the capabilities and restrictions defined in the default role.  
Note: Since unauthenticated users have authentication strength equal to zero, the  
Required User-Authentication Strength Level of the Default Role must also be zero.  
The Coprocessor can have a variable number of additional roles, as needed and  
defined by the customer. For simple applications, the default role by itself may be  
sufficient. Any number of roles can be defined, as long as the Coprocessor has  
enough available storage to hold them.  
Chapter 2. CCA Node-Management and Access-Control 2-3  
CCA Release 2.54  
Understanding Profiles  
Any user who needs to be authenticated to the Coprocessor must have a user  
profile. Users who only need the capabilities defined in the default role do not need  
a profile.  
A user profile defines a specific user to the CCA implementation. Each profile  
contains the following information:  
User ID This is the “name” used to identify the user to the Coprocessor. The User  
ID is an eight-byte value, with no restrictions on its content. Although it will  
typically be an unterminated ASCII (or EBCDIC on OS/400) character string,  
any 64-bit string is acceptable.2  
Comment A 20-byte comment can be incorporated into the profile for future  
reference.  
Logon Failure Count This field contains a count of the number of consecutive  
times the user has failed a logon attempt, due to incorrect authentication data.  
The count is reset each time the user has a successful logon. The user is no  
longer allowed to log on after three consecutive failures. This lockout  
condition can be reset by an administrator whose role has sufficient authority.  
Role ID This character string identifies the role that contains the user's  
authorization information. The authority defined in the role takes effect after  
the user successfully logs on to the Coprocessor.  
Activation and Expiration Dates These values define the first and last dates on  
which this user is permitted to log on to the Coprocessor. An administrator  
whose role has the necessary authority can reset these fields to extend the  
user's access period.  
Authentication Data Authentication data is the information used to verify the  
identity of the user. It is a self-defining structure, which can accommodate  
many different authentication mechanisms. In the current CCA  
implementation, user identification is accomplished by means of a passphrase  
supplied to the Logon_Control verb.  
The profile's authentication-data field can hold data for more than one  
authentication mechanism. If more than one is present in a user's profile, any  
of the mechanisms can be used to log on. Different mechanisms, however,  
may have different strengths.  
The structure of the authentication data is described in “Authentication Data  
Structure” on page B-33.  
In addition, the profile contains other control and error-checking fields. The detailed  
layout of the profile data-structure can be found in “Profile Structure” on page B-32.  
Profile(s) are stored in non-volatile memory inside the secure module on the  
Coprocessor. When a user logs on, his stored profile is used to authenticate the  
information presented to the Coprocessor. In most applications, the majority of the  
users will operate under the default role, and will not have user profiles. Only the  
security officers and other special users will need profiles.  
2
In many cases, a utility program will be used to enter the user ID. That utility may restrict the ID to a specific character set.  
2-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Initializing and Managing the Access-Control System  
Before you can use a Coprocessor with newly loaded or initialized CCA support  
you should initialize roles, profiles, and other data. You may also need to update  
some of these values from time to time. Access-control initialization and  
management are the processes you will use to accomplish this.  
You can initialize and manage the access-control system in either of two ways:  
You can use the IBM-supplied utility program for your platform:  
– Cryptographic Node Management utility program3 (“CNM”) (not for OS/400)  
– OS/400 Cryptographic Coprocessor web-based configuration utility.  
You can write programs that use the access-control verbs described in this  
chapter.  
The verbs allow you to write programs that do more than the utility program  
included with the CCA Support Program. If your needs are simple, however, the  
utility program may do everything you need.  
Access-Control Management and Initialization Verbs  
Two verbs provide all of the access-control management and initialization functions:  
CSUAACI  
Perform access-control initialization functions  
Perform access-control management functions.  
CSUAACM  
With Access_Control_Initialization, you can perform functions such as:  
Loading roles and user profiles  
Changing the expiration date for a user profile  
Changing the authentication data in a user profile  
Resetting the authentication failure-count in a user profile.  
With Access_Control_Maintenance, you can perform functions such as:  
Getting a list of the installed roles or user profiles  
Retrieving the non-secret data for a selected role or user profile  
Deleting a selected role or user profile from the Coprocessor  
Get a list of the users who are logged on to the Coprocessor.  
These two verbs are fully described on pages 2-21 and 2-24, respectively. See  
also “Access-Control Data Structures” on page B-28.  
Permitting Changes to the Configuration  
It is possible to setup the Coprocessor so no one is authorized to perform any  
functions, including further initialization. It is also possible to setup the Coprocessor  
where operational commands are available, but not initialization commands,  
meaning you could never change the configuration of the Coprocessor. This  
happens if you setup the Coprocessor with no roles having the authority to perform  
initialization functions.  
3
The Cryptographic Node Management utility is described in the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program  
Installation Manual.  
Chapter 2. CCA Node-Management and Access-Control 2-5  
CCA Release 2.54  
Take care to ensure that you define roles that have the authority to perform  
initialization, including the RQ-TOKEN and RQ-REINT options of the  
Cryptographic_Facility_Control (CSUACFC) verb. You must also ensure there are  
active profiles that use these roles.  
If you configure your Coprocessor so that initialization is not allowed, you can  
recover by reloading4 the Coprocessor CCA software. This will delete all  
information previously loaded, and restore the Coprocessor's CCA function to its  
initial state.  
Configuration and Greenwich Mean Time (GMT)  
CCA always operates with GMT time. This means that the time, date, and  
day-of-the-week values in the Coprocessor are measured according to GMT. This  
can be confusing because of its effect on access-control checking.  
All users have operating time limits, based on values in their roles and profiles.  
These include:  
Profile activation and expiration dates  
Time-of-day limits  
Day-of-the-week limits.  
All of these limits are measured using time in the Coprocessor's frame of reference,  
not the user's. If your role says that you are authorized to use the Coprocessor on  
days Monday through Friday, it means Monday through Friday in the GMT time  
zone, not your local time zone. In like manner, if your profile expiration date is  
December 31, it means December 31 in GMT.  
In the Eastern United States, your time differs from GMT by four hours during the  
part of the year Daylight Savings Time is in effect. At noon local time, it is 4:00 PM  
GMT. At 8:00 PM local time, it is midnight GMT, which is the time the Coprocessor  
increments its date and day-of-the-week to the next day.  
For example, at 7:00 PM on Tuesday, December 30 local time, it is 11:00 PM,  
Tuesday, December 30 to the Coprocessor. Two hours later, however, at 9:00 PM,  
Tuesday, December 30 local time, it is 1:00 AM Wednesday, December 31 to the  
Coprocessor. If your role only allows you to use the Coprocessor on Tuesday, you  
would have access until 8:00 PM on Tuesday. After that, it would be Wednesday  
in the GMT time frame used by the Coprocessor.  
This happens because the Coprocessor does not know where you are located, and  
how much your time differs from GMT. Time zone information could be obtained  
from your local workstation, but this information could not be trusted by the  
Coprocessor; it could be forged in order to obtain access at times the system  
administrator intended to keep you from using the Coprocessor.  
4
Use file CNWxxxyy.CLU. See Chapter 4 of the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation  
Manual.  
2-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Notes:  
1. During the portions of the year when Daylight Savings Time is not in effect, the  
time difference between Eastern Standard Time and GMT is 5 hours.  
2. In the OS/400 environment, no translation is provided for Role and Profile  
names. The Coprocessor will initialize the default role name to DEFAULT  
encoded in ASCII. OS/400 CCA users will need to consider the encoding of  
Role and Profile names.  
Logging On and Logging Off  
A user must log on to the Coprocessor in order to activate a user profile and the  
associated role. This is the only way to use a role other than the default role. You  
log on and log off using the Logon_Control verb, which is described on page 2-52.  
When you successfully log on, the CCA implementation establishes a session  
between your application program and the Coprocessor's access-control system.  
The Security Application Program Interface (SAPI) code stores the logon context  
information, which contains the session information needed by the host computer to  
protect and validate transactions sent to the Coprocessor. As part of that session,  
a randomly derived session key, generated in the Coprocessor, is subsequently  
used to protect information you interchange with the Coprocessor. This protection  
is described in “Protecting Your Transaction Information” on page 2-9. The logon  
process and its algorithms are described in “Passphrase Verification Protocol” on  
page D-16.  
On OS/2, AIX, and NT, the logon context information resides in memory associated  
with the process thread which performed the Logon_Control verb. On OS/400, the  
logon context information resides in memory owned by the process in which the  
application runs. Host-side logon context information can be saved and shared  
with other threads, processes, or programs; see “Use of Logon Context Information”  
on page 2-8.  
Thus, on OS/2, AIX, and NT, each thread in any process can log on to the CCA  
access control system within a specific CCA Coprocessor. Because the  
Coprocessor code creates the session key, and the session key is stored in the  
active context information, a thread cannot concurrently be logged on to more that  
one Coprocessor.  
In order to log on, you must prove the user's identity to the Coprocessor. This is  
accomplished using a passphrase, a string of up to 64 characters which are known  
only to you and the Coprocessor. A good passphrase should not be too short, and  
it should contain a mixture of alphabetic characters, numeric characters, and  
special symbols such as “*,” “+,” “!,” and others. It should not be comprised of  
familiar words or other information which someone might be able to guess.  
When you log on, no part of the passphrase ever travels over any interface to the  
Coprocessor. The passphrase is hashed and processed into a key that encrypts  
information passed to the Coprocessor. The Coprocessor has a copy of the hash  
and can construct the same key to recover and validate the log-on information.  
CCA does not communicate your passphrase outside of the memory owned by the  
calling process.  
When you have finished your work with the Coprocessor, you must log off in order  
to end your session. This invalidates the session key you established when you  
Chapter 2. CCA Node-Management and Access-Control 2-7  
CCA Release 2.54  
logged on, and frees resources you were using in the host system and in the  
Coprocessor.  
Use of Logon Context Information  
The Logon_Control verb offers the capability to save and restore logon context  
information through the GET-CNTX and PUT-CNTX rule-array keywords.  
The GET-CNTX keyword is used to retrieve a copy of your active logon context  
information, which you can then store for subsequent use. The PUT-CNTX  
keyword is used to make active previously stored context information. Note that  
the Coprocessor is unaware of what thread, program, or process has initiated a  
request. The host CCA code supplies session information from the active context  
information in each request to the Coprocessor. The Coprocessor attempts to  
match this information with information it has retained for its active sessions.  
Unmatched session information will cause the Coprocessor to reject the associated  
request.  
As an example, consider a simple application which contains two programs,  
LOGON and ENCRYPT:  
The program LOGON logs you on to the Coprocessor using your passphrase.  
The program ENCRYPT encrypts some data. The roles defined for your  
system require you to be logged on in order to use the ENCIPHER function.  
These two programs must use the GET-CNTX and PUT-CNTX keywords in order  
to work properly. They should work as follows:  
LOGON  
1. Log the user on to the Coprocessor using CSUALCT verb with the  
PPHRASE keyword.  
2. Retrieve the logon context information using CSUALCT with the  
GET-CNTX keyword.  
3. Save the logon context information in a place that will be available  
to the ENCIPHER program. This could be as simple as a disk file,  
or it could be something more complicated such as shared memory  
or a background process.  
ENCRYPT  
1. Retrieve the logon context information saved by the LOGON  
program.  
2. Restore the logon context information to the CCA API code using  
the CSUALCT verb with the PUT-CNTX keyword.  
3. Encipher the data.  
Note: You should take care in storing the logon context information. Design your  
software so that the saved context is protected from disclosure to others who may  
be using the same computer. If someone is able to obtain your logon context  
information, they may be able to impersonate you for the duration of your logon  
session.  
2-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Protecting Your Transaction Information  
When you are logged on to the Coprocessor, the information transmitted to and  
from the CCA Coprocessor application is cryptographically protected using your  
session key. A message authentication code is used to ensure that the data was  
not altered during transmission. Since this code is calculated using your session  
key, it also verifies that you are the originator of the request, not someone else  
attempting to impersonate you.  
For some verbs, it is also important to keep the information secret. This is  
especially important with the Access_Control_Initialization verb, which is used to  
send new role and profile data to the Coprocessor. To ensure secrecy, some verbs  
offer a special protected option, which causes the data to be encrypted using your  
session key. This prevents disclosure of the critical data, even if the message is  
intercepted during transmission to the Coprocessor.  
Controlling the Cryptographic Facility  
There are six verbs that you can call to manage aspects of the CCA Coprocessor.  
One of these, the Key_Storage_Designate verb, is unique to the OS/400  
implementation and allows you to select among key-storage files.  
The Cryptographic_Facility_Query verb enables you to obtain the status of the CCA  
node. You specify one of several status categories, and the verb returns that  
category of status. Status information you can obtain includes:  
The condition of the master-key registers: clear, full, and so forth. Note that the  
extended CCA status returns information about both the symmetric and the  
asymmetric master-key-register sets.  
The role name in effect for your processing thread.  
Information about the Coprocessor hardware including the unique eight-byte  
serial number. This serial number is also printed on the label on the  
Coprocessor's mounting bracket.  
The state of the Coprocessor's battery: OK or change the battery soon.  
Various tamper indications. Note that this information is also returned in  
X'8040xxxx' status messages, for example, when you use the Coprocessor  
Load Utility.  
Time and date from the Coprocessor's internal clock.  
The Environment Id (EID), which is a 16-byte identifier used in the PKA92 key  
encryption scheme and in master-key cloning. You assign an EID to represent  
the Cryptographic Coprocessor.  
Diagnostic information that could be of value to product development in the  
event of malfunction.  
The Cryptographic_Facility_Control verb enables you to:  
Reinitialize (“zeroize”) the CCA node. This is a two-step process that requires  
your application to compute an intermediate value as insurance against any  
inadvertent reinitialize action.  
Set parameters into the CCA node, other than those related to the  
access-control system, including: the date and time, the function control vector  
Chapter 2. CCA Node-Management and Access-Control 2-9  
CCA Release 2.54  
used to establish the maximum strength of certain cryptographic functions, the  
environment identifier, and the maximum number of master-key-cloning shares,  
and the minimum number of shares needed to reconstitute a master key.  
Reset the intrusion latch. The intrusion latch circuit can be set by breaking an  
external circuit connected to jack 6 (J6) on the Coprocessor. Normally the pins  
of J6 are connected to each other with a jumper; see the IBM 4758 PCI  
Cryptographic Coprocessor CCA Support Program Installation Manual, Chapter  
2. In your installation you might connect an external circuit to J6 that opens if  
covers on your host machine are opened. Note that setting the intrusion latch  
does not cause zeroization of the Coprocessor. If the intrusion latch is set,  
exception status is reported on most verb calls.  
Reset the battery-low indicator (latch). The Coprocessor electronics sets the  
battery-low indicator when the reserve power in the battery falls below a  
predetermined level. You acknowledge and reset the battery-low condition  
using the RESETBAT rule-array keyword. Of course if the battery has not  
been replaced, you should expect the low-battery-power condition to return.  
The Key_Storage_Initialization verb is used to establish a fresh symmetric or  
asymmetric (DES or PKA) key-storage data set. The data file that holds the key  
records is initialized with header records that contain a verification pattern for the  
master key. Any existing key records in the key storage are lost. The index file is  
also initialized. The file names and paths for the key storage and its index file are  
obtained from different sources depending on the operating system:  
The AIX ODM registry  
The Windows registry.  
See the CCA Support Program Installation Manual for information.  
The Cryptographic_Resource_Allocate and Cryptographic_Resource_Deallocate  
verbs allow your application to steer requests to one of multiple CCA Coprocessors.  
See the “Multi-Coprocessor Capability” for further information.  
Multi-Coprocessor Capability  
Multi-Coprocessor support operates with up to eight Coprocessors installed in a  
single machine, some or all of which are loaded with the CCA application. When  
more than one Coprocessor with CCA is installed, an application program can  
explicitly select which cryptographic resource (Coprocessor) to use, or it can  
optionally accept the default Coprocessor. To explicitly select a Coprocessor, use  
the Cryptographic_Resource_Allocate verb. This verb allocates a Coprocessor  
loaded with the CCA software. Once allocated, CCA requests are routed to it until  
it is deallocated. To deallocate a currently allocated Coprocessor, use the  
Cryptographic_Resource_Deallocate verb. When a Coprocessor is not allocated  
(either before an allocation occurs or after the cryptographic resource is  
deallocated), requests are routed to the default CCA Coprocessor.  
Except for the OS/400 environment, a multi-threaded application program can use  
all of the installed CCA Coprocessors simultaneously. A program thread can use  
only one of the installed CCA Coprocessors at any given time, but it can switch to a  
different installed CCA Coprocessor as needed. To perform the switch, a program  
thread must deallocate a currently allocated cryptographic resource, if any, then it  
must allocate the desired cryptographic resource. The  
2-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Resource_Allocate verb will fail if a cryptographic resource is  
already allocated.  
To determine the number of CCA Coprocessors installed in a machine, use the  
Cryptographic_Facility_Query verb with the STATCARD rule-array keyword. The  
verb returns the number of Coprocessors running CCA software. The count  
includes any Coprocessors loaded with CCA UDX code.  
When using multiple CCA Coprocessors, you must consider the implications of the  
master keys in each of the Coprocessors. See “Master-Key Considerations with  
Multiple CCA Coprocessors” on page 2-17. You must also consider the  
implications of a logged-on session. See “Logging On and Logging Off” on  
page 2-7.  
When you log on to a Coprocessor, the Coprocessor creates a session key and  
communicates this to the CCA host code which saves the key in a “session  
context” memory area. If your processing alternates between Coprocessors, be  
sure to save and restore the appropriate session context information.  
Multi-Coprocessor CCA Host Implementation  
The implementation in OS/400 host systems varies somewhat from that in the other  
environments. The following sections describe each approach:  
OS/400 multi-coprocessor implementation  
AIX and Windows multi-coprocessor implementation.  
OS/400 Multi-Coprocessor Support  
With OS/400, the kernel-level code detects all new Coprocessors at IPL time and  
assigns them a resource name in the form of CRP01, CRP02, and so forth. In  
order to use a Coprocessor, a user must create a cryptographic device description  
object. When creating the device description object, the user specifies the  
cryptographic resource name. The name of the device description object itself is  
completely arbitrary. A user can call the object “BANK1,” “CRYPTO,” “CRP01,”  
or whatever. The device-description-object name has no bearing on which  
resource it names. A user could create a device-description-object named CRP01  
that internally names the CRP03 resource. (Unless you are intentionally renaming  
a resource, such a practice would likely lead to confusion.) With the  
Cryptographic_Resource_Allocate and Cryptographic_Resource_Deallocate verbs,  
you specify a device-description-object name (and not an OS/400 resource name).  
If no device has been allocated, the CCA code will default to use of the object  
named “CRP01,” if any. If no such object exists, the verb will terminate abnormally.  
Note: The scope of the Cryptographic_Resource_Allocate and the  
Cryptographic_Resource_Deallocate verbs is operating-system dependent. For  
OS/400, these verbs are scoped to a process.  
AIX, Windows and OS/2 Multi-Coprocessor Support  
With the first call to CCA from a process, the CCA host code associates  
Coprocessor designators CRP01 through CRP08 with specific Coprocessors. The  
host code determines the total number of Coprocessors installed through a call to  
Chapter 2. CCA Node-Management and Access-Control 2-11  
CCA Release 2.54  
the Coprocessor device driver.5 The host code then polls each Coprocessor in turn  
to determine which ones contain the CCA application. As each Coprocessor is  
evaluated, the CCA host code associates the identifiers CRP01, CRP02, and so  
forth to the Coprocessors with CCA.6  
In the absence of a specific Coprocessor allocation, the host code employs the  
device designated CRP01 by default. You can alter the default designation by  
explicitly setting the CSU_DEFAULT_ADAPTER environment variable. The  
selection of a default device occurs with the first CCA call to a Coprocessor. Once  
selected, the default remains constant throughout the life of the thread. Changing  
the value of the environment variable after a thread uses a Coprocessor does not  
affect the assignment of the default CCA Coprocessor.  
If a thread with an allocated Coprocessor terminates without first deallocating the  
Coprocessor, excess memory consumption will result. It is not necessary to  
deallocate a cryptographic resource if the process itself is terminating; it is only  
suggested if individual threads terminate while the process continues to run.  
Note: The scope of the Cryptographic_Resource_Allocate and the  
Cryptographic_Resource_Deallocate verbs is operating-system dependent. For the  
AIX and Windows implementations, these verbs are scoped to a thread. "Scoped  
to a thread" means that each of several threads within a process can allocate a  
specific Coprocessor.  
Understanding and Managing Master Keys  
In a CCA node, the master key is used to encrypt (wrap) working keys used by the  
node that can appear outside of the cryptographic engine. The working keys are  
triple encrypted. This method of securing keys enables a node to operate on an  
essentially unlimited number of working keys without concern for storage space  
within the confines of the secured cryptographic engine.  
The CCA design supports three master-key registers: new, current, and old. While  
a master key is being assembled, it is accumulated in the new master-key register.  
Then the Master_Key_Process verb is used to transfer (set) the contents of the  
new master-key register to the current master-key register.  
Working keys are normally encrypted by the current master-key. To facilitate  
continuous operations, CCA implementations also have an old master-key register.  
When a new master-key is transferred to the current master-key register, the  
preexisting contents (if any) of the current master-key register are transferred to the  
old master-key register. With the IBM 4758 CCA implementation, whenever a  
working key must be decrypted by the master key, master-key verification pattern  
information that is included in the key token is used to determine if the current or  
the old master-key must be used to recover the working key. Special status (return  
code 0, reason code 10001) is returned in case of use of the old master-key so that  
your application programs can arrange to have the working key updated to  
encryption by the current master-key (using the Key_Token_Change and  
5
6
The device driver designates the Coprocessors using numbers 0, 1, ..., 7. The number assignment is based on the design of the  
BIOS in a machine. BIOS routines “walk the bus” to determine the type of device in each PCI slot. Adding, removing, or  
relocating Coprocessors can alter the number associated with a specific Coprocessor.  
Coprocessors loaded with a UDX extension to CCA will also be assigned a CRP0x identifier.  
2-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Token_Change verbs). Whenever a working key is encrypted for local  
use, it is encrypted using the current master-key.  
Symmetric and Asymmetric Master-Keys  
The CCA Version 2 implementation incorporates a second set of master-key  
registers. One register set is used to encrypt DES (symmetric) working-keys. The  
second register set is used to encrypt PKA (asymmetric) private working-keys. The  
verbs that operate on the master keys permit you to specify a register set (with  
keywords SYM-MK and ASYM-MK). If your applications that modify the  
master-key registers never explicitly select a register set, the master keys in the  
two register sets are modified in the same way and will contain the same keys.  
However, if at any time you modify only one of the register sets, your applications  
will thereafter need to manage the two register sets independently.  
The Cryptographic Node Management (CNM) utility does not contain logic to select  
a specific register set, and therefore use of CNM results in operation as though  
there were only a single set of registers. Note that if you use another program to  
modify a register in only one of the register sets, the CNM utility will no longer be  
usable for updating the master keys.  
For consistency with the S/390 CCA implementation, you can use a symmetric-key  
master-key that has an effective double-length (usually master keys are triple  
length). To accomplish this, use the same key value for the first and third 8-byte  
portion of the key.  
Establishing Master Keys  
Master keys are established in one of three ways:  
1. From clear key parts (components)  
2. Through random generation internal to the Coprocessor  
3. Cloning (copying encrypted shares).  
Establishing a master key from clear information. Individual “key-parts”  
(components) are supplied as clear information and the parts are  
exclusive-ORed within the cryptographic engine. Knowledge of a single part  
gives no information about the final key when multiple (random-valued) parts are  
exclusive-ORed.  
A common technique is to record the values of the parts (typically on paper or  
diskette) and independently store these values in locked safes. When the  
master key is to be instantiated in a cryptographic engine, individuals who are  
trusted to not share the key-part information retrieve the parts and enter the  
information into the cryptographic engine. The Master_Key_Process verb  
supports this operation.  
Entering the first and subsequent parts is authorized by two different control  
points so that a cryptographic engine (the Coprocessor) can enforce that two  
different roles, and thus profiles, are activated to install the master-key parts. Of  
course this requires that roles exist that enforce this separation of responsibility.  
Setting of the master key is also a unique command with its own control point.  
Therefore you can set up the access-control system to require the participation  
of at least three individuals or three groups of individuals.  
You can check the contents of any of the master-key registers, and the key parts  
as they are entered into the new master-key register, using the Key_Test verb.  
Chapter 2. CCA Node-Management and Access-Control 2-13  
CCA Release 2.54  
The verb performs a one-way function on the key-of-interest, the result of which  
is either returned or compared to a known correct result.  
Establishing a master key from an internally generated random value. The  
Master_Key_Process verb can be used to randomly generate a new master-key  
within the cryptographic engine. The value of the new master-key is not  
available outside of the cryptographic engine.  
This method, which is a separately authorized command invoked through use of  
the Master_Key_Process verb, ensures that no one has access to the value of  
the master key. Random generation of a master key is useful when the shares  
technique described next is used, and when keys shared with other nodes are  
distributed using public key techniques or when DES transport keys are  
established between nodes. In these cases, there is no need to re-establish a  
master key with the same value.  
“Cloning” a master key from one cryptographic engine to another  
cryptographic engine. In certain high-security applications, it is desirable to  
copy a master key from one cryptographic engine to another without exposing  
the value of the master key. The IBM 4758 CCA implementation supports  
cloning the master key through a process of splitting the master key into n  
shares, of which m shares, 1mn15, are required to reconstitute the master  
key in another engine. The term “cloning” is used to differentiate the process  
from “copying” because no one share, or any combination of fewer than m  
shares, provide sufficient information needed to reconstitute the master key.  
This secure master-key cloning process is supported by the Cryptographic Node  
Management (CNM) utility. See Chapter 5 and Appendix F of the IBM 4758 PCI  
Cryptographic Coprocessor CCA Support Program Installation Manual. That  
utility can hold the certificates and shares in a “data base” that you can transport  
on diskette between the various nodes:  
The certifying node public-key certificate  
The Coprocessor (master key) Share-Source node public-key certificate  
The Coprocessor (master key) Share-Receiving node public-key certificate  
The master-key shares.  
You establish the 'm' and 'n' values through the use of the  
Cryptographic_Facility_Control verb.  
Shares of the current master-key are obtained using the Obtain mode of the  
Master_Key_Distribution verb. The Receive mode of the  
Master_Key_Distribution verb is used to enter an individual share into the  
receiving (target) cryptographic-engine. When sufficient shares have been  
entered, the verb returns status (return code 4, reason code 1024) that indicates  
the cloned master-key is now complete within the new master-key register of the  
target cryptographic-engine.  
The master-key shares are signed by the source engine. Each signed share is  
then triple-encrypted by a fresh triple-length DES key, the share-encrypting key.  
A certified public-key from the target cryptographic-engine is validated, and the  
share-encrypting key is wrapped (encrypted) using the public key from the  
certificate.  
At the target cryptographic-engine, an encrypted share and the wrapped  
share-encrypting key are presented to the engine. The private key to unwrap  
the share-encrypting key must exist within the cryptographic engine as a  
“retained key” (a private key that never leaves the engine). This private key  
2-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
must also have been marked as suitable for operation with the  
Master_Key_Distribution verb when it was generated.  
When receiving a share, you must also supply the share-signing key in a  
certificate to the Master_Key_Distribution verb. The engine validates the  
certificate, and uses the validated public key to validate the individual master-key  
share.  
The certificates used to validate the share-signing public key and the  
target-engine public key used to wrap the share-encrypting key are validated by  
the cryptographic engines using a retained public-key. A retained public-key is  
introduced into a cryptographic engine in a two-part process using the  
PKA_Public_Key_Hash_Register and PKA_Public_Key_Register verbs. This  
allows you to establish two distinct roles to enforce dual control. Two different  
individuals are authorized so that split authority and dual control can be enforced  
in setting up the certificate validating public key.  
You identify the nodes with unique 16-byte identifiers of your choice. The  
environment ID (EID) is also established through the use of the  
Cryptographic_Facility_Control verb.  
The processing of a given share (share 1, 2, ..., n) requires authorization to a  
distinct control point so that you can enforce split responsibility in obtaining and  
installing the shares.  
The certifying node can be either the share source or target node as you desire,  
or can be an independent node that might be located in a cryptographic control  
center.  
Although not currently supported by IBM products, the shares could be stored on  
intermediate devices (for example, smart cards), provided that the devices could  
perform the required key-management and digital-signature functions.  
With the current capabilities of the IBM 4758 CCA Support Program, you must  
initialize the target Coprocessor with its retained private key and have the  
associated public-key certified before you obtain shares for the target  
Coprocessor. This implies that the target Coprocessor has been initialized and  
is not reset before a master key is cloned to the Coprocessor.  
Chapter 2. CCA Node-Management and Access-Control 2-15  
CCA Release 2.54  
┌──────────────────────────────────┐  
│Share─Administration Control Point│  
3. │  
│ CERT{SA}(SA) H(CERT{SA}(SA))  
│ ───────┬──── ───┬───────────  
└─────────│─────────│──────────────┘  
┌────────────────────────┐  
│CCA Cryptographic Engine│  
┌────────────────────────┐  
│CCA Cryptographic Engine│  
│(Primary = 'a')  
│('b')  
1 ──── Roles, Profiles,  
│ Roles, Profiles,────ꢁ 1  
m_of_n, EID│  
│ m_of_n, EID  
2 ────ꢁ Audit  
Audit ──── 2  
4 ──────────────────────────┴─────────────────────ꢁ 4  
5 ────────────────┴───────────────────────────────ꢁ 5  
Certify by SA  
││  
││  
│ Gererate CSS  
6 ─────────ꢁPu{CSS}─┘  
│ ─CERT{SA}(Pu{CSS}) ┘│  
└─Pu{CSR_i} ──────── 7 Generate CSR  
└ꢁCERT{SA}(Pu{CSR_i})─ꢁ│  
8 ─────┼────────────────────────────────────┘  
──────┼─ꢁPu{CSR_i}(SE_j),  
eᑍSE_j(j,mks_j,SIG{CSS}(j,mks_j))─────ꢁ 9  
(m times)  
└──────────────────────────────────────────ꢁ  
Set and Verify ────ꢁ 1ꢃ  
the master key ────  
└────────────────────────┘  
└────────────────────────┘  
Figure 2-2. Coprocessor-to-Coprocessor Master-Key Cloning  
Figure 2-2 depicts the steps of a master-key cloning scenario. These steps  
include:  
1. Install appropriate access-control roles and profiles, m-of-n, and EID values.  
Have operators change their profile passwords. Ensure that the roles provide  
the degree of responsibility-separation that you require.  
2. Audit the setup of the Share Administration, Share Source, and Share  
Receiving nodes.  
3. Generate a retained RSA private key, the Share-Administration (SA) key. This  
key is used to certify the public keys used in the scheme. Self-certify the SA  
key. Distribute the hash of this certificate to the source and share-receiving  
node(s) under dual control.  
4. Install (register) the hash of the SA public-key in both the source and receiving  
nodes.  
5. Install (register) the SA public-key in both the source and receiving nodes. Two  
different roles can be used to permit this and the prior step to aid in ensuring  
dual control of the cloning process.  
6. In the source node, generate a retained key usable for master-key  
administration, the Coprocessor Share Signing (CSS) key, and have this key  
certified by the SA key.  
2-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
7. In the target node, generate a retained key usable for master-key  
administration, the Coprocessor Share Receiving (CSR) key, and have this key  
certified by the SA key.  
8. Once a master key has been established in the source node, perhaps through  
random master-key generation, obtain shares of the master key. Also obtain  
master-key verification information for use in step 10 using the Key_Test verb.  
Note that generally fewer shares are required to reconstitute the master key  
than that which can be obtained from the source node. Thus corruption of  
some of the information that is in transit between source and target can be  
tolerated.  
9. Deliver and install the master-key shares.  
10. Verify that the new master-key in the target node has the proper value. Then  
set the master key.  
Master-Key Considerations with Multiple CCA Coprocessors  
Master keys are used to wrap (encrypt) working keys (as opposed to clear keys or  
keys wrapped by key-encrypting keys or RSA keys). Master-key-wrapped keys are  
either stored in the CCA key storage, or are held and managed by your  
application(s). When multiple Coprocessors are installed, it is a responsibility of the  
using organization(s) to ensure that appropriate current and old master-keys, both  
symmetric and asymmetric, are installed in the multiple Coprocessors. The most  
straightforward approach is to ensure that when you change (“set”) master keys on  
one CCA Coprocessor, you also change the master keys (both asymmetric and  
symmetric) on the other Coprocessor(s).  
The approach to multiple Coprocessors differs in detail between OS/400 and the  
workstation environments. Each type of environment is discussed:  
OS/400  
AIX and Windows.  
OS/400 Multi-Coprocessor Master-Key Support: IBM recommends loading all  
CCA Coprocessors with the same current and the same old master-keys, especially  
if your applications perform load balancing among the Coprocessors or if the  
Coprocessors will be used for SSL.  
With OS/400, multiple key-storage files can exist. To avoid confusion, keep all  
keys in the key-storage files encrypted by a common, current master-key. The  
master-key verification pattern is not stored in the header record of any key-storage  
file. Therefore, it is important that when you change the master key, you  
re-encipher all of the keys in all of your key-storage files. The organization that  
manages all users of the Coprocessors must arrange procedures for keeping all  
key-storage files up to date with the applicable current master-key. Note that the  
person changing the master key may not have authorization to (or knowledge of) all  
key-storage files on the system.  
The order of loading and setting of the master key between Coprocessors is not  
significant. However, be sure that after all Coprocessor master-keys have been  
updated that you then update all key-storage files. Remember that if you import a  
key or generate a key, it is returned encrypted by the current master-key within the  
Coprocessor used for the task.  
Chapter 2. CCA Node-Management and Access-Control 2-17  
CCA Release 2.54  
AIX and Windows Multi-Coprocessor Master-Key Support: It is a general  
recommendation that all of the CCA Coprocessors within the system use the same  
current and old master keys. When setting a new master-key, it is essential that all  
of the changes are performed by a single program running on a single thread. If  
the thread-process is ended before all of the Coprocessor master-keys are  
changed, significant complications can arise. It is suggested that you start the  
CNM utility and use it to make all of the changes before you end the utility.  
If you fail to change all of the master keys with the same program running on the  
same thread, either because there is an unplanned interruption, or perhaps  
because you intend to have different master keys between Coprocessors, you need  
to understand the design of the CCA host code that is described next.  
CCA Host Code Design: (AIX and Windows) CCA keeps a copy of the symmetric  
or the asymmetric current-master-key verification pattern in the key-storage header  
records. This information is used to ensure that a given key-storage file is  
associated with a Coprocessor having the same current master-key. This can  
prevent accessing an out-of-date key-storage backup file. The verification pattern  
is written into the header record when key storage is initialized, and when the  
current master-key is changed in a Coprocessor.  
CCA also keeps two flags in memory associated with a host-processing thread. If  
there are multiple threads, each thread has its own set of flags. The flags,  
symmetric-directory-open (SDO) and asymmetric-directory-open (ADO), are set to  
false when CCA processing begins on the thread.  
When a CCA verb is called and a key storage is referenced, and if the associated  
flag (SDO or ADO) is false, CCA obtains the verification pattern for the current  
master-key and compares this to the header-record information. If the patterns  
match, the flag is set to true, and processing continues. If the existing patterns do  
not match, processing is terminated with an error indication. If there is no current  
master-key or if key storage has not been initialized, processing continues  
although, depending on the CCA verb, other error conditions may arise.  
A key-storage reference occurs in two cases:  
1. When the verb call employs a key label  
2. When the SET master-key option is used on the Master_Key_Process verb.  
Situations to Consider: Given the design of the host code, when you employ  
multiple Coprocessors with CCA, you should consider the following cases in regard  
to master keys. Remember that if you explicitly manage the symmetric or the  
asymmetric master keys (using the SYM-MK or ASYM-MK keywords on the  
Master_Key_Process verb), you have both master keys and both key storages to  
consider. If you do not explicitly manage the two classes of master keys, then the  
implementation will operate as though there is a single set of master keys. The  
CNM utility provided with the CCA Support Program does not explicitly manage the  
two sets of keys and the program design assumes that the master keys have  
always been managed without explicit reference to the symmetric or the  
asymmetric keys.  
Setting master keys in multiple Coprocessors.  
If, as recommended, you keep the master keys the same in all of the CCA  
Coprocessors, and you set the master key in each of the Coprocessors from a  
single program running on the same thread, the following will take place:  
2-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
When all of the Coprocessors are newly initialized, that is, their  
current-master-key registers are empty, first install the same master key in  
each of the new-master-key registers. Then set the master key in each of  
the Coprocessors. Finally, if you are going to use key storage, initialize  
key storage.  
If all of the Coprocessors have the same current master-key, when you  
undertake to set the master key in the first Coprocessor, the code will  
attempt to set the directory-open flags (SDO and ADO). This should  
succeed if you have the proper key-storage files (or key storage is not  
initialized). Note that the verification pattern in the key-storage header is  
changed as soon as the first master-key is set.  
When you set the master key in the additional Coprocessors, because the  
directory-open flags are already set, no check is made to ensure that the  
verification patterns in key storage and for the current-master-key match  
(and they would not match because the header was updated when the  
first Coprocessor master-key was set). As soon as the master key is set,  
its verification pattern will be copied to the header in key storage.  
Note that the key in the new-master-key register is not verified. You may  
wish to confirm the proper and consistent contents of these registers  
using the key-test service prior to undertaking setting of the master keys.  
Setting the master key in a Coprocessor after other Coprocessor(s) are  
successfully in operation.  
If you have one or more Coprocessors in operation and then wish to add an  
additional Coprocessor and need to set its current, and possibly old, master  
keys to the keys already in the other Coprocessors, special care must be  
taken. Two cases should be considered:  
1. If the new Coprocessor has a current master-key that is not the same as  
that in the other Coprocessors, and if key storage is initialized for use with  
the other Coprocessors, when you start a new thread and attempt to set  
the master key, the action will fail unless you take precautions. Because  
the directory-open flag(s) are initially set to false, the CCA host code will  
compare the verification pattern for the current master-key in the  
Coprocessor and in the key-storage header record. This comparison will  
fail and processing will terminate with an error indication.  
2. If the new Coprocessor did not have a key in the current master-key  
register, the set-master-key operation would proceed. Note that the  
verification pattern for this master key will be copied to an initialized  
key-storage header record.  
A solution to the first situation is to proceed as follows:  
Allocate a Coprocessor that has the desired current master key(s)  
Perform a DES_Key_Record_List or other action that will cause the  
key-storage-valid flag(s) to be set.  
Deallocate the Coprocessor  
Allocate the new Coprocessor  
Set the master key.  
Note that you may need to install two master keys into the new Coprocessor  
in order have both the current and the old master-keys agree with those in the  
other Coprocessor(s).  
Chapter 2. CCA Node-Management and Access-Control 2-19  
CCA Release 2.54  
Intentionally using different master keys in a set of Coprocessors.  
This situation becomes very complicated if you are using key storage with a  
subset of the Coprocessors. The preceding discussion provides information  
that you can use to manage this case. If you are not using key storage and  
have not initialized key storage files, then the situation is quite simple. Just  
load and set the master keys as you would in a single-Coprocessor situation.  
Note that while you are changing master keys in a multiple-Coprocessor  
arrangement, it may be undesirable to continue other cryptographic processing.  
Several problems should be considered:  
1. Keys generated or imported and returned enciphered with the latest master key  
are not usable with other Coprocessors until they too have been updated with  
the latest master key. Existing keys may still be usable since the previous  
master key in the updated Coprocessor(s) will be in the old master-key register  
and CCA can use this to recover the working keys.  
2. The header record in the key-storage file may have been altered to an  
undesirable value--refer to the earlier discussion.  
3. If you set the master key without specifically mentioning symmetric or  
asymmetric keys (this is the way the CNM utility operates), and if you are using  
key storage, you will need to have both the symmetric and the asymmetric key  
storage files initialized, even if you do not place keys in one or both of the key  
storages files.  
2-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Access_Control_Initialization  
Access_Control_Initialization (CSUAACI)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Access_Control_Initialization verb is used to initialize or update parameters  
and tables for the Access-Control system in the 4758 Cryptographic Coprocessor.  
You can use this verb to perform the following services:  
Load roles and user profiles  
Change the expiration date for a user profile  
Change the authentication data, such as a passphrase, in a user profile  
Reset the authentication failure count in a user profile.  
You select which service to perform by specifying the corresponding keyword in the  
input rule-array. You can only perform one of these services per verb call.  
Restrictions  
Format  
None  
CSUAACI  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one, two, or three  
rule_array_count * 8 bytes  
Integer  
String  
array  
verb_data_1_length  
verb_data_1  
verb_data_2_length  
verb_data_2  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
verb_data_1_length bytes  
verb_data_2_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one,  
two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 2. CCA Node-Management and Access-Control 2-21  
Access_Control_Initialization  
CCA Release 2.54  
Keyword  
Meaning  
Function to perform (one required)  
INIT-AC  
Initializes roles and user profiles.  
Changes the expiration date in a user profile.  
CHGEXPDT  
CHG-AD  
Changes authentication data in a user profile or changes a  
user's passphrase.  
Note: The PROTECTD keyword must also be used  
whenever you use CHG-AD. You must authenticate yourself  
before you are allowed to change authentication data, and the  
use of protected mode verifies that you have been  
authenticated.  
RESET-FC  
Resets the count of consecutive failed logon attempts for a  
user. Clearing the failure count permits a user to log on  
again, after being locked out due to too many failed  
consecutive attempts.  
Options (one or two, optional)  
PROTECTD  
Specifies to operate in protected mode. Data sent to the  
Coprocessor is protected by encrypting the data with the  
user's session key, KS.  
If the user has not successfully logged on, there is no session  
key in effect, and the PROTECTD keyword will result in an  
abnormal termination.  
REPLACE  
Specifies that a new profile can replace an existing profile with  
the same name. This keyword applies only when the rule  
array contains the INIT-AC keyword.  
Without the REPLACE keyword, any attempt to load a profile  
which already exists will be rejected. This protects against  
accidentally overlaying a user's profile with one for a different  
user who has chosen the same profile ID as one that is  
already on the Coprocessor.  
verb_data_1_length  
The verb_data_1_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the verb_data_1 variable.  
verb_data_1  
The verb_data_1 parameter is a pointer to a string variable containing data  
used by the verb.  
This field is used differently depending on the function being performed.  
Rule-Array  
Keyword  
Contents of verb_data_1 field  
INIT-AC  
The field contains a list of zero or more user profiles to be  
loaded into the Coprocessor. See “Profile Structure” on  
page B-32.  
CHGEXPDT,  
CHG-AD, or  
RESET-FC  
The field contains the eight-character profile ID for the user  
profile that is to be modified.  
2-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Access_Control_Initialization  
verb_data_length_2  
The verb_data_length_2 parameter is a pointer to an integer variable containing  
the number of bytes of data in the verb_data_2 variable.  
verb_data_2  
The verb_data_2 parameter is a pointer to a string variable containing data  
used by the verb. Authentication data structures are described in  
“Access-Control Data Structures” on page B-28.  
This field is used differently depending on the function being performed.  
Rule-Array  
Keyword  
Contents of verb_data_2 field  
INIT-AC  
The field contains a list of zero or more roles to be loaded into  
the Coprocessor. See “Role Structure” on page B-29.  
CHGEXPDT  
The field contains the new expiration date to be stored in the  
specified user profile. The expiration date is an  
eight-character string, in the form YYYYMMDD.  
CHG-AD  
The field contains the new authentication-data, to be used in  
the specified user profile.  
If the profile currently contains authentication data for the  
same authentication mechanism, that data is replaced by the  
new data. If the profile does not contain authentication data  
for the mechanism, the new data is added to the data  
currently stored for the specified profile.  
RESET-FC  
The verb_data_2 field is empty. Its length is zero.  
Required Commands  
The Access_Control_Initialization verb requires the following commands to be  
enabled:  
Initialize the access-control system roles and profiles (offset X'0112') with the  
INIT-AC keyword. See “Profile Structure” on page B-32.  
Change the expiration date in a user profile (offset X'0113') with the  
CHGEXPDT keyword.  
Change the authentication data in a user profile (offset X'0114') with the  
CHG-AD keyword.  
Reset the logon failure count in a user profile (offset X'0115') with the  
RESET-FC keyword.  
Chapter 2. CCA Node-Management and Access-Control 2-23  
Access_Control_Maintenance  
CCA Release 2.54  
Access_Control_Maintenance (CSUAACM)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Access_Control_Maintenance verb is used to query or control installed roles  
and user profiles.  
You can use this verb to perform the following services:  
Retrieve a list of the installed roles or user profiles  
Retrieve the non-secret data for a selected role or user profile  
Delete a selected role or user profile from the Coprocessor  
Retrieve a list of the users who are logged on to the Coprocessor.  
You select which service to perform by specifying the corresponding keyword in the  
input rule-array. You can only perform one of these services per verb call.  
Restrictions  
Format  
None  
CSUAACM  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
name  
Input  
String  
8 bytes  
output_data_length  
output_data  
In/Output Integer  
Output String  
output_data_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
2-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Access_Control_Maintenance  
Keyword  
Meaning  
Function to perform (one required)  
LSTPROFS  
LSTROLES  
Retrieves a list of the user profiles currently installed in the  
Coprocessor.  
Keyword Q-NUM-RP shows how to determine how much data  
this request will return to the application program.  
Retrieves a list of the roles currently installed in the  
Coprocessor.  
Keyword Q-NUM-RP shows how to determine how much data  
this request will return to the application program.  
GET-PROF  
GET-ROLE  
Retrieves the non-secret part of a specified user profile.  
Retrieve the non-secret part of a role definition from the  
Coprocessor.  
DEL-PROF  
DEL-ROLE  
Q-NUM-RP  
Deletes a specified user profile.  
Deletes a specified role definition from the Coprocessor.  
Queries the number of roles and profiles presently installed in  
the Coprocessor. This allows the application program to know  
how much data will be returned with the LSTROLES or  
LSTPROFS keywords.  
Q-NUM-UR  
LSTUSERS  
Queries the number of users currently logged on to the  
Coprocessor. This allows the application program to know  
how much data will be returned with the LSTUSERS keyword.  
Users may log on or log off between the time you use  
Q-NUM-UR and the time you use LSTUSERS, so the list of  
users may not always contain exactly the number the  
Coprocessor reported was logged on.  
Retrieves a list of the profile IDs for all users who are  
currently logged on to the Coprocessor.  
name  
The name parameter is a pointer to a string variable containing the name of a  
role or user profile which is the target of the request.  
This field is used differently depending on the function being performed.  
Rule-Array  
Keyword  
Contents of name variable  
LSTPROFS,  
LSTROLES,  
Q-NUM-RP,  
Q-NUM-UR, or  
LSTUSERS  
The name field is unused.  
GET-PROF or  
DEL-PROF  
The name field contains the eight-character profile ID for the  
user profile that is to be retrieved or deleted.  
GET-ROLE or  
DEL-ROLE  
The name field contains the eight-character role ID for the role  
definition that is to be retrieved or deleted.  
Chapter 2. CCA Node-Management and Access-Control 2-25  
Access_Control_Maintenance  
CCA Release 2.54  
output_data_length  
The output_data_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the output_data variable. The value must be a  
multiple of four bytes.  
On input, the output_data_length variable must be set to the total size of the  
variable pointed to by the output_data parameter. On output, this variable will  
contain the number of bytes of data returned by the verb in the output_data  
variable.  
output_data  
The output_data parameter is a pointer to a string variable containing data  
returned by the verb. Any integer value returned in the output_data field is in  
big-endian format; the high-order byte of the value is in the lowest-numbered  
address in storage. Authentication data structures are described in  
“Access-Control Data Structures” on page B-28.  
This field is used differently depending on the function being performed.  
Rule-Array  
Keyword  
Contents of output_data Variable  
LSTPROFS  
Contains a list of the profile IDs for all the user profiles stored  
in the Coprocessor.  
LSTROLES  
Contains a list of the role IDs for all the roles stored in the  
Coprocessor.  
2-26 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Access_Control_Maintenance  
Rule-Array  
Keyword  
Contents of output_data Variable  
GET-PROF  
Contains the non-secret portion of the selected user profile.  
This includes the following data, in the order listed.  
Profile version Two bytes containing 2 one-byte integer  
values, where the first byte contains the major  
version number and the second byte contains the  
minor version number.  
Comment A 20-character field, padded on the right with  
spaces, which describes the profile. This field is  
not X'00' terminated.  
Role  
The eight-character name of the user's assigned  
role.  
Logon failure count A one-byte integer containing the  
number of consecutive failed logon attempts by the  
user.  
Pad  
A one-byte padding value containing X'00'.  
Activation date The first date on which the profile is valid.  
The date consists of a two-byte integer containing  
the year, followed respectively by a one-byte  
integer for the month and a one-byte integer for the  
day of the month.  
Expiration date The last date on which the profile is valid.  
The format is the same as the Activation date  
described above.  
List of enrolled authentication mechanism information For  
each authentication mechanism associated with the  
profile, the verb returns a series of three integer  
values:  
1. The two-byte Mechanism ID  
2. The two-byte Mechanism Strength  
3. The four-byte authentication data Expiration  
date, which has the same format as the  
Activation date described above.  
Note that the authentication data itself is not returned, only the  
IDs, strength, and expiration date of the data are returned.  
Chapter 2. CCA Node-Management and Access-Control 2-27  
Access_Control_Maintenance  
CCA Release 2.54  
Rule-Array  
Contents of output_data Variable  
Keyword  
GET-ROLE  
The field contains the non-secret portion of the selected role.  
This includes the following data, in the order listed.  
Role version Two bytes containing integer values, where the  
first byte contains the major version number and  
the second byte contains the minor version  
number.  
Comment A 20-character field, padded with spaces,  
containing a comment which describes the role.  
This field is not X'00' terminated.  
Required authentication-strength level A two-byte integer  
defining how secure the user authentication must  
be in order to authorize this role.  
Lower time-limit The earliest time of day that this role can be  
used. The time limit consists of two integer values,  
a one-byte hour, followed by a one-byte minute.  
The hour can range from 0-23, and the minute can  
range from 0-59.  
Upper time-limit The latest time of day that this role can be  
used. The format is the same as the Lower  
time-limit.  
Valid days of the week A one-byte field defining which days  
of the week this role can be used. Seven bits of  
the byte are used to represent Sunday through  
Saturday, where a '1' bit means that the day is  
allowed, while a '0' bit means it is not.  
The first bit (MSB) is for Sunday, and the last bit  
(LSB) is unused and is set to zero.  
Access-control-point list The access-control-point bit map  
defines which functions a user with this role is  
permitted to run.  
DEL-PROF or  
DEL-ROLE  
The variable is empty. Its length is zero.  
Q-NUM-RP  
The variable contains an array of two four-byte integers. The  
first integer is the number of roles currently loaded with use of  
the Access_Control_Initialization verb, while the second  
integer is the number of user profiles currently loaded with use  
of the same verb.  
Q-NUM-UR  
LSTUSERS  
The variable contains a single integer value which indicates  
the number of users currently logged on to the Coprocessor.  
The variable contains an array of eight-character profile IDs,  
one for each user currently logged on to the Coprocessor.  
The list is not in any meaningful order.  
2-28 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Access_Control_Maintenance  
Required Commands  
The Access_Control_Maintenance verb requires the following commands to be  
enabled in the hardware:  
Read public access-control information (offset X'0116') with the LSTPROFS,  
LSTROLES, GET-PROF, GET-ROLE, and Q-NUM-RP keywords  
Delete a User Profile (offset X'0117') with the DEL-PROF keyword  
Delete a Role (offset X'0118') with the DEL-ROLE keyword.  
Chapter 2. CCA Node-Management and Access-Control 2-29  
Cryptographic_Facility_Control  
CCA Release 2.54  
Cryptographic_Facility_Control (CSUACFC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
Use the Cryptographic_Facility_Control verb to perform the following services:  
Reinitialize the CCA application in the Coprocessor.  
Set the date and time in the Coprocessor clock.  
Reset the Coprocessor Intrusion Latch (see page 2-10)  
Reset the Coprocessor Battery-Low Indicator (see page 2-10)  
Load or clear the Function Control Vector, which defines limitations on the  
cryptographic functions available in the Coprocessor.  
Establish the environment identifier (EID), which is a user-defined identifier.  
Once set, the EID can only be set again following a CCA reinitialization.  
Establish the minimum and maximum number of “cloning information” shares  
that are required and that can be used to pass sensitive information from one  
Coprocessor to another Coprocessor.  
Select which service to perform by specifying the corresponding keyword in the  
input rule-array. You can only perform one of these services per verb call.  
Restrictions  
Use only these characters in an environment identifier (EID): A...Z, a...z, 0...9, and  
these additional characters relating to different character symbols in the various  
national language character sets as listed below:  
ASCII  
EBCDIC  
Systems  
X'40'  
X'50'  
X'7E'  
USA Graphic  
(for reference)  
space character  
&
=
@
Systems  
X'20'  
X'26'  
X'3D'  
X'40'  
X'7C'  
The alphabetic and numeric characters should be encoded in the normal character  
set for the computing platform that is in use, either ASCII or EBCDIC.  
Format  
CSUACFC  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
verb_data_length  
verb_data  
In/Output Integer  
In/Output String  
verb_data_length bytes  
2-30 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Control  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
This verb requires two keywords in the rule array. One specifies the  
Coprocessor for which the request is intended, the other specifies the function  
to perform. No rule-array elements are set by the verb. The rule_array  
keywords are shown below:  
Keyword  
Coprocessor to use (optional)  
ADAPTER1 This keyword is ignored. It is accepted for backward  
compatibility.  
Control function to perform (one required)  
Meaning  
RQ-TOKEN  
Requests a random eight-byte token from the adapter, which  
is returned in the verb_data variable. This is the first step  
when reinitializing the Coprocessor.  
The second step for reinitialization uses RQ-REINT, described  
below.  
RQ-REINT  
Reinitializes the CCA application in the Coprocessor. For  
RQ-REINT, you must set the verb_data field to the one's  
complement of the token that was returned by the  
Coprocessor when you executed the verb using the  
RQ-TOKEN keyword. This is the second and final step when  
reinitializing the Coprocessor.  
This two-step process provides protection against accidental  
reinitialization of the Coprocessor.  
SETCLOCK  
Sets the date and time of the Coprocessor's secure clock.  
You must put the date and time values in the verb_data  
variable, as described under the description of that parameter.  
RESET-IL  
RESETBAT  
LOAD-FCV  
CLR-FCV  
SET-EID  
Clears the Intrusion Latch on the Coprocessor.  
Clears the Battery-Low Indicator (latch) on the Coprocessor.  
Loads a new Function Control Vector into the Coprocessor.  
Clears the Function Control Vector from the Coprocessor.  
Sets an environment identifier (EID) value.  
SET-MOFN  
Sets the minimum and maximum number of “cloning  
information” shares that are required and that can be used to  
pass sensitive information from one Coprocessor to another  
Coprocessor.  
Chapter 2. CCA Node-Management and Access-Control 2-31  
Cryptographic_Facility_Control  
CCA Release 2.54  
verb_data_length  
The verb_data_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the verb_data variable. On input, specify the  
size of the variable. The verb updates the variable with the size of the returned  
data.  
verb_data  
The verb_data parameter is a pointer to a string variable containing data used  
by the verb on input, or generated by the verb on output.  
This field is used differently depending on the value of the control function  
selected by a rule-array keyword.  
For RQ-TOKEN, verb_data is an output parameter. It receives an  
eight-byte randomly generated value, which the application uses with the  
RQ-REINT keyword on a subsequent call.  
On input, the verb_data_length variable must contain the length of the  
buffer addressed by the verb_data pointer. Allocate an eight-byte buffer  
and specify this length in the verb_data_length variable.  
For RQ-REINT, verb_data is an input parameter. You must set it to the  
one's complement of the token you received as a result of the RQ-TOKEN  
call. Allocate an eight-byte buffer and specify this length in the  
verb_data_length variable.  
For SETCLOCK, verb_data is an input variable. It must contain a  
character string which contains the current GMT date and time. Allocate a  
16-byte buffer and specify this length in the verb_data_length variable.  
This string has the form YYYYMMDDHHmmSSWW, where these fields are  
defined as follows.  
YYYY The current year  
MM  
DD  
The current month, from 01 to 12  
The current day of the month, from 01 to 31  
The current hour of the day, from 00 to 23  
The current minutes past the hour, from 00 to 59  
The current seconds past the minute, from 00 to 59  
HH  
mm  
SS  
WW  
The current day of the week, where Sunday is represented as 01,  
and Saturday by 07.  
For LOAD-FCV, verb_data is an input variable. It must contain a character  
string which contains the function control vector (FCV) as described in  
“Function Control Vector” on page B-42. Allocate a 204-byte buffer and  
specify this length in the verb_data_length variable.  
For CLR-FCV, no data is provided and the verb_data_length variable  
should be set to zero.  
For SET-EID, verb_data is an input variable. The variable contains a  
16-byte environment identifier, or EID, value. This identifier is used in  
verbs such as PKA_Key_Generate and PKA_Symmetric_Key_Import. See  
“Restrictions” on page 2-30 for a list of valid characters in an environment  
identifier. Allocate a 16-byte buffer and specify this length in the  
verb_data_length variable.  
2-32 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Control  
For SET-MOFN, verb_data is an input variable. The variable contents  
establish the minimum and maximum number of “cloning information”  
shares that are required and that can be used to pass sensitive information  
from one Coprocessor to another Coprocessor. The verb_data variable  
contains a two-element array of integers. The first element is the m  
minimum required number of shares to reconstruct cloned information (see  
the Master_Key_Distribution verb). The second element is the n maximum  
number of shares that can be issued to reconstruct cloned information (see  
the Master_Key_Distribution verb). Allocate an eight-byte buffer (two,  
four-byte integers) and specify this length in the verb_data_length variable.  
Required Commands  
The Cryptographic_Facility_Control verb requires the following commands to be  
enabled in the hardware:  
Reinitialize Device (offset X'0111') with the RQ-TOKEN, RQ-REINT keywords  
Set Clock (offset X'0110') with the SETCLOCK keyword  
Reset Intrusion Latch (offset X'010F') with the RESET-IL keyword  
Reset Battery-LOW Indicator (offset X'030B') with the RESETBAT keyword  
Load a Function Control Vector (offset X'0119') with the LOAD-FCV keyword  
Clear the Function Control Vector (offset X'011A') with the CLR-FCV keyword  
Set EID command (offset X'011C') with the SET-EID keyword  
Initialize Master Key Cloning command (offset X'011D') with the SET-MOFN  
keyword.  
Chapter 2. CCA Node-Management and Access-Control 2-33  
Cryptographic_Facility_Query  
CCA Release 2.54  
Cryptographic_Facility_Query (CSUACFQ)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Cryptographic_Facility_Query verb is used to retrieve information about the  
Cryptographic Coprocessor and the CCA application program in that Coprocessor.  
This information includes the following:  
General information about the Coprocessor  
General information about the CCA application program in the Coprocessor  
Status of master-key shares distribution  
Environment identifier, EID  
Diagnostic information from the Coprocessor  
Export-control information from the Coprocessor  
Time and date information.  
On input, you specify:  
A rule-array count of one or two  
Optionally a rule-array keyword of ADAPTER1  
The class of information queried with a rule-array keyword.  
The verb returns information elements in the rule array and sets the  
rule-array-count variable to the number of returned elements.  
Restrictions  
Format  
You cannot limit the number of returned rule-array elements. Figure 2-3 on  
page 2-35 describes the number and meaning of the information in output  
rule-array elements. You are advised to allocate a minimum of 30 rule-array  
elements to allow for extensions of the returned information.  
CSUACFQ  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
Integer  
Integer  
In/Output Integer  
In/Output String  
In/Output Integer  
In/Output String  
array  
exit_data_length  
one or two on input  
rule_array_count * 8 bytes  
verb_data_length  
verb_data  
In/Output Integer  
In/Output String  
verb_data_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. On input, the value must be  
one or two for this verb.  
2-34 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Query  
On output, the verb sets the variable to the number of rule-array elements it  
returns to the application program.  
Note: With this verb, the number of returned rule-array elements can exceed  
the rule-array count that you specified on input. Be sure that you allocate  
adequate memory to receive all of the information elements according to the  
information class that you select on input with the information-to-return keyword  
in the rule-array.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
On input, set the rule array to specify the type of information to retrieve. There  
are two input rule_array elements, as described below.  
Keyword  
Adapter to use (optional)  
ADAPTER1 This keyword is ignored. It is accepted for backward  
compatibility.  
Information to return (one required)  
Meaning  
STATCCA  
STATCCAE  
STATCARD  
STATDIAG  
STATEID  
Gets CCA-related status information.  
Gets CCA-related extended status information.  
Gets Coprocessor-related basic status information.  
Gets diagnostic information.  
Gets the environment identifier, EID.  
STATEXPT  
STATMOFN  
TIMEDATE  
Gets function control vector-related status information.  
Gets master-key shares distribution information.  
Reads the current date, time, and day of the week from the  
secure clock within the Coprocessor.  
The format of the output rule-array depends on the value of the rule-array  
element which identifies the information to be returned. Different sets of  
rule-array elements are returned depending on whether the input keyword is  
STATCCA, STATCCAE, STATCARD, STATDIAG, STATEID, STATEXPT, or  
STATMOFN, TIMEDATE.  
For rule-array elements that contain numbers, those numbers are represented  
by numeric characters which are left-justified and padded on the right with  
space characters. For example, a rule-array element which contains the  
number two will contain the character string “2  
.  
On output, the rule-array elements can have the values shown in the table  
below.  
Chapter 2. CCA Node-Management and Access-Control 2-35  
Cryptographic_Facility_Query  
CCA Release 2.54  
Figure 2-3 (Page 1 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
Output rule-array for option STATCCA  
1
NMK Status  
State of the New Master-Key register:  
One means the register is clear  
Two means the register contains a partially  
complete key  
Three means the register contains a  
complete key.  
2
3
CMK Status  
OMK Status  
State of the Current Master-Key register:  
One means the register is clear  
Two means the register contains a key.  
State of the Old Master-Key register:  
One means the register is clear  
Two means the register contains a key.  
4
5
6
CCA Application  
Version  
A character string that identifies the version of  
the CCA application program that is running in  
the Coprocessor.  
CCA Application  
Build Date  
A character string containing the build date for  
the CCA application program that is running in  
the Coprocessor.  
User Role  
A character string containing the Role identifier  
which defines the host application user's  
current authority.  
2-36 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Query  
Figure 2-3 (Page 2 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
Output rule-array for option STATCCAE  
1
Symmetric NMK  
Status  
State of the Symmetric New Master-Key  
register:  
One means the register is clear  
Two means the register contains a partially  
complete key  
Three means the register contains a  
complete key.  
2
3
Symmetric CMK  
Status  
State of the Symmetric Current Master-Key  
register:  
One means the register is clear  
Two means the register contains a key.  
Symmetric OMK  
Status  
State of the Symmetric Old Master-Key  
register:  
One means the register is clear  
Two means the register contains a key.  
4
5
6
7
CCA Application  
Version  
A character string that identifies the version of  
the CCA application program that is running in  
the Coprocessor.  
CCA Application  
Build Date  
A character string containing the build date for  
the CCA application program that is running in  
the Coprocessor.  
User Role  
A character string containing the Role identifier  
which defines the host application user's  
current authority.  
Asymmetric NMK  
Status  
State of the Asymmetric New Master-Key  
register:  
One means the register is clear  
Two means the register contains a partially  
complete key  
Three means the register contains a  
complete key.  
8
9
Asymmetric CMK  
Status  
State of the Asymmetric Current Master-Key  
register:  
One means the register is clear  
Two means the register contains a key.  
Asymmetric OMK  
Status  
State of the Asymmetric Old Master-Key  
register:  
One means the register is clear  
Two means the register contains a key.  
Chapter 2. CCA Node-Management and Access-Control 2-37  
Cryptographic_Facility_Query  
CCA Release 2.54  
Figure 2-3 (Page 3 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
Output rule-array for option STATCARD  
1
Number of Installed  
Adapters  
The number of active Cryptographic  
Coprocessors installed in the machine. Note  
that this only includes Coprocessors that have  
CCA software loaded (including those with CCA  
UDX software). Non-CCA Coprocessors are  
not included in this number.  
2
3
4
DES Hardware  
Level  
A numeric character string containing an  
integer value identifying the version of DES  
hardware that is on the Coprocessor.  
RSA Hardware  
Level  
A numeric character string containing an  
integer value identifying the version of RSA  
hardware that is on the Coprocessor.  
POST Version  
A character string identifying the version of the  
Coprocessor's Power-On Self Test (POST)  
firmware.  
The first four characters define the POST0  
version, and the last four characters define the  
POST1 version.  
5
6
7
8
9
Coprocessor  
Operating System  
Name  
A character string identifying the operating  
system firmware on the Coprocessor.  
Coprocessor  
Operating System  
Version  
A character string identifying the version of the  
Coprocessor's operating system firmware.  
Coprocessor Part  
Number  
A character string containing the  
eight-character part number identifying the  
version of the Coprocessor.  
Coprocessor EC  
Level  
A character string containing the  
eight-character EC (Engineering Change) level  
for this version of the Coprocessor.  
Miniboot Version  
A character string identifying the version of the  
Coprocessor's Miniboot firmware. This  
firmware controls the loading of programs into  
the Coprocessor.  
The first four characters define the MiniBoot0  
version, and the last four characters define the  
MiniBoot1 version.  
10  
11  
CPU Speed  
A numeric character string containing the  
operating speed of the microprocessor chip, in  
Megahertz.  
Adapter ID  
Also see element  
number 15.  
A unique identifier manufactured into the  
Coprocessor. The Coprocessor's Adapter ID is  
an eight-byte binary value where the  
high-order byte is X'78' for an IBM 4758-001  
and 4758-013, and is X'71' for an IBM  
4758-002 and 4758-023. The remaining bytes  
are a random value.  
2-38 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Query  
Figure 2-3 (Page 4 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
12  
13  
14  
15  
Flash Memory Size  
A numeric character string containing the size  
of the flash EPROM memory on the  
Coprocessor, in 64-kilobyte increments.  
DRAM Memory  
Size  
A numeric character string containing the size  
of the dynamic RAM (DRAM) memory on the  
Coprocessor, in kilobytes.  
Battery-Backed  
Memory Size  
A numeric character string containing the size  
of the battery-backed RAM on the Coprocessor,  
in kilobytes.  
Serial Number  
A character string containing the unique serial  
number of the Coprocessor. The serial number  
is factory installed and is also reported by the  
CLU utility in a Coprocessor-signed status  
message.  
Output rule-array for option STATDIAG  
1
Battery State  
A numeric character string containing a value  
which indicates whether the battery on the  
Coprocessor needs to be replaced:  
One means that the battery is good  
Two means that the battery should be  
replaced.  
2
3
Intrusion Latch  
State  
A numeric character string containing a value  
which indicates whether the Intrusion Latch on  
the Coprocessor is set or cleared:  
One means that the latch is cleared  
Two means that the latch is set.  
Error Log Status  
A numeric character string containing a value  
which indicates whether there is data in the  
Coprocessor CCA error log:  
One means that the error log is empty  
Two means that the error log contains data,  
but is not yet full  
Three means that the error log is full, and  
cannot hold any more abnormal termination  
data.  
4
Mesh Intrusion  
A numeric character string containing a value to  
indicate whether the Coprocessor has detected  
tampering with the protective mesh that  
surrounds the secure module. This indicates a  
probable attempt to physically penetrate the  
module:  
One means no intrusion had been detected  
Two means an intrusion attempt detected.  
Chapter 2. CCA Node-Management and Access-Control 2-39  
Cryptographic_Facility_Query  
CCA Release 2.54  
Figure 2-3 (Page 5 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
5
Low Voltage  
Detected  
A numeric character string containing a value to  
indicate whether a power supply voltage was  
below the minimum acceptable level. This may  
indicate an attempt to attack the security  
module:  
One means only acceptable voltages have  
been detected  
Two means a voltage has been detected  
below the low-voltage tamper threshold.  
6
High Voltage  
Detected  
A numeric character string containing a value to  
indicate whether a power supply voltage was  
above the maximum acceptable level. This  
may indicate an attempt to attack the security  
module:  
One means only acceptable voltages have  
been detected  
Two means a voltage has been detected  
above the high-voltage tamper threshold.  
7
Temperature  
Range Exceeded  
A numeric character string containing a value to  
indicate whether the temperature in the secure  
module was outside of the acceptable limits.  
This may indicate an attempt to obtain  
information from the module:  
One means the temperature is acceptable  
Two means the temperature has been  
detected outside of an acceptable limit.  
8
Radiation Detected  
A numeric character string containing a value to  
indicate whether radiation was detected inside  
the secure module. This may indicate an  
attempt to obtain information from the module:  
One means no radiation has been detected  
Two means radiation has been detected.  
9, 11,  
13, 15,  
17  
Last Five  
Commands Run  
These five rule-array elements contain the last  
five commands that were executed by the  
Coprocessor CCA application. They are in  
chronological order, with the most recent  
command in element 9. Each element contains  
the security API command code in the first four  
characters, and the subcommand code in the  
last four characters.  
10, 12,  
14, 16,  
18  
Last Five Return  
Codes  
These five rule-array elements contain the  
SAPI return codes and reason codes  
corresponding to the five commands in  
rule-array elements 9, 11, 13, 15, and 17.  
Each element contains the return code in the  
first four characters, and the reason code in the  
last four characters.  
2-40 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Query  
Figure 2-3 (Page 6 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
Output rule-array for option STATEID (Environment Identifier)  
1,2  
EID  
The two elements when concatenated provide  
the 16-byte EID value.  
Output rule-array for option STATEXPT  
1
Base CCA  
Services  
Availability  
A numeric character string containing a value to  
indicate whether base CCA services are  
available:  
Zero means base CCA services are not  
available  
One means base CCA services are  
available.  
2
3
CDMF Availability  
A numeric character string containing a value to  
indicate whether CDMF encryption is available:  
Zero means CDMF encryption is not  
available  
One means CDMF encryption is available.  
56-bit DES  
Availability  
A numeric character string containing a value to  
indicate whether 56-bit DES encryption is  
available:  
Zero means 56-bit DES encryption is not  
available  
One means 56-bit DES encryption is  
available.  
4
Triple-DES  
Availability  
A numeric character string containing a value to  
indicate whether Triple-DES encryption is  
available:  
Zero means Triple-DES encryption is not  
available  
One means Triple-DES encryption is  
available.  
5
6
SET Services  
Availability  
A numeric character string containing a value to  
indicate whether SET (Secure Electronic  
Transaction) services are available:  
Zero means SET services are not available  
One means SET services are available.  
Maximum Modulus  
for Symmetric Key  
Encryption  
A numeric character string containing the  
maximum modulus size that is enabled for the  
encryption of symmetric keys. This defines the  
longest public-key modulus that can be used  
for key management of symmetric-algorithm  
keys.  
Chapter 2. CCA Node-Management and Access-Control 2-41  
Cryptographic_Facility_Query  
CCA Release 2.54  
Figure 2-3 (Page 7 of 7). Cryptographic_Facility_Query Information Returned in  
the Rule Array  
Element  
Number  
Name  
Description  
Output rule-array for option STATMOFN  
Elements one and two, and elements three and four, are each treated as a 16-byte  
string with the high-order 15 bytes having meaningful information and the 16th byte  
containing a space character. Each byte provides status information about the 'i'th  
share, 1i15, of master-key information.  
1, 2  
Master-Key Shares  
Generation  
The 15 individual bytes are set to one of these  
character values:  
0
1
2
Cannot be generated  
Can be generated  
Has been generated but not  
distributed  
3
4
Generated and distributed once  
Generated and distributed more  
than once.  
3, 4  
Master-Key Shares  
Reception  
The 15 individual bytes are set to one of these  
character values:  
0
1
3
4
Cannot be received  
Can be received  
Has been received  
Has been received more than once.  
5
6
'm'  
The minimum number of shares required to  
instantiate a master key through the  
master-key-shares process. The value is  
returned in two characters, valued from 01 to  
15, followed by six space characters.  
'n'  
The maximum number of distinct shares  
involved in the master-key shares process.  
The value is returned in two characters, valued  
from 01 to 15, followed by six space  
characters.  
Output rule-array for option TIMEDATE  
1
Date  
The current date is returned as a character  
string of the form YYYYMMDD, where YYYY  
represents the year, MM represents the month  
(01-12), and DD represents the day of the  
month (01-31).  
2
3
Time  
The current GMT time of day is returned as a  
character string of the form HHMMSS.  
Day of the Week  
The day of the week is returned as a number  
between 1 (Sunday) and 7 (Saturday).  
verb_data_length  
The verb_data_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the verb_data variable.  
verb_data  
The verb_data parameter is a pointer to a string variable containing data sent  
to the Coprocessor for this verb, or received from the Coprocessor as a result  
2-42 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Facility_Query  
of this verb. Its use depends on the options specified by the host application  
program.  
The verb_data parameter is not currently used by this verb.  
Required Commands  
Cryptographic_Facility_Query is a universally authorized verb. There are no  
access-control restrictions on its use.  
Chapter 2. CCA Node-Management and Access-Control 2-43  
Cryptographic_Resource_Allocate  
CCA Release 2.54  
Cryptographic_Resource_Allocate (CSUACRA)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Cryptographic_Resource_Allocate verb is used to allocate a specific CCA  
Coprocessor for use by the thread or process, depending on the scope of the verb.  
For the OS/400, this verb is scoped to a process; for the other implementations,  
this verb is scoped to a thread. When a thread (or process, depending on the  
scope) allocates a cryptographic resource, requests will be routed to that resource.  
When a cryptographic resource is not allocated, requests will be routed to the  
default cryptographic resource.  
You can set the default cryptographic resource. If you take no action, the default  
assignment is CRP01.  
You cannot allocate a cryptographic resource while one is already allocated. Use  
the Cryptographic_Resource_Deallocate verb to deallocate a currently allocated  
cryptographic resource.  
Be sure to review “Multi-Coprocessor Capability” on page 2-10 and “Master-Key  
Considerations with Multiple CCA Coprocessors” on page 2-17.  
Restrictions  
Format  
None  
CSUACRA  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
resource_name_length  
resource_name  
Input  
Input  
Integer  
String  
resource_name_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
2-44 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Resource_Allocate  
Keyword  
Meaning  
Cryptographic resource (required)  
DEVICE  
Specifies an (IBM 4758) CCA Coprocessor.  
resource_name_length  
The resource_name_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the resource_name variable. The  
length must be within the range of 1 to 64.  
resource_name  
The resource_name parameter is a pointer to a string variable containing the  
name of the Coprocessor to be allocated.  
Required Commands  
None  
Chapter 2. CCA Node-Management and Access-Control 2-45  
Cryptographic_Resource_Deallocate  
CCA Release 2.54  
Cryptographic_Resource_Deallocate (CSUACRD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Cryptographic_Resource_Deallocate verb is used to deallocate a specific CCA  
Coprocessor that is currently allocated by the thread or process, depending on the  
scope of the verb. For the OS/400, this verb is scoped to a process; for the other  
implementations, this verb is scoped to a thread. When a thread (or process,  
depending on the scope) deallocates a cryptographic resource, requests will be  
routed to the default cryptographic resource.  
You can set the default cryptographic resource. If you take no action, the default  
assignment is CRP01.  
Be sure to review “Multi-Coprocessor Capability” on page 2-10 and “Master-Key  
Considerations with Multiple CCA Coprocessors” on page 2-17.  
If a thread with an allocated Coprocessor terminates without first deallocating the  
Coprocessor, excess memory consumption will result. It is not necessary to  
deallocate a cryptographic resource if the process itself is terminating; it is only  
suggested if individual threads terminate while the process continues to run.  
Restrictions  
Format  
None  
CSUACRD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
resource_name_length  
resource_name  
Input  
Input  
Integer  
String  
resource_name_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
2-46 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Resource_Deallocate  
Keyword  
Meaning  
Cryptographic resource (required)  
DEVICE  
Specifies an (IBM 4758) CCA Coprocessor.  
resource_name_length  
The resource_name_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the resource_name variable. The  
length must be within the range of 1 to 64.  
resource_name  
The resource_name parameter is a pointer to a string variable containing the  
name of the Coprocessor to be deallocated.  
Required Commands  
None  
Chapter 2. CCA Node-Management and Access-Control 2-47  
Key_Storage_Designate  
CCA Release 2.54  
Key_Storage_Designate (CSUAKSD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
The Key_Storage_Designate verb specifies the key-storage file used by the  
process.  
You select the type of key storage, for DES keys or for public keys, using a  
rule-array keyword.  
Restrictions  
Format  
None  
CSUAKSD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_storage_file_name_length  
key_storage_file_name  
Input  
Input  
Integer  
String  
key_storage_file_name_length  
bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Key-storage type (one required)  
DES  
PKA  
Indicates that the file name applies to the DES key-storage  
specification.  
Indicates that the file name applies to the public-key  
key-storage specification.  
2-48 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Storage_Designate  
key_storage_file_name_length  
The key_storage_file_name_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the key_storage_file_name variable.  
The length must be within the range of 1 to 64.  
key_storage_file_name  
The key_storage_file_name parameter is a pointer to a string variable  
containing the fully qualified file name of the key-storage file to be selected.  
Required Commands  
None  
Chapter 2. CCA Node-Management and Access-Control 2-49  
Key_Storage_Initialization  
CCA Release 2.54  
Key_Storage_Initialization (CSNBKSI)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Key_Storage_Initialization verb initializes a key-storage file using the current  
symmetric or asymmetric master-key. The initialized key storage will not contain  
any pre-existing key records. The name and path of the key storage data and  
index file are established differently in each operating environment. See the IBM  
4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual for  
information on these files.  
Restrictions  
Format  
None  
CSNBKSI  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
two  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_storage_file_name_length  
key_storage_file_name  
Input  
Input  
Integer  
String  
key_storage_file_name_length  
bytes  
key_storage_description_length  
key_storage_description  
Input  
Input  
Integer  
String  
64  
key_storage_description_length  
bytes  
clear_master_key  
Input  
String  
24 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be two for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Master-key source (required)  
CURRENT Specifies that the current symmetric master-key of the default  
cryptographic facility is to be used for the initialization.  
Meaning  
2-50 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Storage_Initialization  
Keyword  
Meaning  
Key-storage selection (one required)  
DES  
PKA  
Initialize DES key-storage.  
Initialize PKA key-storage.  
key_storage_file_name_length  
The key_storage_file_name_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the key_storage_file_name variable.  
The length must be within the range of 1 to 64.  
key_storage_file_name  
The key_storage_file_name parameter is a pointer to a string variable  
containing the fully qualified file name of the key-storage file to be initialized. If  
the file does not exist, it is created. If the file does exist, it is overwritten and  
all existing keys are lost.  
key_storage_description_length  
The key_storage_description_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the key_storage_description  
variable.  
key_storage_description  
The key_storage_description parameter is a pointer to a string variable  
containing the description string that is stored in the key-storage file when it is  
initialized.  
clear_master_key  
The clear_master_key parameter is unused, but it must be declared and point  
to 24 data bytes in application storage.  
Required Commands  
Except in the OS/400 environment, the Key_Storage_Initialization verb requires the  
Compute Verification Pattern command (offset X'001D') to be enabled in the  
hardware. In the OS/400 environment, no commands are issued to the  
Coprocessor and therefore command authorization does not apply.  
Chapter 2. CCA Node-Management and Access-Control 2-51  
Logon_Control  
CCA Release 2.54  
Logon_Control (CSUALCT)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
Use the Logon_Control verb to perform the following services:  
Log on to the Coprocessor, using your access-control profile  
Log off of the Coprocessor  
Save or restore logon content information.  
Select the service to perform by specifying the corresponding keyword in the input  
rule-array. Only one service is performed for each call to this verb.  
If you log on to the adapter when you are already logged on, the existing logon  
session is replaced with a new session.  
Restrictions  
Format  
None  
CSUALCT  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
user_id  
auth_parms_length  
auth_parms  
auth_data_length  
auth_data  
Input  
Input  
Input  
In/Output Integer  
Input String  
String  
Integer  
String  
8 bytes  
auth_parms_length bytes  
auth_data_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
2-52 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Logon_Control  
Keyword  
Meaning  
Keywords used to log on  
LOGON  
Tells the Coprocessor that you want to log on. When you use  
the LOGON keyword, you must also use a second keyword,  
PPHRASE, to indicate how you will identify yourself to the  
Coprocessor.  
PPHRASE  
Specifies that you are going to identify yourself using a  
passphrase.  
Keywords used to log off  
LOGOFF  
FORCE  
Tells the Coprocessor you want to log off.  
Tells the Coprocessor that a specified user is to be logged off.  
The user's profile ID is specified by the user_id parameter.  
Keywords used to save and restore logon context information  
GET-CNTX  
Obtains a copy of the logon context information that is  
currently active in your session. See “Use of Logon Context  
Information” on page 2-8.  
PUT-CNTX  
Restores the logon context information that was saved using  
the GET_CNTX keyword. See “Use of Logon Context  
Information” on page 2-8.  
user_id  
The user_id parameter is a pointer to a string variable containing the ID string  
which identifies the user to the system. The user ID must be exactly eight  
characters in length. Shorter user IDs should be padded on the right with  
space characters.  
The user_id parameter is always used when logging on. It is also used when  
the LOGOFF keyword used in conjunction with the FORCE keyword to force a  
user off.  
auth_parms_length  
The auth_parms_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the auth_parms variable.  
On input, this variable contains the length (in bytes) of the auth_parms variable.  
On output, this variable contains the number of bytes of data returned in the  
auth_parms variable.  
auth_parms  
The auth_parms parameter is a pointer to a string variable containing data  
used in the authentication process.  
This field is used differently depending on the authentication method specified  
in the rule array.  
Keyword  
Contents of auth_parms field  
PPHRASE  
The authentication parameter field is empty. Its length is zero.  
auth_data_length  
The auth_data_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the auth_data variable.  
Chapter 2. CCA Node-Management and Access-Control 2-53  
Logon_Control  
CCA Release 2.54  
On input, this field contains the length (in bytes) of the auth_data variable.  
When no usage is defined for the auth_data parameter, set the length variable  
to zero.  
On output, this field contains the number of bytes of data returned in the  
auth_data variable.  
auth_data  
The auth_data parameter is a pointer to a string variable containing data used  
in the authentication process.  
This field is used differently depending on the keywords specified in the rule  
array.  
Rule-Array  
Keyword  
Contents of auth_data field  
PPHRASE and  
LOGON  
The authentication data field contains the user-provided  
passphrase.  
GET-CNTX  
The authentication data field receives the active logon context  
information. The size of the buffer provided for the auth_data  
field must be at least 256 bytes.  
PUT-CNTX  
The authentication data field contains your active logon  
context.  
Required Commands  
The Logon_Control verb requires the Force User Logoff of a Specified User  
command (offset X'011B') to be enabled in the hardware for use with the FORCE  
keyword.  
2-54 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Master_Key_Distribution  
Master_Key_Distribution (CSUAMKD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Master_Key_Distribution verb is used to perform these operations related to  
the distribution of shares of the master key:  
Generate and distribute a share of the current master-key  
Receive a master-key share. When sufficient shares are received, reconstruct  
the master key in the new master-key register.  
You choose which class of master key, either symmetric or asymmetric, to clone  
with the SYM-MK and the ASYM-MK rule-array keywords. If neither keyword is  
specified, the verb performs the same operation on both classes of registers,  
provided that the registers already contain the same values.  
OBTAIN and INSTALL rule-array keywords control the operation of the verb.  
With the OBTAIN keyword...  
You specify:  
– The share number, i, where 1 i 15 and i the maximum number of  
shares to be distributed as defined by the SET-MOFN option in the  
Cryptographic_Facility_Control verb  
– The private_key_name of the Coprocessor-retained key used to sign a  
generated master-key share. This key must have the CLONE attribute set  
at the time of key generation.  
– The certifying_key_name of the public key already registered in the  
Coprocessor used to validate the following certificate  
– The certificate and its length that provides the public key used to encrypt  
the clone_information_encrypting_key  
– The length and location of the clone_information field that will receive the  
encrypted cloning information (master-key share).  
The verb performs:  
– Generation of master-key shares, as required, and formatting of the  
information to be cloned  
– Signing of the cloning_information  
– Generation of an encryption key and encryption of the cloning information  
– Recovery and validation of the public key used to encrypt the  
clone_info_encrypting_key  
– Encryption of the clone_info_encrypting_key.  
The verb returns:  
– The encrypted cloning information  
– The encrypted clone_info_encrypting_key.  
With the INSTALL keyword...  
You specify:  
– The share number, i, presented in this request  
Chapter 2. CCA Node-Management and Access-Control 2-55  
Master_Key_Distribution  
CCA Release 2.54  
– The private_key_name of the Coprocessor-retained key used to decrypt the  
clone_info_encrypting_key. This key must have the CLONE attribute set at  
the time of key generation.  
– The certifying_key_name of the public key already registered in the  
Coprocessor used to validate the following certificate  
– The certificate and its length that provides the public key used to validate  
the signature on the cloning information  
– The length and location of the clone_info field that provides the encrypted  
cloning information (master-key share).  
The verb performs:  
– Recovery of the clone_info_encrypting_key  
– Decryption of the cloning information  
– Recovery and validation of the public key used to validate the cloning  
information signature  
– Validation of the cloning information signature  
– Retention of a master-key share  
– Regeneration of a master key in the new master-key register when  
sufficient shares have been received.  
The verb returns:  
– A return code valued to four if the master key has been recovered into the  
new master-key register. A return code of zero indicates that processing  
was normal, but a master key was not recovered into the new master-key  
register. (Other return codes, and various reason codes, can also occur in  
abnormal cases.)  
Restrictions  
Format  
When using the OBTAIN keyword, the current master-key register must be full.  
When using the INSTALL keyword, the new master-key register must be clear  
(empty).  
CSUAMKD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
share_index  
Input  
Input  
Input  
Input  
Input  
Integer  
String  
String  
Integer  
String  
private_key_name  
certifying_key_name  
certificate_length  
64 bytes  
64 bytes  
certificate  
certificate_length bytes  
clone_info_encrypting_key_length  
clone_info_encrypting_key  
In/Output Integer  
In/Output String  
clone_info_encrypting_key_length  
bytes  
clone_info_length  
clone_info  
In/Output Integer  
In/Output String  
clone_info_length bytes  
2-56 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Master_Key_Distribution  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Operation (one required)  
OBTAIN  
Generate and output a master-key share and other cloning  
information.  
INSTALL  
Receive a master-key share and other cloning information.  
Master-key choice (one, optional)  
SYM-MK  
Operate with the symmetric master-key registers.  
Operate with the asymmetric master-key registers.  
ASYM-MK  
share_index  
The share_index parameter is a pointer to an integer variable containing the  
index number of the share to be generated or received by the Coprocessor.  
private_key_name  
The private_key_name parameter is a pointer to a string variable containing the  
name of the Coprocessor-retained private key used to sign the cloning  
information (OBTAIN mode), or recover the cloning-information encrypting key  
(INSTALL mode).  
certifying_key_name  
The certifying_key_name parameter is a pointer to a string variable containing  
the name of the Coprocessor-retained public key used to verify the offered  
certificate.  
certificate_length  
The certificate_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the certificate variable.  
certificate  
The certificate parameter is a pointer to a string variable containing the  
public-key certificate that can be validated using the public key identified with  
the certifying_key_name variable.  
clone_info_encrypting_key_length  
The clone_info_encrypting_key_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
clone_info_encrypting_key variable.  
Chapter 2. CCA Node-Management and Access-Control 2-57  
Master_Key_Distribution  
CCA Release 2.54  
clone_info_encrypting_key  
The clone_info_encrypting_key parameter is a pointer to a string variable  
containing the encrypted key used to recover the cloning information.  
clone_info_length  
The clone_info_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the clone_info variable.  
clone_info  
The clone_info parameter is a pointer to a string variable containing the  
encrypted cloning information (master-key share).  
Required Commands  
The Master_Key_Distribution verb requires the following commands to be enabled  
based on the requested share-number, 1i15, and the use of either the OBTAIN  
or the INSTALL rule-array keyword:  
Clone-info Obtain command (offset X'0210'+share_index, for example, for  
share 10, X'021A')  
Clone-info Install command (offset X'0220'+share_index, for example, for  
share 12, X'022C').  
2-58 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Master_Key_Process  
Master_Key_Process (CSNBMKP)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Master_Key_Process verb operates on the three master-key registers: new,  
current, and old. Use the verb to:  
Clear the new and clear the old master-key registers  
Generate a random master-key value in the new master-key register  
Exclusive-OR a clear value as a key part into the new master-key register  
Set the master key which transfers the current master-key to the old master-key  
register, the new master-key to the current master-key register, and clear the  
new master-key register. SET also clears the master-key-shares tables.  
For IBM 4758 Cryptographic Coprocessor implementations, the master key is a  
triple-length, 168-bit, 24-byte value.  
You choose processing of the symmetric or asymmetric registers by specifying one  
of the SYM-MK and the ASYM-MK rule-array keywords. If neither keyword is  
specified, the verb performs the same operation on both classes of registers,  
provided that the registers already contain the same values.  
Before starting to load new master-key information, ensure that the new master-key  
register is cleared. Do this by using the CLEAR keyword in the rule array.  
To form a master key from key parts in the new master-key register, use the verb  
several times to complete the following tasks:  
Clear the register, if it is not already clear  
Load the first key part  
Load any middle key-parts, calling the verb once for each middle key_part  
Load the last key_part.  
You can remove a prior master-key from the Coprocessor with the CLR-OLD  
keyword. The contents of the old master-key register are removed and  
subsequently only current-master-key encrypted keys will be usable. If there is a  
value in the old master-key register, this master key can also be used to decrypt an  
enciphered working key.  
For symmetric master-keys, the low-order bit in each byte of the key is used as  
parity for the remaining bits in the byte. Each byte of the key part should contain  
an odd number of one bits. If this is not the case, a warning is issued. The  
product maintains odd parity on the accumulated symmetric master-key value.  
When the LAST master-key part is entered, this additional processing is performed:  
If any two of the eight-byte parts of the new master-key have the same value, a  
warning is issued. This warning should not be ignored and a key with this  
property should generally not be used.  
Chapter 2. CCA Node-Management and Access-Control 2-59  
Master_Key_Process  
CCA Release 2.54  
The master-key verification pattern (MKVP) of the new master-key is compared  
against the MKVP of the current and the old master-keys. If they are the  
same, the service fails with return code 8, reason code 704.  
If any of the eight-byte parts of the new master-key compares equal to one of  
the weak DES-keys, the service fails with return code 8, reason code 703. See  
page 2-62 for a list of these “weak” keys. (A parity-adjusted version of the  
asymmetric master-key is used to look for weak keys.)  
Except in the OS/400 environment, as part of the SET process, if a DES and/or  
PKA key-storage exists, the header record of each key storage is updated with the  
verification pattern of the (new) current master-key. The OS/400 environment does  
not have master-key verification records in the key-storage data set.  
Restrictions  
Format  
None  
CSNBMKP  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one, two, or three  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_part  
Input  
String  
24 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one,  
two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Cryptographic component (optional)  
ADAPTER Specifies the Coprocessor. This is the default for IBM 4758  
implementations.  
Master-key choice (one, optional)  
Meaning  
SYM-MK  
Operate with the symmetric master-key registers.  
Operate with the asymmetric master-key registers.  
ASYM-MK  
2-60 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Master_Key_Process  
Keyword  
Meaning  
Master-key process (one required)  
CLEAR  
Specifies to clear the new master-key register.  
Specifies to clear the old master-key register and set the  
CLR-OLD  
status for this register to empty.  
You can use the CLR-OLD keyword to cause the old  
master-key register to be cleared. The status response in the  
Cryptographic_Facility_Query verb, STATCCA, shows the  
condition of this register.  
FIRST  
Specifies to load the first key_part.  
MIDDLE  
Specifies to XOR the second, third, or other intermediate  
key_part into the new master-key register.  
LAST  
Specifies to XOR the last key_part into the new master-key  
register.  
RANDOM  
SET  
Causes generation of a random master-key value in the new  
master-key register.  
Specifies to advance the current master-key to the old  
master-key register, to advance the new master-key to the  
current master-key register, and to clear the new-master-key  
register.  
key_part  
The key_part parameter is a pointer to a string variable containing a 168-bit  
(3x56-bit, 24-byte) clear key-part that is used when you specify one of the  
keywords FIRST, MIDDLE, or LAST  
If you use the CLEAR, RANDOM, or SET keywords, the information in the  
variable is ignored, but you must declare the variable.  
Required Commands  
The Master_Key_Process verb requires the following commands to be enabled in  
the hardware:  
To process the symmetric master-keys, and also the asymmetric master-keys  
when neither master-key set is specified:  
– Clear New Master Key Register command (offset X'0032') with the  
CLEAR keyword  
– Clear Old Master Key Register command (offset X'0033') with the  
CLR-OLD keyword  
– Load First Master Key Part command (offset X'0018') with the FIRST  
keyword  
– Combine Master Key Parts command (offset X'0019') with the MIDDLE or  
LAST keyword  
– Generate Random Master Key command (offset X'0020') with the  
RANDOM keyword  
– Set Master Key command (offset X'001A') with the SET keyword.  
To process the asymmetric master-keys:  
– Clear New PKA Master Key Register command (offset X'0060') with the  
CLEAR keyword  
Chapter 2. CCA Node-Management and Access-Control 2-61  
Master_Key_Process  
CCA Release 2.54  
– Clear Old PKA Master Key Register command (offset X'0061') with the  
CLR-OLD keyword  
– Load First PKA Master Key Part command (offset X'0053') with the FIRST  
keyword  
– Combine PKA Master Key Parts command (offset X'0054') with the  
MIDDLE or LAST keywords  
– Generate Random PKA Master Key command (offset X'0120') with the  
RANDOM keyword  
– Set PKA Master Key command (offset X'0057') with the SET keyword.  
Related Information  
The following are considered questionable DES keys:  
ꢃ1 ꢃ1 ꢃ1 ꢃ1 ꢃ1 ꢃ1 ꢃ1 ꢃ1 /ᑍ weak ᑍ/  
FE FE FE FE FE FE FE FE /ᑍ weak ᑍ/  
1F 1F 1F 1F ꢃE ꢃE ꢃE ꢃE /ᑍ weak ᑍ/  
Eꢃ Eꢃ Eꢃ Eꢃ F1 F1 F1 F1 /ᑍ weak ᑍ/  
ꢃ1 FE ꢃ1 FE ꢃ1 FE ꢃ1 FE /ᑍ semi-weak ᑍ/  
FE ꢃ1 FE ꢃ1 FE ꢃ1 FE ꢃ1 /ᑍ semi-weak ᑍ/  
1F Eꢃ 1F Eꢃ ꢃE F1 ꢃE F1 /ᑍ semi-weak ᑍ/  
Eꢃ 1F Eꢃ 1F F1 ꢃE F1 ꢃE /ᑍ semi-weak ᑍ/  
ꢃ1 Eꢃ ꢃ1 Eꢃ ꢃ1 F1 ꢃ1 F1 /ᑍ semi-weak ᑍ/  
Eꢃ ꢃ1 Eꢃ ꢃ1 F1 ꢃ1 F1 ꢃ1 /ᑍ semi-weak ᑍ/  
1F FE 1F FE ꢃE FE ꢃE FE /ᑍ semi-weak ᑍ/  
FE 1F FE 1F FE ꢃE FE ꢃE /ᑍ semi-weak ᑍ/  
ꢃ1 1F ꢃ1 1F ꢃ1 ꢃE ꢃ1 ꢃE /ᑍ semi-weak ᑍ/  
1F ꢃ1 1F ꢃ1 ꢃE ꢃ1 ꢃE ꢃ1 /ᑍ semi-weak ᑍ/  
Eꢃ FE Eꢃ FE F1 FE F1 FE /ᑍ semi-weak ᑍ/  
FE Eꢃ FE Eꢃ FE F1 FE F1 /ᑍ semi-weak ᑍ/  
1F 1F ꢃ1 ꢃ1 ꢃE ꢃE ꢃ1 ꢃ1 /ᑍ possibly semi-weak ᑍ/  
ꢃ1 1F 1F ꢃ1 ꢃ1 ꢃE ꢃE ꢃ1 /ᑍ possibly semi-weak ᑍ/  
1F ꢃ1 ꢃ1 1F ꢃE ꢃ1 ꢃ1 ꢃE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 ꢃ1 1F 1F ꢃ1 ꢃ1 ꢃE ꢃE /ᑍ possibly semi-weak ᑍ/  
Eꢃ Eꢃ ꢃ1 ꢃ1 F1 F1 ꢃ1 ꢃ1 /ᑍ possibly semi-weak ᑍ/  
FE FE ꢃ1 ꢃ1 FE FE ꢃ1 ꢃ1 /ᑍ possibly semi-weak ᑍ/  
FE Eꢃ 1F ꢃ1 FE F1 ꢃE ꢃ1 /ᑍ possibly semi-weak ᑍ/  
Eꢃ FE 1F ꢃ1 F1 FE ꢃE ꢃ1 /ᑍ possibly semi-weak ᑍ/  
FE Eꢃ ꢃ1 1F FE F1 ꢃ1 ꢃE /ᑍ possibly semi-weak ᑍ/  
Eꢃ FE ꢃ1 1F F1 FE ꢃ1 ꢃE /ᑍ possibly semi-weak ᑍ/  
Eꢃ Eꢃ 1F 1F F1 F1 ꢃE ꢃE /ᑍ possibly semi-weak ᑍ/  
FE FE 1F 1F FE FE ꢃE ꢃE /ᑍ possibly semi-weak ᑍ/  
FE 1F Eꢃ ꢃ1 FE ꢃE F1 ꢃ1 /ᑍ possibly semi-weak ᑍ/  
Eꢃ 1F FE ꢃ1 F1 ꢃE FE ꢃ1 /ᑍ possibly semi-weak ᑍ/  
FE ꢃ1 Eꢃ 1F FE ꢃ1 F1 ꢃE /ᑍ possibly semi-weak ᑍ/  
Eꢃ ꢃ1 FE 1F F1 ꢃ1 FE ꢃE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 Eꢃ Eꢃ ꢃ1 ꢃ1 F1 F1 ꢃ1 /ᑍ possibly semi-weak ᑍ/  
1F FE Eꢃ ꢃ1 ꢃE FE F1 ꢃ1 /ᑍ possibly semi-weak ᑍ/  
1F Eꢃ FE ꢃ1 ꢃE F1 FE ꢃ1 /ᑍ possibly semi-weak ᑍ/  
ꢃ1 FE FE ꢃ1 ꢃ1 FE FE ꢃ1 /ᑍ possibly semi-weak ᑍ/  
1F Eꢃ Eꢃ 1F ꢃE F1 F1 ꢃE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 FE Eꢃ 1F ꢃ1 FE F1 ꢃE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 Eꢃ FE 1F ꢃ1 F1 FE ꢃE /ᑍ possibly semi-weak ᑍ/  
1F FE FE 1F ꢃE FE FE ꢃE /ᑍ possibly semi-weak ᑍ/  
Eꢃ ꢃ1 ꢃ1 Eꢃ F1 ꢃ1 ꢃ1 F1 /ᑍ possibly semi-weak ᑍ/  
FE 1F ꢃ1 Eꢃ FE ꢃE ꢃ1 F1 /ᑍ possibly semi-weak ᑍ/  
FE ꢃ1 1F Eꢃ FE ꢃ1 ꢃE F1 /ᑍ possibly semi-weak ᑍ/  
Eꢃ 1F 1F Eꢃ F1 ꢃE ꢃE F1 /ᑍ possibly semi-weak ᑍ/  
2-62 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Master_Key_Process  
FE ꢃ1 ꢃ1 FE FE ꢃ1 ꢃ1 FE /ᑍ possibly semi-weak ᑍ/  
Eꢃ 1F ꢃ1 FE F1 ꢃE ꢃ1 FE /ᑍ possibly semi-weak ᑍ/  
Eꢃ ꢃ1 1F FE F1 ꢃ1 ꢃE FE /ᑍ possibly semi-weak ᑍ/  
FE 1F 1F FE FE ꢃE ꢃE FE /ᑍ possibly semi-weak ᑍ/  
1F FE ꢃ1 Eꢃ Eꢃ FE ꢃ1 F1 /ᑍ possibly semi-weak ᑍ/  
ꢃ1 FE 1F Eꢃ ꢃ1 FE ꢃE F1 /ᑍ possibly semi-weak ᑍ/  
1F Eꢃ ꢃ1 FE ꢃE F1 ꢃ1 FE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 Eꢃ 1F FE ꢃ1 F1 ꢃE FE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 ꢃ1 Eꢃ Eꢃ ꢃ1 ꢃ1 F1 F1 /ᑍ possibly semi-weak ᑍ/  
1F 1F Eꢃ Eꢃ ꢃE ꢃE F1 F1 /ᑍ possibly semi-weak ᑍ/  
1F ꢃ1 FE Eꢃ ꢃE ꢃ1 FE F1 /ᑍ possibly semi-weak ᑍ/  
ꢃ1 1F FE Eꢃ ꢃ1 ꢃE FE F1 /ᑍ possibly semi-weak ᑍ/  
1F ꢃ1 Eꢃ FE ꢃE ꢃ1 F1 FE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 1F Eꢃ FE ꢃ1 Eꢃ F1 FE /ᑍ possibly semi-weak ᑍ/  
ꢃ1 ꢃ1 FE FE ꢃ1 ꢃ1 FE FE /ᑍ possibly semi-weak ᑍ/  
1F 1F FE FE ꢃE ꢃE FE FE /ᑍ possibly semi-weak ᑍ/  
FE FE Eꢃ Eꢃ FE FE F1 F1 /ᑍ possibly semi-weak ᑍ/  
Eꢃ FE FE Eꢃ F1 FE FE F1 /ᑍ possibly semi-weak ᑍ/  
FE Eꢃ Eꢃ FE FE F1 F1 FE /ᑍ possibly semi-weak ᑍ/  
Eꢃ Eꢃ FE FE F1 F1 FE FE /ᑍ possibly semi-weak ᑍ/  
Chapter 2. CCA Node-Management and Access-Control 2-63  
Random_Number_Tests  
CCA Release 2.54  
Random_Number_Tests (CSUARNT)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
The Random_Number_Tests verb invokes the USA NIST FIPS PUB 140-1  
specified cryptographic operational tests. These tests, selected by a rule-array  
keyword, consist of:  
For random numbers: monobit test, poker test, runs test, and long run test  
Known answer tests of DES, RSA, and SHA-1 processes.  
The tests are performed three times. If there is any test failure, the verb returns  
return code four and reason code one.  
Restrictions  
Format  
None  
CSUARNT  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Test selection (one required)  
FIPS-RNT  
KAT  
Perform the FIPS 140-1 specified test on the random number  
generation output.  
Perform the FIPS 140-1 specified known-answer tests on  
DES, RSA, and SHA-1.  
2-64 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Random_Number_Tests  
Required Commands  
None.  
Chapter 2. CCA Node-Management and Access-Control 2-65  
CCA Release 2.54  
2-66 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 3. RSA Key-Management  
This chapter describes the management of RSA public and private keys and how  
you can:  
Generate keys with various characteristics  
Import keys from other systems  
Protect and move a private key from one node to another.  
The verbs listed in Figure 3-1 are used to perform cryptographic functions and  
assist you in obtaining key-token data structures.  
Figure 3-1. Public-Key Key-Administration Services  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
PKA_Key_Generate  
PKA_Key_Import  
3-7  
Generates a public-private key-pair.  
Imports a public-private key-pair.  
CSNDPKG  
CSNDPKI  
CSNDPKB  
CSNDKTC  
E
E
S
E
3-11  
3-14  
3-22  
PKA_Key_Token_Build  
PKA_Key_Token_Change  
Builds a public-key-architecture (PKA) key-token.  
Reenciphers a private key from the old asymmetric  
master-key to the current asymmetric master-key.  
PKA_Public_Key_Extract  
3-24  
3-26  
3-28  
Extracts a public key from a public-private public-key  
token.  
CSNDPKX  
CSNDPKH  
CSNDPKR  
S
E
E
PKA_Public_Key_Hash_Register  
PKA_Public_Key_Register  
Registers the hash of a public key used later to verify an  
offered public key. See PKA_Public_Key_Register.  
Registers a public key used later to verify an offered  
public-key. Registration requires that a hash of the public  
key has previously been registered within the Coprocessor.  
See PKA_Public_Key_Hash_Register.  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
RSA Key-Management  
This implementation of CCA supports a set of public-key cryptographic services that  
are collectively designated PKA96. The PKA96 services support the RSA  
public-key algorithm and related hashing methods including MD5 and SHA-1.  
Figure 3-2 on page 3-2 shows the relationship among the services, the  
public-private key-token, and other data involved with supporting digital signatures  
and symmetric (DES) key exchange.  
These topics are discussed in this section:  
How to generate a public-private key pair  
How to import keys from other systems  
How to update a private key when the asymmetric master-key that protects a  
private key is changed  
How to use the keys and provide for private-key protection  
How to use a private key at multiple nodes  
How to register and retain a public key.  
Copyright IBM Corp. 1997, 2005  
3-1  
CCA Release 2.54  
────────────┬─────────────────  
┌───────ꢄ───────────┐  
│PKA_Key_Token_Build├┐  
└┬──────────────────┘│  
└──────┬───────┬────┘  
┌─────────┐  
│(Skeleton)  
│ ┌──────ꢄ───────┐  
│ │PKA_Key_Import├┐  
│ └┬─────────────┘│  
│ ┌─────ꢄ──────────┐  
│ │PKA_Key_Generate├┐  
│ └┬───────────────┘│  
│ └────┬───────────┘  
└─────┬────────┘  
└────────────────┐ │  
│ │  
┌───ꢄ──ꢄ───────ꢄ────────┐  
│ PKA96 PU─PR Key Token │  
Data  
──┬──  
PU: Clear  
┌──────ꢄ─────┐  
PR: eᑍMK(PR)  
or eᑍKEK(PR)  
or Clear  
│One_Way_Hash├┐  
└┬───────────┘│  
└─────┬──────┘  
└───────────┬───────────┘  
└────────────────────────────┬─────┴────────┬────────┐  
├────────────────┐  
┌────ꢄ───────ꢄ─────────────┐ │  
│Digital_Signature_Generate├┐ │  
└┬─────────────────────────┘│ │  
└───────────┬──────────────┘ │  
┌──────────ꢄ───────────┐ │  
│PKA_Public_Key_Extract├┐ │  
└┬─────────────────────┘│ │  
└─────────┬────────────┘ │  
┌──────────┐  
│eᑍMK.CV(K)│  
└─────┬────┘  
┌─────ꢄ─────┐  
│ Digital │  
│ Signature │  
└─────┬─────┘  
┌────────ꢄ───────┐  
│ PU Key Token │  
└────────┬───────┘  
(DES/CDMF│  
Key)  
┌───┴──────────────│──────┐  
┌────────────┘  
┌─────ꢄ───────────────ꢄ────┐  
│PKA_Symmetric_Key_Export │  
│PKA_Symmetric_Key_Generate├┐  
└┬─────────────────────────┘│  
└─────────┬────────────────┘  
┌──ꢄ─────────ꢄ───ꢄ───────┐  
│Digital_Signature_Verify├┐  
└┬───────────────────────┘│  
└───────────┬────────────┘  
yes/no  
┌────ꢄ────┐  
│ePU(K),CV│  
┌─────────────────┘  
│(Private key)  
└────┬────┘  
┌──────────ꢄ───────────ꢄ─┐  
│PKA_Symmetric_Key_Import├┐  
└┬───────────────────────┘│  
└─────────┬──────────────┘  
┌───────────────┐  
│Designates Verb├┐  
└┬──────────────┘│  
└───────────────┘  
┌─────ꢄ────┐  
│eᑍMK.CV(K)│  
┌───────────────┐  
│Data Structure │  
└───────────────┘  
└──────────┘  
(DES/CDMF Key)  
Figure 3-2. PKA96 Verbs with Key-Token Flow  
Key Generation  
You generate RSA public-private key-pairs using the PKA_Key_Generate verb.  
You specify certain facts about the desired key in a “skeleton key token” that you  
can create using the PKA_Key_Token_Build verb.  
When generating the key-pair you must determine:  
The key-length  
How, or if, the private key should be encrypted  
If the key should be retained within the Coprocessor, and if so, its name (label)  
The form of the private key: modular-exponent or Chinese Remainder  
A key name if access-control on the name will be employed  
Whether the key should be usable in symmetric key-exchange operations  
Whether the key should be usable in digital signature generation operations.  
3-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The PKA_Key_Generate verb either retains the generated private key within the  
Coprocessor, or the verb outputs the generated private key in one of three forms so  
you can control where the private key is deployed.  
You can request that the generated private key be retained within the secure  
cryptographic-engine through the use of the RETAIN keyword on the  
PKA_Key_Generate verb. In this case, only the public key is returned. You use  
the retained private key by referring to it with a key label which you specify in the  
key-name section of the skeleton key-token.  
If you do not retain the private key within the Coprocessor, you select how you wish  
to receive the private key:  
Cleartext  
Both the private and public keys are returned as cleartext. This option requires  
that you provide protection for the private key by means other than encryption  
within the key-generating step. This option is provided so the user can test, or  
interface with, other systems or applications that require the private key to be in  
the clear.  
Enciphered by the local master-key  
You can request that the key-generating service return the private key  
enciphered by the asymmetric master-key within the cryptographic engine.  
Since there is no service available to re-encrypt the private key other than by  
the current or a replacement master-key, the generated private key is  
effectively locked to the generating node, or other nodes that you establish with  
the same master key. (Generally these would be backup nodes or parallel  
nodes for greater throughput.)  
Enciphered by a transport key-encrypting-key  
You can request the service to encrypt the generated private key under either a  
DES IMPORTER key or a DES EXPORTER key. An IMPORTER key will  
permit the private key to be imported and used later at the generating node.  
Or, the key-encrypting key can be an EXPORTER transport key. An  
EXPORTER key is shared with one or more nodes. This allows you to  
distribute the key to another node(s). For example, you could obtain a private  
key in this form for distribution to a zSeries (S/390) large server's integrated  
RSA cryptographic processor.  
Note: EXPORTER and IMPORTER key-encrypting “transport” keys are  
discussed in Chapter 5, “DES Key-Management.”  
Because you can obtain the private key, it can be made functional on more than  
one cryptographic engine and used for backup or additional throughput. Your  
administration procedures control where the key can be used. The private key can  
be transported securely between nodes in its encrypted form. You can set up  
one-way key distribution channels between nodes and “lock” the receiving transport  
key-encrypting key to a particular node or nodes so that you can be certain where  
the private key exists. This ability to replicate a key to multiple nodes is especially  
important to high-throughput server systems and important for backup processing  
purposes.  
In systems with an access monitor like RACF on IBM zSeries servers, the key  
name that you associate with a private key gives you the ability to enforce  
Chapter 3. RSA Key-Management 3-3  
CCA Release 2.54  
restricted key usage. These systems can determine if a requesting process has  
the right to use the particular key name that is cryptographicly bound to the private  
key. You specify such a key name when you build the skeleton_key_token in the  
PKA_Key_Token_Build verb.  
For RSA keys, you decide if the key should be returned in modular-exponent form  
or in Chinese-Remainder-Theorem (CRT) form. Generally the CRT form performs  
faster in services that use the private key. This decision is represented by the form  
of the private key that you indicate in the skeleton_key_token. You can reuse an  
existing key-token having the desirable properties, or you can build the  
skeleton_key_token with the PKA_Key_Token_Build verb. Note that certain  
implementations such as the IBM zSeries (S/390) server CMOS Cryptographic  
Coprocessor feature (CCF) cannot employ a private key in the CRT form generated  
by the PKA_Key_Generate verb. (The PCICC feature on the zSeries does support  
use of the generated CRT key.)  
For RSA keys, you also decide if the public exponent should be valued to three,  
216+1, or fully random. Also, in the PKA_Key_Token_Build verb you can indicate  
that the key should be usable for both digital signature signing and symmetric key  
exchange (KEY-MGMT), or you can indicate that the key should be usable only for  
digital signature signing (SIG-ONLY), or only key decryption (KM-ONLY).  
The key can be generated as a random value, or the key can be generated based  
on a seed derived from regeneration data provided by the application program.  
You can also have a newly generated public key “certified” by a private key held  
within the Coprocessor. You can obtain a self-signature, and/or a signature(s) from  
another key. To obtain these signature/certificates, you must extend the skeleton  
key-token yourself as this support is not provided by the PKA_Key_Token_Build  
verb.  
The formats of the key tokens are described in “RSA PKA Key-Tokens” on  
page B-6. The key tokens are a concatenation of several “sections” with each  
section providing information pertaining to the key. All of the described formats can  
be input to the Version 2 support, but only selected formats are output by Version 2  
support.  
Key Import  
To be secure and useful in services, a private key must be enciphered by an  
asymmetric master-key on the CCA node where it will be used.1 You can use the  
PKA_Key_Import verb to get a private key deciphered from a transport key and  
enciphered by the asymmetric master-key. Also, you can get a clear  
(unenciphered) private key enciphered by the master key using the  
PKA_Key_Import verb.  
The public and private keys must be presented in a PKA external key-token (see  
“RSA PKA Key-Tokens” on page B-6). You can use the PKA_Key_Token_Build  
verb to structure the key into the proper token format.  
1
Of course a private key generated as a retained private-key is also secure, but in this case PKA_Key_Import does not apply.  
3-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
You provide or identify the operational transport key (key-encrypting key) and the  
encrypted private key with its associated public key to the import service. The  
service will return the private key encrypted under the current asymmetric  
master-key along with the public key.  
The Coprocessor is designed to generate and employ RSA CRT-form keys having  
p>q. If you import a private key having q>p, the key will be accepted. However,  
each time that you use such a key your application will incur substantial overhead  
to recalculate the inverse of the quantity U. (See Figure B-12 on page B-14 for  
the components of an RSA CRT key.)  
Reenciphering a Private Key Under an Updated Master-Key  
When the asymmetric master-key at a CCA node is changed, operational keys,  
such as RSA private keys enciphered by the master key, must be securely  
decrypted from under the preexisting master key and enciphered under the  
replacement master-key. You can accomplish this task using the  
PKA_Key_Token_Change verb.  
After the preexisting asymmetric master-key has become the old master-key and  
the replacement master-key has become the current master-key, you use the  
PKA_Key_Token_Change verb to effect the reencipherment of the private key.  
Using the PKA Keys  
The public-private keys that you create (generate) or import can be used in these  
services:  
For private keys:  
Digital_Signature_Generate  
PKA_Symmetric_Key_Import  
SET_Block_Decompose  
PKA_Decrypt  
Master_Key_Distribution  
For public keys:  
Digital_Signature_Verify  
PKA_Symmetric_Key_Export  
PKA_Symmetric_Key_Generate  
SET_Block_Compose  
PKA_Encrypt  
Master_Key_Distribution  
You must arrange appropriate protection for the private key. A CCA node can help  
ensure that the key will remain confidential. However, you must ensure that the  
master key and any transport keys are protected, for example, through  
split-knowledge, dual-control procedures. Or, you can choose to retain the private  
key in the secure cryptographic-engine.  
Besides the confidentiality of the private key, you must also ensure that only  
authorized applications can use the private key. You can hold the private key in  
application-managed storage and pass the key to the cryptographic services as  
required. This will generally limit the access other applications might have to the  
key. In systems with an access monitor, such as RACF on MVS systems, it is  
possible to associate a key name with the private key and have use of the key  
name authorized by the access monitor.  
Chapter 3. RSA Key-Management 3-5  
CCA Release 2.54  
Using the Private Key at Multiple Nodes  
You can arrange to use a private key at multiple nodes if the nodes have the same  
asymmetric master-key, or if you arrange to have the same transport key installed  
at each of the target nodes. In the latter case, you need to arrange to have the  
transport key under which the private key is enciphered installed at each target  
node.  
Having the private key installed at multiple nodes enables you to provide increased  
service levels for greater throughput, and to maintain operation when a primary  
node goes out of service. Of course, having a private key installed at more than  
one node increases the risk of someone misusing or compromising the key. You  
have to weigh the advantages and disadvantages as you design your system or  
systems.  
Extracting a Public Key  
CCA PKA key generation returns a public-private key-pair in a single key-token  
(provided your application is not retaining the private key within the Coprocessor).  
You can obtain a key token with only the public-key information using the  
PKA_Public_Key_Extract verb.  
If you use the public-private key token in verbs that only require the public key, the  
implementation may attempt to recover the private key which in the usual case  
would fail (since normally the private key should not be usable where use is being  
made of the public key).  
Registering and Retaining a Public Key  
You can use the PKA_Public_Key_Hash_Register and the  
PKA_Public_Key_Register verbs to “register” a public key in the secure  
cryptographic engine under dual-control. Authorize the related commands in two  
different roles to enforce a dual control policy. Your applications can subsequently  
reference the registered public key stored within the engine with the confidence that  
the key has been entered under dual control. Note that the  
Master_Key_Distribution verb makes use of registered RSA public keys in the  
master-key shares distribution scheme.  
3-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Generate  
PKA_Key_Generate (CSNDPKG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The PKA_Key_Generate verb is used to generate a public-private key-pair for use  
with the RSA algorithm.  
The skeleton_key_token specified to the verb determines the following  
characteristics of the generated key-pair:  
The key type: RSA  
The key length (modulus size)  
The RSA public-key exponent, valued to 3, 216+1, or random  
Any RSA private-key optimization (modulus-exponent versus “Chinese  
Remainder” form)  
Any signatures and signature-information that should be associated with the  
public key.  
The skeleton_key_token can be created using the PKA_Key_Token_Build verb.  
See page 3-14.  
|
|
|
|
|
|
Normally the output key is randomly generated. You may find it useful in testing  
situations to recreate the same key values. By providing “regeneration data,” a  
seed can be supplied so that the same value of the generated key can be obtained  
in multiple instances. Beginning with Release 2.53, you must enable the use of  
regeneration data with an additional command. See Required Commands for this  
verb. Of course you should not use regeneration data in production environments.  
The process for generating a particular key pair from regeneration data may vary  
between product implementations. Therefore, you should not rely on obtaining the  
same key-pair for a given regeneration-data string between products.  
The generated private-key can be returned in one of three forms:  
In cleartext form  
Enciphered by the CCA asymmetric master-key  
Enciphered by a transport key, either a DES IMPORTER or DES EXPORTER  
key-encrypting-key. If the private key is enciphered by an IMPORTER key, it  
can be imported to the generating node. If the private key is enciphered by an  
EXPORTER key, it can be imported to a node where the corresponding  
IMPORTER key is installed.  
Using the RETAIN rule-array keyword, you can cause the private key to be retained  
within the Coprocessor. You incorporate the key label by which you will later  
reference the newly generated key in the “key name” section of the skeleton  
key-token. (Later, you use this label to employ the key in verbs such as  
Digital_Signature_Generate, PKA_Symmetric_Key_Import, Master_Key_Distribution,  
SET_Block_Decompose, and PKA_Decrypt.) On output, the verb returns an  
external key-token containing the public key in the generated_key_identifier  
variable. The generated_key_identifier variable returned from the verb will not  
contain the private key.  
Chapter 3. RSA Key-Management 3-7  
PKA_Key_Generate  
CCA Release 2.54  
Note: When using the RETAINED key option, the key label supplied in the  
skeleton key-token references the key storage within the Coprocessor, and in this  
case must not reference a record in the host-system key-storage.  
The rule-array keyword CLONE flags a generated and retained RSA private key as  
usable in an engine “cloning” process. Cloning is a technique for copying sensitive  
Coprocessor information from one Coprocessor to another. (See “Understanding  
and Managing Master Keys” on page 2-12.)  
If you include a public-key certificate section within the skeleton key token, you  
cause the cryptographic engine to sign a certificate with the key that is designated  
in the public-key certificate signature subsection. Using this technique, you can  
cause the cryptographic engine to sign the newly generated public key using  
another key that has been retained within the engine, including the newly generated  
key (producing a “self-signature”). You can obtain more than one signature on the  
public key when you include multiple signature subsections in the skeleton key  
token. See “RSA Public-Key Certificate Section” on page B-17.  
Note: The verb will return a “section X'06'” private-key token format when you  
request a modulus-exponent internal key even though you have specified a type  
X'02' skeleton token.  
Restrictions  
1. Not all IBM implementations of CCA may support a CRT form of the RSA  
private key; check the product-specific literature. The IBM 4758 product family  
implementation supports an optimized RSA private key (a key in “Chinese  
Remainder” form). The formats vary between versions.  
2. See “RSA PKA Key-Tokens” on page B-6 for the formats used when  
generating the various forms of key token.  
3. When generating a key for use with ANSI X9.31 digital signatures, the  
modulus-length (key-length) must be one of 1024, 1280, 1536, 1792, or 2048  
bits.  
4. The key label used for a Retained key must not exist in the external key  
storage held on DASD.  
Format  
CSNDPKG  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
regeneration_data_length  
regeneration_data  
Input  
Input  
Integer  
String  
regeneration_data_length  
bytes  
skeleton_key_token_length  
skeleton_key_token  
Input  
Input  
Integer  
String  
skeleton_key_token_length  
bytes  
transport_key_identifier  
Input  
String  
64 bytes  
generated_key_identifier_length  
generated_key_identifier  
In/Output Integer  
In/Output String  
generated_key_identifier_length  
bytes  
3-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Generate  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Private-key encryption (one required)  
MASTER  
XPORT  
Enciphers the private key under the asymmetric master-key.  
The transport_key_token should specify a null key-token.  
Enciphers the private key under the IMPORTER or  
EXPORTER key-encrypting-key identified by the  
transport_key_token parameter.  
CLEAR  
RETAIN  
Returns the private key in cleartext.  
Returns the private key within the cryptographic engine and  
returns the public key in the generated_key_identifier variable.  
The name presented in the generated_key_identifier variable  
is used later to access the retained private key.  
Options (optional)  
CLONE  
Flags as usable a retained private RSA key in a cryptographic  
engine “cloning” operation. This keyword requires the  
RETAIN keyword to also be specified.  
regeneration_data_length  
The regeneration_data_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the regeneration_data variable. This  
must be a value of 0, or in the range 8 to 256, inclusive. If the value is 0, the  
generated keys will be based on a random-seed value. If this value is between  
8 and 256, the regeneration data will be hashed to form a seed value used in  
the key generation process to provide a means for recreating a public-private  
key pair.  
regeneration_data  
The regeneration_data parameter is a pointer to a string variable containing a  
value used as the basis for creating a particular public-private key pair in a  
repeatable manner. The regeneration data will be hashed to form a seed value  
used in the key generation process and provides a means for recreating a  
public-private key pair.  
skeleton_key_token_length  
The skeleton_key_token_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the skeleton_key_token variable. The  
maximum length is 2500 bytes.  
Chapter 3. RSA Key-Management 3-9  
PKA_Key_Generate  
CCA Release 2.54  
skeleton_key_token  
The skeleton_key_token parameter is a pointer to a string variable containing a  
skeleton key-token. This information provides the characteristics for the PKA  
key-pair to be generated. A skeleton key-token can be created using the  
PKA_Key_Token_Build verb.  
transport_key_identifier  
The transport_key_identifier parameter is a pointer to a string variable  
containing an internal key-encrypting-key token or a key label of an internal  
key-encrypting-key token, or a null key-token. If the XPORT rule_array  
keyword is not specified, this parameter should point to a null key-token.  
Otherwise, the specified key enciphers the private key and can be an  
IMPORTER or an EXPORTER key-type. Use an IMPORTER key to encipher a  
private key to be used at this node. Use an EXPORTER key to encipher a  
private key to be used at another node.  
generated_key_identifier_length  
The generated_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the generated_key_identifier  
variable. The maximum length is 2500 bytes. On output, and if the size is of  
sufficient length, the variable is updated with the actual length of the  
generated_key_identifier variable.  
generated_key_identifier  
The generated_key_identifier parameter is a pointer to a string variable  
containing either a key label identifying a key-storage record, or is other  
information that will be overwritten. If the key label identifies a key record in  
key storage, the generated key token will replace any key token associated  
with the label. If the first byte of the identified string does not indicate a key  
label (that is, not in the range X'20' to X'FE'), and the field is of sufficient  
length to receive the result, then the generated key token will be returned in the  
identified variable.  
When generating a RETAINed key, on output the verb returns the public-key  
key-token in this variable.  
Required Commands  
The PKA_Key_Generate verb requires the PKA Key Generate command (offset  
X'0103') to be enabled in the hardware.  
Also enable one of these commands in the hardware, depending on  
rule-array-keyword usage and the content of the skeleton key-token:  
With the CLONE rule-array keyword, the PKA Clone Key Generate command  
(offset X'0204')  
With the CLEAR rule-array keyword, the PKA Clear Key Generate command  
(offset X'0205')  
|
|
Beginning with Release 2.53, to generate the keys based on the value supplied in  
the regeneration_data parameter, you must enable one of these commands:  
|
|
|
|
When using the RETAIN keyword, enable the Permit Regeneration Data for  
Retain Keys command (offset X'027E')  
When not using the RETAIN keyword, enable the Permit Regeneration Data  
command (offset X'027D').  
3-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Import  
PKA_Key_Import (CSNDPKI)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The PKA_Key_Import verb is used to import a public-private key-pair. A private  
key must be accompanied by the associated public key. A source private-key may  
be in the clear or it may be enciphered.  
Generally you obtain the key token from the PKA_Key_Generate verb. If the key  
originates in a non-CCA system, you can use the PKA_Key_Token_Build verb to  
create the source_key_token.  
The verb will decipher the private key using the DES IMPORTER key identified by  
the transport_key_identifier when the source private-key is enciphered.  
Imported keys are returned in an internal target_key_identifier with the private key  
enciphered by the asymmetric master-key.  
Restrictions  
Not all IBM implementations of this verb may support an optimized form of the  
RSA private-key. Check the product-specific literature. The IBM 4758 product  
family implementation supports an optimized RSA private key (a key in  
“Chinese Remainder” form).  
With Version 2, a clear, external RSA private-key in modulus-exponent format  
is presented in a key section type X'02'. When imported, the enciphered  
private-key is returned in a X'06' type private-key key-token section.  
Not all IBM implementations of this verb support the use of a key label with the  
target-key identifier. Check the product-specific literature.  
Format  
CSNDPKI  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
source_key_token_length  
source_key_token  
Input  
Input  
Integer  
String  
source_key_token_length  
bytes  
transport_key_identifier  
target_key_identifier_length  
target_key_identifier  
Input  
In/Output Integer  
In/Output String  
String  
64 bytes  
target_key_identifier_length  
bytes  
Chapter 3. RSA Key-Management 3-11  
PKA_Key_Import  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array parameter is  
not presently used in this service, but must be specified.  
source_key_token_length  
The source_key_token_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the source_key_token variable. The  
maximum length is 2500 bytes.  
source_key_token  
The source_key_token parameter is a pointer to a string variable containing a  
PKA96 key-token. The key token must contain both public-key and private-key  
information. The private key can be in cleartext or it can be enciphered.  
transport_key_identifier  
The transport_key_identifier parameter is a pointer to a string variable  
containing either a key-encrypting-key token or a key label of a  
key-encrypting-key token, or a null key-token. This key will be used to decipher  
an encrypted private-key. The designated DES key must be an IMPORTER  
key-type with IMPORT capability enabled in its control vector.  
If the source key is not encrypted, a null key-token must be specified (the first  
byte of the key token must be X'00').  
target_key_identifier_length  
The target_key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the target_key_identifier variable.  
The maximum length is 2500 bytes. On output, and if the size is of sufficient  
length, the variable is updated with the actual length of the target_key_identifier  
variable.  
target_key_identifier  
The target_key_identifier parameter is a pointer to a string variable containing  
either a key label identifying a key-storage record, or is other information that  
will be overwritten with the imported key. If the key label identifies a key record  
in key storage, the returned key-token will replace any key token associated  
with the label. If the first byte of the identified string does not indicate a key  
label (that is, not in the range X'20' to X'FE'), and the field is of sufficient  
length to receive the result, then the key token will be returned in the identified  
variable.  
3-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Import  
Required Commands  
The PKA_Key_Import verb requires the PKA Key Import command (offset X'0104')  
to be enabled in the hardware.  
Chapter 3. RSA Key-Management 3-13  
PKA_Key_Token_Build  
CCA Release 2.54  
PKA_Key_Token_Build (CSNDPKB)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Token_Build verb constructs a public-key architecture (PKA)  
key-token from the supplied information.  
This verb is used to create the following:  
A skeleton_key_token for use with the PKA_Key_Generate verb  
A key token with a public key that has been obtained from another source  
A key token with a clear private-key and the associated public key.  
Other than a skeleton key-token prepared for use with the PKA_Key_Generate  
verb, every PKA key-token contains a public-key value. A token optionally contains  
a private-key value.  
See “RSA PKA Key-Tokens” on page B-6 for a description of the key token  
formats. With Version 2 software, you create RSA private-key tokens for section  
types:  
X'08' using the RSA-CRT keyword to obtain a token format for a key usable with  
the Chinese-Remainder Theorem (CRT) algorithm.  
X'02' using the RSA-PRIV keyword to obtain a token format for a key in  
modulus-exponent form  
X'04' using the RSA-PUBL keyword to obtain a token format for a public key.  
You specify:  
The token type:  
RSA-CRT for an RSA Chinese-Remainder Theorem token  
RSA-PRIV for an RSA modulus-exponent token  
RSA-PUBL for an RSA public-key only token.  
The usage limits for a private key:  
– If an RSA private-key may be allowed to import a symmetric key, and the  
key may also be used to create digital signatures, include the KEY-MGMT  
keyword in the rule array.  
– If a private key should be prevented from use in digital signature  
generation, include the KM-ONLY keyword in the rule array.  
– If an RSA private-key should be prevented from use in importing of DES  
keys, you may include the SIG-ONLY keyword in the rule array. This is the  
default.  
A key name when:  
– You need to specify the key-label for a retained private key in a skeleton  
key-token.  
– You are providing a key name for an access-control check in certain  
systems (i.e. for IBM eServer zSeries ICSF).  
3-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Token_Build  
Restrictions  
The RSA-OPT rule-array keyword is not supported with Version 2. Instead,  
use keyword RSA-CRT to obtain a X'08' private-key section type.  
The RSA key length is limited to the range of 512 to 2048 bits with specific  
formats restricted to 1024 bits maximum.  
When generating a key for use with ANSI X9.31 digital signatures, the  
modulus-length (key-length) must be one of 1024, 1280, 1536, 1792, or 2048  
bits.  
Format  
CSNDPKB  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_values_structure_length  
key_values_structure  
Input  
Input  
Integer  
String  
key_values_structure_length  
bytes  
key_name_length  
key_name  
reserved_1_length  
reserved_1  
reserved_2_length  
reserved_2  
reserved_3_length  
reserved_3  
reserved_4_length  
reserved_4  
reserved_5_length  
reserved_5  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
Integer  
String  
Integer  
String  
Integer  
String  
Integer  
String  
key_name_length bytes  
zero  
null  
zero  
null  
zero  
null  
zero  
null  
zero  
null  
token_length  
token  
In/Output Integer  
Output String  
token_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 3. RSA Key-Management 3-15  
PKA_Key_Token_Build  
CCA Release 2.54  
Keyword  
Meaning  
Token type (one required)  
RSA-CRT  
Create a key token for an RSA public-key and a key in  
Chinese-Remainder form.  
RSA-OPT  
RSA-PRIV  
Note: This keyword is not supported with Version 2 software.  
Create a key token for an RSA public and private key pair in  
modulus-exponent form.  
RSA-PUBL  
Create a key token for an RSA public-key in  
modulus-exponent form.  
RSA key-usage control (one, optional)  
SIG-ONLY  
KEY-MGMT  
KM-ONLY  
Selects a usage control to render the private key usable in  
digital-signature operations but not in (DES) key import  
operations. This is the default.  
Selects a usage control that allows an RSA private-key to be  
used in distribution of symmetric keys and in digital-signature  
services.  
Selects a usage control to render the private key usable in  
(DES) key-import operations but not in digital-signature  
operations.  
key_values_structure_length  
The key_values_structure_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the key_values_structure variable.  
The maximum length is 2500 bytes.  
key_values_structure  
The key_values_structure parameter is a pointer to a string variable containing  
a structure of the lengths and data for the components of the key or keys. The  
contents of this structure are shown in Figure 3-3, and sample data is  
described on page 3-19.  
3-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Token_Build  
Figure 3-3 (Page 1 of 2). PKA_Key_Token_Build Key-Values-Structure Contents  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
RSA key-values structure, modulus-exponent form (RSA-PRIV or RSA-PUBL)  
000  
002  
Length of the modulus in bits (512 to 1024 for RSA-PRIV, 512 to 2048  
for RSA-PUBL)  
002  
002  
Length of the modulus field, n, in bytes, “nnn.” This value must not  
exceed 256 for a 2048 bit-length key.  
This value should be zero when preparing a skeleton key token for use  
with the PKA_Key_Generate verb.  
004  
006  
002  
002  
Public exponent field length in bytes, “eee.”  
This value should be zero when preparing a skeleton key token to  
generate a random-exponent public key in the PKA_Key_Generate verb.  
This value must not exceed 256.  
Private exponent field length in bytes, “ddd.” This value can be zero  
indicating that private key information is not provided. This value must  
not exceed 256.  
2048  
; n=pq for prime p and prime q.  
008  
nnn  
eee  
Modulus, n, integer value, 1<n<2  
8+nnn  
Public exponent field, e, integer value, 1<e<n, e must be odd. When  
you are building a skeleton_key_token to control the generation of an  
RSA key pair, the public key exponent can be one of three values: 3,  
16  
65537 (2 +1), or 0 (zero) to indicate that a full-random exponent  
should be generated. The exponent field can be a null-length field  
when preparing a skeleton_key_token.  
-1  
8+nnn  
+eee  
ddd  
Private exponent, d, integer value, 1<d<n, d=e mod(p-1)(q-1).  
RSA key-values structure, Chinese Remainder form (RSA-CRT)  
000  
002  
002  
002  
Length of the modulus in bits (512 to 2048).  
Length of the modulus field, n, in bytes, “nnn.”  
This value can be zero if the key token will be used as a  
skeleton_key_token in the PKA_Key_Generate verb.  
This value must not exceed 256.  
004  
002  
Length of the public exponent field, e, in bytes: “eee.”  
This value should be zero when preparing a skeleton key token to  
generate a random-exponent public key in the PKA_Key_Generate verb.  
This value must not exceed 256.  
006  
008  
002  
002  
Reserved, binary zero.  
Length of the prime number field, p, in bytes: “ppp.” (Can be zero in a  
skeleton_key_token.) The maximum value of ppp+qqq is 256 bytes.  
010  
002  
002  
002  
002  
Length of the prime number field, q, in bytes: “qqq.” (Can be zero in a  
skeleton_key_token.) The maximum value of ppp+qqq is 256 bytes.  
012  
Length of the d field, in bytes: “rrr.” (Can be zero in a  
p
skeleton_key_token.) The maximum value of rrr+sss is 256 bytes.  
014  
Length of the d field, in bytes: “sss.” (Can be zero in a  
q
skeleton_key_token.) The maximum value of rrr+sss is 256 bytes.  
016  
Length of the U field, in bytes: “uuu.” (Can be zero in a  
skeleton_key_token.) The maximum length of U is 256 bytes.  
Note:  
All length fields are in binary  
All binary fields (exponents, lengths, and so forth) are stored with the high-order byte first  
(left, low-address, big endian, S/390 format).  
Chapter 3. RSA Key-Management 3-17  
PKA_Key_Token_Build  
CCA Release 2.54  
Figure 3-3 (Page 2 of 2). PKA_Key_Token_Build Key-Values-Structure Contents  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
018  
nnn  
eee  
Modulus, n.  
018  
Public exponent, e, integer value, 1<e<n, e must be odd.  
+nnn  
When you are building a skeleton_key_token to control the generation  
of an RSA key pair, the public key exponent can be one of the following  
values: 3, 65537 (2 +1), or 0 (zero) to indicate that a full-random  
16  
exponent should be generated. The exponent field can be a null-length  
field if the exponent value is zero.  
018  
+nnn  
+eee  
ppp  
qqq  
Prime number, p.  
Prime number, q.  
018  
+nnn  
+eee  
+ppp  
018  
rrr  
d
= d mod(p-1).  
= d mod(q-1)  
p
q
+nnn  
+eee  
+ppp  
+qqq  
018  
sss  
d
+nnn  
+eee  
+ppp  
+qqq  
+rrr  
-1  
018  
uuu  
U = q mod(p)  
+nnn  
+eee  
+ppp  
+qqq  
+rrr  
+sss  
Note:  
All length fields are in binary  
All binary fields (exponents, lengths, and so forth) are stored with the high-order byte first  
(left, low-address, big endian, S/390 format).  
key_name_length  
The key_name_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the optional key_name variable. If this variable  
contains zero, the key-name section is not included in the target token. If a key  
name is to be included, the value must be 64 for this verb.  
key_name  
The key_name parameter is a pointer to a string variable containing the name  
of the key. The name of the key can consist of the characters A...Z, 0...9, #, $,  
@, or period (.), and must begin with an alphabetic character. See “Key-Label  
Content” on page 7-2.  
reserved_x_length(s)  
The reserved_x_length parameters are each a pointer to an integer variable  
containing the number of bytes of data in the corresponding reserved_x  
variable. These variables are reserved for future use, and each variable should  
contain zero.  
3-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Token_Build  
reserved_x(s)  
The reserved_x parameters are each a pointer to a string variable that is  
reserved for future use. Each of the reserved_x parameters should contain a  
null pointer.  
token_length  
The token_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the token variable. On output, the variable contains  
the length of the token returned in the token variable. The maximum length is  
2500 bytes.  
token  
The token parameter is a pointer to a string variable containing the assembled  
token returned by the verb.  
Related Information  
Samples for the key_values_structure are shown below (and see the note following  
the examples).  
Chapter 3. RSA Key-Management 3-19  
PKA_Key_Token_Build  
CCA Release 2.54  
Token Type  
Modulus  
Length in  
Bits  
Public  
Exponent  
Key-Values Structure (Hexadecimal)  
Structure  
Length  
(Bytes)  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-CRT  
RSA-PRIV  
512  
Random  
(0)  
0200 0000 0000 0000 0000 0000 0000 0000 0000  
0200 0000 0001 0000 0000 0000 0000 0000 0000 03  
18  
19  
21  
18  
19  
21  
18  
19  
21  
18  
19  
21  
8
512  
3
512  
65537  
0200 0000 0003 0000 0000 0000 0000 0000 0000  
010001  
768  
Random  
(0)  
0300 0000 0000 0000 0000 0000 0000 0000 0000  
768  
3
0300 0000 0001 0000 0000 0000 0000 0000 0000 03  
768  
65537  
0300 0000 0003 0000 0000 0000 0000 0000 0000  
010001  
1024  
1024  
1024  
2048  
2048  
2048  
512  
Random  
(0)  
0400 0000 0000 0000 0000 0000 0000 0000 0000  
3
0400 0000 0001 0000 0000 0000 0000 0000 0000 03  
65537  
0400 0000 0003 0000 0000 0000 0000 0000 0000  
010001  
Random  
(0)  
0800 0000 0000 0000 0000 0000 0000 0000 0000  
3
0800 0000 0001 0000 0000 0000 0000 0000 0000 03  
65537  
0800 0000 0003 0000 0000 0000 0000 0000 0000  
010001  
Random  
(0)  
0200 0000 0000 0000  
RSA-PRIV  
RSA-PRIV  
RSA-PRIV  
512  
512  
768  
3
0200 0000 0001 0000 3  
0200 0000 0003 0000 010001  
0300 0000 0000 0000  
9
65537  
11  
8
Random  
(0)  
RSA-PRIV  
RSA-PRIV  
RSA-PRIV  
768  
768  
3
0300 0000 0001 0000 3  
0300 0000 0003 0000 010001  
0400 0000 0000 0000  
9
65537  
11  
8
1024  
Random  
(0)  
RSA-PRIV  
RSA-PRIV  
1024  
1024  
3
0400 0000 0001 0000 3  
9
65537  
0400 0000 0003 0000 010001  
11  
Note: All values in the key_values_structure must be stored in “big endian” format  
to ensure compatibility among different computing platforms. “Big endian” format  
specifies the high-order byte be stored at the low address in the field.  
Data stored by Intel architecture processors is normally stored in “little endian”  
format. “Little endian” format specifies the low-order byte be stored in the low  
address in the field.  
3-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Token_Build  
Required Commands  
None  
Chapter 3. RSA Key-Management 3-21  
PKA_Key_Token_Change  
CCA Release 2.54  
PKA_Key_Token_Change (CSNDKTC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Token_Change verb changes RSA private keys from encipherment  
with the old asymmetric master-key to encipherment with the current asymmetric  
master-key. You identify the task with the rule-array keyword, and the internal  
key-token to change with the key_identifier parameter.  
Note: This verb is similar in function to the CSNBKTC Key_Token_Change verb  
used with DES key tokens.  
Restrictions  
Format  
Certain implementations of CCA may not support this verb.  
CSNDKTC  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_identifier_length  
key_identifier  
In/Output Integer  
In/Output String  
key_identifier_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 3-4. PKA_Key_Token_Change Rule_Array Keywords  
Keyword  
Encipherment type (required)  
RTCMK Changes an RSA private key from encipherment with the old  
Meaning  
asymmetric master-key to encipherment with the current  
asymmetric master-key.  
3-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Token_Change  
key_identifier_length  
The key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the key_identifier variable. On  
output, the variable contains the length of the key token returned by the verb if  
a key token (not a key label) was specified. The maximum length is 2500  
bytes.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing an  
internal key-token or a key label of an internal key-token-record in key storage.  
The private key within the token is securely reenciphered under the current  
asymmetric master-key.  
Required Commands  
When you specify the reencipher option, the PKA_Key_Token_Change verb  
requires the Token Change command (offset X'0102') to be enabled in the  
hardware.  
Chapter 3. RSA Key-Management 3-23  
PKA_Public_Key_Extract  
CCA Release 2.54  
PKA_Public_Key_Extract (CSNDPKX)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Public_Key_Extract verb is used to extract a public key from a  
public-private key-pair. The public key is returned in a PKA public-key token.  
Both the public key and the related private key must be present in the source key  
token. The source private-key may be in the clear or may be enciphered.  
Restrictions  
Format  
None  
CSNDPKX  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
source_key_identifier_length  
source_key_identifier  
Input  
Input  
Integer  
String  
source_key_identifier_length  
bytes  
target_key_token_length  
target_key_token  
In/Output Integer  
Output String  
target_key_token_length  
bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array parameter is  
not presently used by this verb, but must be specified.  
source_key_identifier_length  
The source_key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the source_key_identifier variable.  
The maximum size that should be specified is 2500 bytes.  
source_key_identifier  
The source_key_identifier parameter is a pointer to a string variable containing  
either a key label identifying a PKA key-storage record or a PKA96 key-token.  
3-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Public_Key_Extract  
target_key_token_length  
The target_key_token_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the target_key_token variable. On  
output, the variable contains the length of the key token returned by the verb.  
The maximum length is 2500 bytes.  
target_key_token  
The target_key_token parameter is a pointer to a string variable containing the  
PKA96 public-key token returned by the verb.  
Required Commands  
None  
Chapter 3. RSA Key-Management 3-25  
PKA_Public_Key_Hash_Register  
CCA Release 2.54  
PKA_Public_Key_Hash_Register (CSNDPKH)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Public_Key_Hash_Register verb is used to register a hash value for a  
public key in anticipation of verifying the public key offered in a subsequent use of  
the PKA_Public_Key_Register verb.  
Restrictions  
Format  
None  
CSNDPKH  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
public_key_name  
hash_data_length  
hash_data  
Input  
Input  
Input  
String  
Integer  
String  
64 bytes  
hash_data_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Hash type (required)  
SHA-1  
The hash algorithm used to create the hash value.  
Special usage (optional)  
CLONE  
Indicates that the public key associated with this hash value  
can be employed in a CCA node-cloning process provided  
that this usage is confirmed when the public key is registered.  
public_key_name  
The public_key_name parameter is a pointer to a string variable containing the  
name under which the registered public-key will be accessed.  
3-26 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Public_Key_Hash_Register  
hash_data_length  
The hash_data_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the hash_data variable.  
hash_data  
The hash_data parameter is a pointer to a string variable containing the SHA-1  
hash of a public-key certificate that will be offered with the use of the  
PKA_Public_Key_Register verb. The format of the public-key certificate is  
defined in “RSA Public-Key Certificate Section” on page B-17.  
Required Commands  
The PKA_Public_Key_Hash_Register verb requires the Register PKA Public Key  
Hash command (offset X'0200') to be enabled in the hardware.  
Chapter 3. RSA Key-Management 3-27  
PKA_Public_Key_Register  
CCA Release 2.54  
PKA_Public_Key_Register (CSNDPKR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Public_Key_Register verb is used to register a public key in the  
cryptographic engine. Keywords in the rule array designate the subsequent  
permissible uses of the registered public key.  
The public key offered for registration must be contained in a token that contains a  
certificate section. The public key value contained in the certificate will be the key  
that is registered. A pre-registered hash value over the certificate section,  
exclusive of the certificate signature bits, is used to independently validate the  
offered key; see the PKA_Public_Key_Hash_Register verb and “RSA PKA  
Key-Tokens” on page B-6.  
Restrictions  
Format  
None  
CSNDPKR  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero or one  
rule_array_count * 8 bytes  
Integer  
String  
array  
public_key_name  
public_key_certificate_length  
public_key_certificate  
Input  
Input  
Input  
String  
Integer  
String  
64 bytes  
certificate_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero or  
one for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Special usage (optional)  
CLONE Indicates that the registered public-key can be employed in a  
Meaning  
CCA node cloning process provided that this usage was also  
asserted when the hash value was registered.  
3-28 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Public_Key_Register  
public_key_name  
The public_key_name parameter is a pointer to a string variable containing the  
name under which the registered public-key will be accessed.  
public_key_certificate_length  
The public_key_certificate_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the public_key_certificate variable.  
public_key_certificate  
The public_key_certificate parameter is a pointer to a string variable containing  
a public key to be registered. The public key must be presented in an RSA  
public-key certificate section; see “RSA Public-Key Certificate Section” on  
page B-17.  
Required Commands  
The PKA_Public_Key_Register verb requires the PKA Public Key Register  
command (offset X'0201') to be enabled in the hardware.  
If you specify the CLONE rule-array keyword, also enable the PKA Public Key  
Register with Cloning command (offset X'0202').  
Chapter 3. RSA Key-Management 3-29  
CCA Release 2.54  
3-30 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 4. Hashing and Digital Signatures  
This chapter discusses the data hashing and the digital signature techniques you  
can use to determine data integrity. A digital signature may also be used to  
establish the non-repudiation security property. (Another approach to data integrity  
based on DES message authentication codes is discussed in Chapter 6, “Data  
Confidentiality and Data Integrity.”)  
Data integrity and data authentication techniques enable you to determine that  
a data object (a string of bytes) has not been altered from some known state.  
Non-repudiation permits you to assert that the originator of a digital signature  
may not later deny having created the digital signature.  
This section explains how to determine the integrity of data. Determining data  
integrity involves determining whether individual values of a string of bytes have  
been altered. Two techniques are described:  
Digital signatures  
Hashing.  
Digital signatures use both hashing and public-key cryptography.  
Figure 4-1. Hashing and Digital Signature Services  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
Digital_Signature_Generate  
Digital_Signature_Verify  
MDC_Generate  
4-4  
4-7  
This verb generates a digital signature.  
This verb verifies a digital signature.  
CSNDDSG  
CSNDDSV  
CSNBMDG  
E
E
E
4-10  
This verb generates a hash using the Modification  
Detection Code (MDC) one-way function.  
One_Way_Hash  
4-13  
This verb generates a hash using any of the SHA-1, MD5,  
or RIPEMD160 one-way hashing functions.  
CSNBOWH  
S/E  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Hashing  
Data hashing functions have long been used to determine the integrity of a block of  
data. The application of a hash function to a data string produces a quantity called  
a hash value (also referred to as a hash, a message digest, or a “fingerprint”).  
Common hashing functions produce hash values of 128 or 160 bits. While many  
different strings supplied to a given hashing function will produce the same  
hash-value, it is computationally infeasible to determine a modification to a data  
string that will result in a desired hash-value.  
Hash functions for data integrity applications have a one-way property: given a  
hash value, it is highly improbable that a second data string can be found that will  
hash to the same value as the original. Consequently, if a hash value for a string  
is known, you can compute the hash value for another string suspected to be the  
same and compare the two hash values. If both hash values are identical, there is  
a very high probability that the strings producing them are identical.  
Copyright IBM Corp. 1997, 2005  
4-1  
CCA Release 2.54  
The CCA products support the following hash functions:  
Secure Hash Algorithm-1 (SHA-1) The SHA-1 is defined in FIPS 180-1 and  
produces a 20-byte, 160-bit hash value. The algorithm performs best on  
big-endian, general purpose computers. This algorithm is usually preferred over  
MD5 if the application designers have a choice of algorithms. SHA-1 is also  
specified for use with the DSS digital signature standard.  
RIPEMD-160 RIPEMD-160 is a 160-bit cryptographic hash function, designed by  
Hans Dobbertin, Antoon Bosselaers, and Bart Preneel. It is intended to be used  
as a secure replacement for the 128-bit hash functions MD4, MD5, and RIPEMD.  
RIPEMD was developed in the framework of the EU project RIPE (RACE  
Integrity Primitives Evaluation, 1988-1992).  
Message Digest-5 (MD5) MD5 is specified in the Internet Engineering Task Force  
RFC 1321 and produces (as with MDC) a 16-byte, 128-bit hash value. This  
algorithm performs best on little-endian (for example, Intel), general purpose  
computers.  
Modification Detection Code (MDC) The MDC is based on the DES algorithm and  
produces a 16-byte, 128-bit hash value. This hashing algorithm is considered  
quite strong. However, it performs rapidly only when supported by  
DES-hardware units specifically designed for MDC. See “Modification Detection  
Code (MDC) Calculation Methods” on page D-3 for a description of the MDC  
algorithm.  
There are many different approaches to data integrity verification. In some cases,  
you can simply make known the hash value for a data string. Anyone wishing to  
verify the integrity of the data would recompute the hash value and compare the  
result to the known-to-be-correct hash value.  
In other cases, you might want someone to prove to you that they possess a  
specific data string. In this case, you could randomly generate a challenge string,  
append the challenge string to the string in question, and hash the result. You  
would then provide the other party with the challenge string, ask them to perform  
the same hashing process, and return the hash value to you. This method forces  
the other party to re-hash the data. When the two hash values are the same you  
can be confidant that the strings are the same, and the other party actually  
possesses the data string, and not merely a hash value.  
The hashing services described in this chapter allow you to divide a string of data  
into parts, and compute the hash value for the entire string in a series of calls to  
the appropriate verb. This can be useful if it is inconvenient or impossible to bring  
the entire string into memory at one time.  
Digital Signatures  
You can protect data from undetected modification by including a  
proof-of-data-integrity value. This proof of data integrity value is called a digital  
signature, and relies on hashing (see “Hashing” above) and public-key  
cryptography.  
When you wish to sign some data you can produce a digital signature by hashing  
the data and encrypting the results of the hash (the hash value) using your private  
key. The encrypted hash value is called a digital signature.  
4-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Anyone with access to your public key can verify your information as follows:  
1. Hash the data using the same hashing algorithm that you used to create the  
digital signature.  
2. Decrypt the digital signature using your public key.  
3. Compare the decrypted results to the hash value obtained from hashing the  
data.  
An equal comparison confirms that the data they possess is the same as that which  
you signed. The Digital_Signature_Generate and the Digital_Signature_Verity  
verbs described in this chapter perform the hash encrypting and decrypting  
operations. Their requirements are as follows:  
No one else should have access to your private key, and the use of the key  
must be controlled so that someone else cannot sign data as though they were  
you.  
The verifying party must have your public key. They assure themselves that  
they do have your public key through the use of one-or-more certificates from  
one-or-more Certification Authorities.  
Note: The verification of public keys also involves the use of digital signatures;  
however, this subject is outside the scope of this manual.  
The value that is encrypted and decrypted using RSA public-key technology  
must be the same length in bits as the modulus of the keys. This bit-length is  
normally 512, 768, 1024, or 2048. Since the hash value is either 128 or 160  
bits in length, some process for formatting the hash into a structure for RSA  
encrypting must be selected.  
Unlike the DES algorithm, the strength of the RSA algorithm is sensitive to the  
characteristics of the data being encrypted. The digital signature verbs (Verify  
and Generate) support several different hash-value-formatting approaches.  
The rule-array keywords for the digital signature verbs contain brief descriptions  
of these formatting approaches:  
– ANSI X9.31  
– ISO 9796-1  
– PKCS #1 block type 00  
– PKCS #1 block type 01  
(RSA PKCS #1 v2.0 standard, RSASSA-PKCS1-v1_5)  
– Padding with zero bits.  
You can also validate a digital signature using the PKA_Encrypt verb (CSNDPKE,  
see page 5-75) with the ZERO-PAD option in Release 2.50 and later.1  
The receiver of data signed using digital signature techniques can, in some cases,  
assert non-repudiation2 of the data. The use of digital signatures in legally binding  
situations is gaining favor as commerce is increasingly conducted through  
networked communications. The techniques described in this chapter support the  
most common methods of digital signing currently in use.  
1
Release 2.50 currently applies only to the CCA implementation on the IBM eServer iSeries.  
2
Non-repudiation means that the originator of the digital signature cannot later deny having originated the signature and, therefore,  
the data.  
Chapter 4. Hashing and Digital Signatures 4-3  
Digital_Signature_Generate  
CCA Release 2.54  
Digital_Signature_Generate (CSNDDSG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Digital_Signature_Generate verb is used to generate a digital signature.  
You specify:  
The RSA private key  
For X9.31, the hash formatting method  
The hash value  
The address where the verb returns the digital signature.  
The hash quantity may be created through use of the One_Way_Hash or the  
MDC_Generate verbs.  
Restrictions  
A private key flagged as a key-management-only key (in private-key-section  
offset 50) is not usable in this verb. See page 3-14 and page 3-7.  
Not all IBM implementations of this verb may support an optimized form of the  
RSA private key, however, the IBM 4758 product family implementation of this  
verb does support an optimized RSA private key (“Chinese Remainder” form).  
Not all CCA implementations support each formatting method.  
The modulus-length (key-length) of a key used with ANSI X9.31 digital  
signatures must be one of 1024, 1280, 1536, 1792, or 2048 bits.  
Format  
CSNDDSG  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
PKA_private_key_identifier_length  
PKA_private_key_identifier  
In/Output Integer  
In/Output String  
exit_data_length bytes  
zero, one, or two  
Input  
Input  
Input  
Input  
Integer  
String array rule_array_count * 8 bytes  
Integer  
String  
PKA_private_key_identifier_length  
bytes  
hash_length  
hash  
Input  
Input  
Integer  
String  
hash_length bytes  
signature_field_length  
signature_bit_length  
signature_field  
In/Output Integer  
Output  
Output  
Integer  
String  
signature_field_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, or two.  
4-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Digital_Signature_Generate  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Digital-signature-hash formatting method (one, optional)  
X9.31  
Formats the hash according to the ANSI X9.31 standard and  
generates the digital signature.  
PKCS-1.1  
Calculates the digital signature on the string supplied in the  
hash variable as specified in the RSA Data Security, Inc.,  
Public Key Cryptography Standards #1 block type 01. The  
RSA PKCS #1 standard refers to this as  
RSASSA-PKCS1-v1_5 when you BER encode the hash as  
described under the second note to the hash parameter. See  
“PKCS #1 Formats” on page D-19.  
ISO-9796  
PKCS-1.0  
ZERO-PAD  
Formats the hash according to the ISO 9796-1 standard and  
generates the digital signature. This is the default. See  
“Formatting Hashes and Keys in Public-Key Cryptography” on  
page D-19.  
Calculates the digital signature on the string supplied in the  
hash variable as specified in the RSA Data Security, Inc.,  
Public Key Cryptography Standards #1 block type 00. See  
“PKCS #1 Formats” on page D-19.  
Places the supplied hash-value in the low-order bit positions  
of a bit-string of the same length as the modulus. Sets all  
non-hash-value bit positions to zero. Ciphers the resulting  
bit-string to obtain the digital signature.  
Hashing method specification  
When using X9.31 formatting, specify one.  
SHA-1  
Hash generated using the SHA-1 algorithm.  
Hash generated using the RIPEMD-160 algorithm.  
RPMD-160  
Notes:  
1. The hash for PKCS-1.1 and PKCS-1.0 should have been created using  
MD5 or SHA-1 algorithms.  
2. The hash for ISO-9796 and ZERO-PAD can be obtained by any hashing  
method.  
3. See “Formatting Hashes and Keys in Public-Key Cryptography” on  
page D-19 for a discussion of hash formatting methods.  
PKA_private_key_identifier_length  
The PKA_private_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
PKA_private_key_identifier variable. The maximum length is 2500 bytes.  
PKA_private_key_identifier  
The PKA_private_key_identifier parameter is a pointer to a string variable  
containing either a key label identifying a key-storage record or retained key, or  
an internal public-private key token.  
Chapter 4. Hashing and Digital Signatures 4-5  
Digital_Signature_Generate  
CCA Release 2.54  
hash_length  
The hash_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the hash variable.  
hash  
The hash parameter is a pointer to a string variable containing the information  
to be signed.  
Notes:  
1. For ISO-9796, the information identified by the hash parameter must be  
less than or equal to one-half of the number of bytes required to contain  
the modulus of the RSA key. Although ISO 9796-1 allows messages of  
arbitrary bit length up to one-half of the modulus length, this verb requires  
the input text to be a byte multiple up to the correct maximum length.  
2. For PKCS-1.0 or PKCS-1.1, the information identified by the hash  
parameter must be at least 11 bytes shorter than the number of bytes  
required to contain the modulus of the RSA key, and should be the ANS.1  
BER encoding of the hash value.  
You can create the BER encoding of an MD5 or SHA-1 value by  
prepending these strings to the 16-byte or 20-byte hash values,  
respectively:  
MD5  
X'3020300C 06082A86 4886F70D 02050500 0410'  
SHA-1  
X'30213009 06052B0E 03021A05 000414'  
3. For ZERO-PAD, the information identified by the hash parameter must be  
less than or equal to the number of bytes required to contain the modulus  
of the RSA key.  
4. See “Formatting Hashes and Keys in Public-Key Cryptography” on  
page D-19 for a discussion of hash formatting methods.  
signature_field_length  
The signature_field_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the signature_field variable. On  
output, if the size is sufficient, the variable contains the actual length of the  
digital signature returned by the verb. The maximum length is 256 bytes.  
signature_bit_length  
The signature_bit_length parameter is a pointer to an integer variable  
containing the number of bits of data of the digital signature returned in the  
signature_field variable.  
signature_field  
The signature_field parameter is a pointer to a string variable containing the  
stored digital signature. Unused bytes at the right of the field are undefined  
and should be ignored. The digital signature bit-field is in the low-order bits of  
the byte string containing the digital signature.  
Required Commands  
The Digital_Signature_Generate verb requires the Digital Signature Generate  
command (offset X'0100') to be enabled in the hardware.  
4-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Digital_Signature_Verify  
Digital_Signature_Verify (CSNDDSV)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Digital_Signature_Verify verb is used to verify a digital signature.  
Provide the digital signature, the public key, the hash formatting method, and the  
hash of the data to be validated. The hash quantity may be created through use of  
the One_Way_Hash or the MDC_Generate verbs.  
For RSA, the hash formatting method is selected through keywords in the rule  
array. The supplied hash information is formatted and compared to the public-key  
ciphered digital signature.  
If the digital signature is validated, the verb returns a return code of zero. If the  
digital signature is not validated, and there are no other problems, the verb returns  
a return code of 4 and reason code of 429 (decimal).  
Restrictions  
Format  
Not all CCA implementations support each formatting method.  
CSNDDSV  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero or one  
rule_array_count * 8 bytes  
Integer  
String  
array  
PKA_public_key_identifier_length  
PKA_public_key_identifier  
Input  
Input  
Integer  
String  
PKA_public_key_identifier_length  
bytes  
hash_length  
hash  
signature_field_length  
signature_field  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
hash_length bytes  
signature_field_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero or  
one.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 4. Hashing and Digital Signatures 4-7  
Digital_Signature_Verify  
CCA Release 2.54  
Keyword  
Meaning  
Digital-signature-hash formatting method (one, optional, for RSA)  
X9.31  
Format the hash according to the ANSI X9.31 standard and  
compare to the digital signature. See “Formatting Hashes and  
Keys in Public-Key Cryptography” on page D-19.  
PKCS-1.1  
Format the hash as specified in the RSA Data Security, Inc.,  
Public Key Cryptography Standards #1 block type 01 and  
compare to the digital signature. The RSA PKCS #1 standard  
refers to this as RSASSA-PKCS-v1_5 when you BER encode  
the hash as described under the second note to the hash  
parameter. See “PKCS #1 Formats” on page D-19.  
ISO-9796  
PKCS-1.0  
ZERO-PAD  
Format the hash according to the ISO 9796-1 standard and  
compare to the digital signature. This is the default. See  
“Formatting Hashes and Keys in Public-Key Cryptography” on  
page D-19.  
Format the hash as specified in the RSA Data Security, Inc.,  
Public Key Cryptography Standards #1 block type 00 and  
compare to the digital signature. See “PKCS #1 Formats” on  
page D-19.  
The supplied hash value is placed in the low-order bit  
positions of a bit-string of the same length as the modulus  
with all non-hash-value bit positions set to zero. After  
ciphering the supplied digital signature, the result is compared  
to the hash-extended bit string.  
Notes:  
1. The hash for PKCS-1.1 and PKCS-1.0 should have been created using  
MD5 or SHA-1 algorithms.  
2. The hash for ISO-9796 and ZERO-PAD can be obtained by any hashing  
method.  
PKA_public_key_identifier_length  
The PKA_public_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
PKA_public_key_identifier variable. The maximum length is 2500 bytes.  
PKA_public_key_identifier  
The PKA_public_key_identifier parameter is a pointer to a string variable  
containing either a key label identifying a key-storage record or a registered  
public-key, or a key token.  
hash_length  
The hash_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the hash variable.  
hash  
The hash parameter is a pointer to a string variable containing the hash  
information to be verified.  
4-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Digital_Signature_Verify  
Notes:  
1. For ISO-9796, the information identified by the hash parameter must be  
less than or equal to one-half of the number of bytes required to contain  
the modulus of the RSA key. Although ISO 9796-1 allows messages of  
arbitrary bit length up to one-half of the modulus length, this verb requires  
the input text to be a byte multiple up to the correct maximum length.  
2. For PKCS-1.0 or PKCS-1.1, the information identified by the hash  
parameter must be 11 bytes shorter than the number of bytes required to  
contain the modulus of the RSA key, and should be the ANS.1 BER  
encoding of the hash value.  
You can create the BER encoding of an MD5 or SHA-1 value by  
prepending these strings to the 16-byte or 20-byte hash values,  
respectively:  
MD5  
X'3020300C 06082A86 4886F70D 02050500 0410'  
SHA-1  
X'30213009 06052B0E 03021A05 000414'  
3. For ZERO-PAD, the information identified by the hash parameter must be  
less than or equal to the number of bytes required to contain the modulus  
of the RSA key.  
signature_field_length  
The signature_field_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the signature_field variable.  
signature_field  
The signature_field parameter is a pointer to a string variable containing the  
digital signature. The digital signature bit-field is in the low-order bits of the  
byte string containing the digital signature.  
Required Commands  
The Digital_Signature_Verify verb requires the Digital Signature Verify command  
(offset X'0101') to be enabled in the hardware.  
Chapter 4. Hashing and Digital Signatures 4-9  
MDC_Generate  
CCA Release 2.54  
MDC_Generate (CSNBMDG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
Use the MDC_Generate verb to create a 128-bit (16-byte) hash value on a data  
string whose integrity you intend to confirm. After using this verb to generate an  
MDC, you can compare the MDC to a known value or communicate the value to  
another entity so that they may compare the MDC hash value to one that they  
calculate.  
The MDC_Generate verb allows you to:  
Specify the two or four encipherment version of the algorithm  
Segment your text into a series of verb calls.  
You can also use the verb as a keyed hash algorithm. See the Related Information  
at the end of this verb description.  
Specifying Two or Four Encipherments: Four encipherments per round of the  
algorithm will improve security; two encipherments per round of the algorithm will  
improve performance. To specify the number of encipherments, use keywords  
MDC-2, MDC-4, PADMDC-2, or PADMDC-4 with the rule_array parameter. Two  
encipherments create results that differ from four encipherments; ensure that you  
use the same number of encipherments to verify the MDC.  
For a description of the MDC calculations, see “Modification Detection Code (MDC)  
Calculation Methods” on page D-3.  
Segmenting Text: The MDC_Generate verb lets you segment text into a series of  
verb calls. If you can present all of the data to be hashed in a single invocation of  
the verb, use the rule array keyword ONLY. You can segment your text and  
present the segments with a series of verb calls. Use the rule array keywords  
FIRST and LAST for the first and last segments. If you use more than two  
segments, use the rule array keyword MIDDLE for the additional segment(s).  
Between verb calls, the implementation stores unprocessed text data and  
intermediate information from the partial MDC calculation in the chaining_vector  
variable and the MDC key in the MDC variable. During segmented processing, the  
application program must not change the data in either of these variables.  
Restrictions  
When padding is requested (by specifying a process rule of PADMDC-2 or  
PADMDC-4 in the rule_array variable), a text length of zero is valid for any  
segment-control specified in the rule_array variable FIRST, MIDDLE, LAST, or  
ONLY). When LAST or ONLY is specified, the supplied text will be padded  
with X'FF' bytes and a padding count in the last byte to bring the total text  
length to the next multiple of 8 that is greater than or equal to 16.  
When no padding is requested (by specifying a process rule of MDC-2 or  
MDC-4 in the rule_array variable), the total length of text provided (over a  
single or segmented calls) must be at least 16 bytes and a multiple of 8 bytes.  
For segmented calls, a text length of zero is valid on any of the calls.  
4-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
MDC_Generate  
Format  
CSNBMDG  
return_code  
reason_code  
exit_data_length  
exit_data  
Input  
Input  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
text_length  
text  
rule_array_count  
rule_array  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
array  
text_length bytes  
rule_array_count * 8 bytes  
chaining_vector  
MDC  
In/Output String  
In/Output String  
18 bytes  
16 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
text_length  
The text_length parameter is a pointer to an integer variable containing the  
length (in bytes) of text to process.  
text  
The text parameter is a pointer to a string variable containing the text for which  
the verb calculates the MDC value.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule array. The value of the rule_array_count  
must be zero, one, or two for this verb.  
rule_array  
The rule_array parameter is a pointer to an array of keywords. The keywords  
are eight-bytes in length, and must be left-justified and padded on the right with  
space characters. The rule_array keywords are shown below:  
Figure 4-2 (Page 1 of 2). MDC_Generate Rule_Array Keywords  
Keyword  
Meaning  
Segmenting and Key Control (one, optional)  
ONLY  
Specifies that segmenting is not used and the default key is  
used. This is the default.  
FIRST  
Specifies the first segment of text, and use of the default key.  
MIDDLE  
Specifies an intermediate segment of text, or the first segment  
of text and use of a user-supplied key.  
LAST  
Specifies the last segment of text, or that segmenting is not  
used, and use of a user-supplied key.  
Chapter 4. Hashing and Digital Signatures 4-11  
MDC_Generate  
CCA Release 2.54  
Figure 4-2 (Page 2 of 2). MDC_Generate Rule_Array Keywords  
Keyword Meaning  
Algorithm Mode (one, optional)  
PADMDC-2  
PADMDC-4  
MDC-2  
Specifies two encipherments for each eight-byte block using  
PADMDC procedures.  
Specifies four encipherments for each eight-byte block using  
PADMDC procedures.  
Specifies two encipherments for each eight-byte block using  
MDC procedures. This is the default.  
Note: Use of the MDC-2 mode is not recommended.  
MDC-4  
Specifies four encipherments for each eight-byte block using  
MDC procedures.  
Note: Use of the MDC-4 mode is not recommended.  
Chaining_Vector  
The chaining_vector parameter is a pointer to an 18-byte string variable the  
security server uses as a work area to hold segmented data between verb  
invocations.  
Note: When segmenting text, the application program must not change the  
data in this string between verb calls to the MDC_Generate verb.  
MDC  
The MDC parameter is a pointer to a user-supplied MDC key or to a 16-byte  
string variable containing the MDC value. This value can be the key that the  
application program provides. This field is also used to hold the intermediate  
MDC result when segmenting text.  
Note: When segmenting text, the application program must not change the  
data in this string between verb calls to the MDC_Generate verb.  
Required Commands  
The MDC_Generate verb requires the Generate MDC command (offset X'008A')  
to be enabled in the hardware.  
Related Information  
The MDC_Generate verb uses a default key when you specify ONLY or FIRST  
keywords. If you want to use the MDC as a keyed-hash algorithm, place your key  
into the MDC variable and ensure that the chaining_vector variable is set to null (18  
bytes of X'00'). Then for a single segment of text, use the LAST keyword. For  
multiple segments of text, begin with the MIDDLE keyword and then proceed to use  
additional calls specifying MIDDLE as required and finally LAST; as with the default  
key, you must not alter the value of the MDC or chaining_vector variables between  
calls.  
4-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
One_Way_Hash  
One_Way_Hash (CSNBOWH)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The One_Way_Hash verb obtains a hash value from a text string using the MD5,  
SHA-1, or RIPEMD-160 hashing methods, as you specify in the rule_array.  
You can provide all of the data to be hashed in a single call to the verb, or you can  
provide the data to be hashed using multiple calls. Keywords that you supply in the  
rule_array inform the verb of your intention.  
For the SHA-1 hash process, the verb hashes text strings of 8192 bytes or longer  
using the Coprocessor hardware, with shorter text strings hashed by software in the  
host computer. It is faster to process short text strings in the host computer, while  
it is faster to process long strings in the Coprocessor.  
The SHA-1 method is specified in FIPS 180-1, May 31, 1994. The MD5 method is  
specified in RFC 1321, dated April 1992. The RIPEMD-160 method is an  
outgrowth of the EU project RIPE (RACE Integrity Primitives Evaluation); further  
information can be found on the Internet under “RIPEMD.”  
Note: Hashing can also be performed using the MDC_Generate verb  
(CSNCMDG) for the (MDC-2, MDC-4,) PADMDC-2, and PADMDC-4 methods.  
Restrictions  
Format  
If FIRST or MIDDLE calls are made, the text size must be a multiple of the  
algorithm block size: 64 bytes.  
This verb requires that text to be hashed be a multiple of eight bits aligned in bytes.  
Only data that is a byte multiple can be hashed. (These are not requirements of  
the standards.)  
CSNBOWH  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
text_length  
text  
chaining_vector_length  
chaining_vector  
hash_length  
hash  
Input  
Input  
Input  
In/Output String  
Input Integer  
In/Output String  
Integer  
String  
Integer  
text_length bytes  
128 bytes  
chaining_vector_length bytes  
16 or 20 bytes  
hash_length bytes  
Chapter 4. Hashing and Digital Signatures 4-13  
One_Way_Hash  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Hash method (one required)  
MD5  
Specifies the use of the MD5 method.  
SHA-1  
Specifies the use of the SHA-1 method.  
RPMD-160  
Specifies the use of the RIPEMD-160 method.  
Chaining control (one, optional)  
FIRST  
Specifies the first in a series of calls to compute the hash;  
intermediate results are stored in the hash variable.  
MIDDLE  
Specifies this is not the first nor the last in a series of calls to  
compute the hash; intermediate results are stored in the hash  
variable.  
LAST  
ONLY  
Specifies the last in a series of calls to compute the hash;  
intermediate results are retrieved from the hash variable.  
Specifies the only call made to compute the hash. This is the  
default.  
text_length  
The text_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the text variable. The maximum length on OS/400  
systems is 64MB - 64 bytes and on the other systems is 32MB - 64 bytes.  
Note: If FIRST or MIDDLE calls are made, the text size must be a multiple of  
the algorithm block-size.  
text  
The text parameter is a pointer to a string variable containing the data on which  
the hash value is computed.  
chaining_vector_length  
The chaining_vector_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the chaining_vector variable. The  
value must be 128 for this verb.  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing a  
work area used by this verb. Application programs must not alter the contents  
of this field between related FIRST, MIDDLE, and LAST calls.  
4-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
One_Way_Hash  
hash_length  
The hash_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the hash variable. This value must be at least 16  
bytes for MD5, and at least 20 bytes for SHA-1. The maximum length is 128  
bytes.  
hash  
The hash parameter is a pointer to a string variable containing the hash value  
returned by the verb. With use of the FIRST or MIDDLE keywords, the hash  
variable receives intermediate results.  
Required Commands  
Calculation of a SHA-1 hash with a text length greater than 8192 bytes requires the  
SHA-1 command (command offset X'0107') to be enabled in the hardware.  
Chapter 4. Hashing and Digital Signatures 4-15  
CCA Release 2.54  
4-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 5. DES Key-Management  
This chapter describes verbs to perform basic CCA DES key-management  
functions. Figure 5-1 lists the verbs covered in this chapter. Introductory material  
is presented under these topics:  
Understanding CCA DES Key-Management  
Control vectors, key types, and key-usage restrictions  
Key tokens, key labels, and key identifiers  
Using the key-processing and key-storage verbs  
Security precautions.  
Figure 5-1 (Page 1 of 2). Basic CCA DES Key-Management Verbs  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
Clear_Key_Import  
5-22  
Enciphers a clear key under the symmetric master-key,  
and updates or creates an internal key-token for a DATA  
key. (Also see Multiple_Clear_Key_Import.)  
CSNBCKI  
E
Control_Vector_Generate  
Control_Vector_Translate  
5-24  
5-26  
Builds a control vector from keywords.  
CSNBCVG  
CSNBCVT  
S
E
Changes the control vector associated with a key in an  
external key-token.  
Cryptographic_Variable_Encipher 5-29  
Encrypts modest quantities of data using a unique  
CSNBCVE  
E
key-class, CVARENC. The service is used to prepare the  
mask-array variable for the Control_Vector_Translate verb.  
Data_Key_Export  
5-31  
5-33  
5-35  
Exports a DES data-key and creates an external key-token  
that contains a null control vector.  
CSNBDKX  
CSNBDKM  
CSNBDKG  
E
E
E
Data_Key_Import  
Imports a DES data-key and creates an internal key-token  
for the key.  
Diversified_Key_Generate  
Generates a DES key based on supplied information and a  
key-generating key. The verb often finds use in generating  
keys for use with smart-cards.  
Key_Export  
5-42  
5-44  
Exports a DES key and creates an external key-token.  
CSNBKEX  
CSNBKGN  
E
E
Key_Generate  
Generates a random DES key or DES key pair, enciphers  
the keys, and updates or creates internal or external  
key-tokens.  
Key_Import  
Key_Part_Import  
Key_Test  
5-51  
5-54  
5-58  
Imports a DES key or a key-token, and updates an internal  
key-token or creates an internal key-token.  
CSNBKIM  
CSNBKPI  
CSNBKYT  
E
E
E
Combines clear key parts, enciphers the key, and updates  
an internal key-token.  
Generates or verifies a verification pattern for keys and key  
parts.  
Key_Token_Build  
5-61  
5-64  
Creates a DES key-token from supplied information.  
CSNBKTB  
CSNBKTC  
S
E
Key_Token_Change  
Reenciphers a DES key from the old symmetric  
master-key to the current symmetric master-key.  
Key_Token_Parse  
Key_Translate  
5-66  
5-69  
5-71  
Parses a DES key-token and provides the contents as  
individual variables.  
CSNBKTP  
CSNBKTR  
CSNBCKM  
S
E
E
Changes the encipherment of a key from one  
key-encrypting key to another key-encrypting key.  
Multiple_Clear_Key_Import  
Imports DES keys to form a double-length DES data-key.  
(Also see Clear_Key_Import.)  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Copyright IBM Corp. 1997, 2005  
5-1  
CCA Release 2.54  
Figure 5-1 (Page 2 of 2). Basic CCA DES Key-Management Verbs  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
PKA_Decrypt  
5-73  
Uses an RSA private-key to decrypt a symmetric key  
formatted in an RSA DSI PKCS #1 block type 2 structure  
and return the symmetric key in the clear.  
CSNDPKD  
E
PKA_Encrypt  
5-75  
Uses an RSA public-key to encrypt a clear symmetric-key  
in an RSA DSI PKCS #1 block type 2 structure and return  
the encrypted key.  
CSNDPKE  
E
Using the ZERO-PAD option, you can encipher information  
including a hash to validate digital signatures such as ISO  
9796-2.  
PKA_Symmetric_Key_Export  
PKA_Symmetric_Key_Generate  
5-78  
5-81  
Exports a symmetric key under an RSA public key.  
CSNDSYX  
CSNDSYG  
E
E
Generates a new DES key and returns one copy  
multiply-enciphered under the symmetric master-key or a  
DES key-encrypting key and another copy enciphered  
under an RSA public key.  
PKA_Symmetric_Key_Import  
Prohibit_Export  
5-86  
5-90  
5-91  
Imports a symmetric key under an RSA private key.  
Modifies a key so it can no longer be exported.  
Generates a random number.  
CSNDSYI  
CSNBPEX  
CSNBRNG  
E
E
E
Random_Number_Generate  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Understanding CCA DES Key-Management  
The DES algorithm operates on 64 data-bits at a time (eight bytes of 8-bit-per-byte  
data). The results produced by the algorithm are controlled by the value of a key  
that you supply. Each byte of the key contains 7 bits of key information plus a  
parity bit (the low-order bit in the byte). The parity bit is set so that there is an odd  
number of one bits for each key byte. The parity bits do not participate in the DES  
algorithm.  
The DES algorithm is not secret. However, by using a secret key, the algorithm  
can produce ciphertext that is impossible (for all practical purposes) to decrypt  
without knowing the secret key. The requirement to keep a key secret, and to have  
the key available at specific place(s) and time(s), produces a set of activities known  
collectively as key management.  
Because the secrecy and reliability of DES-based cryptography is strongly related  
to the secrecy, control, and use of DES keys, the following aspects of key  
management are important:  
Securing a cryptographic facility or process. The hardware provides a secure,  
tamper-resistant environment for performing cryptographic operations and for  
storing cryptographic keys in the clear. The hardware provides cryptographic  
functions as a set of commands that are selectively enabled under different  
roles. To activate a profile and its role to enable different hardware capabilities,  
users (programs or persons) must supply identification and a password for  
verification. Using these capabilities, you can control the use of sensitive  
key-management capabilities.  
Separating key types to restrict the use of each key. A user or a process  
should be restricted to performing only the processes that are required to  
accomplish a specific task. Therefore, a key should be limited to a set of  
5-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
functions in which it can be used. The cryptographic subsystem uses a system  
of control vectors1 to separate the cryptographic keys into a set of key types  
and restrict the use of a key. The subsystem enforces the use of a particular  
key type in each part of a cryptographic command. To control the use of a  
key, the control vector is combined with the key that is used to encipher the  
control vector's associated key. For example, a key that is designated a  
key-encrypting key cannot be employed in the decipher verb, thereby  
preventing the use of a key-encrypting key to obtain a cleartext key.  
Securely installing and verifying keys. Capabilities are provided to install keys,  
either in whole or in parts, and to determine the integrity of the key or the key  
part to ensure the accurate and secure entry of key information. The hardware  
commands and profiles allow you to enforce a split-knowledge, dual-control  
security policy in the installation of keys from clear information.  
Generating keys. The system can generate random clear and enciphered  
keys. The key-generation service creates an extensive set of key types for use  
in both CCA subsystems and other DES-based systems. Keys can be  
generated for local use and for distribution to remote nodes.  
Securely distributing keys manually and electronically. The system provides for  
unidirectional key-distribution channels and a key-translation service.  
Your application program(s) should provide procedures to perform the following  
key-management activities:  
Generating and periodically replacing keys. A key should be used for a very  
limited period of time. This may minimize the resulting damage should an  
adversary determine the value of a key.  
Archiving keys.  
Destroying keys and media used to distribute keys.  
Auditing the key generation, distribution, installation, archiving, and destruction  
processes.  
Reacting to unusual occurrences in the key-management process.  
Creating management controls for key management.  
Before a key is removed from a CCA cryptographic facility for storage in key  
storage or in application storage, the key is multiply-enciphered under a master key  
or another key-encrypting key. The master key is a triple-length DES key  
composed of three 56-bit DES keys. The first and the second parts of a master  
key (each 56-bit component) are required to be unique. For compatibility with other  
implementations, it is permissible for the third part to be the same as the first part,  
thus creating an effective “double-length” master-key.  
Key-encrypting keys, sometimes designated “transport keys,” are double-length  
DES keys composed of two halves, each half being a 56-bit DES key. The halves  
of a key-encrypting key can be the same value, in which case the key-encrypting  
key operates as though it were a single-length, 56-bit, DES key.  
1
A control vector is a logical extension of a key variant, which is a method of key separation that some other cryptographic systems  
use.  
Chapter 5. DES Key-Management 5-3  
CCA Release 2.54  
A key that is multiply-enciphered under the master key is an operational key (OP).  
The key is operational because a cryptographic facility can use the master key to  
multiply-decipher it to obtain the original key-value. A key that is  
multiply-enciphered under a key-encrypting key (other than the master key) is  
called an external key. Two types of external keys are used at a cryptographic  
node:  
An importable key (IM) is enciphered under an operational key-encrypting key  
(KEK) whose control vector provides key-importing authority.  
An exportable key (EX) is enciphered under an operational KEK whose control  
vector provides key-exporting authority.  
Control Vectors  
The CCA cryptographic commands form a complete, consistent, secure command  
set that performs within tamper-resistant hardware. The cryptographic commands  
use a set of distinct key types that provide a secure cryptographic system that  
blocks many attacks that can be directed against it.  
CCA implementations use a control vector to separate keys into distinct key types  
and to further restrict the use of a key. A control vector is a non-secret value that  
is carried in the clear in the key token along with the encrypted key that it specifies.  
A control vector is cryptographically associated with a key by being exclusive-ORed  
with a master key or another key-encrypting key to form a key that is used to  
multiply-encipher or multiply-decipher the key being associated with the control  
vector. This permanently binds the type and use of the key to the key. Any  
change to the original control vector would result in later recovering an altered  
key-value. If the control vector used to decipher a key is different from the control  
vector that was used to encipher the same key, the correct clear key cannot be  
recovered. The key-encipherment processes are described in detail at “CCA Key  
Encryption and Decryption Processes” on page C-12.  
After a key is multiply-enciphered, the originator of the key can ensure that the  
intended use of the key is preserved by giving the key-encrypting key only to a  
system that implements the CCA control vector design and that is managed by an  
audited organization.  
Key-encrypting keys in CCA are double-length keys. A double-length DES key  
consists of two (single-length) 56-bit DES keys that are used together as one key.  
The first half (left half) of a double-length key, and all of a single-length key, are  
multiply-enciphered using the exclusive-OR of the encrypting key and the control  
vector. The second half (right half) of a double-length key is multiply-enciphered  
using the exclusive-OR of the encrypting key and a modification of the control  
vector; the modification consists of the reversal of control vector bits 41 and 42.  
Appendix C, “CCA Control-Vector Definitions and Key Encryption” provides detailed  
information about the construction of a control-vector value and the process for  
encrypting a CCA DES key.  
5-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Checking a Control Vector Before Processing a Cryptographic  
Command  
Before a CCA cryptographic facility processes a command that uses a  
multiply-enciphered key, the facility’s logic checks the control vector associated with  
the key. The control vector must indicate a valid key type for the requested  
command, and any control-vector restriction (key-usage) bits must be set  
appropriately for the command. If the command permits use of the control vector,  
the cryptographic facility multiply-deciphers the key and uses the key to process the  
command. (Alteration of the control-vector value to permit use of the key in the  
command would result in recovery of a different, unpredictable key value.)  
Figure 5-2 shows the flow of cryptographic command processing in a cryptographic  
facility.  
At the CCA API...  
Verb─Call  
Key Token  
Data  
─────────────────  
─────────────────────────── ────────  
Cryptographic  
Control  
Enciphered  
Data  
Command  
Vector  
Key  
┌───────────────│──────────────────────│──────────────│─────────────│──────┐  
│Tamper  
┌──────────┐  
│Control  
│Resistant  
│Cryptographic ├────ꢁ│Vector  
│Facility  
│ ────┤  
│Checking │  
└──────────┘  
┌─────────┐  
│ Master Key────ꢁ│Exclusive│  
│ (or KEK)  
│─OR  
└────┬────┘  
┌─────────┐  
└────────ꢁ│Multiply │  
│Decipher │  
└────┬────┘  
Clear Key  
┌─────────┐ │  
└───────ꢁ│ Process │ │  
└─────────────────────────────────────────────ꢁ│  
│ │  
└────┬────┘ │  
└───────────────────────────────────────────────────────────────────│──────┘  
Result  
Figure 5-2. Flow of Cryptographic Command Processing in a Cryptographic Facility  
Key Types  
The CCA implementation in this product defines DES key-types as shown in  
Figure 5-3 on page 5-7. The key type in a control vector determines the use of  
the key, which verbs can use the key, and whether the cryptographic facility  
processes a key as a symmetric or “asymmetric” DES key. By differentiating keys  
with a control vector, a given key-value can be multiply-enciphered with different  
control vectors so as to impart different capabilities to copies of the key. This  
technique creates DES keys having an asymmetric property.  
Symmetric DES keys. A symmetric DES key can be used in two related  
processes. The cryptographic facility can interpret the following key types as  
symmetric:  
– CIPHER and DATA. A key with these key types can be used to both  
encipher and decipher data.  
– MAC. A key with this key type can be used to create a  
message-authentication code (MAC) and to verify a trial MAC.  
Chapter 5. DES Key-Management 5-5  
CCA Release 2.54  
Asymmetric DES keys. An asymmetric DES key is a key in a key pair in which  
the keys are used as opposites.  
– ENCIPHER and DECIPHER. Used to only encrypt data versus only to  
decrypt data.  
– MAC and MACVER. Used in generating (and verifying) a MAC versus only  
verifying a MAC.  
– PINGEN and PINVER. Used in generating (and verifying) a personal  
identification number (PIN) versus only verifying a PIN.  
– OPINENC and IPINENC. Used to only encrypt a PIN block versus only to  
decrypt a PIN block.  
Likewise these unusual key types are paired for other opposite purposes:  
– CVARENC and CVARXCVL  
– CVARENC and CVARXCVR.  
The cryptographic facility also interprets key-encrypting keys with the following  
key types as asymmetric keys that can be used to create one-way  
key-distribution channels:  
– EXPORTER or OKEYXLAT. A key with this key type can encipher a key at  
a node that “exports” a key.  
– IMPORTER or IKEYXLAT. A key with this key type can decipher a key at  
a node that “imports” the key.  
An EXPORTER key is paired with an IMPORTER or an IKEYXLAT key. An  
IMPORTER key is paired with an EXPORTER or an OKEYXLAT key. These  
key types permit the establishment of a unidirectional key-distribution channel  
which is important both to preserve the asymmetric capabilities possible with  
CCA-architecture systems, and to further secure a key-distribution system from  
unintended key-distribution possibilities.  
For information about generating key pairs, see “Generating Keys” on  
page 5-16.  
Depending on the key type, a key can be single or double in length. A  
double-length key that has different values in its left and right halves greatly  
increases the difficulty for an adversary to obtain the clear value of the enciphered  
quantity. A double-length key that has the same values in its left and right halves  
produces the same results as a single-length key and therefore has the strength of  
a single-length key. See Figure 5-3 on page 5-7.  
Some verbs can create a default control-vector for a key type. For information  
about the values for these control vectors, see Appendix C, “CCA Control-Vector  
Definitions and Key Encryption.”  
Key-Usage Restrictions  
In addition to a key type and subtype, a control vector contains key-usage values  
that further restrict the use of a key. Most key types define a default set of  
key-usage restrictions in a control vector. See Figure C-2 on page C-3.  
Key-usage restrictions can be varied by using keywords when constructing  
control-vector values using the Key_Token_Build verb or the  
Control_Vector_Generate verb, or by manually setting bits in the control vector.  
5-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure 5-4 on page 5-9 shows the key-type, key subtype, and key-usage keywords  
that can be combined in the Control_Vector_Generate verb and the  
Key_Token_Build verb to build a control vector. The left column lists the key types,  
the middle column lists the subtype keywords, and the right column lists the  
key-usage keywords that further define a control vector. Figure 5-5 on page 5-10  
describes the control-vector-usage keywords.  
For information about the control vector bits, see Appendix C, “CCA Control-Vector  
Definitions and Key Encryption.”  
Figure 5-3 (Page 1 of 2). Key Types and Verb Usage  
Key Type  
Usable with Verbs  
Cipher Class (Data Operation Keys)  
These keys are used to cipher text. In operational form and in external form, these keys  
are associated with a control vector.  
CIPHER  
Encipher, Decipher  
Encipher  
ENCIPHER  
DECIPHER  
Decipher  
MAC Class (Data Operation Keys)  
These keys are used to generate and verify a message-authentication code (MAC). In  
operational form and in external form, these keys are associated with a control vector.  
MAC  
MAC_Generate, MAC_Verify  
MAC_Verify  
MACVER  
DATA Class (Data Operation Keys)  
These keys are used to cipher text and to produce and verify message-authentication  
codes. In operational form, these keys are always associated with a control vector. In  
external form, the DATA key-type keys are not usually associated with a control vector.  
DATA  
Encipher, Decipher, MAC_Generate, MAC_Verify  
Encipher, Decipher  
DATAC  
DATAM  
DATAMV  
MAC_Generate, MAC_Verify  
MAC_Verify  
Secure Messaging Class (Data Operation Keys)  
These keys are used to encrypt keys or PINs. They are double-length keys. In  
operational form and in external form, these keys are associated with a control vector.  
SECMSG  
Diversified_Key_Generate  
Note: This key-type is added in release 2.30 in  
anticipation of additional verbs that employ the key  
type in a future release.  
Key-Encrypting-Key Class  
These keys are used to cipher other keys. They are double-length keys. In operational  
form and in external form, these keys are associated with a control vector.  
EXPORTER  
Data_Key_Export, Key_Export, Key_Generate,  
Key_Translate, Control_Vector_Translate  
IMPORTER  
Data_Key_Import, Key_Import, Key_Generate,  
Key_Translate, Control_Vector_Translate,  
Secure_Key_Import  
Chapter 5. DES Key-Management 5-7  
CCA Release 2.54  
Figure 5-3 (Page 2 of 2). Key Types and Verb Usage  
Key Type  
Usable with Verbs  
IKEYXLAT, OKEYXLAT  
PIN Class  
Key_Translate  
These keys are used in the various financial-PIN processing commands. They are  
double-length keys. In operational form and in external form, these keys are associated  
with a control vector.  
PINGEN  
Clear_PIN_Generate,  
Clear_PIN_Generate_Alternate,  
Encrypted_PIN_Generate,  
Encrypted_PIN_Generate_Alternate,  
Encrypted_PIN_Verify  
PINVER  
IPINENC  
Encrypted_PIN_Verify  
Clear_PIN_Generate_Alternate,  
Encrypted_PIN_Translate, Encrypted_PIN_Verify  
OPINENC  
Clear_PIN_Encrypt, Encrypted_PIN_Generate,  
Encrypted_PIN_Translate  
Key-Generating-Key Class  
These keys are used to derive keys. They are double-length keys.  
KEYGENKY  
Diversified_Key_Generate,  
Encrypted_PIN_Translate,  
Encrypted_PIN_Verify  
DKYGENKY  
Diversified_Key_Generate  
Cryptographic Variable Class  
These keys are used in the special verbs that operate with cryptographic variables and  
are single-length keys. In operational form and in external form, these keys are  
associated with a control vector.  
CVARENC  
CVARXCVL  
CVARXCVR  
Cryptographic_Variable_Encipher  
Control_Vector_Translate  
Control_Vector_Translate  
5-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
├─Key_Type─┤├─Key_Subtype─┤├─Key_Usage──────────────────────────────────────────────────────────────────────┤  
ꢁꢁ┬─MAC ─────┐  
Note: ANY is default  
├─MACVER───┴────────────────┬─────────┐  
├─DATA─────┐  
├─CIPHER───┤  
├─ENCIPHER─┤  
├─DECIPHER─┤  
├─CVARENC──┤  
├─CVARXCVL─┤  
├─ANY─────┤  
├─ANSIX9.9┤  
├─CVVKEY─A┤  
├─CVVKEY─B┤  
└─AMEX─CSC┴────────────┐  
Note: SINGLE  
is default  
├─CVARXCVR─┴───────────────────────────────────────┴─────────────────────┬──────────┐  
Note: DKYLꢃ  
is default  
Note: DMAC  
is default  
├─SINGLE───┤  
├─KEYLN8───┤  
├─DKYGENKY──┬─────────┐ ┌──┬─────────┐  
├─DOUBLE───┤  
├─DKYLꢃ───┤ │ ├─DMAC────┤  
├─DKYL1───┤ │ ├─DDATA───┤  
├─DKYL2───┤ │ ├─DMV─────┤  
├─DKYL3───┤ │ ├─DIMP────┤  
├─DKYL4───┤ │ ├─DEXP────┤  
├─DKYL5───┤ │ ├─DPVR────┤  
├─DKYL6───┤ │ ├─DMKEY───┤  
└─DKYL7───┴──┘ ├─DMPIN───┤  
├─KEYLN16──┤  
└─MIXED────┴─┐  
└─DALL────┴───────────────────────────────────┐  
├─SECMSG────────────────────┬─SMKEY───┐  
├─DATAC────┐  
├─DATAM────┤  
└─SMPIN───┴───────────────────────────────────┤  
├─DATAMV───┴──────────────────────────────────────────────────────────────┤  
├─KEYGENKY──────────────────┬─CLR8─ENC────────────────────────────────────┤  
├─IKEYXLAT─┐  
└─UKPT────────────────────────────────────────┤  
├─OKEYXLAT─┴─────────────────────────────────────────────────┐  
├─IMPORTER───────────────┬────Note 1────┐  
│ ┌──────────┐ │  
│ ꢄ │ │  
└──┬─OPIM────┤ │  
├─IMEX────┤ │  
├─IMIM────┤ │  
└─IMPORT──┴─┤  
├─EXPORTER───────────────┬────Note 1────┤  
│ ┌──────────┐ │  
│ ꢄ  
│ │  
└──┬─OPEX────┤ │  
├─IMEX────┤ │  
├─EXEX────┤ │  
└─EXPORT──┴─┴─────────┬────────┐ │ Note: ANY │  
└─XLATE──┴─┤ is default │  
├─PINVER─────────────────────────────────────────┐  
├──────────┐ │  
├─ANY──────┤ │  
├─NOT─KEK──┤ │  
├─DATA─────┤ │  
├─PIN──────┤ │  
└─LMTD─KEK─┴─┤  
├─PINGEN─────────────────┬────Note 1────┐  
│ ┌──────────┐ │  
│ ꢄ  
│ │  
└──┬─CPINGEN─┤ │  
├─CPINGENA┤ │  
├─EPINGEN─┤ │  
└─EPINVER─┴─┴────────┤  
│ Note: NO─SPEC  
├─IPINENC────────────────┬────Note 1─────┐  
│ ┌───────────┐ │  
│ is default  
├──────────┐  
├─NO─SPEC──┤  
├─IBM─PIN──┤  
│ ꢄ  
│ │  
└──┬─CPINGENA─┤ │  
├─EPINVER──┤ │  
├─REFORMAT─┤ │  
├─GBP─PIN──┴──┬──────────┤  
├─IBM─PINO─┐ └─NOOFFSET─┤  
└─TRANSLAT─┴─┴───┐  
└─OPINENC────────────────┬────Note 1─────┐  
│ ┌───────────┐ │  
├─GBP─PINO─┤  
├─VISA─PVV─┤  
└─INBK─PIN─┴─────────────┤  
│ ꢄ  
│ │  
└──┬─CPINENC──┤ │  
├─EPINGEN──┤ │  
├─REFORMAT─┤ │  
│ Note:  
│ DOUBLE  
│ is default│  
└─TRANSLAT─┴─┴───┴────────────────────────────┼──────────┐│  
├─DOUBLE───┤│  
Note 1: All keywords in the list below are  
├─KEYLN16──┤│ Note: XPORT─OK  
defaults unless one or more keywords  
in the list are specified.  
└─MIXED────┴┤ is default  
├──────────┐  
├─XPORT─OK─┤  
└─NO─XPORT─┴┬──────────┐  
└─KEY─PART─┴─ꢁꢁ  
Figure 5-4. Control_Vector_Generate and Key_Token_Build CV Keyword Combinations  
Chapter 5. DES Key-Management 5-9  
CCA Release 2.54  
Figure 5-5 (Page 1 of 3). Control Vector Key-Subtype and Key-Usage Keywords  
Keyword  
Meaning  
Key-Encrypting Keys  
OPIM  
IMPORTER keys that have a control vector with this attribute can  
be used in the Key_Generate verb when the key form is OPIM.  
IMEX  
IMPORTER and EXPORTER keys that have a control vector with  
this attribute can be used in the Key_Generate verb when the key  
form is IMEX.  
IMIM  
IMPORTER keys that have a control vector with this attribute can  
be used in the Key_Generate verb when the key form is IMIM.  
IMPORT  
OPEX  
IMPORTER keys that have a control vector with this attribute can  
be used to import a key in the Key_Import verb.  
EXPORTER keys that have a control vector with this attribute can  
be used in the Key_Generate verb when the key form is OPEX.  
EXEX  
EXPORTER keys that have a control vector with this attribute can  
be used in the Key_Generate verb when the key form is EXEX.  
EXPORT  
XLATE  
ANY  
EXPORTER keys that have a control vector with this attribute can  
be used to export a key in the Key_Export verb.  
IMPORTER and EXPORTER keys that have a control vector with  
this attribute can be used in the Key_Translate verb.  
Key-encrypting keys that have a control vector with this attribute  
can be used to transport any type of key.  
NOT-KEK  
DATA  
Key-encrypting keys that have a control vector with this attribute  
cannot be used to transport key-encrypting keys.  
Key-encrypting keys that have a control vector with this attribute  
can be used to transport keys with a key type of DATA, CIPHER,  
ENCIPHER, DECIPHER, MAC, and MACVER.  
PIN  
Key-encrypting keys that have a control vector with this attribute  
can be used to transport keys with a key type of PINVER,  
IPINENC, and OPINENC.  
Note: The PINGEN key cannot be transported by this type of  
KEK.  
LMTD-KEK  
Key-encrypting keys that have a control vector with this attribute  
can be used to exchange keys with key-encrypting keys that carry  
NOT-KEK, PIN, or DATA key-type ciphering restrictions.  
Data Operation Keys  
SMKEY  
Enable the encryption of keys in an EMV secure message.  
Enable the encryption of PINs in an EMV secure message  
SMPIN  
PIN Keys  
NO-SPEC  
The control vector does not require a specific PIN-calculation  
method.  
IBM-PIN  
Select the IBM 3624 PIN-calculation method.  
IBM-PINO  
Select the IBM 3624 PIN-calculation method with offset  
processing.  
GBP-PIN  
Select the IBM German Bank Pool PIN-calculation method.  
GBP-PINO  
Select the IBM German Bank Pool PIN-calculation method with  
institution-PIN input or output.  
5-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure 5-5 (Page 2 of 3). Control Vector Key-Subtype and Key-Usage Keywords  
Keyword  
Meaning  
VISA-PVV  
INBK-PIN  
NOOFFSET  
Select the VISA-PVV PIN-calculation method.  
Select the Interbank PIN-calculation method.  
Indicates that a PINGEN or PINVER key cannot participate in the  
generation or verification of a PIN when an offset or the VISA-PVV  
process is requested.  
CPINGEN  
CPINGENA  
EPINGEN  
EPINVER  
CPINENC  
REFORMAT  
The key can participate in the Clear_PIN_Generate verb.  
The key can participate in the Clear_PIN_Generate_Alternate verb.  
The key can participate in the Encrypted_PIN_Generate verb.  
The key can participate in the Encrypted_PIN_Verify verb.  
The key can participate in the Clear_PIN_Encrypt verb.  
The key can participate in the Encrypted_PIN_Translate verb in  
the Reformat mode.  
TRANSLAT  
The key can participate in the Encrypted_PIN_Translate verb in  
the Translate mode.  
Key-Generating Keys  
CLR8-ENC  
The key can be used to multiply-encrypt eight bytes of clear data  
with a generating key.  
DALL  
The key can be used to generate keys with the following key  
types: DATA, DATAC, DATAM, DATAMV, DMKEY, DMPIN,  
EXPORTER, IKEYXLAT, IMPORTER, MAC, MACVER,  
OKEYXLAT, and PINVER  
DDATA  
DEXP  
DIMP  
The key can be used to generate a single-length or double-length  
DATA or DATAC key.  
The key can be used to generate an EXPORTER or an  
OKEYXLAT key.  
The key can be used to generate an IMPORTER or an IKEYXLAT  
key.  
DMAC  
The key can be used to generate a MAC or DATAM key.  
DMKEY  
The key can be used to generate a SECMSG with SMKEY secure  
messaging key for encrypting keys.  
DMPIN  
The key can be used to generate a SECMSG with SMPIN secure  
messaging key for encrypting PINs.  
DMV  
The key can be used to generate a MACVER or DATAMV key.  
The key can be used to generate a PINVER key.  
DPVR  
DKYL0  
A DKYGENKY key with this subtype can be used to generate a  
key based on the key-usage bits.  
DKYL1  
DKYL2  
DKYL3  
DKYL4  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL0.  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL1.  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL2.  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL3.  
Chapter 5. DES Key-Management 5-11  
CCA Release 2.54  
Figure 5-5 (Page 3 of 3). Control Vector Key-Subtype and Key-Usage Keywords  
Keyword  
DKYL5  
Meaning  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL4.  
DKYL6  
DKYL7  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL5.  
A DKYGENKY key with this subtype can be used to generate a  
DKYGENKY key with a subtype of DKYL6.  
Key Lengths  
MIXED  
Indicates that the key can be either a replicated single-length key  
or a double-length key with two different, random eight-byte  
values.  
SINGLE  
KEYLN8  
Specifies the key as a single-length key.  
DOUBLE  
KEYLN16  
Specifies the key as a double-length key.  
Miscellaneous Attributes  
XPORT-OK  
NO-XPORT  
KEY-PART  
Permits the key to be exported by Key_Export or  
Data_Key_Export.  
Prohibits the key from being exported by Key_Export or  
Data_Key_Export.  
Specifies the control vector is for a key part.  
Key Tokens, Key Labels, and Key Identifiers  
In CCA, a cryptographic key is generally contained within a data structure called a  
key token. The key token can contain the key, a control vector, and other  
information pertinent to the key. Key tokens can be null, internal, or external.  
Internal key-tokens can be stored in key storage and are accessed using a key  
label. The CCA API generally permits an application to provide either a key token  
or a key label, in which case the parameter description is designated a key  
identifier. Key tokens, key labels, and key identifiers are discussed in the following  
sections.  
Key Tokens  
The security API operates with a key token rather than operating simply with a key.  
A DES key-token is a 64-byte data structure that can contain the key and other  
information frequently needed with the key.  
Figure 5-6 on page 5-13 shows the general format of a key token. For more  
information, see Appendix B, “Data Structures.”  
5-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
8
16  
32  
6ꢃ 63  
┌─────────┬─────────┬──────────────┬──────────────┬──────────────┬───────────┬─────┐  
│Key-  
│Token  
│Type  
│Flags  
│Control Infor-│ Internal Key │Control Vector│  
│ TVV │  
│mation for  
or  
│Using the Key │ External Key │  
└─────────┴─────────┴──────────────┴──────────────┴──────────────┴───────────┴─────┘  
Miscellaneous control information: token type (null, internal, or external),  
token version layout, and other information.  
The key value (multiply-enciphered under a key formed by either  
the master key or a key-encrypting key that is exclusive-ORed with the  
control vector).  
The control vector for the key provides information about the permitted  
uses of the key.  
A token-validation value (TVV), which is a checksum that is used to  
validate a token.  
Figure 5-6. Key_Token Contents  
You can use the Key_Token_Build verb to assemble a key token or use the  
Key_Token_Parse verb to disassemble a key token. You can also use application  
code to assemble or disassemble a key token. You should keep in mind, however,  
that the contents and format of key tokens are version and implementation  
sensitive. Key-token formats are described in Appendix B, “Data Structures” on  
page B-1.  
The cryptographic system uses key labels and external, internal, and null  
key-tokens, as shown in Figure 5-7.  
External Key_Token  
63  
┌──────────┬──────────────┬──────────────────────┐  
┌────────ꢁX'ꢃ2'  
│ eᑍKEK.CV(KEY)│  
└──────────┴──────────────┴──────────────────────┘  
Internal Key_Token  
63  
┌──────────┬──────────────┬──────────────────────┐  
OR ───────ꢁX'ꢃ1'  
│ eᑍKM.CV(KEY) │  
└──────────┴──────────────┴──────────────────────┘  
Key_Identifier───────ꢁ  
Null Key_Token  
63  
┌──────────┬──────────────┬──────────────────────┐  
OR ───────ꢁX'ꢃꢃ'  
└──────────┴──────────────┴──────────────────────┘  
Key_Label  
63  
┌────────────────────────────────────────────────┐  
└────────ꢁName_Token_1.Name_Token_2. -- .Name_Token_n  
└───────────────────────┬────────────────────────┘  
──┐ ꢂ  
The first byte is│ │  
in the range of ├──┘  
X'2ꢃ' to X'FE'. │  
──┘  
Key Storage ┌──ꢄ────────┐  
│ ─── ───── │  
│ ─── ───── │  
│ ─── ───── │  
│ ─── ───── │  
│ ─── ───── │  
│ ─── ───── │  
└──ꢂ───ꢂ────┘  
Key_Label─┘  
└─Internal Key_Token  
Figure 5-7. Use of Key Tokens and Key Labels  
Chapter 5. DES Key-Management 5-13  
CCA Release 2.54  
External Key-Token: An external key-token contains an external key that is  
multiply-enciphered under a key formed by the exclusive-OR of a key-encrypting  
key and the control vector that was assigned when the key token was created or  
updated.  
An external key-token is specified in a verb call using a key_token parameter. An  
external key-token resides in application storage. An application program can  
obtain an external key-token by calling one of the following verbs:  
Control_Vector_Translate  
Data_Key_Export  
Key_Export  
Key_Generate  
Key_Token_Build  
Key_Translate.  
Internal Key-Token: An internal key-token contains an operational key that is  
multiply-enciphered under a key formed by the exclusive-OR of a symmetric  
master-key and the control vector that was used when the key token was created  
or updated.  
An internal key-token is specified in a cryptographic verb call by using a  
key_identifier parameter. These verbs produce an internal key-token:  
Clear_Key_Import  
Data_Key_Import  
Diversified_Key_Generate  
Key_Generate  
Key_Import  
Key_Part_Import  
Key_Record_Read  
Key_Token_Build  
Prohibit_Export  
Symmetric_Key_Import.  
Null Key-Token: A null key-token is a 64-byte string that begins with the value  
X'00'. A null key-token can reside in application storage or in key storage. Some  
verbs that create a key token with default values do so when you identify a null  
key-token.  
Key Labels  
A key label serves as an indirect address for a key-token record in key storage.  
The security server uses a key label to access key storage to retrieve or to store  
the key token. A key_identifier parameter can point to either a key label or a key  
token. Key labels are discussed further at “Key-Label Content” on page 7-2.  
Key Identifiers  
When a verb parameter is described as some form of a key_identifier, you can  
present either a key token or a key label. The key label identifies a key-token  
record in key storage.  
5-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Using the Key-Processing and Key-Storage Verbs  
Figure 5-8 on page 5-16 shows key-processing and key-storage verbs and how  
they relate to key parts, internal and external key-tokens, and key storage. You  
can create keys in your application programs by using the  
Multiple_Clear_Key_Import, Diversified_Key_Generate, Key_Generate,  
Key_Part_Import, Clear_Key_Import, and Random_Number_Generate verbs.  
CCA subsystems do not reveal the clear value of enciphered keys, and do provide  
significant control over encrypted keys. Simple key-distribution is addressed by the  
Cryptographic Node Management (CNM) utility’s capabilities to read and write  
encrypted keys from and to key storage and to process key parts with support for  
dual control of the key parts. Application programs can use the key processing and  
storage verbs to implement a key-distribution system of your design.  
The CNM utility, Key_Part_Import, Clear_Key_Import, Multiple_Clear_Key_Import,  
and Key_Test verbs allow you to install keys and verify key installation.  
Installing and Verifying Keys  
To keep a key secret, it can be installed as a series of key parts. Different  
individuals can use an application program that loads individual key parts into the  
cryptographic facility using the Key_Part_Import verb, or the Cryptographic Node  
Management utility to enter a key part from a keyboard or diskette.  
The key parts are single or double in length, based on the type of key you are  
accumulating. Key-parts are exclusive-ORed as they are accumulated. Thus,  
knowledge of a key-part value provides no knowledge about the final key when it is  
composed of more than one part. An already-entered key-part(s) is stored outside  
the cryptographic facility enciphered under the symmetric master-key. When all the  
key parts are accumulated, the key-part bit is turned off in the key's control vector.  
A master-key key-part is loaded into the new master-key register. The key part  
replaces the value in the new master-key register, or is exclusive-ORed with the  
existing contents of the register. In a separate command, you can copy the  
contents of the current master-key register to the old master-key register and write  
over the current master-key register with the contents of the new master-key  
register.  
The commands to load (master) key parts must be individually authorized by  
appropriate bits being turned on in the active role for the Load First (Master) Key  
Part command or the Load and Combine (Master) Key Part command.  
You can use the Key_Test verb to generate a verification pattern. The verification  
pattern can then be used to determine the equivalence of another key or a key  
part. An application program can use the Key_Test verb to verify the contents of a  
key register, an enciphered key, or an enciphered key-part. The CNM utility also  
includes services to generate and use key and key-part verification patterns.  
Though you do not know the value of the key or the key part, you can test a key  
register, key, or key part to ensure it has a correct value. You can provide the  
verification information to the individual who loads the key part(s) for the parts that  
should already be loaded. If the pattern does not verify, you can instruct the  
individual or application not to load an additional key part or not to set the master  
key. This procedure can ensure that only valid key-parts are used.  
Chapter 5. DES Key-Management 5-15  
CCA Release 2.54  
Random_Number_Generate  
Diversified_Key_Generate  
┌────┴────┐  
Clear_Key_  
Key_Part_ Import  
Import  
┬ ┌───────────────────┘  
│ │  
│ │  
┌─────────────────┐ ┬  
│ │  
┌────┐  
│K │  
Symmetric_Key_Import ┌─ꢄ──ꢄ─────────ꢄ──ꢄ─┐  
│Internal Key─Token ├─────ꢁKey_Record_Write├─ꢁe S │  
─────┤Key_Record_Read ──┤y t │  
┌──────┴───────────┐ │  
│RSA─enciphered─key│ └─┬ꢂ─ꢂ────┬────ꢂ────┘  
│ o │  
│ r │  
└───ꢂ──ꢂ───────────┘  
││ │  
││ │  
││ │  
││ │  
┴ ┴  
Key_Record_Create├───ꢁ a │  
Key_Record_Delete├───ꢁ g │  
Key_Record_List├─────ꢁ e │  
└────┘  
Symmetric_Key_Export  
ꢂ ꢂ  
│ └─────────────────┘│ │  
├─────────────────┬───┘ │  
│ Key_  
│ Import  
Symmetric_Key_  
Generate  
│ Key_  
│ Generate │  
└───┐ │ Key_  
│ │ Export │  
┌─────────────────┐│ │  
┌─ꢄꢄ─ꢄ────ꢄ────┴────┐  
│External Key─Token │  
Key_Translate  
└─┬─────────────────┘  
└─────────────────┘  
Figure 5-8. Key-Processing Verbs  
In addition to the utilities that are supplied with the hardware, you can use the  
Key_Part_Import verb in an application program to load keys from individual key  
parts.  
Note that loading of key parts into the Coprocessor with the Master_Key_Process  
and Key_Part_Import verbs or the CNM utility exposes the key parts to potential  
copying by unauthorized processes. If you are concerned by this exposure, you  
should randomly generate master keys within the Coprocessor, and/or you should  
consider distribution of other keys using public key cryptographic techniques.  
Generating Keys  
A CCA cryptographic facility can generate2 clear keys, key parts, and  
multiply-enciphered keys or pairs of keys. These keys are generated as follows:  
To generate a clear key, use the odd-parity mode of the  
Random_Number_Generate verb.  
To generate a key part, use the odd-parity mode of the  
Random_Number_Generate verb. for the first part, and use the even-parity  
mode for subsequent key parts. You can use a key part with the  
Key_Part_Import verb.  
A multiply-enciphered key or pair of keys. To generate a random,  
multiply-enciphered key, use the Key_Generate verb. The Key_Generate verb  
multiply-enciphers a random number using a control vector and either the  
2
Keys can also be “diversified” from key-generating keys, see “Diversifying Keys” on page 5-19.  
5-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
master key or a key-encrypting key. If you are generating a DES asymmetric  
key-type, the verb will multiply-encipher the random number a second time with  
the “opposite” key-type control-vector. The verb restricts the combination of  
control vectors used for the two encipherments and also places restrictions on  
the use of master-key versus EXPORTER and IMPORTER  
encryption-key-types. This is done to ensure a secure, asymmetric  
key-distribution system.  
The Key_Generate verb can also do the following:  
– Generate one random number for a single-length key or one or two random  
numbers for a double-length key  
– Update a key token or create a key token that contains the default  
control-vector values for the key type. If you update a key token, you can  
use your own control vector to add additional restrictions.  
Before generating a key, consider how the key will be archived and recovered if  
unexpected events occur. Before using the Key_Generate verb, also consider the  
following aspects of key processing:  
The use of the key determines the key type and can determine whether you  
create a key token with the default control-vector or a key token with your own  
updated control-vector that contains non-default restrictions.  
If you update a key token, first use the Control_Vector_Generate and  
Key_Token_Build verbs to create the control vector and the key token, then  
use the Key_Generate verb to generate the key.  
Where and when the key will be used determines the form of the key, whether  
the verb generates one key or a key-pair, and whether the verb  
multiply-enciphers each key for operational, import, or export use. The verb  
multiply-enciphers each key under a key that is formed by exclusive-ORing the  
control vector in the new or updated key-token with one of the following keys:  
– The symmetric master-key. This is the operational (OP) key form.  
– An IMPORTER key-encrypting-key. This is the external, importable (IM)  
key form.  
– An EXPORTER key-encrypting-key. This is the external, exportable (EX)  
key form.  
If a key will be used locally, it should be enciphered in the OP key form or IM  
key form. An IM key form can be saved on external media and imported when  
its use is required. Saving a key locally in the IM key form ensures that the key  
can be used if the symmetric master-key is changed between the time the key  
was generated and the time it is used. This allows you to maintain the  
IMPORTER key-encrypting-keys in operational form and to store keys that are  
not needed immediately on external media.  
If a key will be used remotely (sent to another node), it should be enciphered in  
the EX key form under a local EXPORTER key. At the other node, the key will  
be imported under the paired IMPORTER key.  
Use the SINGLE keyword for a key that should be single length. Use the  
SINGLE-R keyword for a double-length key that should perform as a  
single-length key; this is often required when such a key will be interchanged  
with a non-CCA system. Use the DOUBLE keyword for a double-length key.  
Chapter 5. DES Key-Management 5-17  
CCA Release 2.54  
Since the two halves are random numbers, it is unlikely that the result of the  
DOUBLE keyword will produce two halves with the same 64-bit values.  
Exporting and Importing Keys, Symmetric Techniques  
To operate on data with the same key at two different nodes, you must transport  
the key securely between the nodes. To do this, a transport key or key-encrypting  
key must be installed at both nodes. (You can also use an RSA asymmetric key as  
a transport key, see “Exporting and Importing Keys, Asymmetric Techniques” on  
page 5-19.)  
A key that is enciphered under a key-encrypting key other than the symmetric  
master-key is called an external key. Deciphering an operational key with the  
master key and enciphering the key under a key-encrypting key is called a  
key-export operation and changes an operational key to an external key. The  
key-export operation is performed in the cryptographic facility so that the clear  
value of the key to be exported is not revealed.  
Deciphering an external key with a key-encrypting key and enciphering the key  
under the local symmetric master-key is called a key-import operation, and changes  
an external key to an operational key.  
The control vector for the transport key-encrypting-key at the source node must  
specify the key as an EXPORTER key. The control vector at the target node must  
specify the transport key-encrypting-key as an IMPORTER key. The key to be  
transported must be multiply-enciphered under an EXPORTER key-encrypting-key  
at the source node and multiply-deciphered under an IMPORTER  
key-encrypting-key at the target node. Figure 5-9 on page 5-19 shows both the  
key-export and key-import operations. Data operation keys, PIN keys, and  
key-encrypting keys can be transported in this manner. The control vector specifies  
what kind of keys can be enciphered by a key-encrypting key. For more  
information, see Appendix C, “CCA Control-Vector Definitions and Key Encryption”  
on page C-1.  
Use the Key_Export and the Key_Import verbs to export and import keys with key  
types that the control vectors associated with the EXPORTER or IMPORTER keys  
permit. Use can the Data_Key_Export verb and the Data_Key_Import verb to  
export and import DATA keys; these verbs will not import and export key-encrypting  
keys and PIN keys.  
The key-encipherment processes are described in detail at “CCA Key Encryption  
and Decryption Processes” on page C-12 .  
5-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
┌──────────────┐  
┌──────────────┐  
Operational │ Key to Be │  
│ Imported  
│ Key  
Operational  
Form of Key  
at Node B  
Form of Key │ Exported  
at Node A  
└──────┬───────┘  
└───────ꢂ──────┘  
┌───────────────────────────│──────┐  
┌──────│───────────────────────────┐  
│Key_Export  
┌────ꢄ────┐ │  
│Multiply-│ │  
│ ┌────┴────┐  
│ │Multiply-│  
Key_Import │  
│ Symmetric Master Key─ꢁDecipher │ │  
│ │Encipher ──Symmetric Master Key│  
└────┬────┘ │  
┌────ꢄ────┐ │  
│Multiply-│ │  
│ └────ꢂ────┘  
│ ┌────┴────┐  
│ Exporter  
│ │Multiply-│ Importer  
│ Key-Encrypting Key ──ꢁEncipher │ │  
│ │Decipher ──Key-Encrypting Key │  
└────┬────┘ │  
│ └────ꢂ────┘  
└───────────────────────────│──────┘  
└──────│───────────────────────────┘  
│ ┌──────────────┐ │  
└──ꢁ External Key ├──┘  
└──────────────┘  
Figure 5-9. Key Exporting and Importing  
Exporting and Importing Keys, Asymmetric Techniques  
You can also distribute a DES key from one node to another node by “wrapping”  
(encrypting) the DES key in the public key of the receiver (IMPORTER). CCA  
provides two services for wrapping the DES key in the public key of the recipient:  
PKA_Symmetric_Key_Export  
PKA_Symmetric_Key_Generate  
and you use the PKA_Symmetric_Key_Import verb to unwrap the transported key  
using the recipient's matching private key.  
Several techniques for formatting the key to be distributed are in common use and  
are supported by the verbs. The verbs support processing of default DATA keys.  
PKA_Symmetric_Key_Generate and PKA_Symmetric_Key_Import can also be used  
to exchange a DES key-encrypting-key.  
DATA keys can be exchanged with CCA and non-CCA implementations using two  
methods defined in the RSA PKCS #1 v2.0 standard:  
RSAES-OAEP  
RSAES-PKCS-v1_5.  
Key-encrypting keys can be exchanged between CCA implementations using the  
“PKA92” formatting method. PKA92 is an OAEP formatting method.  
The formatting methods are discussed in “Formatting Hashes and Keys in  
Public-Key Cryptography” on page D-19.  
Diversifying Keys  
CCA supports several methods for diversifying a key using the  
Diversified_Key_Generate verb. Key-diversification is a technique often used in  
working with smart cards. In order to secure interactions with a population of  
cards, a “key-generating key” is used with some data unique to a card to derive  
(“diversify”) a key(s) for use with that card. The data is often the card serial  
number or other quantity stored on the card. The data is often public, and  
Chapter 5. DES Key-Management 5-19  
CCA Release 2.54  
therefore it is very important to handle the key-generating key with a high degree of  
security lest the interactions with the whole population of cards be placed in  
jeopardy.  
In the current implementation, several methods of diversifying a key are supported:  
CLR8-ENC, TDES-ENC, TDES-DEC, SESS-XOR, TDES-XOR, and TDESEMV2  
and TDESEMV4. The first two methods triple-encrypt data using the  
generating_key to form the diversified key. The diversified key is then  
multiply-enciphered by the master key modified by the control vector for the output  
key. The TDES-DEC method is similar except that the data is triple-decrypted.  
The SESS-XOR method provides a means for modifying an existing DATA,  
DATAC, MAC, DATAM, or MACVER, DATAMV single- or double-length key. The  
provided data is exclusive-ORed into the clear value of the key. This form of key  
diversification is specified by several of the credit card associations.  
The TDES-ENC and TDES-DEC methods permit the production of either another  
key-generating key, or a “final” key. Control-vector bits 19-22 associated with the  
key-generating key specify the permissible type of final key. (See DKYGENKY on  
page C-6.) Control-vector bits 12-14 associated with the key-generating key  
specify if the diversified key is a final key or another in a series of key-generating  
keys. Bits 12 to 14 specify a counter that is decreased by one each time the  
Diversified_Key_Generate verb is used to produce another key-generating key. For  
example, if the key-generating key that you specify has this counter set to B'010',  
then you must specify the control vector for the generated_key with a DKYGENKY  
key type having the counter bits set to B'001' and specifying the same final key  
type in bits 19-22. Use of a generating_key with bits 12-14 set to B'000' results in  
the creation of the final key. Thus you can control both the number of  
diversifications required to reach a final key, and you can closely control the type of  
the final key.  
The TDESEMV2, TDESEMV4, and TDES-XOR methods also derive a key by  
encrypting supplied data including a transaction counter value received from an  
EMV smart card. The processes are described in detail at“VISA and EMV-Related  
Smart Card Formats and Processes” on page E-17 . Refer to “Working With EMV  
Smart Cards” on page 8-13 to understand the various verbs you can use to  
operate with EMV smart cards.  
Storing Keys in Key Storage  
Only internal key-tokens can be stored in key storage. The verbs that you use to  
create, write, read, delete, and list records in key storage, and the format of the key  
label used to access these records, are described in Chapter 7, “Key-Storage  
Verbs.”  
Note: To use key storage, the Compute_Verification_Pattern command must first  
be authorized. This command is used to validate that the symmetric master-key  
used to encipher keys within the key-storage file had the same value as the  
symmetric master-key in the cryptographic facility when the key-storage file is  
opened.  
5-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Security Precautions  
Be sure to see the “Observations on Secure Operations” chapter in the CCA  
Support Program Installation Manual.  
In order to maintain a secure cryptographic environment, each cryptographic node  
must be audited on a regular basis. This audit should be aimed at preventing  
inadvertent and malicious breaches of security. Some of the things that should be  
audited are listed below:  
The same transport key should not be used as both an EXPORTER key and  
IMPORTER key on any given cryptographic node. This would destroy the  
asymmetrical properties of the transport key.  
Enablement of the Encipher Under Master Key command (command offset  
X'00C3X') should be avoided.  
The Key_Part_Import verb can be used to enter key-encryption keys and data  
keys into the system. This verb provides for split knowledge (dual control) of  
keys by ensuring that no one person knows the true value of a key. Each  
person enters part of a key and the actual key is not assembled until the last  
key part is used. Neither the key nor the partial results of the key assembly  
appear in the clear outside of the secure hardware. Note, however, that the  
clear key-parts have passed through the general purpose computer. Consider  
accumulating the parts on different machines or using public-key cryptography  
in the key-distribution scheme.  
Be careful that the public key used in the PKA_Symmetric_Key_Generate and  
PKA_Symmetric_Key_Export verbs is associated with a legitimate receiver of  
the exported keys.  
Chapter 5. DES Key-Management 5-21  
Clear_Key_Import  
CCA Release 2.54  
Clear_Key_Import (CSNBCKI)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Clear_Key_Import verb enciphers a clear, single-length DES key under a  
symmetric master-key. The resulting key is a DATA key because the service  
requires that the resulting internal key-token have a DATA control-vector. You can  
use this verb to create an internal key-token from a null key-token, or you can  
update an existing internal DATA key-token with the enciphered value of the clear  
key. (You can create other types of DES keys from clear-key information using the  
Key_Part_Import verb.)  
If the clear-key value does not have odd parity in the low-order bit of each byte, the  
reason_code parameter presents a warning.  
Also see the Multiple_Clear_Key_Import verb on page 5-71.  
Restrictions  
Format  
None  
CSNBCKI  
return_code  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
reason_code  
exit_data_length  
exit_data  
exit_data_length bytes  
8 bytes  
clear_key  
Input  
String  
target_key_identifier  
In/Output String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
clear_key  
The clear_key parameter is a pointer to a string variable containing the clear  
value of the DES key being imported as a DATA key. The key is to be  
enciphered under the symmetric master-key. Although not required, the  
low-order bit in each byte should provide odd parity for the other bits in the  
byte.  
target_key_identifier  
The target_key_identifier parameter is a pointer to a string variable. If the key  
token in application storage or key storage is null, then a DATA key-token  
containing the encrypted clear-key replaces the null token. Otherwise, the  
preexisting token must be a DATA key-token and the encrypted clear-key  
replaces the existing key-value.  
5-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_Key_Import  
Required Commands  
The Clear_Key_Import verb requires the Encipher Under Master Key command  
(command offset X'00C3') to be enabled in the active role.  
Chapter 5. DES Key-Management 5-23  
Control_Vector_Generate  
CCA Release 2.54  
Control_Vector_Generate (CSNBCVG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Control_Vector_Generate verb builds a control vector from keywords specified  
by the key_type and rule_array parameters. For descriptions of the keywords and  
for valid combinations of these keywords, see Figure 5-4 on page 5-9, “Key Types”  
on page 5-5, and “Key-Usage Restrictions” on page 5-6. You may achieve added  
security by using optional keywords, or in some cases required keywords, supplied  
in the rule-array variable.  
Restrictions  
Format  
None  
CSNBCVG  
return_code  
reason_code  
exit_data_length  
exit_data  
key_type  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
8 bytes  
String  
Integer  
String  
array  
rule_array_count * 8 bytes  
reserved  
Input  
String  
null pointer or XL8'00'  
variable  
control_vector  
Output  
String  
16 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_type  
The key_type parameter is a pointer to a string variable containing a keyword  
for the key type. The keyword is eight bytes in length, left-justified and padded  
on the right with space characters. Supply a keyword from the following list:  
CIPHER  
DATAC  
DATAM  
DATAMV  
DECIPHER  
DKYGENKY  
ENCIPHER  
EXPORTER  
IKEYXLAT  
IMPORTER  
IPINENC  
MAC  
OKEYXLAT  
OPINENC  
PINGEN  
PINVER  
KEYGENKY3  
SECMSG4  
CVARDEC  
CVARENC  
CVARPINE  
CVARXCVL  
CVARXCVR  
DATA  
MACVER  
For definitions of these keywords, see “Control Vectors” on page 5-4.  
3
CLR8-ENC must be coded in the rule array when the KEYGENKY key-type is coded.  
4
SMKEY or SMPIN must be coded in the rule array when the SECMSG key-type is coded.  
5-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Control_Vector_Generate  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. For the valid combinations of  
keywords for the key type and the rule array, see Figure 5-4 on page 5-9. The  
rule_array keywords are shown below:  
ANY  
DKYL5  
DKYL6  
DKYL7  
DMAC  
DMKEY  
DMPIN  
DMV  
DOUBLE  
DPVR  
EPINGEN  
EPINGENA  
EPINVER  
EXEX  
GBP-PINO  
IBM-PIN  
IBM-PINO  
IMEX  
NO-XPORT  
NOT-KEK  
OPEX  
OPIM  
PIN  
REFORMAT  
SINGLE  
SMKEY6  
SMPIN7  
TRANSLAT  
UKPT  
VISA-PVV  
XLATE  
XPORT-OK  
CLR8-ENC5  
CPINENC  
CPINGEN  
CPINGENA  
DALL  
IMIM  
IMPORT  
INBK-PIN  
KEY-PART  
KEYLN8  
KEYLN16  
LMTD-KEK  
MIXED  
DATA  
DDATA  
DEXP  
DIMP  
DKYL0  
DKYL1  
DKYL2  
DKYL3  
DKYL4  
NOOFFSET  
NO-SPEC  
EXPORT  
GBP-PIN  
reserved  
This reserved parameter is a pointer to a string variable. The parameter must  
either be a null pointer, or a pointer to a variable of eight bytes of X'00'.  
control_vector  
The control_vector parameter is a pointer to a string variable containing the  
control vector returned by the verb.  
Required Commands  
This verb has no required hardware commands because control vector generation  
does not require cryptographic operations. The verb processes the request in the  
security API stub.  
5
6
7
CLR8-ENC must be coded when the KEYGENKY key-type is coded.  
SMKEY can be coded when the DKYGENKY key-type is coded. (Footnote was incorrect.)  
SMPIN can be coded when the DKYGENKY key-type is coded. (Footnote was incorrect.)  
Chapter 5. DES Key-Management 5-25  
Control_Vector_Translate  
CCA Release 2.54  
Control_Vector_Translate (CSNBCVT)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Control_Vector_Translate verb changes the control vector used to encipher an  
external key. See “Changing Control Vectors with the Control_Vector_Translate  
Verb” on page C-20 for additional information about this verb.  
Restrictions  
Format  
None  
CSNBCVT  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
64 bytes  
56 bytes  
64 bytes  
56 bytes  
zero, one, or two  
rule_array_count * 8 bytes  
KEK_key_identifier  
source_key_token  
array_key_left  
mask_array_left  
array_key_right  
mask_array_right  
rule_array_count  
rule_array  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
String  
String  
String  
String  
String  
String  
Integer  
String  
array  
target_key_token  
In/Output String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
KEK_key_identifier  
The KEK_key_identifier parameter is a pointer to a string variable containing an  
internal key-token or the key label of an internal key-token record containing  
the key-encrypting key. The control vector in the internal key-token must  
specify the key type IMPORTER, EXPORTER, IKEYXLAT, or OKEYXLAT.  
source_key_token  
The source_key_token parameter is a pointer to a string variable containing the  
external key-token with the key and control vector to be processed.  
array_key_left  
The array_key_left parameter is a pointer to a string variable containing an  
internal key-token or a key label of an internal key-token record that deciphers  
the left mask-array. The internal key-token must contain a control vector  
specifying a CVARXCVL key-type.  
5-26 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Control_Vector_Translate  
mask_array_left  
The mask_array_left parameter is a pointer to a string variable containing the  
mask array enciphered under the left-array key.  
array_key_right  
The array_key_right parameter is a pointer to a string variable containing an  
internal key-token or the key label of an internal key-token record that  
deciphers the right mask-array. The internal key-token must contain a control  
vector specifying a CVARXCVR key-type.  
mask_array_right  
The mask_array_right parameter is a pointer to a string variable containing the  
mask array enciphered under the right-array key.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, or two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 5-10. Control_Vector_Translate Rule_Array Keywords  
Keyword  
Meaning  
Parity adjustment (one, optional)  
ADJUST  
Ensures that all target-key bytes have odd parity. This is the  
default.  
NOADJUST  
Prevents the parity of the target key from being altered.  
Key portion (one, optional)  
LEFT  
Causes an 8-byte source key, or the left half of a 16-byte  
source key, to be processed with the result placed into both  
halves of the target key. This is the default.  
RIGHT  
BOTH  
Causes the right half of a 16-byte source key to be processed  
with the result placed into only the right half of the target key.  
The left half of the target key is unchanged.  
Causes both halves of a 16-byte source key to be processed  
with the result placed into corresponding halves of the target  
key. When you use the BOTH keyword, the mask array must  
be able to validate the translation of both halves.  
SINGLE  
Causes the left half of the source key to be processed with  
the result placed into only the left half of the target. The right  
half of the target key is unchanged.  
Chapter 5. DES Key-Management 5-27  
Control_Vector_Translate  
CCA Release 2.54  
target_key_token  
The target_key_token parameter is a pointer to a string variable containing an  
external key-token with the new control-vector. This key token contains the key  
halves with the new control-vector.  
Required Commands  
The Control_Vector_Translate verb requires the Translate Control Vector command  
(offset X'00D6') to be enabled in the active role.  
5-28 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Cryptographic_Variable_Encipher  
Cryptographic_Variable_Encipher (CSNBCVE)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Cryptographic_Variable_Encipher verb uses a CVARENC key to encrypt  
plaintext to produce ciphertext using the Cipher Block Chaining (CBC) method.  
The plaintext must be a multiple of eight bytes in length.  
Specify the following to encrypt plaintext:  
An internal key-token or a key label of an internal key-token record that  
contains the key to be used to encrypt the plaintext with the  
c-variable_encrypting_key_identifier parameter. The control vector in the key  
token must specify the CVARENC key-type.  
The length of the plaintext, which is the same as the length of the returned  
ciphertext, with the text_length parameter. The plaintext must be a multiple of  
eight bytes in length.  
The plaintext with the plaintext parameter.  
The initialization vector with the initialization_vector parameter.  
A field for the returned ciphertext with the ciphertext parameter. The length of  
this field is the length that you specified with the text_length parameter.  
The verb does the following:  
Uses the CVARENC key and the initialization value with the CBC method to  
encrypt the plaintext.  
Returns the encrypted plaintext in the variable pointed to by the ciphertext  
parameter.  
Restrictions  
Format  
The text length must be a multiple of eight bytes.  
The minimum length of text that the security server can process is 8 bytes and  
the maximum is 256 bytes.  
CSNBCVE  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
c-variable_encrypting_key_identifier  
text_length  
plaintext  
initialization_vector  
ciphertext  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
Input  
Input  
Input  
Input  
Output  
String  
Integer  
String  
String  
String  
text_length bytes  
8 bytes  
text_length bytes  
Chapter 5. DES Key-Management 5-29  
Cryptographic_Variable_Encipher  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
c-variable_encrypting_key_identifier  
The c-variable_encrypting_key_identifier parameter is a pointer to a string  
variable containing an internal key-token or a key label of an internal key-token  
record in key storage. The internal key-token must contain a control vector that  
specifies a CVARENC key-type.  
text_length  
The text_length parameter is a pointer to an integer variable containing the  
length of the plaintext variable and the ciphertext variable.  
plaintext  
The plaintext parameter is a pointer to is a string variable containing the  
plaintext to be encrypted.  
initialization_vector  
The initialization_vector parameter is a pointer to a string variable containing  
the eight-byte initialization vector the verb uses in encrypting the plaintext.  
ciphertext  
The ciphertext parameter is a pointer to a string variable containing the  
ciphertext returned by the verb.  
Required Commands  
The Cryptographic_Variable_Encipher verb requires the Encipher Cryptovariable  
command (offset X'00DA') to be enabled in the active role.  
5-30 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Data_Key_Export  
Data_Key_Export (CSNBDKX)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Data_Key_Export verb exports a single-length or double-length internal  
DATA-key. The verb can export the key from an internal key-token in key storage  
or application storage. This verb, which is authorized with a different control point  
than used with the Key_Export verb, allows you to limit the export operations to  
DATA keys as compared to the capabilities of the more general verb.  
The verb overwrites the 64-byte target-key-token variable with an external DES  
key-token that contains the source key now encrypted by the EXPORTER  
key-encrypting-key. Only a DATA key can be exported. If the source key has a  
control vector valued to the default DATA control vector, the target key will be  
enciphered without any control vector (that is, an “all zero” control vector),  
otherwise the source-key control vector will also be used with the target key.  
A key with a default, double-length DATA control-vector is exported into a version  
X'01' external key-token. Otherwise, keys are exported into version X'00' key  
tokens.  
Restrictions  
Format  
Starting with Release 2.41, unless you enable the Unrestrict Data Key Export  
command (offset X'0277'), having replicated key-halves is not permitted to export  
a key having unequal key-halves. Note that key parity bits are ignored.  
CSNBDKX  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
source_key_identifier  
exporter_key_identifier  
target_key_token  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
Input  
String  
String  
String  
Input  
Output  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
source_key_identifier  
The source_key_identifier parameter is a pointer to a string variable containing  
the internal key-token or the key label of the internal key-token to be exported.  
Only a DATA key can be exported.  
exporter_key_identifier  
The exporter_key_identifier parameter is a pointer to a string variable  
containing the (EXPORTER) transport key-token or the key label of the  
(EXPORTER) transport key-token used to encipher the target key.  
Chapter 5. DES Key-Management 5-31  
Data_Key_Export  
CCA Release 2.54  
target_key_token  
The target_key_token parameter is a pointer to a string variable containing the  
reencrypted source-key token. Any existing information in this variable will be  
overwritten.  
Required Commands  
The Data_Key_Export verb requires the Data Key Export command (command  
offset X'010A') to be enabled in the active role.  
By also specifying the Unrestrict Data Key Export command (offset X'0277'), you  
can permit a less secure mode of operation that enables an equal key-halves  
EXPORTER key-encrypting-key to export a key having unequal key-halves (key  
parity bits are ignored).  
5-32 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Data_Key_Import  
Data_Key_Import (CSNBDKM)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Data_Key_Import verb imports an encrypted, source DES single-length or  
double-length DATA key and creates or updates a target internal key-token with the  
master-key-enciphered source key. The verb can import the key into an internal  
key-token in application storage or in key storage. This verb, which is authorized  
with a different control point than used with the Key_Import verb, allows you to limit  
the import operations to DATA keys as compared to the capabilities of the more  
general verb.  
Specify the following:  
source_key_token: An external key-token containing the source key to be imported.  
The external key-token must indicate that a control vector is present. However,  
the control vector is usually valued at zero. A double-length key that should  
result in a default DATA control vector must be specified in a version X'01'  
external key-token. Otherwise, both single-length and double-length keys are  
presented in a version X'00' key token.  
Alternatively, you can provide the encrypted DATA-key at offset 16 in an  
otherwise all X'00' key-token. The verb will process this token format as a  
DATA key encrypted by the IMPORTER key and a null (all zero) control vector.  
importer_key_identifier: An IMPORTER key-encrypting-key under which the source  
key is deciphered.  
target_key_identifier: An internal or null key-token. The internal key-token can be  
located in application storage or in key storage.  
The verb builds the internal key-token as follows:  
Creates a default control-vector for a DATA key-type in the internal key-token,  
provided the control vector in the external key-token is zero. If the control  
vector is not zero, the verb copies the control vector from the external  
key-token into the internal key-token.  
Multiply-deciphers the key under the keys formed by the exclusive-OR of the  
key-encrypting key (identified in the importer_key_identifier) and the control  
vector in the external key-token, then multiply-enciphers the key under keys  
formed by the exclusive-OR of the symmetric master-key and the control vector  
in the internal key-token. The verb places the key in the internal key-token.  
Calculates a token-validation value and stores it in the internal key-token.  
This verb does not adjust the parity of the source key.  
Chapter 5. DES Key-Management 5-33  
Data_Key_Import  
CCA Release 2.54  
Restrictions  
Starting with Release 2.41, unless you enable the Unrestrict Data Key Import  
command (offset X'027C'), an IMPORTER transport key having replicated  
key-halves is not permitted to import a key having unequal key-halves. (Note that  
key parity bits are ignored.)  
Format  
CSNBDKM  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
source_key_token  
importer_key_identifier  
target_key_identifier  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
Input  
Input  
String  
String  
In/Output String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
source_key_token  
The source_key_token parameter is a pointer to a string variable containing the  
external key-token to be imported. Only a DATA key can be imported.  
importer_key_identifier  
The importer_key_identifier parameter is a pointer to a string variable  
containing the (IMPORTER) transport key or the key label of the (IMPORTER)  
transport key used to decipher the source key.  
target_key_identifier  
The target_key_identifier parameter is a pointer to a string variable containing a  
null key-token, an internal key-token, or the key label of an internal key-token  
or null key-token record in key storage. The key token receives the imported  
key.  
Required Commands  
The Data_Key_Import verb requires the Data Key Import command (offset  
X'0109') to be enabled in the active role.  
By also specifying the Unrestrict Data Key Import command (offset X'027C'), you  
can permit a less secure mode of operation that enables an equal key-halves  
IMPORTER key-encrypting-key to import a key having unequal key-halves (key  
parity bits are ignored).  
5-34 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Diversified_Key_Generate  
Diversified_Key_Generate (CSNBDKG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Diversified_Key_Generate verb generates a key based on a function of a  
key-generating key, the process rule, and data that you supply. The  
key-generating-key key-type enables you to restrict such keys from being used in  
other verbs that might reveal the value of a diversified key.  
This verb is especially useful for creating “diversified keys” for operating with  
finance industry smart cards. Be sure to review “Diversifying Keys” on page 5-19.  
To use the verb, specify the following:  
A rule-array keyword to select the diversification process.  
The operational key-generating key from which the diversified keys are  
generated. The control vector of the key-generating key determines the type of  
target key that is generated and, except for the SESS-XOR process, restricts  
the use of this key to the key-diversification process.  
The data and its length used in the diversification process.  
The operational key used to recover the data or, for processes that employ  
clear data, a null key-token.  
The generated-key key-token with a suitable control vector for receiving the  
diversified key. The specified process can restrict the type of generated key.  
– For the CLR8-ENC, TDESEMV2, TDESEMV4, and TDES-XOR processes,  
a null token may not be specified  
– For the TDES-ENC or TDES-DEC processes, a null token may be specified  
– For the SESS-XOR process, a null token must be specified.  
The verb generates the diversified key and updates the generated-key key-token  
with this value by the following procedure:  
Determines that it can support the process as requested by the rule-array  
keyword  
Recovers the key-generating key and checks the control vector for the  
appropriate key-type and the specified usage in this verb  
Determines that the length of the generating key is appropriate to the specified  
process  
Determines that the control vector in the generated-key key-token is permissible  
for the specified process  
Recovers the data-encrypting key and determines that the control vector is  
appropriate for the specified process  
Decrypts the data as can be required by the specified process  
Generates the key appropriate to the specified process  
Does not adjust the parity of the derived key.  
Chapter 5. DES Key-Management 5-35  
Diversified_Key_Generate  
CCA Release 2.54  
Returns the diversified key, multiply-enciphered by the master key modified by  
the control vector.  
Restrictions  
Format  
The TDES-XOR rule-array keyword is available starting with Release 2.50. The  
TDESEMV2 and TDESEMV4 rule-array keywords are available starting with  
Release 2.51.  
CSNBDKG  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
generating_key_identifier  
data_length  
data  
data_decrypting_key_identifier  
generated_key_identifier  
In/Output String  
64 bytes  
Input  
Input  
Integer  
String  
data_length bytes  
64 bytes  
64 bytes  
In/Output String  
In/Output String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Process rule (required)  
CLR8-ENC  
Specifies that eight bytes of clear (not encrypted) data shall  
be triple-DES encrypted with the generating key to create  
generated key. The encryption process is like that shown in  
Figure C-4 on page C-13 for a single-length key with a  
control vector valued to binary zero.  
The key selected by the generating_key_identifier must  
specify a KEYGENKY key-type also with control vector bit 19  
set to one.  
The key identified by the data_decrypting_key_identifier must  
identify a null key-token.  
The key token identified by the generated_key_identifier  
variable must contain a control vector that specifies a  
single-length key of one of these types: DATA, CIPHER,  
ENCIPHER, DECIPHER, MAC, or MACVER.  
5-36 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Diversified_Key_Generate  
Keyword  
Meaning  
TDES-ENC  
Specifies that 8 or 16 bytes of clear (not encrypted) data shall  
be triple-DES encrypted with the generating key to create the  
generated key. If the generated_key_identifier variable  
specifies a single-length key, then 8 bytes of clear data is  
triple-DES encrypted. If the generated_key_identifier variable  
specifies a double-length key, then 16 bytes of clear data is  
triple-DES encrypted in ECB mode.  
The key selected by the generating_key_identifier must  
specify a DKYGENKY key-type that has the appropriate  
control vector usage bits (bits 19-22) set for the desired  
generated key.  
Control vector bits 12-14 binary encode the key-derivation  
sequence level (DKYL7 down to DKYL0, see DKYGENKY on  
page C-6). The final key is derived when bits 12 to 14 are  
B'000'. The verb verifies the incremental relationship  
between the value in generated_key_identifier control vector  
and the generating_key_identifier control vector. Or in the  
case when the generated_key_identifier is a null-token, the  
appropriate counter value is placed into the output key-token.  
The data_decrypting_key_identifier must identify a null  
key-token.  
A key token identified by the generated_key_identifier variable  
that is not a null key-token must contain a control vector that  
specifies a single-length or double-length key having a key  
type consistent with the specification in bits 19-22 of the  
generating key.  
TDES-DEC  
Specifies that 8 or 16 bytes of clear (not encrypted) data shall  
be triple-DES decrypted with the generating key to create the  
generated key. If the generated_key_identifier variable  
specifies a single-length key, then 8 bytes of clear data is  
triple-DES decrypted. If the generated_key_identifier variable  
specifies a double-length key, then 16 bytes of clear data is  
triple-DES decrypted in ECB mode.  
The key selected by the generating_key_identifier must  
specify a DKYGENKY key-type that has the appropriate  
control vector usage bits (bits 19-22) set for the desired  
generated key.  
Control vector bits 12-14 binary encode the key-derivation  
sequence level (DKYL7 down to DKYL0, see DKYGENKY on  
page C-6). The final key is derived when bits 12 to 14 are  
B'000'. The verb verifies the incremental relationship  
between the value in generated_key_identifier control vector  
and the generating_key_identifier control vector. Or in the  
case when the generated_key_identifier is a null-token, the  
appropriate counter value is placed into the output key-token.  
The data_decrypting_key_identifier must identify a null  
key-token.  
A key token identified by the generated_key_identifier variable  
that is not a null key-token must contain a control vector that  
specifies a single-length or double-length key having a key  
type consistent with the specification in bits 19-22 of the  
generating-key.  
Chapter 5. DES Key-Management 5-37  
Diversified_Key_Generate  
CCA Release 2.54  
Keyword  
Meaning  
TDESEMV2,  
TDESEMV4  
Note: These options are available starting with Release 2.51.  
Specifies that 10, 18, 26, or 34 bytes of clear data shall be  
processed to form an EMV card-unique key and then a  
session key as specified in the EMV 2000 Integrated Circuit  
Card Specification for Payment Systems Version 4.0 (EMV4.0)  
Book 2, Annex A1.3. See “VISA and EMV-Related Smart  
Card Formats and Processes” on page E-17 for additional  
details. The supplied data variable must contain the  
concatenation of:  
8 or 16 bytes of data to diversify the issuer-master-key.  
2 bytes containing the Application Transaction Counter  
(ATC) received from the smart card. Place the counter  
value in a string construct with the high-order counter bit  
first in the string.  
Optionally, a 16-byte Initial Value used in obtaining the  
session key from the card-unique key.  
The key selected by the generating_key_identifier parameter  
must specify a DKYGENKY key-type at level-0 (bits 12 to 14  
B'000') and indicate permission to create one of several key  
types in bits 19 to 22:  
B'0001' DDATA, to generate a DATA key  
B'0001' DMAC, to generate a MAC key  
B'0001' DMV, to generate a MACVER key  
B'1000' DMKEY, to generate a SECMSG SMKEY (used  
in secure messaging, key encryption, see the  
Secure_Messaging_for_Keys verb)  
B'1001' DMPIN, to generate a SECMSG SMPIN (used in  
secure messaging, PIN encryption, see the  
Secure_Messaging_for_PINs verb).  
The data_decrypting_key_identifier must identify a null  
key-token.  
A key token or key-token record identified by the  
generated_key_identifier parameter that is not a null  
key-token. The token must contain a control vector that  
specifies a key type conforming to that specified in  
control-vector bits 19-22 for the key-generating key. The  
control vector must specify a double-length key.  
5-38 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Diversified_Key_Generate  
Keyword  
Meaning  
TDES-XOR  
Note: This option is available starting with Release 2.50.  
Specifies that 10 or 18 bytes of clear (not encrypted) data  
shall be processed as described at “VISA and EMV-Related  
Smart Card Formats and Processes” on page E-17 to create  
the generated key. The data variable contains either 8 or 16  
bytes of data to be triple-encrypted to which you append a  
2-byte Application Transaction Counter value (previously  
received from the smart card). The counter value shall be in  
a string construct with the high-order counter bit first in the  
string.  
The key selected by the generating_key_identifier parameter  
must specify a DKYGENKY key-type at level-0 (bits 12 to 14  
B'000') and indicate permission to create one of several key  
types in bits 19 to 22:  
B'0001' DDATA, to generate a DATA key  
B'0001' DMAC, to generate a MAC key  
B'0001' DMV, to generate a MACVER key  
B'1000' DMKEY, to generate a SECMSG SMKEY (used  
in secure messaging, key encryption, see the  
Secure_Messaging_for_Keys verb)  
B'1001' DMPIN, to generate a SECMSG SMPIN (used in  
secure messaging, PIN encryption, see the  
Secure_Messaging_for_PINs verb).  
The data_decrypting_key_identifier must identify a null  
key-token.  
A key token or key-token record identified by the  
generated_key_identifier parameter that is not a null  
key-token. The token must contain a control vector that  
specifies a key type conforming to that specified in  
control-vector bits 19-22 for the key-generating key. The  
control vector must specify a double-length key.  
SESS-XOR  
Specifies the VISA method for session-key generation, namely  
that 8 or 16 bytes of data shall be exclusive-ORed with the  
clear value of the session key contained in the key token  
specified by the generating_key_identifier parameter. If the  
generating_key_identifier parameter specifies a single-length  
key, then 8 bytes of data are exclusive-ORed. If the  
generating_key_identifier parameter specifies a double-length  
key, then 16 bytes of data are exclusive-ORed.  
The key token specified by the generating_key_identifier  
parameter must be of key type DATA, DATAC, MAC, DATAM,  
MACVER, or DATAMV.  
The key identified by the data_decrypting_key_identifier must  
identify a null key-token.  
On input, the token identified by the generated_key_identifier  
parameter must identify a null key-token. The control vector  
contained in the output key token identified by the  
generated_key_identifier parameter will be the same as the  
control vector contained in the key token specified by the  
generating_key_identifier parameter.  
Chapter 5. DES Key-Management 5-39  
Diversified_Key_Generate  
CCA Release 2.54  
generating_key_identifier  
The generating_key_identifier parameter is a pointer to a string variable  
containing the key-generating-key key-token or key label of a key-token record.  
data_length  
The data_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the data variable.  
data  
The data parameter is a pointer to a string variable containing the information  
used in the key-generation process. This can be clear or encrypted information  
based on the process rule specified in the rule array. Currently this variable  
must contain clear data.  
data_decrypting_key_identifier  
The data_decrypting_key_identifier parameter is a pointer to a string variable  
containing the data decrypting key-token or key label of a key-token record.  
The specified process dictates the class of key. If the process rule does not  
support encrypted data, point to a null key-token. Currently this variable must  
contain a 64-byte null token.  
generated_key_identifier  
The generated_key_identifier parameter is a pointer to a string variable  
containing the target internal key-token or the key label of the target key-token  
record. Specify either an internal token or a skeleton token containing the  
desired control vector of the generated key.  
For the CLR8-ENC, TDESEMV2, TDESEMV4, and TDES-XOR processes,  
a null token may not be specified  
For the TDES-ENC or TDES-DEC processes, a null token may be specified  
For the SESS-XOR process, a null token must be specified.  
The generated key will be encrypted and returned in the specified token. The  
control vector in the specified internal token must be suitable for the specified  
process rule.  
Required Commands  
The Diversified_Key_Generate verb requires the following commands to be enabled  
in the active role based on the keyword specified for the process rule:  
Process Rule  
Command  
Offset  
Command  
CLR8-ENC  
SESS-XOR  
TDES-DEC  
TDES-ENC  
TDES-XOR  
TDESEMV2,  
TDESEMV4  
X'0040'  
X'0043'  
X'0042'  
X'0041'  
X'0045'  
X'0046'  
Generate Diversified Key (CLR8-ENC)  
Generate Diversified Key (SESS-XOR)  
Generate Diversified Key (TDES-DEC)  
Generate Diversified Key (TDES-ENC)  
Generate Diversified Key (TDES-XOR)  
Generate Diversified Key (TDESEMVn)  
When a key-generating key of key type DKYGENKY is specified with control vector  
bits (19-22) of B'1111', the Generate Diversified Key (DALL with DKYGENKY key  
type) command (offset X'0290') must also be enabled in the active role.  
When using the TDES-ENC or TDES-DEC modes, you may specifically enable  
generation of a single-length key or a double-length key with equal key-halves (an  
5-40 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Diversified_Key_Generate  
effective single-length key) by enabling the Enable DKG Single Length Keys and  
Equal Halves for TDES-ENC, TDES-DEC command (offset X'0044').  
Chapter 5. DES Key-Management 5-41  
Key_Export  
CCA Release 2.54  
Key_Export (CSNBKEX)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Export verb exports a source DES internal-key into a target external  
key-token. Existing information in the target key-token is overwritten. The target  
key is enciphered by the EXPORTER-key exclusive-ORed with the control vector of  
the target key.  
Specify the following:  
Key_type  
A keyword for the key type. Use of the TOKEN keyword is the preferred coding  
style. For compatibility with older systems, however, you can explicitly name a  
key type, in which case the key type must match the key in the control vector of  
the source key-identifier.  
source_key_identifier  
A source-key internal key-token or the key label of an internal key-token record  
in key storage containing the source key to be exported.  
exporter_key_identifier  
An EXPORTER key-encrypting-key under which the target key is enciphered.  
target_key_token  
A 64-byte field to hold the target key-token.  
The verb builds the external key-token:  
Copies the control vector from the internal key-token to the external key-token,  
except when the source key has a control vector valued to the default DATA  
control-vector for single- or double-length keys, in which case the target control  
vector is set to zero.  
Multiply-deciphers the source key under keys formed by the exclusive-OR of  
the master key and the control vector in the source key-token,  
multiply-enciphers the key under keys formed by the exclusive-OR of the  
EXPORTER key-encrypting-key and target-key control vector, and places the  
result in the target key-token.  
Calculates a token-validation value and stores it in the target key-token.  
Places the external key-token in the 64-byte field identified by the  
target_key_token parameter, ignoring any preexisting data.  
Restrictions  
Starting with Release 2.41, unless you enable the Unrestrict Reencipher From  
Master Key command (offset X'0276'), an EXPORTER key-encrypting-key having  
equal key-halves is not permitted to export a key having unequal key-halves. Note  
that key parity bits are ignored.  
5-42 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Export  
Format  
CSNBKEX  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
exit_data_length bytes  
key_type  
Input  
Input  
Input  
Output  
String  
String  
String  
String  
8 bytes  
source_key_identifier  
exporter_key_identifier  
target_key_token  
64 bytes  
64 bytes  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_type  
The key_type parameter is a pointer to a string variable containing a keyword  
that specifies the key type of the source key-token. The keyword is eight bytes  
in length, and must be left-justified and padded on the right with space  
characters. The key_type keywords are shown below:  
CIPHER  
DATA  
DECIPHER  
ENCIPHER  
EXPORTER  
IKEYXLAT  
IMPORTER  
IPINENC  
MAC  
PINGEN  
PINVER  
TOKEN  
MACVER  
OKEYXLAT  
OPINENC  
source_key_identifier  
The source_key_identifier parameter is a pointer to a string variable containing  
the source key-token or key label of a key-token record.  
exporter_key_identifier  
The exporter_key_identifier parameter is a pointer to a string variable  
containing the EXPORTER key-encrypting-key token or key label of a  
key-token record.  
target_key_token  
The target_key_token parameter is a pointer to a string variable containing the  
target key-token.  
Required Commands  
The Key_Export verb requires the Reencipher from Master Key command (offset  
X'0013') to be enabled in the active role.  
By also specifying the Unrestrict Reencipher From Master Key command (offset  
X'0276'), you can permit a less secure mode of operation that enables an equal  
key-halves EXPORTER key-encrypting-key to export a key having unequal  
key-halves (key parity bits are ignored).  
Chapter 5. DES Key-Management 5-43  
Key_Generate  
CCA Release 2.54  
Key_Generate (CSNBKGN)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Generate verb generates a random DES key and returns one or two  
enciphered copies of the key, ready to use or distribute.  
A control vector associated with each copy of the key defines the type of key and  
any specific restrictions on the use of the key. Only certain combinations of key  
types are permitted when you request two copies of a key. Specify the type of key  
through a key type keyword, or by providing a key token or tokens with a control  
vector into which the verb can place the keys. If you specify TOKEN as a  
key-type, the verb uses the preexisting control-vector from the key token. Use of  
the TOKEN keyword allows you to associate other than default control vectors with  
the generated keys. Use of the TOKEN keyword is the preferred coding style.  
Based on the key_form variable, the verb encrypts a copy or copies of the  
generated key under one or two of the following:  
The master key  
An IMPORTER key-encrypting-key  
An EXPORTER key-encrypting-key.  
Request two copies of a key when you intend to distribute the key to more than  
one node, or when you want a copy for immediate local use and the other copy  
available for later local import.  
Specify the key length of the generated key. A DES key can be either single or  
double length. Certain types of CCA keys must be double length, for example,  
EXPORTER and IMPORTER key-encrypting-keys. In certain cases, you need such  
a key to perform as a single-length key. In these cases, specify SINGLE-R, “single  
replicated.” A double-length key with equal halves performs as though the key were  
a single-length key.  
Specify where the generated key copies should be returned, either to application  
storage or to key storage. In either case, a null key-token can be overwritten by a  
default key-token taken from your specification of key-type. If you provide an  
existing key-token, the verb replaces the key value in the token.  
Restrictions  
None  
5-44 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Generate  
Format  
CSNBKGN  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
exit_data_length bytes  
key_form  
key_length  
key_type_1  
key_type_2  
KEK_key_identifier_1  
KEK_key_identifier_2  
generated_key_identifier_1  
generated_key_identifier_2  
Input  
Input  
Input  
Input  
Input  
Input  
String  
String  
String  
String  
String  
String  
4 bytes  
8 bytes  
8 bytes  
8 bytes  
64 bytes  
64 bytes  
64 bytes  
64 bytes  
In/Output String  
In/Output String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_form  
The key_form parameter is a pointer to a string variable containing the keyword  
that defines whether one or two copies of the key will be generated, and the  
type of key-encrypting key used to encipher the key. The keyword is four  
characters in length, and must be left-justified and padded on the right with  
space characters.  
When you want a copy of the new key to be immediately useful at the local  
node, ask for an operational (OP) key. An OP key is enciphered by the  
master key.  
When you want a copy of the new key to be imported to the local node at a  
later time, specify an importable (IM) key. An IM key is enciphered by an  
IMPORTER key type at the generating node.  
When you want to distribute the generated key to another node or nodes,  
specify an exportable (EX) key. An EX key is enciphered by an  
EXPORTER key type at the generating node.  
Specify one of the following keywords for the key_form variable:  
OP  
One key for operational use.  
IM  
One key to be imported later to this node.  
EX  
One key for distribution to another node.  
OPOP  
Two copies of the generated key, normally with different control  
vector values.  
OPIM  
OPEX  
Two copies of the generated key, normally with different control  
vector values; one for use now, one for later importation.  
Two copies of the generated key, normally with different control  
vector values; one for local use and the other for use at a remote  
node.  
IMIM  
Two copies of the generated key, normally with different control  
vector values; to be imported later to the local node.  
Two copies of the generated key, normally with different control  
vector values; one to be imported later to the local node and the  
other for a remote node.  
IMEX  
EXEX  
Two copies of the generated key, sometimes with different control  
vector values; to be sent to two different remote nodes. No copy of  
the generated key will be available to the local node.  
Chapter 5. DES Key-Management 5-45  
Key_Generate  
CCA Release 2.54  
key_length  
The key_length parameter is a pointer to an eight-byte string variable,  
left-justified and padded on the right with space characters, containing the  
length of the new key or keys. Depending on key type, you can specify a  
single-length key or a double-length key. A double-length key consists of two  
eight-byte values. The key_length variable must contain one of the following:  
SINGLE or KEYLN8  
For a single-length key  
SINGLE-R  
For a double-length key with equal-valued halves (“single  
replicated”)  
DOUBLE or KEYLN16  
For a double-length key8. The key halves will be different  
except when the same 56-bit key would be generated twice in  
succession — a minuscule possibility.  
8 spaces  
When you provide a control vector, or when you wish the verb  
to select the key length based on the key type, provide eight  
space characters to direct the verb to select the key length.  
key_type_1 and key_type_2  
The key_type_1 and key_type_2 parameters are pointers to eight-byte string  
variables, each containing a keyword that specifies the key type for each new  
key being generated. To specify the key type via the control vector in the  
preexisting key-token, use the TOKEN keyword. Alternatively, you can specify  
the key type using keywords shown in Figure 5-11 on page 5-48 and  
Figure 5-12 on page 5-49. This is useful when you want to create  
default-value key-tokens and control-vectors.  
Figure 5-11 on page 5-48 lists the keywords allowed when generating a  
single key copy (key_form OP, IM, or EX). Key_type_2 should contain a  
string of eight space characters.  
Figure 5-12 on page 5-49 lists the key_type keyword combinations allowed  
when requesting two copies of a key value.  
KEK_key_identifier_1 and KEK_key_identifier_2  
The KEK_key_identifier_1 and KEK_key_identifier_2 parameters are pointers to  
64-byte string variables containing the key token or key label of a key-token  
record for the key used to encipher the IM-form and EX-form keys. If an  
OP-form key is requested, the associated KEK identifier must point to a null  
key-token.  
generated_key_identifier_1 and generated_key_identifier_2  
The generated_key_identifier_1 and generated_key_identifier_2 parameters are  
pointers to 64-byte string variables containing the key token or key label of a  
key-token record of the generated keys. If the parameter identifies an internal  
or external key-token, the verb attempts to use the information in the existing  
key-token and simply replaces the key value. Using the TOKEN keyword in the  
key_type variables requires that key tokens already exist when the verb is  
called, so the control vectors in those key tokens can be used. In general,  
8
Certain other CCA implementations may support the keyword DOUBLE-O to enable generation of double-length keys with  
key-halves guaranteed to be unique. The associated key-form control vector bits (bits 40-42) B'110' are described at “Key-Form  
Bits, ‘fff’ and ‘FFF’” on page C-7. This implementation does not support the DOUBLE-O keyword, but this implementation does  
support generation of guaranteed unique-key-halves if you supply a key token with a control vector having form-field bits of  
B'110'. Support of form-field B'110' is not available in all CCA implementations.  
5-46 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Generate  
unless you are using the TOKEN keyword, you must identify a null key-token  
on input.  
Required Commands  
Depending on your specification of key form, key type, and use of the SINGLE-R  
key length control, different commands are required to enable operation of the  
Key_Generate verb.  
If you specify the key-form and key-type combinations shown with an X in the  
Key_Form OP column in Figure 5-11 on page 5-48, the Key_Generate verb  
requires the Generate Key command (offset X'008E') to be enabled in the  
active role.  
If you specify the key-form and key-type combinations shown with an X in the  
Key_Form IM column in Figure 5-11 on page 5-48, the Key_Generate verb  
requires the Generate Key Set command (offset X'008C') to be enabled in the  
active role. The verb will apply the restrictive rules of the IMEX column in  
Figure 5-12 on page 5-49 to the generation of the IM form key.  
If you specify the key-form and key-type combinations shown with an X in the  
Key_Form EX column in Figure 5-11 on page 5-48, the Key_Generate verb  
requires the Generate Key Set command (offset X'008C') to be enabled in the  
active role. The verb will apply the restrictive rules of the EXEX column in  
Figure 5-12 on page 5-49 to the generation of the EX form key.  
If you specify the key-form and key-type combinations shown with an X in  
Figure 5-12, the Key_Generate verb requires the Generate Key Set command  
(offset X'008C') to be enabled in the active role.  
If you specify the key-form and key-type combinations shown with an E in  
Figure 5-12 on page 5-49, the Key_Generate verb requires the Generate Key  
Set Extended command (offset X'00D7') to be enabled in the active role.  
If you specify the SINGLE-R key-length keyword, the Key_Generate verb also  
requires the Replicate Key command (offset X'00DB') to be enabled in the  
active role.  
Related Information  
The following sections discuss the key_type and key_length parameters.  
Key-Type Specifications  
Generated keys are returned multiply-enciphered by a key-encrypting key, or by a  
master key, exclusive-ORed with the control vector associated with that copy of the  
generated key. (See “CCA Key Encryption and Decryption Processes” on  
page C-12.)  
There are two methods for specifying the type of key(s) to be generated:  
Specify a key-type keyword(s) from Figure 5-11 on page 5-48 or Figure 5-12  
on page 5-49  
Use the TOKEN keyword and encode the key type and other information in the  
control vector you provide in the generated_key_identifier_n key-token  
variables.  
Use of the key-type keywords generates default control vector values. See  
Figure C-2 on page C-3. One or two keywords are examined based on the  
key_form variable. Figure 5-11 on page 5-48 shows the key-type keywords you  
Chapter 5. DES Key-Management 5-47  
Key_Generate  
CCA Release 2.54  
can use to generate a single key copy with default control-vectors. Figure 5-12 on  
page 5-49 shows the key types you can use to generate two copies of a key. An  
‘X’ indicates a permissible key type for a given key-form. An E indicates that a  
special (Extended) command is required as those keys require special handling.  
You can generate a single-length key with any control vector value9. when you  
specify SINGLE and OP. In this case, the verb uses the Generate Key command  
(X'008E')  
If you encode the key type in a control vector supplied in a key token (and use the  
TOKEN key-type keyword), remember that non-default control vector values for the  
key type can be employed.  
Certain key-type keywords have an asterisk (*) indicating that these keywords are  
not recognized by the verb as key type specifications. Nevertheless, those key  
types are supported when supplied as control vector values.  
Figure 5-11. Key_Type and Key_Form Keywords for One Key  
Key_Type_1  
MAC  
Key_Form OP  
Key_Form IM  
Key_Form EX  
X
X
X
X
X
X
X
X
X
X
X
X
DATA  
PINGEN  
DATAC *  
DATAM *  
DATAMV *  
KEYGENKY *  
DKYGENKY *  
SECMSG *  
Note:  
1. The key types marked with an * must be requested through the specification of a  
proper control vector in a key token and the use of the TOKEN keyword.  
2. Additional key types can be generated as operational keys when you supply key  
form as OP, key type as TOKEN, key length as eight space characters, and provide  
the desired control vector in the key token specified by the  
generated_key_identifier_1 parameter.  
9
The command-level architecture permits many CV values and value-pairs to be generated so long as they adhere to rules defined  
in that architecture. It is beyond the scope of this publication to explain all permissible combinations. Only those with defined  
usage are shown in the tables.  
5-48 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Generate  
Figure 5-12. Key_Type and Key_Form Keywords for a Key Pair  
Key_Type_1  
Key_Type_2  
Key_  
Form  
OPOP,  
OPIM,  
IMIM  
Key_  
Form  
OPEX  
Key_  
Form  
EXEX  
Key_  
Form  
IMEX  
DATA  
DATA  
X
X
X
X
MAC  
MAC  
MAC  
MACVER  
MAC  
DATAC *  
DATAM *  
DATAMV *  
CIPHER  
MACVER  
DATAC *  
DATAM *  
DATAM *  
CIPHER  
CIPHER  
CIPHER  
DECIPHER  
ENCIPHER  
CIPHER  
ENCIPHER  
CIPHER  
DECIPHER  
KEYGENKY *  
DKYGENKY *  
DECIPHER  
DECIPHER  
ENCIPHER  
ENCIPHER  
KEYGENKY *  
DKYGENKY *  
EXPORTER  
IMPORTER  
EXPORTER  
IKEYXLAT  
IKEYXLAT  
IMPORTER  
OKEYXLAT  
OKEYXLAT  
PINGEN  
IMPORTER  
EXPORTER  
IKEYXLAT  
EXPORTER  
OKEYXLAT  
OKEYXLAT  
IMPORTER  
IKEYXLAT  
PINVER  
X
X
X
PINVER  
PINGEN  
OPINENC  
IPINENC  
IPINENC  
OPINENC  
E
X
X
E
X
X
E
OPINENC  
OPINENC  
CVARDEC *  
CVARENC *  
CVARENC *  
CVARENC *  
CVARXCVL *  
CVARXCVR *  
CVARDEC *  
CVARPINE *  
CVARENC *  
CVARDEC *  
CVARXCVL *  
CVARXCVR *  
CVARENC *  
CVARENC *  
CVARPINE *  
CVARDEC *  
Note: The key types marked with an * must be requested through the specification of a proper  
control-vector in a key token and the use of the TOKEN keyword.  
Key-Length Specification  
The key_length parameter points to a variable containing a keyword or eight space  
characters which specifies the length of a key, either single or double. The  
key-length specified must be consistent with the key length indicated by the control  
vectors associated with the generated keys. You can specify SINGLE, KEYLN8,  
SINGLE-R, KEYLN16, DOUBLE, or eight space characters. The SINGLE-R  
keyword (“single replicated”) indicates that you want a double-length key where  
both halves of the key are identical. Such a key performs as though the key were  
single length.  
Figure 5-13 on page 5-50 shows the valid key lengths for each key type. An ‘X’  
indicates that a key length is permitted for a key type and a ‘D’ indicates the default  
Chapter 5. DES Key-Management 5-49  
Key_Generate  
CCA Release 2.54  
key-length the verb uses when you supply eight space characters with the  
key_length parameter.  
Figure 5-13. Key Lengths by Key Type  
Key Type  
SINGLE  
KEYLN8  
SINGLE-R  
DOUBLE  
KEYLN16  
MAC  
MACVER  
X, D  
X, D  
X
X
DATA  
X, D  
X
DATAC *  
DATAM *  
DATAMV *  
X
X
X
X
X
X
EXPORTER  
IMPORTER  
X
X
X, D  
X, D  
IKEYXLAT  
OKEYXLAT  
X
X
X, D  
X, D  
CIPHER  
DECIPHER  
ENCIPHER  
X, D  
X, D  
X, D  
X
X
X
DKYGENKY  
IPINENC  
OPINENC  
PINGEN  
X
X
X
X
X
X, D  
X, D  
X, D  
X, D  
X, D  
PINVER  
CVARDEC *  
CVARENC *  
CVARPINE *  
CVARXCVL *  
CVARXCVR *  
X
X
X
X
X
X
X
X
X
X
KEYGENKY *  
SECMSG *  
X
X
X
X, D  
X, D  
Note: The key types marked with an * must be requested through the specification of a proper  
control-vector in a key token and the use of the TOKEN keyword.  
5-50 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Import  
Key_Import (CSNBKIM)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Import verb imports a source DES key enciphered by the IMPORTER  
key-encrypting-key into a target internal key-token. The imported target-key is  
returned enciphered using the symmetric master-key.  
Specify the following:  
Key_type  
A keyword for the key type. Use of the TOKEN keyword is the preferred coding  
style. For compatibility with older systems, however, you can explicitly name a  
key type, in which case the key type must match the key type encoded in the  
control vector of the source key-token.  
source_key_token  
An external key-token or an encrypted external key to be imported. When you  
import an enciphered key that is not in an external key-token, the key must be  
located at offset 16 (X'10') of a null key-token. (The first byte of a null  
key-token is X'00'.)  
importer_key_identifier  
An IMPORTER key-encrypting-key under which the target key is deciphered.  
target_key_identifier  
An internal or null key-token, or the key label of an internal or null key-token  
record in key storage.  
The verb builds or updates the target key-token as follows:  
If the source key is not in an external key-token,  
– You must specify an explicit key type (not TOKEN).  
– The default CV for the key type is used when decrypting the source key.  
– The default CV for the key type is used when encrypting the target key.  
– The target key-token must either be null or must contain valid,  
non-conflicting information.  
The key token is returned to the application or key storage with the imported  
key.  
If the source key is in an external key-token:  
– When an explicit key type keyword other than TOKEN is used, it must be  
consistent with the key type encoded in the source-key control vector.  
– The control vector in the source key-token is used in decrypting the source  
key.  
– The control vector in the source key-token is used in encrypting the source  
key under the master key. Note that a source key having the default  
external DATA control vector (8 or 16 bytes of X'00') will result in a target  
key with the default internal DATA control vector.  
The key token is returned to the application or key storage with the imported  
key.  
Chapter 5. DES Key-Management 5-51  
Key_Import  
CCA Release 2.54  
Restrictions  
Starting with Release 2.41, unless you enable the Unrestrict Reencipher to Master  
Key command (offset X'027B'), an IMPORTER key-encrypting-key having equal  
key-halves is not permitted to import a key having unequal key-halves. Note that  
key parity bits are ignored.  
Format  
CSNBKIM  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
key_type  
source_key_token  
importer_key_identifier  
target_key_identifier  
In/Output Integer  
In/Output String  
exit_data_length bytes  
8 bytes  
64 bytes  
64 bytes  
64 bytes  
Input  
Input  
Input  
String  
String  
String  
In/Output String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_type  
The key_type parameter is a pointer to a string variable containing an  
eight-byte keyword, left-justified and padded on the right with space characters,  
specifying the key type of the key to be imported. In general, you should use  
the TOKEN keyword.  
CIPHER  
DATA  
DECIPHER  
ENCIPHER  
EXPORTER  
IKEYXLAT  
IMPORTER  
IPINENC  
MAC  
PINGEN  
PINVER  
TOKEN  
MACVER  
OKEYXLAT  
OPINENC  
source_key_token  
The source_key_token parameter is a pointer to a string variable containing the  
source DES key-token. Ordinarily the source key-token is an external DES  
key-token (the first byte of the key-token data structure contains X'02').  
However, if the first byte of the token is X'00', then the encrypted source-key  
is taken from the data at offset 16 (X'10') in the source key-token structure.  
importer_key_identifier  
The importer_key_identifier parameter is a pointer to a string variable  
containing the key-token or key label for the IMPORTER (transport)  
key-encrypting-key.  
target_key_identifier  
The target_key_identifier parameter is a pointer to a string variable containing  
the target key-token or key label of a key-token record.  
Required Commands  
The Key_Import verb requires the Reencipher to Master Key command (offset  
X'0012') to be enabled in the active role.  
By also enabling the Unrestrict Reencipher To Master Key command (offset  
X'027B'), you can permit a less secure mode of operation that enables an equal  
5-52 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Import  
key-halves IMPORTER key-encrypting-key to import a key having unequal  
key-halves (key parity bits are ignored).  
Chapter 5. DES Key-Management 5-53  
Key_Part_Import  
CCA Release 2.54  
Key_Part_Import (CSNBKPI)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Part_Import verb is used to accumulate “parts” of a key and store the  
result as an encrypted partial key or as the final key. Individual key-parts are  
exclusive-ORed together to form the accumulated key.  
On each call to Key_Part_Import (except COMPLETE, see below), specify 8 bytes  
or 16 bytes of clear key-information based on the length of the key that you are  
accumulating. Align an 8-byte clear key in the high-order bytes (leftmost bytes) of  
a 16-byte field. Also specify an internal key-token in which the key information is  
accumulated. The key token must include a control vector. The control vector  
defines the length of the key, 8 or 16 bytes (single length or double length). The  
control vector must have the KEY-PART bit set on. The verb returns the  
accumulated key information as a master-key-encrypted value in the updated  
key-token.  
You can use the Key_Token_Build verb to create the internal key-token into which  
the first key-part will be imported.  
On each call to Key_Part_Import, also specify a rule-array keyword to define the  
verb action: FIRST, MIDDLE, LAST, ADD-PART, or COMPLETE.  
With the FIRST keyword, the verb ignores any key information present in the  
input key-token. Each byte of the 8- or 16-byte key-part should have the  
low-order bit set such that the byte has an odd number of one-bits, otherwise  
assuming no other problems, the verb will return reason code 2. Use of the  
FIRST keyword requires that the Load First Key Part command be enabled in  
the access-control system.  
With the MIDDLE keyword, the verb exclusive-ORs the clear key-part with the  
(internally decrypted) key value from the input key-token. Each byte of the 8-  
or 16-byte key-part should have the low-order bit set such that the byte has an  
even number of one-bits. If any byte in the updated key has an even number  
of one bits, and there are no other problems, the verb will return reason  
code 2. Use of the MIDDLE keyword requires that the Combine Key Parts  
command be enabled in the access-control system. The key-part bit remains  
on in the control vector of the updated key token returned from the verb.  
With the LAST keyword, the verb exclusive-ORs the clear key-part with the  
(internally decrypted) key value in the input key-token. Each byte of the 8- or  
16-byte key-part should have the low-order bit set such that the byte has an  
even number of one-bits. If any byte in the updated key has an even number  
of one bits, and there are no other problems, the verb will return reason  
code 2. This use of the LAST keyword requires that the Combine Key Parts  
command be enabled in the access-control system. The key-part bit is set off  
in the control vector of the updated key token returned from the verb.  
With the ADD-PART keyword, the verb exclusive-ORs the clear key-part with  
the (internally decrypted) key value in the input key-token. Each byte of the 8-  
or 16-byte key-part should have the low-order bit set such that the byte has an  
even number of one-bits. If any byte in the updated key has an even number  
5-54 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Part_Import  
of one bits, and there are no other problems, the verb will return reason  
code 2. Use of the ADD-PART keyword requires that the Add Key Part  
command be enabled in the access-control system. The key-part bit remains  
on in the control vector of the updated key token returned from the verb.  
With the COMPLETE keyword, the key-part bit is set off in the control vector of  
the updated key token returned from the verb. Use of the COMPLETE  
keyword requires that the Complete Key Part command be enabled in the  
access-control system. The 16-byte key_part variable must be declared but will  
be ignored by the Coprocessor.  
Notes:  
1. If your input creates a key value with one or more bytes with an even number  
of one bits, that is an out-of-parity key, and the verb returns a reason-code  
value of 2. Many verbs check the parity of keys and, if the key does not have  
odd parity in each key-byte, may return a warning or may terminate without  
performing the requested operation. In general, out-of-parity DATA keys are  
tolerated.  
2. You can enforce a dual-control, split-knowledge security policy by employing  
the FIRST, ADD-PART, and COMPLETE keywords. See “Required  
Commands” on page 5-57. New applications should employ the ADD-PART  
and COMPLETE keywords in lieu of the MIDDLE and LAST keywords in order  
to ensure a separation of responsibilities between someone who can add  
key-part information and someone who can declare that appropriate information  
has been accumulated in a key. Consider using the Key_Test verb to ensure a  
correct key-value has been accumulated prior to using the COMPLETE option  
to mark the key as fully operational.  
Restrictions  
A “replicated key-halves” key (both cleartext halves of a double-length key are  
equal) performs like a single-length DES key and is therefore weaker than a  
double-length key with unequal halves. Note that key parity bits are ignored.  
When the Unrestrict Combine Key Parts command (offset X'027A') is turned off in  
the active role, and when the key information decrypted from the key token is a  
double-length key and has other than all-zero key bits (parity bits are ignored), the  
halves of the key decrypted from the source key-token and the halves of the  
updated key are inspected. The updated key is only returned if either the halves of  
the source and the updated key are both equal or both unequal. When the equality  
of the key-halves of the resulting accumulated key represents a change from the  
equality of the source-key halves, the verb terminates with return code 8 and  
reason code 2062.  
Format  
CSNBKPI  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_part  
key_identifier  
Input  
In/Output String  
String  
16 bytes  
64 bytes  
Chapter 5. DES Key-Management 5-55  
Key_Part_Import  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 5-14. Key_Part_Import Rule_Array Keywords  
Keyword  
Meaning  
Key part (one required)  
FIRST  
Specifies that an initial key-part is provided. The verb returns  
this key-part encrypted by the master key in the key token  
which you supplied.  
ADD-PART  
COMPLETE  
MIDDLE  
Specifies that additional key-part information is provided. The  
verb exclusive-ORs the key part into the key information held  
encrypted in the key token.  
Specifies that the key-part bit shall be turned off in the control  
vector of the key rendering the key fully operational. Note that  
no key_part information is added to the key with this keyword.  
Specifies that an intermediate key-part, which is neither the  
first key-part nor the last key-part, is provided. The verb  
exclusive-ORs the key part into the key information held  
encrypted in the key token. Note that the command control  
point for this keyword is the same as that for the LAST  
keyword and different from that for the ADD-PART keyword.  
LAST  
Specifies that the last key-part is provided. The verb  
exclusive-ORs the key part into the key information held  
encrypted in the key token. The key-part bit is turned off in  
the control vector.  
key_part  
The key_part parameter is a pointer to a string variable containing a key part to  
be entered. The key part may be either 8 or 16 bytes in length. For 8-byte  
keys, place the key part in the high-order bytes of the 16-byte key-part field.  
The information in this variable must be defined but will be ignored by the  
Coprocessor when you use the COMPLETE rule-array keyword.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing the  
internal DES key-token or a key label for a DES key-token. The key token  
must not be null and does supply the control vector for the partial key.  
5-56 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Part_Import  
Required Commands  
The Key_Part_Import verb requires the following commands to be enabled in the  
active role:  
The Load First Key Part command (offset X'001B') with the FIRST keyword.  
The Combine Key Parts command (offset X'001C') with the MIDDLE and  
LAST keywords.  
The Add Key Part command (offset X'0278') with the ADD-PART keyword.  
The Complete Key Part command (offset X'0279') with the COMPLETE  
keyword.  
The Key_Part_Import verb enforces the key-halves restriction documented above  
when the Unrestrict Combine Key Parts command (offset X'027A') is disabled in  
the active role. Enabling this command results in less secure operation and is not  
recommended.  
Chapter 5. DES Key-Management 5-57  
Key_Test  
CCA Release 2.54  
Key_Test (CSNBKYT)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
You use the Key_Test verb to verify the value of a key or key-part. Several  
verification algorithms are supported. The verb supports testing of clear keys,  
enciphered keys, master keys, and key-parts. The verification pattern and the  
verification processes do not reveal the value of an encrypted key, other than  
equivalency of two key values.  
The verb operates in either a GENERATE or VERIFY mode that you specify with a  
rule-array keyword. You also specify the type of key or key-part.  
If you test one of the master keys (keywords KEY-KM, KEY-NKM, or KEY-OKM)  
you may specify which class of master key to test, either symmetric or asymmetric,  
using the SYM-MK and the ASYM-MK rule-array keywords. If you do not select a  
master-key class, the verb requires that both selected asymmetric and symmetric  
master-keys have the same value. There are three verification methods that apply.  
See “Master Key Verification Algorithms” on page D-1.  
For historical reasons, the verification information is passed in two 8-byte variables,  
random_number and verification_pattern. For simplicity, these variables can be two  
8-byte elements of a 16-byte array and processed by your application as a single  
quantity. Both parameters must be coded when calling the API.  
When the verb generates a verification pattern, it returns information in the  
random number and verification pattern variables.  
When the verb tests a verification pattern, it uses information supplied in the  
random number and verification pattern variables. Supply the verification data  
and random number from a previous procedure call to the Key_Test verb. The  
verb returns the verification results in the form of a return code. If verification  
fails, the verb returns a return code of four and reason code of one.  
For certain types of keys, you can specify an alternative key-test algorithm using a  
rule-array keyword. The algorithms are explained in “Cryptographic Key Verification  
Techniques” on page D-1.  
Except for master keys, you can specify the ENC-ZERO algorithm. The  
verification information is provided in the four high-order bytes of the verification  
pattern variable.  
For master keys, you can specify the MDC-4 algorithm.  
Specify the type of key or key-part with a rule-array keyword: master key, clear or  
enciphered, and so forth.  
5-58 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Test  
Restrictions  
Format  
None  
CSNBKYT  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
rule_array_count  
rule_array  
Input  
Input  
Integer  
String  
array  
two, three, or four  
rule_array_count * 8 bytes  
key_identifier  
random_number  
verification_pattern  
Input  
In/Output String  
In/Output String  
String  
64 bytes  
8 bytes  
8 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be two,  
three, or four for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Process rule (one required)  
GENERATE  
VERIFY  
Generates a verification pattern.  
Verifies a verification pattern.  
Key or key-part rule (one required)  
KEY-CLR  
KEY-CLRD  
KEY-ENC  
Requests processing for a single-length clear key or key part.  
Requests processing for a double-length clear key or key part.  
Requests processing for a single-length enciphered key or key  
part supplied in a key token.  
KEY-ENCD  
Requests processing for a double-length enciphered key or  
key part supplied in a key token.  
KEY-KM  
Identifies the master-key register.  
Identifies the new master-key register.  
Identifies the old master-key register.  
KEY-NKM  
KEY-OKM  
Master-key selector (one, optional)  
SYM-MK  
Specifies use of the symmetric master-key registers.  
Specifies use of the asymmetric master-key registers.  
ASYM-MK  
Chapter 5. DES Key-Management 5-59  
Key_Test  
CCA Release 2.54  
Keyword  
Meaning  
Verification-process rule (one, optional)  
ENC-ZERO  
MDC-4  
Specifies use of the “encrypt zeros” method. Use only with  
KEY-CLR, KEY-CLRD, KEY-ENC, or KEY-ENCD keywords.  
Specifies use of the MDC-4 master-key-verification method.  
Use only with KEY-NKM, KEY-KM, or KEY-OKM keywords.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing an  
internal key-token, a key label that identifies an internal key-token record in key  
storage, or a clear key.  
The key token contains the key or the key part used to generate or verify the  
verification pattern.  
When you specify the KEY-CLR keyword, the clear key or key part must be  
stored in bytes 0 to 7 of the key identifier. When you specify the KEY-CLRD  
keyword, the clear key or key part must be stored in bytes 0 to 15 of the key  
identifier. When you specify the KEY-ENC or the KEY-ENCD keyword, the key  
or key part cannot be a clear key.  
random_number  
The random_number parameter is a pointer to a string variable containing a  
number the verb may use in the verification process. When you specify the  
GENERATE keyword, the verb returns the random number. When you specify  
the VERIFY keyword, you must supply the number. With the ENC-ZERO  
method, the random_number variable is not used but must be specified.  
verification_pattern  
The verification_pattern parameter is a pointer to a string variable containing  
the binary verification pattern. When you specify the GENERATE keyword, the  
verb returns the verification pattern. When you specify the VERIFY keyword,  
you must supply the verification pattern.  
With the ENC-ZERO method, the verification data occupies the high-order four  
bytes while the low-order four bytes are unspecified (the data is passed  
between your application and the cryptographic engine but is otherwise  
unused). See “Cryptographic Key Verification Techniques” on page D-1.  
Required Commands  
The Key_Test verb requires the Compute Verification Pattern command (offset  
X'001D') to be enabled in the hardware.  
5-60 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Token_Build  
Key_Token_Build (CSNBKTB)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Token_Build verb assembles an external or internal key-token in  
application storage from information you supply.  
The verb can include a control vector you supply or can build a control vector  
based on the key type and the control vector related keywords in the rule array.  
See Figure 5-4 on page 5-9.  
The Key_Token_Build verb does not perform cryptographic services on any key  
value. You cannot use this verb to change a key or to change the control vector  
related to a key.  
Restrictions  
Format  
Note: Version 1 code, and the Transaction Security System, used a smaller  
master key verification pattern. With Version 2, the verb interface is changed to  
accept an eight-byte verification pattern identified by the  
master_key_verification_pattern parameter.  
CSNBKTB  
return_code  
reason_code  
exit_data_length  
exit_data  
key_token  
key_type  
Output  
Output  
In/Output Integer  
In/Output String  
Output  
Input  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
8 bytes  
String  
String  
Integer  
String  
array  
rule_array_count  
rule_array  
rule_array_count * 8 bytes  
key_value  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
String  
void *  
Integer  
String  
String  
String  
Integer  
String  
16 bytes  
reserved_1*  
reserved_2  
reserved_3  
control_vector  
reserved_4  
reserved_5  
reserved_6  
Integer valued to 0  
null pointer or 0  
null pointer or XL8'00'  
16 bytes  
null pointer or XL8'00'  
null pointer or 0  
null pointer or 8-space  
variable  
master_key_verification_pattern  
Input  
String  
8 bytes  
* Previous implementations used the reserved_1 parameter to point to a four-byte  
integer or string that represented the master key verification pattern. The IBM 4758  
Version 2 CCA Support Program requires this parameter to point to a four-byte  
value equal to binary zero.  
Chapter 5. DES Key-Management 5-61  
Key_Token_Build  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_token  
The key_token parameter is a pointer to a string variable containing the  
assembled key-token.  
Note: This variable cannot contain a key label.  
key_type  
The key_type parameter is a pointer to a string variable containing a keyword  
that defines the key type. The keyword is eight bytes in length, and must be  
left-justified and padded on the right with space characters. Valid key_type  
keywords are shown below:  
CIPHER  
DATAC  
DATAM  
DATAMV  
DECIPHER  
DKYGENKY  
ENCIPHER  
EXPORTER  
IKEYXLAT  
IMPORTER  
IPINENC  
KEYGENKY  
MAC  
OKEYXLAT  
OPINENC  
PINGEN  
PINVER  
SECMSG  
USE-CV  
CVARDEC  
CVARENC  
CVARPINE  
CVARXCVL  
CVARXCVR  
DATA  
MACVER  
For information about key types, see Appendix C, “CCA Control-Vector  
Definitions and Key Encryption” on page C-1.  
Specify the USE-CV keyword to indicate the key type should be obtained from  
the control vector variable.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 5-15 (Page 1 of 2). Key_Token_Build Rule_Array Keywords  
Keyword  
Meaning  
Token type (one required)  
INTERNAL  
EXTERNAL  
Specifies an internal key-token.  
Specifies an external key-token.  
Key status (one, optional)  
KEY  
Indicates the key token is to contain a key. The key_value  
variable contains the key.  
NO-KEY  
Indicates the key token is not to contain a key. This is the  
default key status.  
5-62 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Token_Build  
Figure 5-15 (Page 2 of 2). Key_Token_Build Rule_Array Keywords  
Keyword Meaning  
Control-vector (CV) status (one, optional)  
Note: If you specify the USE-CV keyword in the key_type parameter, use the CV  
keyword here.  
CV  
Obtain the control vector from the variable identified by the  
control_vector parameter.  
NO-CV  
This keyword indicates that a control vector is to be supplied  
based on the key type and control-vector-related keywords.  
This is the default.  
Control-vector keywords (one or more, optional).  
See Figure 5-4 on page 5-9 for the key-usage keywords that  
can be specified for a given key type.  
key_value  
The key_value parameter is a pointer to a string variable containing the  
encrypted key-value incorporated into the encrypted-key portion of the key  
token if you use the KEY rule_array keyword. Single-length keys must be  
left-justified in the variable and padded on the right (low-order) with eight bytes  
of X'00'.  
control_vector  
The control_vector parameter is a pointer to a string variable. If you use the  
CV rule-array keyword, the variable is copied to the control-vector field of the  
key token.  
master_key_verification_pattern  
The master_key_verification_pattern parameter is a pointer to a string variable.  
The value is inserted into the key token when you specify both the KEY and  
INTERNAL keywords in the rule array.  
Required Commands  
The Key_Token_Build verb has no required hardware commands.  
Chapter 5. DES Key-Management 5-63  
Key_Token_Change  
CCA Release 2.54  
Key_Token_Change (CSNBKTC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
Use the Key_Token_Change verb to reencipher a DES key from encryption under  
the old master-key to encryption under the current master-key and to update the  
keys in internal DES key-tokens.  
Note: An application system is responsible for keeping all of its keys in a useable  
form. When the master key is changed, the IBM 4758 product family  
implementations can use an internal key that is enciphered by either the current or  
the old master-key. Before the master key is changed a second time, it is  
important to have a key reenciphered under the current master-key for continued  
use of the key. Use the Key_Token_Change verb to reencipher such a key(s).  
Note: Previous implementations of IBM CCA products had additional capabilities  
with this verb such as deleting key records and key tokens in key storage. Also,  
use of a wild card (*) was supported in those implementations  
Restrictions  
Format  
None  
CSNBKTC  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_identifier  
In/Output String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
5-64 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Token_Change  
Figure 5-16. Key_Token_Change Rule_Array Keywords  
Keyword  
RTCMK  
Meaning  
Reenciphers a DES key to the current master-key in an  
internal key-token in application storage or in key storage If  
the supplied key is already enciphered under the current  
master-key the verb returns a positive response (return code,  
reason code — 0, 0). If the supplied key is enciphered under  
the old master-key, the key will be updated to encipherment  
by the current master-key and the verb returns a positive  
response (return code, reason code — 0, 0). Other cases  
return some form of abnormal response.  
Key_Identifier  
The key_identifier parameter is a pointer to a string variable containing the DES  
internal key-token or the key label of an internal key-token record in key  
storage.  
Required Commands  
If you specify RTCMK keyword, the Key_Token_Change verb requires the  
Reencipher to Current Master Key command (offset X'0090') to be enabled in the  
hardware.  
Chapter 5. DES Key-Management 5-65  
Key_Token_Parse  
CCA Release 2.54  
Key_Token_Parse (CSNBKTP)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Token_Parse verb disassembles a key token into separate pieces of  
information. The verb can disassemble an external key-token or an internal  
key-token in application storage.  
Use the key_token parameter to specify the key token to disassemble.  
The verb returns some of the key-token information in a set of variables identified  
by individual parameters and the remaining key-token information as keywords in  
the rule array.  
Control vector information is returned in keywords found in the rule array when the  
verb can fully parse the control vector. Supported keywords are shown in  
Figure 5-4 on page 5-9. Otherwise, the verb returns return code 4, reason code  
2039.  
The Key_Token_Parse verb performs no cryptographic services.  
Restrictions  
Format  
None.  
CSNBKTP  
return_code  
reason_code  
exit_data_length  
exit_data  
key_token  
key_type  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Output  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
8 bytes  
String  
String  
rule_array_count  
rule_array  
In/Output Integer  
Output  
String  
array  
rule_array_count * 8 bytes  
key_value  
MKVP  
Output  
Output  
String  
Integer  
16 bytes  
(only for a version X'03'  
internal-token)  
reserved_2  
reserved_3  
control_vector  
reserved_4  
reserved_5  
Output  
Output  
Output  
Output  
Output  
Output  
Output  
Integer  
String  
String  
String  
Integer  
String  
String  
8 bytes  
16 bytes  
8 bytes  
reserved_6  
master_key_verification_pattern  
8 bytes  
8 bytes (Only for a version  
X'00' internal token)  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_token  
The key_token parameter is a pointer to a string variable in application storage  
containing an external or internal key-token to be disassembled.  
5-66 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Token_Parse  
Note: You cannot use a key label for a key-token record in key storage. The  
key token must be in application storage.  
key_type  
The key_type parameter is a pointer to a string variable containing a keyword  
defining the key type. The keyword is eight bytes in length, and must be  
left-justified and padded on the right with space characters. Valid key_type  
keywords are shown below:  
CIPHER  
DATAC  
DATAM  
DATAMV  
DECIPHER  
DKYGENKY  
ENCIPHER  
EXPORTER  
IKEYXLAT  
KEYGENKY  
IMPORTER  
IPINENC  
MACVER  
OKEYXLAT  
OPINENC  
PINGEN  
PINVER  
SECMSG  
CVARDEC  
CVARENC  
CVARPINE  
CVARXCVL  
CVARXCVR  
DATA  
MAC  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. This value must be a  
minimum of 3 and should be at least 20 for this verb.  
On input, specify the maximum number of usable array elements that are  
allocated. On output, the verb sets the value to the number of keywords  
returned to the application.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords that expresses the contents of the key token. The keywords are  
eight bytes in length, and are left-justified and padded on the right with space  
characters. The rule_array keywords are shown below:  
Figure 5-17. Key_Token_Parse Rule_Array Keywords  
Keyword  
Meaning  
Token type (one returned)  
INTERNAL  
EXTERNAL  
Specifies an internal key-token.  
Specifies an external key-token.  
Key status (one returned)  
KEY  
Indicates the key token contains a key. The key_value  
variable contains the key.  
NO-KEY  
Indicates the key token does not contain a key.  
Control-vector (CV) status (one returned)  
CV  
The key token specifies that a control vector is present. The  
verb sets the control vector variable with the value of the  
control vector found in the key token.  
NO-CV  
The key token does not specify the presence of a control  
vector. The verb sets the control vector variable with the  
value of the control vector field found in the key token.  
Control-vector keywords  
See Figure 5-4 on page 5-9 for the key-usage keywords that  
can result with a given key type.  
Chapter 5. DES Key-Management 5-67  
Key_Token_Parse  
CCA Release 2.54  
key_value  
The key_value parameter is a pointer to a string variable. If the verb returns  
the KEY keyword in the rule array, the key-value variable contains the 16-byte  
enciphered key.  
MKVP  
The MKVP parameter is a pointer to an integer variable. The verb writes zero  
into the variable except when parsing a version X'03' internal key-token.  
reserved_2/5  
The reserved_2 and reserved_5 parameters are either null pointers or pointers  
to integer variables. If the parameter is not a null pointer, the verb writes zero  
into the reserved variable.  
reserved_3/4  
The reserved_3 and reserved_4 parameters are either null pointers or pointers  
to string variables. If the parameter is not a null pointer, the verb writes eight  
bytes of X'00' into the reserved variable.  
reserved_6  
The reserved_6 parameter is either a null pointer or a pointer to a string  
variable. If the parameter is not a null pointer, the verb writes eight space  
characters into the reserved variable.  
control_vector  
The control_vector parameter is a pointer to a string variable in application  
storage. If the verb returns the NO-CV keyword in the rule array, the key token  
did not contain a control-vector value and the control vector variable will be  
filled with 16 space characters.  
master_key_verification_pattern  
The master_key_verification_pattern parameter is a pointer to a string variable  
in application storage. For version 0 key-tokens that contain a key, the  
eight-byte master key verification pattern will be copied to the variable.  
Otherwise the variable will be filled with eight space characters.  
Required Commands  
The Key_Token_Parse verb has no required hardware commands because it is not  
a cryptographic verb.  
5-68 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Translate  
Key_Translate (CSNBKTR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Key_Translate verb uses one key-encrypting key to decipher an input key and  
then enciphers this key using another key-encrypting key within the secure  
environment.  
Specify the following key tokens to use this verb:  
The external (input) key-token containing the key to be reenciphered.  
The internal key-token containing the IMPORTER or IKEYXLAT  
key-encrypting-key. (The control vector for the IMPORTER key must have the  
XLATE bit set to one.)  
The internal key-token containing the EXPORTER or OKEYXLAT  
key-encrypting-key. (The control vector for the EXPORTER key must have the  
XLATE bit set to one.)  
A 64-byte field for the external (output) key-token.  
The verb builds the output key-token as follows:  
Copies the control vector from the input key-token.  
Verifies that the XLATE bit is set to one if an IMPORTER or EXPORTER  
key-encrypting-key is used.  
Multiply-deciphers the key under a key formed by the exclusive-OR of the  
key-encrypting key and the control vector in the input key-token,  
multiply-enciphers the key under a key formed by the exclusive-OR of the  
key-encrypting key and the control vector in the output key token; then places  
the key in the output key-token.  
Copies other information from the input key-token.  
Calculates a token-validation value and stores it in the output key-token.  
Restrictions  
Format  
None  
CSNBKTR  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
input_key_token  
input_KEK_key_identifier  
output_KEK_key_identifier  
output_key_token  
In/Output Integer  
In/Output String  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
64 bytes  
64 bytes  
Input  
String  
String  
String  
Input  
Output  
Chapter 5. DES Key-Management 5-69  
Key_Translate  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
input_key_token  
The input_key_token parameter is a pointer to a string variable containing an  
external key-token. The external key-token contains the key to be  
reenciphered (translated).  
input_KEK_key_identifier  
The input_KEK_key_identifier parameter is a pointer to a string variable  
containing the internal key-token or the key label of an internal key-token  
record in key storage. The internal key-token contains the key-encrypting key  
used to decipher the key. The internal key-token must contain a control vector  
that specifies an IMPORTER or IKEYXLAT key type. The control vector for an  
IMPORTER key must have the XLATE bit set to one.  
output_KEK_key_identifier  
The output_KEK_key_identifier parameter is a pointer to a string variable  
containing the internal key-token or the key label of an internal key-token  
record in key storage. The internal key-token contains the key-encrypting key  
used to encipher the key. The internal key-token must contain a control vector  
that specifies an EXPORTER or OKEYXLAT key type. The control vector for  
an EXPORTER key must have the XLATE bit set to one.  
output_key_token  
The output_key_token parameter is a pointer to a string variable containing an  
external key-token. The external key-token contains the reenciphered key.  
Required Commands  
The Key_Translate verb requires the Translate Key command (offset X'001F') to  
be enabled in the hardware.  
5-70 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Multiple_Clear_Key_Import  
Multiple_Clear_Key_Import (CSNBCKM)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Multiple_Clear_Key_Import verb multiply-enciphers a clear, single-length or  
double-length DES DATA key under a symmetric master-key.  
You can use this verb to create an internal key-token from a null key token. In this  
case, the control vector will be set to the value of a single-length or double-length  
default control-vector. Or, you can update an existing internal DATA key-token with  
the enciphered value of the clear key.  
You can specify a key label of an existing record in key storage.  
If the clear-key value does not have odd parity in the low-order bit of each byte, the  
reason_code parameter presents a warning.  
Restrictions  
Format  
None  
CSNBCKM  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero or one  
rule_array_count * 8 bytes  
Integer  
String  
array  
clear_key_length  
clear_key  
key_identifier  
Input  
Input  
Output  
Integer  
String  
String  
8 or 16  
clear_key_length bytes  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero or  
one for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 5. DES Key-Management 5-71  
Multiple_Clear_Key_Import  
CCA Release 2.54  
Keyword  
Meaning  
Algorithm (optional)  
DES  
The key should be enciphered under the master key as a  
DES key. This is the default.  
clear_key_length  
The clear_key_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the clear_key variable.  
clear_key  
The clear_key parameter is a pointer to a string variable containing the  
single-length (8-byte) or double-length (16-byte) plaintext DES-key to be  
imported.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing a null  
key-token, or an internal key-token, or the key label of an internal key-token  
record in key storage. A key token is returned to the application, or to key  
storage if the label of a valid key-storage record was specified.  
Required Commands  
The Multiple_Clear_Key_Import verb requires the Clear Key Multiple command  
(offset X'00C3') to be enabled in the hardware.  
5-72 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Decrypt  
PKA_Decrypt (CSNDPKD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The PKA_Decrypt verb decrypts (unwraps) input data using an RSA private-key.  
The decrypted data is examined to ensure it meets RSA DSI PKCS #1 block type 2  
format specifications. See “PKCS #1 Formats” on page D-19.  
Restrictions  
1. A key-usage flag bit (see offset 050 in the private-key section) must be on to  
permit use of the private key in the decryption of a symmetric key.  
2. The RSA private-key modulus size (key size) is limited by the Function Control  
Vector to accommodate potential governmental export and import regulations.  
The verb enforces this restriction.  
|
|
3. Beginning with Release 2.53, a private key with the CLONE attribute is rejected  
by this verb with return code 8, reason code 64 (decimal).  
Format  
CSNDPKD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
source_encrypted_key_length  
source_encrypted_key  
Input  
Input  
Integer  
String  
source_encrypted_key_length  
bytes  
data_structure_length  
data_structure  
Input  
In/Output String  
Integer  
data_structure_length bytes  
private_key_identifier_length  
private_key_identifier  
Input  
Input  
Integer  
String  
private_key_identifier_length  
bytes  
clear_target_key_length  
clear_target_key  
In/Output Integer  
Output String  
clear_target_key_length  
bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 5. DES Key-Management 5-73  
PKA_Decrypt  
CCA Release 2.54  
Keyword  
Recovery method (required)  
PKCS-1.2  
Meaning  
Specifies the method found in RSA DSI PKCS #1 block type  
02 documentation. In the RSA PKCS #1 v2.0 standard, RSA  
terminology describes this as the RSAES-PKCS1-v1_5 format.  
source_encrypted_key_length  
The source_encrypted_key_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the source_encrypted_key variable.  
The maximum size allowed is 256 bytes.  
source_encrypted_key  
The source_encrypted_key parameter is a pointer to a string variable  
containing the input key to be decrypted.  
data_structure_length  
The data_structure_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the data_structure variable. This  
value must be zero.  
data_structure  
The data_structure parameter is a pointer to a string variable. This variable is  
currently ignored.  
private_key_identifier_length  
The private_key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the private_key_identifier variable.  
The maximum size allowed is 2500 bytes.  
private_key_identifier  
The private_key_identifier parameter is a pointer to a string variable containing  
the RSA private-key token, or the label of an RSA private-key token in key  
storage, used to decrypt the source key.  
clear_target_key_length  
The clear_target_key_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the clear_target_key variable. On  
input, this variable specifies the maximum permissible length of the result. On  
output, this verb updates the variable to indicate the length of the returned key.  
The maximum size allowed is 256 bytes.  
clear_target_key  
The clear_target_key parameter is a pointer to a string variable containing the  
decrypted (clear) key returned by this verb.  
Required Commands  
The PKA_Decrypt verb requires the RSA Decipher Key Data command (offset  
X'011F') to be enabled in the hardware.  
5-74 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Encrypt  
PKA_Encrypt (CSNDPKE)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The PKA_Encrypt verb encrypts (wraps) input data using an RSA public key. The  
data that you encrypt may include:  
For keys, the encrypted data can be formatted according to RSA DSI PKCS #1  
block type 2 format specifications. See “PKCS #1 Formats” on page D-19.  
Other data, such as a digital signature, can be RSA-ciphered using the public  
key and the ZERO-PAD option. The data that you provide will be padded on  
the left with zero bits to the modulus length of the public key. When validating  
a digital signature using the ZERO-PAD option, you are responsible for  
formatting of the hash and any other required information.  
Restrictions  
The RSA public-key modulus size (key size) is limited by the Function Control  
Vector to accommodate governmental export and import regulations.  
A message can be encrypted provided that it is smaller than the public key  
modulus.  
The ZERO-PAD rule-array keyword is only available starting with Release 2.50.  
Format  
CSNDPKE  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
clear_source_data_length  
clear_source_data  
Input  
Input  
Integer  
String  
clear_source_data_length  
bytes  
data_structure_length  
data_structure  
public_key_identifier_length  
public_key_identifier  
In/Output Integer  
Input  
Input  
Input  
String  
Integer  
String  
data_structure_length bytes  
public_key_identifier_length  
bytes  
target_data_length  
target_data  
In/Output Integer  
Output String  
target_data_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
Chapter 5. DES Key-Management 5-75  
PKA_Encrypt  
CCA Release 2.54  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Format method (one required)  
PKCS-1.2  
Specifies the method found in RSA DSI PKCS #1 block type  
02 documentation. In the RSA PKCS #1 v2.0 standard, RSA  
terminology describes this as the RSAES-PKCS1-v1_5 format.  
ZERO-PAD  
Places the supplied data in the low-order bit positions of a bit  
string of the same length as the modulus. As required,  
high-order bits are set to zero. Ciphers the resulting bit-string  
with the public key.  
clear_source_data_length  
The clear_source_data_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the clear_source_data variable.  
When using the PKCS-1.2 keyword, the maximum size allowed is 245 bytes  
with a 2048-bit public key. When using the ZERO-PAD keyword, the maximum  
size allowed is 256 bytes with a 2048-bit public key.  
clear_source_data  
The clear_source_data parameter is a pointer to a string variable containing the  
input data to be encrypted.  
data_structure_length  
The data_structure_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the data_structure variable. This  
value must be zero.  
data_structure  
The data_structure parameter is a pointer to a string variable. This variable is  
currently ignored.  
public_key_identifier_length  
The public_key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the public_key_identifier variable.  
The maximum size allowed is 2500 bytes.  
public_key_identifier  
The public_key_identifier parameter is a pointer to a string variable containing  
the RSA public-key token, or the label of an RSA public-key token in key  
storage, used to encrypt the source data.  
target_data_length  
The target_data_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the target_data variable. On input, this variable  
specifies the maximum permissible length of the result. On output, this verb  
updates the variable to indicate the length of the returned data. The maximum  
size allowed is 256 bytes. The data length will be the same as the size of the  
public-key modulus.  
5-76 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Encrypt  
target_data  
The target_data parameter is a pointer to a string variable containing the  
encrypted data returned by the verb. The returned encrypted target-data is the  
same length as the public-key modulus.  
Required Commands  
The PKA_Encrypt verb requires the RSA Public-Key Encipher Clear Key-Data  
command (offset X'011E') to be enabled in the hardware.  
Chapter 5. DES Key-Management 5-77  
PKA_Symmetric_Key_Export  
CCA Release 2.54  
PKA_Symmetric_Key_Export (CSNDSYX)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Symmetric_Key_Export verb enciphers a symmetric DES or CDMF  
default DATA-key using an RSA public key.  
Specify the symmetric key to be exported, the exporting RSA public-key, and a  
rule-array keyword to define the key-formatting method. The DATA control-vector  
must have the default value for a single-length or a double-length key as listed in  
Figure C-2 on page C-3.  
Choose a key-formatting method through a rule array keyword specification. The  
formatted key is then enciphered (wrapped) using the supplied public key.  
Formatting options:  
PKCSOAEP The PKCSOAEP keyword specifies to format a single-length or  
double-length DATA key (or CDMF key) according to the method described in  
the RSA DSI PKCS#1-v2.0 documentation for RSAES-OAEP. See “PKCS #1  
Formats” on page D-19.  
PKCS-1.2 The PKCS-1.2 keyword specifies to format a single-length or  
double-length DATA key (or CDMF key) according to the method described in  
the RSA DSI PKCS #1 documentation for block type 2. In the RSA PKCS #1  
v2.0 standard, RSA terminology describes this as the RSAES-PKCS1-v1_5  
format. See “PKCS #1 Formats” on page D-19.  
ZERO-PAD The ZERO-PAD keyword specifies to format a single-length or  
double-length DATA key (or CDMF key) by padding the key value to the left  
with bits valued to zero.  
Restrictions  
Format  
The RSA public-key modulus size (key size) is limited by the Function Control  
Vector to accommodate potential governmental export and import regulations.  
You can only export a default DATA-key with this verb.  
CSNDSYX  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
source_key_identifier_length  
source_key_identifier  
Input  
Input  
Integer  
String  
source_key_identifier_length  
bytes  
RSA_public_key_token_length  
RSA_public_key_token  
Input  
Input  
Integer  
String  
RSA_public_key_identifier_length  
bytes  
RSA_enciphered_key_length  
RSA_enciphered_key  
In/Output Integer  
Output String  
RSA_enciphered_key_length  
bytes  
5-78 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Symmetric_Key_Export  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Key-formatting method (one required)  
PKCSOAEP  
PKCS-1.2  
Specifies that a DES (or CDMF) DATA-key can be exported  
using the formatting method found in RSA DSI PKCS#1-v2.0  
RSAES-OAEP documentation.  
Specifies that a DES (or CDMF) DATA-key can be exported  
using the formatting method following the rules defined in the  
RSA Laboratories PKCS#1 v2.0 RSAES-PKCS1-v1_5  
specification.  
ZERO-PAD  
Specifies that a DES (or CDMF) DATA-key can be exported  
with the key value padded on the left with bits valued to zero.  
source_key_identifier_length  
The source_key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the source_key_identifier variable.  
The maximum size allowed is 2500 bytes.  
source_key_identifier  
The source_key_identifier parameter is a pointer to a string variable containing  
either an operational key-token or the key label of an operational key-token to  
be exported. The associated control-vector must permit the key to be exported.  
RSA_public_key_token_length  
The RSA_public_key_token_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the RSA_public_key_token variable.  
The maximum size allowed is 2500 bytes.  
RSA_public_key_token  
The RSA_public_key_token parameter is a pointer to a string variable  
containing a PKA96 RSA key-token with the RSA public-key of the remote  
node that is to import the exported key.  
RSA_enciphered_key_length  
The RSA_enciphered_key_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the RSA_enciphered_key variable.  
On output, the variable is updated with the actual length of the  
RSA_enciphered_key variable. The maximum size allowed is 2500 bytes.  
Chapter 5. DES Key-Management 5-79  
PKA_Symmetric_Key_Export  
CCA Release 2.54  
RSA_enciphered_key  
The RSA_enciphered_key parameter is a pointer to a string variable containing  
the exported RSA-enciphered key returned by the verb.  
Required Commands  
The PKA_Symmetric_Key_Export verb requires these commands to be enabled in  
the hardware for exporting various key types:  
Symmetric Key Export PKCS-1.2/OAEP command (offset X'0105') for DATA  
keys using the PKCSOAEP and PKCS-1.2 methods  
Symmetric Key Export ZERO-PAD command (offset X'023E') for DATA keys  
using the ZERO-PAD method.  
5-80 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Symmetric_Key_Generate  
PKA_Symmetric_Key_Generate (CSNDSYG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Symmetric_Key_Generate verb generates a random DES-key and  
enciphers the key value. The key value is enciphered under an RSA public-key for  
distribution to a remote node (that has the associated private key). The key value  
is also multiply-enciphered under either the symmetric master-key or a DES  
key-encrypting-key.  
Rule-array keywords define how the RSA-enciphered key shall be enciphered, the  
length of the generated key, and the type of DES key used to encipher the local  
copy of the key.  
There are three classes of rule-array keywords:  
1. Required keywords to select the formatting method used to expand and secure  
the generated key that is encrypted (wrapped) by the public key. Three of the  
methods deal with DATA keys and the other two are used with key-encrypting  
keys.  
2. Optional key-length keywords to control the length of the generated key.  
3. When generating DATA keys, optional keywords to select the key used to  
encrypt (wrap) the local_enciphered_key.  
Key encryption (wrapping) methods:  
DATA keys, either single-length or double-length, can be generated with the  
default DATA control-vector as defined in Figure C-2 on page C-3. One copy  
of the key, the local_enciphered_key, is returned encrypted by the symmetric  
master key or by an IMPORTER or EXPORTER key-encrypting-key. If you do  
not specify a null key-token, you must supply either the single-length or  
double-length default control vector in a key token.  
The public key is used to wrap another copy of the generated key and returned  
in the RSA_enciphered_key_token. On input you must specify a null  
key-token. You choose how the generated key shall be formatted prior to RSA  
encryption using one of these keywords:  
PKCSOAEP The key is formatted into an “encrypted message” following the  
rules defined in the RSA Laboratories PKCS#1 v2.0 RSAES-OAEP  
specification. See “PKCS #1 Formats” on page D-19.  
PKCS-1.2 The key is formatted into an “encrypted message” following the  
rules defined in the RSA Laboratories PKCS#1 v2.0  
RSAES-PKCS1-v1_5 specification. See “PKCS #1 Formats” on  
page D-19.  
ZERO-PAD The generated key value is extended with zero bits to the left.  
Chapter 5. DES Key-Management 5-81  
PKA_Symmetric_Key_Generate  
CCA Release 2.54  
Key-encrypting keys, either effective single-length or true double-length, are  
generated with the details dependent on the keyword you use to control the key  
formatting technique.  
PKA92  
With this keyword, the verb generates a key-encrypting key and  
returns two copies of the key. You must specify a pair of  
complementary control vectors that conform to the rules for an  
OPEX case as defined for the Key_Generate verb. The control  
vector for one key copy must be from the EXPORTER class while  
the control vector for the other key-copy must be from the  
IMPORTER class.  
The verb enciphers one key copy using the RSA_public_key and  
the key encipherment technique defined in “PKA92 Key Format and  
Encryption Process” on page C-14. The control vector for this key  
is taken from an internal (operational) DES key token that must be  
present on input in the RSA_enciphered_key_token variable.  
The control vector for the local key is taken from a DES key token  
that must be present on input in the local_enciphered_key_identifier  
variable or in the key token identified by the key label in that  
variable.  
Note: A node-identification (EID) value must have been  
established prior to use of the PKA92 keyword. Use the  
Cryptographic_Facility_Control verb to set the EID.  
NL-EPP-5 With this keyword, the verb generates a key-encrypting key and  
returns two copies of the key. The verb enciphers one key copy  
using the key encipherment technique defined by certain OEM  
equipment. See “Encrypting a Key_Encrypting Key in the  
NL-EPP-5 Format” on page C-16. On input, the  
RSA_enciphered_key_token variable must contain a DES internal  
key token that contains a control vector for an IMPORTER  
key-encrypting-key.  
The control vector for the local key is taken from a DES key token  
that must be present on input in the local_enciphered_key_identifier  
variable or in the key token identified by the key label in that  
variable.  
Restrictions  
The permissible key-length of the RSA public key is limited by the value specified in  
the function control vector for RSA encipherment of keys.  
5-82 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Symmetric_Key_Generate  
Format  
CSNDSYG  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one, two, or three  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_encrypting_key_identifier  
RSA_public_key_identifier_length  
RSA_public_key_identifier  
Input  
Input  
Input  
String  
Integer  
String  
64 bytes  
RSA_public_key_identifier_length  
local_enciphered_key_identifier_length  
local_enciphered_key_identifier  
RSA_enciphered_key_token_length  
RSA_enciphered_key_token  
In/Output Integer  
In/Output String  
In/Output Integer  
In/Output String  
RSA_enciphered_key_length  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one,  
two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Key-formatting method (one required)  
PKCSOAEP  
PKCS-1.2  
Specifies the PKCS#1-V2.0 OAEP method of key  
encipherment for DATA keys.  
Specifies the PKCS #1, block type 2 method of key  
encipherment for DATA keys. In the RSA PKCS #1 v2.0  
standard, RSA terminology describes this as the  
RSAES-PKCS1-v1_5 format.  
ZERO-PAD  
PKA92  
Specifies the pad-with-zero-bits-to-the-left method of key  
encipherment for DATA keys.  
Specifies the PKA92 method of key encipherment for  
key-encrypting keys.  
NL-EPP-5  
Specifies the NL-EPP-5 process of key encipherment for  
key-encrypting keys. See “Encrypting a Key_Encrypting Key  
in the NL-EPP-5 Format” on page C-16.  
Key length (optional use with PKA92 or NL-EPP-5)  
SINGLE-R For key-encrypting keys, specifies that a generated  
key-encrypting key is to have equal left and right halves and  
thus perform as a single-length key. Otherwise, the two  
key-halves will be independent random values.  
Chapter 5. DES Key-Management 5-83  
PKA_Symmetric_Key_Generate  
CCA Release 2.54  
Keyword  
Meaning  
Key length (optional use with PKCSOAEP, PKCS-1.2, and ZERO-PAD)  
SINGLE  
KEYLN8  
Specifies that an exported DATA key should be single length.  
This the default.  
DOUBLE  
KEYLN16  
Specifies that an exported DATA key should be double length.  
DES encipherment (optional use with PKCSOAEP, PKCS-1.2, and ZERO-PAD)  
OP  
Enciphers one key copy with the symmetric master-key. This  
is the default.  
IM  
Enciphers one key copy using the IMPORTER  
key-encrypting-key specified with the  
key_encrypting_key_identifier parameter.  
EX  
Enciphers one key copy using the EXPORTER  
key-encrypting-key specified with the  
key_encrypting_key_identifier parameter.  
key_encrypting_key_identifier  
The key_encrypting_key_identifier parameter is a pointer to a string variable  
containing the key token or the key label of a key token in key storage with the  
key-encrypting key used to encipher one generated-key copy for DES-based  
key distribution.  
RSA_public_key_identifier_length  
The RSA_public_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
RSA_public_key_identifier variable. The maximum size allowed is 2500 bytes.  
RSA_public_key_identifier  
The RSA_public_key_identifier parameter is a pointer to a string variable  
containing a PKA96 RSA key-token with the RSA public-key of the remote  
node that will import the exported key.  
local_enciphered_key_identifier_length  
The local_enciphered_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
local_enciphered_key_identifier variable. The maximum size allowed is 2500.  
However, this value should be 64 as in current CCA practice a DES key-token  
or a key label is always a 64-byte structure.  
local_enciphered_key_identifier  
The local_enciphered_key_identifier parameter is a pointer to a string variable  
containing either a key name or a key token. The control vector for the local  
key is taken from the identified key token. On output, the generated key is  
inserted into the identified key token.  
On input, you must specify a token type consistent with your choice of local-key  
encryption. If you specify IM or EX, you must specify an external key-token.  
Otherwise, specify an internal key-token or a null key-token.  
When PKCSOAEP, PKCS-1.2, or ZERO-PAD is specified, a null key-token can  
be specified. In this case, a DATA key will be returned. For an internal key  
(OP), a default DATA control-vector is returned in the key token. For an  
external key (IM or EX), the control vector is set to null.  
5-84 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Symmetric_Key_Generate  
RSA_enciphered_key_token_length  
The RSA_enciphered_key_token_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
RSA_enciphered_key_token variable. On output, the variable is updated with  
the actual length of the RSA_enciphered_key_token variable. The maximum  
size allowed is 2500 bytes.  
RSA_enciphered_key_token  
The RSA_enciphered_key_token parameter is a pointer to a string variable  
containing the generated RSA-enciphered key returned by the verb. If you  
specify PKCS-1.2 or ZERO-PAD, on input you should specify a null key token.  
If you specify PKA92 or NL-EPP-5, on input specify an internal (operational)  
DES key-token.  
Required Commands  
The PKA_Symmetric_Key_Generate verb requires these command(s) to be  
enabled in the hardware depending on the key-formatting method:  
Symmetric Key Generate PKCS-1.2/OAEP command (command offset  
X'023F') for DATA keys using the PKCSOAEP and PKCS-1.2 methods  
Symmetric Key Generate ZERO-PAD command (command offset X'023C') for  
DATA keys using the ZERO-PAD method.  
PKA92 Symmetric Key Generate command (command offset X'010D')  
NL-EPP-5 Symmetric Key Generate command (command offset X'010E')  
Chapter 5. DES Key-Management 5-85  
PKA_Symmetric_Key_Import  
CCA Release 2.54  
PKA_Symmetric_Key_Import (CSNDSYI)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Symmetric_Key_Import verb recovers a symmetric DES (or CDMF) key  
that is enciphered by an RSA public key. The verb deciphers the RSA-enciphered  
symmetric-key to be imported by using an RSA private-key, then multiply-enciphers  
the symmetric DES-key using the master key and a control vector.  
You specify the operational importing RSA private-key, the RSA-enciphered DES  
key to be imported, and a rule-array keyword to define the key-formatting method.  
Several methods for recovering keys are available. You select a method through  
the use of a rule-array keyword:  
For processing single-length or double-length DATA keys, use one of the these  
three methods. The control vector in any non-NULL key token identified by the  
target_key_identifier parameter must specify the default value for a DATA  
control-vector corresponding to the key length found in the decrypted information.  
See Figure C-2 on page C-3.  
PKCSOAEP The PKCSOAEP keyword specifies that after decrypting the  
RSA_enciphered_key variable, the format is checked for conformance with  
RSA DSI PKCS#1-v2.0 RSAES-OAEP specifications for a single-length or  
double-length key. See “PKCS #1 Formats” on page D-19.  
PKCS-1.2 The PKCS-1.2 keyword specifies that after decrypting the  
RSA_enciphered_key variable, the format is checked for conformance with  
RSA DSI PKCS #1 block type 2 specifications for a single-length or  
double-length key. In the RSA PKCS #1 v2.0 standard, RSA terminology  
describes this as the RSAES-PKCS1-v1_5 format. See “PKCS #1 Formats” on  
page D-19.  
ZERO-PAD The ZERO-PAD keyword specifies that after decrypting the  
RSA_enciphered_key variable, the format is checked to ensure that all bytes to  
the left of either a single-length or a double-length key are zero bits.  
For key-encrypting keys:  
PKA92 Key-encrypting keys and their control vectors are deciphered using the  
method employed in the Transaction Security Systems PKA92 implementation.  
See “PKA92 Key Format and Encryption Process” on page C-14.  
A node-identification (EID) value must be established prior to use of this verb.  
Under the PKA92 scheme, the EID values at the exporting and importing  
nodes must be different. Use the Cryptographic_Facility_Control verb to set  
the EID.  
Note: This implementation will import IPINENC, OPINENC, PINGEN, and  
PINVER key types when formatted according to the PKA92 scheme. However,  
the implementation does not provide a means for enciphering these key types  
in PKA92 format. This extension to CCA is considered non-standard, and may  
not be present in other CCA implementations such as the implementation on  
IBM eServer zSeries (S/390).  
5-86 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Symmetric_Key_Import  
Restrictions  
1. Private key key-usage controls can prevent use of specific private keys in this  
verb. See page 3-7. A key-usage flag bit (see offset 050 in the private-key  
section) must be on to permit use of the private key in the decryption of a  
symmetric key.  
2. The RSA private-key modulus size (key size) is limited by the Function Control  
Vector to accommodate potential governmental export and import regulations.  
3. Under PKA92, the EID enciphered with a key-encrypting key cannot be the  
same as the EID of the importing cryptographic engine.  
4. Other IBM implementations of this verb may not support:  
Key types other than a default DATA control-vector  
Use of a key label with the target key identifier.  
Check the product-specific literature for restrictions.  
|
|
5. Beginning with Release 2.53, a private key with the CLONE attribute is rejected  
by this verb with return code 8, reason code 64 (decimal).  
Format  
CSNDSYI  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
RSA_enciphered_key_length  
RSA_enciphered_key  
RSA_private_key_identifier_length  
RSA_private_key_identifier  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
RSA_enciphered_key_length  
RSA_private_key_identifier_length  
bytes  
target_key_identifier_length  
target_key_identifier  
In/Output Integer  
In/Output String  
target_key_identifier_length  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 5. DES Key-Management 5-87  
PKA_Symmetric_Key_Import  
CCA Release 2.54  
Keyword  
Meaning  
RSA key-encipherment method (one required)  
PKCSOAEP  
PKCS-1.2  
Specifies the method found in RSA DSI PKCS#1-v2.0  
RSAES-OAEP documentation.  
Specifies the method found in RSA DSI PKCS#1-v2.0  
RSAES-PKCS1-v1_5 specification.  
ZERO-PAD  
Specifies that a DES (or CDMF) DATA-key can be imported  
with the key value padded from the left with bits valued to  
zero.  
PKA92  
Specifies the PKA92 method of key encipherment for  
key-encrypting keys.  
RSA_enciphered_key_length  
The RSA_enciphered_key_length parameter is a pointer to an integer  
containing the number of bytes of data in the RSA_enciphered_key variable.  
The maximum size allowed is 2500 bytes.  
RSA_enciphered_key  
The RSA_enciphered_key parameter is a pointer to a string variable containing  
the key being imported.  
RSA_private_key_identifier_length  
The RSA_private_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
RSA_private_key_identifier variable. The maximum size allowed is 2500 bytes.  
RSA_private_key_identifier  
The RSA_private_key_identifier parameter is a pointer to a string variable  
containing a key label or a PKA96 key-token with the internal RSA private-key  
to be used to decipher the RSA-enciphered key.  
target_key_identifier_length  
The target_key_identifier_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the target_key_identifier variable. On  
output, the value is updated with the actual length of the target_key_identifier  
variable returned by the verb. The maximum size allowed is 2500 bytes.  
target_key_identifier  
The target_key_identifier parameter is a pointer to a string variable containing  
either a key label, an internal key-token, or a null key-token. Any identified  
internal key-token must contain a control vector that conforms to the  
requirements of the key that is imported. For example, if the PKCS-1.2  
keyword is used in the rule array, the key token must contain a default-value,  
DATA control-vector. The imported key is returned in a key token identified  
through this parameter.  
Required Commands  
The PKA_Symmetric_Key_Import verb requires these commands to be enabled in  
the hardware for importing various key types:  
Symmetric Key Import PKCS-1.2/OAEP command (command offset X'0106')  
for for DATA keys using the PKCSOAEP and PKCS-1.2 methods  
5-88 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Symmetric_Key_Import  
Symmetric Key Import ZERO-PAD command (command offset X'023D') for  
DATA keys using the ZERO-PAD methods  
PKA92 Symmetric Key Import command (command offset X'0235') when  
importing key-generating keys using the PKA92 method  
PKA92 Symmetric Key Import command (command offset X'0236') when  
importing PINGEN, PINVER, IPINENC, or OPINENC keys using the PKA92  
method.  
Chapter 5. DES Key-Management 5-89  
Prohibit_Export  
CCA Release 2.54  
Prohibit_Export (CSNBPEX)  
Platform/  
Product  
OS/2  
AIX  
NT  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Prohibit_Export verb modifies an operational key than can be exported so that  
it can no longer be exported.  
The verb does the following:  
Multiply-deciphers the key under a key formed by the exclusive-OR of the  
master key and the control vector.  
Turns off the export bit in the control vector  
Multiply-enciphers the key under a key formed by the exclusive-OR of the  
master key and the control vector. The key and the modified control vector are  
stored in the key token.  
Restrictions  
Format  
None  
CSNBPEX  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
key_identifier  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing the  
internal key-token, or the key label of an internal key-token record in key  
storage.  
Required Commands  
The Prohibit_Export verb requires the Lower Export Authority command (offset  
X'00CD') to be enabled in the hardware.  
5-90 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Random_Number_Generate  
Random_Number_Generate (CSNBRNG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Random_Number_Generate verb generates a random number for use as an  
initialization vector, clear key, or clear key-part.  
You specify whether the random number is 64 bits, or 56 bits with the low-order bit  
in each of the eight bytes adjusted for even or odd parity. The verb returns the  
random number in an eight-byte binary field.  
Because the Random_Number_Generate verb uses cryptographic processes, the  
quality of the output is better than that which higher-level language compilers  
typically supply.  
Restrictions  
Format  
None  
CSNBRNG  
return_code  
reason_code  
exit_data_length  
exit_data  
form  
random_number  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Output  
Integer  
Integer  
exit_data_length bytes  
8 bytes  
8 bytes  
String  
String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
form  
The form parameter is a pointer to a string variable containing a keyword to  
select the characteristic of the random number. The keyword is eight bytes in  
length, and must be left-justified and padded on the right with space characters.  
The keywords are shown below:  
Figure 5-18. Key_Token_Build Form Keywords  
Keyword  
Meaning  
Generation type (one required)  
RANDOM  
ODD  
Requests the generation of a 64-bit random number.  
Requests the generation of a 56-bit, odd parity, random  
number.  
EVEN  
Requests the generation of a 56-bit, even parity, random  
number.  
Chapter 5. DES Key-Management 5-91  
Random_Number_Generate  
CCA Release 2.54  
random_number  
The random_number parameter is a pointer to a string variable containing the  
random number returned by the verb.  
Required Commands  
The Random_Number_Generate verb requires the Generate Key command (offset  
X'008E') to be enabled in the hardware.  
5-92 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 6. Data Confidentiality and Data Integrity  
This chapter describes the verbs that use the Data Encryption Standard (DES)  
algorithm to encrypt and decrypt data and to generate and verify a message  
authentication code (MAC).  
Figure 6-1. Data Confidentiality and Data Integrity Verbs  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
Decipher  
6-5  
6-8  
Deciphers data  
CSNBDEC  
CSNBENC  
CSNBMGN  
CSNBMVR  
E
E
E
E
Encipher  
Enciphers data  
MAC_Generate  
MAC_Verify  
6-11  
6-14  
Generates a message authentication code (MAC)  
Verifies a MAC.  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Encryption and Message Authentication Codes  
This section explains how to use the services described in this chapter to ensure  
the confidentiality of data through encryption, and to ensure the integrity of data  
through the use of Message Authentication Codes (MAC).  
Note: See Chapter 4, “Hashing and Digital Signatures” on page 4-1 for  
information about other ways to ensure data integrity.  
Ensuring Data Confidentiality  
You can use the Encipher verb to convert plaintext to ciphertext, and the Decipher  
verb to reverse the process to convert ciphertext back to plaintext. These services  
use the DES data encryption algorithm. DES operates on blocks of 64 bits (8  
bytes). Based on the length of the DES key that you specify, the Encipher and  
Decipher verbs will perform either basic (single) DES or triple-DES1. See  
“Single-DES and Triple-DES for General Data” on page D-6.  
If you know that your data will always be a multiple of 8 bytes, you can request the  
use of the cipher block chaining mode of encryption, designated CBC. In this mode  
of encryption, the enciphered result of encrypting one block of plaintext is  
exclusive-ORed with the subsequent block of plaintext prior to enciphering the  
second block. This process is repeated through the processing of your plaintext.  
The process is reversed in decryption. See “Ciphering Methods” on page D-5.  
Note that if some portion of the ciphertext is altered, the CBC decryption of that  
block and the subsequent block will not recover the original plaintext. Other blocks  
of plaintext will be correctly recovered. CBC encryption is used to disguise patterns  
in your data that could be seen if each data block was encrypted by itself.  
In general, data to be ciphered is not a multiple of eight bytes. In this case, you  
need to adopt a strategy for the last block of data. The Encipher and Decipher  
1
Note that CCA implementations always encipher DES keys and PIN blocks with “triple-DES.”  
Copyright IBM Corp. 1997, 2005  
6-1  
CCA Release 2.54  
verbs also support the ANSI X9.23 mode of encryption. In X9.23 encryption, at  
least one byte of data and up to eight bytes of data are always added to the end of  
your plaintext. The last of the added bytes is a binary value equal to the number of  
added bytes. The ANSI X9.23 process ensures that the enciphered data is always  
a multiple of eight bytes as required for CBC encryption. In X9.23 decryption, the  
padding is removed from the decrypted plaintext.  
Whenever the first block of plaintext has a predictable value, it is important to  
modify the first block of data prior to encryption to deny an adversary a known  
plaintext-ciphertext pair. There are two common approaches:  
Use an initialization vector  
Prepend your data with 8 bytes of random data, an initial text sequence.  
An initialization vector is exclusive-ORed with the first block of plaintext prior to  
encrypting the result. The initialization vector is exclusive-ORed with the decryption  
of the first block of ciphertext to correctly recover the original plaintext. You must,  
of course, have a means of passing the value of the initialization vector from the  
encryption process to the decryption process. A common solution to the problem is  
to pass the initialization vector as an encrypted quantity during key agreement  
between the encrypting and decrypting processes. You specify the value of an  
initialization vector when you invoke the Encipher and the Decipher verbs.  
If the procedure for agreeing on a key does not readily result in passing of an  
encrypted quantity that can serve as the initialization vector, then you can add eight  
bytes of random data to the start of your plaintext. Of course, the decrypting  
process must remove this initial text sequence as it recovers your plaintext. An  
initialization vector valued to binary zero is used in this case.  
The key used to encrypt or decrypt your data is specified in a key token. The  
control vector for the key must be of the general class DATA2 or CIPHER-class  
(control vector bits 8 to 15 equal to X'00' or X'03', respectively). In addition to  
the class of key defined in CV bits 8 to 14, CV bit 18 must also be on to encipher  
data while CV bit 19 must also be on to decipher data. See Appendix C, “CCA  
Control-Vector Definitions and Key Encryption.” DATA keys can participate in both  
enciphering and MACing while CIPHER-class keys only perform in ciphering  
operations.  
If an invocation of the Encipher or the Decipher verb should include use of the  
initialization vector value, use the keyword INITIAL. If there is more data that is a  
logical extension of preceding data, you can use the keyword CONTINUE. In this  
case, the initialization vector value is not used, but the enciphered value of the last  
block of data from a prior ciphering verb is taken from the chaining_vector save  
area that you must provide with each use of the ciphering verbs. Each portion of  
your data must be a multiple of eight bytes and you must use the CBC encryption  
mode. You can use X9.23 keyword with the final invocation of the ciphering verbs  
if your processes use this method to accommodate data that can be other than a  
multiple of eight bytes.  
2
Uppercase letters are used for DATA to distinguish the meaning from a more general sense in which the term data keys means  
keys used for ciphering and MACing. In this publication, DATA means keys whose control vector bits 8 to 15 are valued to X'00'.  
6-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Ensuring Data Integrity  
CCA offers three classes of services for ensuring data integrity:  
Message authentication code (MAC) techniques based on the DES algorithm  
Hashing techniques  
Digital signature techniques.  
This chapter includes the MAC verbs. For information on using hashing or digital  
signatures to ensure the integrity of data, see Chapter 4, “Hashing and Digital  
Signatures.”  
The MAC_Generate and the MAC_Verify verbs support message authentication  
code generation and verification consistent with ANSI standard X9.9,  
ISO DP 8731, Part I, (ISO/IEC 9797-1, Algorithm 1) and ANSI X9.19 Optional  
Procedure 1 (ISO/IEC 9797-1, Algorithm 3). These methods together support both  
single-length and double-length keys. If the specified key is double length, the  
ANSI X9.19 algorithm will be performed; otherwise, ANSI X9.9 will be performed.  
See Appendix C, “CCA Control-Vector Definitions and Key Encryption.”  
The verbs also support the message padding technique employed with EMV smart  
card messages. The verbs perform EMV-required padding when you supply a  
rule-array keyword EMVMAC or EMVMACD consistent with the specified  
single-length or double-length key.  
Both the DATA-class and the MAC/MACVER key types can be used. Control  
vector bit 20 must be on for keys used in the MAC_Generate verb. Control vector  
bit 21 must be on for keys used in the MAC_Verify verb.  
For additional information about MAC calculation methods, see “MAC Calculation  
Methods” on page D-13.  
You can employ MAC values with four-byte, six-byte, or eight-byte lengths (32, 48,  
or 64 bits) by using the MACLEN4, MACLEN6, or MACLEN8 keywords in the rule  
array. MACLEN4 is the default.  
When generating or verifying a 32-bit MAC, exchange the MAC in one of these  
ways:  
Binary, in four bytes (the default method)  
Eight hexadecimal characters, invoked using the HEX-8 keyword  
Eight hexadecimal characters with a space character between the fourth and  
fifth hex characters invoked using the HEX-9 keyword.  
For details about MAC services, see the MAC_Generate verb on page 6-11 and the  
MAC_Verify verb on page 6-14.  
MACing Segmented Data  
The MAC services described in this chapter allow you to divide a string of data into  
parts, and generate or verify a MAC in a series of calls to the appropriate verb.  
This can be useful when it is inconvenient or impossible to bring the entire string  
into memory. For example, you might wish to MAC the entire contents of a data  
set tens or hundreds of megabytes in length. The length of the data in each  
procedure-call is restricted only by the operating environment and the particular  
verb. For restrictions to a verb, see the “Restriction” section of the verb  
descriptions later in this chapter.  
Chapter 6. Data Confidentiality and Data Integrity 6-3  
CCA Release 2.54  
In each procedure call, a segmenting-control keyword indicates whether the call  
contains the first, middle, or last unit of segmented data; the chaining_vector  
parameter specifies the work area that the verb uses. (The default  
segmenting-control keyword ONLY specifies that segmenting is not used.)  
6-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Decipher  
Decipher (CSNBDEC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Decipher verb uses the Data Encryption Standard (DES) or the Commercial  
Data Masking Facility (CDMF) algorithm and a cipher key to decipher data  
(ciphertext). This verb results in data called plaintext.  
Performance can be enhanced if you align the start of the plaintext and ciphertext  
variables on a four-byte boundary.  
Both single-DES and triple-DES are performed based on the length of the key.  
DATA, CIPHER, and DECIPHER key types can be used. For additional information  
about the ciphering verbs, see “Ensuring Data Confidentiality” on page 6-1.  
Restrictions  
The starting address of plaintext cannot begin within the ciphertext variable.  
The text_length variable is restricted to a maximum value of 32MB - 8 bytes, and  
to 64MB - 8 bytes in the OS/400 environment.  
The installed Function Control Vector regulates the maximum data ciphering  
capability to one of CDMF, single-DES, or triple-DES.  
Format  
CSNBDEC  
return_code  
reason_code  
exit_data_length  
exit_data  
key_identifier  
text_length  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
In/Output Integer  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
String  
ciphertext  
Input  
Input  
Input  
Input  
String  
String  
Integer  
String  
array  
text_length bytes  
8 bytes  
zero, one, two, or three  
rule_array_count * 8 bytes  
initialization_vector  
rule_array_count  
rule_array  
chaining_vector  
plaintext  
In/Output String  
Output String  
18 bytes  
text_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing an  
internal key-token or a key label of an internal key-token record in key storage.  
text_length  
The text_length parameter is a pointer to an integer variable. On input, the  
text_length variable contains the number of bytes of data in the ciphertext  
variable. On output, the text_length variable contains the number of bytes of  
data in the plaintext variable.  
Chapter 6. Data Confidentiality and Data Integrity 6-5  
Decipher  
CCA Release 2.54  
ciphertext  
The ciphertext parameter is a pointer to a string variable containing the text to  
be deciphered.  
initialization_vector  
The initialization_vector parameter is a pointer to a string variable containing  
the initialization_vector the verb uses with the input data.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. This value must be zero,  
one, two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
For an adapter that supports both DES and CDMF, you can choose the  
encryption process.  
The rule_array keywords are shown below:  
Keyword  
Meaning  
Deciphering method (one, optional)  
CBC  
Specifies cipher-block chaining. The data must be a multiple  
of eight bytes. This is the default.  
X9.23  
Specifies cipher-block chaining with one to eight bytes of  
padding. This is compatible with the requirements in ANSI  
Standard X9.23.  
ICV (one, optional)  
INITIAL  
Specifies use of the initialization vector from the key token or  
the initialization vector to which the initialization_vector  
parameter points. This is the default.  
CONTINUE  
Specifies use of the initialization vector to which the  
chaining_vector parameter points. The CONTINUE keyword  
is not valid with with the X9.23 keyword.  
Decryption process (one, optional)  
DES  
Specifies use of the DES ciphering algorithm. If an adapter  
does not support DES general data-decipherment, the verb is  
rejected. This is the default on an adapter that supports both  
DES and CDMF.  
CDMF  
Specifies use of the CDMF ciphering algorithm.  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing the  
segmented data between calls by the security server. The output chaining  
vector is contained in bytes zero through seven.  
Note: The application program must not change the data in this variable.  
plaintext  
The plaintext parameter is a pointer to a string variable containing the plaintext  
returned by the verb. The starting address of plaintext variable cannot begin  
within the ciphertext variable. The verb updates the text_length variable to the  
6-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Decipher  
length of the plaintext when it returns. The length will be different when  
padding is removed.  
Required Commands  
The Decipher verb requires the Decipher command (offset X'000F') to be enabled  
in the hardware.  
Chapter 6. Data Confidentiality and Data Integrity 6-7  
Encipher  
CCA Release 2.54  
Encipher (CSNBENC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Encipher verb uses the DES algorithm and a secret key to encipher data. This  
verb returns data called ciphertext.  
The returned ciphertext can be as many as eight bytes longer than the plaintext  
due to padding. Ensure the ciphertext variable is large enough to receive the  
returned data.  
Performance can be enhanced by aligning the start of the plaintext and ciphertext  
variables on four-byte boundaries.  
DATA, CIPHER, and ENCIPHER key-types can be used. Both single-DES and  
triple-DES are performed based on the length of the key. For additional information  
about the ciphering verbs, see “Ensuring Data Confidentiality” on page 6-1.  
Restrictions  
Format  
The text_length variable is restricted to a maximum value of 32MB - 8 bytes and to  
64MB - 8 bytes in the OS/400 environment.  
The installed Function Control Vector regulates the maximum data ciphering  
capability to one of CDMF, single-DES, or triple-DES.  
CSNBENC  
return_code  
reason_code  
exit_data_length  
exit_data  
key_identifier  
text_length  
Output  
Output  
In/Output Integer  
In/Output String  
In/Output String  
In/Output Integer  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
plaintext  
Input  
Input  
Input  
Input  
String  
String  
Integer  
String  
array  
text_length bytes  
8 bytes  
zero, one, two, or three  
rule_array_count * 8 bytes  
initialization_vector  
rule_array_count  
rule_array  
pad_character  
chaining_vector  
ciphertext  
Input  
In/Output String  
Output String  
Integer  
18 bytes  
updated text_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing an  
internal key-token or the key label of an internal key-token record in key  
storage.  
6-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encipher  
text_length  
The text_length parameter is a pointer to an integer variable. On input, the  
text_length variable contains the number of bytes of data in the cleartext  
variable. On output, the text_length variable contains the number of bytes of  
data in the ciphertext variable.  
plaintext  
The plaintext parameter is a pointer to a string variable containing the text to be  
enciphered.  
initialization_vector  
The initialization_vector parameter is a pointer to a string variable containing  
the initialization_vector the verb uses with the input data.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Ciphering method (one, optional)  
CBC  
Specifies cipher-block chaining. The data must be a multiple  
of eight bytes. This is the default.  
X9.23  
Specifies cipher block chaining with one to eight bytes of  
padding. This is compatible with the requirements in ANSI  
Standard X9.23.  
ICV (one, optional)  
INITIAL  
Specifies use of the initialization vector from the key token or  
the initialization vector to which the initialization_vector  
parameter points. This is the default.  
CONTINUE  
Specifies use of the initialization vector to which the  
chaining_vector parameter points. The CONTINUE keyword  
is not valid with the X9.23 keyword.  
Encryption process (one, optional)  
DES  
Specifies use of the DES ciphering algorithm. If an adapter  
does not support DES general data encipherment, the verb is  
rejected. This is the default on an adapter that supports both  
DES and CDMF.  
CDMF  
Specifies use of the CDMF ciphering algorithm.  
pad_character  
The pad_character parameter is a pointer to an integer variable containing a  
value used as a padding character. The value must be in the range from 0 to  
255. When you use the X9.23 ciphering method, the security server extends  
the plaintext with a count byte and padding bytes as required.  
Chapter 6. Data Confidentiality and Data Integrity 6-9  
Encipher  
CCA Release 2.54  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing a  
work area that the security server uses to carry segmented data between  
procedure-calls.  
Note: The application program must not change the data in this variable.  
ciphertext  
The ciphertext parameter is a pointer to a string variable containing the  
enciphered text returned by the verb. The starting address of the ciphertext  
variable cannot begin within the plaintext variable. The returned ciphertext  
might be up to eight bytes longer than the plaintext because of padding. The  
verb updates the text_length variable to the length of the ciphertext when it  
returns. The length will be different when padding is added.  
Required Commands  
The Encipher verb requires the Encipher command (offset X'000E') to be enabled  
in the hardware.  
6-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
MAC_Generate  
MAC_Generate (CSNBMGN)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The MAC_Generate verb generates a message authentication code (MAC) for a  
text string that you supply. For additional information about using the MAC  
generation and verification verbs, see “Ensuring Data Integrity” on page 6-3.  
Performance can be enhanced by aligning the start of the text variable on a  
four-byte boundary.  
You specify the message authentication code process through the choice of a  
rule-array keyword. Note that there are defaults based on your use of a  
single-length or double-length key.  
X9.1-1  
ANSI X9.9-1 procedure, by default when you supply a single-length key. This is  
the same as ISO/IEC 9797-1, Algorithm 1.  
X9.19OPT  
ANSI X9.19 Optional Procedure, by default when you supply a double-length key.  
This is the same as ISO/IEC 9797-1, Algorithm 3.  
EMVMAC and EMVMACD  
EMV authentication processes.3 The verb extends the text you supply with X'80'  
and the minimum number (0...7) bytes of X'00' for the extended message to be  
a multiple of 8 bytes in length. The MAC is computed based on ISO/IEC 9797-1,  
Algorithm 1 or 3 depending on key length. When specifying a single-length key,  
use EMVMAC. When specifying a double-length key, use EMVMACD.  
Note: The EMV specification permits the MAC to be 4, 5, ..., 8 bytes in length.  
The MAC_Verify verb only supports MAC lengths of 4, 6, and 8 bytes.  
You can specify any of these key types: DATA, DATAM, or MAC.  
Restrictions  
The text_length variable must be at least 8 bytes, and less than 32MB - 8 bytes, or  
less than 64MB - 8 bytes in the OS/400 environment.  
Support for EMVMAC and EMVMACD begins with Release 2.51.  
3
See the EMV 4.0 Book 2, Annex A.1.2, for information about this form of MAC generation.  
Chapter 6. Data Confidentiality and Data Integrity 6-11  
MAC_Generate  
CCA Release 2.54  
Format  
CSNBMGN  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
key_identifier  
text_length  
text  
rule_array_count  
rule_array  
Input  
Input  
Input  
Input  
Input  
String  
Integer  
String  
Integer  
String  
array  
64 bytes  
text_length bytes  
zero, one, two, or three  
rule_array_count * 8 bytes  
chaining_vector  
MAC  
In/Output String  
Output String  
18 bytes  
4, 6, 8, or 9 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing an  
internal key-token or the key label of an internal key-token record in key  
storage. Use either MAC, DATA, or DATAM key-types. Keys can be either  
single length or double length.  
text_length  
The text_length parameter is a pointer to an integer variable containing the  
number of data bytes in the text variable.  
text  
The text parameter is a pointer to a string variable containing the text that the  
hardware uses to calculate the MAC.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
MAC ciphering-method (one, optional)  
EMVMAC  
EMVMACD  
X9.9-1  
Specifies the EMV-related message-padding and calculation  
method. You must also specify a single-length key.  
Specifies the EMV-related message-padding and calculation  
method. You must also specify a double-length key.  
Specifies the ANSI X9.9-1 and X9.19 Basic Procedure. This  
is the default for a single-length key.  
X9.19OPT  
Specifies the ANSI X9.19 Optional Procedure. This is the  
default for a double-length key.  
6-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
MAC_Generate  
Keyword  
Meaning  
Segmenting control (one, optional)  
ONLY  
FIRST  
MIDDLE  
LAST  
Specifies the application program does not use segmenting.  
This is the default.  
Specifies this is the first segment of data from the application  
program.  
Specifies this is an intermediate segment of data from the  
application program.  
Specifies this is the last segment of data from the application  
program.  
MAC length and presentation (one, optional)  
MACLEN4  
MACLEN6  
MACLEN8  
HEX-8  
Specifies a four-byte MAC. This is the default.  
Specifies a six-byte MAC.  
Specifies an eight-byte MAC.  
Specifies a four-byte MAC and presents it as eight  
hexadecimal characters.  
HEX-9  
Specifies a four-byte MAC and presents it as two groups of  
four hexadecimal characters separated by a space character.  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing a  
work area the security server uses to carry segmented data between procedure  
calls.  
Note: The application program must not change the data in this variable.  
MAC  
The MAC parameter is a pointer to a string variable containing the resulting  
MAC returned by the verb. The value is left-justified in the variable. Allocate a  
variable large enough to receive the resulting MAC value.  
Required Commands  
The MAC_Generate verb requires the Generate MAC command (offset X'0010') to  
be enabled in the hardware.  
Chapter 6. Data Confidentiality and Data Integrity 6-13  
MAC_Verify  
CCA Release 2.54  
MAC_Verify (CSNBMVR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The MAC_Verify verb verifies a message authentication code (MAC) for a text  
string that you supply. For additional information about using the MAC generation  
and verification verbs, see “Ensuring Data Integrity” on page 6-3.  
Performance can be enhanced by aligning the start of the text variable on a  
four-byte boundary.  
You specify the message authentication code process through the choice of a  
rule-array keyword. Note that there are defaults based on your use of a  
single-length or double-length key.  
X9.1-1  
ANSI X9.9-1 procedure, by default when you supply a single-length key. This is  
the same as ISO/IEC 9797-1, Algorithm 1.  
X9.19OPT  
ANSI X9.19 Optional Procedure, by default when you supply a double-length key.  
This is the same as ISO/IEC 9797-1, Algorithm 3.  
EMVMAC and EMVMACD  
EMV authentication procedure.4 The verb extends the text you supply with X'80'  
and the minimum number (0...7) bytes of X'00' for the extended message to  
become a multiple of 8 bytes in length. The MAC is computed based on ISO/IEC  
9797-1, Algorithm 1 or 3 depending on key length. When specifying a  
single-length key, use EMVMAC. When specifying a double-length key, use  
EMVMACD.  
Note: The EMV specification permits the MAC to be 4, 5, ..., 8 bytes in length.  
This verb only supports MAC lengths of 4, 6, and 8 bytes.  
You can specify any of these key types: DATA, DATAM, MAC, or MACVER.  
Restrictions  
The text_length variable must be at least eight bytes, and less than 32MB - 8  
bytes, or less than 64MB - 8 bytes in the OS/400 environment.  
Support for EMVMAC and EMVMACD begins with Release 2.51.  
4
See the EMV 4.0 Book 2, Annex A.1.2, for information about this form of MAC verification.  
6-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
MAC_Verify  
Format  
CSNBMVR  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
key_identifier  
text_length  
text  
rule_array_count  
rule_array  
Input  
Input  
Input  
Input  
Input  
String  
Integer  
String  
Integer  
String  
array  
64 bytes  
text_length bytes  
zero, one, two, or three  
rule_array_count * 8 bytes  
chaining_vector  
MAC  
In/Output String  
Input String  
18 bytes  
9 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_identifier  
The key_identifier parameter is a pointer to a string variable containing an  
internal key-token or the key label of an internal key-token record in key  
storage. Use either MAC, MACVER, DATA, DATAM, or DATAMV key-types.  
Keys can be either single length or double length.  
text_length  
The text_length parameter is a pointer to an integer variable containing the  
number of bytes of data in the text variable.  
text  
The text parameter is a pointer to a string variable containing the text the  
hardware uses to calculate the MAC.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
MAC ciphering-method (one, optional)  
EMVMAC  
EMVMACD  
X9.9-1  
Specifies the EMV-related message-padding and calculation  
method. You must also specify use of a single-length key.  
Specifies the EMV-related message-padding and calculation  
method. You must also specify use of a double-length key.  
Specifies the ANSI X9.9-1 and X9.19 Basic Procedure. This  
is the default for a single-length key.  
X9.19OPT  
Specifies the ANSI X9.19 Optional Procedure. This is the  
default for a double length key.  
Chapter 6. Data Confidentiality and Data Integrity 6-15  
MAC_Verify  
CCA Release 2.54  
Keyword  
Meaning  
Segmenting control (one, optional)  
ONLY  
FIRST  
MIDDLE  
LAST  
Specifies the application program does not use segmenting.  
This is the default.  
Specifies this is the first segment of data from the application  
program.  
Specifies this is an intermediate segment of data from the  
application program.  
Specifies this is the last segment of data from the application  
program.  
MAC length and presentation (one, optional)  
MACLEN4  
MACLEN6  
MACLEN8  
HEX-8  
Specifies a four-byte MAC. This is the default.  
Specifies a six-byte MAC.  
Specifies an eight-byte MAC.  
Specifies a four-byte MAC and accepts it as eight  
hexadecimal characters.  
HEX-9  
Specifies a four-byte MAC and accepts it as two groups of  
four hexadecimal characters separated by a space character.  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing a  
work area the security server uses to carry segmented data between  
procedure-calls.  
Note: The application program must not change the data in this variable.  
MAC  
The MAC parameter is a pointer to a string variable containing the trial MAC.  
Ensure that this parameter is a pointer to a nine-byte string variable, because  
nine bytes are always sent to the security server. The MAC value must be  
left-justified in the variable. The verb verifies the MAC if you specify the ONLY  
or LAST keyword for the segmenting control.  
Required Commands  
The MAC_Verify verb requires the Verify MAC command (offset X'0011') to be  
enabled in the hardware.  
6-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 7. Key-Storage Verbs  
This chapter describes how you can use key-storage mechanisms and the  
associated verbs for creating, writing, reading, listing, and deleting records in key  
storage.  
Figure 7-1. Key-Storage-Record Services  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
DES_Key_Record_Create  
DES_Key_Record_Delete  
7-4  
7-5  
Creates a key record in DES key-storage.  
CSNBKRC  
CSNBKRD  
S
S
Deletes a key record or deletes the key token from a key  
record in DES key-storage.  
DES_Key_Record_List  
7-7  
Lists the key names of the key records in DES  
key-storage.  
CSNBKRL  
S
DES_Key_Record_Read  
DES_Key_Record_Write  
PKA_Key_Record_Create  
PKA_Key_Record_Delete  
7-9  
Reads a key token from DES key-storage.  
Writes a key token into DES key-storage.  
Creates a record in the public-key key-storage.  
CSNBKRR  
CSNBKRW  
CSNDKRC  
CSNDKRD  
S
S
S
S
7-10  
7-11  
7-13  
Deletes a record or deletes the key token from a record in  
public-key key-storage.  
PKA_Key_Record_List  
7-15  
Lists the key names of the records in public-key  
key-storage.  
CSNDKRL  
S
PKA_Key_Record_Read  
PKA_Key_Record_Write  
Retained_Key_Delete  
Retained_Key_List  
7-17  
7-19  
7-21  
7-22  
Reads a key token from public-key key-storage.  
Writes a key token in public-key key-storage.  
Deletes a key retained within the cryptographic engine.  
CSNDKRR  
CSNDKRW  
CSNDRKD  
CSNDRKL  
S
S
E
E
Lists the public and private RSA keys retained within the  
cryptographic engine.  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Key Labels and Key-Storage Management  
Use the verbs described in this chapter to manage key storage. The CCA support  
software manages key storage as an indexed repository of key records. Access  
key storage through the use of a key label.  
There are several independent key-storage systems to manage records for DES  
key-records and for PKA key-records. DES key-storage holds internal DES  
key-tokens. PKA key-storage holds both internal and external public and private  
RSA key-tokens.  
Also, public and private RSA-keys can be retained within the Coprocessor. Public  
RSA-keys are loaded into the Coprocessor through use of the  
PKA_Public_Key_Hash_Register and PKA_Public_Key_Register verbs. Private  
RSA-keys are generated and optionally retained within the Coprocessor using the  
PKA_Key_Generate verb. Depending on the other uses for Coprocessor storage,  
between 75 and 150 keys can normally be retained within the Coprocessor.  
Key storage must be initialized before any records are created. Before a key token  
can be stored in key storage, a key-storage record must be created using the  
Key_Record_Create verb.  
Copyright IBM Corp. 1997, 2005  
7-1  
CCA Release 2.54  
Use the Key_Record_Delete verb to delete a key token from a key record, or to  
entirely delete the key record from key storage.  
Use the Key_Record_List verb to determine the existence of key records in key  
storage. The Key_Record_List verb creates a key-record-list data set with  
information about select key-records. The wild-card character (*) is used to obtain  
information about multiple key-records. The data set can be read using  
conventional workstation-data-management services.  
Individual key-tokens can be read or written using the Key_Record_Read or  
Key_Record_Write verbs.  
Key-Label Content  
Use a key label to identify a record or records in key storage managed by a CCA  
implementation. The key label must be left-justified in the 64-byte string variable  
used as input to the verb. Some verbs specify use of a key label while others  
specify use of a key identifier. Calls that use a key identifier accept either a key  
token or a key label.  
A key-label character string has the following properties:  
If the first character is within the range X'20' through X'FE', the input is  
treated as a key label, even if it is otherwise not valid. (Inputs beginning with a  
byte valued in the range X'00' through X'1F' are considered to be some form  
of key token. A first byte valued to X'FF' is not valid.)  
The first character of the key label cannot be numeric (0...9).  
The label is terminated by a space character on the right (ASCII X'20',  
EBCDIC X'40'). The remainder of the 64-byte field is padded with space  
characters.  
Construct a label with one to seven name-tokens, each separated by a period  
(“.”). The key label must not end with a period.  
A name-token consists of one to eight characters in the character set A...Z,  
0...9, and three additional characters relating to different character symbols in  
the various national language character sets as listed below:  
ASCII  
EBCDIC  
Systems  
X'7B'  
X'5B'  
X'7C'  
USA Graphic  
(for reference)  
#
$
Systems  
X'23'  
X'24'  
X'40'  
@
The alphabetic and numeric characters and the period should be encoded in  
the normal character set for the computing platform that is in use, either ASCII  
or EBCDIC.  
Notes:  
1. Some CCA implementations accept the characters a...z and fold these to  
their uppercase equivalents A...Z. Only use the uppercase alphabetic  
characters.  
2. Some implementations internally transform the EBCDIC encoding of a key  
label to an ASCII string. Also, the label may be “tokenized” by dropping the  
periods and formatting each name token into eight-byte groups, padded on  
the right with space characters.  
7-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Some verbs accept a key label containing a “wild card” represented by an asterisk  
(*). (X'2A' in ASCII; X'5C' in EBCDIC). When a verb permits the use of a wild  
card, the wild card can appear as the first character, as the last character, or as the  
only character in a name token. Any of the name tokens can contain a wild card.  
Examples of valid key labels include the following:  
A
ABCD.2.3.4.5555  
ABCDEFGH  
BANKSYS.XXXXX.43ᑍ.ᑍPDQ  
Examples of invalid key labels include the following:  
A/.B (includes an unacceptable character, “/”)  
ABCDEFGH9 (name token too long)  
11111111.2.3.4.55555 (first character numeric)  
A1111111.2.3.4.55555.6.7.8 (too many name tokens)  
BANKSYS.XXXXX.ᑍ43ᑍ.D (more than one wild card in a name token).  
Chapter 7. Key-Storage Verbs 7-3  
DES_Key_Record_Create  
CCA Release 2.54  
DES_Key_Record_Create (CSNBKRC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The DES_Key_Record_Create verb adds a key record with a null key-token to DES  
key-storage. It is identified by the key label specified using the key_label  
parameter.  
After creating a DES key-record, you can use any of the following verbs to add or  
update a key token in the key record:  
Clear_Key_Import  
DES_Key_Record_Write  
Data_Key_Import  
Key_Generate  
Key_Import  
Key_Part_Import  
Multiple_Clear_Key_Import  
PKA_Symmetric_Key_Import.  
To delete a DES key-record, use the DES_Key_Record_Delete verb.  
Restrictions  
Format  
None  
CSNBKRC  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
key_label  
Input  
String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of the DES key-record to be created.  
Required Commands  
The DES_Key_Record_Create verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
DES_Key_Record_Delete  
DES_Key_Record_Delete (CSNBKRD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The DES_Key_Record_Delete verb does either of the following tasks:  
Replaces the token in a key record with a null key-token  
Deletes an entire key record, including the key label, from key storage.  
Identify the task with the rule_array keyword, and the key record with the key_label  
parameter. To identify multiple records, use a wild card (*) in the key label.  
Restrictions  
Format  
None  
CSNBKRD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
Input  
String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 7-2. DES_Key_Record_Delete Rule_Array Keywords  
Keyword  
Meaning  
Task (one required)  
TOKEN-DL  
Deletes a key token from a key record in DES key-storage.  
LABEL-DL  
Deletes an entire key record, including the key label, from  
DES key-storage.  
Chapter 7. Key-Storage Verbs 7-5  
DES_Key_Record_Delete  
CCA Release 2.54  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of a key-token record in key storage. In a key label, use a wild card (*) to  
identify multiple records in key storage.  
Required Commands  
The DES_Key_Record_Delete verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
DES_Key_Record_List  
DES_Key_Record_List (CSNBKRL)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The DES_Key_Record_List verb creates a key-record-list data set containing  
information about specified key records in key storage. Information listed includes  
whether record validation is correct, the type of key, and the date and time the  
record was created and last updated.  
Specify the key records to be listed using the key-label variable. To identify  
multiple key-records, use the wild card (*) in the key label.  
Note: To list all the labels in key storage, specify a key_label of *, *.*, *.*.*, and  
so forth, up to a maximum of seven name tokens (*.*.*.*.*.*.*).  
The verb creates the key-record-list data set and returns the name of the data set  
and the length of the data set name to the calling application. This data set has a  
header record, followed by 0 to n detail records, where n is the number of key  
records with matching key-labels. For information about the header and detail  
records, see “Key_Record_List Data Set” on page B-25.  
AIX users should refer to the CCA Support Program Installation Manual, Chapter 3,  
AIX installation instructions for information concerning the location of the  
key-record-list directory.  
Restrictions  
Format  
None  
CSNBKRL  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
key_label  
data_set_name_length  
data_set_name  
security_server_name  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
Input  
String  
Integer  
String  
String  
Output  
Output  
Output  
data_set_name_length bytes  
8 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of a key-token record in key storage. In a key label, you can use a wild  
card (*) to identify multiple records in key storage.  
Chapter 7. Key-Storage Verbs 7-7  
DES_Key_Record_List  
CCA Release 2.54  
data_set_name_length  
The data_set_name_length parameter is a pointer to an integer variable  
containing the number of bytes of data returned by the verb in the  
data_set_name variable. The maximum returned value is 64 bytes.  
data_set_name  
The data_set_name parameter is a pointer to a 64-byte string variable  
containing the name of the data set returned by the verb. The data set  
contains the key-record information.  
The verb returns the data_set_name as a fully qualified file specification (for  
example, C:\PKADIR\KYRLTnnn.LST in the OS/2 environment), where nnn is  
the numeric portion of the name. This value increases by one every time you  
use this verb; when it reaches 999, the value is reset to 001.  
Note: When the verb stores a key-record-list data set, it overlays any older  
data set with the same name.  
security_server_name  
The security_server_name parameter is a pointer to a string variable. The  
information in this variable is not currently used, but the variable must be  
declared.  
Required Commands  
The DES_Key_Record_List verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
DES_Key_Record_Read  
DES_Key_Record_Read (CSNBKRR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The DES_Key_Record_Read verb copies a key token from DES key-storage to  
application storage. The returned key-token can be null.  
Restrictions  
Format  
None  
CSNBKRR  
return_code  
reason_code  
exit_data_length  
exit_data  
key_label  
key_token  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Output  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
64 bytes  
String  
String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of the record to be read from DES key-storage.  
key_token  
The key_token parameter is a pointer to a string variable containing the key  
token read from DES key-storage.  
Required Commands  
The DES_Key_Record_Read verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
Chapter 7. Key-Storage Verbs 7-9  
DES_Key_Record_Write  
CCA Release 2.54  
DES_Key_Record_Write (CSNBKRW)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The DES_Key_Record_Write verb copies an internal DES key-token from  
application storage into DES key-storage.  
Before you use the DES_Key_Record_Write verb, use DES_Key_Record_Create to  
create a key record.  
Restrictions  
Format  
None  
CSNBKRW  
return_code  
reason_code  
exit_data_length  
exit_data  
key_token  
key_label  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
64 bytes  
64 bytes  
String  
String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
key_token  
The key_token parameter is a pointer to a string variable containing the internal  
key-token to be written into DES key-storage.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label that identifies the record in DES key-storage where the key token is to be  
written.  
Required Commands  
The DES_Key_Record_Write verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Record_Create  
PKA_Key_Record_Create (CSNDKRC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Record_Create service adds a key record with a null key-token to  
PKA key-storage. The new key-record may be a null key-token or a valid PKA  
internal or external key-token. It is identified by the key label specified with the  
key_label parameter.  
After creating a PKA key-record, you can use any of the following verbs to add or  
update a key token in the record:  
PKA_Key_Import  
PKA_Key_Generate  
PKA_Key_Record_Write.  
To delete a PKA key-record, you must use the PKA_Key_Record_Delete verb.  
Restrictions  
Format  
None  
CSNDKRC  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
key_token_length  
key_token  
Input  
Input  
Input  
String  
Integer  
String  
64 bytes  
key_token_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. Currently this verb does not  
require keywords and this field is ignored.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of the PKA key-record to be created.  
Chapter 7. Key-Storage Verbs 7-11  
PKA_Key_Record_Create  
CCA Release 2.54  
key_token_length  
The key_token_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the key_token variable. If the value of the  
key_token_length variable is zero, a record with a null PKA key-token is  
created.  
key_token  
The key_token parameter is a pointer to a string variable containing the key  
token being written to PKA key-storage.  
Required Commands  
The PKA_Key_Record_Create verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Record_Delete  
PKA_Key_Record_Delete (CSNDKRD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Record_Delete verb does either of the following tasks:  
Replaces the token in a key record with a null key-token  
Deletes an entire key-record, including the key label, from key storage.  
Identify the task with the rule_array keyword, and the key record with the key_label  
parameter. To identify multiple records, use a wild card (*) in the key label.  
Restrictions  
Format  
None  
CSNDKRD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero or one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
Input  
String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero or  
one for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 7-3. PKA_Key_Record_Delete Rule_Array Keywords  
Keyword  
Meaning  
Task (one, optional)  
TOKEN-DL  
Deletes a key token from a key record in PKA key-storage.  
This is the default.  
LABEL-DL  
Deletes an entire key record, including the key label, from  
PKA key-storage.  
Chapter 7. Key-Storage Verbs 7-13  
PKA_Key_Record_Delete  
CCA Release 2.54  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of a key-token record in PKA key-storage. Use a wild card (*) in the  
key_label variable to identify multiple records in key storage.  
Required Commands  
The PKA_Key_Record_Delete verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Record_List  
PKA_Key_Record_List (CSNDKRL)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Record_List verb creates a key-record-list data set containing  
information about specified key records in PKA key-storage. Information includes  
whether record validation is correct, the type of key, and the dates and times when  
the record was created and last updated.  
Specify the key records to be listed using the key_label variable. To identify  
multiple key records, use the wild card (*) in a key label.  
Note: To list all the labels in key storage, specify a key_label of *, *.*, *.*.*, and  
so forth, up to a maximum of seven name tokens (*.*.*.*.*.*.*).  
The verb creates the list data set and returns the name of the data set and the  
length of the data set name to the calling application. The verb also returns the  
name of the security server where the data set is stored. The  
PKA_Key_Record_List data set has a header record, followed by 0 to n detail  
records, where n is the number of key records with matching key labels. For  
information about the header and detail records, see “Key_Record_List Data Set”  
on page B-25.  
AIX users should refer to the CCA Support Program Installation Manual, Chapter 3,  
AIX installation instructions for information concerning the location of the key record  
list directory.  
Restrictions  
Format  
None  
CSNDKRL  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
data_set_name_length  
data_set_name  
Input  
String  
Integer  
String  
String  
64 bytes  
Output  
Output  
Output  
data_set_name_length bytes  
8 bytes  
security_server_name  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
Chapter 7. Key-Storage Verbs 7-15  
PKA_Key_Record_List  
CCA Release 2.54  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. Currently this verb does not  
use keywords and this field is ignored.  
key_label  
The key_label parameter is a pointer to a string variable containing a key  
record in PKA key-storage. You can use a wild card (*) to identify multiple  
records in key storage.  
data_set_name_length  
The data_set_name_length parameter is a pointer to an integer variable  
containing the number of bytes of data returned in the data_set_name variable.  
The maximum returned value is 64 bytes.  
data_set_name  
The data_set_name parameter is a pointer to a 64-byte string variable  
containing the name of the data set returned by the verb. The data set  
contains the key-record information.  
The verb returns the data_set_name as a fully qualified file specification (for  
example, C:\PKADIR\KYRLTnnn.LST in the OS/2 environment), where nnn is  
the numeric portion of the name. This value increases by one every time you  
use this verb. When it reaches 999, the value is reset to 001.  
Note: When the verb stores a key-record-list data set, it overlays any older  
data set with the same name.  
security_server_name  
The security_server_name parameter is a pointer to a string variable. The  
information in this variable is not currently used, but the variable must be  
declared.  
Required Commands  
The PKA_Key_Record_List verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Record_Read  
PKA_Key_Record_Read (CSNDKRR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Record_Read verb copies a key token from PKA key-storage to  
application storage.  
The returned key-token may be null. In this event, the key_length variable contains  
a value of eight and the key-token variable contains eight bytes of X'00' beginning  
at offset zero (see “Null Key-Token” on page B-2).  
Restrictions  
Format  
None  
CSNDKRR  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
Input  
String  
64 bytes  
key_token_length  
key_token  
In/Output Integer  
Output String  
key_token_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. Currently this verb does not  
require keywords and this field is ignored.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label of the record to be read from PKA key-storage.  
key_token_length  
The key_token_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the key_token variable. The maximum size is  
2500 bytes.  
Chapter 7. Key-Storage Verbs 7-17  
PKA_Key_Record_Read  
CCA Release 2.54  
key_token  
The key_token parameter is a pointer to a string variable containing the key  
token read from PKA key-storage. This variable must be large enough to hold  
the PKA key-token being read. On successful completion, the  
key_token_length variable contains the actual length of the token being  
returned.  
Required Commands  
The PKA_Key_Record_Read verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PKA_Key_Record_Write  
PKA_Key_Record_Write (CSNDKRW)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The PKA_Key_Record_Write verb copies an internal or external PKA key-token  
from application storage into PKA key-storage.  
The verb performs either of these two processing options:  
Writes the new key-token only if the old token was null  
Writes the new key-token regardless of content of the old token.  
Before you use the PKA_Key_Record_Write verb, use the  
PKA_Key_Record_Create to create a key record.  
Restrictions  
Format  
None  
CSNDKRW  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero or one  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
key_token_length  
key_token  
Input  
Input  
Input  
String  
Integer  
String  
64 bytes  
key_token_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero or  
one for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Chapter 7. Key-Storage Verbs 7-19  
PKA_Key_Record_Write  
CCA Release 2.54  
Figure 7-4. PKA_Key_Record_Write Rule_Array Keywords  
Keyword Meaning  
Processing option (one, optional)  
CHECK  
Specifies that the record will be written only if a record of the  
same label in PKA key-storage contains a null key-token.  
This is the default.  
OVERLAY  
Specifies that the record will be overwritten regardless of the  
current content of the record in PKA key-storage.  
key_label  
The key_label parameter is a pointer to a string variable containing the key  
label that identifies the key record in PKA key-storage where the key token is to  
be written.  
key_token_length  
The key_token_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the key_token variable. The maximum size is  
2500 bytes.  
key_token  
The key_token parameter is a pointer to a string variable containing the PKA  
key-token to be written into PKA key-storage.  
Required Commands  
The PKA_Key_Record_Write verb requires the Compute Verification Pattern  
command (offset X'001D') to be enabled in the access-control system.  
7-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Retained_Key_Delete  
Retained_Key_Delete (CSNDRKD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Retained_Key_Delete verb deletes a PKA key that has been retained within  
the Coprocessor.  
You can retain both public and private keys within the Coprocessor through the use  
of verbs such as PKA_Key_Generate and PKA_Public_Key_Register. A list of  
retained keys can be obtained with the use of the Retained_Key_List verb.  
Restrictions  
Format  
None  
CSNDRKD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label  
Input  
String  
64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter should be a null address pointer.  
key_label  
The key_label parameter points to a string variable containing the key label of a  
key that has been retained within the Coprocessor.  
Required Commands  
The Retained_Key_Delete verb requires the Delete Retained Key command (offset  
X'0203') to be enabled in the hardware.  
Chapter 7. Key-Storage Verbs 7-21  
Retained_Key_List  
CCA Release 2.54  
Retained_Key_List (CSNDRKL)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Retained_Key_List verb lists the key labels of those PKA keys that have been  
retained within the Coprocessor. You filter the set of key labels returned to your  
application through the use of the key label mask input variable.  
Specify the keys to be listed using the key_label_mask variable. To identify  
multiple keys, use the wild card (*) in a mask. Only labels with matching characters  
to those in the mask up to the first “*” will be returned. To list all retained key  
labels, specify a mask of an “*” followed by 63 space characters. For example, if  
the Coprocessor has retained key-labels a.a, a.a1, a.b.c.d, and z.a, and you specify  
the mask a.*, the verb will return a.a, a.a1 and a.b.c.d. If you had specified a mask  
of a.a*, the verb will return a.a and a.a1.  
You can retain both public and private keys within the Coprocessor through the use  
of verbs such as PKA_Key_Generate and PKA_Public_Key_Register. You can  
delete retained keys with the use of the Retained_Key_Delete verb.  
Restrictions  
Format  
None  
CSNDRKL  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero  
rule_array_count * 8 bytes  
Integer  
String  
array  
key_label_mask  
retained_keys_count  
key_labels_count  
key_labels  
Input  
Output  
In/Output Integer  
Output String  
String  
Integer  
64 bytes or null pointer  
key_labels_count * 64 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero for  
this verb.  
rule_array  
The rule_array parameter should be a null address pointer.  
7-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Retained_Key_List  
key_label_mask  
The key_label_mask parameter points to a string variable containing a key  
label mask that is used to filter the list of key names returned by the verb. You  
can use a wild card (*) to identify multiple keys retained within the Coprocessor.  
retained_keys_count  
The retained_keys_count parameter points to an integer variable to receive the  
total number of retained keys stored within the Coprocessor.  
key_labels_count  
The key_labels_count parameter points to an integer variable which on input  
defines the maximum number of key labels to be returned, and which on output  
defines the number of key labels returned by the Coprocessor.  
key_labels  
The key_labels parameter points to a string array variable. The Coprocessor  
returns zero or more 64-byte entries that each contain a key label of a key  
retained within the Coprocessor.  
Required Commands  
The Retained_Key_List verb requires the List Retained Key Names command  
(offset X'0230') to be enabled in the hardware.  
Chapter 7. Key-Storage Verbs 7-23  
CCA Release 2.54  
7-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Chapter 8. Financial Services Support Verbs  
There are several classes of verbs described in this chapter:  
Finance industry PIN processing verbs. Information common to these verbs is  
described in the next section.  
Support for changing the acceptable PIN on a smart card based on VISA and  
EMV design concepts.  
SET-related verbs; these verbs support cryptographic operations as defined in  
the Secure Electronic Transaction (SET) protocol as defined by VISA  
International and MasterCard; see their Web pages for a reference to the SET  
protocol.  
Transaction validation verbs for computing and validating codes for  
MasterCard, VISA, and American Express.  
Figure 8-1 lists the verbs described in this chapter.  
Figure 8-1 (Page 1 of 2). Financial Services Support Verbs  
Verb  
Page  
Service  
Entry  
Point  
Svc  
Lcn  
Clear_PIN_Encrypt  
8-15  
Formats a PIN into a PIN block and outputs the PIN block  
as an encrypted quantity.  
CSNBCPE  
E
The keyword RANDOM represents an extension to the  
support available with other CCA implementations. to  
generate random PINs that are output in encrypted  
PIN-blocks.  
Clear_PIN_Generate  
8-18  
8-21  
Generates a clear PIN, or a PIN offset.  
CSNBPGN  
CSNBCPA  
E
E
Clear_PIN_Generate_Alternate  
Extracts a customer-selected PIN or institution-assigned  
PIN from an encrypted PIN-block and generates a PIN  
offset.  
**  
CVV_Generate  
8-27  
8-30  
8-33  
Generates a card-verification value according to the VISA  
CVV and MasterCard CVC rules for track 2.  
CSNBCSG  
CSNBCSV  
CSNBEPG  
E
E
E
**  
CVV_Verify  
Verifies a card-verification value according to the VISA  
CVV and MasterCard CVC rules for track 2.  
Encrypted_PIN_Generate  
Generates a PIN from an account number and other  
information and returns the result in an encrypted  
PIN-block.  
Encrypted_PIN_Translate  
8-37  
Operates in two modes...  
CSNBPTR  
E
Translate mode reencrypts a PIN block under a different  
key.  
Reformat mode does one or more of the following:  
Reformats a PIN from one PIN-block format into  
another PIN-block format  
Changes selected non-PIN digits in a PIN block  
Reencrypts a PIN block.  
Encrypted_PIN_Verify  
8-42  
8-49  
Extracts and verifies a PIN by using the specified  
PIN-calculation method.  
CSNBPVR  
CSNBKET  
E
E
|
|
|
Key_Encryption_Translate  
Translates an encrypted DATA key (which must have an  
all-zero control vector) from ECB mode to CBC mode, or  
from CBC mode to ECB mode.  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Copyright IBM Corp. 1997, 2005  
8-1  
CCA Release 2.54  
Figure 8-1 (Page 2 of 2). Financial Services Support Verbs  
Verb  
Page  
8-52  
8-59  
8-62  
Service  
Entry  
Point  
Svc  
Lcn  
PIN_Change/Unblock  
Secure_Messaging_for_Keys  
Secure_Messaging_for_PINs  
Calculates a PIN for a smart card based on keys and data  
you supply according to VISA and EMV specifications.  
CSNBPCU  
CSNBSKY  
CSNBSPN  
E
E
E
Securely incorporates a key into a text block which is then  
encrypted (generally for use with EMV smart cards).  
Securely incorporates a PIN block into a text block which  
is then encrypted (generally for use with EMV smart  
cards).  
SET_Block_Compose  
SET_Block_Decompose  
Transaction_Validation  
8-66  
8-70  
8-75  
Creates a SET-protocol RSA-OAEP block and DES  
encrypts the data block in support of the SET protocols.  
CSNDSBC  
CSNDSBD  
CSNBTRV  
E
E
E
Decomposes the RSA-OAEP block and DES decrypts the  
data block in support of the SET protocols.  
Generates and verifies American Express Card Security  
Codes (CSC).  
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software  
Processing Financial PINs  
This section describes how the financial personal identification number (PIN) verbs  
allow you to process financial PINs. A financial PIN is used to authorize personal  
financial transactions for a customer who uses an automated teller machine or  
point-of-sale device.1 A financial PIN is similar to a password except that a financial  
PIN consists of decimal digits and is normally a cryptographic function of an  
associated account number. The financial PIN verbs support PINs that range from  
4 to 16 digits in length. (A financial PIN is usually 4 digits in length.)  
The financial PIN verbs form a complete set of verbs that you can use in various  
combinations to process financial PINs. The verb relationships and primary inputs  
and outputs are depicted in Figure 8-2 on page 8-4, You use these verbs to do the  
following:  
Provide security for the PINs by supporting encrypted PIN-blocks with these  
capabilities:  
– Encryption of a clear PIN in various PIN-block formats  
– Generation of random PIN values and encryption of these in various  
PIN-block formats  
– Verification of a PIN. The PIN block is decrypted as part of the verification  
service  
– Reencrypting a PIN-block under another key with optional, integral  
changing of the PIN-block format.  
Support multiple PIN-calculation methods  
Support multiple PIN-block formats and PIN-extraction methods  
Support ANSI X9.24 derived unique-key-per-transaction PIN-block encryption  
Provide the following services:  
1
In this chapter, automated teller machine (ATM) can also mean a point-of-sale device, an enhanced teller terminal, or a  
programmable workstation, unless noted otherwise.  
8-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
– Create encrypted PIN blocks for transmission  
– Generate institution-assigned PINs  
– Generate an offset or a VISA PIN-validation value (PVV)  
– Create encrypted PIN blocks for a PIN-verification database  
– Change the PIN-block encrypting key or the PIN-block format  
– Verify PINs.  
Normally, a customer inserts a magnetic-stripe card and enters a PIN (a trial PIN)  
into an automated teller machine to identify himself. The automated teller machine  
does the following:  
Obtains account information and other information from the magnetic stripe on  
the card  
Formats the trial PIN into a PIN block and encrypts the PIN block  
Sends the information from the card, the encrypted PIN block, and other data in  
a message to a host program for verification.  
To verify a PIN, a program normally uses one of the following two methods:  
PIN-calculation method. In this method, the program calls the PIN verification  
verb that decrypts the trial PIN block, extracts the trial PIN from the PIN block,  
re-calculates the account-number-based PIN, adjusts this value with any offset,  
compares the resulting value to the trial PIN, and returns the results of the  
comparison.  
PIN database method. In this method, the encrypted PIN-block that contains  
the correct customer-PIN is stored in a PIN-verification database. Upon receipt  
of an encrypted trial-PIN block, the program calls a verb to translate (decipher,  
then encipher) the trial PIN block to the format and key used for the encrypted  
PIN-block in the PIN-verification database. The two encrypted PIN-blocks can  
then be compared for equality.  
In general, a PIN can be assigned by an institution or selected by a customer.  
Some PIN-calculation methods use the institution-assigned or customer-selected  
PIN to calculate another value that is stored on the magnetic stripe of the  
account-holder's card or in a data base and that is used in the PIN-verification  
process.  
Chapter 8. Financial Services Support Verbs 8-3  
CCA Release 2.54  
Account  
Customer─Entered PIN  
Customer─Selected PIN  
Number  
──────────┬─────────  
──────────┬──────────  
T─PIN  
Clear  
C─PIN  
┌───ꢄ────────────────────┐  
PINGEN──ꢁClear_PIN_Generate  
├───────────────────────────┐  
Account  
Number  
CSNBPGN│  
└──────────────────────┐ │  
│ │  
└───────────┬────────────┘  
┌───ꢄ─────────────ꢄ──────┐  
│ │ PINGEN──ꢁClear_PIN_Generate  
A─PIN  
│ │  
│ │  
│(Offset─generation Mode)│  
└─────────────────────────────────────┐ │ │  
CSNBPGN│  
Account  
ꢄ ꢄ ꢄ  
Clear PIN  
│ │ │  
└───────────┬────────────┘  
Number  
O─PIN  
│ │ │  
┌───ꢄ────────────────────┐  
┌─────────ꢄ─ꢄ─ꢄ──────────┐  
PINGEN──ꢁEncrypted_PIN_Generate │  
OPINENC──ꢁClear_PIN_Encrypt  
│(Also RANDOM PIN  
OPINENC─ꢁ  
CSNBEPG│  
│generate option) CSNBCPE│  
└───────────┬────────────┘  
A─PIN  
└───────────┬────────────┘  
└───────────────┐ ┌─────────────────────┤  
ꢄ ꢄ  
Encrypted  
PIN_Block  
(Typically C─PIN)  
Encrypted  
PIN_Block  
Account  
┌────────────────┤  
Number  
IPINENC ┌───────────ꢄ────────────┐  
┌───ꢄ───────ꢄ────────────┐  
or  
──ꢁEncrypted_PIN_Translate │  
│ IPINENC─ꢁClear_PIN_Generate  
KEYGENKY │  
│_Alternate  
w/CKSN  
OPINENC │  
or  
──ꢁ  
CSNBPTR│  
│ PINGEN──ꢁ  
CSNBCPA│  
KEYGENKY └───────────┬────────────┘  
└───────────┬────────────┘  
w/CKSN  
Encrypted  
PIN_Block  
O─PIN  
│ ───────────────┘  
Account  
Number  
T─PIN  
┌─────────────────────────────┴───────────────────────┘  
IPINENC ┌──ꢄ────────ꢄ─────────ꢄ──┐  
or  
──ꢁEncrypted_PIN_Verify  
KEYGENKY │  
w/CKSN  
PINVER──ꢁ  
CSNBPVR│  
└───────────┬────────────┘  
Y/N  
Figure 8-2. Financial PIN Verbs  
8-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PIN-Verb Summary  
The following terms are used for the various “PIN” values:  
A-PIN  
C-PIN  
O-PIN  
T-PIN  
The quantity derived from a function of the account number, and  
PIN-generating key, and other inputs such as a decimalization table.  
The quantity that a customer should use to identify himself. In general,  
this can be a customer-selected or institution-assigned quantity.  
A quantity, sometimes called an offset, that relates the A-PIN to the  
C-PIN as permitted by certain calculation methods.  
The trial PIN presented for verification.  
The Clear_PIN_Generate verb (CSNBPGN) uses a PIN-generating key and an  
account number to create an A-PIN according to the calculation method selected  
through a rule-array keyword. See “PIN-Calculation Methods” on page E-2.  
Certain calculation methods also accept a C-PIN value and return an O-PIN  
calculated from the Coprocessor-generated A-PIN value.  
The Encrypted_PIN_Generate verb (CSNBEPG) uses a PIN-generating key and an  
account number to create an A-PIN according to the calculation method selected  
through a rule-array keyword. The verb formats the A-PIN value into a PIN block  
as specified in the input control information. The PIN block is returned encrypted  
by the supplied OPINENC-type key.  
The Clear_PIN_Encrypt verb (CSNBCPE) accepts a PIN value and formats the  
input into a PIN block. The result is encrypted and returned. This verb can also  
randomly generate PIN values and return these as encrypted PIN blocks. This  
function is useful when an institution wishes to distribute (initial) PIN values to its  
customers.  
The Clear_PIN_Generate_Alternate verb (CSNBCPA) accepts an encrypted PIN  
block that would normally contain a customer-selected C-PIN value. The verb  
calculates the A-PIN from the account number and PIN-generating key and then  
derives the O-PIN as a function of the A-PIN and the C-PIN. The O-PIN is  
returned in the clear.  
The Encrypted_PIN_Verify verb (CSNBPVR) accepts an account number and  
PIN-verifying or PIN-generating key to internally produce an A-PIN. For certain  
methods, the verb also accepts an O-PIN so that it can produce the correct value  
that a customer should enter to access his account. The final input, an encrypted  
T-PIN block, is decrypted, the customer-entered trial PIN is extracted from the block  
and compared to the calculated value; equality or inequality is indicated by the  
return code (and reason code) values. Return code 0 indicates the PIN is validated  
while code 4 indicates that the trial PIN failed validation.  
The Encrypted_PIN_Translate verb (CSNBPTR) is used to change the key used  
later to decrypt or compare the PIN block. The verb can also extract the PIN from  
one PIN-block format and insert the PIN into another PIN-block format before  
reencryption. This service is useful when transferring PIN blocks from one domain  
to another.  
Chapter 8. Financial Services Support Verbs 8-5  
CCA Release 2.54  
PIN-Calculation Method and PIN-Block Format Summary  
As described in the following sections, you can use a variety of PIN calculation  
methods and a variety of PIN-block formats with the various PIN-processing verbs.  
Figure 8-3 provides a summary of the supported combinations.  
Figure 8-3. PIN Verb, PIN-Calculation Method, and PIN-Block-Format Support Summary  
Verb / Calculation Method, PIN  
Block  
Entry  
Point  
UKPT IBM- IBM- VISA- GBP- INBK- NL-  
3624 ISO-0 ISO-1 ISO-2  
PIN  
PINO PVV  
PIN  
PIN  
PIN-1  
Clear_PIN_Encrypt  
CSNBCPE  
CSNBPGN  
CSNBCPA  
CSNBEPG  
CSNBPTR  
CSNBPVR  
Clear_PIN_Generate  
Clear_PIN_Generate_Alternate  
Encrypted_PIN_Generate  
Encrypted_PIN_Translate  
Encrypted_PIN_Verify  
Providing Security for PINs  
It is important to maintain the security of PINs. Unauthorized knowledge of a PIN  
and its associated account number can result in fraudulent transactions. One  
method of maintaining the security of a PIN is to store the PIN in a PIN block,  
encrypt the PIN block, and only send or store a PIN in this form. A PIN block is 64  
bits in length, which is the length of data on which the DES algorithm operates. A  
PIN block consists of both PIN digits and non-PIN digits. The non-PIN digits pad  
the PIN digits to a length of 64 bits. When discussing PINs, the term digit refers to  
a 4-bit quantity that can be valued to the decimal values 0...9 and in some cases  
also to the hexadecimal values A...F. Several different PIN-block formats are  
supported. See “PIN-Block Formats” on page E-9.  
The non-PIN digits can also add variability to a PIN block. Varying the value of the  
non-PIN digits in a PIN block is a security measure used to create a large number  
of different encrypted PIN-blocks, even though there are typically only 10,000 PIN  
values in use. To enhance the security of a clear PIN during PIN processing, the  
verbs generally operate with encrypted PIN-blocks. The PIN verbs provide  
high-level services that typically insert or extract PIN values to or from a PIN block  
internal to the verb.  
The following verbs receive clear PINs from your application program or return  
clear PINs to your program. None of the other PIN verbs reveals a clear PIN.  
Clear_PIN_Generate  
Clear_PIN_Encrypt.  
When your application program supplies a clear PIN to a verb or receives a clear  
PIN from a verb, ensure that adequate access controls and auditing are provided to  
protect this sensitive data. Also recognize that exhaustive use of certain verbs  
such as Encrypted_PIN_Verify and Clear_PIN_Generate_Alternate can reveal the  
value of a PIN. Therefore, if production level keys are available in a system, be  
sure that you have usage controls and auditing in effect to detect inappropriate  
usage of these verbs.  
8-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Using Specific Key Types and Key-Usage Bits to Help Ensure  
PIN Security  
The control vectors (see Appendix C, “CCA Control-Vector Definitions and Key  
Encryption” on page C-1) associated with obtaining and verifying PINs enable you  
to minimize certain security exposures. The class of keys designated PINGEN  
operates in the verbs that create and validate PIN values, whereas the PINVER  
class operates only in those verbs that validate a PIN. Reduce your exposure to  
fraud by limiting the availability of the PINGEN keys to those applications and times  
when it is legitimate to create new PIN values. Use the PINVER key class to  
validate PINs. You can also further restrict those verbs in which a PINGEN key will  
perform by selectively turning off bits in the default PINGEN control vector.  
Those verbs that encrypt a PIN block require the encrypting key to be of the class  
OPINENC, output PIN (block) encrypting key. Those verbs that decrypt a PIN  
block require the encrypting key to be of the class IPINENC, input PIN (block)  
encrypting key. The actual input and output key values are the same, but the use  
of two different types of control vectors aids in defeating certain insider attacks that  
might enable redirection of encrypted PIN values to an unintended service to the  
attacker's benefit. You can also turn off selected bits in the default OPINENC and  
IPINENC control vectors to limit those verbs in which a given key can operate to  
further reduce exposure to insider fraud.  
Point-of-sale terminals that accept a customer's PIN often use the  
unique-key-per-transaction mechanism specified in ANSI X9.24 to ensure that  
tampering with the device will not reveal keys used to encrypt previous PIN  
encryptions. The Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs  
optionally support processing PIN blocks encrypted according to ANSI X9.24. In  
these cases you supply the “base key” and a “current key serial number” (CKSN)  
and the verb derives the appropriate key and employs a special PIN-block  
encryption technique to decrypt or encrypt the PIN block.  
In summary, the PIN verbs use these key types:  
PINGEN (PIN-generating) key type  
The PIN verbs that generate and verify a PIN require the PIN-generating  
key to have a control vector that specifies a PINGEN key type.  
The Encrypted_PIN_Verify verb can also use a key with a PINGEN key  
type if bit 22 is set to one to specify that the key can be used to verify a  
PIN.  
PINVER (PIN-verifying) key type  
The Encrypted_PIN_Verify verb, which verifies an encrypted PIN by  
using the PIN calculation method, requires the PIN-generating key to  
have a control vector that specifies the PINVER key type, or a control  
vector that specifies the PINGEN key type and has bit 22 set to 1. Note  
that the PINVER key type cannot be used to create a PIN value, and  
therefore is the preferred key type in a system that only needs to  
validate PINs.  
IPINENC (input PIN-block encrypting) key type  
The PIN verbs that decrypt a PIN block require the decrypting key to  
have a control vector that specifies an IPINENC key type.  
Chapter 8. Financial Services Support Verbs 8-7  
CCA Release 2.54  
OPINENC (output PIN-block encrypting) key type  
The PIN verbs that encrypt a PIN block require the encrypting key to  
have a control vector that specifies an OPINENC key type.  
KEYGENKY (unique-key-per-transaction base key-generating key) key type  
The Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs can  
derive a unique key from the KEYGENKY derivation key and  
current-key-serial-number to decrypt or encrypt a PIN block.  
Supporting Multiple PIN-Calculation Methods  
The PIN verbs support multiple PIN-calculation methods. You use a data_array  
variable to supply information that a PIN-calculation method requires.  
PIN-Calculation Methods  
A PIN-calculation method determines the value of an A-PIN in relationship to an  
account number. The methods are described in “PIN-Calculation Methods” on  
page E-2. The PIN verbs support the following PIN-calculation methods, which you  
specify with a keyword in the rule_array variable for a verb:  
PIN-Calculation Method  
IBM 3624 PIN  
Keyword  
IBM-PIN  
IBM 3624 PIN Offset  
IBM-PINO  
NL-PIN-1  
GBP-PIN  
VISA-PVV  
INBK-PIN  
Netherlands PIN-1  
IBM German Bank Pool Institution PIN  
VISA PIN-Validation Value (PVV)  
Interbank PIN  
Data_Array  
To supply the information that a PIN-calculation method requires, the PIN verbs use  
a data_array variable. Depending on the calculation method and the verb, the data  
array elements can include a decimalization table, validation data, an offset or clear  
PIN, or transaction security data.  
The data array is a 48-byte string made up of three consecutive 16-byte character  
strings. Each element must be 16 bytes in length, uppercase, left-justified, and  
padded on the right with space characters. Some PIN-calculation methods and  
verbs do not require all three elements. However, all three elements must be  
declared.  
Data Array with IBM-PIN, IBM-PINO, NL-PIN-1, GBP-PIN: When using the  
IBM-PIN, the IBM-PINO, the NL-PIN-1, or GBP-PIN method, the data array  
contains elements for a decimalization table, validation data, and for certain verbs,  
a clear PIN or an offset.  
decimalization_table  
The first element in the data array for a PIN-calculation method points to the  
decimalization table of 16 characters that are used to map the hexadecimal  
digits (X'0' to X'F') of the encrypted validation data to decimal digits (X'0' to  
X'9').  
8-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Note: To avoid errors when using the IBM 3624 PIN-block format, you should  
not include in the decimalization table a decimal digit that is also used as a pad  
digit. For information about a pad digit, see “PIN Profile” on page 8-10.  
validation_data  
The second element in the data array for a PIN-calculation method supplies 1  
to 16 characters of account data, which can be the customer’s account number  
or other identifying number. If necessary, the application program must  
left-justify the validation data and pad on the right with space characters to a  
length of 16 bytes. While normally the validation data consists of  
numeric-decimal characters, the Clear_PIN_Generate_Alternate,  
Encrypted_PIN_Generate, and Encrypted_PIN_Verify verbs have been updated  
to support any hexadecimal character (0, ..., 9, A, ..., F) in support of industry  
practice.  
clear_PIN, offset_data, or reserved  
The third element in the data array contains an O-PIN value. If an O-PIN is not  
used in the verb or method, then this should be 16 space characters.  
Data Array with the VISA-PVV Calculation Method: When using the VISA-PVV  
calculation method, the data array consists of the transaction_security_parameter,  
the PVV, and one reserved element.  
transaction_security_parameter  
The first element in the data array for the VISA-PVV calculation method points  
to transaction security data. Specify 16 characters that include the following:  
– Eleven (rightmost) digits of personal account number (PAN) data, excluding  
the check digit. For information about a PAN, see “Personal Account  
Number (PAN)” on page 8-13.  
– One digit of key index valued from one to six.  
– Four space characters.  
referenced PVV  
When using the Encrypted_PIN_Verify verb, the second element in the data  
array for the VISA-PVV calculation method contains four numeric characters,  
which are the PVV value for the account and derived from a customer-selected  
PIN value. This value is followed by 12 space characters.  
reserved  
The second element (when not using the Encrypted_PIN_Verify verb) and the  
third element in the data array for the VISA-PVV calculation method are  
reserved. These elements point to 16-byte variables in application storage.  
The information in these elements will be ignored, but the elements must be  
declared.  
Data Array for the Interbank Calculation Method: When using the Interbank  
PIN-calculation method with certain verbs, the data array consists of one element,  
the transaction_security_parameter, for transaction security data. The other two  
elements are reserved.  
transaction_security_parameter  
The first element in the data array for the Interbank calculation method points  
to transaction security data. Specify 16 numeric characters that include the  
following:  
Chapter 8. Financial Services Support Verbs 8-9  
CCA Release 2.54  
– Eleven (rightmost) digits of PAN data, excluding the check digit. For  
information about a PAN, see “Personal Account Number (PAN)” on  
page 8-13.  
– A constant, six.  
– A one-digit key index selector from one to six.  
– Three numeric characters of validation data.  
reserved  
The second and third elements in the data array for the Interbank calculation  
method are reserved. These elements point to 16-byte variables in application  
storage. The information in these elements will be ignored, but the elements  
must be declared.  
Supporting Multiple PIN-Block Formats and PIN-Extraction Methods  
The PIN verbs support multiple PIN-block formats, which you specify in a  
PIN_profile variable. The supported PIN-block formats are described in “PIN-Block  
Formats” on page E-9. Multiple methods for extracting the PIN value from the PIN  
block exist for certain PIN-block formats. Depending on the PIN-block format, the  
verbs also require a pad digit, a personal account number (PAN), and/or a  
sequence number.  
When deriving the unique-key according to the ANSI X9.24 UKPT process, the  
verbs also require you to supply the current key serial number (CKSN). The CKSN  
is supplied as an extension of the PIN profile.  
This section describes the following:  
The PIN-profile variable  
The PIN-extraction methods  
The Personal Account Number (PAN)  
The current key serial number (CKSN).  
PIN Profile  
A PIN-profile variable consists of three elements and an optional extension, the  
CKSN. The basic elements identify the PIN-block format, the level of format  
control, and any pad digit. Generally you can code the basic PIN profile as a  
constant in your application. Each element is an eight-byte character string in an  
array, which is the equivalent of a single 24-byte string that is organized as three  
8-byte fields. The elements must be eight bytes in length, uppercase, and,  
depending on the element, either left-justified or right-justified and padded with  
space characters. Depending on the verb and the PIN-block format, all three  
elements might not be used. However, all three elements (that is, all 24 bytes)  
must be declared.  
PIN-Block Format: The PIN-block format is the first element in a PIN-profile  
variable. You specify the format through the use of one of these keywords, left  
justified:  
8-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PIN-Block Format  
Keyword  
3624  
IBM 3624  
ISO-0 (equivalent to ANSI X9.8, VISA format 1, and ECI-1 formats)  
ISO-0  
ISO-1  
ISO-2  
ISO-1 (same as the ECI-4 format)  
ISO-2  
EMV-PIN-change  
VISAPCU1  
VISAPCU2  
Format Control Enforcement: The format-control level is the second element in  
a PIN profile. For the IBM 4758 implementation, this element must be set to NONE  
followed by four space characters.  
Pad Digit: The pad digit is the third element in a PIN profile. Certain PIN-block  
formats require a pad digit when a PIN is formatted or extracted, or both, as shown  
in Figure 8-4 on page 8-11. The Pad Digit for PIN Formatting column indicates the  
value(s) that the verb uses when it creates a PIN block. The Pad Digit for PIN  
Extraction column indicates the value(s) that the verb uses when it extracts a PIN  
from a PIN block.  
When required, specify the pad digit as a character from the character set 0  
through 9 and A through F. The pad digit must be uppercase, right-justified in the  
eight-byte element, with seven preceding space characters. When a pad digit is  
not required, specify eight space characters.  
Note: For the IBM 3624 PIN-block format, the pad digit should be a non-decimal  
character (in the range from C'A' to C'F'). The 3624 PIN-block format depends  
on the fact that the pad digit is not the same as a PIN digit. If they are the same,  
unpredictable results can occur. For this reason, it is strongly recommended that  
you do not use a decimal digit for the pad digit. (If you use a decimal digit for the  
pad digit, you also limit the range of possible PINs.)  
If you use a decimal digit for the pad digit, ensure that you do not include the  
decimal digit in the decimalization table. For information about the decimalization  
table, see “Data_Array” on page 8-8.  
Figure 8-4. Pad-Digit Specification by PIN-Block Format  
PIN-Block Format  
Keyword  
Pad Digit for PIN  
Formatting  
Pad Digit for PIN Extraction  
3624  
0 through F  
F
0 through F  
ISO-0  
The pad-digit specification will  
be ignored.  
ISO-1  
The pad-digit specification will  
be ignored.  
The pad-digit specification will  
be ignored.  
ISO-2  
The pad-digit specification will  
be ignored.  
The pad-digit specification will  
be ignored.  
EMV-PIN-change  
The pad-digit specification is  
ignored.  
The pad-digit specification is  
ignored.  
Current Key Serial Number: When a PIN block is encrypted with a derived,  
unique key, the PIN profile variable is extended by 24 bytes. The CKSN is left  
justified within the extension and padded by four bytes of X'00'.  
Chapter 8. Financial Services Support Verbs 8-11  
CCA Release 2.54  
The CKSN is the concatenation of a terminal identifier and a sequence number  
which together define a unique terminal (within the set of terminals associated with  
a given base key) and the sequence number of the transaction originated by that  
terminal. Each time the terminal completes a transaction, it increments the  
sequence number and modifies the transaction-encryption key retained within the  
terminal. The key-modification process is a one-way function so that tampering  
with the terminal will not reveal previously used keys. For details of this process,  
see “UKPT Calculation Methods” on page E-13.  
PIN-Extraction Methods  
Before a verb can process a formatted and encrypted PIN, the verb must decrypt  
the PIN block and extract the PIN from the PIN block. The PIN verbs support  
multiple PIN-extraction methods. The valid PIN-extraction method depends on the  
PIN-block format.  
You can specify a PIN-extraction method or use the default method for the  
PIN-block format. To specify a PIN-extraction method, you use a keyword in the  
rule_array parameter for the verb.  
Figure 8-5 shows the keywords for the PIN-extraction methods that are valid for  
each PIN-block format. When only one PIN-extraction method is valid, the keyword  
is the default value. When more than one method is valid, the first keyword is the  
default value.  
Figure 8-5. PIN-Extraction Method Keywords by PIN-Block Format  
PIN-Block  
Format  
PIN-Extraction Method Keywords (Used in the Rule Array)  
3624  
PADDIGIT, HEXDIGIT, PINLEN04 to PINLEN16, PADEXIST  
ISO-0  
ISO-1  
ISO-2  
PINBLOCK  
PINBLOCK  
PINBLOCK  
The PIN-extraction method keywords operate as described:  
PINBLOCK  
Depending on the contents of the PIN block, this keyword specifies  
that the verb use one of the following items to identify the PIN:  
The PIN length, if the PIN block contains a PIN-length field  
The PIN-delimiter character, if the PIN block contains a  
PIN-delimiter character.  
PADDIGIT  
HEXDIGIT  
This keyword specifies that the verb use the pad value in the PIN  
profile to identify the end of the PIN.  
This keyword specifies that the verb use the first occurrence of a  
digit in the range from X'A' to X'F' as the pad value to determine  
the PIN length.  
PINLENxx  
This keyword specifies that the verb use the length specified in  
the keyword, where xx can range from 04 to 16 digits, to identify  
the PIN.  
PADEXIST  
This keyword specifies that the verb use the character in the sixt  
position of the PIN block as the value of the pad value.  
8-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Personal Account Number (PAN)  
A personal account number (PAN) identifies an individual and relates that individual  
to an account at the financial institution. The PAN consists of the following:  
Issuer identification number  
Customer account number  
One check digit.  
For the ISO-0 PIN-block format, the PIN verbs use a PAN to format and extract a  
PIN. You specify the PAN with a PAN_data parameter for the verb. You must  
specify the PAN in character format in a 12-byte field. Each digit in the PAN must  
be in the range from 0 to 9. The actual PAN might be more than 12 digits, but the  
PIN verbs use only 12 digits for the PAN. Depending on the PIN-block format, the  
verbs use the rightmost 12 digits or the leftmost 12 digits.  
When using the ISO-0 PIN-block format, use the rightmost 12 digits of the  
PAN, excluding the check digit.  
Working With EMV Smart Cards  
Beginning with Release 2.50, and extended in Release 2.51, the implementation  
includes several new verbs and additional verb capabilities you can use in secure  
communications with EMV smart cards. The processing capabilities are consistent  
with the specifications provided in these documents:  
EMV 2000 Integrated Circuit Card Specification for Payment Systems Version  
4.0 (EMV4.0) Book 2  
Design VISA Integrated Circuit Card Specification Manual.  
Capabilities include:  
The Diversified_Key_Generate verb (CSNBDKG, page 5-35) with rule-array  
options TDES-XOR, TDESEMV2, and TDESEMV4 enable you to derive a key  
used to cipher and authenticate messages, and more particularly message  
parts, for exchange with an EMV smart card. You use the derived key with  
verbs such as Encipher, Decipher, MAC_Generate, MAC_Verify,  
Secure_Messaging_for_Keys, and Secure_Messaging_for_PINs. These  
message parts can be combined with message parts created using the  
Secure_Messaging_for_Keys and Secure_Messaging_for_PINs verbs.  
The Secure_Messaging_for_Keys verb (CSNBSKY, page 8-59) enables you to  
securely incorporate a key into a message part (generally the value portion of a  
TLV component of a secure message for a card). Similarly, the  
Secure_Messaging_for_PINs verb (CSNBSPN, page 8-62) enables secure  
incorporation of a PIN block into a message part.  
The PIN_Change/Unblock verb (CSNBPCU, page 8-52) enables you to encrypt  
a new PIN for sending to a new EMV card, or for updating the PIN value on an  
initialized EMV card. This verb internally generates the required session key as  
alluded to above for the Diversified_Key_Generate verb.  
The ZERO-PAD option of the PKA_Encrypt verb (CSNDPKE, page 5-75)  
enables you to validate a digital signature created according to ISO 9796-2 by  
encrypting information you format, including a hash value of the message to be  
validated. You compare the resulting enciphered data to the digital signature  
accompanying the message to be validated.  
Chapter 8. Financial Services Support Verbs 8-13  
CCA Release 2.54  
The MAC_Generate and MAC_Verify verbs incorporate post-padding a  
X'80'...X'00' string to a message as required for authenticating messages  
exchanged with EMV smart cards.  
8-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_PIN_Encrypt  
Clear_PIN_Encrypt (CSNBCPE)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Clear_PIN_Encrypt verb formats a PIN into one of the following PIN-block  
formats and encrypts the results (see “PIN-Block Formats” on page E-9):  
IBM 3624 format  
ISO-0 format (same as the ANSI X9.8, VISA-1, and ECI formats)  
ISO-1 format (same as the ECI-4 format)  
ISO-2 format.  
You can use the Clear_PIN_Encrypt verb to create an encrypted PIN-block for  
transmission. With the RANDOM keyword, you can also have the verb generate  
random PIN numbers. This can be useful when you supply PIN numbers to a  
bank-card manufacturer.  
Note: A clear PIN is a sensitive piece of information. Ensure that your application  
program and system design provide adequate protection for any clear-PIN value.  
To use this verb, specify the following:  
A key used to encrypt the PIN block.  
A clear PIN. When you generate random PINs, the clear-PIN variable specifies  
the length of the generated-PIN value by the number of numeral zero  
characters. The remainder of the variable must be padded with space  
characters.  
A PIN profile that specifies the format of the PIN block to be created, and any  
pad digit; see “PIN Profile” on page 8-10.  
When using the ISO-0 PIN-block format, the PAN_data variable provides the  
account number that is exclusive-ORed with the PIN information.  
The sequence number for use in certain PIN-block formats; for those PIN-block  
formats that do not employ a sequence number, specify a value of 99999 in the  
integer variable.  
The verb does the following:  
Formats the PIN into the specified PIN-block format.  
Checks the control vector for the OPINENC key by doing the following:  
– Verifying that the CPINENC bit is one.  
Encrypts the PIN block in ECB mode.  
Returns the encrypted PIN-block in the encrypted_PIN_block variable.  
Restrictions  
None  
Chapter 8. Financial Services Support Verbs 8-15  
Clear_PIN_Encrypt  
CCA Release 2.54  
Format  
CSNBCPE  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
exit_data_length bytes  
PIN_encrypting_key_identifier  
rule_array_count  
rule_array  
Input  
Input  
Input  
String  
Integer  
String  
array  
64 bytes  
zero or one  
rule_array_count * 8 bytes  
clear_PIN  
PIN_profile  
Input  
Input  
String  
String  
array  
16 bytes  
3 * 8 bytes  
PAN_data  
sequence_number  
encrypted_PIN_block  
Input  
Input  
Output  
String  
Integer  
String  
12 bytes  
8 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
PIN_encrypting_key_identifier  
The PIN_encrypting_key_identifier parameter points to a string containing an  
internal key-token or a key label of an internal key-token. The internal  
key-token contains the key that encrypts the PIN block. The control vector in  
the internal key-token must specify an OPINENC key type and have the  
CPINENC bit set to one.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero or  
one for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
PIN source (one, optional)  
ENCRYPT  
RANDOM  
Causes the verb to use the PIN value contained in the  
clear_PIN variable. This is the default operation of the verb,  
Causes the verb to use a randomly generated PIN value. The  
length of the PIN is based on the value in the clear_PIN  
variable. Value the clear PIN to zero and use as many digits  
as the desired random PIN. Pad the remainder of the  
clear-PIN variable with space characters.  
clear_PIN  
The clear_PIN parameter points to a string variable containing the clear PIN.  
The values in this variable must be left-justified and padded on the right with  
space characters.  
8-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_PIN_Encrypt  
PIN_profile  
The PIN_profile parameter points to a string variable containing three 8-byte  
elements with: a PIN-block format keyword, a format control keyword (NONE),  
and a pad digit as required by certain formats. See “PIN Profile” on page 8-10.  
PAN_data  
The PAN_data parameter points to a personal account number (PAN) in  
character format. The verb uses this parameter if the PIN profile specifies the  
ISO-0 keyword for the PIN-block format. Otherwise, ensure that this parameter  
points to a 12-byte variable in application storage. The information in this  
variable will be ignored, but the variable must be declared.  
sequence_number  
The sequence_number parameter points to a character integer. The verb  
currently ignores the value in this variable. For future compatibility, the  
suggested value is '99999'.  
encrypted_PIN_block  
The encrypted_PIN_block parameter points to a string variable containing the  
encrypted PIN-block returned by the verb.  
Required Commands  
The Clear_PIN_Encrypt verb requires the Format and Encrypt PIN command  
(command offset X'00AF') to be enabled in the hardware.  
Chapter 8. Financial Services Support Verbs 8-17  
Clear_PIN_Generate  
CCA Release 2.54  
Clear_PIN_Generate (CSNBPGN)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The Clear_PIN_Generate verb generates an A-PIN or an O-PIN by using one of the  
following calculation methods that you specify with a rule-array keyword (see  
“PIN-Calculation Methods” on page E-2):  
IBM 3624 PIN (IBM-PIN)  
IBM 3624 PIN Offset (IBM-PINO).  
You can use this verb to do the following:  
Generate a clear PIN for immediate use; for example, generate a clear A-PIN  
as part of PIN mailer processing  
Generate an offset (O-PIN) for use on a customer account magnetic-stripe  
card.  
Notes:  
1. A clear PIN is a sensitive piece of information. Ensure that your application  
program and system design provide adequate protection for the clear PIN.  
2. To format and encrypt a PIN, use the Clear_PIN_Encrypt verb.  
To use this verb, specify:  
A PIN-generating key  
The number of rule-array elements  
The PIN-calculation method  
The length of the PIN  
For certain PIN-calculation methods, an additional PIN-length value with the  
PIN_check_length variable to determine the length of the O-PIN value  
A decimalization table, validation data (for example, account-number  
information) and, based on the PIN-calculation method, the C-PIN value, in a  
character array  
A 16-byte variable to receive the clear PIN.  
The verb does the following:  
Verifies that the CPINGEN bit is set to one in the control vector for the PINGEN  
key.  
Calculates the A-PIN, and optionally uses the C-PIN and the A-PIN to compute  
the O-PIN value. See “PIN-Calculation Methods” on page E-2.  
Uses the specified PIN length to determine the length of the PIN.  
Returns the clear A-PIN or O-PIN in the variable identified by the  
returned_result parameter.  
8-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_PIN_Generate  
Restrictions  
Format  
None  
CSNBPGN  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
PIN_generating_key_identifier  
rule_array_count  
rule_array  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
one  
Input  
Input  
Input  
String  
Integer  
String  
array  
rule_array_count * 8 bytes  
PIN_length  
PIN_check_length  
data_array  
Input  
Input  
Input  
Integer  
Integer  
String  
array  
3 * 16 bytes  
16 bytes  
returned_result  
Output  
String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
PIN_generating_key_identifier  
The PIN_generating_key_identifier parameter points to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage. The internal key-token contains the PIN-generation key and  
must contain a control vector that specifies the PINGEN key type and has the  
CPINGEN bit set to one.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. This value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
PIN-calculation method (one required)  
IBM-PIN  
This keyword specifies the IBM 3624 PIN-calculation method  
to be used to generate a PIN.  
IBM-PINO  
This keyword specifies the IBM 3624 PIN offset calculation  
method to be used to generate a PIN offset.  
PIN_length  
The PIN_length parameter points to an integer variable in the range from 4 to  
16 containing the length of the PIN.  
Chapter 8. Financial Services Support Verbs 8-19  
Clear_PIN_Generate  
CCA Release 2.54  
PIN_check_length  
The PIN_check_length parameter points to an integer variable in the range  
from 4 to 16 containing the length of the PIN offset. The verb uses the PIN  
check length if you specify the IBM-PINO keyword for the calculation method.  
Otherwise, ensure that this parameter points to a four-byte variable in  
application storage. The information in this variable will be ignored, but this  
variable must be declared.  
Note: The PIN check length must be less than or equal to the PIN length.  
data_array  
The data_array parameter points to a string variable containing three 16-byte  
numeric character strings, which are equivalent to a single 48-byte string. The  
values in the data array depend on the keyword for the PIN-calculation method.  
Each element is not always used, but you must always declare a complete data  
array.  
The numeric characters in each 16-byte string must be from 1 to 16 bytes in  
length, left-justified, and padded on the right with space characters. The verb  
converts the space characters to zeros.  
When using the IBM-PIN or the IBM-PINO keyword, identify the following  
elements in the data array.  
Element  
Description  
decimalization_table  
This element contains the decimalization table of 16  
characters (0 to 9) that are used to convert the  
hexadecimal digits (X'0' to X'F') of the encrypted  
validation data to decimal digits (X'0' to X'9').  
validation_data  
clear_PIN  
This 16-byte element contains 1 to 16 characters of  
account data. The data must be left-justified and  
padded on the right with spaces.  
When using the IBM-PINO keyword, this 16-byte  
element contains the clear customer-selected PIN. This  
value must be left-justified and padded on the right with  
spaces.  
When using the IBM-PIN keyword, this element is  
ignored but must be declared.  
returned_result  
The returned_result parameter points to a string variable containing the result  
returned by the verb. The result will be left-justified and padded on the right  
with space characters.  
Required Commands  
The Clear_PIN_Generate verb requires the following command to be enabled in the  
hardware based on the keyword specified for the PIN-calculation method.  
PIN-Calculation  
Method  
Command  
Offset  
Command  
IBM-PIN,  
X'00A0'  
Generate Clear 3624 PIN  
IBM-PINO  
8-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_PIN_Generate_Alternate  
Clear_PIN_Generate_Alternate (CSNBCPA)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Clear_PIN_Generate_Alternate verb is used to obtain a value, the “O-PIN”  
(offset or VISA-PVV), that will relate the institution-assigned PIN to the  
customer-known PIN. The verb supports these PIN-calculation methods:  
IBM 3624 PIN Offset (IBM-PINO)  
Visa PIN Validation Value (VISA-PVV).  
You supply the “customer PIN” (C-PIN) as an encrypted PIN-block. The verb:  
Decrypts a PIN block  
Extracts a customer-selected or institution-assigned PIN (C-PIN)  
Generates an A-PIN from the input account number, PIN-generating key, and  
so forth  
Computes an O-PIN from the C-PIN and the A-PIN; the O-PIN is returned in  
the clear.  
Note: To generate an O-PIN from a clear C-PIN, see the Clear_PIN_Generate  
verb.  
To use this verb, specify:  
An input PIN-block encrypting key used to decrypt the PIN block  
A PIN-generating key used to calculate the A-PIN  
A PIN profile that describes the PIN block that contains the C-PIN  
When using the ISO-0 PIN-block format, personal account number (PAN) data  
to be used in extracting the PIN  
The encrypted PIN-block that contains the C-PIN  
A calculation method and optionally a PIN-extraction method  
The length of the O-PIN offset (the verb determines the length of the C-PIN  
from the length of the extracted PIN)  
A decimalization table and account validation data  
A 16-byte variable for the O-PIN.  
The verb does the following:  
Checks the control vector of the IPINENC key to ensure that the CPINGENA bit  
is one  
Decrypts the PIN block in ECB mode  
Extracts the PIN. The verb uses the PIN-extraction method specified with the  
rule_array parameter or the default extraction method for the PIN-block format.  
The verb also uses the PIN_check_length variable. Depending on the  
PIN-block format specified in the PIN profile, the verb also uses the pad digit  
specified in the input_PIN_profile variable or the PAN specified in the  
PAN_data variable.  
Verifies that the CPINGENA bit is one in the control vector for the PINGEN key  
Chapter 8. Financial Services Support Verbs 8-21  
Clear_PIN_Generate_Alternate  
CCA Release 2.54  
Calculates the A-PIN. The verb uses the specified calculation method, the  
data_array variable, and the PIN_check_length variable to calculate the PIN.  
Calculates the O-PIN  
Returns the clear O-PIN in the variable identified by the returned_result  
parameter.  
Restrictions  
Format  
None  
CSNBCPA  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output Integer  
exit_data_length bytes  
64 bytes  
64 bytes  
inbound_PIN_encrypting_key_identifier  
PIN_generating_key_identifier  
input_PIN_profile  
Input  
Input  
Input  
String  
String  
String  
array  
3 * 8 bytes  
PAN_data  
Input  
Input  
Input  
Input  
String  
String  
Integer  
String  
array  
12 bytes  
8 bytes  
one or two  
rule_array_count * 8 bytes  
encrypted_PIN_block  
rule_array_count  
rule_array  
PIN_check_length  
data_array  
Input  
Input  
Integer  
String  
array  
3 * 16 bytes  
16 bytes  
returned_result  
Output  
String  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
inbound_PIN_encrypting_key_identifier  
The inbound_PIN_encrypting_key_identifier parameter points to a string  
variable containing an internal key-token or a key label of an internal key-token  
record in key storage. The internal key-token contains the key that decrypts  
the PIN-block C-PIN. The control vector in the key token must specify the  
IPINENC key type and have the CPINGENA bit set to one.  
PIN_generating_key_identifier  
The PIN_generating_key_identifier parameter points to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage. The internal key-token contains the PIN-generation key and  
must contain a control vector that specifies the PINGEN key type and has the  
CPINGENA bit set to one.  
input_PIN_profile  
The input_PIN_profile parameter points to a string variable containing a  
character array with three 8-byte elements: the PIN-block format keyword, the  
format control (NONE), a pad digit (if needed); see “PIN Profile” on page 8-10.  
PAN_data  
The PAN_data parameter points to a string variable containing personal  
account number (PAN) data. If the PIN profile specifies the ISO-0 keyword, the  
verb uses the PAN data to recover the C-PIN from the PIN block.  
8-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_PIN_Generate_Alternate  
Note: When using the ISO-0 format, use the 12 rightmost PAN digits,  
excluding the check digit.  
encrypted_PIN_block  
The encrypted_PIN_block parameter points to a string variable containing the  
encrypted PIN-block of the (customer-selected) C-PIN value.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
Element  
Number  
Function of Keyword  
1
2
PIN-calculation method  
PIN-extraction method.  
The first element in the rule array must specify one of the keywords that  
indicates the PIN-calculation method, as shown in Figure 8-6.  
Figure 8-6. Clear_PIN_Generate_Alternate Rule_Array Keywords (First Element)  
PIN-Calculation  
Method  
Meaning  
IBM-PINO  
NL-PIN-1  
VISA-PVV  
This keyword specifies use of the IBM 3624 PIN Offset  
calculation method  
This keyword specifies use of the Netherlands PIN-1  
calculation method  
This keyword specifies use of the VISA-PVV calculation  
method.  
The second element in the rule array must specify one of the keywords that  
indicate a PIN-extraction method, as shown in Figure 8-7. For more  
information about extraction methods, see “PIN-Extraction Methods” on  
page 8-12.  
Notes:  
1. In the table, the PIN-block format keyword is the keyword that you specify  
in the input_PIN_profile parameter.  
2. If the PIN-block format allows you to choose the PIN-extraction method,  
and if you specify a rule-array count of one, the PIN-extraction method  
keyword that is listed first in the following table is the default.  
Chapter 8. Financial Services Support Verbs 8-23  
Clear_PIN_Generate_Alternate  
CCA Release 2.54  
Figure 8-7. Clear_PIN_Generate_Alternate Rule_Array Keywords (Second  
Element)  
PIN-Block  
Format  
PIN-Extraction  
Method  
Meaning  
Keyword  
Keyword  
3624  
PADDIGIT  
HEXDIGIT  
PINLEN04  
PINLEN05  
The PIN-extraction method keywords  
specify a PIN-extraction method for an IBM  
3624 PIN-block format. The first keyword,  
PADDIGIT, is the default PIN-extraction  
method for the PIN-block format.  
.
.
.
PINLEN16  
PADEXIST  
ISO-0  
ISO-1  
PINBLOCK  
This keyword specifies the default  
PIN-extraction method for an ISO-0  
PIN-block format.  
PINBLOCK  
This keyword specifies the default  
PIN-extraction method for an ISO-1  
PIN-block format.  
PIN_check_length  
The PIN_check_length parameter points to an integer variable in the range  
from 4 to 16 containing the number of digits of PIN information that the verb  
should check. The verb uses the PIN_check_length parameter if you specify  
the IBM-PINO keyword for the calculation method. Otherwise, ensure that this  
parameter points to a four-byte variable in application storage. The information  
in this variable will be ignored, but this variable must be declared.  
Note: The PIN check length must be less than or equal to the PIN length.  
The length of the PIN offset in the returned result will be determined by the  
value that the PIN_check_length parameter identifies. The security server  
shortens the PIN offset.  
data_array  
The data_array parameter points to a string variable containing three 16-byte  
character strings, which are equivalent to a single 48-byte string. The values in  
the data array depend on the PIN-calculation method. Each element is not  
always used, but you must always declare a complete 48-byte data array.  
When using the IBM-PINO keyword, identify the following elements in the data  
array:  
8-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Clear_PIN_Generate_Alternate  
Element  
Description  
decimalization_table  
This element contains the decimalization  
table of 16 characters (0 to 9) that are used  
to convert the hexadecimal digits (X'0' to  
X'F') of the enciphered validation data to  
decimal digits (X'0' to X'9').  
validation_data  
reserved_3  
This 16-byte element contains 1 to 16  
characters of account data. The data must  
be left-justified and padded on the right with  
space characters.  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
When using the NL-PIN-1 keyword, identify the following elements in the data  
array:  
Element  
Description  
decimalization_table  
This 16-character string should contain the  
characters 0, 1, ..., 9, A, ..., F.  
validation_data  
reserved_3  
This 16-byte element contains 1 to 16  
characters of account data. The data must  
be left-justified and padded on the right with  
space characters.  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
When using the VISA-PVV keyword, identify the following elements in the data  
array. For more information about transaction security data for the VISA-PVV  
calculation method, see “VISA PIN Validation Value (PVV) Calculation Method”  
on page E-7.  
Element  
Description  
transaction_security_parameter  
This element contains 16 numeric  
characters that include the following:  
Eleven (rightmost) digits of PAN data  
One digit of key index from one to six  
Four space characters for padding.  
reserved_2  
reserved_3  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
Chapter 8. Financial Services Support Verbs 8-25  
Clear_PIN_Generate_Alternate  
returned_result  
CCA Release 2.54  
The returned_result parameter points to a string variable containing the clear  
O-PIN returned by the verb. The 16-byte result will be left-justified and padded  
on the right with space characters.  
The length of the PIN offset in the returned result will be determined by the  
value that the PIN_check_length parameter specifies.  
Required Commands  
The Clear_PIN_Generate_Alternate verb requires the following commands to be  
enabled in the hardware based on the keyword specified for the PIN-calculation  
methods.  
PIN-Calculation  
Method  
Command  
Offset  
Command  
IBM-PINO  
NL-PIN-1  
VISA-PVV  
X'00A4'  
X'0231'  
X'00BB'  
Generate Clear 3624 PIN Offset  
Generate Clear NL-PIN-1 Offset  
Generate Clear VISA-PVV Alternate  
8-26 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
CVV_Generate  
CVV_Generate (CSNBCSG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The CVV_Generate verb supports the VISA card-verification value (CVV) and the  
MasterCard card-verification code (CVC) process as defined for track 2 by  
generating a CVV. For details about the CVV process, see “CVV and CVC  
Method” on page E-16  
The verb generates a CVV that is based on the information that the PAN_data, the  
expiration_date, and the service_code parameters provide. The verb uses the  
key-A and key-B keys to cryptographically process this information. The verb  
returns the 5-byte variable that the CVV_value parameter identifies. If the  
requested CVV is shorter than 5 characters, the CVV is padded on the right by  
space characters.  
The control vectors supplied with key-A and key-B must indicate either a  
MAC-class key type or a DATA-class key type. The subtype bit field in the control  
vectors can be B'0000'. Alternatively, you can ensure that the keys are used only  
in the CVV_Generate and CVV_Verify verbs by specifying a MAC-class key with  
subtype bits for key-A as B'0010' and for key-B as B'0011'. For more  
information about control vectors, see Appendix C, “CCA Control-Vector Definitions  
and Key Encryption.”  
Restrictions  
Format  
None  
CSNBCSG  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero, one, or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
PAN_data  
expiration_date  
service_code  
CVV_key-A_identifier  
CVV_key-B_identifier  
CVV_value  
Input  
Input  
Input  
Input  
Input  
Output  
String  
String  
String  
String  
String  
String  
16 bytes  
4 bytes  
3 bytes  
64 bytes  
64 bytes  
5 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, or two for this verb.  
Chapter 8. Financial Services Support Verbs 8-27  
CVV_Generate  
CCA Release 2.54  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
PAN-data length (one, optional)  
PAN-13  
PAN-16  
This keyword specifies that the length of the PAN data is 13  
bytes. PAN-13 is the default value.  
This keyword specifies that the length of the PAN data is 16  
bytes.  
CVV length (one, optional)  
CVV-1  
CVV-2  
CVV-3  
CVV-4  
CVV-5  
This keyword specifies the length of the CVV to be returned is  
1 character. This is the default value.  
This keyword specifies the length of the CVV to be returned is  
2 characters.  
This keyword specifies the length of the CVV to be returned is  
3 characters.  
This keyword specifies the length of the CVV to be returned is  
4 characters.  
This keyword specifies the length of the CVV to be returned is  
5 characters.  
PAN_data  
The PAN_data parameter points to a string variable containing personal  
account number (PAN) data in character format. The PAN is the account  
number as defined for the track-2 magnetic-stripe standards. If the PAN-13  
keyword is specified in the rule array, 13 characters are processed; if the  
PAN-16 keyword is specified in the rule array, 16 characters are processed.  
Even if you specify the PAN-13 keyword, the server copies 16 bytes to a work  
area. Therefore, ensure that the variable addresses 16 bytes of application  
storage.  
expiration_date  
The expiration_date parameter points to a string variable containing the card  
expiration date. The date is in numeric character format. The application  
programmer must determine whether the CVV will be calculated as YYMM or  
MMYY.  
service_code  
The service_code parameter points to a string variable containing the service  
code in character format. The service code is the number that the track-2  
magnetic-stripe standards define.  
CVV_key-A_identifier  
The CVV_key-A_identifier parameter points to a string variable containing an  
internal key-token or a key label of an internal key-token record in key storage.  
The internal key-token contains the key-A key that encrypts information in the  
CVV process.  
8-28 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
CVV_Generate  
CVV_key-B_identifier  
The CVV_key-B_identifier parameter points a string variable containing an  
internal key-token or a key label of an internal key-token record in key storage.  
The internal key-token contains the key-B key that decrypts information in the  
CVV process.  
CVV_value  
The CVV_value parameter points to a string variable containing the CVV value  
in character format returned by the verb.  
Required Commands  
The CVV_Generate verb requires the Generate CVV command (command offset  
X'00DF') to be enabled in the hardware.  
Chapter 8. Financial Services Support Verbs 8-29  
CVV_Verify  
CCA Release 2.54  
CVV_Verify (CSNBCSV)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-2/23  
X
X
X
The CVV_Verify verb supports the VISA card-verification value (CVV) and the  
MasterCard card-verification code (CVC) process as defined for track 2 by verifying  
a CVV. For details about the CVV process, see “CVV and CVC Method” on  
page E-16  
The verb generates a CVV value internal to the Coprocessor based on the  
information you identify with the PAN_data, the expiration_date, and the  
service_code parameters. The verb uses the key-A and key-B keys to  
cryptographically process this information. Based on your use of the CVV-n  
rule-array keywords, the internal CVV value is truncated to fewer characters and  
padded on the right with space characters. The internal CVV value is compared to  
the five-character value that you identify with the CVV_value parameter. The result  
of this comparison is indicated in the return code. If the return code is zero, the  
values correctly compared. If the CVV values do not match, the return code is set  
to four (and the reason code is set to one).  
The control vectors supplied with key-A and key-B must indicate either a  
MAC-class, a MACVER-class, or a DATA-class key type. The subtype bit field in  
the control vectors can be B'0000'. Alternatively, you can ensure that the keys  
are used only in the CVV_Generate and CVV_Verify verbs by specifying a  
MACVER-class key with subtype bits for key-A as B'0010' and for key-B as  
B'0011'. For more information about control vectors, see Appendix C, “CCA  
Control-Vector Definitions and Key Encryption.”  
Restrictions  
Format  
None  
CSNBCSV  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero, one, or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
PAN_data  
expiration_date  
service_code  
CVV_key-A_identifier  
CVV_key-B_identifier  
CVV_value  
Input  
Input  
Input  
Input  
Input  
Input  
String  
String  
String  
String  
String  
String  
16 bytes  
4 bytes  
3 bytes  
64 bytes  
64 bytes  
5 bytes  
8-30 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
CVV_Verify  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be zero,  
one, or two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
PAN-data length (one, optional)  
PAN-13  
PAN-16  
This keyword specifies that the length of the PAN data is 13  
bytes. PAN-13 is the default value.  
This keyword specifies that the length of the PAN data is 16  
bytes.  
CVV length (one, optional)  
CVV-1  
CVV-2  
CVV-3  
CVV-4  
CVV-5  
This keyword specifies the length of the CVV to be verified is  
1 character. This is the default value.  
This keyword specifies the length of the CVV to be verified is  
2 characters.  
This keyword specifies the length of the CVV to be verified is  
3 characters.  
This keyword specifies the length of the CVV to be verified is  
4 characters.  
This keyword specifies the length of the CVV to be verified is  
5 characters.  
PAN_data  
The PAN_data parameter points to a string variable containing the personal  
account number (PAN) data in character format. The PAN is the account  
number as defined for the track-2 magnetic-stripe standards. If the PAN-13  
keyword is specified in the rule array, 13 characters are processed; if the  
PAN-16 keyword is specified in the rule array, 16 characters are processed.  
Even if you specify the PAN-13 keyword, the server copies 16 bytes to a work  
area. Therefore, ensure that the verb can address 16 bytes of application  
storage.  
Chapter 8. Financial Services Support Verbs 8-31  
CVV_Verify  
CCA Release 2.54  
expiration_date  
The expiration_date parameter points to a string variable containing the card  
expiration date. The date is in numeric character format. The application  
programmer must determine whether the CVV will be calculated as YYMM or  
MMYY.  
service_code  
The service_code parameter points to a string variable containing the service  
code in character format. The service code is the number that the track-2,  
magnetic-stripe standards define.  
CVV_key-A_identifier  
The CVV_key-A_identifier parameter points to a string variable containing an  
internal key-token or a key label of an internal key-token record in key storage.  
The internal key-token contains the key-A key that encrypts information in the  
CVV process.  
CVV_key-B_identifier  
The CVV_key-B_identifier parameter points to a string variable containing an  
internal key-token or a key label of an internal key-token record in key storage.  
The internal key-token contains the key-B key that decrypts information in the  
CVV process.  
CVV_value  
The CVV_value parameter points to a string variable containing the CVV value  
in character format.  
Required Commands  
The CVV_Verify verb requires the Verify CVV command (command offset X'00E0')  
to be enabled in the hardware.  
8-32 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Generate  
Encrypted_PIN_Generate (CSNBEPG)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Encrypted_PIN_Generate verb generates and formats a PIN and encrypts the  
PIN block. To generate the PIN, the verb uses one of the following PIN calculation  
methods:  
IBM 3624 PIN  
IBM German Bank Pool Institution PIN  
Interbank PIN.  
To format the PIN, the verb uses one of the following PIN-block formats:  
IBM 3624  
ISO-0 (same as ANSI X9.8, VISA-1, and ECI-1 formats)  
ISO-1 (same as the ECI-4 format)  
ISO-2.  
You can use the Encrypted_PIN_Generate verb to generate a PIN and create an  
encrypted PIN-block for transmission or for later use in a PIN verification database.  
Note: To generate a clear PIN, use the Clear_PIN_Generate verb.  
To generate and format a PIN and encrypt the PIN block, specify the following:  
An internal key-token or a key label of an internal key-token record that  
contains the PIN-generating key with the PIN_generating_key_identifier  
parameter. The control vector in the key token must specify the PINGEN  
key-type and have the EPINGEN bit set to one.  
An internal key-token or a key label of an internal key-token record that  
contains the key to be used to encrypt the PIN block with the  
outbound_PIN_encrypting_key_identifier parameter. The control vector in the  
key token must specify the OPINENC key-type and have the EPINGEN bit set  
to one.  
One for the number of rule_array elements with the rule_array_count variable.  
The PIN-calculation method with a keyword in the rule_array variable.  
The length of the PIN for those PIN-calculation methods with variable-length  
PINs in the PIN_length variable. (Otherwise, the variable should be valued to  
zero.)  
A decimalization table and account validation data with the data_array  
parameter. For information about a decimalization table and calculation  
methods, see “PIN-Calculation Methods” on page E-2. For information about  
the data-array variable, see “Data_Array” on page 8-8.  
A PIN profile that specifies the format of the PIN block to be created, the level  
of format control, and any pad digit with the output_PIN_profile parameter. For  
more information about the PIN profile, see “PIN-Block Formats” on page E-9.  
One of the following with the PAN_data parameter:  
Chapter 8. Financial Services Support Verbs 8-33  
Encrypted_PIN_Generate  
CCA Release 2.54  
– When using the ISO-0 PIN-block format, specify a PAN. For information  
about a personal account number (PAN), see “Personal Account Number  
(PAN)” on page 8-13.  
– When using another PIN-block format, specify a 12-byte variable in  
application storage. The information in the variable will not be used, but  
the variable must be declared.  
With the sequence_number variable specify a four-byte integer variable valued  
to 99999.  
An eight-byte variable for the encrypted PIN with the encrypted_PIN_block  
parameter.  
The verb does the following:  
Verifies that the EPINGEN bit is one in the control vector for the PIN-generating  
key.  
Uses the specified PIN-calculation method and account validation data to  
calculate the PIN.  
Optionally uses the specified PIN length to determine the length of the PIN.  
Formats the PIN into the specified PIN-block format. The verb includes the  
clear PIN and, depending on the PIN-block format, the pad digit, the PAN, and  
the sequence number. For a description of the formats, see “PIN-Block  
Formats” on page E-9.  
Checks the control vector for the OPINENC key by verifying that the EPINGEN  
bit is one.  
Encrypts the PIN block in ECB mode according to the format-control keyword  
specified in the PIN profile.  
Restrictions  
Format  
None  
CSNBEPG  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
PIN_generating_key_identifier  
outbound_PIN_encrypting_key_identifier  
rule_array_count  
rule_array  
Input  
Input  
Input  
Input  
String  
String  
Integer  
String  
array  
one  
rule_array_count * 8 bytes  
PIN_length  
data_array  
PIN_profile  
Input  
Input  
Input  
Integer  
String  
String  
array  
16 bytes * 3  
3 * 8 bytes  
PAN_data  
sequence_number  
encrypted_PIN_block  
Input  
Input  
Output  
String  
Integer  
String  
12 bytes  
8 bytes  
8-34 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Generate  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
PIN_generating_key_identifier  
The PIN_generating_key_identifier parameter points to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage. The internal key-token contains the PIN-generating key and  
must contain a control vector that specifies a PINGEN key type and has the  
EPINGEN bit set to one.  
outbound_PIN_encrypting_key_identifier  
The outbound_PIN_encrypting_key_identifier parameter is a pointer to a string  
variable containing an internal key-token or a key label of an internal key-token  
record in key storage. The internal key-token contains the key to be used to  
encrypt the formatted PIN and must contain a control vector that specifies the  
OPINENC key type and has the EPINGEN bit set to one.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. This value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Figure 8-8. Encrypted_PIN_Generate Rule_Array Keywords  
Keyword  
Meaning  
Calculation method (one required)  
IBM-PIN  
GBP-PIN  
INBK-PIN  
This keyword specifies the IBM 3624 PIN-calculation method  
to be used to generate a PIN.  
This keyword specifies the IBM German Bank Pool Institution  
PIN calculation method to be used to generate a PIN.  
This keyword specifies the Interbank PIN-calculation method  
to be used to generate a PIN.  
PIN_length  
The PIN_length parameter is a pointer to an integer variable containing the PIN  
length for those PIN-calculation methods with variable-length PINs. Otherwise,  
the variable should be valued to zero.  
data_array  
The data_array parameter is a pointer to a string variable containing three  
16-byte character strings, which are equivalent to a single 48-byte string. The  
values in the data array depend on the keyword for the PIN-calculation method.  
Each element is not always used, but you must always declare a complete data  
array, see “Data_Array” on page 8-8.  
The numeric characters in each 16-byte string must be from 1 to 16 bytes in  
length, uppercase, left-justified, and padded on the right with space characters.  
The verb converts the space characters to zeros.  
Chapter 8. Financial Services Support Verbs 8-35  
Encrypted_PIN_Generate  
CCA Release 2.54  
PIN_profile  
The PIN_profile parameter is a pointer to a string variable containing the PIN  
profile including the PIN-block format. See “PIN Profile” on page 8-10.  
PAN_data  
The PAN_data parameter is a pointer to a string variable containing 12 digits of  
Personal Account Number (PAN) data. The verb uses this parameter if the PIN  
profile specifies ISO-0 for the PIN-block format. Otherwise, ensure that this  
parameter is a pointer to a four-byte variable in application storage. The  
information in this variable is ignored, but this variable must be declared.  
Note: When using the ISO-0 keyword, use the 12 rightmost digits of the PAN  
data, excluding the check digit.  
sequence_number  
The sequence_number parameter is a pointer to a string variable containing the  
sequence number used by certain PIN-block formats. Ensure that this  
parameter is a pointer to a four-byte variable in application storage.  
encrypted_PIN_block  
The encrypted_PIN_block parameter is a pointer to a string variable containing  
the encrypted PIN-block returned by the verb.  
Required Commands  
The Encrypted_PIN_Generate verb requires the following commands to be enabled  
in the cryptographic engine based on the keyword specified for the PIN-calculation  
methods.  
PIN-Calculation Method  
Command Offset  
Command  
IBM-PIN  
X'00B0'  
Generate Formatted and  
Encrypted 3624 PIN  
GBP-PIN  
INBK-PIN  
X'00B1'  
Generate Formatted and  
Encrypted German Bank Pool  
PIN  
X'00B2'  
Generate Formatted and  
Encrypted Interbank PIN  
8-36 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Translate  
Encrypted_PIN_Translate (CSNBPTR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Encrypted_PIN_Translate verb can change PIN block encryption, and  
optionally format a PIN into a different PIN-block format. You can use this verb in  
an interchange-network application, or to change the PIN block to conform to the  
format and encryption key used in a PIN-verification database. The verb also  
supports derived Unique Key Per Transaction (UKPT) PIN-block encryption (ANSI  
X9.24) for both input and output PIN blocks.  
Supported PIN-block formats:  
IBM 3624  
ISO-0 (equivalent to ANSI X9.8, VISA-1, and ECI-1 formats).  
ISO-1 (same as the ECI-4 format)  
ISO-2.  
The verb operates in one of two modes:  
In translate mode the verb decrypts a PIN block using an input key that you  
supply, or that is derived from other information that you supply. The cleartext  
information is then encrypted using an output key that you supply, or that is  
derived from other information that you supply. The cleartext is not examined.  
In reformat mode the verb performs the translate-mode functions and in  
addition processes the cleartext information. Following rules that you specify,  
the PIN is recovered from the input cleartext PIN-block and formatted into an  
output PIN-block for encryption.  
To use this verb, specify:  
The mode of operation with a keyword in the rule array: TRANSLAT or  
REFORMAT  
Optionally, the method of PIN extraction with a rule-array keyword  
Optionally, unique-key-per-transaction processing (UKPT) on input and/or  
output with rule array keywords: UKPTIPIN, UKPTOPIN, or UKPTBOTH  
Input and output PIN-block encrypting keys, or the base key(s) used to derive  
the PIN-block enciphering keys  
Input and output PIN profiles, which for UKPT processing are extended with the  
“current key serial number” (CKSN). See “PIN Profile” on page 8-10,“Current  
Key Serial Number” on page 8-11 , and “UKPT Calculation Methods” on  
page E-13.  
Input and output PAN data as required by the selected PIN-block formats  
An output PIN-block sequence number as required by the selected PIN-block  
format, or specify a value of 99999.  
The verb does the following:  
Decrypts the input PIN-block by using the supplied IPINENC key in ECB mode,  
or derives the decryption key using the specified KEYGENKY key and current  
Chapter 8. Financial Services Support Verbs 8-37  
Encrypted_PIN_Translate  
CCA Release 2.54  
key serial number, and then uses ANSI X9.24-specified “special decryption.”  
Checks the control vector to ensure that for an IPINENC key that the  
TRANSLAT bit is valued to one for translate mode and/or the REFORMAT bit is  
valued to one for reformat mode, or for a KEYGENKY key that the UKPT bit is  
valued to one. Likewise the OPINENC key must have one or both of the  
TRANSLAT and REFORMAT bits set appropriate to the requested mode.  
In reformat mode, the verb performs these additional steps:  
– Extracts the PIN from the specified PIN-block format using the method  
specified by default or by a rule-array keyword. If required by the  
PIN-block format, PAN data will be used in the extraction process.  
– Formats the extracted-PIN into the format declared for the output  
PIN-block. As required by the PIN-block format, the verb incorporates PAN  
data, sequence number, and pad character information in formatting the  
output.  
Encrypts the output PIN-block by using the supplied OPINENC key in ECB  
mode, or derives the decryption key using the specified KEYGENKY key and  
output current key serial number and uses ANSI X9.24-specified “special  
encryption.” The TRANSLAT bit must be valued to one in the OPINENC control  
vector, or the UKPT bit must be valued to one in the KEYGENKY control  
vector.  
Restrictions  
Format  
Some CCA implementations may enforce a specific order of the rule array  
keywords with this verb; see product-specific literature.  
Previous editions of this manual incorrectly described the CKSN as requiring  
space-character padding. Pad the CKSN with four bytes of X'00'.  
CSNBPTR  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
input_PIN_encrypting_key_identifier  
output_PIN_encrypting_key_identifier  
input_PIN_profile  
Input  
Input  
Input  
String  
String  
String  
array  
24 or 48 bytes  
input_PAN_data  
input_PIN_block  
rule_array_count  
rule_array  
Input  
Input  
Input  
Input  
String  
String  
Integer  
String  
array  
12 bytes  
8 bytes  
one, two, or three  
rule_array_count * 8 bytes  
output_PIN_profile  
Input  
String  
array  
String  
Integer  
String  
24 or 48 bytes  
12 bytes  
output_PAN_data  
sequence_number  
output_PIN_block  
Input  
Input  
Output  
8 bytes  
8-38 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Translate  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
input_PIN_encrypting_key_identifier  
The input_PIN_encrypting_key_identifier parameter is a pointer to a string  
variable containing an internal key-token or a key label of an internal key-token  
record in key storage.  
If you do not use the unique-key-per-transaction process, the internal key-token  
must contain the input PIN-block encrypting key to be used to decrypt the input  
PIN-block. The control vector in the key token must specify the IPINENC  
key-type and have one or both of the TRANSLAT and REFORMAT bits set to  
one as appropriate to the requested mode.  
If you use the unique-key-per-transaction process for the input PIN-block,  
specify the base derivation key as a KEYGENKY key-type with the UKPT bit  
valued to one.  
output_PIN_encrypting_key_identifier  
The output_PIN_encrypting_key_identifier parameter is a pointer to a string  
variable containing an internal key-token or a key label of an internal key-token  
record in key storage.  
If you do not use the unique-key-per-transaction process, the internal key-token  
must contain the output PIN-block encrypting key to be used to encrypt the  
output PIN-block. The control vector in the key token must specify the  
OPINENC key-type and have one or both of the TRANSLAT and REFORMAT  
bits set to one as appropriate to the requested mode.  
If you use the unique-key-per-transaction process for the output PIN-block,  
specify the base derivation key as a KEYGENKY key-type with the UKPT bit  
valued to one.  
input_PIN_profile  
The input_PIN_profile parameter is a pointer to a string variable containing  
three 8-byte character strings with information defining the PIN-block format,  
and optionally an additional 24 bytes containing the input current key serial  
number (CKSN). The strings are equivalent to 24-byte or 48-byte strings. For  
more information about a PIN profile, see “PIN Profile” on page 8-10.  
input_PAN_data  
The input_PAN_data parameter is a pointer to a string variable containing the  
personal account number (PAN) data. The verb uses this data to recover the  
PIN from the PIN block if you specify the REFORMAT keyword and the input  
PIN profile specifies the ISO-0 keyword for the PIN-block format.  
Note: When using the ISO-0 format, use the 12 rightmost digits of PAN,  
excluding the check digit.  
input_PIN_block  
The input_PIN_block parameter is a pointer to a string variable containing the  
encrypted PIN-block.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. This value must be one,  
two, or three for this verb.  
Chapter 8. Financial Services Support Verbs 8-39  
Encrypted_PIN_Translate  
CCA Release 2.54  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
Keyword  
Meaning  
Mode (one required)  
TRANSLAT  
This keyword specifies that only PIN-block encryption is  
changed.  
REFORMAT  
This keyword specifies that either or both the the PIN-block  
format and the PIN-block encryption are to be changed.  
If the PIN-extraction method is not chosen by default, another  
element in the rule array must specify one of the keywords  
that indicates a PIN-extraction method as listed in Figure 8-9.  
For more information about extraction methods, see  
“PIN-Extraction Methods” on page 8-12.  
Unique Key per Transaction (one, optional)  
UKPTIPIN  
UKPTOPIN  
UKPTBOTH  
Specifies the use of UKPT input-key derivation and PIN-block  
decryption.  
Specifies the use of UKPT output-key derivation and  
PIN-block encryption.  
Specifies the use of UKPT key-derivation and PIN-block  
ciphering for both input and output processing.  
PIN-extraction method (one, optional)  
See Figure 8-9.  
Figure 8-9. Encrypted_PIN_Translate Rule_Array Keywords  
PIN-Block  
Format  
PIN-Extraction  
Method  
Meaning  
PIN-extraction method (one, optional)  
Note: You specify the PIN-block format keyword in the PIN profile variable.  
3624  
PADDIGIT,  
HEXDIGIT,  
PINLEN04 to  
PINLEN16,  
PADEXIST  
The PIN-extraction method keywords  
specify a PIN extraction method for an IBM  
3624 PIN-block format. The first keyword,  
PADDIGIT, is the default PIN-extraction  
method for the 3624 PIN-block format.  
ISO-0  
ISO-1  
ISO-2  
PINBLOCK  
PINBLOCK  
PINBLOCK  
This keyword specifies the default  
PIN-extraction method for an ISO-0  
PIN-block format.  
This keyword specifies the default  
PIN-extraction method for an ISO-1  
PIN-block format.  
This keyword specifies the default  
PIN-extraction method for an ISO-2  
PIN-block format.  
output_PIN_profile  
The output_PIN_profile parameter is a pointer to a string variable containing  
three 8-byte character strings with information defining the PIN-block format,  
8-40 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Translate  
and optionally an additional 24 bytes containing the output current key serial  
number (CKSN). The strings are equivalent to 24-byte or 48-byte strings. For  
more information about a PIN profile, see “PIN Profile” on page 8-10.  
output_PAN_data  
The output_PAN_data parameter is a pointer to a string variable containing the  
personal account number (PAN) data. If you specify the REFORMAT keyword,  
and if the output PIN-profile specifies the ISO-0 keyword for the PIN-block  
format, the verb uses this data to format the output PIN-block. In any case,  
ensure that this parameter points to a 12-byte variable in application storage.  
Note: When using the ISO-0 format, use the 12 rightmost digits of PAN,  
excluding the check digit.  
sequence_number  
The sequence_number parameter is a pointer to an integer variable containing  
the sequence number. Ensure that this parameter is a pointer to an integer  
variable valued to 99999.  
output_PIN_block  
The output_PIN_block parameter is a pointer to a string variable containing the  
reenciphered and optionally reformatted PIN-block returned by the verb.  
Required Commands  
The Encrypted_PIN_Translate verb requires the commands shown in Figure 8-10  
to be enabled in the active hardware based on the keyword specified for translation  
or reformatting and the format control in the PIN profile. You should enable only  
those commands that are required.  
Figure 8-10. Encrypted_PIN_Translate Required Hardware Commands  
TRANSLAT or  
REFORMAT  
Keyword  
Input  
Output  
Profile  
Format  
Control  
Keyword  
Command Command  
Offset  
Profile  
Format  
Control  
Keyword  
TRANSLAT  
REFORMAT  
NONE  
NONE  
X'00B3'  
Translate PIN with No  
Format-Control to No  
Format-Control  
NONE  
NONE  
X'00B7'  
Reformat PIN with No  
Format-Control to No  
Format-Control  
The Encrypted_PIN_Translate verb also requires the Unique Key Per Transaction,  
ANSI X9.24 command (offset X'00E1') to be enabled if you employ UKPT  
processing.  
Chapter 8. Financial Services Support Verbs 8-41  
Encrypted_PIN_Verify  
CCA Release 2.54  
Encrypted_PIN_Verify (CSNBPVR)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The Encrypted_PIN_Verify verb extracts a trial PIN (T-PIN) from an encrypted  
PIN-block and verifies this value by comparing it to an account PIN (A-PIN)  
calculated by using the specified PIN-calculation method. Certain PIN-calculation  
methods modify the value of the A-PIN with the clear offset (O-PIN) value prior to  
the comparison. The verb also supports derived Unique Key Per Transaction  
(UKPT) PIN-block encryption (ANSI X9.24) for decrypting the input PIN block.  
Supported PIN-block formats:  
IBM 3624  
ISO-0 (equivalent to ANSI X9.8, VISA-1, and ECI-1 formats).  
ISO-1 (same as the ECI-4 format)  
ISO-2.  
Supported PIN-calculation methods:  
IBM 3624 PIN  
IBM 3624 PIN Offset  
IBM German Bank Pool Institution PIN  
VISA-PVV  
Interbank PIN.  
To use this verb, specify:  
Processing choices using rule-array keywords:  
– A PIN-calculation method  
– Optionally, a PIN-extraction method  
– Optionally, unique-key-per-transaction processing (UKPT) with the  
UKPTIPIN keyword  
An input PIN-block decrypting key, or the base key used to derive the  
PIN-block enciphering key.  
A PIN-verifying key to be used to calculate the PIN.  
A PIN profile for the input PIN-block, which for UKPT processing must be  
extended with the current key sequence number (CKSN). See “PIN Profile” on  
page 8-10, “Current Key Serial Number” on page 8-11, and “UKPT Calculation  
Methods” on page E-13.  
When using the ISO-0 block format, a PAN to be used in extracting the PIN.  
See “Personal Account Number (PAN)” on page 8-13.  
The PIN block that contains the PIN to be verified.  
The length of the PIN to be checked if you specify the IBM-PIN or the  
IBM-PINO calculation methods in the rule array.  
In the data array: a decimalization table, account validation data, and for certain  
calculation methods, an offset value  
8-42 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Verify  
The verb does the following:  
Decrypts the input PIN-block by using the supplied IPINENC key in ECB mode,  
or derives the decryption key using the specified KEYGENKY key and CKSN  
and uses ANSI X9.24-specified “special decryption.” The EPINVER bit must be  
valued to one in the IPINENC control vector, or the UKPT bit must be valued to  
one in the KEYGENKY control vector. See “PIN Profile” on page 8-10 and  
“UKPT Calculation Methods” on page E-13.  
Extracts the trial PIN (T-PIN) from the specified PIN-block format using the  
method specified by default or by a rule array keyword. If required by the  
PIN-block format, PAN data and/or the pad digit will be used in the extraction  
process.  
Verifies use of a PINVER or PINGEN key type having the EPINVER bit valued  
to one in the control vector of the PIN-verifying key  
Calculates the account-number-based PIN (A-PIN)  
For methods that employ an offset, modifies the A-PIN value with the offset  
(O-PIN) value entered in the third element of the data array variable. The  
NOOFFSET bit must be valued to zero in the control vector of the PIN-verifying  
key when employing the IBM 3624 PIN Offset calculation method.  
Compares the extracted trial (T-PIN) with the possibly modified account PIN  
(A-PIN) and reports the results in the return code variable. Return code four  
indicates a verification failure while return code zero indicates success.  
Restrictions  
Format  
Some CCA implementations may enforce a specific order of the rule array  
keywords with this verb; see product-specific literature.  
Previous editions of this manual incorrectly described the CKSN as requiring  
space-character padding. Pad the CKSN with four bytes of X'00'.  
CSNBPVR  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
PIN_encrypting_key_identifier  
PIN_verifying_key_identifier  
PIN_profile  
In/Output Integer  
In/Output String  
exit_data_length bytes  
64 bytes  
64 bytes  
Input  
Input  
Input  
String  
String  
String  
array  
24 or 48 bytes  
PAN_data  
Input  
Input  
Input  
Input  
String  
String  
Integer  
String  
array  
12 bytes  
8 bytes  
one, two, or three  
rule_array_count * 8 bytes  
encrypted_PIN_block  
rule_array_count  
rule_array  
PIN_check_length  
data_array  
Input  
Input  
Integer  
String  
array  
3 * 16 bytes  
Chapter 8. Financial Services Support Verbs 8-43  
Encrypted_PIN_Verify  
CCA Release 2.54  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
PIN_encrypting_key_identifier  
The PIN_encrypting_key_identifier parameter is a pointer to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage.  
If you do not use the unique-key-per-transaction process, the internal key-token  
must contain the input PIN-block encrypting key to be used to decrypt the input  
PIN-block. The control vector in the key token must specify the IPINENC  
key-type with EPINVER bit valued to one.  
If you use the unique-key-per-transaction process for the input PIN-block,  
specify the base derivation key as a KEYGENKY key-type with the UKPT bit  
valued to one.  
PIN_verifying_key_identifier  
The PIN_verifying_key_identifier parameter points to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage. The internal key-token contains the key used to generate the  
account-number-based PIN (A-PIN). The control vector in the internal  
key-token must specify a PINVER or PINGEN key-type. For a PINGEN (and  
PINVER) key, the EPINVER bit must be one.  
PIN_profile  
The PIN_profile parameter is a pointer to a string variable containing three  
8-byte character strings with information defining the PIN-block format, and  
optionally an additional 24 bytes containing the input current key serial number  
(CKSN). The strings are equivalent to 24-byte or 48-byte strings. For more  
information about a PIN profile, see “PIN Profile” on page 8-10 and “Current  
Key Serial Number” on page 8-11.  
PAN_data  
The PAN_data parameter is a pointer to a string variable containing the  
personal account number (PAN) data. The verb uses the PAN data to recover  
the PIN from the PIN block if the PIN profile specifies the ISO-0 keyword for the  
PIN-block format. Otherwise, ensure that this parameter is a pointer to a  
12-byte variable in application storage.  
Note: When using the ISO-0 format, use the 12 rightmost PAN digits,  
excluding the check digit.  
encrypted_PIN_block  
The encrypted_PIN_block parameter points to a string variable containing the  
encrypted PIN-block.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one,  
two, or three for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
8-44 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Verify  
Keyword  
Meaning  
Calculation method (one required)  
IBM-PIN  
This keyword specifies that the IBM 3624 PIN-calculation  
method is to be used.  
IBM-PINO  
GBP-PIN  
VISA-PVV  
VISAPVV4  
This keyword specifies that the IBM 3624 PIN Offset  
calculation method is to be used.  
This keyword specifies that the IBM German Bank Pool  
Institution PIN-calculation method is to be used.  
This keyword specifies that the VISA-PVV PIN-calculation  
method is to be used.  
This keyword specifies that the VISA-PVV PIN-calculation  
method is to be used. Acceptable PINs must be exactly four  
digits in length.  
INBK-PIN  
This keyword specifies that the Interbank PIN-calculation  
method is to be used.  
Unique Key Per Transaction (one, optional)  
UKPTIPIN Specifies the use of UKPT input-key derivation and PIN-block  
decryption.  
PIN-extraction method (one, optional)  
See Figure 8-11 on page 8-45.  
Figure 8-11. Encrypted_PIN_Verify PIN-Extraction Method  
PIN-Block  
Format  
PIN-Extraction  
Method  
Meaning  
3624  
PADDIGIT,  
HEXDIGIT,  
PINLEN04 to  
PINLEN16,  
PADEXIST  
The PIN-extraction method keywords  
specify a PIN-extraction method for an IBM  
3624 PIN-block format. The first keyword,  
PADDIGIT, is the default PIN-extraction  
method for the 3624 PIN-block format.  
ISO-0  
ISO-1  
ISO-2  
PINBLOCK  
PINBLOCK  
PINBLOCK  
This keyword specifies the default  
PIN-extraction method for an ISO-0  
PIN-block format.  
This keyword specifies the default  
PIN-extraction method for an ISO-1  
PIN-block format.  
This keyword specifies the default  
PIN-extraction method for an ISO-2  
PIN-block format.  
PIN_check_length  
The PIN_check_length parameter is a pointer to an integer variable containing  
the number of digits of PIN information that the verb should verify. The verb  
uses the value in the variable if you specify the IBM-PIN or IBM-PINO keyword  
for the calculation method. The specified number of digits is selected from the  
low order (right side) of the PIN. Ensure that this parameter always points to  
an integer variable in application storage.  
Note: The PIN check length must be less than or equal to the PIN length and  
in the range from 4 to 16.  
Chapter 8. Financial Services Support Verbs 8-45  
Encrypted_PIN_Verify  
CCA Release 2.54  
data_array  
The data_array parameter is a pointer to a string variable containing three  
16-byte character strings, which are equivalent to a single 48-byte string. The  
values you specify in the data array depend on the PIN-calculation method.  
Each element is not always used, but you must always declare a complete  
48-byte data array.  
When using the IBM-PIN, IBM-PINO or GBP-PIN keyword, identify the  
following elements in the data array.  
Element  
Description  
decimalization_table  
This element contains the decimalization  
table of 16 characters (0 to 9) that are used  
to convert the hexadecimal digits  
(X'0' to X'F') of the encrypted validation  
data to decimal digits (X'0' to X'9').  
validation_data  
offset data  
This 16-byte element contains 1 to 16  
characters of account data. The data must  
be left-justified and padded on the right with  
space characters. (To conform with industry  
practice, any hexadecimal character can be  
specified.)  
When using the IBM-PINO keyword, this  
16-byte element contains the offset data  
which must be left-justified and padded on  
the right with space characters. The PIN  
length specifies the number of digits that are  
processed for the IBM-PINO PIN-calculation  
method.  
When using the IBM-PIN or GBP-PIN  
keyword, this element is ignored, but must  
be declared.  
8-46 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Encrypted_PIN_Verify  
When using the VISA-PVV or VISAPVV4 keywords, identify the following  
elements in the data array. For more information about these elements, and  
transaction security data for the VISA-PVV calculation method, see “VISA PIN  
Validation Value (PVV) Calculation Method” on page E-7.  
Element  
Description  
transaction_security_parameter  
This element contains 16 characters that  
include the following:  
Eleven (rightmost) digits of PAN data  
One digit of key index from one to six  
Four space characters.  
PVV (O-PIN)  
reserved_3  
This 16-byte element contains four numeric  
characters, which are the referenced PVV  
value. This value is followed by 12 space  
characters.  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
When using the INBK-PIN keyword, identify the following elements in the data  
array. For more information about these elements and transaction security  
data for the Interbank calculation method, see “Interbank PIN-Calculation  
Method” on page E-8.  
Element  
Description  
transaction_security_parameter  
This element contains 16 numeric  
characters that include the following:  
Eleven (rightmost) digits of PAN data  
A constant of six  
A one-digit key index selector from one  
to six  
Three numeric characters of validation  
data.  
reserved_2  
reserved_3  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
The information in this element will be  
ignored, but the 16-byte element must be  
declared.  
Chapter 8. Financial Services Support Verbs 8-47  
Encrypted_PIN_Verify  
CCA Release 2.54  
Required Commands  
The Encrypted_PIN_Verify verb requires the following commands to be enabled in  
the hardware, based on the keyword specified for the PIN-calculation methods.  
PIN-Calculation  
Method  
Command  
Offset  
Command  
IBM-PIN,  
IBM-PINO  
GBP-PIN  
VISA-PVV,  
VISAPVV4  
INBK-PIN  
NL-PIN-1  
X'00AB'  
Verify Encrypted 3624 PIN  
X'00AC'  
X'00AD'  
Verify Encrypted German Bank Pool PIN  
Verify Encrypted VISA-PVV  
X'00AE'  
X'0232'  
Verify Encrypted Interbank PIN  
Verify Encrypted NL-PIN-1  
The Encrypted_PIN_Translate verb also requires the Unique Key Per Transaction,  
ANSI X9.24 command (offset X'00E1') to be enabled if you employ UKPT  
processing.  
8-48 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Encryption_Translate  
Key_Encryption_Translate (CSNBKET)  
|
|
|
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
|
IBM 4758-2/23  
X
|
|
|
|
|
|
The Key_Encryption_Translate verb is used to change the method of key  
encryption. An input key can be a double-length external CCA DATA key or a  
double-length CBC-encrypted key. The returned key is encrypted using the other  
method, CBC encryption or CCA (ECB) encryption. The CCA DATA key must be  
double-length and have an all-zero control vector. The CBC-encrypted key is  
treated as a 16-byte string encrypted using an all-zero initialization vector.  
|
|
You specify the following:  
1. The translation reencryption operation using a rule-array keyword:  
|
|
CBCTOECB to change from CBC key-encryption to CCA (ECB) encryption  
ECBTOCBC to change from CCA (ECB) key-encryption to CBC encryption.  
|
2. The key-encrypting key.  
|
|
When performing the CBCTOECB translation, specify an IMPORTER key  
When performing the ECBTOCBC translation, specify an EXPORTER key.  
|
|
|
3. Using the key_in parameter, identify either a 64-byte external CCA DATA  
key-token or a 16-byte CBC encrypted key. Set the key_in_length variable to  
the length of the key_in variable.  
|
|
|
4. Using the key_out parameter, identify either a 64-byte external CCA DATA  
key-token with an all-zero control vector, or a 16-byte string. Set the  
key_out_length variable to the length of the key_out variable.  
|
The verb does the following:  
|
|
Recovers the key-encrypting key and checks that its type is consistent with the  
requested translation, ECBTOCBC or CBCTOECB.  
|
|
Decrypts the supplied key_in key using the key-encrypting key, and encrypts  
the result again using the key-encrypting key.  
|
|
For CBCTOECB translation, the key_out variable is updated with the data key  
in an external token with an all-zero control vector.  
|
For ECBTOCBC translation, the key is returned in a 16-byte string.  
|
|
Restrictions  
None  
Chapter 8. Financial Services Support Verbs 8-49  
Key_Encryption_Translate  
CCA Release 2.54  
|
|
Format  
CSNBKET  
|
|
|
|
|
|
|
|
|
|
|
|
|
|
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
kek_key_identifier_length  
kek_key_identifier  
Input  
In/Output String  
Integer  
64  
kek_key_identifier_length  
bytes  
16 or 64  
key_in_length bytes  
16 or 64  
key_out_length bytes  
key_in_length  
key_in  
key_out_length  
key_out  
Input  
Input  
In/Output Integer  
Output String  
Integer  
String  
|
Parameters  
|
|
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
|
|
|
|
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. This value must be one for  
this verb.  
|
|
|
|
|
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
|
|
Keyword  
Meaning  
Key translation method (one required)  
|
|
|
CBCTOECB  
ECBTOCBC  
This keyword specifies decryption of a 16-byte string and CCA  
key-encryption of the resulting clear (key) value as an external  
CCA DATA key.  
|
|
This keyword specifies decryption of a CCA DATA key and  
CBC encryption of the resulting clear key.  
|
|
|
kek_identifier_length  
The kek_identifier_length parameter is a pointer to an integer variable  
containing a value of 64, the length of a CCA DES key token.  
|
|
|
kek_identifier  
The kek_identifier parameter is a pointer to a string variable containing the  
key-encrypting key key-token or key label of a key-token record.  
|
|
|
key_in_length  
The key_in_length parameter points to an integer variable valued to 16 for the  
CBCTOECB translation or valued to 64 for the ECBTOCBC translation.  
|
|
|
key_in  
The key_in parameter points to a string variable containing either a CCA  
external key-token or a 16-byte CBC-encrypted key.  
8-50 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Encryption_Translate  
|
|
|
|
|
key_out_length  
The key_out_length parameter points to an integer variable. On input, you  
should set the variable to at least 64 for the CBCTOECB translation or to at  
least 16 for the ECBTOCBC translation. On successful completion, the verb  
will set the variable to the length of the returned key_out variable.  
|
|
|
|
key_out  
The key_out parameter points to a string variable. The verb returns the  
encrypted key in either a CCA external DATA key-token with an all-zero control  
vector or a 16-byte string.  
|
Required Commands  
|
|
The Key_Encryption_Translate verb requires the following commands to be enabled  
in the active role based on the keyword specified in the rule array.  
|
|
For CBCTOECB translation, enable the Translate Key from CBC to ECB  
command (offset X'030D').  
|
|
For ECBTOCBC translation, enable the Translate Key from ECB to CBC  
command (offset X'030E').  
Chapter 8. Financial Services Support Verbs 8-51  
PIN_Change/Unblock  
CCA Release 2.54  
PIN_Change/Unblock (CSNBPCU)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
X
IBM 4758-23  
Use the PIN_Change/Unblock verb to prepare an encrypted message-portion for  
communicating an original or replacement PIN for an EMV smart-card. The verb  
embeds the PIN(s) in an encrypted PIN-block from information that you supply.  
You incorporate the information created with the verb in a message sent to the  
smart card.  
The processing is consistent with the specifications provided in these documents:  
EMV 2000 Integrated Circuit Card Specification for Payment Systems Version  
4.0 (EMV4.0) Book 2  
Design VISA Integrated Circuit Card Specification Manual.  
You specify:  
Through the optional choice of one rule-array keyword, the key-diversification  
process to employ in deriving the session key used to encrypt the PIN block.  
See “VISA and EMV-Related Smart Card Formats and Processes” on  
page E-17 for processing details.  
TDES-XOR An exclusive-OR process described in the appendix. You can  
omit this keyword as it is the default process.  
TDESEMV2 The tree-based-diversification process with a “branch factor” of 2.  
TDESEMV4 The tree-based-diversification process with a “branch factor” of 4.  
Through the required choice of one rule-array keyword, if you are providing a  
PIN for a smart card with, or without, an existing (current) PIN:  
VISAPCU1 For a card without a PIN, you provide the new PIN in an  
encrypted PIN-block in the new_reference_PIN_block variable.  
The contents of current_reference_PIN... variables are ignored.  
VISAPCU2 For a card with a current PIN, you provide the existing PIN in an  
encrypted PIN-block in the current_reference_PIN_block variable,  
and supply the new PIN-value in an encrypted PIN-block in the  
new_reference_PIN_block variable.  
Issuer-provided master-derivation keys (MDK). The card-issuer provides two  
keys for diversifying the same data:  
– The MAC-MDK key which you incorporate in the variable specified by the  
authentication_key_identifier parameter. The verb uses this key to derive  
an authentication value incorporated in the PIN block. The control vector  
for the MAC-MDK key must specify a DKYGENKY key type with DKYL0  
(level-0), and DMAC or DALL permissions. See Figure C-3 on page C-5.  
– The ENC-MDK key which you incorporate in the variable specified by the  
encryption_key_identifier parameter. The verb uses this key to derive the  
PIN-block encryption key. The control vector for the ENC-MDK key must  
specify a DKYGENKY key type with DKYL0 (level-0), and DMPIN or DALL  
permissions.  
8-52 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PIN_Change/Unblock  
See “VISA and EMV-Related Smart Card Formats and Processes” on  
page E-17 which explains the derivation processes and PIN-block formation.  
The diversification_data_length to indicate the sum of the lengths of:  
– Data, 8 or 16 bytes, encrypted by the verb using the MDK keys  
– The 2-byte Application Transfer Counter (ATC)  
(You receive the ATC value from the EMV smart card.)  
– The optional 16-byte Initial Value used in the TDESEMVn processes.  
Valid lengths are 10, 18, 26, and 34 bytes.  
The diversification_data variable. Concatenate the 8 or 16-byte data, the ATC,  
and optionally the Initial Value.  
The 16-bit ATC counter is processed as a two-byte string, not as an integer  
value.  
The new-reference PIN in an encrypted PIN block. You provide:  
– The key to decrypt the PIN block  
– The PIN block  
– The format information that defines how to parse the PIN block  
– When using an ISO-0 format PIN block, personal-account number (PAN)  
information to enable PIN recovery from the ISO-0 format PIN block.  
If you specified VISAPCU2 (because the target smart card already has a PIN),  
the current_reference_PIN in an encrypted PIN block with the associated  
decrypting key, PIN-block format, and PAN data. In any case, you must  
declare current_reference_PIN... variables.  
The output_PIN_message variable to receive the encrypted PIN block for the  
smart card, and the length in bytes of the PIN block (16). The PIN-block format  
you specify (VISAPCU1 or VISAPCU2) corresponds to the one or two PIN  
values to be communicated to the smart card.  
You must declare two variables which are reserved for future use:  
output_PIN_data_length (valued to zero), and an output_PIN_data string  
variable (or set the associated parameter to a null pointer).  
The PIN_Change/Unblock verb:  
Decrypts the MDK keys and verifies the required control vector permissions.  
Diversifies the left-most eight bytes of data using the MAC-MDK key to obtain  
the authentication value for placement into the PIN block.  
Recovers the supplied PIN value(s) provided that PIN-block encrypting keys are  
one of IPINENC or OPINENC type, and the use of the specific type is  
authorized with the appropriate access-control command.  
Constructs and pads the output PIN block to a 16-byte string. See  
“Constructing the PIN-block for Transporting an EMV Smart-Card PIN” on  
page E-17.  
Generates the session key used to encrypt the output-PIN block using the  
ENC-MDK, the key_generation_data, the ATC counter value, and the optional  
Initial Value.  
Triple encrypts the 16-byte padded PIN-block in ECB mode.  
Returns the encrypted, padded PIN-block in the output_PIN_message variable.  
Chapter 8. Financial Services Support Verbs 8-53  
PIN_Change/Unblock  
CCA Release 2.54  
Restrictions  
This verb is supported beginning with Release 2.50. Support for the TDESEMV2  
and TDESEMV4 keywords begins with Release 2.51.  
Format  
CSNBPCU  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
authentication_key_identifier_length  
authentication_key_identifier  
encryption_key_identifier_length  
encryption_key_identifier  
diversification_length  
diversification_data  
new_reference_PIN_key_identifier_length  
new_reference_PIN_key_identifier  
new_reference_PIN_block  
new_reference_PIN_profile  
new_reference_PIN_PAN_data  
current_reference_PIN_key_identifier_length  
current_reference_PIN_key_identifier  
current_reference_PIN_block  
current_reference_PIN_profile  
current_reference_PIN_PAN_data  
output_PIN_data_length  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
Integer  
String  
Integer  
String  
String  
String  
String  
Integer  
String  
String  
String  
String  
Integer  
String  
String  
64  
64  
10, 18, 26, or 34  
64  
64 bytes  
8 bytes  
3*8 bytes  
12 bytes  
64  
64 bytes  
8 bytes  
3*8 bytes  
12 bytes  
0
Can be null  
3*8 bytes  
output_PIN_data  
output_PIN_profile  
output_PIN_message_length  
output_PIN_message  
In/Output Integer  
Output String  
16  
output_PIN_message_length  
bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter points to an integer variable containing the  
number of elements in the rule_array variable. The value must be one or two  
for this verb.  
rule_array  
The rule_array parameter points to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
8-54 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PIN_Change/Unblock  
Keyword  
Meaning  
Diversification process (one, optional)  
TDES-XOR  
TDESEMV2  
This keyword specifies to diversify the issuer-master-key using  
triple DES and an exclusive-OR process. This is the default  
process.  
This keyword specifies to diversify the issuer-master-key using  
the EMV tree-based function, branch factor 2. See EMV 4.0  
Book 2, Annex A1.3.1, and “VISA and EMV-Related Smart  
Card Formats and Processes” on page E-17.  
TDESEMV4  
This keyword specifies to diversify the issuer-master-key using  
the EMV tree-based function, branch factor 4.  
Output PIN creation process (one required)  
VISAPCU1  
This keyword specifies to create the output PIN from the  
new-reference PIN and the smart-card-unique, intermediate  
key.  
VISAPCU2  
This keyword specifies to create the output PIN from the  
new-reference PIN and the smart-card-unique, intermediate  
key, and the current-reference PIN.  
authentication_key_identifier_length  
The authentication_key_identifier_length parameter points to an integer variable  
set to 64. This is the string length of the related key identifier.  
authentication_key_identifier  
The authentication_key_identifier parameter points to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage. The internal key-token contains the MAC-MDK key used to  
diversify the data to form the authentication value. The control vector for this  
key must specify a DKYGENKY key type with DKYL0 (level-0), and DMAC or  
DALL permissions. Both halves of this double-length key must be unique. See  
Figure C-3 on page C-5.  
encryption_key_identifier_length  
The encryption_key_identifier_length parameter points to an integer variable set  
to 64. This is the string length of the related key identifier.  
encryption_key_identifier  
The encryption_key_identifier parameter points to a string variable containing  
an internal key-token or a key label of an internal key-token record in key  
storage. The internal key-token contains the ENC-MDK key used to diversify  
the data to form the output PIN-block encryption key. The control vector for  
this key must specify a DKYGENKY key type with DKYL0 (level-0), and DMPIN  
or DALL permissions. Both halves of this double-length key must be unique.  
diversification_data_length  
The diversification_data_length parameter points to an integer set to the  
byte-length of the data used in the generation of the authentication value and  
the PIN-block encryption key. With TDES-XOR use a length of 10 or 18. With  
TDESEMV2 and TDESEMV4 use a length of 10, 18, 26 or 34.  
diversification_data  
The diversification_data parameter points to a string variable. Form the  
variable by concatenating two or three values:  
Chapter 8. Financial Services Support Verbs 8-55  
PIN_Change/Unblock  
CCA Release 2.54  
The first 8 or 16 bytes of data should contain the value used to form the  
smart-card-specific authentication value and the PIN-block encryption key.  
The next two bytes of data contain the 16-bit ATC counter used to further  
diversify the ENC-MDK key to form the session key used to encrypt the  
output PIN block. The high-order counter bit is in the left-most counter  
byte.  
When using the TDESEMV2 or TDESEMV4 tree-based diversification  
process, you can concatenate an optional 16-byte Initial Value. (Otherwise  
the verb substitutes 16 bytes of X'00'.)  
new_reference_PIN_key_identifier_length  
The new_reference_PIN_key_identifier_length parameter points to an integer  
variable set to 64. This is the string length of the related key identifier.  
new_reference_PIN_key_identifier  
The new_reference_PIN_key_identifier parameter points to a string variable  
containing an internal key-token or a key label of an internal key-token record  
in key storage. The internal key-token contains the key used to decrypt the  
new_reference_PIN_block. The control vector for this key must specify either  
an IPINENC or an OPINENC key type.  
new_reference_PIN_block  
The new_reference_PIN_block parameter points to an 8-byte string variable  
containing an encrypted PIN block which in turn contains the  
new_reference_PIN.  
new_reference_PIN_profile  
The new_reference_PIN_profile parameter points to an array of three, 8-byte  
string variables which define the new_reference_PIN_block format. For more  
information about a PIN profile, see “PIN Profile” on page 8-10.  
new_reference_PIN_PAN_data  
The new_reference_PIN_PAN_data parameter points to a 12-byte string  
variable containing the PAN data. PAN data is used to recover a PIN from an  
ISO-0 PIN block. If the PIN block is not in ISO-0 format, this value will be  
ignored, but a 12-byte variable must be specified.  
current_reference_PIN_key_identifier_length  
The current_reference_PIN_key_identifier_length parameter points to an integer  
variable set to 0 or 64 providing the length in bytes of the  
current_reference_PIN_key_identifier variable. If the VISAPCU2 keyword is  
used a key must be specified and this variable must be 64, else 0.  
current_reference_PIN_key_identifier  
The current_reference_PIN_key_identifier parameter points to a string variable.  
The contents of this variable are inspected when the VISAPCU2 rule-array  
keyword is present. The variable should contain an internal key-token or a key  
label of an internal key-token record in key storage. The internal key-token  
contains the key used to decrypt the current_reference_PIN_block. The control  
vector for this key must specify either an IPINENC or an OPINENC key type.  
current_reference_PIN_block  
The current_reference_PIN_block parameter points to an 8-byte string variable.  
The contents of this variable are inspected when the VISAPCU2 rule-array  
keyword is present. The variable should contain an encrypted PIN block which  
in turn contains the current_reference_PIN.  
8-56 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PIN_Change/Unblock  
current_reference_PIN_profile  
The current_reference_PIN_profile parameter points to an array of three, 8-byte  
string variables. The contents of the variables are inspected when the  
VISAPCU2 rule-array keyword is present. The variables define which PIN  
block format is processed. For more information about a PIN profile, see “PIN  
Profile” on page 8-10.  
current_reference_PIN_PAN_data  
The current_reference_PIN_PAN_data parameter points to a 12-byte string  
variable. The variable should contain the PAN data. PAN data is used to  
recover a PIN from an ISO-0 PIN block. The contents of this variable are  
inspected when the VISAPCU2 rule-array keyword is present and the  
PIN-profile specifies an ISO-0 PIN block format.  
output_PIN_data_length  
The output_PIN_data_length parameter points to an integer, which for this  
implementation must be set to zero.  
output_PIN_data  
The output_PIN_data parameter points to a string variable which for this  
implementation can be a null pointer.  
output_PIN_profile  
The output_PIN_profile parameter points to an array of three, 8-byte string  
variables. The variables define which PIN block format is processed. The  
variables should be set to these values:  
1. As per the rule array selection, the string ‘VISAPCU1’ or ‘VISAPCU2’.  
2. Format control set to ‘NONE’ (followed by four space characters).  
3. Eight space characters.  
For more information about a PIN profile, see “PIN Profile” on page 8-10.  
output_PIN_message_length  
The output_PIN_message_length parameter points to an integer containing the  
length in bytes of the output_PIN_message variable. Set this variable to at  
least a value of 16 on input. On a successful response, the verb returns a  
value of 16 which is the length of the output_PIN_message.  
output_PIN_message  
The output_PIN_message parameter points to a 16-byte string variable to  
receive the output encrypted, padded PIN-block.  
Required Commands  
The PIN_Change/Unblock verb requires one or both of the following commands to  
be enabled in the cryptographic engine based on the permissible key-type,  
IPINENC or OPINENC, used in the decryption of the input PIN blocks.  
Chapter 8. Financial Services Support Verbs 8-57  
PIN_Change/Unblock  
CCA Release 2.54  
PIN-block  
encrypting  
key-type  
Command Command  
Offset  
Comment  
OPINENC  
X'00BC'  
Generate PIN Change  
Required if either the  
using OPINENC  
new_reference_PIN_key or the  
current_reference_PIN_key are  
permitted to be an OPINENC key  
type.  
IPINENC  
X'00BD'  
Generate PIN Change  
using IPINENC  
Required if either the  
new_reference_PIN_key or the  
current_reference_PIN_key are  
permitted to be an IPINENC key type.  
When an MAC-MDK and/or ENC-MDK of key type DKYGENKY is specified with  
control vector bits (19-22) of B'1111', the Generate Diversified Key (DALL with  
DKYGENKY key type) command (offset X'0290') must also be enabled in the  
active role.  
8-58 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Secure_Messaging_for_Keys  
Secure_Messaging_for_Keys (CSNBSKY)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-23  
X
Use the Secure_Messaging_for_Keys verb to decrypt a key you supply for  
incorporation into a text block you also supply. The text block is then encrypted  
within the verb to preserve the security of the key value. The encrypted text block,  
normally the “value” field in a TLV2 item, can be incorporated into a message sent  
to an EMV smart card.  
The processing is consistent with the specifications provided in these documents:  
EMV 2000 Integrated Circuit Card Specification for Payment Systems Version  
4.0 (EMV4.0) Book 2  
Design VISA Integrated Circuit Card Specification Manual.  
You specify:  
Whether the text block shall be CBC or ECB encrypted.  
The input_key to be included within the encrypted text block. The input_key  
can be an internal key (encrypted under the master key), or an external key, in  
which case you also provide the IMPORTER or EXPORTER key required to  
decipher the input_key. You also specify the length of this key using the  
key_field_length variable.  
The key to encipher the “secure message” text block, the secmsg_key.  
The clear_text to be encrypted along with its length and the offset within the  
block for placement of the decrypted input_key. The text you supply must be a  
multiple of eight bytes.  
You also supply the encryption initialization_vector and the variable for  
receiving the initialization vector for encrypting additional message text. The  
verb design presumes that the supplied text is a portion of a larger message  
you are preparing for an EMV smart card. The encrypted text must be on an  
8-byte boundary within the complete message. The initialization_vector would  
normally be the encrypted eight bytes just prior to the text prepared within this  
verb.  
The variable to receive the enciphered_text.  
The Secure_Messaging_for_Keys verb:  
Recovers the input key.  
Places the deciphered input-key value within the supplied text at the specified  
offset.  
Encrypts the supplied text. In CBC mode, uses the supplied  
initialization_vector and also returns the value to be supplied as the initialization  
vector when enciphering subsequent data for the EMV card message (the  
output_chaining_vector).  
2
TLV (Tag, Length, Value) is defined in ISO 7816-4  
Chapter 8. Financial Services Support Verbs 8-59  
Secure_Messaging_for_Keys  
CCA Release 2.54  
Returns the enciphered text.  
Restrictions  
Format  
This verb is supported beginning with Release 2.50.  
CSNBSKY  
return_code  
reason_code  
exit_data_length  
exit_data  
Output  
Output  
In/Output Integer  
In/Output String  
Integer  
Integer  
exit_data_length bytes  
rule_array_count  
rule_array  
Input  
Input  
Integer  
String  
array  
zero or one  
rule_array_count * 8 bytes  
input_key_identifier  
key_encrypting_key_identifier  
secmsg_key_identifier  
clear_text_length  
clear_text  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
String  
String  
String  
Integer  
String  
String  
Integer  
64 bytes  
64 bytes  
64 bytes  
Multiple of 8, 4096  
clear_text_length bytes  
8 bytes  
(0 is at the start of the  
clear_text)  
initialization_vector  
key_offset  
key_field_length  
enciphered_text  
output_chaining_vector  
Input  
Output  
Output  
Integer  
String  
String  
key length, e.g. 8 or 16  
clear_text_length bytes  
8 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter points to an integer variable containing the  
number of elements in the rule_array variable. The value must be zero or one.  
rule_array  
The rule_array parameter points to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
Keyword  
Meaning  
Enciphering mode (one, optional)  
TDES-CBC  
TDES-ECB  
Use CBC mode to encipher the clear_text. This is the default.  
Use ECB mode to encipher the clear_text.  
input_key_identifier  
The input_key_identifier parameter is a pointer to a string variable containing  
the encrypted-key key-token or the label of a key record in key storage. You  
may identify any type of key, provided the control-vector export-allowed  
permission bit is on (bit 17). You also may specify an external DATA key with  
an all-zero control vector.  
key_encrypting_key_identifier  
The key_encrypting_key_identifier parameter is a pointer to a string variable  
containing the IMPORTER or EXPORTER key to decipher an external  
8-60 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Secure_Messaging_for_Keys  
input_key. You may also specify a key label of a key storage record for such a  
key. For an internal-form input_key, you may specify a null key-token.  
secmsg_key_identifier  
The secmsg_key_identifier parameter is a pointer to a string variable containing  
an internal key-token or the key label of an internal key-token in key storage.  
The control vector must specify a SECMSG type key with the SMKEY  
control-vector bit (bit 18) on.  
clear_text_length  
The clear_text_length parameter is a pointer to an integer containing the length  
of text in bytes to be encrypted. This must be a multiple of eight and less than  
or equal to 4096.  
clear_text  
The clear_text parameter is a pointer to the text string to be updated and  
encrypted.  
initialization_vector  
The initialization_vector parameter is a pointer to an eight-byte string containing  
the CBC-encryption initialization vector (the data to be exclusive-ORed with the  
first eight bytes of the message). This can be a null pointer when ECB mode is  
specified.  
key_offset  
The key_offset parameter is a pointer to an integer containing the offset of the  
location for the decrypted input-key. The start of the text is an offset of zero.  
The offset plus the key-offset-field-length must be less than or equal to the  
clear-text-length.  
key_field_length  
The key_field_length parameter is a pointer to an integer containing the length  
of key information to be inserted into the text message. Use a length of 8 for a  
single-length key and a length of 16 for a double-length key.  
enciphered_text  
The enciphered_text parameter is a pointer to a string variable to receive the  
enciphered text message.  
output_chaining_vector  
The output_chaining_vector parameter is a pointer to an eight-byte string to  
receive the CBC chaining value. This is the same as the last eight bytes of  
returned text and would be used as an initialization_vector when encrypting  
subsequent data for a message. This can be a null pointer when ECB mode is  
specified.  
Required Commands  
The Secure_Messaging_for_Keys verb requires the Secure Messaging for Keys  
command (offset X'0273') to be enabled in the hardware.  
Chapter 8. Financial Services Support Verbs 8-61  
Secure_Messaging_for_PINs  
CCA Release 2.54  
Secure_Messaging_for_PINs (CSNBSPN)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-23  
X
Use the Secure_Messaging_for_PINs verb to decrypt an input PIN-block, optionally  
reformat the PIN-block, and incorporate the PIN-block into a text block you also  
supply. The text block is then encrypted within the verb to preserve the security of  
the PIN value. The encrypted text block, normally the “value” field in a TLV3 item,  
can be incorporated into a message sent to an EMV smart card.  
The processing is consistent with the specifications provided in these documents:  
EMV 2000 Integrated Circuit Card Specification for Payment Systems Version  
4.0 (EMV4.0) Book 2  
Design VISA Integrated Circuit Card Specification Manual.  
You specify:  
Whether the text block shall be CBC or ECB encrypted  
Whether the PIN block shall be self-encrypted  
The encrypted input_PIN_block  
The key to decrypt the input_PIN_block  
The PIN profile for the input_PIN_block  
When the PIN profile specifies an ISO-0 PIN-block format, the PAN data to  
recover the PIN  
The key to encipher the “secure message” text block, the secmsg_key  
The PIN profile for the PIN-block included within the output message  
When the PIN profile specifies an ISO-0 PIN-block format, the PAN data to  
obscure the PIN  
The clear_text to be encrypted along with its length and the offset within the  
text for placement of the PIN block. The text you supply must be a multiple of  
eight bytes.  
You also supply the encryption initialization_vector and the variable for  
receiving the initialization vector for encrypting additional message text. The  
verb design presumes that the supplied text is a portion of a larger message  
you are preparing for an EMV smart card. The encrypted text must be on an  
8-byte boundary within the complete message. The initialization_vector would  
normally be the encrypted eight bytes just prior to the text prepared within this  
verb.  
The variable to receive the enciphered_text  
The variable to receive a copy of the last eight bytes of enciphered text. This  
can be used as an initialization vector for enciphering subsequent message  
text.  
3
TLV (Tag, Length, Value) is defined in ISO 7816-4  
8-62 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Secure_Messaging_for_PINs  
The Secure_Messaging_for_PINs verb:  
Deciphers the input PIN block  
Reformats the PIN block when the input and output PIN-block formats differ  
Self-encrypts the output PIN block as specified  
Places the PIN block within the supplied text at the specified offset  
Encrypts the updated text. In CBC mode, uses the supplied initialization_vector  
and also returns the value to be supplied as the initialization vector when  
enciphering subsequent data for the EMV card message (the  
output_chaining_vector).  
Returns the enciphered text.  
Restrictions  
Format  
This verb is supported beginning with Release 2.50.  
CSNBSPN  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
zero, one, or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
input_PIN_block  
PIN_encrypting_key_identifier  
input_PIN_profile  
input_PAN_data  
secmsg_key_identifier  
output_PIN_profile  
output_PAN_data  
clear_text_length  
clear_text  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
Input  
String  
String  
String  
String  
String  
String  
String  
Integer  
String  
String  
Integer  
8 bytes  
64 bytes  
3 * 8 bytes  
12 bytes  
64 bytes  
3 * 8 bytes  
12 bytes  
multiple of 8, 4096  
clear_text_length bytes  
8 bytes  
(zero is at the start of the  
clear_text)  
initialization_vector  
PIN_offset  
PIN_offset_field_length  
enciphered_text  
output_chaining_vector  
Input  
Output  
Output  
Integer  
String  
String  
8 bytes  
clear_text_length bytes  
8 bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter points to an integer variable containing the  
number of elements in the rule_array variable. The value must be zero, one, or  
two.  
rule_array  
The rule_array parameter points to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters.  
Chapter 8. Financial Services Support Verbs 8-63  
Secure_Messaging_for_PINs  
CCA Release 2.54  
Keyword  
Meaning  
Enciphering mode (one, optional)  
TDES-CBC  
TDES-ECB  
Use CBC mode to encipher the clear_text. This is the default.  
Use ECB mode to encipher the clear_text.  
PIN encryption (one, optional)  
CLEARPIN  
Do not encrypt the PIN block prior to encrypting the complete  
text message. This is the default.  
SELFENC  
Append the PIN-block self-encrypted to the clear PIN block  
within the unencrypted output message. See “PIN-Block  
Self-encryption” on page E-19.  
input_PIN_block  
The input_PIN_block parameter is a pointer to an eight-byte string variable  
containing the input, encrypted PIN-block.  
PIN_encrypting_key_identifier  
The PIN_encrypting_key_identifier parameter is a pointer to a string variable  
containing an internal key-token or the key label of an internal key-token in key  
storage. The key is used to decipher the input PIN block and must be an  
IPINENC key-type.  
input_PIN_profile  
The input_PIN_profile parameter is a pointer to a string variable containing  
three 8-byte character strings with information defining the input PIN-block  
format. See “PIN Profile” on page 8-10. The verb supports PIN block formats  
ISO-0, ISO-1, and ISO-2.  
input_PAN_data  
The input_PAN_data parameter is a pointer to a string variable containing the  
personal account number (PAN) data. The verb uses the PAN data when it  
must output the PIN in a different PIN-block format and the input format is  
ISO-0. (You supply the 12 rightmost PAN digits, excluding the check digit.)  
secmsg_key_identifier  
The secmsg_key_identifier parameter is a pointer to a string variable containing  
an internal key-token, or the key label of an internal key-token in key storage.  
The control vector must specify a SECMSG type key with the SMPIN  
control-vector bit (bit 19) on.  
output_PIN_profile  
The output_PIN_profile parameter is a pointer to a string variable containing  
three 8-byte character strings with information defining the output PIN-block  
format. See “PIN Profile” on page 8-10. The verb supports PIN block formats  
ISO-0, ISO-1, and ISO-2.  
output_PAN_data  
The output_PAN_data parameter is a pointer to a string variable containing the  
personal account number (PAN) data. The verb uses the PAN data when it  
must output the PIN in a different PIN-block format and the output format is  
ISO-0. (You supply the 12 rightmost PAN digits, excluding the check digit.)  
8-64 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Secure_Messaging_for_PINs  
clear_text_length  
The clear_text_length parameter is a pointer to an integer containing the length  
of text to be encrypted. This must be a multiple of eight, and less than or  
equal to 4096.  
clear_text  
The clear_text parameter is a pointer to the text string to be updated with a PIN  
block and encrypted.  
initialization_vector  
The initialization_vector parameter is a pointer to an eight-byte string containing  
the CBC-encryption initialization vector (the data to be exclusive-ORed with the  
first eight bytes of the text). This can be a null pointer when ECB mode is  
specified.  
PIN_offset  
The PIN_offset parameter is a pointer to an integer containing the offset to the  
location for the PIN block. Specify the start of the text as offset zero. The  
offset plus PIN_offset_field_length must be less than or equal to the  
clear_text_length.  
PIN_offset_field_length  
The PIN_offset_field_length parameter is a pointer to an integer valued to eight.  
enciphered_text  
The enciphered_text parameter is a pointer to a string variable to receive the  
enciphered text message.  
output_chaining_vector  
The output_chaining_vector parameter is a pointer to an eight-byte string to  
receive the CBC chaining value. This is the same as the last eight bytes of  
returned enciphered text and can be used as an initialization_vector when  
encrypting subsequent data for a message. This can be a null pointer when  
ECB mode is specified.  
Required Commands  
The Secure_Messaging_for_PINs verb requires the Secure Messaging for PINs  
command (offset X'0274') to be enabled in the hardware.  
Chapter 8. Financial Services Support Verbs 8-65  
SET_Block_Compose  
CCA Release 2.54  
SET_Block_Compose (CSNDSBC)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The SET_Block_Compose verb creates a SET-protocol RSA-OAEP block and DES  
encrypts the data block in support of the SET protocols. Optionally the verb will  
compute the SHA-1 hash of the supplied data block and include this in the OAEP  
block.  
DES_encrypted_block can be as many as eight bytes longer than the  
data_to_encrypt due to padding. Ensure the DES_encrypted_block buffer is large  
enough.  
Restrictions  
The data-block length variable is restricted to 32 megabytes.  
The DES_key_block_length parameter must point to an integer valued to zero. The  
DES_key_block parameter should be a null address pointer, or point to an unused  
64-byte application variable.  
The chaining_vector parameter must be a null address pointer, or point to an  
unused 18-byte application variable. This parameter is included to support a  
possible future extension to enable segmented data encryption.  
Format  
CSNDSBC  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one  
rule_array_count * 8 bytes  
Integer  
String  
array  
block_contents_identifier  
XData_string_length  
XData_string  
Input  
Input  
Input  
String  
Integer  
String  
1 byte  
XData_string_length bytes  
data_to_encrypt_length  
data_to_encrypt  
In/Output Integer  
Input  
String  
data_to_encrypt_length  
bytes  
data_to_hash_length  
data_to_hash  
initialization_vector  
RSA_public_key_identifier_length  
RSA_public_key_identifier  
Input  
Input  
Input  
Input  
Input  
Integer  
String  
String  
Integer  
String  
data_to_hash_length bytes  
8 bytes  
RSA_public_key_identifier_length  
bytes  
DES_key_block_length  
DES_key_block  
RSA-OAEP_block_length  
RSA-OAEP_block  
In/Output Integer  
In/Output String  
In/Output Integer  
In/Output String  
DES_key_block_length bytes  
RSA-OAEP_block_length  
bytes  
chaining_vector  
In/Output String  
18 bytes  
DES_encrypted_block  
Output  
String  
updated  
data_to_encrypt_length  
bytes  
8-66 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
SET_Block_Compose  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one for  
this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Block type (required)  
SET1.00  
Specifies that the structure of the RSA-OAEP encrypted block  
is defined by the SET protocol.  
block_contents_identifier  
The block_contents_identifier parameter is a pointer to a string variable  
containing a binary value that will be copied into the Block Contents (BC) field  
of the SET DB data block. The BC field indicates what data is carried in the  
Actual Data Block (ADB) and the format of any extra data (XData_string).  
XData_string_length  
The XData_string_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the XData_string variable. The  
maximum length is 94 bytes.  
XData_string  
The XData_string parameter is a pointer to a string containing extra-encrypted  
data within the OAEP-processed and RSA-encrypted block. If the  
Xdata_string_length variable is zero, this parameter is ignored but must still be  
declared.  
data_to_encrypt_length  
The data_to_encrypt_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the data_to_encrypt variable. The  
maximum length is the same limit as on the Encipher service. On output, and if  
the field is of sufficient length, the variable is updated with the actual length of  
the DES-encrypted data block.  
data_to_encrypt  
The data_to_encrypt parameter is a pointer to a string variable containing the  
data to be DES-encrypted with a single-use 64-bit DES key (generated by this  
service). The data will first be padded by this service according to the PKCS  
#5 padding rule before encryption.  
data_to_hash_length  
The data_to_hash_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the data_to_hash variable.  
Chapter 8. Financial Services Support Verbs 8-67  
SET_Block_Compose  
CCA Release 2.54  
The hash is an optional part of the OAEP block. No hash is computed or  
inserted into the OAEP block if the data_to_hash_length variable is zero.  
data_to_hash  
The data_to_hash parameter is a pointer to a string variable containing the  
data that is to be hashed and included in the OAEP block.  
If the data_to_hash_length variable is not zero, a SHA-1 hash of the  
data_to_hash variable will be included in the OAEP block.  
initialization_vector  
The initialization_vector parameter is a pointer to a string variable containing  
the initialization vector the verb uses with the input data.  
RSA_public_key_identifier_length  
The RSA_public_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
RSA_public_key_identifier variable. The maximum size allowed is 2500 bytes.  
of the variable that contains the key token or the key label of the PKA96 RSA  
public-key used to encipher the OAEP block.  
RSA_public_key_identifier  
The RSA_public_key_identifier parameter is a pointer to a string variable  
containing the PKA96 RSA key-token or a key label of the PKA96 RSA  
key-token with the RSA public-key used to perform the RSA encryption of the  
OAEP block.  
DES_key_block_length  
The DES_key_block_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the DES_key_block variable. The  
value must be zero for this verb.  
DES_key_block  
The DES_key_block parameter is a pointer to a string variable containing DES  
key-block. This parameter must be a null pointer, or a pointer to 64 bytes of  
unused application storage.  
RSA-OAEP_block_length  
The RSA-OAEP_block_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the RSA-OAEP_block variable. The  
value must be at least 128 bytes. On output, and if the field is of sufficient  
length, the variable is updated with the actual length of the RSA-OAEP_block  
variable.  
RSA-OAEP_block  
The RSA-OAEP_block parameter is a pointer to a string variable containing the  
RSA-OAEP block.  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing a  
work area that the security server uses to carry segmented data between calls.  
The parameter must contain a null pointer or a pointer to 18 bytes of unused  
application storage.  
DES_encrypted_block  
The DES_encrypted_block parameter is a pointer to a string variable containing  
the DES-encrypted data block returned by the verb (cleartext was identified  
8-68 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
SET_Block_Compose  
with the data_to_encrypt variable). The starting address must not fall inside the  
data_to_encrypt area.  
Required Commands  
The SET_Block_Compose verb requires the SET Block Compose command  
(command offset X'010B') to be enabled in the hardware.  
Chapter 8. Financial Services Support Verbs 8-69  
SET_Block_Decompose  
CCA Release 2.54  
SET_Block_Decompose (CSNDSBD)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2/23  
X
X
X
X
The SET_Block_Decompose verb decomposes the RSA-OAEP block and DES  
decrypts the data block in support of the SET protocols.  
Restrictions  
The maximum data block that can be supplied for DES decryption is the limit as  
expressed in the Decipher service (see page 6-5).  
The DES_key_block_length parameter must point to an integer which has a value  
of zero, 64, or 128. The DES_key_block parameter must point to a buffer of the  
size designated by DES_key_block_length. When the length is zero, it is also  
acceptable for the DES key block pointer to be NULL.  
The chaining_vector parameter must be a null address pointer, or point to an  
unused 18-byte application variable. This parameter is included to support a  
possible future extension to enable segmented data-encryption.  
|
|
Beginning with Release 2.53, a private key with the CLONE attribute is rejected by  
this verb with return code 8, reason code 64 (decimal).  
Note: The API for this verb has been modified from that originally published in  
August, 1997.  
8-70 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
SET_Block_Decompose  
Format  
CSNDSBD  
return_code  
reason_code  
exit_data_length  
exit_data  
rule_array_count  
rule_array  
Output  
Output  
In/Output Integer  
In/Output String  
Input  
Input  
Integer  
Integer  
exit_data_length bytes  
one or two  
rule_array_count * 8 bytes  
Integer  
String  
array  
RSA-OAEP_block_length  
RSA-OAEP_block  
Input  
Input  
Integer  
String  
RSA-OAEP_block_length  
bytes  
DES_encrypted_data_block_length  
DES_encrypted_data_block  
In/Output Integer  
Input  
String  
DES_encrypted_data_block_length  
bytes  
initialization_vector  
RSA_private_key_identifier_length  
RSA_private_key_identifier  
Input  
Input  
Input  
String  
Integer  
String  
8 bytes  
RSA_private_key_identifier_length  
bytes  
DES_key_block_length  
DES_key_block  
block_contents_identifier  
XData_string_length  
XData_string  
In/Output Integer  
In/Output String  
DES_key_block_length bytes  
1 byte  
Output  
In/Output Integer  
Output String  
In/Output String  
Output String  
String  
XData_string_length bytes  
18 bytes  
DES_encrypted_data_block_length  
bytes  
chaining__vector  
data_block  
hash_block_length  
hash_block  
In/Output Integer  
Output String  
hash_block_length bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter is a pointer to an integer variable containing  
the number of elements in the rule_array variable. The value must be one or  
two for this verb.  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, and must be left-justified  
and padded on the right with space characters. The rule_array keywords are  
shown below:  
Keyword  
Meaning  
Block type (required)  
SET1.00  
Specifies that the structure of the RSA-OAEP encrypted block  
is defined by the S.E.T. 1.00 protocol.  
PIN-block encryption (optional)  
PINBLOCK Specifies that the OAEP block will contain PIN information in  
the XDATA field, including an ISO-0 format PIN-block. The  
PIN block is encrypted, using an IPINENC or OPINENC key  
that is contained in the DES_key_block variable. The PIN  
information and the encrypted PIN-block are returned in the  
XData_string variable.  
Chapter 8. Financial Services Support Verbs 8-71  
SET_Block_Decompose  
CCA Release 2.54  
RSA-OAEP_block_length  
The RSA-OAEP_block_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the RSA-OAEP_block variable. This  
value must be 128 bytes.  
RSA-OAEP_block  
The RSA-OAEP_block parameter is a pointer to a string variable containing the  
RSA-OAEP block.  
DES_encrypted_data_block_length  
The DES_encrypted_data_block_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
DES_encrypted_data_block variable. On output, the variable is updated with  
the actual length of the decrypted data with padding removed.  
DES_encrypted_data_block  
The DES_encrypted_data_block parameter is a pointer to a string variable  
containing the DES-encrypted data block.  
initialization_vector  
The initialization_vector parameter is a pointer to a string variable containing  
the initialization vector the verb uses with the input data.  
RSA_private_key_identifier_length  
The RSA_private_key_identifier_length parameter is a pointer to an integer  
variable containing the number of bytes of data in the  
RSA_private_key_identifier variable. The maximum size allowed is 2500 bytes.  
RSA_private_key_identifier  
The RSA_private_key_identifier parameter is a pointer to a string variable  
containing the PKA96 RSA key-token or the key label of the PKA96 RSA  
key-token with the RSA private-key used to perform the RSA decryption of the  
OAEP block.  
DES_key_block_length  
The DES_key_block_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the DES_key_block variable. The  
value can be 0, 64, or 128. These three values are used in the following way:  
0
This is the normal value when the PINBLOCK keyword is not present.  
In this case, no DES key data is passed as input or output.  
64  
This value is permitted for the case when the PINBLOCK keyword is  
not present, in order to improve compatibility with the  
SET_Block_Decompose verb defined for the S/390 ICSF  
implementation of CCA. The Coprocessor treats this in the same way  
as a value of zero.  
128  
This is the length when the PINBLOCK keyword is present.  
DES_key_block  
The DES_key_block parameter is a pointer to a string variable containing the  
PIN encrypting key used when the PINBLOCK keyword is present. For  
compatibility with the S/390 ICSF implementation of this verb, the parameter is  
also allowed to point to an unused 64-byte variable in application storage when  
the PINBLOCK keyword is not present.  
The PIN encrypting-key token must be an internal token, and must be of type  
IPINENC or OPINENC. The key token must be in the last (rightmost) 64 bytes  
8-72 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
SET_Block_Decompose  
of a 128-byte buffer. The first 64 bytes of the buffer are reserved for future  
use, and should be set to X'00'.  
The PIN encrypting-key token will be returned to the caller in the same buffer  
on completion of the verb.  
block_contents_identifier  
The block_contents_identifier parameter is a pointer to a string variable  
containing the Block Contents (BC) field of the SET DB data block. The BC  
field indicates what data is carried in the Actual Data Block (ADB), and the  
format of any extra data (XData string).  
XData_string_length  
The XData_string_length parameter is a pointer to an integer variable  
containing the number of bytes of data in the XData_string variable. The  
minimum value is 94 bytes. On output, and if the field is of sufficient length,  
the variable is updated with the actual length of the XData_string variable  
returned by the verb.  
XData_string  
The XData_string parameter is a pointer to the string variable containing the  
extra-encrypted data within the OAEP-processed and RSA-decrypted block.  
When the XData field contains PIN information, eight bytes of that information  
are an ISO-0 format PIN-block in cleartext. This PIN block is enciphered using  
the PIN encryption-key received in the DES_key_block variable. The  
enciphered PIN-block replaces the cleartext PIN-block in the XData_string  
variable returned by the verb.  
chaining_vector  
The chaining_vector parameter is a pointer to a string variable containing a  
work area the security server uses to carry segmented data between calls. The  
parameter must contain a null pointer or a pointer to a 18 bytes of unused  
application storage.  
data_block  
The data_block parameter is a pointer to a string variable containing the  
decrypted DES-encrypted data block. The starting address must not fall inside  
the DES-encrypted data block area. Padding characters are removed.  
hash_block_length  
The hash_block_length parameter is a pointer to an integer variable containing  
the number of bytes of data in the hash_block variable. An error will be  
returned if the hash_block variable is not large enough to hold the 20-byte  
SHA-1 hash.  
On output, this field is updated to reflect the number of bytes of hash data  
returned in the hash_block variable, either 0 or 20 bytes.  
hash_block  
The hash_block parameter is a pointer to a string variable containing the  
SHA-1 hash extracted from the OAEP block returned by the verb.  
Chapter 8. Financial Services Support Verbs 8-73  
SET_Block_Decompose  
CCA Release 2.54  
Required Commands  
The SET_Block_Decompose verb requires the SET Block Decompose command  
(command offset X'010C') to be enabled in the hardware.  
Two additional commands are used when encrypting PIN data with this verb.  
When using an IPINENC type key, the verb requires the  
SET_PIN_encrypt_IPINENC command (command offset X'0121') to be  
enabled in the hardware.  
When using an OPINENC type key, the verb requires the  
SET_PIN_encrypt_OPINENC command (command offset X'0122') to be  
enabled in the hardware.  
8-74 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Transaction_Validation  
Transaction_Validation (CSNBTRV)  
Platform/  
Product  
OS/2  
AIX  
Win NT/  
2000  
OS/400  
IBM 4758-2  
X
X
X
X
The Transaction_Validation verb supports the generation and validation of  
American Express card security codes (CSC).  
The Transaction_Validation verb generates and verifies transaction values based  
on information from the transaction and a cryptographic key. You select the  
validation method, and either the generate or verify mode, through rule-array  
keywords.  
For the American Express process, the control vector supplied with the  
cryptographic key must indicate a MAC or MACVER class. The control vector bits  
zero to three can be B'0000'. Alternatively, you can ensure that a key is used  
only for the American Express CSC process by specifying a MAC or a  
MACVER-class key with control vector bits zero to three valued to B'0100'. The  
control vector generate bit must be on (bit 20) if you request CSC generation and  
the verify bit (bit 21) must be on if you request verification. See Figure C-3 on  
page C-5 for information about the control vectors.  
The verb returns the validation within the return code. A return code of zero  
indicates the transaction has been validated, and return code four indicates the  
transaction has not been validated.  
Restrictions  
Format  
The transaction_info and validation_values variables cannot exceed 256 bytes in  
length. CSC codes must be 19 bytes in length.  
CSNBTRV  
return_code  
reason_code  
Output  
Output  
Integer  
Integer  
exit_data_length  
exit_data  
In/Output Integer  
In/Output String  
rule_array_count  
rule_array  
transaction_key_identifier_length  
transaction_key_identifier  
transaction_info_length  
transaction_info  
Input  
Input  
Input  
Input  
Input  
Input  
Integer  
String  
Integer  
String  
Integer  
String  
one or two  
rule_array_count * 8 bytes  
64  
64 bytes  
transaction_info_length bytes  
validation_values_length  
validation_values  
In/Output Integer  
In/Output String  
validation_values_length  
bytes  
Parameters  
For the definitions of the return_code, reason_code, exit_data_length, and exit_data  
parameters, see “Parameters Common to All Verbs” on page 1-11.  
rule_array_count  
The rule_array_count parameter points to an integer for the number of the  
rule-array elements. The value must be one or two for this verb.  
Chapter 8. Financial Services Support Verbs 8-75  
Transaction_Validation  
CCA Release 2.54  
rule_array  
The rule_array parameter is a pointer to a string variable containing an array of  
keywords. The keywords are eight bytes in length, left-justified, and padded on  
the right with space characters, as shown below.  
Keyword  
Meaning  
Operation (one, optional)  
VERIFY  
Specifies verification of the value presented in the validation  
values variable. (This is the default when the CSC-3, CSC-4,  
or CSC-5 keywords are used.)  
GENERATE  
Specifies generation of transaction validation values. (This is  
the default when the CSC-345 keyword is used.)  
American Express card security codes (one required with VERIFY)  
CSC-3  
3-digit card security code (CSC) located on the signature  
panel (the default), VERIFY implied  
CSC-4  
CSC-5  
4-digit CSC located on the front of the card, VERIFY implied  
5-digit CSC located on the magnetic stripe, VERIFY implied  
American Express card security codes (required with GENERATE)  
CSC-345  
Generates 3-byte, 4-byte, 5-byte values when given an  
account number and an expiration date, GENERATE implied.  
transaction_key_identifier_length  
The transaction_key_identifier_length parameter is a pointer to an integer  
variable containing 64, the length of the key token or key label variable.  
transaction_key_identifier  
The transaction_key_identifier parameter is a pointer to a string variable  
containing a key token or a key label of a key token in key storage.  
transaction_info_length  
The transaction_info_length parameter is a pointer to an integer variable  
containing the length of the transaction_info variable. For American Express  
CSC codes, this length must be 19.  
transaction_info  
The transaction_info parameter is a pointer to a string variable containing the  
concatenation of the 4-byte expiration date (in the format of YYMM) and the  
15-byte American Express account number. Provide the information in  
character format.  
validation_values_length  
The validation_values_length parameter is a pointer to an integer variable  
containing the length of the validation_values variable.  
validation_values  
The validation_values parameter is a pointer to a string variable containing  
American Express CSC values. The data is output for GENERATE and input  
for VERIFY.  
8-76 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Transaction_Validation  
Operation  
Element Description  
Validation-Values  
Length  
GENERATE and  
555554444333  
12  
CSC-345  
where:  
55555 = CSC 5 value  
4444 = CSC 4 value  
333 = CSC 3 value  
VERIFY and CSC-3  
VERIFY and CSC-4  
VERIFY and CSC-5  
333 = CSC 3 value  
4444 = CSC 4 value  
55555 = CSC 5 value  
3
4
5
Required Commands  
The Transaction_Validation verb requires the listed commands to be enabled in the  
access-control system:  
GENERATE and CSC-345  
VERIFY and CSC-3  
VERIFY and CSC-4  
VERIFY and CSC-5  
Generate CSC-5, 4, 3 values command  
(command offset X'0291')  
Verify CSC-3 values command  
(command offset X'0292')  
Verify CSC-4 values command  
(command offset X'0293')  
Verify CSC-5 values command  
(command offset X'0294')  
Chapter 8. Financial Services Support Verbs 8-77  
CCA Release 2.54  
8-78 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix A. Return Codes and Reason Codes  
This appendix describes the return codes and the reason codes that a verb uses to  
report the results of processing.  
Each return code is associated with a reason code that supplies details about the  
result of verb processing. A successful result can include return code 0 and reason  
code 0 or another combination of a return code and a reason code. Generally, you  
should be able to base your application program design on the return codes; the  
reason codes amplify the meaning supplied by the return codes.  
A verb supplies a return code and a reason code in the return_code parameter and  
in the reason_code parameter.  
Return Codes  
A return code provides a summary of the results of verb processing. A return code  
can have the values shown in Figure A-1.  
Figure A-1. Return Code Values  
Hex  
Value  
Decimal  
Value  
Meaning  
00  
04  
00  
This return code indicates a normal completion of verb processing. To provide additional  
information, a few nonzero reason codes are associated with this return code.  
04  
This return code is a warning that indicates that the verb completed processing; however, an  
unusual event occurred. The event is most likely related to a problem created by the user, or  
it is a normal occurrence based on the data supplied to the verb.  
08  
08  
12  
This return code indicates that the verb stopped processing. Either an error occurred in the  
application program or a possible recoverable error occurred in the Coprocessor support  
code.  
0C  
This return code indicates that the verb stopped processing. Either a Coprocessor is not  
available or a processing error occurred in the Coprocessor support code. The reason is  
most likely related to a problem in the setup of the hardware or in the configuration of the  
software.  
10  
16  
This return code indicates that the verb stopped processing. A processing error occurred in  
the Coprocessor support code. If these errors persist, a repair of the Coprocessor hardware  
or a correction to the Coprocessor support code may be required.  
Reason Codes  
A reason code details the results of verb processing. Every reason code is  
associated with a single return code. A nonzero reason code can be associated  
with a zero return code.  
It is expected that User Defined Extensions (UDX) will return reason codes in the  
range of 20480 (X'5000') through 24575 (X'5FFF'). See the documentation for  
your UDXs, if any, for these reason code meanings.  
Copyright IBM Corp. 1997, 2005  
A-1  
CCA Release 2.54  
Figure A-2 on page A-2 shows the reason codes, listed in numeric sequence and  
grouped by their corresponding return code. The return codes appear in decimal  
form, and the reason codes appear in decimal and hexadecimal (hex) form.  
Return Code 0  
Figure A-2. Reason Codes for Return Code 0  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
0
0
0
0
000 (000)  
002 (002)  
008 (008)  
151 (097)  
The verb completed processing successfully.  
One or more bytes of a key do not have odd parity.  
No value is present to be processed.  
The key token supplies the MAC length or MACLEN4 is the  
default for key tokens that contain MAC or MACVER keys.  
A new master-key value was found to have duplicate thirds.  
A provided master-key part did not have odd parity.  
A key encrypted under the old master-key was used.  
0
0
0
701 (2BD)  
702 (2BE)  
10001  
(2711)  
A-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Return Code 4  
Figure A-3. Reason Codes for Return Code 4  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
4
4
001 (001)  
013 (00D)  
The verification test failed.  
The key token has an initialization vector, and the  
initialization_vector parameter value is nonzero. The verb  
uses the value in the key token.  
4
4
016 (010)  
017 (011)  
The rule array and the rule-array count are too small to  
contain the complete result.  
The requested ID is not present in any profile in the specified  
cryptographic hardware component.  
4
4
019 (013)  
158 (09E)  
The financial PIN in a PIN block is not verified.  
The Key_Token_Change, Key_Record_Delete, or  
Key_Record_Write verbs did not process any records.  
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.  
4
4
166 (0A6)  
179 (0B3)  
The control-vector keywords that are in the rule array are  
ignored.  
4
4
4
283 (11B)  
287 (11F)  
429 (1AD)  
The Cryptographic Coprocessor battery is low.  
The PIN-block format is not consistent.  
The digital signature is not verified. The verb completed its  
processing normally.  
4
1024 (400) Sufficient shares have been processed to create a new  
master-key.  
4
4
2039 (7F7) At least one control vector bit cannot be parsed.  
2042 (7FA) The supplied passphrase is invalid.  
Appendix A. Return Codes and Reason Codes A-3  
CCA Release 2.54  
Return Code 8  
Figure A-4 (Page 1 of 6). Reason Codes for Return Code 8  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
8
012 (00C)  
The token-validation value in an external key token is not  
valid.  
8
8
022 (016)  
023 (017)  
The ID number in the request field is not valid.  
An access to the data area was outside the data-area  
boundary.  
8
8
8
8
8
8
8
8
024 (018)  
025 (019)  
026 (01A)  
029 (01D)  
030 (01E)  
031 (01F)  
032 (020)  
033 (021)  
The master key verification pattern is not valid .  
The value that the text_length parameter specifies is not valid.  
The value of the PIN is not valid.  
The token-validation value in an internal key token is not valid.  
No record with a matching key label is in key storage.  
The control vector did not specify a DATA key.  
A key label format is not valid.  
A rule array or other parameter specifies a keyword that is not  
valid.  
8
8
8
8
8
034 (022)  
035 (023)  
036 (024)  
037 (025)  
039 (027)  
A rule-array keyword combination is not valid.  
A rule-array count is not valid.  
The action command must be specified in the rule array.  
The object type must be specified in the rule array.  
A control vector violation occurred. Check all control vectors  
employed with the verb. For security reasons, no detail is  
provided.  
8
8
040 (028)  
041 (029)  
The service code does not contain numerical character data.  
The keyword supplied with the key_form parameter is not  
valid.  
8
8
042 (02A)  
043 (02B)  
The expiration date is not valid.  
The keyword supplied with the key_length or the  
key_token_length parameter is not valid.  
A record with a matching key label already exists in key  
storage.  
8
044 (02C)  
8
8
8
045 (02D)  
046 (02E)  
047 (02F)  
The input character string cannot be found in the code table.  
The card-validation value (CVV) is not valid.  
A source key token is unusable because it contains data that  
is not valid or undefined.  
8
8
048 (030)  
049 (031)  
One or more keys has a master key verification pattern that is  
not valid.  
A key-token-version-number found in a key token is not  
supported.  
8
8
050 (032)  
051 (033)  
The key-serial-number specified in the rule array is not valid.  
The value that the text_length parameter specifies is not a  
multiple of eight bytes.  
8
054 (036)  
The value that the pad_character parameter specifies is not  
valid.  
8
8
8
8
055 (037)  
056 (038)  
058 (03A)  
059 (03B)  
The initialization vector in the key token is enciphered.  
The master key verification pattern in the OCV is not valid.  
The parity of the operating key is not valid.  
Control information (for example, the processing method or the  
pad character) in the key token conflicts with that in the rule  
array.  
8
8
8
060 (03C)  
061 (03D)  
062 (03E)  
A cryptographic request with the FIRST or MIDDLE keywords  
and a text length less than 8 bytes is not valid.  
The keyword supplied with the key_type parameter is not  
valid.  
The source key was not found.  
A-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure A-4 (Page 2 of 6). Reason Codes for Return Code 8  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
8
063 (03F)  
A key token had an invalid token header (for example, not an  
internal token).  
8
064 (040)  
The RSA key is not permitted to perform the requested  
operation. Likely causes are key distribution usage is not  
enabled for the key.  
8
8
8
8
8
065 (041)  
066 (042)  
067 (043)  
068 (044)  
072 (048)  
The key token failed consistency checking.  
The recovered encryption block failed validation checking.  
RSA encryption failed.  
RSA decryption failed.  
The value that the size parameter specifies is not valid (too  
small, too large, negative, or zero).  
8
081 (051)  
The modulus length (key size) exceeds the allowable  
maximum.  
8
8
085 (055)  
090 (05A)  
The date or the time value is not valid.  
Access control checking failed. See the Required Commands  
descriptions for the failing verb.  
8
091 (05B)  
The time sent in your logon request was more than five  
minutes different from the clock in the secure module.  
Your user profile has expired.  
Your user profile has not yet reached its activation date.  
Your authentication data (for example, passphrase) has  
expired.  
8
8
8
092 (05C)  
093 (05D)  
094 (05E)  
8
8
8
8
095 (05F)  
096 (060)  
100 (064)  
101 (065)  
Access to the data is not authorized.  
An error occurred reading or writing the secure clock.  
The PIN length is not valid.  
The PIN check length is not valid. It must be in the range  
from 4 to the PIN length inclusive.  
8
8
8
102 (066)  
103 (067)  
104 (068)  
The value of the decimalization table is not valid.  
The value of the validation data is not valid.  
The value of the customer-selected PIN is not valid, or the PIN  
length does not match the value supplied with the PIN_length  
parameter or defined by the PIN-block format specified in the  
PIN profile.  
8
8
8
8
8
8
8
8
8
8
105 (069)  
106 (06A)  
107 (06B)  
108 (06C)  
109 (06D)  
110 (06E)  
111 (06F)  
112 (070)  
114 (072)  
116 (074)  
The value of the transaction_security_parameter is not valid.  
The PIN-block format keyword is not valid.  
The format control keyword is not valid.  
The value or the placement of the padding data is not valid.  
The extraction method keyword is not valid.  
The value of the PAN data is not numeric character data.  
The sequence number is not valid.  
The PIN offset is not valid.  
The PVV value is not valid.  
The clear PIN value is not valid. For example, digits other  
than 0, ..., 9 were found.  
8
8
120 (078)  
121 (079)  
An origin or destination identifier is not valid.  
The value of the inbound_key or source_key parameter is not  
valid.  
8
8
122 (07A)  
125 (07D)  
The value of the inbound_KEK_count or outbound_count  
parameter is not valid.  
A PKA92-encrypted key having the same EID as the local  
node cannot be imported.  
8
8
153 (099)  
154 (09A)  
The text length exceeds the system limits.  
The key token that the key_identifier parameter specifies is not  
an internal key token or a key label.  
Appendix A. Return Codes and Reason Codes A-5  
CCA Release 2.54  
Figure A-4 (Page 3 of 6). Reason Codes for Return Code 8  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
8
155 (09B)  
The value that the generated_key_identifier parameter  
specifies is not valid, or it is not consistent with the value that  
the key_form parameter specifies.  
8
8
8
8
8
156 (09C)  
157 (09D)  
159 (09F)  
160 (0A0)  
161 (0A1)  
A keyword is not valid with the specified parameters.  
The key-token type is not specified in the rule array.  
The keyword supplied with the option parameter is not valid.  
The key type and the key length are not consistent.  
The value that the data_set_name_length parameter specifies  
is not valid.  
8
8
162 (0A2)  
163 (0A3)  
The offset value is not valid.  
The value that the data_set_name parameter specifies is not  
valid.  
8
8
8
164 (0A4)  
165 (0A5)  
168 (0A8)  
The starting address of the output area falls inside the input  
area.  
The carry_over_character_count that is specified in the  
chaining vector is not valid.  
A hexadecimal MAC value contains characters that are not  
valid, or the MAC on a request or reply failed because the  
user session key in the host and the adapter card do not  
match.  
8
8
169 (0A9)  
170 (0AA)  
An MDC_Generate text length error occurred.  
Special authorization through the operating system is required  
to use this verb.  
8
8
171 (0AB)  
175 (0AF)  
The control_array_count value is not valid.  
The key token cannot be parsed because no control vector is  
present.  
8
8
180 (0B4)  
181 (0B5)  
A null key token was presented for parsing.  
The key token is not valid. The first byte is not valid, or an  
incorrect token type was presented.  
8
183 (0B7)  
The key type is not consistent with the key type of the control  
vector.  
8
8
184 (0B8)  
185 (0B9)  
An input pointer is null.  
A disk I/O error occurred: perhaps the file is in-use, does not  
exist, etc.  
8
8
186 (0BA)  
187 (0BB)  
The key-type field in the control vector is not valid.  
The requested MAC length (MACLEN4, MACLEN6,  
MACLEN8) is not consistent with the control vector (key-a,  
key-b).  
8
8
8
191 (0BF)  
192 (0C0)  
204 (0CC)  
The requested MAC length (MACLEN6, MACLEN8) is not  
consistent with the control vector (MAC-LN-4).  
A key-storage record contains a record validation value that is  
not valid.  
A memory allocation failed. This can occur in the host and in  
the Coprocessor. Try closing other host tasks. If the problem  
persists, contact IBM.  
8
8
8
8
205 (0CD)  
323 (143)  
335 (14F)  
340 (154)  
The X9.23 ciphering method is not consistent with the use of  
the CONTINUE keyword.  
The ciphering method that the Decipher verb used does not  
match the ciphering method that the Encipher verb used.  
Either the specified cryptographic hardware component or the  
environment does not implement this function.  
One of the input control vectors has odd parity.  
A-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure A-4 (Page 4 of 6). Reason Codes for Return Code 8  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
8
343 (157)  
Either the data block or the buffer for the block is too small, or  
a variable has caused an attempt to create an internal data  
structure that is too large.  
8
374 (176)  
Less data was supplied than expected or less data exists than  
was requested.  
8
8
8
377 (179)  
382 (17E)  
385 (181)  
A key-storage error occurred.  
A time-limit violation occurred.  
The cryptographic hardware component reported that the data  
passed as part of a command is not valid for that command.  
The cryptographic hardware component reported that the user  
ID or role ID is not valid.  
The command was not processed because the profile cannot  
be used.  
The command was not processed because the expiration date  
was exceeded.  
The command was not processed because the active profile  
requires the user to be pre-verified.  
8
8
8
8
8
387 (183)  
393 (189)  
394 (18A)  
397 (18D)  
398 (18E)  
The command was not processed because the maximum  
PIN/password failure limit is exceeded.  
8
8
8
407 (197)  
442 (1BA)  
605 (25D)  
A PIN-block consistency-check-error occurred.  
DES keys with replicated halves are not allowed.  
The number of output bytes is greater than the number that is  
permitted.  
8
8
8
703 (2BF)  
704 (2C0)  
705 (2C1)  
A new master-key value was found to be one of the weak  
DES keys.  
The new master-key would have the same master key  
verification pattern as the current master-key.  
The same key-encrypting key was specified for both exporter  
keys.  
8
8
706 (2C2)  
707 (2C3)  
Pad count in deciphered data is not valid.  
The Master-Key registers are not in the state required for the  
requested function.  
8
8
713 (2C9)  
714 (2CA)  
The algorithm or function is not available on current hardware  
(DES on a CDMF-only system, or T-DES on DES-only or  
CDMF-only system)  
A reserved parameter was not a null pointer or an expected  
value.  
8
8
715 (2CB)  
718 (2CE)  
A parameter that must have a value of zero is invalid.  
The hash of the data block in the decrypted RSA-OAEP block  
does not match the hash of the decrypted data block.  
The block format (BT) field in the decrypted RSA-OAEP block  
does not have the correct value.  
The initial byte (I) in the decrypted RSA-OAEP block does not  
have a valid value.  
The V field in the decrypted RSA-OAEP does not have the  
correct value.  
8
8
8
719 (2CF)  
720 (2D0)  
721 (2D1)  
8
8
8
8
8
8
8
8
752 (2F0)  
753 (2F1)  
754 (2F2)  
756 (2F4)  
760 (2F8)  
761 (2F9)  
762 (2FA)  
763 (2FB)  
The key-storage file path is not usable.  
Opening the key-storage file failed.  
An internal call to the key_test command failed.  
Creation of the key-storage file failed.  
An RSA-key modulus length in bits or in bytes is not valid.  
An RSA-key exponent length is not valid.  
A length in the key value structure is not valid.  
The section identification number within a key token is invalid.  
Appendix A. Return Codes and Reason Codes A-7  
CCA Release 2.54  
Figure A-4 (Page 5 of 6). Reason Codes for Return Code 8  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
8
8
8
8
8
8
8
8
8
8
8
8
8
8
770 (302)  
771 (303)  
772 (304)  
773 (305)  
774 (306)  
775 (307)  
776 (308)  
777 (309)  
778 (30A)  
779 (30B)  
780 (30C)  
781 (30D)  
782 (30E)  
783 (30F)  
The PKA key token has an invalid field.  
The user is not logged on.  
The requested role was not found.  
The requested profile was not found.  
The profile already exists.  
The supplied data is not replaceable.  
The requested Id is already logged on.  
The authentication data is invalid.  
The checksum for the role is in error.  
The checksum for the profile is in error.  
There is an error in the profile data.  
There is an error in the role data.  
The Function-Control-Vector header is invalid.  
The command is not permitted by the Function-Control-Vector  
value.  
8
8
8
8
784 (310)  
785 (311)  
The operation you requested cannot be performed because  
the user profile is in use.  
The operation you requested cannot be performed because  
the role is presently in use.  
1025 (401) Registered Public Key or Retained Private Key Name already  
exists.  
1026 (402) Key name (Registered Public Key or Retained Private Key)  
does not exist.  
8
8
8
8
8
1027 (403) Environment Identifier Data is already set.  
1028 (404) Master Key Share Data is already set.  
1029 (405) There is an error in the Environment Identifier Data.  
1030 (406) There is an error in using the Master Key Share Data.  
1031 (407) There is an error in using Registered Public Key or Retained  
Private Key data.  
8
8
8
8
8
8
8
1032 (408) There is an error in using Registered Public Key Hash data.  
1033 (409) The Public Key Hash was not registered.  
1034 (40A) The Public Key was not registered.  
1035 (40B) The Public Key Certificate Signature was not verified.  
1037 (40D) There is a Master Key Shares distribution error.  
1038 (40E) The Public Key Hash is not marked for cloning.  
1039 (40F) The Registered Public Key Hash does not match the  
Registered Hash.  
8
8
8
8
8
8
8
8
1040 (410) The Master Key Share Enciphering Key failed encipher.  
1041 (411) The Master Key Share Enciphering Key failed decipher.  
1042 (412) The Master Key Share Digital Signature Generate failed.  
1043 (413) The Master Key Share Digital Signature Verify failed.  
1044 (414) There is an error in reading VPD data from the adapter.  
1045 (415) Encrypting the Cloning Information failed.  
1046 (416) Decrypting the Cloning Information failed.  
1047 (417) There is an error loading New Master Key from Master Key  
Shares.  
8
8
8
1048 (418) The Clone Information has one or more invalid sections.  
1049 (419) The Master Key Share Index is not valid.  
1050 (41A) The public-key encrypted-key is rejected because the EID with  
the key is the same as the EID for this node.  
8
1051 (41B) The private-key is rejected because the key is not flagged for  
use in master-key cloning.  
8
8
1100 (44C) General hardware device driver execution error.  
1101 (44D) Hardware device driver invalid parameter.  
A-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure A-4 (Page 6 of 6). Reason Codes for Return Code 8  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
8
8
1102 (44E) Hardware device driver invalid buffer length.  
1103 (44F) Hardware device driver too many opens. Cannot open device  
now.  
8
8
1104 (450) Hardware device driver access denied. Cannot access device.  
1105 (451) Hardware device driver device is busy and cannot perform  
request now.  
8
1106 (452) Hardware device driver buffer too small. Received data  
truncated.  
8
8
1107 (453) Hardware device driver request interrupted. Request aborted.  
1108 (454) Hardware device driver security tamper. Hardware intrusion  
detected.  
8
8
2034 (7F2) The environment variable used to set the default Coprocessor  
is invalid, or does not exist for a Coprocessor in the system.  
2036 (7F4) The contents of a chaining vector are not valid. Ensure that  
the chaining vector was not modified by your application  
program.  
8
8
2038 (7F6) No RSA private key information was provided.  
2041 (7F9) An invalid default card environment variable has been  
detected.  
8
2050 (802) The current key serial number field in the PIN profile variable  
is invalid (not hexadecimal or too many one bits).  
8
8
8
2051 (803) Invalid message length in OAEP-decoded information.  
2053 (805) No message found in the OAEP-decoded data.  
2054 (806) Invalid RSA Enciphered Key cryptogram: OAEP optional  
encoding parameters failed validation.  
8
8
2055 (807) The RSA public key is too small to encrypt the DES key.  
2062 (80E) The active role does not permit changing the characteristic of  
a double-length key in Key_Part_Import.  
8
8
2065 (811) The specified key token is not null.  
3001 (BB9) The RSA-OAEP block contains a PIN block and the verb did  
not request PINBLOCK processing.  
8
8
8
8
8
8
8
8
8
8
6000 (1770) The specified device is already allocated.  
6001 (1771) No device is allocated.  
6002 (1772) The specified device was not found.  
6003 (1773) The specified device is an improper type.  
6004 (1774) Use of the specified device is not authorized for this user.  
6005 (1775) The specified device is not varied on line.  
6006 (1776) The specified device is in a damaged state.  
6007 (1777) The key-storage file has not been designated.  
6008 (1778) The key-storage file has not been found.  
6009 (1779) The specified key-storage file is either the wrong type or the  
wrong format.  
8
8
6010 (177A) The user is not authorized to use the key-storage file.  
6011 (177B) The specified CCA verb request is not permitted from a  
secondary thread.  
8
8
8
6012 (177C) A cryptographic resource is already allocated.  
6013 (177D) The length of the cryptographic resource name is invalid.  
6014 (177E) The cryptographic resource name is invalid, or does not refer  
to a Coprocessor that is available in the system.  
Appendix A. Return Codes and Reason Codes A-9  
CCA Release 2.54  
Return Code 12  
Figure A-5. Reason Codes for Return Code 12  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
12  
097 (061)  
File space in key storage is insufficient to complete the  
operation.  
12  
196 (0C4)  
The device driver, the security server, or the directory server is  
not installed, or is not active, or in AIX, file permissions are not  
valid for your application.  
12  
12  
197 (0C5)  
206 (0CE)  
A key-storage file I/O error occurred, or a file was not found.  
The key-storage file is not valid, or the master-key verification  
failed. There is an unlikely but possible synchronization  
problem with the Master_Key_Process verb.  
The verification method flags in the profile are not valid.  
There was insufficient memory available to process your  
request, either memory in the host computer, or memory  
inside the Coprocessor including the Flash EPROM used to  
store keys, profiles, and other application data.  
This cryptographic hardware device driver is not installed or is  
not responding, or the CCA code is not loaded in the  
Coprocessor.  
12  
12  
207 (0CF)  
324 (144)  
12  
338 (152)  
12  
12  
12  
12  
12  
339 (153)  
764 (2FC)  
768 (300)  
A system error occurred in interprocess communication  
routine.  
The master key(s) are not loaded and therefore a key could  
not be recovered or enciphered.  
One or more paths for key-storage directory operations is  
improperly specified.  
2045 (7FD) The CCA software was unable to claim a semaphore. The  
system may be short of resources.  
2046 (7FE) The CCA software was unable to list all of the keys. The limit  
of 500 000 keys may have been reached.  
A-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Return Code 16  
Figure A-6. Reason Codes for Return Code 16  
Return  
Code  
Dec  
Reason  
Code  
Dec (Hex)  
Meaning  
16  
099 (063)  
An unrecoverable error occurred in the security server; contact  
your IBM service representative.  
16  
336 (150)  
An error occurred in a cryptographic hardware or software  
component.  
16  
16  
16  
16  
16  
337 (151)  
444 (1BC)  
556 (22C)  
708 (2C4)  
709 (2C5)  
A device software error occurred.  
The verb-unique-data had an invalid length.  
The request parameter block failed consistency checking.  
Inconsistent data was returned from the cryptographic engine.  
Cryptographic engine internal error, could not access the  
master-key data.  
16  
710 (2C6)  
An unrecoverable error occurred while attempting to update  
master-key data items.  
16  
16  
712 (2C8)  
769 (301)  
An unexpected error occurred in the master-key manager.  
The host system code or the CCA application in the  
Coprocessor encountered an unexpected error and was  
unable to process the request. Windows NT and 2000, and  
OS/2 support is limited to 32 concurrent requests.  
16  
16  
16  
16  
16  
2047 (7FF) Unable to transfer Request Data from host to Coprocessor.  
2057 (809) Internal error: memory allocation failure.  
2058 (80A) Internal error: unexpected return code from OAEP routines.  
2059 (80B) Internal error: OAEP SHA-1 request failure.  
2061 (80D) Internal error in CSNDSYI, OAEP-decode: enciphered  
message too long.  
Appendix A. Return Codes and Reason Codes A-11  
CCA Release 2.54  
A-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix B. Data Structures  
This appendix describes the following data structures:  
Key tokens  
Chaining vector records  
Key-storage records  
Key record list data set  
Access-control data structures  
Master key shares  
Distributed function control vector.  
Key Tokens  
This section describes the DES and RSA key-tokens used with the product. A “key  
token” is a data structure that contains information about a key and usually contains  
a key or keys.  
In general, a key that is available to an application program or held in key storage  
is multiply-enciphered by some other key. When a key is enciphered by the  
CCA-node's master key, the key is designated an “internal” key and is held in an  
internal key-token structure. Therefore, an internal key-token is used to hold a key  
and its related information for use at a specific CCA node.  
An external key-token is used to communicate a key between nodes, or to hold a  
key in a form not enciphered by a CCA master key. DES keys and RSA  
private-keys in an external key-token are multiply-enciphered by a transport key. In  
a CCA-node, a transport key is a double-length DES key-encrypting-key.  
The remainder of this section describes the structures used with the IBM 4758  
product family:  
Master key verification pattern  
Token-validation value and record-validation value  
Null key-token  
DES key-tokens  
– Internal DES key-token  
– External DES key-token  
– DES key-token flag bytes  
RSA key-tokens  
Chaining-vector records  
Key-storage records  
Key-record-list data set.  
Master Key Verification Pattern  
A Master Key Verification Pattern (MKVP) exists within an internal key token. An  
MKVP permits the cryptographic engine to detect if the key within the token is  
enciphered by an available master key. Different internal key-verification-pattern  
approaches are employed depending on the version of the key token and, for DES  
key tokens, the value of the symmetric master key. See “Master Key Verification  
Algorithms” on page D-1.  
Copyright IBM Corp. 1997, 2005  
B-1  
CCA Release 2.54  
An IBM 4758 does not permit the introduction of a new master key value that has  
the same verification value as either the current master-key or as the old  
master-key.  
Token-Validation Value and Record-Validation Value  
The Token-Validation Value (TVV) is a checksum that helps ensure that an  
application program-provided key token is valid. A Token-Validation Value is the  
sum (two’s complement ADD), ignoring carries and overflow, on the key token by  
operating on four bytes at a time, starting with bytes zero to three and ending with  
bytes 56 to 59. The four-byte strings are treated as big-endian binary numbers with  
the high-order byte stored in the lower address. DES key-token bytes 60 to 63  
contain the Token-Validation Value.  
When an application program supplies a key token, the CCA node checks the  
Token-Validation Value. When a CCA verb builds a DES key-token, it generates a  
Token-Validation Value in the key token.  
The record-validation value (RVV) used in DES key-storage records uses the same  
algorithm as the Token-Validation Value. The RVV is the sum of the bytes in  
positions 0 to 123 except for bytes 60 to 63.  
Null Key-Token  
Figure B-1 shows the null key-token format. With some CCA verbs, a null  
key-token can be used instead of an internal or an external key-token. A verb  
generally accepts a null key-token as a signal to use a key token with default  
values.  
A null key-token is indicated by the value X'00' at offset zero in a key token, a key  
token variable, or a key identifier variable.  
The (DES) Key_Import verb accepts input with offset zero valued to X'00'. In this  
special case, the verb treats information starting at offset 16 as an enciphered,  
single length key. In a very limited sense, this special case can be considered a  
“null key-token.”  
PKA key-storage uses an eight-byte structure, shown below, to represent a null  
key-token. The DES_Key_Record_Read verb will return this structure if a key  
record with a null key-token is read. Also, if you examine PKA key-storage, you  
should expect key records without a key token containing specific key values to be  
represented by a “null key-token.” In the case of key-storage records, the record  
length (offset 2 and 3) can be greater than 8.  
Figure B-1. PKA Null Key-Token Format  
Offset  
00  
Length  
01  
Meaning  
X'00' Indicates that this is a null key-token  
X'00' Version zero  
01  
01  
02  
02  
X'0008' Indicates a PKA null key-token  
Reserved, binary zero  
04  
04  
B-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
DES Key-Tokens  
DES key-token data structures are 64 bytes in length, contain an enciphered key, a  
control vector, various flag bits, version number, and token validation value.  
An internal key-token contains a key multiply-enciphered by a master key while an  
external key-token contains a key multiply-enciphered by some key-encrypting key.  
Internal DES Key-Token  
Starting with the IBM 4758 Version 2 CCA Support Program (IBM 4758 Models 002  
and 023), the support software accepts and outputs a version X'00' internal DES  
key-token. This support also accepts the version X'03' internal DES key-token.  
The IBM 4758 Version 1 CCA implementation (IBM 4758 Models 001 and 013)  
only supports a version X'03' internal DES key-token.  
Figure B-2. Internal DES Key-Token, Version 0 Format (Version 2 Software)  
Offset  
00  
Length  
Meaning  
1
3
1
1
1
1
8
8
X'01' (a flag that indicates an internal key-token)  
Reserved, binary zero  
01  
04  
The version number (X'00')  
Reserved, binary zero  
05  
06  
Flag byte 1; for more information, see Figure B-6 on page B-6  
Reserved, binary zero  
07  
08-15  
16-23  
Master key verification pattern  
The single-length operational (master-key encrypted) key or the left half of a  
double-length operational key  
24-31  
32-39  
40-47  
48-59  
60-63  
8
8
Null, or the right half of a double-length operational key  
The control-vector base  
8
Null, or the control vector base for the right half of a double-length key  
Reserved, binary zero  
12  
4
The token-validation value  
Figure B-3 (Page 1 of 2). Internal DES Key-Token, Version 3 Format  
Offset  
Length  
Meaning  
Note: Created and processed by version 1 Software. Version 2 software only accepts as input.  
00  
01  
1
1
2
1
1
1
1
8
8
X'01' (a flag that indicates an internal key-token)  
Reserved, binary zero  
02  
Master key verification pattern  
The version number (X'03')  
04  
05  
Reserved, binary zero  
06  
Flag byte 1; for more information, see Figure B-6 on page B-6  
Reserved, binary zero  
07  
08-15  
16-23  
Reserved, binary zero  
The single-length operational (master-key encrypted) key or the left half of a  
double-length operational key  
24-31  
32-39  
40-47  
8
8
8
Null, or the right half of a double-length operational key  
The control-vector base  
Null, or the control vector base for the right half of a double-length key  
Appendix B. Data Structures B-3  
CCA Release 2.54  
Figure B-3 (Page 2 of 2). Internal DES Key-Token, Version 3 Format  
Offset  
48-59  
60-63  
Length  
Meaning  
12  
4
Reserved, binary zero  
The token-validation value  
B-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
External DES Key-Token  
CCA implementations generally use a version X'00' external key-token. See  
Figure B-4. The IBM 4758 Version 2 CCA Support Program also uses a version  
X'01' external key-token to hold a double-length DATA key that is associated with  
a null (all-zero bits) control vector. See Figure B-5.  
Figure B-4. External DES Key-Token Format, Version X'00'  
Offset  
00  
Length  
Meaning  
1
3
1
1
1
1
X'02' (a flag that indicates an external key-token)  
Reserved, binary zero  
01  
04  
The version number (X'00')  
05  
Reserved, binary zero  
06  
Flag byte 1; for more information, see Figure B-6 on page B-6  
Flag byte 2; for more information, see Figure B-7 on page B-6  
Reserved, generally X'00', except X'02' will be tolerated.  
Reserved, binary zero  
07  
08-15  
16-23  
24-31  
32-39  
40-47  
48-59  
60-63  
8
8
The single-length key or the left half of a double-length key  
Null, or the right half of a double-length key  
The control-vector base  
8
8
8
Null, or the control vector base for the right half of a double-length key  
Reserved, binary zero  
12  
4
The token-validation value  
Figure B-5. External DES Key-Token Format, Version X'01'  
Offset  
00  
Length  
Meaning  
1
3
X'02' (a flag that indicates an external key-token)  
Reserved, binary zero  
01  
04  
1
The version number (X'01')  
Reserved, binary zero  
05  
1
06  
1
Flag byte 1; for more information, see Figure B-6 on page B-6  
Reserved, binary zero  
07  
1
08-15  
16-23  
24-31  
32-47  
48-58  
59  
8
Reserved, binary zero  
8
The left half of a double-length key  
The right half of a double-length key  
Null control vector, binary zero  
Reserved, binary zero  
8
16  
11  
1
Key length flag, double, X'10'  
The token-validation value  
60-63  
4
Appendix B. Data Structures B-5  
CCA Release 2.54  
DES Key-Token Flag Byte 1:  
Figure B-6. Key-Token Flag Byte 1  
1
Bits (MSB...LSB)  
Meaning  
1xxx xxxx  
The encrypted key value and the Master Key Verification Pattern are  
present  
0xxx xxxx  
x0xx xxxx  
x1xx xxxx  
An encrypted key is not present  
The control-vector value is not present  
The control-vector value is present  
All other bit combinations are reserved; undefined bits should be zero.  
DES Key-Token Flag Byte 2:  
Figure B-7. Key-Token Flag Byte 2  
Bits (MSB...LSB)  
Meaning  
For Key-Encrypting Keys  
0000 0010  
This key-encrypting key will import and export external key-tokens using  
the Transaction Security System key-token format.  
RSA PKA Key-Tokens  
PKA key-tokens contain various items, some of which are optional, and some of  
which can be present in different forms. The token is composed of concatenated  
sections that must occur in the prescribed order.  
As with other CCA key-tokens, both internal and external forms are defined.  
A PKA internal key-token contains a private key that is protected by encrypting  
the private key information using the CCA-node asymmetric master key, or by  
an object protection key (OPK) that is itself encrypted by the asymmetric  
master key. The internal key-token will also contain the modulus and the  
public-key exponent. A master key verification pattern is also included to  
enable determination that the proper master key is available to process the  
protected private key.  
Note, the format and content of an internal key-token is local to a specific node and  
product implementation, and does not represent an interchange format.  
An RSA external key-token contains the modulus and the public-key exponent.  
Also, the external key-token optionally contains the private key. If present, the  
private key may be in the clear or may be protected by encryption using a  
double-length DES transport key. An external key-token is an inter-product  
interchange data structure.  
An RSA private key can be represented in one of several forms:  
By a modulus and the private-key exponent  
By a set of numbers used in the Chinese-remainder theorem (CRT). The  
Coprocessor always generates a CRT key with p>q. If you import a CRT key  
from another RSA implementation with q>p the key will be usable within the  
1
MSB is the most significant bit; LSB is the least significant bit.  
B-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Coprocessor but your application will encounter a performance penalty with  
each use of the key.  
Protection of the private key is provided by encrypting a confounder (a random  
number) and the private key information exclusive of the modulus. An encrypted  
private key in an external key-token is protected by a double-length transport key  
and the EDE2 algorithm. See “CCA RSA Private Key Encryption and Decryption  
Process” on page C-12. The private key and the blinding values in an internal  
key-token are protected by the triple-length asymmetric master key and encryption  
algorithms as specified with each private key data structure.  
RSA Key-Token Sections  
A PKA key-token is the concatenation of an ordered set of sections. These  
key-token-section data structures are described.  
Section  
Reference  
Usage  
Header  
Figure B-8 on page B-9  
RSA Token Header  
X'04'  
Figure B-13 on page B-16  
Figure B-9 on page B-10  
RSA Public Key  
X'02'  
RSA Private Key, 1024-Bit  
Modulus-Exponent Format. Generated for  
external format for clear keys or for keys  
encrypted by a key-encrypting key.  
X'05'  
Figure B-10 on page B-11  
Figure B-11 on page B-13  
RSA Private Key, 2048-Bit  
Chinese-Remainder Format. Accepted only  
as an input and not generated in Version 2.  
X'06'  
RSA Private Key, 1024-Bit  
Modulus-Exponent Format with OPK. Only  
used as a master-key encrypted, internal  
format.  
X'08'  
Figure B-12 on page B-14  
Figure B-14 on page B-16  
RSA Private Key, Chinese-Remainder  
Format with OPK. Internal and external  
format; replaces section type X'05'.  
X'10'  
RSA Private-Key Name  
Figure B-15 on page B-17  
through Figure B-21 on  
page B-19  
RSA Public-Key Certificate(s)  
X'FF'  
Figure B-22 on page B-20  
RSA Private-Key Blinding Information  
Note: A modulus-exponent format is not supported for RSA keys with a modulus  
(key size) greater than 1024 bits.  
You form a PKA key-token by concatenating these sections:  
A token header (see Figure B-8 on page B-9):  
– An external header (first-byte X'1E')  
– An internal header (first-byte X'1F')  
An optional private-key section in one of these formats:  
– Section identifier X'02' for a clear or key-encrypting key enciphered,  
modulus-exponent format key up to 1024 bits  
– Section identifier X'06' for a master-key enciphered, modulus-exponent  
format key up to 1024 bits  
– Section identifier X'08' for a CRT-format key up to 2048 bits  
Appendix B. Data Structures B-7  
CCA Release 2.54  
– Section identifier X'05' for a CRT-format key up to 1024 bits is accepted  
as input.  
A public-key section (RSA section identifier X'04', see Figure B-13 on  
page B-16) see Figure B-13 on page B-16)  
An optional key-name section (section identifier X'10', see Figure B-14 on  
page B-16)  
For internal key-tokens with private keys in X'02' or X'05' sections, a  
private-key blinding section (section identifier X'FF', see Figure B-22 on  
page B-20)  
An optional certificate(s) section (section identifier X'40' with subsidiary  
sections, see Figure B-15 on page B-17).  
The key tokens can be built with the PKA_Key_Token_Build verb.  
PKA Key-Token Integrity  
If the token contains private key information, then the integrity of the information  
within the token can be verified by computing and comparing the SHA-1 hash  
values that are found in the private-key sections (portions of the key token). The  
SHA-1 hash value at offset four within the private-key section requires access to  
the cleartext values of the private-key components. The cryptographic engine will  
verify this hash quantity whenever it retrieves the secret key for productive use.  
A second SHA-1 hash value is located at offset 30 within the private key section.  
This hash value is computed on optional, designated key-token information  
following the public-key section. The value of this SHA-1 hash is included in the  
computation of the hash at offset four. As with the offset-four hash value, the hash  
at offset 30 is validated whenever a private key is recovered from the token for  
productive use.  
In addition to the hash checks, various token format and content checks are  
performed to validate the key values.  
The optional private-key name section can be used by access monitor systems (for  
example, RACF) to ensure that the application program is entitled to employ the  
particular private key.  
Number Representation in PKA Key-Tokens  
1. All length fields are in binary.  
2. All binary fields (exponents, lengths, and so forth) are stored with the  
high-order byte first (left, low-address, S/390 format); thus the least significant  
bits are to the right and preceded with zero-bits to the width of a field.  
3. In variable-length binary fields that have an associated field-length value,  
leading bytes that would contain X'00' can be dropped and the field shortened  
to contain only the significant bits.  
B-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-8. RSA Key-Token Header  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
Token identifier (a flag that indicates token type)  
X'1E'  
External token; the optional private-key is either in cleartext or  
enciphered by a transport key-encrypting-key.  
X'1F'  
Internal token; the private key is enciphered by the master key.  
001  
002  
004  
001  
002  
004  
The version number (X'00')  
Length of the key-token structure  
Reserved, binary zero  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Appendix B. Data Structures B-9  
CCA Release 2.54  
Figure B-9. RSA Private Key, 1024-Bit Modulus-Exponent Format  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
X'02' Section identifier, RSA private key, modulus-exponent format  
(RSA-PRIV). This section type is created by selected IBM 4755  
Cryptographic Adapters and the IBM 4758 Version 1 CCA Support Program.  
Version 2 software uses this format for a clear or an encrypted RSA private  
key in an external key-token.  
001  
002  
004  
001  
002  
020  
The version number (X'00')  
Length of the RSA private-key section X'016C' (364 decimal)  
SHA-1 hash value of the private-key subsection cleartext, offset 28 to and  
including the modulus that ends at offset 363  
024  
026  
028  
002  
002  
001  
Reserved, binary zero  
Master key verification pattern in an internal key-token, else X'0000'  
Key format and security  
X'00' Unencrypted RSA private-key subsection identifier  
X'82' Encrypted RSA private-key subsection identifier  
029  
030  
001  
020  
Reserved, binary zero  
SHA-1 hash of the optional key-name section; if there is no name section,  
then 20 bytes of X'00'  
050  
001  
Key usage flag bits  
The two high-order bits indicate permitted key usage in the decryption of  
symmetric keys and in the generation of digital signatures. Useful  
combinations:  
X'00'  
X'C0'  
X'80'  
Only signature generation (SIG-ONLY)  
Only key unwrapping (KM-ONLY)  
Both signature generation and key unwrapping (KEY-MGMT).  
All other bits, reserved, B'0'  
Reserved, binary zero  
051  
060  
084  
009  
024  
Reserved, binary zero  
Start of the optionally encrypted subsection.  
Private key encryption:  
External token: EDE2 process using the double-length transport key  
Internal token: EDE3 process using the asymmetric master key.  
See “Triple-DES Ciphering Algorithms” on page D-10.  
084  
108  
024  
128  
Random number (confounder)  
-1  
Private-key exponent, d. d=e mod((p-1)(q-1)), 1<d<n, and where e is the  
public exponent  
End of the optionally encrypted subsection. All of the fields starting with the confounder  
field and ending with the private-key exponent are enciphered for key confidentiality  
when the key format and security flags (offset 28) indicate that the private key is  
enciphered.  
512 1024  
Modulus, n. n=pq, where p and q are prime and 2 <n<2  
236  
128  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
B-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-10 (Page 1 of 2). Private Key, 2048-Bit Chinese-Remainder Format  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
X'05' Section identifier, RSA private key, CRT (RSA-OPT) format. This  
section type is created by the IBM 4758 Version 1 CCA Support Program.  
001  
002  
001  
002  
The version number (X'00')  
Length of the RSA private-key section, 76 +ppp +qqq +rrr +sss +ttt +uuu  
+xxx +nnn  
004  
024  
020  
002  
SHA-1 hash value of the private-key subsection cleartext, offset 28 to the  
end of the modulus  
Length in bytes of the optionally encrypted secure subsection, or X'0000' if  
the subsection is not encrypted  
026  
028  
002  
001  
Master key verification pattern in an internal key-token, else X'0000'  
Key format and security  
X'40' Unencrypted RSA private-key subsection identifier, Chinese remainder  
form  
X'42' Encrypted RSA private-key subsection identifier, Chinese remainder  
form  
029  
030  
001  
020  
Reserved, binary zero  
SHA-1 hash of the optional key-name section; if there is no name section,  
then 20 bytes of X'00'  
050  
001  
Key usage flag bits  
The high-order bit indicates permitted key usage in the decryption of  
symmetric keys.  
X'00'  
X'C0'  
X'80'  
Only signature generation (SIG-ONLY)  
Only key unwrapping (KM-ONLY)  
Both signature generation and key unwrapping (KEY-MGMT).  
All other bits, reserved, B'0'  
051  
052  
001  
Reserved, binary zero  
Start of the optionally encrypted subsection.  
Private key encryption:  
External token: EDE2 process using the double-length transport key  
Internal token: EDE3 process using the asymmetric master key.  
See “Triple-DES Ciphering Algorithms” on page D-10.  
052  
060  
062  
064  
066  
068  
070  
072  
074  
076  
008  
002  
002  
002  
002  
002  
002  
002  
002  
ppp  
qqq  
Random number, confounder  
Length of prime number, p, in bytes: ppp  
Length of prime number, q, in bytes: qqq  
Length of d , in bytes: rrr  
p
Length of d , in bytes: sss  
q
Length of A , in bytes: ttt  
p
Length of A , in bytes: uuu  
q
Length of modulus, n., in bytes: nnn  
Length of padding field, in bytes: xxx  
Prime number, p  
076  
Prime number, q  
+ppp  
Appendix B. Data Structures B-11  
CCA Release 2.54  
Figure B-10 (Page 2 of 2). Private Key, 2048-Bit Chinese-Remainder Format  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
076  
+ppp  
+qqq  
rrr  
d
= d mod(p-1)  
p
q
076  
+ppp  
+qqq  
+rrr  
sss  
d
= d mod(q-1)  
p-1  
mod(n)  
076  
+ppp  
+qqq  
+rrr  
ttt  
A
= q  
p
q
+sss  
076  
+ppp  
+qqq  
+rrr  
uuu  
A
= (n+1-A )  
p
+sss  
+ttt  
076  
+ppp  
+qqq  
+rrr  
xxx  
X'00' padding of length xxx bytes such that the length from the start of the  
random number above to the end of the padding field is a multiple of eight  
bytes  
+sss  
+ttt  
+uuu  
End of the optionally encrypted subsection; all of the fields starting with the confounder  
field and ending with the variable length pad field are enciphered for key confidentiality  
when the key format-and-security flags (offset 28) indicate that the private key is  
enciphered.  
512 2048  
Modulus, n. n=pq, where p and q are prime and 2 <n<2  
076  
+ppp  
+qqq  
+rrr  
nnn  
+sss  
+ttt  
+uuu  
+xxx  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
B-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-11. RSA Private Key, 1024-Bit Modulus-Exponent Format with OPK  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
X'06' Section identifier, RSA private key, modulus-exponent format  
(RSA-PRIV). This section type is created by the IBM 4758 Version 2 CCA  
Support Program. This section type provides compatibility and  
interchangeability with the CCF hardware in S/390 processors.  
001  
002  
004  
001  
002  
020  
The version number (X'00')  
Length of the RSA private-key section X'0198' (408 decimal)  
SHA-1 hash value of the private-key subsection cleartext, offset 28 up to and  
including the modulus that ends at offset 363  
024  
028  
004  
001  
Reserved, binary zero  
Key format and security  
X'02' Encrypted RSA private-key with OPK  
Private key source:  
029  
001  
X'21' Imported from cleartext  
X'22' Imported from ciphertext  
X'23' Generated using regeneration data  
X'24' Randomly generated  
030  
050  
020  
001  
SHA-1 hash of all optional sections that follow the public key section, if any,  
else 20 bytes of X'00'  
Key usage flag bits  
The two high-order bits indicate permitted key usage in the decryption of  
symmetric keys and in the generation of digital signatures. Useful  
combinations:  
X'00'  
X'C0'  
X'80'  
Only signature generation (SIG-ONLY)  
Only key unwrapping (KM-ONLY)  
Both signature generation and key unwrapping (KEY-MGMT).  
All other bits, reserved, B'0'  
Reserved, binary zero  
051  
054  
060  
003  
006  
048  
Reserved, binary zero  
Object Protection Key (OPK); six 8-byte values: confounder, three key  
values, and two initialization vector values.  
The asymmetric master key encrypts the OPK using the EDE3 algorithm.  
See “Triple-DES Ciphering Algorithms” on page D-10.  
-1  
108  
128  
Private-key exponent, d. d=e mod((p-1)(q-1)), 1<d<n, and where e is the  
public exponent.  
The OPK encrypts the private key exponent using the EDE5 algorithm. See  
“Triple-DES Ciphering Algorithms” on page D-10 and Figure D-9 on  
page D-12.  
512  
1024  
236  
364  
380  
128  
016  
020  
Modulus, n. n=pq, where p and q are prime and 2 <n<2  
Asymmetric-keys master key verification pattern  
SHA-1 hash value of the subsection cleartext, offset 400 to the section end.  
This hash value is checked after an enciphered private key is deciphered for  
use. This hash would protect blinding information if that were required by a  
future design; see earlier Basic Services manuals.  
400  
402  
404  
406  
002  
002  
002  
002  
Reserved, binary zero  
Reserved, binary zero  
Reserved, binary zero  
Reserved, binary zero  
Appendix B. Data Structures B-13  
CCA Release 2.54  
Figure B-12 (Page 1 of 2). RSA Private Key, Chinese-Remainder Format with OPK  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
X'08' Section identifier, RSA private key, CRT format (RSA-CRT). This  
section type is created by the IBM 4758 Version 2 CCA Support Program.  
001  
002  
001  
002  
The version number (X'00')  
Length of the RSA private-key section, 132 +ppp +qqq +rrr +sss +uuu +xxx  
+nnn  
004  
020  
SHA-1 hash value of the private-key subsection cleartext, offset 28 to the  
end of the modulus  
024  
028  
004  
001  
Reserved, binary zero  
Key format and security:  
External token:  
X'40' Unencrypted RSA private-key subsection identifier  
X'42' Encrypted RSA private-key subsection identifier  
Internal token:  
X'08' Encrypted RSA private-key subsection identifier  
029  
001  
External tokens, reserved, binary zero  
Internal tokens:  
X'21' Imported from cleartext  
X'22' Imported from ciphertext  
X'23' Generated using regeneration data  
X'24' Randomly generated  
030  
050  
020  
001  
SHA-1 hash of all optional sections that follow the public key section, if any;  
else 20 bytes of X'00'  
Key usage flag bits  
The two high-order bits indicate permitted key usage in the decryption of  
symmetric keys and in the generation of digital signatures. Useful  
combinations:  
X'00'  
X'C0'  
X'80'  
Only signature generation (SIG-ONLY)  
Only key unwrapping (KM-ONLY)  
Both signature generation and key unwrapping (KEY-MGMT).  
All other bits, reserved, B'0'  
051  
054  
056  
058  
060  
062  
064  
066  
068  
070  
072  
076  
003  
002  
002  
002  
002  
002  
002  
002  
002  
002  
004  
016  
Reserved, binary zero  
Length of the prime number, p, in bytes: ppp  
Length of the prime number, q, in bytes: qqq  
Length of d , in bytes: rrr  
p
Length of d , in bytes: sss  
q
Length of the 'U' value, in bytes: uuu  
Length of the modulus, n, in bytes: nnn  
Reserved, binary zero  
Reserved, binary zero  
Length of the pad field, in bytes: xxx  
Reserved, binary zero  
External token, reserved, binary zero  
Internal token, asymmetric master key verification pattern  
092  
032  
External token: reserved, binary zero.  
Internal token: Object Protection Key (OPK), eight-byte confounder and 3  
eight-byte keys used in the triple-DES CBC process to encrypt the private  
key and blinding information. These 32 bytes are triple-DES CBC encrypted  
by the asymmetric master key. See T-DES at “Triple-DES Ciphering  
Algorithms” on page D-10.  
B-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-12 (Page 2 of 2). RSA Private Key, Chinese-Remainder Format with OPK  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
124  
Start of the (optionally) encrypted subsection.  
External token:  
When offset 028 is X'40', the subsection is not encrypted  
When offset 028 is X'42', the subsection is encrypted by the double-length  
transport key using the triple-DES CBC process.  
Internal token:  
When offset 028 is X'08', the subsection is encrypted by the triple-length OPK  
using the triple-DES CBC process.  
See “Triple-DES Ciphering Algorithms” on page D-10.  
124  
132  
008  
ppp  
qqq  
Random number, confounder  
Prime number, p  
132  
Prime number, q  
+ppp  
132  
+ppp  
+qqq  
rrr  
d
= d mod(p-1)  
= d mod(q-1)  
p
q
132  
+ppp  
+qqq  
+rrr  
sss  
d
-1  
132  
+ppp  
+qqq  
+rrr  
uuu  
xxx  
U = q mod(p)  
+sss  
132  
+ppp  
+qqq  
+rrr  
X'00' padding of length xxx bytes such that the length from the start of the  
confounder at offset 124 to the end of the padding field is a multiple of eight  
bytes  
+sss  
+uuu  
End of the optionally encrypted subsection; all of the fields starting with the confounder  
field and ending with the variable length pad field are enciphered for key confidentiality  
when the key format-and-security flags (offset 28) indicate that the private key is  
enciphered.  
512 2048  
Modulus, n. n=pq where p and q are prime and 2 <n<2  
132  
+ppp  
+qqq  
+rrr  
nnn  
+sss  
+uuu  
+xxx  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Appendix B. Data Structures B-15  
CCA Release 2.54  
Figure B-13. RSA Public Key  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
006  
008  
010  
001  
001  
002  
002  
002  
002  
002  
X'04', Section identifier, RSA public key  
The version number (X'00')  
Section length, 12+xxx+yyy  
Reserved, binary zero  
RSA public-key exponent field length in bytes, “xxx”  
Public-key modulus length in bits.  
RSA public-key modulus field length in bytes, “yyy”  
Note: If the token contains an RSA private-key section, this field length, yyy,  
should be zero. The RSA private-key section will contain the modulus.  
012  
xxx  
Public-key exponent, e (this field length will generally be 1, 3, or 64 to 256  
bytes). e must be odd and 1<e<n. (e is frequently valued to 3 or 2 +1  
16  
(=65 537), otherwise e is of the same order of magnitude as the modulus)  
Note: You can import an RSA public key having an exponent valued to two  
(2). Such a public key can correctly validate an ISO 9796-1 digital signature.  
However, the current product implementation will not generate an “RSA” key  
with a public exponent valued to two (a “Rabin” key).  
512  
2048  
. This field  
012  
yyy  
Modulus, n. n=pq where p and q are prime and 2 <n<2  
+xxx  
will be absent when the modulus is contained in the private-key-section. If  
present, the field length will be 64 to 256 bytes  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Figure B-14. RSA Private-Key Name  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
064  
X'10', Section identifier, private-key name  
The version number (X'00')  
Section length, X'0044' (68 decimal)  
Private-key name, left-justified, padded with space characters (X'20'). The  
private-key name can be used by an access-control system to validate the  
calling application's entitlement to employ the key. When generating a  
retained private key, the name supplied in this part of the skeleton key-token  
is subsequently used in the Coprocessor to locate the retained key.  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
B-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
RSA Public-Key Certificate Section: An optional public key certificate(s) section  
can be included in an RSA key-token. The section consists of:  
The section header (identifier X'40')  
A public key subsection (identifier X'41')  
An optional certificate information subsection (identifier X'42') with any or all of  
these elements:  
– User data (identifier X'50')  
– EID (identifier X'51')  
– Serial number (identifier X'52')  
A signature subsection (identifier X'45').  
The section (as with the rest of the key token) is composed of a series of  
“tag-length-variable” (TLV) items to form a self-defining data structure. One or  
more TLV items can be included in the variable portion of a higher level TLV item.  
The section header is described followed by descriptions of the TLV items that can  
be included in the section.  
Figure B-15. RSA Public-Key Certificate(s) Section Header  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
001  
001  
002  
X'40', Section identifier, certificate  
The version number (X'00')  
Section length; includes:  
Section header  
Public key subsection  
Information subsection (optional)  
Signature subsection(s).  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Figure B-16. RSA Public-Key Certificate(s) Public Key Subsection  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
006  
008  
010  
012  
001  
001  
002  
002  
002  
002  
002  
xxx  
X'41', Public Key Subsection identifier  
The version number (X'00')  
Subsection length, 12+xxx+yyy  
Reserved, binary zero  
RSA public-key exponent field length in bytes, “xxx”  
Public-key modulus length in bits  
RSA public-key modulus field length in bytes, “yyy”  
Public-key exponent, e (this field length will generally be 1, 3, or 64 to 256  
bytes). e must be odd and 1<e<n.  
512  
2048  
. This field  
012  
yyy  
Modulus, n. n=pq, where p and q are prime and 2 <n<2  
+xxx  
will be absent when the modulus is contained in the private-key section. If  
present, the field length will be 64 to 256 bytes, inclusive.  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Appendix B. Data Structures B-17  
CCA Release 2.54  
Figure B-17. RSA Public-Key Certificate(s) Optional Information Subsection Header  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
iii  
X'42', Information Subsection Header  
The version number (X'00')  
Subsection length, 4+iii  
The information field that will contain any of the includable TLV entities:  
User data (Id = 50)  
EID (Id = 51)  
Serial number (Id = 52)  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Figure B-18. RSA Public-Key Certificate(s) User Data TLV  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
uuu  
X'50', User Data TLV Header  
The version number (X'00')  
TLV length, 4+uuu  
User-provided data. 0 uuu 64  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Figure B-19. RSA Public-Key Certificate(s) Environment Identifier (EID) TLV  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
016  
X'51', Private Key Environment Identifier TLV Header  
The version number (X'00')  
X'0014', TLV length  
EID string of the CCA node that generated the public (and private) key.  
(This TLV must be provided in a skeleton key-token with usage of the  
PKA_Key_Generate verb. The verb will fill in the EID string prior to certifying  
the public key.) The EID value is encoded using the ASCII character set.  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Figure B-20. RSA Public-Key Certificate(s) Serial Number TLV  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
008  
X'52', Serial Number TLV Header  
The version number (X'00')  
X'000C', TLV length  
Serial number of the Coprocessor that generated the public (and private) key.  
(This TLV must be provided in a skeleton key-token with usage of the  
PKA_Key_Generate verb. The verb will fill in the serial number prior to  
certifying the public key.)  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
B-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-21. RSA Public-Key Certificate(s) Signature Subsection  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
001  
X'45', Signature Subsection Header  
The version number (X'00')  
Subsection length, 70+sss  
Hashing algorithm identifier; X'01' signifies use of the SHA-1 hashing  
algorithm  
005  
006  
001  
064  
Signature formatting identifier; X'01' signifies use of the ISO 9796-1 process  
Signature-key identifier; the key label of the key used to generate the  
signature  
070  
sss  
The signature field  
The signature is calculated on data that begins with the Signature Section  
Identifier (X'40') through the byte immediately preceding this signature field.  
Note: More than one Signature Subsection can be included in a Signature Section; this  
accommodates the possibility of a self-signature as well as a device-key signature.  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Appendix B. Data Structures B-19  
CCA Release 2.54  
RSA Private-Key Blinding Information:  
Figure B-22. RSA Private-Key Blinding Information  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
X'FF', Section identifier, private-key blinding information.  
Used with internal key-tokens created by the CCA Support Program, Version  
1 (having section identifiers X'02' or X'05').  
001  
002  
004  
001  
002  
020  
The version number (X'00')  
Section length, 34 + rrr + iii  
SHA-1 hash value of the internal information subsection cleartext, offset 28 to  
the section end. This hash value is checked after an enciphered private key  
is deciphered for use.  
024  
026  
028  
002  
002  
Length in bytes of the encrypted secure subsection  
Reserved, binary zero  
Start of the encrypted secure subsection. An internal token with section identifiers  
X'02' or X'05' uses the asymmetric master key and the EDE3 algorithm.  
See“Triple-DES Ciphering Algorithms” on page D-10 .  
028  
030  
032  
034  
002  
002  
002  
rrr  
Length of the random number r, in bytes: rrr  
-1  
Length of the random number inverse r , in bytes: iii  
Length of the padding field, in bytes xxx  
Random number r (used in blinding)  
-1  
034  
+rrr  
iii  
Random number r (used in blinding)  
034  
+rrr  
+iii  
xxx  
X'00' padding of length xxx bytes such that the length from the start of the  
encrypted subsection to the end of the padding field is a multiple of eight  
bytes.  
End of the encrypted subsection.  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
Chaining-Vector Records  
The chaining_vector parameter specifies an address that points to the place in  
main storage that contains an 18-byte work area that is required with the Cipher,  
MAC_Generate and MAC_Verify, verbs. The application program should not  
change the chaining-vector information. The verb uses the chaining vector to carry  
information between procedure calls.  
Figure B-23. Cipher, MAC_Generate, and MAC_Verify Chaining-Vector Format  
Offset  
Length  
Meaning  
00-07  
8
The cryptographic Output Chaining-Vector (OCV) of the service. When used  
with the MAC_Generate and MAC_Verify verbs, the OCV is enciphered as a  
cryptographic variable  
08  
09-15  
16  
1
7
2
The count of the bytes that are carried over and not processed (from 0 to 7)  
The bytes that are carried over and left-justified  
The token master-key verification pattern  
Note: See “Number Representation in PKA Key-Tokens” on page B-8.  
B-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key-Storage Records  
Key storage exists as an online, Direct Access Storage Device (DASD)-resident  
data set for the storage of key records. Key records contain a key label, space for  
a key token, and control information. The stored key tokens are accessed using  
the key label. DES and PKA key tokens are held in independent key storage data  
sets.  
For platforms other than OS/400, the first two records in key storage contain  
key-storage control information that includes the key verification information for the  
master key that is used to multiply-encipher the keys that are held in key storage.  
Figure B-24 shows the format of the first record in the file header of the  
key-storage file. This record contains the default master-key verification  
pattern, and part of the file description.  
Figure B-25 on page B-23 shows the format of the second record in the file  
header of the key-storage file. This record contains the rest of the file  
description for key storage.  
For platforms other than OS/400, Figure B-26 on page B-23 shows the format of  
both the DES and PKA records that contain key tokens. For the OS/400 platform,  
the DES and PKA key tokens are held in distinct record formats.  
Figure B-27 on page B-24 shows the format of the records in OS/400 DES  
key-storage that contain key tokens.  
Figure B-28 on page B-24 shows the format of the records in OS/400 PKA  
key-storage that contain key tokens.  
Appendix B. Data Structures B-21  
CCA Release 2.54  
Figure B-24. Key-Storage-File Header, Record 1 (not OS/400)  
Offset  
00  
Length  
04  
Meaning  
The total length of this key record.  
The record validation value.  
The key label without separators.  
04  
04  
08  
64  
$$FORTRESS$REL01$MASTER$KEY$VERIFY$PATTERN .  
72  
15  
The date and time of when this record was created. The date string consists  
of an 8 digit date and a 6 digit time ( ccyymmddhhmmssz ) where:  
cc - century  
yy - year  
mm - month  
dd - day  
hh - Hour in 24 hour format (00-24).  
mm - Minutes.  
ss - Seconds.  
z - String terminator (0x00)  
87  
15  
The date and time of when this record was last updated. This field has the  
same format as the created date.  
102  
128  
26  
01  
Reserved  
An indicator that this is either an internal DES (X'01') or PKA (X'1F') key  
token.  
129  
130  
132  
134  
01  
02  
02  
02  
Version 1, X'00'; Version 2, X'01'.  
Token length which is a value of 64.  
Reserved  
First two bytes of the SHA-1 MKVP. See “SHA-1 Based Master Key  
Verification Method” on page D-1.  
136  
152  
16  
24  
The master key verification pattern of the current master key in the  
cryptographic facility when this file was initialized.  
The first 24 bytes of the file description (the remaining 40 bytes are stored in  
the second record).  
176  
188  
12  
04  
Reserved  
The token validation value. Bytes 128 through 191 are considered to be the  
64 byte token.  
B-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-25. Key-Storage File Header, Record 2 (not OS/400)  
Offset  
00  
Length  
04  
Meaning  
The total length of this key record.  
The record validation value.  
The key label without separators.  
04  
04  
08  
64  
For the DES key-storage file the key label is  
$$FORTRESS$DES$REL01$KEY$STORAGE$FILE$HEADER .  
For the PKA key-storage file the key label is  
$$FORTRESS$PKA$REL01$KEY$STORAGE$FILE$HEADER .  
72  
87  
15  
15  
The date and time of when this record was created. This field has the same  
format as the created date in Figure B-24 on page B-21.  
The date and time of when this record was last updated. This field has the  
same format as the created date in Figure B-24 on page B-21.  
102  
128  
129  
130  
132  
136  
26  
01  
01  
02  
04  
40  
Reserved  
An indicator that this is either an internal DES or PKA key token.  
Reserved  
Token length which is a value of 64.  
Reserved  
The last 40 bytes of the file description (the first 24 bytes were stored in the  
first record).  
176  
188  
12  
04  
Reserved  
The token validation value. Bytes 128 through 191 are considered to be the  
64 byte token.  
Figure B-26. Key-Record Format in Key Storage (not OS/400)  
Offset  
00  
Length  
04  
Meaning  
The total length of this key record.  
The record validation value.  
The key label without separators.  
04  
04  
08  
64  
72  
15  
The date and time of when this record was created. This field has the same  
format as the created date in Figure B-24 on page B-21.  
87  
15  
The date and time of when this record was last updated. This field has the  
same format as the created date in Figure B-24 on page B-21.  
102  
128  
26  
??  
Reserved  
A DES or PKA key token.  
Appendix B. Data Structures B-23  
CCA Release 2.54  
Figure B-27. DES Key-Record Format, OS/400 Key Storage  
Offset  
00  
Length  
56  
Meaning  
The key label without separators.  
Reserved  
56  
02  
58  
64  
The DES key token.  
122  
04  
The date and time of when this record was created. This field has the same  
format as the created date in Figure B-24 on page B-21.  
126  
04  
The date and time of when this record was last updated. This field has the  
same format as the created date in Figure B-24 on page B-21.  
130  
132  
136  
02  
04  
Reserved  
The record validation value.  
Reserved  
120  
Figure B-28. PKA Key-Record Format, OS/400 Key Storage  
Offset  
00  
Length  
64  
Meaning  
The key label without separators.  
Reserved  
64  
24  
88  
04  
The date and time of when this record was created. This field has the same  
format as the created date in Figure B-24 on page B-21.  
92  
04  
The date and time of when this record was last updated. This field has the  
same format as the created date in Figure B-24 on page B-21.  
96  
100  
102  
04  
02  
??  
The record validation value.  
The key token length  
The PKA key token  
B-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key_Record_List Data Set  
There are two Key_Record_List verbs, one for the DES key store and one for the  
PKA key store. Each creates an internal data set that contains information about  
specified key records in key storage. Both verbs return the list in a data set,  
KYRLTnnn.LST, where nnn is the numeric portion of the name and nnn starts at  
001 and increments to 999 and then wraps back to 001. You locate the data set  
using the fully-qualified data-set name returned by the DES_Key_Record_List and  
PKA_Key_Record_List verbs.  
The data set has a header record, followed by zero to n detail records, where n is  
the number of key records with matching key labels.  
Figure B-29 (Page 1 of 2). Key-Record-List Data Set Format (Other Than OS/400)  
Offset  
Length  
Meaning  
Header Record (Part 1)  
0
24  
This field contains the installation-configured listing header (the default value  
for the DES key store is DES KEY-RECORD-LIST and for the PKA key store  
is PKA KEY-RECORD-LIST).  
24  
26  
2
This field contains spaces for separation.  
19  
This field contains the date and the time when the list was generated. The  
format is ccyy-mm-dd hh:tt:ss, where:  
cc  
yy  
Is the century  
Is the year  
mm Is the month  
dd  
hh  
tt  
Is the day  
Is the hour  
Is the minute  
Is the second.  
ss  
A space character separates the day and the hour.  
This field contains spaces for separation.  
45  
50  
56  
58  
5
6
2
4
This field contains the number of detail records.  
This field contains spaces for separation.  
This field contains the length of each detail record, in character form, and  
left-justified. (The length is 154.)  
62  
4
This field contains the offset to the first detail record, in character form, and  
left-justified. (The offset is 154.)  
66  
75  
9
2
This field is reserved filled with space characters.  
This field contains carriage return/line feed (CR/LF).  
Header Record (Part 2)  
77  
141  
152  
64  
11  
2
This field contains the key-label pattern that you used to request the list.  
This field is reserved filled with space characters.  
This field contains a carriage return or line feeds (CR/LF).  
Appendix B. Data Structures B-25  
CCA Release 2.54  
Figure B-29 (Page 2 of 2). Key-Record-List Data Set Format (Other Than OS/400)  
Offset  
Length  
Meaning  
Detail Record (Part 1)  
0
1
This field contains an asterisk (*) if the key-storage record did not have a  
correct record validation value; this record should be considered to be a  
potential error.  
1
3
2
64  
8
This field contains spaces for separation.  
This field contains the key label.  
67  
This field contains the key type. If a null key token exists in the record or if  
the key token does not contain the key value, this field is set to NO-KEY.  
For the DES key-storage, if the key token does not contain a control vector,  
this field is set to NO-CV. If the control vector cannot be decoded to a  
recognized key type, this field is set to ERROR, and an asterisk (*) is set into  
the record at offset 0. For PKA key-storage, the possible key types are:  
RSA-PRIV, RSA-PUBL, or RSA-OPT.  
75  
2
This field contains a carriage return or line feeds (CR/LF).  
Detail Record (Part 2)  
77/0  
4
For an internal token, this field will contain (the first) two bytes of the Master  
key verification pattern expressed in hexadecimal.  
81/4  
82/5  
1
8
This field contains spaces for separation  
Reserved, filled with space characters.  
This field contains spaces for separation.  
90/13  
92/15  
2
19  
This field contains the date and time when the record was created. The  
format is ccyy-mm-dd hh:tt:ss, where:  
cc  
yy  
Is the century  
Is the year  
mm Is the month  
dd  
hh  
tt  
Is the day  
Is the hour  
Is the minute  
Is the second.  
ss  
A space character separates the day and the hour.  
This field contains spaces for separation.  
111/34  
113/36  
2
19  
This field contains the last time and date when the record was updated. The  
format is ccyy-mm-dd hh:tt:ss, where:  
cc  
yy  
Is the century  
Is the year  
mm Is the month  
dd  
hh  
tt  
Is the day  
Is the hour  
Is the minute  
Is the second.  
ss  
A space character separates the day and the hour.  
This field contains a space character for separation.  
132/55  
133/56  
1
8
This field contains type of token, INTERNAL, EXTERNAL or NO-KEY (null  
token). Anything else, this field is set of ERROR and an asterisk (*) is set  
into the record offset 0 field.  
141/64  
152/75  
11  
2
Reserved, filled with space characters.  
This field contains a carriage return (CR) or line feeds (LF).  
B-26 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-30 (Page 1 of 2). Key-Record-List Data Set Format (OS/400 only)  
Offset  
Length  
Meaning  
Header Record  
0
24  
This field contains the installation-configured listing header (the default value  
for the DES key store is DES KEY-RECORD-LIST and for the PKA key store  
is PKA KEY-RECORD-LIST).  
24  
26  
2
This field contains spaces for separation.  
19  
This field contains the date and the time when the list was generated. The  
format is ccyy-mm-dd hh:tt:ss, where:  
cc  
yy  
Is the century  
Is the year  
mm Is the month  
dd  
hh  
tt  
Is the day  
Is the hour  
Is the minute  
Is the second.  
ss  
A space character separates the day and the hour.  
This field contains spaces for separation.  
45  
50  
56  
58  
5
6
2
4
This field contains the number of detail records.  
This field contains spaces for separation.  
This field contains the length of each detail record, in character form, and  
left-justified. (The length is 134.)  
62  
68  
6
64  
2
This field is reserved filled with space characters.  
This field contains the key-label pattern that you used to request the list.  
This field is reserved filled with space characters.  
132  
Appendix B. Data Structures B-27  
CCA Release 2.54  
Figure B-30 (Page 2 of 2). Key-Record-List Data Set Format (OS/400 only)  
Offset  
Length  
Meaning  
Detail Record  
0
1
This field contains an asterisk (*) if the key-storage record did not have a  
correct record validation value; this record should be considered to be a  
potential error.  
1
3
2
64  
8
This field contains spaces for separation.  
This field contains the key label.  
67  
This field contains the key type. If a null key token exists in the record or if  
the key token does not contain the key value, this field is set to NO-KEY.  
For the DES key-storage, if the key token does not contain a control vector,  
this field is set to NO-CV. If the control vector cannot be decoded to a  
recognized key type, this field is set to ERROR, and an asterisk (*) is set into  
the record at offset 0. For PKA key-storage, the possible key types are:  
RSA-PRIV, RSA-PUBL, or RSA-OPT.  
75  
77  
2
4
This field is reserved filled with space characters.  
For an internal token, this field will contain (the first) two bytes of the Master  
key verification pattern expressed in hexadecimal.  
81  
82  
90  
92  
1
8
This field contains spaces for separation  
Reserved, filled with space characters.  
This field contains spaces for separation.  
2
19  
This field contains the date and time when the record was created. The  
format is ccyy-mm-dd hh:tt:ss, where:  
cc  
yy  
Is the century  
Is the year  
mm Is the month  
dd  
hh  
tt  
Is the day  
Is the hour  
Is the minute  
Is the second.  
ss  
A space character separates the day and the hour.  
This field contains spaces for separation.  
111  
113  
2
19  
This field contains the last time and date when the record was updated. The  
format is ccyy-mm-dd hh:tt:ss, where:  
cc  
yy  
Is the century  
Is the year  
mm Is the month  
dd  
hh  
tt  
Is the day  
Is the hour  
Is the minute  
Is the second.  
ss  
A space character separates the day and the hour.  
This field is reserved filled with space characters.  
132  
2
Access-Control Data Structures  
The following sections define the data structures that are used in the access-control  
system.  
Unless otherwise noted, all two-byte and four-byte integers are in big-endian  
format; the high-order byte of the value is in the lowest-numbered address in  
memory.  
B-28 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Role Structure  
This section describes the data structures used with roles.  
Basic Structure of a Role  
The following figure describes how the Role data is structured. This is the format  
used when role data is transferred to or from the Coprocessor, using verbs  
CSUAACI or CSUAACM.  
Bytes  
Field  
┌───────┐  
2
2
│ Role structure version (X'ꢃ1', X'ꢃꢃ')  
├───────┤  
│ Role structure length (bytes)  
├───────┴─────────────────────────────────── ─ ────────────┐  
2ꢃ  
2
│ Comment  
├───────┬─────────────────────────────────── ─ ────────────┘  
│ Checksum  
├───────┤  
2
│ Reserved  
├───────┴───────────────────────┐  
8
│ Role ID  
├───────┬───────────────────────┘  
2
│ Required Authentication Strength  
├───────┤  
2
│ Lower time limit  
├───────┤  
2
│ Upper time limit  
├───┬───┘  
1
│ Valid DOW  
├───┤  
1
│ Reserved  
├───┴─────────────────────────────────────── ─ ────────────┐  
variable │  
│ Permitted Operations  
└─────────────────────────────────────────── ─ ────────────┘  
Figure B-31. Role Layout  
The checksum is defined as the exclusive-OR (XOR) of each byte in the role  
structure. The high-order byte of the checksum field is set to zero (X'00'), and the  
exclusive-OR result is put in the low-order byte.  
Note: The checksum value is not used in the current role structure. It may be  
verified by the Cryptographic Coprocessor with a future version of the role  
structure.  
The Permitted Operations are defined by the Access-Control-Point list, described in  
“Access-Control-Point List” on page B-30 below.  
The lower time limit and upper time limit fields are two-byte structures with each  
byte containing a binary value. The first byte contains the hour (0-23) and the  
second byte contains the minute (0-59). For example, 8:45 AM is represented by  
X'08' in the first byte, and X'2D' in the second.  
If the lower time limit and upper time limit are identical, the role is valid for use at  
any time of the day.  
The valid days-of-the-week are represented in a single byte with each bit  
representing a single day. Set the appropriate bit to one to validate a specific day.  
The first, or Most Significant Bit (MSB) represents Sunday, the second bit  
represents Monday, and so on. The last or Least Significant Bit (LSB) is reserved  
and must be set to zero.  
Appendix B. Data Structures B-29  
CCA Release 2.54  
Aggregate Role Structure  
A set of zero one or more role definitions are sent in a single data structure. This  
structure consists of a header, followed by one or more role structures as defined in  
“Basic Structure of a Role” on page B-29.  
The header defines the number of roles which follow in the rest of the structure. Its  
layout is shown in Figure B-32, with three concatenated role structures shown for  
illustration.  
Bytes  
Field  
┌───────┐  
4
4
│ Number of roles in aggregate structure  
├───────┤  
│ Reserved  
├───────┴───────────────────────────────────┐  
variable│  
│ First role  
├───────────────────────────────────────────┴─────────────┐  
variable│ │ Second role  
├───────────────────────────────────────┬─────────────────┘  
variable│ │ Third role  
└───────────────────────────────────────┘  
Figure B-32. Aggregate Role Structure with Header  
Access-Control-Point List  
The user's permissions are attached to each Role in the form of an  
Access-Control-Point list. This list is a map of bits, with one bit for each primitive  
function that can be independently controlled. If a bit is True (1), the user has the  
authority to use the corresponding function, if all other access conditions are also  
satisfied. If the bit is False (0), the user is not permitted to make use of the  
function that bit represents.  
The access-control-point identifiers are two byte integers. This provides a total  
space of 64K possible bits. Only a small fraction of these are used, so storing the  
entire 64K bit (8K byte) table in each role would be an unnecessary waste of  
memory space. Instead, the table is stored as a sparse matrix, where only the  
necessary bits are included.  
To accomplish this, each bitmap is stored as a series of one or more bitmap  
segments, where each can hold a variable number of bits. Each segment must  
start with a bit that is the high-order bit in a byte, and each must end with a bit that  
is the low order bit in a byte. This restriction results in segments that have no  
partial bytes at the beginning or end. Any bits that do not represent defined  
access-control points must be set to zero, indicating that the corresponding function  
is not permitted.  
The bitmap portion of each segment is preceded by a header, providing information  
about the segment. The header contains the following fields.  
Starting bit number The index of the first bit contained in the segment. The index  
of the first access-control point in the table is zero (X'0000').  
Ending bit number The index of the last bit contained in the segment.  
Number of bytes in segment The number of bytes of bitmap data contained in  
this segment.  
B-30 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The entire access-control-point structure is comprised of a header, followed by one  
or more access-control-point segments. The header indicates how many segments  
are contained in the entire structure.  
The layout of this structure is illustrated in Figure B-33.  
Bytes  
Field  
┌───────┐  
──┐  
2
2
2
2
2
2
│ Number of segments  
├───────┤  
├─ Header  
│ Reserved  
──┘  
├───────┤  
──┐  
│ Start bit number  
├───────┤  
│ End bit number  
├───────┤  
│ First  
│ Number of bytes  
├─ bitmap  
├───────┤  
│ segment  
│ Reserved  
├───────┴──────────────────────────── ─ ─────────────┐  
variable│ │ Bitmap data  
├───────┬──────────────────────────── ─ ─────────────┘  
─┘  
.
.
.
.
.
.
├───────┤  
──┐  
2
2
2
2
│ Start bit number  
├───────┤  
│ End bit number  
├───────┤  
│ Last  
│ Number of bytes  
├─ bitmap  
├───────┤  
│ segment  
│ Reserved  
├───────┴──────────────────────────── ─ ─────────────┐  
variable│ │ Bitmap data  
└──────────────────────────────────── ─ ─────────────┘  
─┘  
Figure B-33. Access-Control-Point Structure  
Default Role Contents  
The default role will have the following characteristics.  
The role ID will be DEFAULT.  
The required authentication strength level will be zero.  
The role will be valid at all times and on all days of the week.  
The only functions that will be permitted are those related to access-control  
initialization. This will guarantee that the owner will initialize the Coprocessor  
before any useful cryptographic work can be done. This requirement prevents  
security “accidents” in which unrestricted default authority might accidentally be  
left intact when the system is put into service.  
The access-control points that are enabled in the default role are shown in  
Figure B-34.  
Figure B-34 (Page 1 of 2). Functions Permitted in Default Role  
Code  
Function Name  
X'0107'  
X'0110'  
X'0111'  
X'0112'  
PKA96 One Way Hash  
Set Clock  
Reinitialize Device  
Initialize access-control system roles and profiles  
Appendix B. Data Structures B-31  
CCA Release 2.54  
Figure B-34 (Page 2 of 2). Functions Permitted in Default Role  
Code  
Function Name  
X'0113'  
X'0114'  
Change the expiration date in a user profile  
Change the authentication data (for example, passphrase) in a user  
profile  
X'0115'  
X'0116'  
X'0117'  
X'0118'  
Reset the logon failure count in a user profile  
Read public access-control information  
Delete a user profile  
Delete a role  
Profile Structure  
This section describes the data structures related to user profiles.  
Basic Structure of a Profile  
The following figures describe how the Profile data is structured. This is the format  
used when profile data is transferred to or from the Coprocessor, using verbs  
Access_Control_Initialization or Access_Control_Maintenance.  
Bytes  
Field  
┌───────┐  
2
2
│ Profile structure version (X'ꢃ1', X'ꢃꢃ')  
├───────┤  
│ Profile length  
├───────┴──────────────────────────── ─ ───────────┐  
2ꢃ  
2
│ Comment  
├───────┬──────────────────────────── ─ ───────────┘  
│ Checksum  
├───┬───┘  
1
Logon failure count  
Reserved  
├───┤  
1
├───┴───────────────────────────┐  
8
│ User ID  
├───────────────────────────────┤  
8
│ Role ID  
├───────┬───┬───┬───────────────┘  
4
│ Activation date (see format below)  
├───────┼───┼───┤  
│ Expiration date (see format below)  
├───────┴───┴───┴──────────────────── ─ ───────────┐  
│ Authentication data  
└──────────────────────────────────── ─ ───────────┘  
4
variable │  
Figure B-35. Profile Layout  
Bytes  
Field  
┌───────┐  
2
1
1
│ Year (big-endian format)  
├───┬───┘  
Month (1-12)  
Day (1-31)  
├───┤  
└───┘  
Figure B-36. Layout of Profile Activation and Expiration Dates  
When a new profile is loaded, the host application does not provide the Logon  
failure count value. This field is automatically set to zero when the profile is stored  
in the Coprocessor. The failure count field should have a value of zero in the  
initialization data you send with Access_Control_Initialization.  
B-32 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The checksum is defined as the exclusive-OR (XOR) of each byte in the profile  
structure. The high-order byte of the checksum field is set to zero (X'00'), and the  
exclusive-OR result is put in the low-order byte.  
Note: The checksum value is not used in the current profile structure. It may be  
verified by the Cryptographic Coprocessor with a future version of the profile  
structure.  
Aggregate Profile Structure  
For initialization, a set of zero (or more interestingly, one) profile definitions are sent  
to the Coprocessor together, in a single data structure. This structure consists of a  
header, followed by one or more profile structures as defined in “Profile Structure”  
on page B-32.  
The header defines the number of profiles which follow in the rest of the structure.  
Its layout is shown in Figure B-37, with three concatenated profile structures shown  
for illustration.  
Bytes  
Field  
┌───────┐  
4
4
│ Number of profiles in aggregate structure  
├───────┤  
│ Reserved  
├───────┴───────────────────────────────────────┐  
variable│  
│ First profile  
├─────────────────────────────────┬─────────────┘  
variable│ │ Second profile  
├─────────────────────────────────┴──────┐  
variable│ │ Third profile  
└────────────────────────────────────────┘  
Figure B-37. Aggregate Profile Structure with Header  
Authentication Data Structure  
This section describes the authentication data, which is part of each user profile.  
Authentication data is the information the Coprocessor uses to verify your identity  
when you log on.  
There are two versions of the authentication data structure, corresponding to  
profiles versions 1.0 and 1.1. The only difference is in the meaning of the length  
field, as described below.  
General Structure of Authentication Data: The Authentication Data field is a  
series of one or more Authentication Data structures, each containing the data and  
parameters for a single authentication method. The field begins with a header,  
which contains two data elements.  
Length  
A two-byte integer value defining how many bytes of authentication  
information are in the structure. For profile structure version 1.0, the  
Length includes all bytes after the Length field itself. For profile  
structure version 1.1, the Length includes all bytes after the header,  
where the header includes both the Length field and the Field Type  
Identifier field.  
Field Type Identifier A two-byte integer value which identifies the type of data  
following the header. The identifier must be set to the integer value  
X'0001', which indicates that the data is of type “Authentication Data.”  
Appendix B. Data Structures B-33  
CCA Release 2.54  
The header is followed by individual sets of authentication data, each containing the  
data for one authentication mechanism. This layout is shown pictorially in  
Figure B-38 on page B-34.  
Figure B-38. Layout of the Authentication Data Field  
The content of the individual Authentication Data structures is shown in  
Figure B-39 below.  
B-34 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-39 (Page 1 of 2). Authentication Data for Each Authentication Mechanism  
Field name  
Length  
(bytes)  
Description  
Length  
2
The size of this set of authentication mechanism data, in  
bytes. The length field includes all bytes of mechanism data  
following the length field itself.  
Mechanism ID  
2
An identifier which describes the authentication mechanism  
associated with this set of data. For example, there might be  
identifiers for passphrase, PIN, fingerprint, public-key based  
identification, and others. This is an integer value.  
For passphrase authentication, the mechanism ID is the  
integer value X'0001'.  
Mechanism  
Strength  
2
4
An integer value which defines the strength of this  
identification mechanism, relative to all others. Higher values  
reflect greater strength. A value of zero is reserved for users  
who have not been authenticated in any way.  
Expiration  
Date  
The last date on which this authentication data may be used  
to identify the user. The field contains the month, day, and  
year of expiration. All four digits of the year are stored, so  
that no problems occur at the turn of the century.  
The expiration date is a four-byte structure, as shown in the  
C type definition below.  
typedef struct {  
unsigned char exp_year[2];  
unsigned char exp_month;  
unsigned char exp_day;  
} expiration_date_t;  
The two-byte exp_year is in big-endian format. The  
high-order byte is at the lower numbered address.  
Mechanism  
Attributes  
4
This field contains flags and attributes needed to fully  
describe the operation and use of the authentication  
mechanism. One flag is defined for all methods:  
Renewable A Boolean value which indicates whether the  
user is permitted to renew the authentication  
data. If this value is True (1), the user can  
renew the data by authenticating, and then  
providing new authentication data. For example,  
to replace a passphrase, the user would first log  
on using his or her passphrase. Then, the  
passphrase would be changed by providing the  
new passphrase authentication data using the  
Access_Control_Initialization verb with the  
CHG-AD rule-array keyword. The format of the  
passphrase authentication data is described  
immediately below under ‘mechanism data’.  
The Renewable bit is the most-significant bit (MSB) in the  
four-byte attributes field. The other 31 bits are unused, and  
must be set to zero.  
Appendix B. Data Structures B-35  
CCA Release 2.54  
Figure B-39 (Page 2 of 2). Authentication Data for Each Authentication Mechanism  
Field name  
Length  
(bytes)  
Description  
Mechanism  
data  
variable  
This field contains the data needed to perform the  
authentication. The size, content, and complexity of this data  
will vary according to the authentication mechanism. For  
example, the content could be as simple as a password that  
is compared to one entered by the user, or it could be as  
complex as a set of sophisticated biometric reference data,  
or a public key certificate.  
Authentication Data for Passphrase Authentication: For passphrase  
authentication, the mechanism data field contains the 20-byte SHA-1 hash of the  
user's passphrase. The hash is computed in the host, where it is used to construct  
the profile that is downloaded to the Coprocessor.  
Examples of the Data Structures  
Passphrase authentication data  
Figure B-40 shows the contents of a sample authentication mechanism data  
structure for a passphrase.  
ꢃꢃ 2ꢃ ꢃꢃ ꢃ1 ꢃ1 8ꢃ ꢃ7 ce ꢃ6 ꢃ1 8ꢃ ꢃꢃ ꢃꢃ ꢃꢃ fb f5  
c4 84 75 5f ba 59 6b ca 4a 9d ca ꢃ8 fb 52 9e e2  
45 41  
. ..............  
..u_.Yk.J....R..  
EA  
Figure B-40. Passphrase Authentication Data Structure  
This data breaks down into the following fields.  
00 20  
The length of the authentication mechanism data, excluding the length  
field itself. (32 bytes)  
00 01  
01 80  
07 CE  
The mechanism identifier, for Passphrase Authentication Data.  
The mechanism strength. Hex 0180, or decimal 384.  
The year of the passphrase expiration date. Hex 07CE, or decimal  
1998.  
06 01  
The month and day of the passphrase expiration date. This represents  
June 1.  
80 00 00 00 The mechanism attributes. The Renewable bit is set.  
FB F5 C4 84 75 5F BA 59 6B CA 4A 9D CA 08 FB 52 9E E2 45 41 The  
authentication data. This 20-byte value is the SHA-1 hash of the user's  
passphrase. In this case, the passphrase is  
This is my passphrase.  
User Profile  
Figure B-41 on page B-37 shows the contents of an entire user profile, containing  
the passphrase data shown above.  
B-36 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
ꢃ1 ꢃꢃ ꢃꢃ 5a 2d 2ꢃ 53 61 6d 7ꢃ 6c 65 2ꢃ 5ꢃ 72 6f  
66 69 6c 65 2ꢃ 31 2ꢃ 2d ab cd ꢃꢃ ꢃꢃ 4a 5f 53 6d  
69 74 68 2ꢃ 41 44 4d 49 4e 31 2ꢃ 2ꢃ ꢃ7 cd ꢃ6 ꢃ1  
ꢃ7 cd ꢃc 1f ꢃꢃ 24 ꢃꢃ ꢃ1 ꢃꢃ 2ꢃ ꢃꢃ ꢃ1 ꢃ1 8ꢃ ꢃ7 ce  
ꢃ6 ꢃ1 8ꢃ ꢃꢃ ꢃꢃ ꢃꢃ fb f5 c4 84 75 5f ba 59 6b ca  
4a 9d ca ꢃ8 fb 52 9e e2 45 41  
...Z- Sample Pro  
file 1 -....J_Sm  
ith ADMIN1 ....  
....."... ......  
..........u_.Yk.  
J....R..EA  
Figure B-41. User Profile Data Structure  
This user profile contains the following fields.  
01 00  
The profile structure version number. For a version 1.1 profile structure,  
this would have the value 01 01.  
00 5A  
The length of the profile, including the length field itself. Hex 5A is  
equal to decimal 90.  
“- Sample Profile 1 -” The 20 character comment for this user profile.  
AB CD  
The checksum for the user profile.  
Note: The checksum value is not used. In future versions of the profile  
structure, the checksum may be verified in the Cryptographic  
Coprocessor.  
00  
00  
The logon failure count.  
Reserved field, which must be zero.  
“J_Smith ” The user ID for this profile.  
“ADMIN1 ” The role that will define the authority associated with this profile.  
07 CD  
06 01  
07 CD  
0C 1F  
The year of the profile's activation date. Hex 07CD is equal to decimal  
1997.  
The month and day of the profile's activation date. This represents June  
1.  
The year of the profile's expiration date. Hex 07CD is equal to decimal  
1997.  
the month and day of the profile's expiration date. Hex 0C is equal to  
decimal 12, and hex 1F is equal to decimal 31, so the profile expires on  
December 31.  
00 22  
00 01  
The total length of all the authentication data for this profile, not  
including the length of this field itself.  
The field type identifier, indicating that the following data is  
Authentication Data.  
Passphrase data The remainder of the field is the passphrase data structure, as  
described above.  
Aggregate Profile Structure  
Figure B-42 on page B-38 shows the aggregate profile structure, containing one  
user profile. This is the structure that is passed to the CSUAACI verb in order to  
load one or more user profiles.  
Appendix B. Data Structures B-37  
CCA Release 2.54  
ꢃꢃ ꢃꢃ ꢃꢃ ꢃ1 ꢃꢃ ꢃꢃ ꢃꢃ ꢃꢃ ꢃ1 ꢃꢃ ꢃꢃ 5a 2d 2ꢃ 53 61  
6d 7ꢃ 6c 65 2ꢃ 5ꢃ 72 6f 66 69 6c 65 2ꢃ 31 2ꢃ 2d  
ab cd ꢃꢃ ꢃꢃ 4a 5f 53 6d 69 74 68 2ꢃ 41 44 4d 49  
4e 31 2ꢃ 2ꢃ ꢃ7 cd ꢃ6 ꢃ1 ꢃ7 cd ꢃc 1f ꢃꢃ 24 ꢃꢃ ꢃ1  
ꢃꢃ 2ꢃ ꢃꢃ ꢃ1 ꢃ1 8ꢃ ꢃ7 ce ꢃ6 ꢃ1 8ꢃ ꢃꢃ ꢃꢃ ꢃꢃ fb f5  
c4 84 75 5f ba 59 6b ca 4a 9d ca ꢃ8 fb 52 9e e2  
45 41  
...........Z- Sa  
mple Profile 1 -  
....J_Smith ADMI  
N1 ........."..  
. ..............  
..u_.Yk.J....R..  
EA  
Figure B-42. Aggregate Profile Structure  
This structure contains the following data fields.  
00 00 00 01 The number of profiles that are in the aggregate structure. This  
example contains only one user profile, but any number can be included  
in the same aggregate structure.  
00 00 00 00 A reserved field, which must contain zeros.  
User profile The remainder of this structure contains the single user profile that  
was described earlier in this section.  
Access-Control-Point List  
Figure B-43 shows the contents of a sample Access-Control-Point List.  
ꢃꢃ ꢃ2 ꢃꢃ ꢃꢃ ꢃꢃ ꢃꢃ ꢃ1 17 ꢃꢃ 23 ꢃꢃ ꢃꢃ fꢃ ff ff ff  
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ꢃ2  
ꢃꢃ ꢃ2 17 ꢃꢃ ꢃ3 ꢃꢃ ꢃꢃ 8f 99 fe  
.........#......  
................  
................  
..........  
Figure B-43. Access-Control-Point List  
The Access-Control-Point list contains the following data fields.  
00 02  
The number of segments of data in the access-control-point list. In this  
list, there are two discontiguous segments of access-control points. One  
starts at access-control point 0, and the other starts at access-control  
point X'200'.  
00 00  
00 00  
01 17  
A reserved field, which must be filled with zeros.  
The number of the first access-control point in this segment.  
The number of the last access-control point in this segment. The  
segment starts at access-control point 0, and ends with access control  
point X'117', which is decimal 279.  
00 23  
00 00  
The number of bytes of data in the access-control points for this  
segment. There are X'23' bytes, which is 35 decimal.  
A reserved field, which must be filled with zeros.  
F0 FF FF FF ... FF FF (35 bytes) This is the first set of access-control points, with  
one bit corresponding to each point. Thus, the first byte contains bits  
0-7, the next byte contains 8-15, and so on.  
02 00  
02 17  
The number of the first access-control point in the second segment.  
The number of the last access-control point in this segment. The  
segment starts at access-control point X'200' (decimal 512), and ends  
with access-control point X'217' (decimal 535).  
B-38 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
00 03  
00 00  
The number of bytes of data in the access-control points for this  
segment. There are 3 bytes, for the access-control points from 512  
through 535.  
A reserved field, which must be filled with zeros.  
8F 99 FE This is the second set of access-control points, with one bit  
corresponding to each point. Thus, the first byte contains bits 512-519,  
the second byte contains 520-527, and the third byte contains 528-535.  
Role Data Structure  
Figure B-44 shows the contents of a role data structure.  
ꢃ1 ꢃꢃ ꢃꢃ 62 2a 4e 65 77 2ꢃ 64 65 66 61 75 6c 74  
2ꢃ 72 6f 6c 65 2ꢃ 31 2a ab cd ꢃꢃ ꢃꢃ 44 45 46 41  
55 4c 54 2ꢃ 23 45 ꢃ1 ꢃf 17 1e 7c ꢃꢃ ꢃꢃ ꢃ2 ꢃꢃ ꢃꢃ  
ꢃꢃ ꢃꢃ ꢃ1 17 ꢃꢃ 23 ꢃꢃ ꢃꢃ fꢃ ff ff ff ff ff ff ff  
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  
ff ff ff ff ff ff ff ff ff ff ff ꢃ2 ꢃꢃ ꢃ2 17 8f  
99 fe  
....ᑍNew default  
role 1ᑍ....DEFA  
ULT #E....|.....  
.....#..........  
................  
................  
..  
Figure B-44. Role Data Structure  
This structure contains the following data fields.  
00 01  
00 62  
The role structure version number.  
The length of the role structure, including the length field itself.  
“*New default role 1*” The 20 character comment describing this role.  
AB CD  
The checksum for the role.  
Note: The checksum value is not used. In future versions of the role  
structure, the checksum may be verified in the Cryptographic  
Coprocessor.  
00 00  
A reserved field, which must be filled with zeros.  
“DEFAULT ” The Role ID for this role. The role in this example will replace the  
DEFAULT role.  
23 45  
01 0F  
The Required Authentication Strength field  
The lower time limit. X'01' is the hour, and X'0F' is the minute  
(decimal 15), so the lower time limit is 1:15 AM, GMT.  
17 1E  
7C  
The upper time limit. X'17' is the hour (decimal 23), and X'1E' is the  
minute (30), so the upper time limit is 23:30 GMT.  
This byte maps the valid days of the week for the role. The first bit  
represents Sunday, the second represents Monday, and so on. Hex 7C  
is binary 01111100, and enables the weekdays Monday through Friday.  
00  
This byte is a reserved field, and must be zero.  
Access-control-point list The remainder of the role structure contains the  
Access-Control-Point list described above.  
Appendix B. Data Structures B-39  
CCA Release 2.54  
Aggregate Role Data Structure  
Figure B-45 shows the an aggregate role data structure, like you would load using  
the CSUAACI verb.  
ꢃꢃ ꢃꢃ ꢃꢃ ꢃ1 ꢃꢃ ꢃꢃ ꢃꢃ ꢃꢃ ꢃ1 ꢃꢃ ꢃꢃ 62 2a 4e 65 77  
2ꢃ 64 65 66 61 75 6c 74 2ꢃ 72 6f 6c 65 2ꢃ 31 2a  
ab cd ꢃꢃ ꢃꢃ 44 45 46 41 55 4c 54 2ꢃ 23 45 ꢃ1 ꢃf  
17 1e 7c ꢃꢃ ꢃꢃ ꢃ2 ꢃꢃ ꢃꢃ ꢃꢃ ꢃꢃ ꢃ1 17 ꢃꢃ 23 ꢃꢃ ꢃꢃ  
fꢃ ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  
ff ff ff ꢃ2 ꢃꢃ ꢃ2 17 8f 99 fe  
............ᑍNew  
default role 1ᑍ  
....DEFAULT #E..  
..|..........#..  
................  
................  
..........  
Figure B-45. Aggregate Role Data Structure  
This structure contains the following data fields.  
00 00 00 01 The number of roles that are in the aggregate structure. This example  
contains only one role, but any number can be included in the same  
aggregate structure.  
00 00 00 00 A reserved field, which must contain zeros.  
Role data structure The remainder of the aggregate structure contains the role  
structure, which was described above.  
B-40 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Master Key Shares Data Formats  
Master key shares, and potentially other information to be “cloned” from one  
Coprocessor to another Coprocessor are packed into a data structure as described  
in Figure B-46.  
Figure B-46. Cloning Information Token Data Structure  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
008  
012  
028  
036  
001  
001  
002  
004  
004  
016  
008  
xxx  
X'1D', token identifier  
X'00', Version  
Length of the cloning information token  
Reserved, binary zero  
Cloning-share index number, i; 1i15  
Origin-node Environment Identifier, EID  
Origin-Coprocessor serial number  
Cloning information TLV's:  
Master key share  
Signature  
And one to seven bytes of padding to ensure that length 'xxx' is a multiple  
of eight bytes.  
Note: The information from offset 036 through 035+xxx is triple encrypted with a triple-length DES  
key using the EDE3 encryption process, see “Triple-DES Ciphering Algorithms” on page D-10.  
Figure B-47. Master Key Share TLV  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
005  
001  
001  
002  
001  
024  
X'01', master key share identifier  
X'00', Version  
X'001D', length of the TLV  
Index value, i, binary  
Master-key share  
Figure B-48. Cloning Information Signature TLV  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
001  
002  
004  
001  
001  
002  
001  
X'45', Signature Subsection Header  
X'00', Version  
Subsection length, 70+sss  
Hashing algorithm identifier; X'01' signifies use of the SHA-1 hashing  
algorithm.  
005  
006  
001  
064  
Signature formatting identifier; X'01' signifies use of the ISO-9796 process.  
Signature-key identifier; the key label of the key used to generate the  
signature.  
070  
sss  
The signature field.  
The signature is calculated on data that begins with the Cloning Information  
Token Data Structure identifier (X'1D') through the byte immediately  
preceding this signature field.  
Appendix B. Data Structures B-41  
CCA Release 2.54  
Function Control Vector  
The export (distribution) of cryptographic implementations by USA companies is  
controlled under USA Government export regulations. An IBM 4758 becomes a  
practical cryptographic engine when it accepts and validates digitally signed  
software. IBM has chosen to export the IBM 4758 as a non-cryptographic product,  
and to control and report the export of the cryptography-enabling software.  
The CCA software that can be loaded into the Coprocessor limits the functionality  
of the Coprocessor based on the values in a function control vector (FCV). At the  
present time, two capabilities are controlled:  
The length of keys used with the DES algorithm for general data encryption  
The length of an RSA key used to encipher DES keys.  
Notes:  
1. Government policies and the FCV do not limit the key-length of keys used in  
digital signature operations.  
2. The SET services can employ 56-bit DES for data encryption, and 1024-bit  
RSA key-lengths when distributing DES keys.  
IBM distributes the FCV in a digitally signed data structure. Figure B-49 shows the  
format of the data structure that contains the function control vector as distributed  
by IBM.  
Figure B-49 (Page 1 of 2). FCV Distribution Structure  
Offset  
Length  
Meaning  
Decimal Decimal  
(Hex)  
000  
(000)  
390  
080  
204  
Package header and validating-key certificate  
Descriptive text coded in ASCII  
390  
(186)  
470  
Function control vector (FCV)  
(1D6)  
This is the information that you supply to the Coprocessor using the  
Cryptographic_Facility_Control verb. It consists of the FCV information and  
signature that is validated by the CCA code within the Coprocessor.  
674  
128  
Digital signature on the complete structure (excepting this signature itself).  
(2A2)  
B-42 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure B-49 (Page 2 of 2). FCV Distribution Structure  
Offset  
Length  
Meaning  
Decimal Decimal  
(Hex)  
FCV Supplied to Coprocessor (offset 470 above)  
470  
(1D6)  
1
1
2
4
4
1
1
1
Record ID, X'06'  
471  
(1D7)  
Version, X'00'  
472  
(1D8)  
Padding, X'0000'  
474  
(1DA)  
FCV record structure length, X'CC', little endian  
Signature rules, X'FF00 0000'  
FCV format version, X'00'  
CCA services class, X'01', Basic  
478  
(1DE)  
482  
(1E2)  
483  
(1E3)  
484  
X'01', CDMF only  
(1E4)  
X'03', CDMF and 56-bit DES  
X'07', CDMF, 56-bit DES, Triple-DES  
485  
(1E5)  
1
4
2
SET services, X'01', CSNDSBD and CSNDSBC with 56-bit DES and  
1024-bit RSA key length permitted  
486  
(1E6)  
Reserved, X'0000 0000'  
490  
(1EA)  
Maximum modulus length for symmetric encryption, little endian  
X'0004' is 1024 bits  
X'0002' is 512 bits  
492  
54  
Reserved, X'00 ...00'  
(1EC)  
546  
128  
Signature validated by the Coprocessor (using key FcvPuK)  
(222)  
Components of the FCV (offset 470 above)  
Appendix B. Data Structures B-43  
CCA Release 2.54  
B-44 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix C. CCA Control-Vector Definitions and Key  
Encryption  
This appendix describes the following:  
DES control-vector values1  
Specifying a control-vector-base value  
Changing control vectors  
CCA key encryption and decryption processes.  
In the Common Cryptographic Architecture (CCA), a control vector is a non-secret  
quantity that expresses permissible usages for an associated key. When a CCA  
DES key is encrypted, the key-encrypting key is exclusive-ORed with the control  
vector to form the actual key used in the DES key-encrypting process. This  
technique allows the generator or introducer of a key to specify how the key is to  
be distributed and used. Attacks can be mounted against a cryptographic system  
when it is possible to use a key for other than its intended purpose. The CCA  
control-vector key-typing scheme and the command authorization and control-vector  
checking performed by a CCA node together provide an important defense against  
misuse of keys and related attacks.  
DES Control-Vector Values  
The CCA key token includes the control vector and the encrypted key that the  
control vector describes. The control vector is as long as the key, either 64 or 128  
bits in length. The control vector is “coupled” to the key because it modifies the  
key-encrypting key value used to encrypt the key found in the key token. See  
“CCA DES Key Encryption and Decryption Processes” on page C-12.  
Although the CCA architecture permits several advanced techniques, the product  
implementations described in this book use the same control-vector value for the  
second half of a double-length key as for the first half...except for the reversal of  
two bits. Therefore, this discussion of control-vector values focuses on a 64-bit  
vector with the understanding that, for a double-length key, the control-vector value  
associated with each key half is essentially the same.  
Bits 8 to 14, and sometimes bits 18 to 22 of a control vector define the key as  
belonging to one of several general classes of keys as shown in Figure C-1.  
1
In this appendix, control vector means DES control vector base unless noted otherwise.  
Copyright IBM Corp. 1997, 2005  
C-1  
CCA Release 2.54  
Figure C-1. Key Classes  
Key Type  
Key Usage  
Key-Encrypting Keys  
IMPORTER  
Used to decrypt a key brought to this local node  
Used to encrypt a key taken from this local node  
EXPORTER  
IKEYXLAT  
Used to decrypt an input key in the Key_Translate service  
Used to encrypt an output key in the Key_Translate service  
OKEYXLAT  
Data operation keys  
CIPHER,  
Used only to encrypt or decrypt data  
DECIPHER,  
ENCIPHER  
DATA  
Used to encrypt or decrypt data, or to generate or verify a MAC  
DATAC  
Used to specify a DATA-class key that will perform in the Encipher  
and Decipher verbs, but not in the MAC_Generate and  
MAC_Verify verbs.  
DATAM  
Used to specify a DATA-class key that will perform in the  
MAC_Generate and MAC_Verify verbs, but not in the Encipher  
and Decipher verbs.  
DATAMV  
Used to specify a DATA-class key that will perform in the  
MAC_Verify verb, but not in the MAC_Generate, Encipher, or  
Decipher verbs.  
MAC  
Used to generate or verify a MAC  
MACVER  
SECMSG  
PIN-processing keys  
IPINENC  
Used to verify a MAC code (cannot be used in MAC-generation)  
Used to encrypt keys or PINs in a secure message  
Used to decrypt a PIN block  
OPINENC  
PINGEN  
Used to encrypt a PIN block  
Used to generate and verify PIN values  
Used to verify, but not generate, PIN values  
PINVER  
Special cryptographic-variable encrypting keys  
CVARENC  
Used to encrypt the mask arrays in the  
Cryptographic_Variable_Encipher verb for the  
Control_Vector_Translate verb  
CVARXCVL and  
CVARXCVR  
Used to encrypt special control values in the  
Cryptographic_Variable_Encipher verb for use with the  
Control_Vector_Translate verb  
Key-generating keys  
DKYGENKY  
Used to generate a key based on a key-generating key  
Used to generate or derive other keys.  
KEYGENKY  
Usually there is a default control-vector associated with each of the key types just  
listed; see Figure C-2 on page C-3. The bits in positions 16-22 and 33-37  
generally have different meanings for every key class. Many of the remaining bits  
in a control vector have a common meaning. Most of the DES key-management  
services permit you to use the default control-vector value by naming the key class  
in the service's key-type variable. This does not apply to all key-type classes.  
C-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
You can use the default control-vector for a key type, or you can create a more  
restrictive control-vector. The default control-vector for a key type provides basic  
key-separation functions. Optional usage restrictions can further tighten the  
security of the system.  
The cryptographic subsystem creates a default control vector for a key type when  
you use the Key_Generate verb and specify a null key token and a key-type in the  
key_type parameter. Also, when you import or export a key, you can specify a key  
type to obtain a default control-vector instead of supplying a control vector in a key  
token. If you specify a key type with the Key_Import verb, ensure that the default  
control-vector is the same as the control vector that was used to encrypt the key.  
The additional control-vector bits that you can turn on or off permit you to further  
restrict the use of a key. This gives you the ability to implement the general  
security policy of permitting only those capabilities actually required in a system.  
The additional bits are designed to block specific attacks although these attacks are  
often obscure.  
You can obtain the value for a control vector in one of several ways:  
To use a default-value control vector, obtain the value from Figure C-2.  
See “Specifying a Control-Vector-Base Value” on page C-7. The material  
presents an ordered set of questions to enable you to create the value for a  
control vector.  
Use the Key_Token_Build verb or the Control_Vector_Generate verb and  
keywords to construct a control vector and incorporate this control vector into a  
key token. See Figure 5-4 on page 5-9.  
Figure C-2 (Page 1 of 2). Key Type Default Control-Vector Values  
Control Vector  
Hexadecimal Value for  
Single-length Key or Left Half  
of Double-Length Key  
Control Vector  
Hexadecimal Value for Right  
Half of Double-Length Key  
Key Type  
CIPHER  
00 03 71 00 03 00 00 00  
DATA  
(single-length)  
(Internal)  
(External)  
00 00 7D 00 03 00 00 00  
00 00 00 00 00 00 00 00  
DATA  
(double-length)  
(Internal)  
(External)  
00 00 7D 00 03 41 00 00  
00 00 00 00 00 00 00 00  
00 00 7D 00 03 21 00 00  
00 00 00 00 00 00 00 00  
DATAC  
00 00 71 00 03 41 00 00  
00 00 4D 00 03 41 00 00  
00 00 44 00 03 41 00 00  
00 03 50 00 03 00 00 00  
00 71 44 00 03 41 00 00  
00 03 60 00 03 00 00 00  
00 00 71 00 03 21 00 00  
00 00 4D 00 03 21 00 00  
00 00 44 00 03 21 00 00  
DATAM  
DATAMV  
DECIPHER  
DKYGENKY  
ENCIPHER  
00 71 44 00 03 21 00 00  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-3  
CCA Release 2.54  
Figure C-2 (Page 2 of 2). Key Type Default Control-Vector Values  
Control Vector  
Hexadecimal Value for  
Single-length Key or Left Half  
of Double-Length Key  
Control Vector  
Hexadecimal Value for Right  
Half of Double-Length Key  
Key Type  
EXPORTER  
IKEYXLAT  
IMPORTER  
IPINENC  
00 41 7D 00 03 41 00 00  
00 42 42 00 03 41 00 00  
00 42 7D 00 03 41 00 00  
00 21 5F 00 03 41 00 00  
00 41 7D 00 03 21 00 00  
00 42 42 00 03 21 00 00  
00 42 7D 00 03 21 00 00  
00 21 5F 00 03 21 00 00  
MAC  
single-length  
double-length  
00 05 4D 00 03 00 00 00  
00 05 4D 00 03 41 00 00  
00 05 4D 00 03 21 00 00  
MACVER  
single-length  
double-length  
00 05 44 00 03 00 00 00  
00 05 44 00 03 41 00 00  
00 05 44 00 03 21 00 00  
00 41 42 00 03 21 00 00  
00 24 77 00 03 21 00 00  
00 22 7E 00 03 21 00 00  
00 22 42 00 03 21 00 00  
OKEYXLAT  
OPINENC  
PINGEN  
00 41 42 00 03 41 00 00  
00 24 77 00 03 41 00 00  
00 22 7E 00 03 41 00 00  
00 22 42 00 03 41 00 00  
PINVER  
C-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Control─Vector─Base Bits  
│ꢃ ꢃ ꢃ ꢃ │ꢃ 1 1 1 │1 1 2 2 │2 2 2 3 │3 3 3 3 │4 4 4 4 │4 5 5 5 │5 5 6 6 │  
│ꢃ 2 4 6 │8 ꢃ 2 4 │6 8 ꢃ 2 │4 6 8 ꢃ │2 4 6 8 │ꢃ 2 4 6 │8 ꢃ 2 4 │6 8 ꢃ 2 │  
│ꢂ  
ꢂ│  
│└─Most Significant Bit  
│ Least Significant Bit─┘│  
│Common Bits  
┌────────┬────Anti─Variant Bits  
│ │  
│ │  
│....uu.P│.......P│.E.....P│......ꢃP│......1P│fff.K..P│.......P│.....u.P│  
││ ││  
││ ││  
│ │  
│─┬─ │ │  
│ │  
│ │  
│ │  
│ │  
│ └E=XPORT─OK  
│ │ └K=KEY─PART │  
││ └P=Even Parity  
│ └─Key─Form  
││ │  
│└u5──UDX5 │  
└─u4──UDX4 │  
│ NOT-CCA─u61─┘ │  
│Key─Encrypting Keys  
│ ┌g=IMEX  
│ │┌k=OPEX  
│ ││┌s=EXEX  
│ │││┌i=EXPORT │  
│ ││││┌x=XLATE │  
│EXPORTER│  
│ │││││ │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃ1ꢃꢃꢃꢃꢃ1│ꢃEgksixP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│OKEYXLAT│  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃ1ꢃꢃꢃꢃꢃ1│ꢃEꢃꢃꢃꢃ1P│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│IKEYXLAT│  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃ1ꢃꢃꢃꢃ1ꢃ│ꢃEꢃꢃꢃꢃ1P│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│IMPORTER│  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃ1ꢃꢃꢃꢃ1ꢃ│ꢃEgksixP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ │││││ │  
│ ││││└x=XLATE │  
│ │││└i=IMPORT │  
│ ││└s=IMIM  
│ │└k=OPIM  
│ └g=IMEX  
│Data Operation Keys  
│DATA  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃEedmvꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│DATAC │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃE11ꢃꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│DATAM │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃEꢃꢃ11ꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│DATAMV │ │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃEꢃꢃꢃ1ꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│CIPHER │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│ꢃE11ꢃꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│DECIPHER│  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│ꢃEꢃ1ꢃꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ENCIPHER│ │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│ꢃE1ꢃꢃꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│MAC  
│ccccuuꢃꢃ│ꢃꢃꢃꢃꢃ1ꢃ1│ꢃEꢃꢃ11ꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│MACVER │  
│ccccuuꢃꢃ│ꢃꢃꢃꢃꢃ1ꢃ1│ꢃEꢃꢃꢃ1ꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│─┬──  
│ ├─ꢃꢃꢃꢃ ANY─MAC │  
│ ├─ꢃꢃꢃ1 ANSIX9.9 │  
│ ├─ꢃꢃ1ꢃ CVVKEY─A │  
│ ├─ꢃꢃ11 CVVKEY─B │  
│ └─ꢃ1ꢃꢃ AMEX─CSC │  
Figure C-3 (Part 1 of 2). Control-Vector-Base Bit Map  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-5  
CCA Release 2.54  
Control─Vector─Base Bits  
│ꢃ ꢃ ꢃ ꢃ │ꢃ 1 1 1 │1 1 2 2 │2 2 2 3 │3 3 3 3 │4 4 4 4 │4 5 5 5 │5 5 6 6 │  
│ꢃ 2 4 6 │8 ꢃ 2 4 │6 8 ꢃ 2 │4 6 8 ꢃ │2 4 6 8 │ꢃ 2 4 6 │8 ꢃ 2 4 │6 8 ꢃ 2 │  
│SECMSG │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃꢃꢃ1ꢃ1ꢃ│ꢃEkpꢃꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ │└─SMPIN  
│ └──SMKEY  
│PIN Processing Keys  
│ꢃꢃꢃꢃ NO─SPEC  
│ Prohibit offset:  
│ NOOFFSET───┐ │  
│ꢃꢃꢃ1 IBM─PIN/IBM─PINO  
│ꢃꢃ1ꢃ VISA─PVV  
│ꢃꢃ11 INBK─PIN  
│ │  
│ │  
│ │  
│ │  
│ │  
│ │  
│ꢃ1ꢃꢃ GBP─PIN/GBP─PINO  
│ꢃ1ꢃ1 NL─PIN─1  
│─┬──  
│ ꢄ PINGEN  
│aaaauuꢃP│ꢃꢃ1ꢃꢃꢃ1ꢃ│ꢃE.....P│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃo1P│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│─┬──  
│ │  
│CPINGEN────┘││││ │  
│EPINGENA────┘│││ │  
│EPINGEN──────┘││ │  
│CPINGENA──────┘│ │  
│EPINVER────────┤ │  
│ │  
│ │  
│ │  
│ │  
│ │  
│ │  
│ │  
│ │  
│ │  
│ ꢄ PINVER  
│ │  
│aaaauuꢃP│ꢃꢃ1ꢃꢃꢃ1ꢃ│ꢃEꢃꢃꢃꢃ1P│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃo1P│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ ┌─────EPINVER │  
│ │┌────CPINGENA│  
│IPINENC │  
│ ││ │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃ1ꢃꢃꢃꢃ1│ꢃEꢃ..trP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
││ │  
││ │  
│OPINENC │  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃ1ꢃꢃ1ꢃꢃ│ꢃE..ꢃtrP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ ││ ││ │  
│ CPINENC─┘│ │└──REFORMAT│  
│ EPINGEN──┘ └───TRANSLAT│  
│Cryptographic Variable─Encrypting Keys  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃꢃ111111│ꢃEvvvvvP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│fffꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ ──┬── │  
├─────ꢃꢃꢃꢃꢃ CVARPINE │  
├─────ꢃꢃꢃꢃ1 CVARDEC │  
├─────ꢃꢃꢃ1ꢃ CVARXCVL │  
├─────ꢃꢃꢃ11 CVARXCVR │  
└─────ꢃꢃ1ꢃꢃ CVARENC │  
│Key─Generating Keys  
│KEYGENKY│  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃ1ꢃ1ꢃꢃ11│ꢃE..ꢃꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
│ │└─CLR8─ENC  
│ └──UKPT  
│DKYGENKY│  
│ꢃꢃꢃꢃuuꢃꢃ│ꢃ111sssP│ꢃEꢃvvvvP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃꢃ11│FFFꢃKꢃꢃP│ꢃꢃꢃꢃꢃꢃꢃꢃ│ꢃꢃꢃꢃꢃuꢃꢃ│  
─┬─ │ ─┬── │  
├──ꢃꢃꢃ1 DDATA│  
├──ꢃꢃ1ꢃ DMAC │  
├──ꢃꢃ11 DMV │  
├──ꢃ1ꢃꢃ DIMP │  
├──ꢃ1ꢃ1 DEXP │  
├──ꢃ11ꢃ DPVR │  
├──1ꢃꢃꢃ DMKEY│  
├──1ꢃꢃ1 DMPIN│  
└──1111 DALL │  
│ DKYLꢃ ꢃꢃꢃ──┤ │  
│ DKYL1 ꢃꢃ1──┤ │  
│ DKYL2 ꢃ1ꢃ──┤ │  
│ DKYL3 ꢃ11──┤ │  
│ DKYL4 1ꢃꢃ──┤ │  
│ DKYL5 1ꢃ1──┤ │  
│ DKYL6 11ꢃ──┤ │  
│ DKYL7 111──┘ │  
Figure C-3 (Part 2 of 2). Control-Vector-Base Bit Map  
C-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Key-Form Bits, ‘fff’ and ‘FFF’  
The key-form bits, 40-42...and for a double-length key, bits 104-106...are  
designated ‘fff’ and ‘FFF’ in the preceding diagram. These bits can have these  
values:  
000  
010  
001  
Single-length key (only ‘fff’, not ‘FFF’)  
Double-length key, left half  
Double-length key, right half  
And these values in some CCA implementations although not created in the IBM  
4758 implementation:  
110  
101  
Double-length key, left half, halves guaranteed unique  
Double-length key, right half, halves guaranteed unique  
Specifying a Control-Vector-Base Value  
You can determine the value of a control vector by working through the following  
series of questions:  
1. Begin with a field of 64 bits (eight bytes) set to B'0'. The most significant bit  
is referred to as bit 0. Define the key type and subtype (bits 8 to 14), as  
follows:  
The main key type bits (bits 8 to 11). Set bits 8 to 11 to one of the  
following values:  
Bits 8 to 11  
0000  
Main Key Type  
Data operation keys, SECMSG secure messaging keys  
PIN keys  
0010  
0011  
Cryptographic variable-encrypting keys  
Key-encrypting keys  
0100  
0101  
KEYGENKY key-generating keys  
DKYGENKY key-generating keys  
0111  
The key subtype bits (bits 12 to 14). Set bits 12 to 14 to one of the  
following values:  
Bits 12 to 14  
Key Subtype  
Data Operation Keys  
000  
001  
010  
101  
Compatibility key (DATA)  
Confidentiality key (CIPHER, DECIPHER, or ENCIPHER)  
MAC key (MAC or MACVER)  
SECMSG secure messaging keys  
Key-Encrypting Keys  
000  
001  
Transport-sending keys (EXPORTER and OKEYXLAT)  
Transport-receiving keys (IMPORTER and IKEYXLAT)  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-7  
CCA Release 2.54  
Bits 12 to 14  
PIN Keys  
001  
Key Subtype  
PIN-generating key (PINGEN, PINVER)  
000  
Inbound PIN-block decrypting key (IPINENC)  
Outbound PIN-block encrypting key (OPINENC)  
010  
Key-Generating Keys  
001  
sss  
KEYGENKY key-generating keys  
DKYGENKY key-generating keys  
sss is the count minus one of the number of diversifications used to  
obtain the final, non-diversification key. See “Diversifying Keys” on  
page 5-19. (The Key_Token_Build verb can set the sss bits when  
you supply the DKYL0, ..., and DKYL7 keywords.)  
Cryptographic Variable-Encrypting Keys  
111  
Cryptographic variable-encrypting key (CVAR....)  
2. For key-encrypting keys, set the following bits:  
The Key-Encrypting Key-limiting bits, previously described as bits “hhh, bits  
35 to 37,” are not supported in any current release of the Coprocessor CCA  
support.  
The key-generating usage bits (gks, bits 18 to 20). Set the gks bits to  
B'111' to indicate that the Key_Generate verb can use the associated  
key-encrypting key to encipher generated keys when the Key_Generate  
verb is generating various key-pair key-form combinations (see the  
Key-Encrypting Keys section of Figure C-3 on page C-5). Without any of  
the gks bits set to 1, the Key_Generate verb cannot use the associated  
key-encrypting key. (The Key_Token_Build verb can set the gks bits to 1  
when you supply the OPIM, IMEX, IMIM, OPEX, and EXEX keywords.)  
The IMPORT and EXPORT bit and the XLATE bit (ix, bits 21 and 22). If  
the ‘i’ bit is set to 1, the associated key-encrypting key can be used in the  
Data_Key_Import, Key_Import, Data_Key_Export, and Key_Export verbs. If  
the ‘x’ bit is set to 1, the associated key-encrypting key can be used in the  
Key_Translate verb. The Control_Vector_Generate verb can set the ‘ix’  
bits to 1 when you supply the IMPORT, EXPORT, and XLATE keywords.  
The key-form bits (fff, bits 40 to 42). The key-form bits indicate how the  
key was generated and how the control vector participates in  
multiple-enciphering. To indicate that the parts can be the same value, set  
these bits to B'010'. For information about the value of the key-form bits  
in the right half of a control vector, see step 13 on page C-11.  
3. For the DATA-class keys (DATA, DATAC, DATM, DATAMV) set the “edmv” bits  
(bits 18 to 21) to one to respectively enable encipher, decipher,  
mac-generation, and mac-verification operations.  
4. For the cipher-class keys (CIPHER, DECIPHER, ENCIPHER, DATA, DATAC)  
set the encipher and decipher bits (bits 18 and 19). When bit 18 is set to 1,  
the key can encipher data. When bit 19 is set to 1, the key can decipher data.  
5. For MAC, MACVER, DATAM, and DATAMV keys, set the following bits:  
C-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The MAC control bits (bits 20 and 21). For a MAC generation key, set bits  
20 and 21 to B'11'. For a MAC verification key, set bits 20 and 21 to  
B'01'.  
The key-form bits (fff, bits 40 to 42). For a single-length key, set the bits to  
B'000'. For a double-length key, set the bits to B'010'.  
6. For SECMSG keys, set one or both of the following bits:  
Set the SMKEY bit (k, bit 18) to enable this key-type to operate in secure  
message services that imbed a key.  
Set the SMPIN bit (p, bit 19) to enable this key-type to operate in secure  
message services that imbed a PIN.  
“Secure message services,” verbs Secure_Messaging_for_Keys and  
Secure_Messaging_for_PINs, as used with for example EMV smart cards, are  
currently only supported in the IBM eServer iSeries release 2.50 CCA support.  
7. For PINGEN and PINVER keys, set the following bits:  
The PIN-calculation method bits (aaaa, bits 0 to 3). Set these bits to one  
of the following values:  
Bits 0  
to 3  
Calculation  
Method  
Description  
Keyword  
0000  
0001  
0010  
0100  
NO-SPEC  
A key with this control vector can be used with any  
PIN-calculation method.  
IBM-PIN or  
IBM-PINO  
A key with this control vector can be used only with the IBM  
PIN or PIN Offset calculation-method.  
VISA-PVV  
A key with this control vector can be used only with the  
VISA-PVV calculation-method.  
GBP-PIN  
or  
GBP-PINO  
A key with this control vector can be used only with the  
German Banking Pool PIN or PIN Offset  
calculation-method.  
0011  
0101  
INBK-PIN  
A key with this control vector can be used only with the  
Interbank PIN-calculation method.  
NL-PIN-1  
A key with this control vector can be used only with the  
NL-PIN-1, Netherlands PIN-calculation method.  
The prohibit-offset bit (o, bit 37) to restrict operations to the PIN value. If  
set to 1, this bit prevents operation with the IBM 3624 PIN Offset  
calculation method and the IBM German Bank Pool PIN Offset  
calculation-method.  
8. For PINGEN, IPINENC, and OPINENC keys, set bits 18 to 22 to indicate  
whether the key can be used with the following verbs; for the bit numbers, see  
Figure C-3 on page C-5:  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-9  
CCA Release 2.54  
Verb Allowed  
Bit Name  
CPINGEN  
EPINGENA  
EPINGEN  
Bit  
18  
19  
Clear_PIN_Generate  
Encrypted_PIN_Generate_Alternate  
Encrypted_PIN_Generate  
20 for PINGEN  
19 for OPINENC  
Clear_PIN_Generate_Alternate  
CPINGENA  
21 for PINGEN  
20 for IPINENC  
Encrypted_Pin_Verify  
Clear_PIN_Encrypt  
EPINVER  
CPINENC  
19  
18  
9. For the IPINENC (inbound) and OPINENC (outbound) PIN-block ciphering  
keys, do the following:  
Set the TRANSLAT bit (t, bit 21) to 1 to permit the key to be used in the  
PIN_Translate verb. The Control_Vector_Generate verb can set the  
TRANSLAT bit to 1 when you supply the TRANSLAT keyword.  
Set the REFORMAT bit (r, bit 22) to 1 to permit the key to be used in the  
PIN_Translate verb. The Control_Vector_Generate verb can set the  
REFORMAT bit and the TRANSLAT bit to 1 when you supply the  
REFORMAT keyword.  
10. For the cryptographic variable-encrypting keys (bits 18 to 22), set the  
variable-type bits (bits 18 to 22) to one of the following values:  
Bits  
Key Type  
Description  
18 to 22  
00000  
00010  
00011  
00100  
CVARPINE  
CVARXCVL  
CVARXCVR  
CVARENC  
Used in the Encrypted_PIN_Generate_Alternate verb to  
encrypt a clear PIN.  
Used in the Control_Vector_Translate verb to decrypt  
the left mask array.  
Used in the Control_Vector_Translate verb to decrypt  
the right mask array.  
Used in the Cryptographic_Variable_Encipher verb to  
encrypt an unformatted PIN.  
11. For KEYGENKY key-generating keys, set the following bits:  
Set bit 19 to 1 if the key will be used in the Diversified_Key_Generate  
(CSNBDKG) verb to generate a diversified key.  
Bit 18 is reserved for Unique Key Per Transaction (UKPT) usage.  
12. For DKYGENKY key-generating keys that are used in the TDES-ENC or  
TDES-DEC mode of the Diversified_Key_Generate (CSNBDKG) verb, set bits  
19 to 22 according to the type of final key that shall be obtained:  
C-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Bits  
Keyword  
To Obtain  
19 to 22  
0001  
0010  
0011  
0100  
0101  
0110  
1000  
1001  
1111  
DDATA  
DMAC  
DMV  
single- or double-length DATA key  
single- or double-length MAC key  
single- or double-length MACVER key  
IMPORTER key  
DIMP  
DEXP  
DPVR  
DMKEY  
DMPIN  
DALL  
EXPORTER key  
PIN verify key  
double-length SMKEY SECMSG key  
double-length SMPIN SECMSG key  
any of the above.  
13. For all keys, set the following bits:  
The export bit (E, bit 17). If set to 0, the export bit prevents a key from  
being exported. By setting this bit to 0, you can prevent the receiver of a  
key from exporting or translating the key for use in another cryptographic  
subsystem. Once this bit is set to 0, it cannot be set to 1 by any verb other  
than the Control_Vector_Translate verb. The Prohibit_Export verb can  
reset the export bit.  
The key-part bit (K, bit 44). Set the key-part bit to 1 in a control vector  
associated with a key part. When the final key part is combined with  
previously accumulated key parts, the key-part bit in the control vector for  
the final key part is set to 0. The Control_Vector_Generate verb can set  
the key-part bit to 1 when you supply the KEY-PART keyword.  
For the user definition bits (uu...u, bits 4, 5, and 61), do the following:  
– Set either or both u4 and u5 as may be required by a user-defined  
extension (UDX). These bits are reserved for use by UDX code and  
are not used or tested by IBM code.  
– Set the u61 bit to 1 if the key is only permitted to function in a  
user-defined extension. That is, the key will not be useable in CCA  
services defined in this publication. Keys with bits 4, 5, and/or 61 set  
on can be generated, and can be imported and exported (provided  
other conditions permit).  
The anti-variant bits (bit 30 and bit 38). Set bit 30 to 0 and bit 38 to 1.  
Many cryptographic systems have implemented a system of variants where  
a 7-bit value is exclusive-ORed with each 7-bit group of a key-encrypting  
key before enciphering the target key. By setting bits 30 and 38 to  
opposite values, control vectors do not produce patterns that can occur in  
variant-based systems.  
Control vector bits 64 to 127. If bits 40 to 42 are B'000' (single-length  
key), set bits 64 to 127 to 0. Otherwise, copy bits 0 to 63 into bits 64 to  
127 and set bits 105 and 106 to B'01'.  
Set the parity bits (low-order bit of each byte, bits 7, 15, ..., 127). These  
bits contain the parity bits (P) of the control vector. Set the parity bit of  
each byte so the number of zero-value bits in the byte is an even number.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-11  
CCA Release 2.54  
CCA Key Encryption and Decryption Processes  
This section describes the CCA key-encryption processes:  
CCA DES key encryption  
CCA RSA private key encryption  
Encipherment of DES keys under RSA in “PKA92” format  
Encipherment of a DES key-encrypting key under RSA in “NL-EPP-5” format.  
CCA DES Key Encryption and Decryption Processes  
With the CCA, multiple enciphering or multiple deciphering a key is a two-step  
process. The implementation first exclusive-ORs the subject key’s control vector  
with the master key or with a key-encrypting key to form keys K1 through K6. The  
resulting keys (Kn) are used in the multiple-encipherment of a clear key, or the  
multiple-decipherment of an encrypted key; see Figure C-4 on page C-13 for the  
formation of K1 through K6 and their use with DES DEA encoding and decoding.  
CCA RSA Private Key Encryption and Decryption Process  
RSA private keys are generally encrypted using an “EDE” algorithm. See  
“Triple-DES Ciphering Algorithms” on page D-10.  
With the CCA Support Program Version 1, a private key in an internal key token  
encrypted by the master key is encrypted using the EDE3 process. The secret key  
is deciphered using the DED3 process. A private key in an external key token  
encrypted by a transport key is encrypted using the EDE2 process. The secret key  
is deciphered using the DED2 process.  
With the CCA Support Program Version 2, the private key is encrypted using an  
“object protection key” (OPK). The OPK is encrypted with the asymmetric master  
key. For internal keys, the secret key values are then encrypted by the OPK. For  
external encrypted private keys encryption is provided by the DES transport key.  
See Figure B-11 on page B-13 and Figure B-12 on page B-14.  
C-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
┌──────────────┬──────────────┬──────────────┐  
Master Key  
┌──────────────┬──────────────┐  
Control Vector │  
└────│─────────┴────│─────────┴────│─────────┘  
└────│─────────┴─────────│────┘  
7 8  
15 16 │  
23  
7 8  
│ 15  
┌─────────│────┬─────────│────┬──────────────┤  
├──┐ │  
│ ꢄ ꢄ  
│ ┌───┐  
│ │XOR│  
│ └─┬─┘  
├──┐ │  
│ ꢄ ꢄ  
│ ┌───┐  
│ │XOR│  
│ └─┬─┘  
├──┐ │  
│ ꢄ ꢄ  
│ ┌───┐  
│ │XOR│  
│ └─┬─┘  
K1  
K2  
K3  
┌─────────│────┬─────────│────┬──────────────│───────────────────┤  
└──┐ │  
ꢄ ꢄ  
└──┐ │  
ꢄ ꢄ  
└──┐ │  
ꢄ ꢄ  
┌───┐  
│XOR│  
└─┬─┘  
┌───┐  
│XOR│  
└─┬─┘  
┌───┐  
│XOR│  
└─┬─┘  
K4  
K5  
K6  
┌──────────────┬──────────────┐  
Key-Encrypting Key  
└────│─────────┴────│─────────┘  
7 8  
15  
┌─────────│────┬─────────────────────────────┘  
├──┐ │  
│ ꢄ ꢄ  
│ ┌───┐  
│ │XOR│  
│ └─┬─┘  
├──┐ │  
│ ꢄ ꢄ  
│ ┌───┐  
│ │XOR│  
│ └─┬─┘  
K1,K3  
K2  
┌─────────│────┬─────────────────────────────────────────────────┘  
└──┐ │  
ꢄ ꢄ  
└──┐ │  
ꢄ ꢄ  
┌───┐  
│XOR│  
└─┬─┘  
┌───┐  
│XOR│  
└─┬─┘  
K4,K6  
K5  
Multiple  
Encipherment  
Multiple  
Decipherment  
┌───────────┬───────────┐  
┌───────────┬───────────┐  
│Multiply-Enciphered Key│  
└────┬──────┴──────┬────┘  
Clear Key  
└────┬──────┴──────┬────┘  
7 8  
15  
7 8  
15  
┌──ꢄ───┐  
┌───ꢄ──┐  
┌──ꢄ───┐  
┌───ꢄ──┐  
K1──ꢁ│Encode│  
└──┬───┘  
│Encode│ ──K4  
└───┬──┘  
K3──ꢁ│Decode│  
└──┬───┘  
│Decode│ ──K6  
└───┬──┘  
┌──ꢄ───┐  
┌───ꢄ──┐  
┌──ꢄ───┐  
┌───ꢄ──┐  
K2──ꢁ│Decode│  
└──┬───┘  
│Decode│ ──K5  
└───┬──┘  
K2──ꢁ│Encode│  
└──┬───┘  
│Encode│ ──K5  
└───┬──┘  
┌──ꢄ───┐  
┌───ꢄ──┐  
┌──ꢄ───┐  
┌───ꢄ──┐  
K3──ꢁ│Encode│  
└──┬───┘  
│Encode│ ──K6  
└───┬──┘  
K1──ꢁ│Decode│  
└──┬───┘  
│Decode│ ──K4  
└───┬──┘  
┌────ꢄ──────┬──────ꢄ────┐  
│Multiply-Enciphered Key│  
└───────────┴───────────┘  
┌────ꢄ──────┬──────ꢄ────┐  
Clear Key  
└───────────┴───────────┘  
Figure C-4. Multiply-Enciphering and Multiply-Deciphering CCA Keys  
Notes:  
1. The encode and decode processes are the DES Electronic Code Book (ECB)  
processes for ciphering 64 data bits using a single-length key, Kn.  
2. A CCA cryptographic implementation processes a single-length key in the same  
way as it processes the left half of a double-length key.  
3. If the left and right halves of a double-length key-encrypting key have the same  
value, using the key in multiple-encipherment or multiple-decipherment of a key  
is equal to single-encipherment or single-decipherment of a key.  
4. The control vector for a double-length key consists of two halves. The second  
half is the same as the first half except for bits 41 and 42, which are reversed  
in value.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-13  
CCA Release 2.54  
PKA92 Key Format and Encryption Process  
The PKA_Symmetric_Key_Export, PKA_Symmetric_Key_Generate, and the  
PKA_Symmetric_Key_Import verbs optionally support a PKA92 method of  
encrypting a DES or CDMF key with an RSA public key. This format is adapted  
from the IBM Transaction Security System (TSS) 4753 and 4755 product's  
implementation of “PKA92.” The verbs do not create or accept the complete PKA92  
AS key token as defined for the TSS products. Rather, the verbs only support the  
actual RSA-encrypted portion of a TSS PKA92 key token, the AS External Key  
Block.  
Forming an External Key Block: The PKA96 implementation forms an AS  
External Key Block by RSA-encrypting a key block using a public key. The key  
block is formed by padding the key record detailed in Figure C-5 with zero bits on  
the left, high-order end of the key record. The process completes the key block  
with three sub-processes: masking, overwriting, and RSA encrypting.  
Figure C-5. PKA96 Clear DES Key Record  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
Zero-bit padding to form a structure as long as the length of the public key modulus. The  
implementation constrains the public key modulus to a multiple of 64 bits in the range of 512 to  
1024 bits. Note that governmental export or import regulations can impose limits on the modulus  
length. The maximum length is validated by a check against a value in the Function Control Vector.  
000  
005  
021  
029  
037  
045  
005  
016  
008  
008  
008  
008  
Header and flags: X'01 0000 0000'  
Environment Identifier (EID), encoded in ASCII  
Control vector base for the DES key  
Repeat of the CV data at offset 021  
The single-length DES key or the left half of a double-length DES key  
The right half of a double-length DES key or a random number. This value is  
locally designated, K.  
053  
061  
008  
001  
Random number, IV  
Ending byte, X'00'  
Masking Sub-process: Create a mask by CBC encrypting a multiple of 8 bytes of  
binary zeros using K as the key and IV as the initialization vector as defined in the  
key record at offsets 45 and 53. Exclusive-OR the mask with the key record and  
call the result PKR.  
Overwriting Sub-process: Set the high-order bits of PKR to B'01', and set the  
low-order bits to B'0110'.  
Exclusive-OR K and IV and write the result at offset 45 in PKR.  
Write IV at offset 53 in PKR. This causes the masked and overwritten PKR to have  
IV at its original position.  
Encrypting Sub-process: RSA encrypt the overwritten PKR masked key record  
using the public key of the receiving node.  
Recovering a Key from an External Key Block: Recover the encrypted DES key  
from an AS External Key Block by performing decrypting, validating, unmasking,  
and extraction sub-processes.  
C-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Decrypting Sub-process: RSA decrypt the AS External Key Block using an RSA  
private key and call the result of the decryption PKR. The private key must be  
usable for key management purposes.  
Validating Sub-process: Verify that the high-order two bits of the PKR record are  
valued to B'01'. and that the low-order four bits of the PKR record are valued to  
B'0110'.  
Unmasking Sub-process: Set IV to the value of the 8 bytes at offset 53 of the PKR  
record. Note that there is a variable quantity of padding prior to offset 0. See  
Figure C-5 on page C-14.  
Set K to the exclusive-OR of IV and the value of the 8 bytes at offset 45 of the  
PKR record.  
Create a mask that is equal in length to the PKR record by CBC encrypting a  
multiple of 8 bytes of binary zeros using K as the key and IV as the initialization  
vector. Exclusive-OR the mask with PKR and call the result the key record.  
Copy K to offset 45 in the PKR record.  
Extraction Sub-process: Confirm that:  
The four bytes at offset 1 in the key record are valued to X'0000 0000'  
The two control vector fields at offsets 21 and 29 are identical  
If the control vector is an IMPORTER or EXPORTER key class, that the EID in  
the key record is not the same as the EID stored in the cryptographic engine.  
The control vector base of the recovered key is the value at offset 21. If the control  
vector base bits 40 to 42 are valued to B'010' or B'110', the key is double length.  
Set the right half of the received key's control vector equal to the left half and  
reverse bits 41 and 42 in the right half.  
The recovered key is at offset 37 and is either 8 or 16 bytes long based on the  
control vector base bits 40 to 42. If these bits are valued to B'000', the key is  
single length. If these bits are valued to B'010' or B'110', the key is double  
length.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-15  
CCA Release 2.54  
Encrypting a Key_Encrypting Key in the NL-EPP-5 Format  
The PKA_Symmetric_Key_Generate verb supports a NL-EPP-5 method of  
encrypting a DES key-encrypting key with an RSA public key. The verb returns an  
encrypted key block by RSA encrypting a key record formed in the following  
manner:  
1. Format the key and other data per Figure C-6  
2. Insert random padding data into the record  
3. Insert the count of pad bytes plus one.  
Figure C-6. NL-EPP-5 Key Record Format  
Offset  
(Bytes)  
Length  
(Bytes)  
Description  
000  
002  
02  
Header and Null Cancelation bytes, X'0B00'  
08  
16  
Single length key-encrypting key  
Double length key-encrypting key  
010 or  
018  
Random padding data  
063  
01  
Padding count byte:  
With an RSA key of length 512-bits: X'36' for a single length  
key-encrypting key, or X'2E' for a double length key-encrypting key  
With an RSA key of length 1024-bits: X'76' for a single length  
key-encrypting key, or X'6E' for a double length key-encrypting key.  
Changing Control Vectors  
Use the following techniques to change the control vector associated with a key:  
Pre-exclusive-OR  
Use this technique to import or export a key from a cryptographic node if  
you can exclusive-OR one or more bit patterns into the value of the  
key-encrypting key used to import the key.  
Control_Vector_Translate Verb  
Use the Control_Vector_Translate verb to change the control vector of  
an external key.  
Note: An external key is a key enciphered by a KEK other than the  
master key.  
Changing Control Vectors with the Pre-Exclusive-OR Technique  
Use the pre-exclusive-OR technique to change a key's control vector when  
exporting or importing the key from or to a CCA cryptographic node. By  
exclusive-ORing information with the KEK used to import or export the key, you can  
effectively change the control vector associated with the key.  
The pre-exclusive-OR technique requires exclusive-ORing additional information  
into the value of the IMPORTER or EXPORTER KEK by one of the following  
methods:  
Exchange the KEK in the form of a plaintext value or in the form of key parts.  
For example, if you use the Key_Part_Import verb to enter the KEK key parts,  
C-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
you can enter another part that is set to the value of the pre-exclusive-OR  
quantity (which quantity is discussed later).  
Use the Key_Generate verb to generate an IMPORTER/EXPORTER pair of  
KEKs, with the KEY-PART control vector bit set on. Then use the  
Key_Part_Import verb to enter an additional key part that is set to the value of  
the pre-exclusive-OR quantity.  
To understand how you can change a key’s control vector when importing or  
exporting keys, you must first understand the importing and exporting process. For  
example, when exporting key K, the cryptogram e*KmCVk(K) is changed to the  
cryptogram e*KEKCVk1(K).  
Notes:  
1. The first cryptogram is read as “the multiple encipherment of key K by the key  
formed from the exclusive-OR of the master key and the control vector, CVk, of  
key K.”  
2. The second cryptogram is read as “the multiple encipherment of key K by the  
key formed from the exclusive-OR of the KEK and the control vector, CVk1, of  
key K.” KEK represents the value of the EXPORTER key.  
3. A control vector of value binary zero is equivalent to not having a control  
vector.  
The CCA specifies that in all but one case, CVk is the same as CVk1. The  
exception is that a DATA key whose CVk contains the value of a default CV for that  
key type, has a CVk1 equal to binary zero.  
To change the control vector on key K, the KEK must be set to the value:  
KEK CVk1 CVk2  
where:  
KEK is the value of the shared EXPORTER key.  
represents exclusive-OR.  
CVk1 is the control vector value used with the operational key K at the local  
node.  
CVk2 is the desired control vector value for the exported key K.  
This process works because the value CVk1 is specified in the key token for the  
exported key. The Key_Export verb provides this control-vector value to the  
hardware, which exclusive-ORs it with the EXPORTER KEK. However, you have  
set the EXPORTER KEK to the value KEKCVk1, and when CVk1 is  
exclusive-ORed with CVk1, the effect is that CVk1 is removed. Because you also  
set the KEK to include the desired control vector, CVk2, the exported key will have  
a changed control vector.  
If you need to change the control vector for a key when importing the key, the  
Key_Import verb works in a similar manner. You exclusive-OR the actual control  
vector value (sometimes called a “variant”) and the desired control vector value for  
the imported key into the value of the key-encrypting key. Then when you call the  
Key_Import verb, be sure that the source-key token contains the control vector of  
the desired target key.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-17  
CCA Release 2.54  
Note that if you are processing a double-length key, you almost certainly will have  
to process the key twice, using the key-encrypting key modified by different values  
each appropriate to a key half. Then you concatenate the resulting two correct  
key-halves.  
┌──────────────────────────────┐  
│PIN─Block─Enciphering Key (Kp)│  
└──────────────┬───────────────┘  
┌─────────────────────────────┐  
Other─System Variant  
├────┐  
└─────────────────────────────┘  
┌─ꢄ─┐  
┌─────────ꢄ──────────┐  
│XOR├───────ꢁEncipher─Key Process│  
└─ꢂ─┘  
└─────────┬──────────┘  
┌─────────────────────────────┐  
Transport Key (Kt)  
├────┘  
└──────────────┬──────────────┘  
Typical Non-CCA System│  
eKt(Kp) = eᑍKt(Kp)  
──────────────────────│───────────────────────────────────────│─────────────────────  
CCA System  
ꢄ ┌────────────────ꢄ─────────────────┐  
Transport-key XOR  
Other─System Variant XOR  
Control Vector to Obtain  
┌──────────────ꢄ──────────────┐  
KEK-left and  
KEK-right  
eᑍKEK.Variant(Kp)  
└────────┬───────────────┬─────────┘  
└──────────────┬──────────────┘  
┌──────ꢄ───────────────ꢄ──────┐  
Double─Length KEK'  
├────┐  
└─────────────────────────────┘  
┌─ꢄ─┐  
┌─────────┴──────────┐  
│XOR├───────ꢁDecipher─Key Process│  
┌─────────────────────────────┐ └─ꢂ─┘  
└─────────┬──────────┘  
│ Control Vector for the  
│ PIN─Block─Enciphering Key, │  
│ Control Vector Left and  
│ Control Vector Right  
└─────────────────────────────┘  
│────┘  
┌──────────────ꢄ───────────────┐  
│PIN─Block─Enciphering Key (Kp)│  
└──────────────────────────────┘  
Figure C-7. Exchanging a Key with a Non-Control-Vector System  
Figure C-7 shows a typical situation. In a non-CCA system, a PIN-block encrypting  
key is singly encrypted by a transport key. No control vector or variant modifies the  
value of the transport key, Kt, used to encrypt the PIN-block encrypting key, Kp.  
The resulting cryptogram can be designated eKt(Kp). Since triple-encryption is the  
same as single-encryption when both halves of the encrypting key is equal,  
eKt(Kp)&rbl,.= e*Kt(Kp).  
In the CCA system, a PIN-block decrypting key is an IPINENC key and must be  
double length. (Note that if both halves of the double-length key are the same, the  
IPINENC key effectively performs single encryption.) You must import both halves  
of the target IPINENC key in different steps and combine the result to obtain the  
desired result key.  
1. Create two key-encrypting keys to import each half of the target input PIN-block  
encrypting key (“IPINENC” key). When you receive key Kt, store this as two  
different keys:  
e*KmCViml(KtCVil) e*KmCVimr(KtCVil)  
where:  
CViml is the control vector for the left half of an IMPORTER key  
CVimr is the control vector for the right half of an IMPORTER key  
C-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
CVil is the control vector for the left half of the target input PIN-block  
encrypting key.  
e*KmCViml(KtCVir) e*KmCVimr(KtCVir)  
where:  
CVir is the control vector for the right half of the target input PIN-block  
encrypting key.  
2. Use the Key_Token_Build verb to build source (external) and target (internal)  
key tokens with:  
eKt(Kp) eKt(Kp)  
CVil CVil  
3. Use Key_Import and the first of the IMPORTER keys to import the left half of  
the target key (discard the right half).  
4. Use the Key_Token_Build verb to build source (external) and target (internal)  
key tokens with:  
eKt(Kp) eKt(Kp)  
CVir CVir  
5. Use Key_Import and the second of the IMPORTER keys to import the right half  
of the target key (discard the left half).  
6. Concatenate the two key halves. You can use the Key_Token_Parse and  
Key_Token_Build verbs to parse and build the required key tokens.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-19  
CCA Release 2.54  
Changing Control Vectors with the Control_Vector_Translate Verb  
Do the following when using the Control_Vector_Translate verb:  
Provide the control information for testing the control vectors of the source,  
target, and key-encrypting keys to ensure that only sanctioned changes can be  
performed  
Select the key-half processing mode.  
Providing the Control Information for Testing the Control  
Vectors  
To minimize your security exposure, the Control_Vector_Translate verb requires  
control information (mask array information) to limit the range of allowable control  
vector changes. To ensure that this verb is used only for authorized purposes, the  
source-key control vector, target-key control vector, and key-encrypting key (KEK)  
control vector must pass specific tests. The tests on the control vectors are  
performed within the secured cryptographic engine.  
The tests consist of evaluating four logic expressions, the results of which must be  
a string of binary zeros. The expressions operate bit-for-bit on information that is  
contained in the mask arrays and in the portions of the control vectors associated  
with the key or key-half that is being processed. If any of the expression  
evaluations do not result in all zero bits, the verb is ended with a control vector  
violation return and reason code (8/39). See Figure C-8. Only the 56 bit positions  
that are associated with a key value are evaluated. The low-order bit that is  
associated with key parity in each key-byte is not evaluated.  
Mask Array Preparation  
A mask array consists of seven 8-byte elements: A1, B1, A2, B2, A3, B3, and B4.  
You choose the values of the array elements such that each of the following four  
expressions evaluates to a string of binary zeros. (See Figure C-8 on page C-22.)  
Set the A bits to the value that you require for the corresponding control vector bits.  
In expressions 1 through 3, set the B bits to select the control vector bits to be  
evaluated. In expression 4, set the B bits to select the source and target control  
vector bits to be evaluated. Also, use the following control vector information:  
C1 is the control vector associated with the left half of the KEK.  
C2 is the control vector associated with the source key, or selected source-key  
half/halves.  
C3 is the control vector associated with the target key or selected target-key  
half/halves.  
1. (C1 exclusive-OR A1) logical-AND B1  
This expression tests whether the KEK used to encipher the key meets your  
criteria for the desired translation.  
2. (C2 exclusive-OR A2) logical-AND B2  
This expression tests whether the control vector associated with the source key  
meets your criteria for the desired translation.  
3. (C3 exclusive-OR A3) logical-AND B3  
This expression tests whether the control vector associated with the target key  
meets your criteria for the desired translation.  
4. (C2 exclusive-OR C3) logical-AND B4  
C-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
This expression tests whether the control vectors associated with the source  
key and the target key meet your criteria for the desired translation.  
Encipher two copies of the mask array, each under a different  
cryptographic-variable key (key type CVARENC). To encipher each copy of the  
mask array, use the Cryptographic_Variable_Encipher verb. Use two different keys  
so that the enciphered-array copies are unique values. When using the  
Control_Vector_Translate verb, the mask_array_left parameter and the  
mask_array_right parameter identify the enciphered mask arrays. The  
array_key_left parameter and the array_key_right parameter identify the internal  
keys for deciphering the mask arrays. The array_key_left key must have a key  
type of CVARXCVL and the array_key_right key must have a key type of  
CVARXCVR. The cryptographic process deciphers the arrays and compares the  
results; for the verb to continue, the deciphered arrays must be equal. If the results  
are not equal, the verb returns the return and reason code for data that is not valid  
(8/385).  
When using the Key_Generate verb to create the key pairs CVARENC-CVARXCVL  
and CVARENC-CVARXCVR, the hardware requires the  
Generate_Key_Set_Extended command to be enabled. Each key in the key pair  
must be generated for a different node. The CVARENC keys are generated for, or  
imported into, the node where the mask array will be enciphered. After enciphering  
the mask array, you should destroy the enciphering key. The CVARXCVL and  
CVARXCVR keys are generated for, or imported into, the node where the  
Control_Vector_Translate verb will be performed.  
If using the BOTH keyword to process both halves of a double-length key,  
remember that bits 41, 42, 104, and 105 are different in the left and right halves of  
the CCA control vector and must be ignored in your mask-array tests (that is, make  
the corresponding B2 and/or B3 bits equal to zero).  
When the control vectors pass the masking tests, the verb does the following:  
Deciphers the source key. In the decipher process, the verb uses a key that is  
formed by the exclusive-OR of the KEK and the control vector in the key token  
variable the source_key_token parameter identifies.  
Enciphers the deciphered source key. In the encipher process, the verb uses a  
key that is formed by the exclusive-OR of the KEK and the control vector in the  
key token variable the target_key_token parameter identifies.  
Places the enciphered key in the key field in the key token variable the  
target_key_token parameter identifies.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-21  
CCA Release 2.54  
For expression  
1: KEK CV  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Control Vector  
2: Source CV  
3: Target CV  
│ꢃ│1│ꢃ│1│... │ꢃ│1│ꢃ│1│...  
│ Under Test  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘  
Exclusive-OR  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Set Tested Positions  
A_values  
│ꢃ│ꢃ│1│1│... │ꢃ│ꢃ│1│1│...  
│ to the Value That  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘ the Control Vector  
Must Match  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐  
Intermediate  
Result  
│ꢃ│1│1│ꢃ│... │ꢃ│1│1│ꢃ│...  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘  
Logical-AND  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Set to 1  
B_values  
│ꢃ│ꢃ│ꢃ│ꢃ│... │1│1│1│1│...  
│ Those Positions  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘ to Be Tested  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Report a Control Vector  
Final Result  
│ꢃ│ꢃ│ꢃ│ꢃ│... │ꢃ│1│1│ꢃ│...  
│ Violation If Any  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘ Bit Position Is 1  
For Expression  
4: Source CV  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐  
│ꢃ│1│ꢃ│1│... │ꢃ│1│ꢃ│1│...  
│ Source Control Vector  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘  
Exclusive-OR  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐  
Target CV  
│ꢃ│ꢃ│1│1│... │ꢃ│ꢃ│1│1│...  
│ Target Control Vector  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐  
Intermediate  
Result  
│ꢃ│1│1│ꢃ│... │ꢃ│1│1│ꢃ│...  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘  
Logical-AND  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Set to 1  
B_values  
│ꢃ│ꢃ│ꢃ│ꢃ│... │1│1│1│1│...  
│ Those Positions  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘ to Be Tested  
┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Report a Control Vector  
Final Result  
│ꢃ│ꢃ│ꢃ│ꢃ│... │ꢃ│1│1│ꢃ│...  
│ Violation If Any  
└─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘ Bit Position Is 1  
Figure C-8. Control_Vector_Translate Verb Mask_Array Processing  
C-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Selecting the Key-Half Processing Mode  
The Control_Vector_Translate verb rule-array keywords determine which key halves  
are processed in the verb call, as shown in Figure C-9.  
Keyword SINGLE  
Keyword RIGHT  
Keyword BOTH  
Keyword LEFT  
┌─────────┬─────────┐  
┌─────────┬─────────┐  
┌─────────┬─────────┐  
┌─────────┬─────────┐  
Source Key │ LEFT  
│ RIGHT │  
└────┬────┴─────────┘  
│ LEFT  
│ RIGHT │  
│ LEFT  
│ RIGHT │  
│ LEFT  
│CV-RIGHT │  
└────┬────┴────┬────┘  
└────┬────┴────┬────┘  
└────┬────┴──────┬──┘  
├───key───┐ ┘  
┌────ꢄ────┐  
┌────ꢄ────┐  
│CHANGE─CV│  
└────┬────┘  
┌────ꢄ────┬────ꢄ────┐  
│CHANGE─CV│CHANGE─CV│  
└────┬────┴────┬────┘  
┌────ꢄ────┬────ꢄ────┐  
│CHANGE─CV│CHANGE─CV│  
└────┬────┴────┬────┘  
Process  
│CHANGE─CV│  
Copy  
└────┬────┘  
(Unchanged)  
┌────ꢄ────┬─────────┐  
Target Key │ LEFT │ RIGHT │  
└─────────┴─────────┘  
┌────ꢄ────┬────ꢄ────┐  
┌────ꢄ────┬────ꢄ────┐  
│ LEFT │ RIGHT │  
└─────────┴─────────┘  
┌────ꢄ────┬────ꢄ────┐  
│ LEFT │ RIGHT │  
└─────────┴─────────┘  
│ LEFT  
│ RIGHT │  
└─────────┴─────────┘  
Figure C-9. Control_Vector_Translate Verb Process. In this figure, CHANGE-CV means the requested control  
vector translation change; LEFT and RIGHT mean the left and right halves of a key and its control vector.  
Keyword  
SINGLE  
Meaning  
This keyword causes the control vector of the left half of the source  
key to be changed. The updated key half is placed into the left half of  
the target key in the target key token. The right half of the target key  
is unchanged.  
The SINGLE keyword is useful when processing a single-length key,  
or when first processing the left half of a double-length key (to be  
followed by processing the right half).  
RIGHT  
BOTH  
This keyword causes the control vector of the right half of the source  
key to be changed. The updated key half is placed into the right half  
of the target key of the target key token. The left half of the source  
key is copied unchanged into the left half of the target key in the  
target key token.  
This keyword causes the control vector of both halves of the source  
key to be changed. The updated key is placed into the target key in  
the target key token.  
A single set of control information must permit the control vector  
changes applied to each key half. Normally, control vector bit  
positions 41, 42, 105, and 106 are different for each key half.  
Therefore, set bits 41 and 42 to B'00' in mask array elements B1, B2,  
and B3.  
You can verify that the source and target key tokens have control  
vectors with matching bits in bit positions 40-42 and 104-106, the  
“form field” bits. Ensuring that bits 40-42 of mask array B4 are set to  
B'111'.  
LEFT  
This keyword enables you to supply a single-length key and obtain a  
double-length key. The source key token must contain:  
The KEK-enciphered single-length key  
The control vector for the single-length key (often this is a null  
value)  
A control vector, stored in the source token where the right-half  
control vector is normally stored, used in decrypting the  
single-length source key when the key is being processed for the  
target right half of the key.  
Appendix C. CCA Control-Vector Definitions and Key Encryption C-23  
CCA Release 2.54  
The verb first processes the source and target tokens as with the  
SINGLE keyword. Then the source token is processed using the  
single-length enciphered key and the source token right-half control  
vector to obtain the actual key value. The key value is then  
enciphered using the KEK and the control vector in the target token  
for the right-half of the key.  
This approach is frequently of use when you must obtain a  
double-length CCA key from a system that only supports a  
single-length key. For example when processing PIN keys or  
key-encrypting keys received from non-CCA systems.  
To prevent the verb from ensuring that each key byte has odd parity, you can  
specify the NOADJUST keyword. If you do not specify the NOADJUST keyword,  
or if you specify the ADJUST keyword, the verb ensures that each byte of the  
target key has odd parity.  
When the Target Key-Token CV Is Null  
When you use any of the LEFT, BOTH, or RIGHT keywords, and when the control  
vector in the target key token is null (all B'0'), then bit 0 in byte 59 of the target  
version X'01' key token will be set to B'1' to indicate that this is a double-length  
DATA key.  
Control_Vector_Translate Example  
As an example, consider the case of receiving a single-length PIN-block encrypting  
key from a non-CCA system. Often such a key will be encrypted by an unmodified  
transport key (no control vector or variant is used). In a CCA system, an inbound  
PIN encrypting key is double-length.  
First use the Key_Token_Build verb to insert the single-length key value into the  
left-half key-space in a key token. Specify USE-CV as a key type and a control  
vector value set to 16 bytes of X'00'. Also specify EXTERNAL, KEY, and CV  
keywords in the rule array. This key token will be the source key key-token.  
Second, the target key token can also be created using the Key_Token_Build verb.  
Specify a key type of IPINENC and the NO-EXPORT rule array keyword.  
Then call the Control_Vector_Translate verb and specify a rule-array keyword of  
LEFT. The mask arrays can be constructed as follows:  
A1 is set to the value of the KEK's control vector, most likely the value of an  
IMPORTER key, perhaps with the NO-EXPORT bit set. B1 is set to eight bytes  
of X'FF' so that all bits of the KEK's control vector will be tested.  
A2 is set to eight bytes of X'00', the (null) value of the source key control  
vector. B2 is set to eight bytes of X'FF' so that all bits of the source-key  
“control vector” will be tested.  
A3 is set to the value of the target key's left-half control vector. B3 is set to  
X'FFFF FFFF FF9F FFFF'. This will cause all bits of the control vector to be  
tested except for the two (“fff”) bits used to distinguish between the left-half and  
right-half target-key control vector.  
B4 is set to eight bytes of X'00' so that no comparison is made between the  
source and target control vectors.  
C-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix D. Algorithms and Processes  
This appendix provides processing details for the following aspects of the CCA  
design:  
Cryptographic key-verification techniques  
Ciphering methods  
Triple-DES algorithms, EDE2 and EDE3  
MAC calculation methods  
Access-control algorithms  
Master-key splitting algorithm  
RSA key-pair generation.  
Cryptographic Key Verification Techniques  
The key-verification implementations described in this book employ several  
mechanisms for assuring the integrity and/or value of the key. These subjects are  
discussed:  
Master key verification algorithms  
CCA DES-key and key-part verification algorithm  
Encrypt zeros algorithm.  
Master Key Verification Algorithms  
The IBM 4758 product family implementations employ “triple-length” master keys  
(three DES keys) that are internally represented in 24 bytes. Verification patterns  
on the contents of the new, current, and old master key registers can be generated  
and verified when the selected register is not in the empty state.  
The IBM 4758 Model 2 and 23 employ several verification pattern generation  
methods.  
SHA-1 Based Master Key Verification Method  
A SHA-1 hash is calculated on the quantity X'01' prepended to the 24-byte  
register contents. The resulting 20-byte hash value is used in the following ways:  
The Key_Test verb uses the first eight bytes of the 20-byte hash as the random  
number variable, and uses the second eight bytes as the verification pattern.  
A SHA-1 based master-key verification pattern stored in a two-byte or an  
eight-byte verification pattern field in a key token consists of the first two or the  
first eight bytes of the calculated SHA-1 value.  
Copyright IBM Corp. 1997, 2005  
D-1  
CCA Release 2.54  
S/390 Based Master Key Verification Method  
When the first and third portions of the symmetric master key have the same value,  
the master key is effectively a double-length DES key. In this case, the master key  
verification pattern (MKVP) is based on this algorithm:  
C = X'4545454545454545'  
IR = MKfirst-part eC(MKfirst-part  
)
MKVP = MKsecond-part eIR(MKsecond-part  
)
where:  
ex(Y) is the DES encoding of Y using x as a key  
represents the bit-wise exclusive-OR function.  
Version X'00' internal DES key tokens use this eight-byte master key verification  
pattern.  
Asymmetric Master Key MDC-Based Verification Method  
The verification pattern for the asymmetric master keys is based on hashing the  
value of the master key using the MDC-4 hashing algorithm. Note that the master  
key is not parity adjusted.  
The RSA private key sections X'06' and X'08' use this 16-byte master key  
verification pattern.  
Key Token Verification Patterns  
The verification pattern techniques used in the several types of key tokens are:  
DES key tokens:  
– Triple-length master key, key token version X'00': eight-byte SHA-1  
– Triple-length master key, key token version X'03': two-byte SHA-1  
– Double-length master key, key token version X'00': eight-byte S/390  
– Double-length master key, key token version X'03': two-byte SHA-1.  
RSA key tokens:  
– Private-key section types X'06' and X'08': MDC-based  
– Private-key section types X'02' and X'05': two-byte SHA-1.  
CCA DES-Key Verification Algorithm  
The cryptographic engines provide a method for verifying the value of a DES  
cryptographic key or key part without revealing information about the value of the  
key or key part.  
The CCA verification method first creates a random number. A one-way  
cryptographic function combines the random number with the key or key part. The  
verification method returns the result of this one-way cryptographic function (the  
verification pattern) and the random number.  
Note: A one-way cryptographic function is a function in which it is easy to  
compute the output from a given input, but it is computationally infeasible to  
compute the input given an output.  
For information about how you can use an application program to invoke this  
verification method, see page 5-58.  
D-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The CCA DES key verification algorithm does the following:  
1. Sets KKR= KKR exclusive-OR RN  
2. Sets K1 = X'4545454545454545'  
3. Sets X1 = DES encoding of KKL using key K1  
4. Sets K2 = X1 exclusive-OR KKL  
5. Sets X2 = DES encoding of KKRusing key K2  
6. Sets VP = X2 exclusive-OR KKR.  
where:  
RN  
Is the random number generated or provided  
KKL  
Is the value of the single-length key, or is the left half of the  
double-length key  
KKR  
VP  
Is XL8'00' if the key is a single-length key, or is the value of the right  
half of the double-length key  
Is the verification pattern.  
Encrypt Zeros DES Key Verification Algorithm  
The cryptographic engine provides a method for verifying the value of a DES  
cryptographic key or key part without revealing information about the value of the  
key or key part.  
In this method the single-length or double-length key DEA encodes a 64-bit value  
that is all zero bits. The leftmost 32 bits of the result are compared to the trial input  
value or returned from the Key_Test verb.  
For a single-length key, the key DEA encodes an 8-byte, all-zero-bits value.  
For a double-length key, the key DEA triple-encodes an 8-byte, all-zero-bits value.  
The left half (high-order half) key encodes the zero-bit value, this result is DEA  
decoded by the right key half, and that result is DEA encoded by the left key half.  
Modification Detection Code (MDC) Calculation Methods  
The MDC calculation method defines a one-way cryptographic function. A one-way  
cryptographic function is a function in which it is easy to compute the input into  
output but not easy to compute the output into input. MDC uses DES encryption  
only and a default key of X'5252 5252 5252 5252 2525 2525 2525 2525'.  
The MDC_Generate verb supports four versions of the MDC calculation method  
that you specify by using one of the keywords shown in Figure D-1. All versions  
use the MDC-1 calculation.  
Figure D-1. Versions of the MDC Calculation Method  
Keyword  
Version of the MDC Calculation  
MDC-2  
Specifies two encipherments for each eight-byte input data block.  
PADMDC-2  
MDC-4  
Specifies four encipherments for each eight-byte input data block.  
PADMDC-4  
Appendix D. Algorithms and Processes D-3  
CCA Release 2.54  
When the keywords PADMDC-2 and PADMDC-4 are used, the supplied text is  
always padded as follows:  
If the supplied text is less than 16 bytes in length, pad bytes are appended to  
make the text length equal to 16 bytes.  
If the supplied text is at least 16 bytes in length, pad bytes are appended to  
make the text length equal to the next-higher multiple of eight bytes, pad bytes  
are always added.  
All appended pad bytes, other than the last pad byte, are set to X'FF'.  
The last pad byte is set to a binary value equal to the count of all appended  
pad bytes (X'01' to X'10').  
Use the resulting pad text in the following procedures. The MDC_Generate verb  
uses these MDC calculation methods. See page 4-10 for more information about  
the MDC_Generate verb.  
Notation Used in Calculations  
The MDC calculations use the following notations:  
eK(X)  
||  
Denotes DES encryption of plaintext X using key K  
Denotes the concatenation operation  
XOR  
:=  
Denotes the exclusive-OR operation  
Denotes the assignment operation  
T8<1>  
T8<2>  
Denotes the first eight-byte block of text  
Denotes the second eight-byte block of text, and so on  
KD1, KD2, IN1, IN2, OUT1, OUT2  
Denote 64-bit quantities  
MDC-1 Calculation  
The MDC-1 calculation, which is used in the MDC-2 and MDC-4 calculations,  
consists of the following procedure:  
MDC-1 (KD1, KD2, IN1, IN2, OUT1, OUT2);  
Set KD1mod := set bit 1 and bit 2 of KD1 to "1" and "ꢃ" respectively.  
Set KD2mod := set bit 1 and bit 2 of KD2 to "ꢃ" and "1" respectively.  
Set F1 := IN1 XOR eKD1mod(IN1)  
Set F2 := IN2 XOR eKD2mod(IN2)  
Set OUT1 := (bits ꢃ..31 of F1) || (bits 32..63 of F2)  
Set OUT2 := (bits ꢃ..31 of F2) || (bits 32..63 of F1)  
End procedure  
D-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
MDC-2 Calculation  
The MDC-2 calculation consists of the following procedure:  
MDC-2 (n, text, KEY1, KEY2, MDC);  
For i := 1,2,...,n do  
Call MDC-1(KEY1, KEY2, T8<i>, T8<i>, OUT1, OUT2)  
Set KEY1 := OUT1  
Set KEY2 := OUT2  
End do  
Set output MDC := (KEY1 || KEY2).  
End procedure  
MDC-4 Calculation  
The MDC-4 calculation consists of the following procedure:  
MDC-4 (n, text, KEY1, KEY2, MDC);  
For i := 1,2,...n do  
Call MDC-1(KEY1,KEY2,T8<i>,T8<i>,OUT1,OUT2)  
Set KEY1int := OUT1  
Set KEY2int := OUT2  
Call MDC-1(KEY1int,KEY2int,KEY2,KEY1,OUT1,OUT2)  
Set KEY1 := OUT1  
Set KEY2 := OUT2  
End do  
Set output MDC := (KEY1 || KEY2)  
End procedure  
Ciphering Methods  
The Data Encryption Standard (DES) algorithm defines operations on eight-byte  
data strings. The DES algorithm is used in many different processes within CCA:  
Encrypting general data  
Triple-encrypting PIN blocks  
Triple-encrypting CCA DES keys  
Triple-encrypting RSA private keys...with several processes  
Deriving keys, hashing data, generating CVV values, etc.  
The Encipher and Decipher describe how you can request encryption of  
application data. See “General Data Encryption Processes” on page D-6 for a  
description of the two supported standardized processes.  
In CCA, PIN blocks are encrypted with double-length keys. The PIN block is  
encrypted with the left-half key, which result is decrypted with the right-half key  
and this result is encrypted with the left-half key.  
“CCA DES Key Encryption and Decryption Processes” on page C-12 describes  
how CCA DES keys are enciphered.  
“Triple-DES Ciphering Algorithms” on page D-10 describes how CCA DES keys  
are enciphered.  
Appendix D. Algorithms and Processes D-5  
CCA Release 2.54  
General Data Encryption Processes  
Although the fundamental concepts of ciphering (enciphering and deciphering) data  
are simple, different methods exist to process data strings that are not a multiple of  
eight bytes in length. Two widely used methods for enciphering general data are  
defined in these ANSI standards:  
ANSI X3.106 (CBC)  
ANSI X9.23.  
Note: These methods also differ in how they define the initial chaining value (ICV).  
This section describes how the Encipher and Decipher verbs implement these  
methods.  
Single-DES and Triple-DES for General Data  
The IBM 4758 Model 002 supports the use of triple-DES in addition to the classical  
“single-DES.” In the subsequent descriptions of the CBC method and ANSI X9.23  
method, the actions of Encipher and Decipher encompass both single-DES and  
triple-DES. The triple-DES processes are depicted in Figure D-2 where “left key”  
and “right key” refer to the two halves of a double-length DES key.  
Cleartext, 8 bytes  
Ciphertext, 8 bytes  
────────┬─────────  
─────────┬─────────  
┌───────────────────┐  
┌───────────────────┐  
Left Key──────ꢁ│  
Left Key──────ꢁ│  
Encipher  
Decipher  
└─────────┬─────────┘  
└─────────┬─────────┘  
┌───────────────────┐  
┌───────────────────┐  
Right Key─────ꢁ│  
Right Key─────ꢁ│  
Decipher  
Encipher  
└─────────┬─────────┘  
└─────────┬─────────┘  
┌───────────────────┐  
┌───────────────────┐  
Left Key──────ꢁ│  
Left Key──────ꢁ│  
Encipher  
Decipher  
└─────────┬─────────┘  
└─────────┬─────────┘  
Ciphertext  
Cleartext  
Figure D-2. Triple-DES Data Encryption and Decryption  
D-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
ANSI X3.106 Cipher Block Chaining (CBC) Method  
ANSI standard X3.106 defines four modes of operation for ciphering. One of these  
modes, Cipher Block Chaining (CBC), defines the basic method for ciphering  
multiple eight-byte data strings. Figure D-3 and Figure D-4 on page D-8 show  
Cipher Block Chaining using the Encipher and the Decipher verbs. A plaintext data  
string that must be a multiple of eight bytes, is processed as a series of eight-byte  
blocks. The ciphered result from processing an eight-byte block is exclusive-ORd  
with the next block of eight input bytes. The last eight-byte ciphered result is  
defined as an output chaining value (OCV). The security server stores the OCV in  
bytes 0 through 7 of the chaining_vector variable.  
An ICV is exclusive-ORd with the first block of eight bytes. When you call the  
Encipher verb or the Decipher verb, specify the INITIAL or CONTINUE keywords.  
If you specify the INITIAL keyword (the default), the initialization vector from the  
verb parameter is exclusive-ORd with the first eight bytes of data. If you specify  
the CONTINUE keyword, the OCV identified by the chaining_vector parameter is  
exclusive-ORd with the first eight bytes of data.  
ANSI X9.23  
An enhancement to the basic Cipher Block Chaining mode of X3.106 is defined so  
that the system can process data lengths that are not exact multiples of eight bytes.  
The ANSI X9.23 method always adds from one byte to eight bytes to the plaintext  
before encipherment. With these methods, the last added byte is the count of the  
added bytes and is within the range of X'01' to X'08'. The other added padding  
bytes are set to X'00'.  
For other than the CBC method, when the security server deciphers the ciphertext,  
the security server uses the last byte of the deciphered data as the number of  
bytes to be removed (the pad bytes and the count byte). The resulting plaintext is  
the same length as the original plaintext.  
Appendix D. Algorithms and Processes D-7  
CCA Release 2.54  
┌──────────────┐  
│Verb Parameter│  
└──────┬───────┘  
┌──────ꢄ───────┐ ────── Plaintext from Application Program ────────────ꢁ  
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  
Vector  
│ │ Data (1,8) │ │ Data (9,16) │ │Data (Nᑍ8─7,Nᑍ8)│  
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘  
│INITIAL  
│Keyword  
┌─ꢄ─┐  
┌───┐  
┌─ꢄ─┐  
┌─ꢄ─┐  
or───ꢁICV├──────ꢁXOR│  
┌──────ꢁXOR│  
┌ ─ ───ꢁXOR│  
└─┬─┘  
└───┘  
└─┬─┘  
└─┬─┘  
│CONTINUE  
│Keyword  
┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐  
│ Encipher │ │ │ Encipher │  
│ Encipher │  
└─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘  
┌───┐  
├─────────┘  
├────── ─ ┘  
├─────────────ꢁOCV│  
└─┬─┘  
┌───────ꢄ────────┐ ┌───────ꢄ────────┐ ┌───────ꢄ────────┐  
│ Data (1,8) │ │ Data (9,16) │ │Data (Nᑍ8─7,Nᑍ8)│  
└────────────────┘ └────────────────┘ └────────────────┘  
───────── Ciphertext to Application Program ──────────ꢁ  
┌────────ꢄ──────┐  
└──────────────────────────────────────────────────────────────┤Chaining Vector│  
└───────────────┘  
Figure D-3. Enciphering Using the CBC Method  
┌──────────────┐  
│Verb Parameter│  
└──────┬───────┘  
┌──────ꢄ───────┐ ──────── Ciphertext from Application Program ─────────ꢁ  
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  
Vector  
│ │ Data (1,8) │ │ Data (9,16) │ │Data (Nᑍ8─7,Nᑍ8)│  
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘  
┌───┐  
├─────────┐  
├────── ─ ┐  
├─────────────ꢁOCV│  
└─┬─┘  
┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐  
│ Decipher │ │ │ Decipher │  
│ Decipher │  
│INITIAL  
│Keyword  
└─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘  
┌───┐  
┌─ꢄ─┐  
┌─ꢄ─┐  
┌─ꢄ─┐  
or───ꢁICV├──────ꢁXOR│  
└──────ꢁXOR│  
└ ─ ───ꢁXOR│  
└───┘  
└─┬─┘  
└─┬─┘  
└─┬─┘  
│CONTINUE  
│Keyword  
┌───────ꢄ────────┐ ┌───────ꢄ────────┐ ┌───────ꢄ────────┐  
│ Data (1,8) │ │ Data (9,16) │ │Data (Nᑍ8─7,Nᑍ8)│  
└────────────────┘ └────────────────┘ └────────────────┘  
──────── Plaintext to Application Program ────────────ꢁ  
┌────────ꢄ──────┐  
└──────────────────────────────────────────────────────────────┤Chaining Vector│  
└───────────────┘  
Figure D-4. Deciphering Using the CBC Method  
D-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
┌──────────────┐  
│Verb Parameter│  
└──────┬───────┘  
┌──────ꢄ───────┐ ── Plaintext from Application Program ───ꢁ  
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────┬─────┬─────┐  
Vector  
│ │ Data (1,8) │ │Data (Nᑍ8─7,Nᑍ8)│ │Data│ Pad │Count│  
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └────┴──┬──┴─────┘  
┌─ꢄ─┐  
┌─ꢄ─┐  
┌─ꢄ─┐  
└───────────────ꢁXOR│  
┌ ─ ───ꢁXOR│  
└─┬─┘  
┌──────ꢁXOR│  
└─┬─┘  
└─┬─┘  
┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐  
│ Encipher │  
│ Encipher │ │ │ Encipher │  
└─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘  
├────── ─ ┘  
├─────────┘  
┌───────ꢄ────────┐ ┌───────ꢄ────────┐ ┌───────ꢄ────────┐  
│ Data (1,8) │ │Data (Nᑍ8─7,Nᑍ8)│ │ Last Block │  
└────────────────┘ └────────────────┘ └────────────────┘  
─────── Ciphertext to Application Program ────────────ꢁ  
Figure D-5. Enciphering Using the ANSI X9.23 Method  
┌──────────────┐  
│Verb Parameter│  
└──────┬───────┘  
┌──────ꢄ───────┐ ──────── Ciphertext from Application Program ─────────ꢁ  
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  
Vector  
│ │ Data (1,8) │ │Data (Nᑍ8─7,Nᑍ8)│ │ Last Block │  
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘  
├────── ─ ┐  
├─────────┐  
┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐ │ ┌─────ꢄ─────┐  
│ Decipher │  
│ Decipher │ │ │ Decipher │  
└─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘  
┌─ꢄ─┐  
┌─ꢄ─┐  
┌─ꢄ─┐  
└───────────────ꢁXOR│  
└ ─ ───ꢁXOR│  
└──────ꢁXOR│  
└─┬─┘  
└─┬─┘  
└─┬─┘  
┌───────ꢄ────────┐ ┌───────ꢄ────────┐ ┌────┬──ꢄ──┬─────┐  
│ Data (1,8) │ │Data (Nᑍ8─7,Nᑍ8)│ │Data│ Pad │Count│  
└────────────────┘ └────────────────┘ └────┴─────┴─────┘  
─── Plaintext to Application Program ────ꢁ  
Figure D-6. Deciphering Using the ANSI X9.23 Method  
Appendix D. Algorithms and Processes D-9  
CCA Release 2.54  
Triple-DES Ciphering Algorithms  
Triple-DES is used to encrypt keys, PIN blocks, and general data. Several  
techniques are employed:  
T-DES ECB DES keys, when triple encrypted under a double-length DES key, are  
ciphered using an e-d-e scheme without feedback. SeeFigure C-4 on  
page C-13.  
Triple-DES CBC Encryption of general data, and RSA section type X'08'  
CRT-format private keys and OPK keys, employs the scheme depicted  
in Figure D-7 on page D-11 and Figure D-8 on page D-11. This is  
often referred to as “outer CBC mode.”  
The CCA implementation described in this publication supports  
double-length DES keys for triple-DES data encryption through the use  
of the Decipher and Encipher verbs. The triple-length asymmetric  
master key is used to CBC encrypt CRT-format OPK keys. (See also  
Figure B-12 on page B-14.)  
EDEx / DEDx CCA employs “EDEx” processes for encrypting several of the RSA  
private key formats (section types X'02', X'05', and X'06') and the  
OPK key in section type X'06'. The EDEx processes make successive  
use of single-key DES CBC processes. EDE2, EDE3, and EDE5  
processes have been defined based on the number of keys and  
initialization vectors used in the process. See Figure D-9 and  
Figure D-10. K1, K2, and K3 are true keys while “K4” and “K5” are  
initialization vectors. See Figure D-9 on page D-12 and Figure D-10.  
D-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
T1 64ꢁ T2 64ꢁ T3 64ꢁ │ │ Tn 64ꢁ │  
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘  
┌───┐  
┌───┐  
┌───┐  
┌───┐  
IV─ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌──//───ꢁ│XOR│  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘  
┌───┐  
Ka─ꢁ│ e │  
└─┬─┘  
┌───┐ │  
Ka─ꢁ│ e │ │ Ka─ꢁ│ e │ │ Ka─ꢁ│ e │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐ │  
Kb─ꢁ│ d │ │ Kb─ꢁ│ d │ │ Kb─ꢁ│ d │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Kb─ꢁ│ d │  
└─┬─┘  
┌───┐ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Kc─ꢁ│ e │  
└─┬─┘  
Kc─ꢁ│ e │ │ Kc─ꢁ│ e │ │ Kc─ꢁ│ e │ │  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
S1 64ꢁ  
S2 64ꢁ  
S3 64ꢁ  
│ │  
Sn 64ꢁ  
└─────────────┴─────────────┴─────────────┴/┴─────────────┘  
For 2-key triple-DES, Kc = Ka  
Figure D-7. Triple-DES CBC Encryption Process  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
S1 64ꢁ  
S2 64ꢁ  
S3 64ꢁ  
│ │  
Sn 64ꢁ  
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘  
├────┐  
├────┐  
├────┐  
┌───┐ │  
Kc─ꢁ│ d │ │ Kc─ꢁ│ d │ │ Kc─ꢁ│ d │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Kc─ꢁ│ d │  
└─┬─┘  
┌───┐ │  
Kb─ꢁ│ e │ │ Kb─ꢁ│ e │ │ Kb─ꢁ│ e │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Kb─ꢁ│ e │  
└─┬─┘  
┌───┐ │  
Ka─ꢁ│ d │ │ Ka─ꢁ│ d │ │ Ka─ꢁ│ d │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Ka─ꢁ│ d │  
└─┬─┘  
┌───┐ │  
┌───┐ │  
┌───┐ │  
┌───┐  
IV─ꢁ│XOR│ └─────ꢁ│XOR│ └─────ꢁ│XOR│ └──//───ꢁ│XOR│  
└─┬─┘  
└─┬─┘  
└─┬─┘  
└─┬─┘  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
T1 64ꢁ  
T2 64ꢁ  
T3 64ꢁ  
│ │  
Tn 64ꢁ  
└─────────────┴─────────────┴─────────────┴/┴─────────────┘  
For 2-key triple-DES, Kc = Ka  
Figure D-8. Triple-DES CBC Decryption Process  
Appendix D. Algorithms and Processes D-11  
CCA Release 2.54  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
T1<64> T2<64> T3<64> │ │ Tn<64> │  
EDE2 EDE3 EDE5  
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘  
┌───┐  
┌───┐  
┌───┐  
┌───┐  
K4  
K1  
IVa─ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌──//───ꢁ│XOR│  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘  
┌───┐  
Ka─ꢁ│ e │  
└─┬─┘  
┌───┐ │  
┌───┐ │  
┌───┐ │  
K1  
K1  
Ka─ꢁ│ e │ │ Ka─ꢁ│ e │ │ Ka─ꢁ│ e │ │  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
├────┐  
├────┐  
├────┐  
┌───┐ │  
Kb─ꢁ│ d │ │ Kb─ꢁ│ d │ │ Kb─ꢁ│ d │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Kb─ꢁ│ d │  
└─┬─┘  
K2  
K2  
K2  
┌───┐ │  
┌───┐ │  
┌───┐ │  
┌───┐  
IVb─ꢁ│XOR│ └─────ꢁ│XOR│ └─────ꢁ│XOR│ └──//───ꢁ│XOR│  
└─┬─┘  
┌───┐  
└─┬─┘  
┌───┐  
└─┬─┘  
┌───┐  
└─┬─┘  
┌───┐  
K5  
K3  
IVc─ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌──//───ꢁ│XOR│  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘  
┌───┐  
Kc─ꢁ│ e │  
└─┬─┘  
┌───┐ │  
┌───┐ │  
┌───┐ │  
K1  
K3  
Kc─ꢁ│ e │ │ Kc─ꢁ│ e │ │ Kc─ꢁ│ e │ │  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
S1<64>  
S2<64>  
S3<64>  
│ │  
Sn<64>  
└─────────────┴─────────────┴─────────────┴/┴─────────────┘  
Figure D-9. EDE Algorithm  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
EDE2 EDE3 EDE5  
S1<64>  
S2<64>  
S3<64>  
│ │  
Sn<64>  
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘  
├────┐  
├────┐  
├────┐  
┌───┐ │  
Kc─ꢁ│ d │ │ Kc─ꢁ│ d │ │ Kc─ꢁ│ d │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Kc─ꢁ│ d │  
└─┬─┘  
K1  
K3  
K3  
K5  
┌───┐ │  
┌───┐ │  
┌───┐ │  
┌───┐  
IVc─ꢁ│XOR│ └─────ꢁ│XOR│ └─────ꢁ│XOR│ └──//───ꢁ│XOR│  
└─┬─┘  
┌───┐  
└─┬─┘  
┌───┐  
└─┬─┘  
┌───┐  
└─┬─┘  
┌───┐  
IVb─ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌─────ꢁ│XOR│ ┌──//───ꢁ│XOR│  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘ │  
└─┬─┘  
┌───┐  
Kb─ꢁ│ e │  
└─┬─┘  
┌───┐ │  
┌───┐ │  
┌───┐ │  
K2  
K2  
K2  
Kb─ꢁ│ e │ │ Kb─ꢁ│ e │ │ Kb─ꢁ│ e │ │  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
└─┬─┘ │  
├────┘  
├────┐  
├────┐  
├────┐  
┌───┐ │  
Ka─ꢁ│ d │ │ Ka─ꢁ│ d │ │ Ka─ꢁ│ d │ │  
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │  
┌───┐ │  
┌───┐ │  
┌───┐  
Ka─ꢁ│ d │  
└─┬─┘  
K1  
K1  
K1  
K4  
┌───┐ │  
┌───┐ │  
┌───┐ │  
┌───┐  
IVa─ꢁ│XOR│ └─────ꢁ│XOR│ └─────ꢁ│XOR│ └──//───ꢁ│XOR│  
└─┬─┘  
└─┬─┘  
└─┬─┘  
└─┬─┘  
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐  
T1<64>  
T2<64>  
T3<64>  
│ │  
Tn<64>  
└─────────────┴─────────────┴─────────────┴/┴─────────────┘  
Figure D-10. DED Process  
D-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
MAC Calculation Methods  
With CCA Release 2.51, three variations of DES based message authentication are  
supported by the MAC_Generate and MAC_Verify verbs:  
ANSI X9.9  
ANSI X9.19 optional Procedure 1  
EMV post-padding of X'80'.  
The Financial Institution (Wholesale) Message Authentication Standard (ANSI  
X9.9-1986) defines a process for the authentication of messages from originator to  
recipient. This process is called the Message Authentication Code (MAC)  
calculation method.1  
Figure D-11 on page D-14 shows the MAC calculation for binary data. KEY is a  
64-bit key, and T1 through Tn are 64-bit data blocks of text. If Tn is less than 64  
bits long, binary zeros are appended (padded) to the right of Tn. Data blocks  
T1...Tn are DES CBC encrypted with all output discarded except for the final output  
block, On.  
The Financial Institution (Retail) Message Authentication Standard, ANSI X9.19  
Optional Procedure 1, specifies additional processing of the 64-bit On MAC value.  
The CCA “X9.19OPT” process employs a double-length DES key. After calculating  
the 64-bit MAC as above with the left half of the double-length key, the result is  
decrypted using the right half of the double-length key. This result is then  
encrypted with the left half of the double-length key. The resulting MAC value is  
processed according to other specifications supplied to the verb call.  
The EMV smart card standards define MAC generation and verification processes  
which are the same as ANSI X9.9 and ANSI X9.19 Optional Procedure 1 except  
for padding added to the end of the message. Append one byte of X'80' to the  
original message. Then append additional bytes, as required, of X'00' to form an  
extended message which is a multiple of eight bytes in length.  
In the X9.9 and X9.19 Optional Procedure 1 standards, the leftmost 32 bits (4  
bytes) of (On) are taken as the MAC. In the EMV standards, the MAC value is four  
to eight bytes in length. CCA provides support for the leftmost 4, 6 and 8 bytes of  
MAC value.  
1
The ANSI X9.9 standard defines five options. The MAC_Generate and MAC_Verify verbs implement option 1, binary data.  
Appendix D. Algorithms and Processes D-13  
CCA Release 2.54  
T1  
T2  
Tn-1  
Tn  
┌──┴──┐  
┌──┴──┐  
┌──┴──┐  
┌─ꢁ─┤ XOR │  
│ │  
┌─ꢁ─┤ XOR │  
│ │  
┌─ꢁ─┤ XOR │  
│ │ │  
│ └──┬──┘  
│ └──┬──┘  
│ └──┬──┘  
┌──┴──┐  
│ ┌──┴──┐  
│ ┌──┴──┐  
│ ┌──┴──┐  
│ │  
│KEY│ Enc │  
│ │  
│ └──┬──┘  
│O2  
└────//─────┘  
│ │  
│KEY│ Enc │  
│ │  
│ └──┬──┘  
│ │  
KEY│ Enc │  
│KEY│ Enc │  
│ │  
└──┬──┘  
│O1  
│ └──┬──┘  
│On  
│On-1 │  
└───────┘  
└───────┘  
├───ꢁ(OCV)  
ANSI X9.9 MAC  
(and to decipher and  
encipher for ANSI X9.19)  
Figure D-11. MAC Calculation Method  
D-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
RSA Key-Pair Generation  
RSA key-pair generation is determined based on user input of the modulus bit  
length, public exponent, and key type. The output is based on creating primes p  
and q in conformance with ANSI X9.31 requirements as follows:  
prime p bit length = ((modulus_bit_length +1)/2)  
prime q bit length = modulus_bit_length - p_bit_length  
p and q are randomly chosen prime numbers  
p > q  
The Rabin-Miller Probabilistic Primality Test is iterated eight times for each  
prime. This test determines that a false prime will be produced with probability  
no greater then 1/4c, where “c” is the number of iterations. Refer to the ANSI  
x9.31 standard and see the section entitled “Miller-Rabin Probabilistic Primality  
Test.”  
Primes p and q are relatively prime with the public exponent.  
Primes p and q are different in at least one of the first 100 most significant bits,  
that is, |p-q| > 2(prime bit length - 100). For example, when the Modulus bit length is  
1024, then both primes bit length are 512 bits and the difference of the two  
primes is |p-q| > 2412  
.
An RSA key is generated in the following manner with respect to random numbers:  
1. For each key-generation, and for any size of key, the PKA Manager2 seeds an  
internal FIPS-approved, SHA-1 based pseudo random number generator  
(PRNG) with the first 20 bytes (160 bits) of information that it receives from  
three successive calls to the RNG Manager's PRNG interface.  
2. The RNG Manager can supply random numbers in three ways, but with the  
CCA Support Program only one way is used, the PRNG method. The PKA  
Manager seeds an internal FIPS-approved, SHA-1 based PRNG with the first  
160 bits out of 192 bits it obtains from a hardware random number pool. The  
PRNG responds with eight random bytes (64 bits) per request. After every  
eight requests, the PRNG is reseeded from the hardware random number pool.  
The RNG Manager can respond to requests for random numbers from other  
processes with such responses interspersed between responses to PKA  
Manager requests.  
The RNG Manager collects a stream of random bits from a hardware  
random-bit source into a 20,000 bit “pool.” The Manager then turns of the  
hardware random-bit generator until additional bits are needed. The goal is to  
always have 20,000 bits in the pool. Bits are supplied first-in, first-out from the  
pool.  
3. Thus, an RSA key is generated from random information obtained from two  
cascaded SHA-1 PRNGs. An RSA key will be based on one or more 160-bit  
seeds from the hardware random-bit source depending on the dynamic mix of  
tasks running within the Coprocessor.  
2
The “PKA Manager” (public-key architecture) and the “RNG Manager” (random number) are components of the control program  
which support the CCA application within the Coprocessor.  
Appendix D. Algorithms and Processes D-15  
CCA Release 2.54  
Access-Control Algorithms  
The following sections describe algorithms and protocols used by the  
access-control system.  
Passphrase Verification Protocol  
This section describes the process used to log a user on to the Cryptographic  
Coprocessor.  
Design Criteria  
The passphrase verification protocol is designed to meet the following criteria.  
1. The use of cryptographic algorithms is permitted in the client logon software,  
but there must be no storage of any long-term cryptographic keys. This is  
because secure key storage is generally not available in the client workstation.  
2. Replay attacks must not be feasible. This means that the logon request  
message must be protected so that it cannot be captured by an adversary, and  
later replayed to gain access to the genuine user's privileges.  
3. An attacker should not be able to guess the cleartext content of the logon  
request message.  
4. No special hardware should be required on the client workstation.  
5. The logon process must result in the establishment of a session key known  
only to the Cryptographic Coprocessor and the client. This key will be used on  
subsequent transactions to prove the identity of the sender, and to secure  
transmitted data.  
6. The session key will be generated in the Coprocessor. Its hardware-based  
random-number generator is of higher quality than software-based  
random-number sources generally available.  
Description of the Protocol  
The protocol is comprised of the following steps.  
1. The user provides his User ID (UID) and passphrase.  
2. The passphrase is hashed in the client workstation, using SHA-1. The resulting  
hash is used to construct a logon key, denoted KL.  
KL is a triple-length DES key. The three components of the triple-length key  
are denoted K1L, K2L, and K3L. K1L is comprised of the first eight bytes of the  
hash, K2L is comprised of the second eight bytes, and K3L is comprised of the  
last four bytes, concatenated with four bytes of X'00'. Figure D-12 shows an  
example to clarify this.  
Passphrase is "This is my passphrase!"  
SHA-1 hash of the passphrase is hex 42BED1CD 1DB68934 6319E315 F3Cꢃ96A8 B2Eꢃ8DB2  
└───────┬───────┘ └────────┬──────┘ └───┬──┘  
K1 is 42BED1CD 1DB68934 ───────────────────┘  
K2 is 6319E315 F3Cꢃ96A8 ──────────────────────────────────────┘  
K3 is B2Eꢃ8DB2 ꢃꢃꢃꢃꢃꢃꢃꢃ ───────────────────────────────────────────────────┘  
Figure D-12. Example of Logon Key Computation  
D-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
3. The client workstation generates a random number, RN (64 bits).  
Note: Note: The random-number RN is not used inside the Cryptographic  
Coprocessor. It is only included in the protocol to guarantee that the cleartext  
of the logon request is different every time.  
4. The client workstation sends a logon request to the Cryptographic Coprocessor,  
including the following information:  
{ UID, eKL(RN, UID, timestamp) }  
Encryption uses DES EDE33 mode, performed in software in the client  
workstation. The timestamp includes both the time and the date, in GMT. It is  
used to prevent replay of the logon request. The timestamp is formed from the  
concatenation of binary encoded values of the year, month, day, hour, minute,  
and second. Each value is held in one byte except for the year which is held in  
a two-byte value.  
5. The Cryptographic Coprocessor retrieves the user profile, which it has in secure  
Coprocessor memory. It uses the received user-ID value, UID, to locate the  
corresponding profile. If the user's profile is not found, the logon request is  
rejected.  
6. The Coprocessor reads the hash of the user's passphrase from the profile, thus  
obtaining KL.  
7. The Coprocessor uses KL to decrypt the user's logon data, thus recovering the  
UID, timestamp, and RN. It compares the recovered UID with the cleartext UID  
it received, and aborts if the two are not equal. Inequality is an indication that  
the passphrase was incorrect, or that someone tried to splice another user's  
captured logon data into their own request.  
8. The Coprocessor verifies that the recovered timestamp is within 5 minutes of  
the current time, according to the Coprocessor's secure clock. If the timestamp  
falls outside this window, it indicates a probable replay attack, and the logon  
request is rejected.  
9. If everything in the preceding steps was acceptable, the user is logged on to  
the Coprocessor. The Coprocessor generates a 192-bit session key, KS, and  
returns this key to the client in the form of eKL(KS).  
10. In a secure internal table, the Coprocessor stores the user-ID (UID), the value  
of KS, and the user's role identifier, which is extracted from the profile. This  
information is used on later requests to verify that the user is logged on, and to  
find the role defining the user's privileges. The table entry is destroyed when  
the user logs off.  
11. The client workstation software (SAPI) saves KS for use in validating  
subsequent verb calls. The SAPI code in the client and the Coprocessor  
compute the industry-standard HMAC keyed-hash algorithm over sensitive  
portions of subsequent verb calls and responses. An HMAC is computed using  
KS as the key.  
3
For a description of the EDE3 encryption process, see Figure D-9 on page D-12.  
Appendix D. Algorithms and Processes D-17  
CCA Release 2.54  
Master-Key-Splitting Algorithm  
This section describes the mathematical and cryptographic basis for the m-of-n key  
shares scheme.  
The key splitting is based on Shamir's secret sharing algorithm:  
The value to be shared is the master key, Km, which is a triple-DES key and thus  
168 bits long. Let P be the first prime number larger than 2168. All operations are  
carried out modulo P.  
Shamir's secret sharing allows the sharing of Km among n trustees in a way that  
no set of t or less of trustees will have ANY information about Km, while t+1  
trustees (or more) will be able to reconstruct Km.  
Sharing phase:  
1. Randomly choose a_t,...,a_1 in [0..P-1]  
2. Consider the polynomial f(x) = a_t xt + ... + a_1 x + a_0, where a_0=Km.  
Compute mk_i = f(i) mod P for all i=1,...n  
3. Proceed to distribute the values mk_i as described above.  
Reconstruction phase:  
1. After generating the set of authentic values (above sharing phase) proceed as  
follows:  
2. Take t+1 such values and interpolate the polynomial f(x) of degree t passing  
through these values using Lagrange interpolation. This will define a  
polynomial f(x) such that: f(i)=mk_i, and further more f(0) = MK. As we are  
only interested in Km, we present the mathematical formula to reconstruct the  
free term of the polynomial f(x). Let k_1,...,k_{t+1} be the indices of the mk_i's  
used for reconstruction. Then  
a_0=SUM_j( b_{k_j} PROD_h (x_{k_h} / (x_{k_h}- x_{k_j}))) mod P  
3. Proceed to install Km = a_0 = f(0) mod P.  
D-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Formatting Hashes and Keys in Public-Key Cryptography  
The Digital_Signature_Generate and Digital_Signature_Verify verbs support several  
methods for formatting a hash, and in some cases a descriptor for the hashing  
method, into a bit-string to be processed by the cryptographic algorithm. This  
section discusses the ANSI X9.31 and PKCS #1 methods. The ISO 9796-1  
method can be found in the ISO standard.  
This section also describes the PKCS #1, version 1, 1.5, and 2.0, methods for  
placing a key in a bit string for RSA ciphering as part of a key exchange.  
ANSI X9.31 Hash Format  
With ANSI X9.31, the string that is processed by the RSA algorithm is formatted by  
the concatenation of a header, padding, the hash and a trailer, from the most  
significant bit to the least significant bit, such that the resulting string is the same  
length as the modulus of the key. For the CCA implementation, the modulus length  
must be a multiple of 8 bits.  
The header consists of X'6B'  
The padding consists of X'BB', repeated as many times as required, and  
terminated by X'BA'  
The hash value follows the padding  
The trailer consists of a hashing mechanism specifier and final byte. These  
specifiers are defined:  
– X'31': RIPEMD-160  
– X'32': RIPEMD-128  
– X'33': SHA-1  
A final byte of X'CC'.  
PKCS #1 Formats  
Version 2.0 of the PKCS #1 standard4 defines methods for formatting keys and  
hashes prior to RSA encryption of the resulting data structures. The earlier  
versions of the PKCS #1 standard defined “block types” 0, 1, and 2, but in the  
current standard that terminology is dropped.  
The CCA products described in this book implement these processes using the  
terminology of the Version 2.0 standard:  
For formatting keys for secured transport:  
– RSAES-OAEP, the preferred method for key-encipherment5 when  
exchanging DATA keys between systems. In CCA, keyword PKCSOAEP  
is used to invoke this formatting technique. The “P” parameter described in  
the standard is not used and its length is set to zero.  
– RSAES-PKCS1-v1_5, is an older method for formatting keys. In CCA,  
keyword PKCS-1.2 is used to invoke this formatting technique.  
For formatting hashes for digital signatures:  
4
PKCS standards can be retrieved from http://www.rsasecurity.com/rsalabs/pkcs.  
5
The PKA92 method and the method incorporated into the SET standard are other examples of the OAEP technique. The “OAEP”  
technique is attributed to Bellare and Rogaway and stands for “Optimal Asymmetric Encryption Padding.”  
Appendix D. Algorithms and Processes D-19  
CCA Release 2.54  
– RSASSA-PKCS1-v1_5, the newer name for the block-type 1 format. In  
CCA, keyword PKCS-1.1 is used to invoke this formatting technique.  
– The PKCS #1 specification no longer discusses use of block-type 0. In  
CCA, keyword PKCS-1.0 is used to invoke this formatting technique. Use  
of block-type 0 is discouraged.  
Using the terminology from older versions of the PKCS #1 standard, block types 0  
and 1 are used to format a hash and block type 2 is used to format a DES key.  
The blocks consist of the following (“” means concatenation):  
X'00' BT PS X'00' D  
where:  
BT is the block type, X'00', X'01', or X'02'.  
PS is the padding of as many bytes as required to make the block the  
same length as the modulus of the RSA key, and is bytes of X'00' for  
block type 0, X'FF' for block type 1, and random and non-X'00' for block  
type 2. The length of PS must be at least 8 bytes.  
D is the key, or the concatenation of the BER-encoded hash identifier and  
the hash.  
You can create the BER encoding of an MD5 or SHA-1 value by prepending these  
strings to the 16 or 20-byte hash values, respectively:  
MD5  
X'3020300C 06082A86 4886F70D 02050500 0410'  
SHA-1  
X'30213009 06052B0E 03021A05 000414'  
D-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix E. Financial System Verbs Calculation Methods  
and Data Formats  
This appendix describes the following:  
PIN-calculation methods  
PIN-block formats  
Unique-key-per-transaction calculation methods  
MasterCard and VISA card verification techniques  
VISA and EMV smart card PIN-related formats and processes.  
The PIN calculation methods are independent from PIN-block formats. A PIN can  
be calculated by any method and generally used in any PIN-block format. For  
example, a PIN can be calculated by the IBM 3624 PIN-calculation method and  
used either in the IBM 3624 PIN-block format or in another PIN-block format.  
Figure E-1. Financial PIN Calculation Methods, Data Formats, Other Items  
Item  
Page  
E-3  
IBM 3624 PIN-Calculation Method  
IBM 3624 PIN Offset Calculation Method  
Netherlands PIN-1 Calculation Method  
IBM German Bank Pool Institution PIN-Calculation Method  
VISA PIN Validation Value (PVV) Calculation Method  
Interbank PIN-Calculation Method  
3624 PIN-Block Format  
E-4  
E-5  
E-6  
E-7  
E-8  
E-9  
ISO-0 PIN-Block Format  
E-10  
E-11  
E-12  
E-13  
E-16  
E-17  
ISO-1 PIN-Block Format  
ISO-2 PIN-Block Format  
UKPT Calculation Methods (Unique Key Per Transaction, ANSI X9.24)  
CVV, CVC (Visa, MasterCard)  
VISA and EMV formats and processes  
Copyright IBM Corp. 1997, 2005  
E-1  
CCA Release 2.54  
PIN-Calculation Methods  
The financial PIN verbs support some or all of these PIN-calculation methods, see  
Figure 8-3 on page 8-6:  
IBM 3624 PIN (IBM-PIN)  
IBM 3624 PIN Offset (IBM-PINO)  
Netherlands PIN-1 (NL-PIN-1).  
IBM German Bank Pool Institution PIN  
VISA PIN Validation Value (PVV)  
Interbank PIN  
In the description of the financial PIN verbs, these terms are employed:  
A-PIN  
The quantity derived from a function of the account number,  
PIN-generating key (PINGEN or PINVER), and other inputs such as a  
decimalization table.  
C-PIN  
O-PIN  
T-PIN  
The quantity that a customer should use to identify himself; in general,  
this can be a customer-selected or institution-assigned quantity.  
A quantity, sometimes called an offset, that relates the A-PIN to the  
C-PIN as permitted by certain methods.  
The trial PIN presented for verification.  
E-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
IBM 3624 PIN-Calculation Method  
The IBM 3624 PIN-calculation method calculates a PIN that is from 4 to 16 digits in  
length.  
The IBM 3624 PIN-calculation method consists of the following steps to create the  
A-PIN:  
1. Encrypt the hexadecimal validation data with a key that has a control vector  
that specifies the PINGEN (or PINVER) key type to produce a 64-bit quantity.  
2. Convert the character format decimalization table to an equivalent array of  
sixteen 4-bit hexadecimal digits, and use the decimalization table to convert the  
hexadecimal digits (X'0' to X'F') of the encrypted validation data to decimal  
digits (X'0' to X'9'). Call this result newpin.  
Let newpin(i), decimalization_table(i), and encrypted_validation_data(i) each  
represent the (i)th hexadecimal digit in each quantity.  
The digits of newpin are obtained by the following procedure:  
For i = 1 to 16 do:  
j := encrypted_validation_data(i)  
newpin(i) := decimalization_table(j)  
end do  
3. Select the n leftmost decimal digits of newpin, where n is the PIN length. The  
result is an n-digit calculated A-PIN. The PIN must be from 4 to 16 digits in  
length.  
Example:  
Encrypted validation data = E5C1BD67B66AE7C6  
Decimalization table index = ꢃ123456789ABCDEF  
Decimalization table  
Newpin  
= 8351296477461538  
= 3913656466643416  
= 6  
PIN length  
Calculated A-PIN  
= 391365 (leftmost 6 digits of newpin)  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-3  
CCA Release 2.54  
IBM 3624 PIN Offset Calculation Method  
The IBM 3624 PIN Offset calculation method is the same as the IBM 3624  
PIN-calculation method except that a step is added after the A-PIN is calculated to  
calculate or use an offset, O-PIN:  
To calculate an O-PIN, the additional step subtracts (digit-by-digit, modulo 10,  
with no carry) the calculated A-PIN from the customer-selected C-PIN.  
The result is an O-PIN (offset) of n decimal digits, where n is the PIN length  
and must be in the range from 4 to 16. The PIN_check_length parameter  
specifies n as the low-order (rightmost) digits of the n-digit PIN offset. The  
O-PIN (offset) is not encrypted.  
To use an offset to verify a trial PIN, the additional step adds (digit-by-digit,  
modulo 10, with no carry) the offset to the calculated A-PIN. The result is  
compared to the customer-entered trial PIN (T-PIN).  
Notes:  
1. The digit-wise subtraction is defined only for digits in the range from  
X'0' to X'9'. Any other value is not valid and causes processing to fail.  
2. The length of the offset depends on the length of the PIN and must be less  
than or equal to the length of the PIN. The financial institution that issues the  
magnetic-stripe card determines the length of the PIN offset, which you specify  
with the PIN_check_length parameter.  
3. When the length of the PIN offset is less than the length of the calculated PIN,  
the subtraction or addition begins with the low order PIN digit.  
E-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Netherlands PIN-1 Calculation Method  
The Netherlands PIN-1 (NL-PIN-1) calculation method calculates a PIN that is 4  
digits in length.  
The method consists of the following steps to create the A-PIN:  
1. Encrypt the hexadecimal validation data with a key that has a control vector  
that specifies the PINGEN (or PINVER) key type to produce a 64-bit quantity.  
2. Convert the character format decimalization table to an equivalent array of  
sixteen 4-bit hexadecimal digits, and use the decimalization table to convert the  
third through sixth hexadecimal digits (X'0' to X'F') of the encrypted validation  
data to decimal digits (X'0' to X'9'). Call this result newpin.  
Note: The application must specify a decimalization table of 0, 1, ...9, 0, ...5.  
Let A-PIN(i), decimalization_table(i), and encrypted_validation_data(i) each  
represent the (i)th hexadecimal digit in each quantity.  
The digits of A-PIN are obtained by the following procedure:  
For i = 3 to 6 do:  
j := encrypted_validation_data(i)  
A-PIN(i-2) := decimalization_table(j)  
end do  
3. The O-PIN offset, also a 4 digit quantity, when added digit-wise modulo 10 to  
the A-PIN results in the C-PIN, customer-used-PIN value.  
Example:  
Encrypted validation data = 8325A637B66EA7A8  
Decimalization table index = ꢃ123456789ABCEDF  
Decimalization table  
A-PIN  
= ꢃ123456789ꢃ12345  
= 25ꢃ6  
O-PIN  
= 9957  
C-PIN, Customer PIN  
= 1453  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-5  
CCA Release 2.54  
IBM German Bank Pool Institution PIN-Calculation Method  
The IBM German Bank Pool Institution PIN calculation method calculates an  
institution PIN that is 4 digits in length.  
The German Bank Pool Institution PIN-calculation method consists of the following  
steps:  
1. Encrypt the hexadecimal validation data with an institution key that has a  
control vector that specifies the PINGEN (or PINVER) key type to get a 64-bit  
quantity.  
2. Convert the character format decimalization table to an equivalent array of  
sixteen 4-bit hexadecimal digits, and use the decimalization table to convert the  
first 6 hexadecimal digits (X'0' to X'F') of the encrypted validation data to  
decimal digits (X'0' to X'9'). Call this result newpin.  
The digits of newpin are obtained by the following procedure:  
For i = 1 to 6 do:  
j := encrypted_validation_data(i)  
newpin(i) := decimalization_table(j)  
end do  
3. Select the 4 rightmost digits of newpin. The result is a 4-digit intermediate PIN.  
4. If the first digit of the intermediate PIN is 0, assign 1 to the first digit of the  
institution PIN, and assign the remaining 3 digits of the intermediate PIN to the  
institution PIN.  
If the first digit of the intermediate PIN is not 0, assign the value of the  
intermediate PIN to the institution PIN.  
The PIN is not encrypted.  
Example:  
Encrypted validation data = E5A4FD67B66AE7C6  
Decimalization table index = ꢃ123456789ABCDEF  
Decimalization table  
Newpin  
Intermediate PIN  
Institution PIN  
= ꢃ123456789ꢃ12345  
= 45ꢃ453  
= ꢃ453 (4 rightmost digits of newpin)  
= 1453 (first digit is changed to 1  
because the intermediate PIN had a  
first digit of ꢃ)  
E-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
VISA PIN Validation Value (PVV) Calculation Method  
The VISA-PVV calculation method calculates a VISA-PVV that is 4 digits in length.  
The VISA PIN Validation Value (PVV) calculation method consists of the following  
steps:  
1. Let X denote the transaction_security_parameter element. This parameter is  
the result of concatenating the 12-numeric-digit generating data (a portion of  
the account number) with the 4-numeric-digit customer-entered PIN. (C-PIN  
when calculating the PVV, or T-PIN when validating a transaction.)  
2. Encrypt X with the double-length key that has a control vector that specifies the  
PINGEN (or PINVER) key type to get 16 hexadecimal digits (64 bits).  
3. Perform decimalization on the result of the previous step by scanning the 16  
hexadecimal digits from left to right, skipping any digit greater than X'9', until 4  
decimal digits (digits that have values from X'0' to X'9') are found.  
If all digits are scanned but 4 decimal digits are not found, repeat the scanning  
process, skipping all digits that are X'9' or less and selecting the digits that  
are greater than X'9'. Subtract 10 (X'A') from each digit selected in this  
scan.  
4. Concatenate and use the resulting digits for the PVV. The PVV is not  
encrypted.  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-7  
CCA Release 2.54  
Interbank PIN-Calculation Method  
The Interbank PIN-calculation method consists of the following steps:  
1. Let X denote the transaction_security_parameter element converted to an array  
of sixteen 4-bit numeric values. This parameter consists of (in the following  
sequence) the 11 rightmost digits of the customer PAN (excluding the check  
digit), a constant of 6, a 1-digit key indicator, and a 3-digit validation field.  
2. Encrypt X with the double-length PINGEN (or PINVER) key to get 16  
hexadecimal digits (64 bits).  
3. Perform decimalization on the result of the previous step by scanning the 16  
hexadecimal digits from left to right, skipping any digit greater than X'9', until 4  
decimal digits (for example, digits that have values from X'0' to X'9') are  
found.  
If all digits are scanned but 4 decimal digits are not found, repeat the scanning  
process, skipping all digits that are X'9' or less and selecting the digits that  
are greater than X'9'. Subtract 10 (X'A') from each digit selected in this  
scan.  
If the 4 digits that were found are all zeros, replace the 4 digits with 0100.  
4. Concatenate and use the resulting digits for the Interbank PIN. The 4-digit PIN  
consists of the decimal digits in the sequence in which they are found. The  
PIN is not encrypted.  
E-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
PIN-Block Formats  
The PIN verbs support one or more of the following PIN-block formats:  
IBM 3624 format  
ISO-0 format (same as the ANSI X9.8, VISA-1, and ECI formats).  
ISO-1 format (same as the ECI-4 format)  
ISO-2 format  
3624 PIN-Block Format  
The 3624 PIN-block format supports a PIN from 1 to 16 digits in length. A PIN that  
is longer than 16 digits is truncated on the right.  
The following is the 3624 PIN-block format:  
1 2 3 4 5 6 7 8 9 1ꢃ 11 12 13 14 15 16  
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐  
│ P │P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│P/X│  
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘  
Figure E-2. 3624 PIN-Block Format  
where:  
P
Is a PIN digit, which is a 4-bit value from X'0' to X'9'. The values of  
the PIN digits are independent.  
P/X Is a PIN digit or a pad value. A PIN digit has a 4-bit value from  
X'0' to X'9'. A pad value has a 4-bit value from X'0' to X'F' and  
must be different from any PIN digit. The number of pad values for this  
format is in the range from 0 to 15, and all the pad values must have  
the same value.  
Example:  
PIN = ꢃ123456, Pad = X'E'.  
PIN block = X'ꢃ123456EEEEEEEEE'.  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-9  
CCA Release 2.54  
ISO-0 PIN-Block Format  
An ISO-0 PIN-block format is equivalent to the ANSI X9.8, VISA-1, and ECI-1  
PIN-block formats. The ISO-0 PIN-block format supports a PIN from 4 to 12 digits  
in length. A PIN that is longer than 12 digits is truncated on the right.  
The following are the formats of the intermediate PIN-block, the PAN block, and the  
ISO-0 PIN-block:  
1 2 3 4 5 6 7 8 9 1ꢃ 11 12 13 14 15 16  
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐  
│ ꢃ │ L │ P │ P │ P │ P │P/F│P/F│P/F│P/F│P/F│P/F│P/F│P/F│ F │ F │  
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘  
Intermediate PIN-Block = IPB  
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐  
│ ꢃ │ ꢃ │ ꢃ │ ꢃ │PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│  
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘  
PAN Block  
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐  
│ │ │ │ │ P │ P │P/F│P/F│P/F│P/F│P/F│P/F│P/F│P/F│ F │ F │  
│ ꢃ │ L │ P │ P │XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│  
│ │ │ │ │PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│  
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘  
PIN Block = IPB XOR PAN Block  
Figure E-3. ISO-0 PIN-Block Format  
where:  
0
L
P
Is the value X'0'.  
Is the length of the PIN, which is a 4-bit value from X'4' to X'C'.  
Is a PIN digit, which is a 4-bit value from X'0' to X'9'. The values of  
the PIN digits are independent.  
P/F  
Is a PIN digit or pad value. A PIN digit has a 4-bit value from  
X'0' to X'9'. A pad value has a 4-bit value of X'F'. The number of  
pad values in the intermediate PIN block (IPB) is from 2 to 10.  
F
Is the value X'F' for the pad value.  
PAN Is twelve 4-bit digits that represent one of the following:  
The rightmost 12 digits of the primary account-number (excluding  
the check digit) if the format of the PIN block is ISO-0, ANSI X9.8,  
VISA-1, or ECI-1  
Each PAN digit has a value from X'0' to X'9'.  
The PIN block is the result of exclusive-ORing the 64-bit IPB with the 64-bit PAN  
block.  
Example:  
L= 6, PIN = 123456, Personal Account Number = 111222333444555  
ꢃ6123456FFFFFFFF : IPB  
ꢃꢃꢃꢃ222333444555 : PAN block for ISO-ꢃ (ANSI X9.8, VISA-1, ECI-1) format  
ꢃ6121675CCBBBAAA : PIN block for ISO-ꢃ (ANSI X9.8, VISA-1, ECI-1) format.  
E-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
ISO-1 PIN-Block Format  
The ISO-1 PIN-block format is equivalent to an ECI-4 PIN-block format. The ISO-1  
PIN-block format supports a PIN from 4 to 12 digits in length. A PIN that is longer  
than 12 digits is truncated on the right.  
The following is the ISO-1 PIN-block format:  
1 2 3 4 5 6 7 8 9 1ꢃ 11 12 13 14 15 16  
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐  
│ 1 │ L │ P │ P │ P │ P │P/R│P/R│P/R│P/R│P/R│P/R│P/R│P/R│ R │ R │  
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘  
Figure E-4. ISO-1 PIN-Block Format  
where:  
1
L
P
Is the value X'1'.  
Is the length of the PIN, which is a 4-bit value from X'4' to X'C'.  
Is the PIN digit, which is a 4-bit value from X'0' to X'9'. The values  
of the PIN digits are independent.  
R
Is a random digit, which is a value from X'0' to X'F'. Typically, this  
should be used for predetermined transaction unique data such as a  
sequence number.  
P/R  
Is a PIN digit or a random digit, depending on the value of PIN length  
L. The number of random digits is in the range from 2 to 10, and the  
random digits can be different.  
Example:  
L=6, PIN = 123456, L = X'6'.  
PIN block = X'161234566ABCFDE1', where X'6', X'A', X'B', X'C', X'F',  
X'D', X'E', and X'1' are the random fillers.  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-11  
CCA Release 2.54  
ISO-2 PIN-Block Format  
The ISO-2 PIN-block format supports a PIN from 4 to 12 digits in length. A PIN  
that is longer than 12 digits is truncated on the right.  
The following is the ISO-2 PIN-block format:  
1 2 3 4 5 6 7 8 9 1ꢃ 11 12 13 14 15 16  
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐  
│ 2 │ L │ P │ P │ P │ P │P/F│P/F│P/F│P/F│P/F│P/F│P/F│P/F│ F │ F │  
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘  
Figure E-5. ISO-2 PIN-Block Format  
where:  
1
L
P
Is the value X'1'.  
Is the length of the PIN, which is a 4-bit value from X'4' to X'C'.  
Is the PIN digit, which is a 4-bit value from X'0' to X'9'. The values  
of the PIN digits are independent.  
F
Is a fill digit valued to X'F'.  
P/F  
Is a PIN digit or a fill digit.  
Example:  
L=6, PIN = 123456, L = X'6'.  
PIN block = X'26123456FFFFFFFF'.  
E-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
UKPT Calculation Methods  
This section describes the calculation methods for deriving the  
unique-key-per-transaction (UKPT) key according to ANSI X9.24 and performing  
the special encryption and special decryption processes.1  
Deriving an ANSI X9.24 Unique-Key-Per-Transaction Key  
To determine the current-transaction encrypting key used by a terminal which is  
encrypting PIN-blocks under the ANSI X9.24 standard, the ANSI X9.24 algorithm  
uses a derivation key and the Current Key Serial Number (CKSN) as inputs.  
The derivation key must be a double-length KEYGENKY key-type with the  
UKPT control vector bit set on. The right half of the derivation key cannot be  
the same as the left half of the derivation key.  
The initial key serial number is a 59-bit value that contains terminal  
identification information that is unique amoung the set of terminals initialized  
under a given derivation key.  
The encryption counter is a 21-bit counter value. The value in the counter is  
set to 0 when the terminal is initialized. The counter increments each time the  
terminal performs a PIN-block encryption. The counter increments such that a  
maximum of 10 bits can be set on; the counter can record 1000000  
encryptions. When the maximum counter value is reached, the terminal is  
disabled.  
The current key serial number (CKSN) is the concatenation of the initial key  
serial number and the encryption counter. This concatenation is an 80-bit  
(10-byte) value.  
The calculation method consists of the following steps:  
1. Calculate the initial encrypting key. To calculate the initial encrypting key, do  
the following:  
a. Move the leftmost 8 bytes of the current key serial number to a work area  
(Ca).  
b. Perform an AND operation with the last byte of Ca and X'EO'. This  
operation clears the high-order bits of the encryption counter. The value  
that Ca now contains is the initial serial number that was loaded when the  
PIN keypad was initialized.  
c. Encrypt Ca, using the left half of the derivation key; name the result Cb.  
d. Decrypt Cb, using the right half of the derivation key; name the result Cc.  
e. Encrypt Cc, using the left half of the derivation key; name the result Cd. Cd  
is the initial PIN encrypting key that was loaded when the terminal was  
initialized.  
f. Rename Cd to be Ka, the initial PIN encrypting key.  
2. Calculate the current encrypting key. To calculate the current encrypting key,  
do the following:  
1
This material is adapted from the VISA Point-of-Sale Equipment Requirements: PIN Processing and Data Authentication  
publication.  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-13  
CCA Release 2.54  
a. Move the rightmost 8 bytes of the current key serial number to a work area  
(Wa).  
b. Move the rightmost 3 bytes of Wa to another work area (Ca).  
c. Perform an AND operation with the rightmost 3 bytes of Wa with  
X'E00000'. This operation clears the encryption counter from Wa.  
d. Perform an AND operation with Ca and X'1FFFFF'. This operation clears  
the low-order bits of the initial serial number from the encryption counter.  
e. Initialize a 3-byte area to X'100000'; name the result Sa.  
f. Initialize a 1-byte counter to X'00'; name the result Ba.  
g. Test each bit of the encryption counter, looking for B'1' bits by doing the  
following loop:  
When a B'1' bit is found, it ORs this bit into the initial serial number. It  
then special encrypts the result with Ka.  
The result of this special encryption is the new Ka.  
When all B'1' bits are processed, a variant of the value in Ka becomes  
the current encrypting key.  
Use the following procedure to do this loop:  
DO i=1 to 21  
a. IF (Ca AND Sa) is not equal to ꢃ THEN DO  
1) ADD 1 to Ba  
2) IF Ba > 1ꢃ THEN exit algorithm with an error  
indicating too many B'1' bits were set in the encryption  
counter  
3) OR Sa into the rightmost 3 bytes of Wa;  
store the result in Ta  
4) XOR Ta and Ka; store the result in Tb  
5) Encrypt Tb with Ka; store the result in Tc  
6) XOR Tc with Ka; store the result in Ka  
b. END IF  
c. Shift Sa one bit to the right.  
Fill in on the left with a B'ꢃ' bit.  
END DO  
The value in Ka is the current encrypting key.  
Note: The CCA implementation does not adjust key parity on any of the  
bytes of the derived encrypting key before encrypting them under its master  
key. Parity adjustment is not done because the key value is used in two  
XOR operations during the special decrypt process of recovering the clear  
PIN-block.  
The following is an example of calculating the initial PIN encrypting key:  
Derivation key = X'5152 5457 585B 5D5E 6162 6467 686B 6D6E'  
Current key serial number = X'ꢃ123 4567 89AB CDFꢃ ꢃꢃꢃ1'  
Ca = X'ꢃ123 4567 89AB CDEꢃ'  
Cb = X'6497 E2F4 C59D 952E'  
Cc = X'ꢃ163 CE85 359F F599'  
Initial PIN encrypting key = Ka1 = Cd = X'21EE 7Cꢃ8 DBE8 2ꢃAB'  
E-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
The following is an example of calculating the current PIN encrypting key:  
Wa = X'4567 89AB CDEꢃ ꢃꢃꢃꢃ'  
Ca = X'1ꢃꢃꢃ1'  
Sa1 = X'1ꢃꢃꢃꢃꢃ'  
Ta = X'4567 89AB CDFꢃ ꢃꢃꢃꢃ'  
Tb1 = X'6489 F5A3 1618 2ꢃAB'  
Tc1 = X'F9AC C638 1939 44BC'  
Ka12 = X'D842 BA3ꢃ C2D1 6417'  
.
.
.
Sa = X'ꢃꢃꢃꢃꢃ1'  
Ta20 = X'4567 89AB CDFꢃ ꢃꢃꢃ1'  
Tb20 = X'9D25 339B ꢃF21 6416'  
Tc20 = X'BF49 836E AE2A ꢃ42A'  
Ka2200 = X'67ꢃB 395E 6CFB 6ꢃ3D'  
Current PIN encrypting key = X'67ꢃB 395E 6CFB 6ꢃC2'  
Performing the Special Encryption and Special Decryption Processes  
The special encryption process consists of the following steps:  
1. Name the derived unique key for the current transaction Ku.  
2. Name the clear PIN-block that was built from the user-entered PIN Pc.  
3. Perform an XOR operation with the rightmost byte of Ku and X'FF' to produce  
a variant of the key; name the result Kuv.  
4. Perform an XOR operation with Kuv and Pc; store the result in T1.  
5. Encrypt T1 with Kuv; store the result in T2.  
6. Perform an XOR operation with Kuv; store the result in Pe.  
The value in Pe is the encrypted PIN-block that the POS terminal will send.  
The special decryption process consists of these steps, in reverse.  
The following is an example of the special encryption process:  
Current encrypting key = Ku = X'67ꢃB 395E 6CFB 6ꢃ3D'  
User-entered PIN = 1234  
User’s primary account-number = X'4ꢃ12 3456 789ꢃ'  
Clear PIN-block (unformatted) = X'ꢃ412 34FF FFFF FFFF'  
Primary account-number (formatted) = X'ꢃꢃꢃꢃ 4ꢃ12 3456 789ꢃ'  
Clear PIN-block (ANSI format) = Pc = X'ꢃ412 74ED CBA9 876F'  
Variant of PIN encrypting key = Kuv = X'67ꢃB 395E 6CFB 6ꢃC2'  
T1 = X'6319 4DB3 A752 E7AD'  
T2 = X'5145 3CA3 E474 2148'  
Pe = X'364E ꢃ5FD 888F 418A'  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-15  
CCA Release 2.54  
CVV and CVC Method  
Figure E-62 shows the method used to generate a card-verification value (CVV) for  
track 2. Each (decimal) digit is represented as a 4-bit, binary value and packed two  
digits per byte.  
┌─────────────────┬──────────┬───────────────┬────────────────────┐  
PAN  
│ Exp Date │ Service Code │  
'ꢃ' pad  
│ 13 or 16 digits │ 4 digits │  
3 digits  
│ Pad to 16 bytes  
└─────────────────┴──────────┴───────────────┴────────────────────┘  
│ꢃ  
15│  
└─────────────────────────────────┬───────────────────────────────┘  
┌──────────┴────────────────────┐  
│ Divide into two 8-byte fields │  
Digits are represented  
in 4-bit groups, 2  
groups per byte.  
└─────┬─────────────────┬───────┘  
┌──────┴──────┐  
┌─────┴───────┐  
Left  
└──────┬──────┘  
┌─────┴─────┐  
Right  
└─────┬───────┘  
Key A ──────┤ Encipher │  
└─────┬─────┘  
┌──┴──┐  
│ XOR ├──────────────┘  
└──┬──┘  
┌─────┴─────┐  
Key A ──────┤ Encipher │  
└─────┬─────┘  
┌─────┴─────┐  
Key B ──────┤ Decipher │  
└─────┬─────┘  
┌─────┴─────┐  
Key A ──────┤ Encipher │  
└─────┬─────┘  
┌─────┴─────────────────────────────────┐  
│Decimalize Result  
│ 1) Select only ꢃ-9 left to right  
│ 2) Left justify result of 1 in field │  
│ 3) Select only A-F left to right  
│ 4) Subtract 1ꢃ from each in 3  
│ 5) Concatenate to result from 2  
│ 6) CVV is the left 1 to 5 digits.  
└───────────────────────────────────────┘  
Figure E-6. CVV Track 2 Algorithm  
At the security API, the CVV_Generate and CVV_Verify verbs require two key  
identifiers, key-A and key-B, as defined in the CVV method. The identifiers can be  
key labels or internal key-tokens.  
The key-A and key-B key pair can include the following key types:  
1. Both keys can be DATA keys.  
2. Both keys can be MAC-class keys with the ANY subtype.  
3. Both keys can be MAC-class keys with the KEY-A and KEY-B subtypes as  
appropriate.  
The CVV_Generate verb requires the control-vector bit (bit 20) to be set to 1. The  
CVV_Verify verb requires the control-vector bit (bit 21) to be set to 1.  
2
Adapted from VisaNet Electronic Value Exchange Standards Manual, pages AA-8 and AA-9.  
E-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
VISA and EMV-Related Smart Card Formats and Processes  
The VISA and EMV specifications for performing secure messaging with an EMV  
compliant smart card are covered in these documents:  
EMV 2000 Integrated Circuit Card Specification for Payment Systems Version  
4.0 (EMV4.0) Book 2  
Design VISA Integrated Circuit Card Specification Manual.  
Book 2, Annex A1.3, describes how a smart-card, card-specific authentication code  
is derived from a card-issuer-supplied authentication key (MAC-MDK).  
Annex A1.3 describes how a smart-card, card-specific session key is derived from  
a card-issuer-supplied PIN-block-encryption key (ENC-MDK). The encryption key is  
derived using a “tree-based-derivation” technique. IBM CCA offers two variations of  
the tree-based technique (TDESEMV2 and TDESEMV4), and a third technique  
CCA designates TDES-XOR.  
In addition, Book 2 describes construction of the PIN block sent to an EMV card to  
initialize or update the user's PIN.  
Design VISA Integrated Circuit Card Specification Manual, Annex B.4, contains a  
description of the session-key derivation technique CCA designates TDES-XOR.  
Augmented by the above-mentioned documentation, the relevant processes are  
described in these sections:  
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  
Derivation of the EMV TDESEMVn tree-based session-key  
PIN-Block self-encryption.  
Derivation of the Smart-Card-Specific Authentication Code  
To ensure that an original or replacement PIN is received from an authorized  
source, the EMV PIN-transport PIN-block incorporates an authentication code.  
The authentication code is the rightmost four bytes resulting from the ECB-mode  
triple-DES encryption of (the first) eight bytes of card specific data.  
Constructing the PIN-block for Transporting an EMV Smart-Card PIN  
The PIN block is used to transport a new PIN value. The PIN block also contains  
an authentication code, and optionally the “current” PIN value, enabling the smart  
card to further ensure receipt of a valid PIN value. To enable incorporation of the  
PIN block into the a message for an EMV smart-card, the PIN block is padded to  
16 bytes prior to encryption.  
PINs of length 4 to 12 digits are supported.  
PIN block construction:  
1. Form three 8-byte, 16-digit blocks, -1, -2, and -3, and set all digits to X'0'.  
2. Replace the rightmost four bytes of block-1 with the authentication code  
described in the previous section.  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-17  
CCA Release 2.54  
3. Set the second digit of block-2 to the length of the new PIN (4 to 12), followed  
by the new PIN, and padded to the right with X'F'.  
4. Include any current PIN by placing it into the leftmost digits of block-3.  
5. Exclusive-OR blocks -1, -2, and -3 to form the 8-byte PIN block.  
6. Pad the PIN block with other portions of the message for the smart card:  
Prepend X'80'  
Append X'80'  
Append and additional six bytes of X'00'.  
The resulting message is ECB-mode triple-encrypted with an appropriate session  
key.  
Derivation of the CCA TDES-XOR Session Key  
In the Diversified_Key_Generate and PIN_Change/Unblock verbs, the TDES-XOR  
process first derives a smart-card-specific intermediate key from the issuer-supplied  
ENC-MDK key and card-specific data. (This intermediate key is also used in the  
TDESEMV2 and TDESEMV4 processes. See the next section.) The intermediate  
key is then modified using the application transaction counter (ATC) value supplied  
by the smart card.  
The double-length session-key creation steps:  
1. Obtain the left-half of an intermediate key by ECB-mode triple-DES encrypting  
the (first) eight bytes of card specific data using the issuer-supplied ENC-MDK  
key.  
2. Again using the ENC-MDK key, obtain the right-half of the intermediate key by  
ECB-mode triple-DES encrypting:  
The second eight-bytes of card-specific derivation data when 16-bytes have  
been supplied, else  
The exclusive-OR of the supplied 8-bytes of derivation data with  
X'FFFFFFFF FFFFFFFF'.  
3. Pad the ATC value to the left with six bytes of X'00' and exclusive-OR the  
result with the left-half of the intermediate key to obtain the left-half of the  
session key.  
4. Obtain the one's complement of the ATC by exclusive-ORing the ATC with  
X'FFFF'. Pad the result on the left with six bytes of X'00'. Exclusive-OR the  
8-byte result with the right-half of the intermediate key to obtain the right-half of  
the session key.  
Derivation of the EMV TDESEMVn Tree-Based Session-Key  
In the Diversified_Key_Generate and PIN_Change/Unblock verbs, the TDESEMV2  
and TDESEMV4 keywords call for the creation of the session key with this process:  
1. The intermediate key is obtained as explained above for the TDES-XOR  
process.  
2. Combine the intermediate key with the two-byte Application Transaction  
Counter (ATC) and an optional Initial Value. The process is defined in the  
EMV 2000 Integrated Circuit Card Specification for Payment Systems Version  
4.0 (EMV4.0) Book 2 Book 2, Annex A1.3.  
E-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
TDESEMV2 causes processing with a branch factor of 2 and a height of  
16.  
TDESEMV4 causes processing with a branch factor of 4 and a height of 8.  
PIN-Block Self-encryption  
In the Secure_Messaging_for_PINs (CSNBSPN) verb, you can use the SELFENC  
rule-array keyword to specify that the eight-byte PIN block shall be used as a DES  
key to encrypt the PIN block. The verb appends the self-encrypted PIN block to  
the clear PIN-block in the output message.  
Appendix E. Financial System Verbs Calculation Methods and Data Formats E-19  
CCA Release 2.54  
E-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix F. Verb List  
This appendix lists the verbs supported by the CCA Support Program feature for  
the IBM 4758 PCI Cryptographic Coprocessor.  
Figure F-1 lists each verb by the verb’s pseudonym and entry-point name and  
shows the operating environment under which the verb is supported. A check () in  
the operating environment column means that the verb is available for use in that  
operating environment.  
Figure F-1 (Page 1 of 3). Security API Verbs in Supported Environments  
Pseudonym  
Entry-Point  
OS/2  
AIX  
NT  
OS/400  
Page  
DES Key Processing and Key Storage Verbs  
Clear_Key_Import  
CSNBCKI  
CSNBCVG  
CSNBCVT  
CSNBCVE  
CSNBDKX  
CSNBDKM  
CSNBDKG  
CSNBKEX  
CSNBKGN  
CSNBKIM  
CSNBKPI  
CSNBKSI  
CSNBKRC  
CSNBKRD  
CSNBKRL  
CSNBKRR  
CSNBKRW  
CSNBKYT  
CSNBKTB  
CSNBKTC  
CSNBKTP  
CSNBKTR  
CSNBCKM  
CSNBRNG  
CSNDPKD  
CSNDPKE  
CSNDSYX  
CSNDSYG  
CSNDSYI  
CSNBPEX  
5-22  
5-24  
5-26  
5-29  
5-31  
5-33  
5-35  
5-42  
5-44  
5-51  
5-54  
2-50  
7-4  
Control_Vector_Generate  
Control_Vector_Translate  
Cryptographic_Variable_Encipher  
Data_Key_Export  
Data_Key_Import  
Diversified_Key_Generate  
Key_Export  
Key_Generate  
Key_Import  
Key_Part_Import  
Key_Storage_Initialization  
DES_Key_Record_Create  
DES_Key_Record_Delete  
DES_Key_Record_List  
DES_Key_Record_Read  
Key_Record_Write  
7-5  
7-7  
7-9  
7-10  
5-58  
5-61  
5-64  
5-66  
5-69  
5-71  
5-91  
5-73  
5-75  
5-78  
5-81  
5-86  
5-90  
Key_Test  
Key_Token_Build  
Key_Token_Change  
Key_Token_Parse  
Key_Translate  
Multiple_Clear_Key_Import  
Random_Number_Generate  
PKA_Decrypt  
PKA_Encrypt  
PKA_Symmetric_Key_Export  
PKA_Symmetric_Key_Generate  
PKA_Symmetric_Key_Import  
Prohibit_Export  
Copyright IBM Corp. 1997, 2005  
F-1  
CCA Release 2.54  
Figure F-1 (Page 2 of 3). Security API Verbs in Supported Environments  
Pseudonym  
Entry-Point  
OS/2  
AIX  
NT  
OS/400  
Page  
Data Confidentiality and Data Integrity Verbs  
Decipher  
CSNBDEC  
CSNDDSG  
CSNDDSV  
CSNBENC  
CSNBMGN  
CSNBMVR  
CSNBMDG  
CSNBOWH  
6-5  
4-4  
Digital_Signature_Generate  
Digital_Signature_Verify  
Encipher  
4-7  
6-8  
MAC_Generate  
6-11  
6-14  
4-10  
4-13  
MAC_Verify  
MDC_Generate  
One_Way_Hash  
Coprocessor Control Verbs  
Access_Control_Initialization  
Access_Control_Maintenance  
Cryptographic_Facility_Control  
Cryptographic_Facility_Query  
Cryptographic_Resource_Allocate  
Cryptographic_Resource_Deallocate  
Key_Storage_Designate  
Logon_Control  
CSUAACI  
CSUAACM  
CSUACFC  
CSUACFQ  
CSUACRA  
CSUACRD  
CSUAKSD  
CSUALCT  
CSUAMKD  
CSNBMKP  
2-21  
2-24  
2-30  
2-34  
2-44  
2-46  
2-48  
2-52  
2-55  
2-59  
Master_Key_Distribution  
Master_Key_Process  
RSA Key Administration and Key Storage Verbs  
Key_Storage_Initialization  
PKA_Key_Generate  
CSNBKSI  
2-50  
3-7  
CSNDPKG  
CSNDPKI  
CSNDPKB  
CSNDKTC  
CSNDKRC  
CSNDKRD  
CSNDKRL  
CSNDKRR  
CSNDKRW  
CSNDPKX  
CSNDPKH  
CSNDPKR  
CSNDRKD  
CSNDRKL  
PKA_Key_Import  
3-11  
3-14  
3-22  
7-11  
7-13  
7-15  
7-17  
7-19  
3-24  
3-26  
3-28  
7-21  
7-22  
PKA_Key_Token_Build  
PKA_Key_Token_Change  
PKA_Key_Record_Create  
PKA_Key_Record_Delete  
PKA_Key_Record_List  
PKA_Key_Record_Read  
PKA_Key_Record_Write  
PKA_Public_Key_Extract  
PKA_Public_Key_Hash_Register  
PKA_Public_Key_Register  
Retained_Key_Delete  
Retained_Key_List  
F-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure F-1 (Page 3 of 3). Security API Verbs in Supported Environments  
Pseudonym  
Entry-Point  
OS/2  
AIX  
NT  
OS/400  
Page  
Financial Services Support Verbs  
Clear_PIN_Encrypt  
CSNBCPE  
CSNBPGN  
CSNBCPA  
CSNBCSG  
CSNBCSV  
CSNBEPG  
CSNBPTR  
CSNBPVR  
CSNBKET  
CSNBPCU  
CSNBSKY  
CSNBSPN  
CSNDSBC  
CSNDSBD  
8-15  
8-18  
8-21  
8-27  
8-30  
8-33  
8-37  
8-42  
8-49  
8-52  
8-59  
8-62  
8-66  
8-70  
Clear_PIN_Generate  
Clear_PIN_Generate_Alternate  
CVV_Generate  
CVV_Verify  
Encrypted_PIN_Generate  
Encrypted_PIN_Translate  
Encrypted_PIN_Verify  
Key_Encryption_Translate  
PIN_Change/Unblock  
Secure_Messaging_for_Keys  
Secure_Messaging_for_PINs  
SET_Block_Compose  
SET_Block_Decompose  
|
Appendix F. Verb List F-3  
CCA Release 2.54  
F-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Appendix G. Access-Control-Point Codes  
The table in this appendix lists the CCA access-control commands (“control  
points”). The role to which a user is assigned determines the commands available  
to that user.  
Important: By default, you should disable commands. Do not enable a command  
unless you know why you are enabling it.  
The table includes the following columns:  
Offset  
The hexadecimal offset for the command; offsets between  
X'0000' and X'FFFF' not listed in this table are reserved.  
Command Name  
Verb Name  
The name of the command required by the following verbs.  
The names of the verbs that require that command to be  
enabled; for example, the Encipher (CSNBENC) verb will fail  
without permission to use the Encipher command.  
Entry  
The entry_point_name of the verb.  
Usage  
Usage recommendations for the command. The  
abbreviations in this column are explained at the bottom of  
the page.  
See the “Required Commands” section towards the end of each verb description for  
access control guidance for each verb.  
Copyright IBM Corp. 1997, 2005  
G-1  
CCA Release 2.54  
Figure G-1 (Page 1 of 4). Supported CCA Commands  
Offset  
Command Name  
Verb Name  
Entry  
Usage  
X'000E' Encipher  
Encipher  
CSNBENC  
CSNBDEC  
CSNBMGN  
CSNBMVR  
CSNBKIM  
CSNBKEX  
SNBMKP  
CSNBMKP  
CSNBMKP  
CSNBKPI  
CSNBKPI  
O
X'000F' Decipher  
Decipher  
O
O
X'0010' Generate MAC  
MAC_Generate  
MAC_Verify  
X'0011' Verify MAC  
O
X'0012' Reencipher to Master Key  
X'0013' Reencipher from Master Key  
X'0018' Load First Master Key Part  
X'0019' Combine Master Key Parts  
X'001A' Set Master Key  
Key_Import  
O
Key_Export  
O
Master_Key_Process  
Master_Key_Process  
Master_Key_Process  
SC, SEL  
SC, SEL  
SC, SEL  
SC, SEL  
SC, SEL  
R
X'001B' Load First Key Part  
X'001C' Combine Key Parts  
X'001D' Compute Verification Pattern  
Key_Part_Import  
Key_Part_Import  
Key_Test  
CSNBKYT  
CSNBKSI  
Key_Storage_Initialization  
DES_Key_Record_Create  
DES_Key_Record_Delete  
DES_Key_Record_List  
DES_Key_Record_Read  
DES_Key_Record_Write  
PKA_Key_Record_Create  
PKA_Key_Record_Delete  
PKA_Key_Record_List  
PKA_Key_Record_Read  
PKA_Key_Record_Write  
CSNBKRC  
CSNBKRD  
CSNBKRL  
CSNBKRR  
CSNBKRW  
CSNDKRC  
CSNDKRD  
CSNDKRL  
CSNDKRR  
CSNDKRW  
X'001F' Translate Key  
Key_Translate  
CSNBKTR  
CSNBMKP  
CSNBMKP  
CSNBMKP  
CSNBDKG  
CSNBDKG  
CSNBDKG  
CSNBDKG  
CSNBDKG  
CSNBDKG  
CSNBDKG  
CSNBMKP  
CSNBMKP  
CSNBMKP  
CSNBMKP  
CSNBMKP  
CSNBMDG  
CSNBKGN  
O
X'0020' Generate Random Master Key  
X'0032' Clear New Master Key Register  
X'0033' Clear Old Master Key Register  
X'0040' Generate Diversified Key (CLR8-ENC)  
X'0041' Generate Diversified Key (TDES-ENC)  
X'0042' Generate Diversified Key (TDES-DEC)  
X'0043' Generate Diversified Key (SESS-XOR)  
X'0044' Enable DKG Single Length Keys and Equal  
X'0045' Generate Diversified Key (TDES-XOR)  
X'0046' Generate Diversified Key (TDESEMVn)  
X'0053' Load First Asymmetric Master Key Part  
X'0054' Combine PKA Master Key Parts  
X'0057' Set Asymmetric Master Key  
Master_Key_Process  
O, SEL  
O, SUP  
O, SUP  
O, SEL  
O, SEL  
O, SEL  
O, SEL  
SC, SEL  
O, SEL  
O, SEL  
SC, SEL  
SC, SEL  
SC, SEL  
SC, SEL  
SC, SEL  
R
Master_Key_Process  
Master_Key_Process  
Diversified_Key_Generate  
Diversified_Key_Generate  
Diversified_Key_Generate  
Diversified_Key_Generate  
Diversified_Key_Generate  
Diversified_Key_Generate  
Diversified_Key_Generate  
Master_Key_Process  
Master_Key_Process  
Master_Key_Process  
X'0060' Clear New Asymmetric Master Key Buffer  
X'0061' Clear Old Asymmetric Master Key Buffer  
X'008A' Generate MDC  
Master_Key_Process  
Master_Key_Process  
Generate_Modification_Detection_Code  
X'008C' Generate Key Set  
Key_Generate  
O
The following codes are used in this table:  
ID  
Initial default.  
O
R
Usage of this command is optional; enable it as required for authorized usage.  
Enabling this command is recommended.  
NR  
NRP  
SC  
SEL  
SUP  
Enabling this command is not recommended.  
Enabling this command is not recommended for production.  
Usage of this command requires special consideration.  
Usage of this command is normally restricted to one or more selected roles.  
This command is normally restricted to one or more supervisory roles.  
This verb performs more than one function, as determined by the keyword in the rule_array parameter of the verb call. Not all  
functions of the verb require the command in this row.  
This verb does not always require the command in this row. Use as determined by the control vector for the key and the action  
being performed.  
G-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure G-1 (Page 2 of 4). Supported CCA Commands  
Offset  
Command Name  
Verb Name  
Entry  
Usage  
X'008E' Generate Key  
Key_Generate  
CSNBKGN  
CSNBRNG  
R
Random_Number_Generate  
X'0090' Reencipher to Current Master Key  
X'00A0' Generate Clear 3624 PIN  
Key_Token_Change  
CSNBKTC  
CSNBPGN  
CSNBCPA  
CSNBPVR  
CSNBPVR  
CSNBPVR  
CSNBPVR  
CSNBCPE  
CSNBEPG  
CSNBEPG  
R
O
O
O
O
O
O
O
O
O
Clear_PIN_Generate  
X'00A4' Generate Clear 3624 PIN Offset  
X'00AB' Verify Encrypted 3624 PIN  
Clear_PIN_Generate_Alternate  
Encrypted_PIN_Verify  
X'00AC' Verify Encrypted German Bank Pool PIN  
X'00AD' Verify Encrypted VISA PVV  
Encrypted_PIN_Verify  
Encrypted_PIN_Verify  
X'00AE' Verify Encrypted Interbank PIN  
X'00AF' Format and Encrypt PIN  
Encrypted_PIN_Verify  
Clear_PIN_Encrypt  
X'00B0' Generate Formatted and Encrypted 3624 PIN  
Encrypted_PIN_Generate  
X'00B1' Generate Formatted and Encrypted German  
Encrypted_PIN_Generate  
Bank Pool PIN  
X'00B2' Generate Formatted and Encrypted Interbank  
Encrypted_PIN_Generate  
CSNBEPG  
CSNBPTR  
CSNBPTR  
O
O
O
PIN  
X'00B3' Translate PIN with No Format-Control to No  
Encrypted_PIN_Translate  
Format-Control  
X'00B7' Reformat PIN with No Format-Control to No  
Encrypted_PIN_Translate  
Format-Control  
X'00BB' Generate Clear VISA PVV Alternate  
X'00BC' Generate PIN Change using IPINENC  
X'00BD' Generate PIN Change using OPINENC  
X'00C3' Encipher Under Master Key  
Clear_PIN_Generate_Alternate  
CSNBCPA  
CSNBPCU  
CSNBPCU  
O
O
PIN_Change/Unblock  
PIN_Change/Unblock  
O
Clear_Key_Import  
CSNBCKI  
SC  
Multiple_Clear_Key_Import  
CSNBCKM  
X'00CD' Lower Export Authority  
Prohibit_Export  
CSNBPEX  
CSNBCVT  
CSNBKGN  
CSNBCVE  
O
SC  
X'00D6' Translate Control Vector  
X'00D7' Generate Key Set Extended  
X'00DA' Encipher/Decipher Cryptovariable  
Translate_Control_Vector  
Key_Generate  
SC, SUP  
Cryptographic_Variable_Encipher  
NRP, O,  
SUP  
X'00DB' Replicate Key  
Key_Generate  
CSNBKGN  
CSNBCSG  
CSNBCSV  
CSNBPTR  
CSNDDSG  
CSNDDSV  
CSNDKTC  
CSNDPKG  
CSNDPKI  
CSNDSYX  
CSNDSYI  
CSNBOWH  
NR, SC  
X'00DF' Generate CVV  
CVV_Generate  
CVV_Verify  
O
X'00E0' Verify CVV  
O
O
X'00E1' Unique Key Per Transaction, ANSI X9.24  
X'0100' PKA96 Digital Signature Generate  
X'0101' PKA96 Digital Signature Verify  
X'0102' PKA96 Key Token Change  
X'0103' PKA96 PKA Key Generate  
X'0104' PKA96 PKA Key Import  
Encrypted_PIN_Translate  
Digital_Signature_Generate  
Digital_Signature_Verify  
PKA_Key_Token_Change  
O, SC  
O
O
PKA_Key_Generate  
O, SUP  
O, SUP  
SC  
PKA_Key_Import  
X'0105' Symmetric Key Export PKCS-1.2/OAEP  
X'0106' PKA Symmetric Key Import PKCS-1.2/OAEP  
X'0107' One-Way Hash, SHA-1  
PKA_Symmetric_Key_Export  
PKA_Symmetric_Key_Import  
O
One_Way_Hash  
R
The following codes are used in this table:  
ID  
Initial default.  
O
R
Usage of this command is optional; enable it as required for authorized usage.  
Enabling this command is recommended.  
NR  
NRP  
SC  
SEL  
SUP  
Enabling this command is not recommended.  
Enabling this command is not recommended for production.  
Usage of this command requires special consideration.  
Usage of this command is normally restricted to one or more selected roles.  
This command is normally restricted to one or more supervisory roles.  
This verb performs more than one function, as determined by the keyword in the rule_array parameter of the verb call. Not all  
functions of the verb require the command in this row.  
This verb does not always require the command in this row. Use as determined by the control vector for the key and the action  
being performed.  
Appendix G. Access-Control-Point Codes G-3  
CCA Release 2.54  
Figure G-1 (Page 3 of 4). Supported CCA Commands  
Offset  
Command Name  
Verb Name  
Entry  
Usage  
X'0109' Data Key Import  
Data_Key_Import  
CSNBDKM  
CSNBDKX  
CSNDSBC  
CSNDSBD  
CSNDSYG  
CSNDSYG  
CSUACFC  
CSUACFC  
CSUACFC  
CSUAACI  
O
O
X'010A' Data Key Export  
Data_Key_Export  
X'010B' Compose SET Block  
X'010C' Decompose SET Block  
X'010D' PKA92 Symmetric Key Generate  
X'010E' NL-EPP-5 Symmetric Key Generate  
X'010F' Reset Intrusion Latch  
X'0110' Set Clock  
SET_Block_Compose  
SET_Block_Decompose  
PKA_Symmetric_Key_Generate  
PKA_Symmetric_Key_Generate  
O
O
SC  
O
Cryptographic_Facility_Control  
SUP  
ID, SUP  
ID, SUP  
Cryptographic_Facility_Control  
X'0111' Reinitialize Device  
X'0112' Initialize &ACS.  
Cryptographic_Facility_Control  
Access_Control_Initialization  
ID, NRP,  
SUP  
X'0113' Change User Profile Expiration Date  
Access_Control_Initialization  
CSUAACI  
CSUAACI  
ID, SUP  
X'0114' Change User Profile Authentication Data  
Access_Control_Initialization  
ID, NRP,  
SUP  
X'0115' Reset User Profile Logon-Attempt-Failure Count  
X'0116' Read Public Access-Control Information  
X'0117' Delete User Profile  
Access_Control_Initialization  
CSUAACI  
CSUAACM  
CSUAACM  
CSUAACM  
CSUACFC  
ID, SUP  
O, ID  
Access_Control_Maintenance  
Access_Control_Maintenance  
ID, SUP  
ID, SUP  
X'0118' Delete Role  
Access_Control_Maintenance  
X'0119' Load Function-Control Vector  
Cryptographic_Facility_Control  
ID, NRP,  
SUP  
X'011A' Clear Function-Control Vector  
X'011B' Force User Logoff  
Cryptographic_Facility_Control  
CSUACFC  
CSUALCT  
CSUACFC  
CSUACFC  
CSNDPKE  
CSNDPKD  
CSNBMKP  
CSNBSBD  
CSNBSBD  
CSNDPKH  
CSNDPKR  
CSNDPKR  
CSNDRKD  
CSNDPKG  
CSNDPKG  
CSNBMKD  
NR, ID  
O, SUP  
O, SUP  
O, SUP  
O, SEL  
SC, SEL  
SC, SEL  
O
Logon_Control  
X'011C' Set EID  
Cryptographic_Facility_Control  
X'011D' Initialize Master Key Cloning  
X'011E' RSA Encipher Clear Key  
X'011F' RSA Decipher Clear Key  
X'0120' Generate Random Asymmetric Master Key  
X'0121' SET PIN Encrypt with IPINENC  
X'0122' SET PIN Encrypt with OPINENC  
X'0200' PKA Register Public Key Hash  
X'0201' PKA Public Key Register with Cloning  
X'0202' PKA Public Key Register  
X'0203' Delete Retained Key  
Cryptographic_Facility_Control  
PKA_Key_Encipher  
PKA_Key_Decipher  
Master_Key_Process  
SET_Block_Decompose  
SET_Block_Decompose  
O
PKA_Public_Key_Hash_Register  
O
PKA_Public_Key_Register  
O, SEL  
O, SEL  
O, SEL  
O, SUP  
O, SUP  
O, SUP  
PKA_Public_Key_Register  
Retained_Key_Delete  
X'0204' PKA Clone Key Generate  
X'0205' PKA Clear Key Generate  
PKA_Key_Generate  
PKA_Key_Generate  
X'0211' Clone-info (Share) Obtain  
Master_Key_Distribution  
through  
X'021F'  
X'0221' Clone-info (Share) Install  
Master_Key_Distribution  
CSNBMKD  
O, SUP  
through  
X'022F'  
The following codes are used in this table:  
ID  
Initial default.  
O
R
Usage of this command is optional; enable it as required for authorized usage.  
Enabling this command is recommended.  
NR  
NRP  
SC  
SEL  
SUP  
Enabling this command is not recommended.  
Enabling this command is not recommended for production.  
Usage of this command requires special consideration.  
Usage of this command is normally restricted to one or more selected roles.  
This command is normally restricted to one or more supervisory roles.  
This verb performs more than one function, as determined by the keyword in the rule_array parameter of the verb call. Not all  
functions of the verb require the command in this row.  
This verb does not always require the command in this row. Use as determined by the control vector for the key and the action  
being performed.  
G-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Figure G-1 (Page 4 of 4). Supported CCA Commands  
Offset  
Command Name  
Verb Name  
Entry  
Usage  
X'0230' List Retained Key  
Retained_Key_List  
Clear_PIN_Generate_Alternate  
CSNDRKL  
CSNBCPA  
CSNBPVR  
CSNDSYI  
CSNDSYI  
CSNDSYG  
CSNDSYI  
CSNDSYX  
CSNDSYG  
CSNBSKY  
CSNBSPN  
CSNBKEX  
CSNBDKX  
CSNBKPI  
CSNBKPI  
CSNBKPI  
CSNBKIM  
CSNBDKM  
CSNDPKG  
CSNDPKG  
O
X'0231' Generate Clear NL-PIN-1 Offset  
X'0232' Verify Encrypted NL-PIN-1  
O
O
Encrypted_PIN_Verify  
X'0235' PKA92 Symmetric Key Import  
X'0236' PKA92 Symmetric Key Import with PIN Keys  
X'023C' ZERO-PAD Symmetric Key Generate  
X'023D' ZERO-PAD Symmetric Key Import  
X'023E' ZERO-PAD Symmetric Key Export  
X'023F' Symmetric Key Generate PKCS-1.2/OAEP  
X'0273' Secure Messaging for Keys  
X'0274' Secure Messaging for PINs  
X'0276' Unrestrict Reencipher from Master Key  
X'0277' Unrestrict Data Key Export  
PKA_Symmetric_Key_Import  
O
PKA_Symmetric_Key_Import  
O
PKA_Symmetric_Key_Generate  
O
PKA_Symmetric_Key_Import  
O, SC  
O, SC  
O, SC  
O
PKA_Symmetric_Key_Export  
PKA_Symmetric_Key_Generate  
Secure_Messaging_for_Keys  
Secure_Messaging_for_PINs  
Key_Export  
O
O, SC  
O, SC  
SC, SEL  
SC, SEL  
O, SC  
O, SC  
O, SC  
O, NRP, SC  
O, NRP, SC  
O, SC  
Data_Key_Export  
X'0278' Add Key Part  
Key_Part_Import  
X'0279' Complete Key Part  
Key_Part_Import  
X'027A' Unrestrict Combine Key Parts  
X'027B' Unrestrict Reencipher to Master Key  
X'027C' Unrestrict Data Key Import  
Key_Part_Import  
Key_Import  
Data_Key_Import  
PKA_Key_Generate  
PKA_Key_Generate  
|
|
X'027D' Permit Regeneration Data  
X'027E' Permit Regeneration Data for Retain Keys  
X'0290' Generate Diversified Key (DALL with  
Diversified_Key_Generate  
PIN_Change/Unblock  
CSNDDKG  
CSNBPCU  
DKYGENKY Key Type)  
X'0291' Generate CSC-5, 4 and 3 Values  
X'0292' Verify CSC-3 Values  
Transaction_Validate  
Transaction_Validate  
Transaction_Validate  
Transaction_Validate  
CSNBTRV  
CSNBTRV  
CSNBTRV  
CSNBTRV  
CSUACFC  
CSNBKET  
CSNBKET  
O, SEL  
O
X'0293' Verify CSC-4 Values  
O
X'0294' Verify CSC-5 Values  
O
O, SUP  
O
X'030B' Reset Battery-Low Indicator  
X'030D' Translate Key from CBC to ECB  
X'030E' Translate Key from ECB to CBC  
The following codes are used in this table:  
Cryptographic_Facility_Control  
Key_Encryption_Translate  
Key_Encryption_Translate  
|
|
O
ID  
Initial default.  
O
R
Usage of this command is optional; enable it as required for authorized usage.  
Enabling this command is recommended.  
NR  
NRP  
SC  
SEL  
SUP  
Enabling this command is not recommended.  
Enabling this command is not recommended for production.  
Usage of this command requires special consideration.  
Usage of this command is normally restricted to one or more selected roles.  
This command is normally restricted to one or more supervisory roles.  
This verb performs more than one function, as determined by the keyword in the rule_array parameter of the verb call. Not all  
functions of the verb require the command in this row.  
This verb does not always require the command in this row. Use as determined by the control vector for the key and the action  
being performed.  
Appendix G. Access-Control-Point Codes G-5  
CCA Release 2.54  
G-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
List of Abbreviations  
ANSI  
American National Standards Institute  
IBM  
International Business Machines  
Integrated Cryptographic Facility  
ACF/VTAM  
Advanced Communications Function  
for the Virtual Telecommunications  
Access Method  
ICRF  
ICSF  
Integrated Cryptographic Service  
Facility  
AIX  
Advanced Interactive Executive  
operating system  
ICSF/MVS  
Integrated Cryptographic Service  
Facility/Multiple Virtual Storage  
APF  
API  
Authorized Program Facility  
IMS  
Information Management System  
Input/Output  
Application Programming Interface  
I/O  
ASCII  
American National Standard Code for  
Information Interchange  
IPL  
Initial Program Load  
ISO  
International Standards Organization  
Key-Encrypting Key  
ATC  
Application Transaction Counter  
Automated Teller Machine  
KEK  
KM  
ATM  
Master key  
BCD  
Binary Coded Decimal  
LAN  
MB  
Local Area Network  
CBC  
Cipher-Block Chaining  
Megabyte  
CCA  
Common Cryptographic Architecture  
Commercial Data Masking Facility  
Customer Information Control System  
Cryptographic Key Data Set  
Current Key Serial Number  
MAC  
MD5  
MDC  
MK  
Message Authentication Code  
Message Digest 5 Hashing Algorithm  
Modification Detection Code  
Master key  
CDMF  
CICS  
CKDS  
CKSN  
COBOL  
MKVP  
MVS  
MVS/ESA  
MVS/XA  
NIST  
Master Key Version Pattern  
Multiple Virtual Storage  
MVS/Enterprise Systems Architecture  
MVS/Extended Architecture  
Common Business-Oriented  
Language  
CV  
Control Vector.  
CVC  
Card-Verification Code.  
Card-Verification Value  
Direct Access Storage Device  
Data Encryption Algorithm  
Data Encryption Standard  
Direct Memory Access  
National Institute of Science and  
Technology (USA).  
CVV  
DASD  
DEA  
OEM  
OS/2  
OS/400  
PAN  
PC  
Original Equipment Manufacturer  
Operating System/2  
DES  
Operating System/400  
Personal Account Number  
Personal Computer  
DMA  
EBCDIC  
Extended Binary Coded Decimal  
Interchange Code  
PCF  
Programmed Cryptographic Facility  
Personal Identification Number  
Public Key Algorithm  
ECB  
Electronic Code Book  
PIN  
EEPROM  
Electrically Erasable, Programmable  
Read-Only Memory  
PKA  
POS  
POST  
PROM  
EIA  
EMV  
F
Electronics Industries Association  
Europay, MasterCard, VISA  
Fahrenheit  
Point Of Sale  
Power-On Self Test  
Programmable Read-Only Memory.  
(A)  
FCC  
Federal Communications  
Commission  
PRPQ  
RACF  
RAM  
Program Request for Price Quotation  
Resource Access Control Facility  
Random Access Memory  
FIPS  
GTF  
Federal Information Processing  
Standard  
Generalized Trace Facility  
RISC  
Reduced Instruction-Set Computer  
Copyright IBM Corp. 1997, 2005  
X-1  
CCA Release 2.54  
ROM  
RPQ  
RSA  
SAA  
SAF  
SHA  
Read-Only Memory  
SNA  
TLV  
TSS  
UKPT  
VM  
Systems Network Architecture  
Request for Price Quotation  
Rivest, Shamir, and Adleman  
Systems Application Architecture  
System Authorization Facility  
Secure Hashing Algorithm  
Tag, Length, Value  
Transaction Security System  
Unique-Key-Per-Transaction  
Virtual Machine  
X-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Glossary  
This glossary includes some terms and definitions from  
the IBM Dictionary of Computing, New York: McGraw  
Hill, 1994. This glossary also includes some terms and  
definitions from:  
Advanced Communications Function for the Virtual  
Telecommunications Access Method. ACF/VTAM is  
an IBM-licensed program that controls communication  
and the flow of data in an SNA network.  
The American National Standard Dictionary for  
Information Systems, ANSI X3.172-1990, copyright  
1990 by the American National Standards Institute  
(ANSI). Copies may be purchased from the  
Advanced Interactive Executive (AIX) operating  
system. IBM’s implementation of the UNIX** operating  
system.  
American National Standards Institute, 11 West 42  
Street, New York, New York 10036. Definitions are  
identified by the symbol (A) after the definition.  
American National Standard Code for Information  
Interchange (ASCII). The standard code (8 bits  
including parity a bit), used for information interchange  
among data processing systems, data communication  
systems, and associated equipment. The ASCII set  
consists of control characters and graphic characters.  
The Information Technology Vocabulary, developed  
by Subcommittee 1, Joint Technical Committee 1, of  
the International Organization for Standardization  
and the International Electrotechnical Commission  
(ISO/IEC JTC1/SC1). Definitions of published parts  
of this vocabulary are identified by the symbol (I)  
after the definition; definitions taken from draft  
international standards, committee drafts, and  
working papers being developed by ISO/IEC  
JTC1/SC1 are identified by the symbol (T) after the  
definition, indicating that final agreement has not yet  
been reached among the participating National  
Bodies of SC1.  
American National Standards Institute (ANSI). An  
organization, consisting of producers, consumers, and  
general interest groups that establishes the procedures  
by which accredited organizations create and maintain  
voluntary industry standards in the United States. (A)  
Application System/400 system (AS/400). AS/400  
was one of a family of general purpose midrange  
systems with a single operating system, Operating  
System/400, that provides application portability across  
all models. AS/400 is now referred to as IBM eServer  
iSeries.  
A
assembler language. A source language that includes  
symbolic machine language statements in which there  
is a one-to-one correspondence between the instruction  
formats and the data formats of the computer.  
access. A specific type of interaction between a  
subject and an object that results in the flow of  
information from one to the other.  
access control. Ensuring that the resources of a  
computer system can be accessed only by authorized  
users in authorized ways.  
authentication. (1) A process used to verify the  
integrity of transmitted data, especially a message. (T)  
(2) In computer security, a process used to verify the  
user of an information system or protected resources.  
access method. (1) A technique for moving data  
between main storage and input/output devices.  
authorization. (1) The right granted to a user to  
communicate with or make use of a computer  
system. (T) (2) The process of granting a user either  
complete or restricted access to an object, resource, or  
function.  
adapter. A printed circuit card that modifies the system  
unit to allow it to operate in a particular way.  
address. (1) In data communication, the unique code  
assigned to each device or workstation connected to a  
network. (2) A character or group of characters that  
identifies a register, a particular part of storage, or some  
other data source or data destination. (A) (3) To refer  
to a device or an item of data by its address. (A) (I)  
authorize. To permit or give authority to a user to  
communicate with or make use of an object, resource,  
or function.  
**  
UNIX is a trademark of UNIX Systems Laboratories, Incorporated.  
Copyright IBM Corp. 1997, 2005  
X-3  
CCA Release 2.54  
control program. A computer program designed to  
schedule and to supervise the programs running in a  
computer system. (A) (I)  
B
bus. In a processor, a physical facility along which  
data is transferred.  
control vector (CV). In CCA, a 16-byte string that is  
exclusive-ORd with a master key or a Key-Encrypting  
Key to create another key that is used to encipher and  
decipher data or data keys. A control vector determines  
the type of key and the restrictions on the use of that  
key.  
byte. (1) A binary character operated on as a unit and  
usually shorter than a computer word. (A) (2) A string  
that consists of a number of bits, treated as a unit, and  
representing a character. (3) A group of eight adjacent  
binary digits that represents one EBCDIC character.  
coprocessor. In this manual, the IBM 4758 PCI  
Cryptographic Coprocessor, generally also when using  
the CCA Support Program.  
C
Card-Verification Code (CVC). See Card-Verification  
Value.  
Cryptographic Key Data Set (CKDS). CKDS is a  
data set containing the encrypting keys used by an  
installation. See key storage.  
Card-Verification Value (CVV). CVV is a  
cryptographic method, defined by VISA, for detecting  
forged magnetic-striped cards. This method  
cryptographically checks the contents of a magnetic  
stripe. This process is functionally the same as  
MasterCard’s Card-Verification Code (CVC) process.  
Cryptographic Node Management utility (CNM).  
One of the utility programs supplied with the CCA  
Support Program. It enables you to initialize the  
Coprocessor access controls and the cryptographic  
master keys.  
Commercial Data Masking Facility (CDMF). CMDF is  
an alternate algorithm for data confidentiality  
applications, based on the DES algorithm with an  
effective 40 bit key strength.  
cryptography. The transformation of data to conceal  
its meaning.  
D
channel. A path along which signals can be sent; for  
example, a data channel or an output channel. (A)  
data. (1) A representation of facts or instructions in a  
form suitable for communication, interpretation, or  
processing by human or automatic means. Data  
includes constants, variables, arrays, and character  
strings. (2) Any representations such as characters or  
analog quantities to which meaning is or might be  
assigned. (A)  
ciphertext. Text that results from the encipherment of  
plaintext. See also plaintext.  
Cipher Block Chaining (CBC). CBC is a mode of  
operation that cryptographically connects one block of  
ciphertext to the next plaintext block.  
data-encrypting key. (1) A key used to encipher,  
decipher, or authenticate data. (2) Contrast with  
Key-Encrypting Key.  
clear data. (1) Data that is not enciphered.  
cleartext. Text that has not been altered by a  
cryptographic process. Synonym for plaintext. See  
also ciphertext.  
Data Encryption Algorithm (DEA). DEA is a 64-bit  
block cipher that uses a 64-bit key, of which 56 bits are  
used to control the cryptographic process and 8 bits are  
used for parity checking to ensure that the key is  
transmitted properly.  
Common Cryptographic Architecture (CCA). The  
CCA API is the programming interface described in this  
manual.  
Data Encryption Standard (DES). DES is the  
National Institute of Standards and Technology Data  
Encryption Standard, adopted by the U.S. government  
as Federal Information Processing Standard (FIPS)  
Publication 46. which allows only hardware  
concatenation. An operation that joins two characters  
or strings in the order specified, forming one string  
whose length is equal to the sum of the lengths of its  
parts.  
implementations of the data-encryption algorithm.  
configuration. (1) The manner in which the hardware  
and software of an information processing system are  
organized and interconnected. (T) (2) The physical and  
logical arrangement of devices and programs that  
constitutes a data processing system.  
data set. The major unit of data storage and retrieval,  
consisting of a collection of data in one of several  
prescribed arrangements and described by control  
information to which the system has access.  
X-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
decipher. (1) To convert enciphered data into clear  
data. (2) Synonym for decrypt. (3) Contrast with  
encipher.  
the Data Encryption Standard. (3) Contrast with  
decode. (4) See also encipher.  
encrypt. (1) Synonym for encipher. (T) (2) To  
convert clear text into ciphertext. (3) Contrast with  
decrypt.  
decode. (1) To convert data by reversing the effect of  
some previous encoding. (A) (I) (2) In the CCA  
products, decode and encode relate to the Electronic  
Code Book mode of the Data Encryption Standard  
(DES). (3) Contrast with encode and decipher..  
Erasable Programmable Read-Only Memory  
(EPROM). EPROM is a PROM that can be erased by  
a special process and reused. (T)  
decrypt. (1) To decipher or decode. (2) Synonym for  
decipher. (3) Contrast with encrypt.  
exit routine. In the CCA products, a user-provided  
routine that acts as an extension to the processing  
provided with calls to the security API.  
device driver. A program that contains the code  
needed to attach and use a device.  
EXPORTER key. (1) In the CCA implementation, a  
type of DES Key-Encrypting Key that can encipher a  
key at a sending node. (2) Contrast with IMPORTER  
key.  
device ID. In the IBM 4758 CCA implementation, a  
user-defined field in the configuration-data that can be  
used for any purpose the user specifies. For example,  
it can be used to identify a particular device, by using a  
unique ID similar to a serial number.  
F
diagnostic. Pertaining to the detection and isolation of  
errors in programs, and faults in equipment.  
feature. A part of an IBM product that can be ordered  
separately.  
directory server. A server that manages key records  
in key storage by using an Indexed Sequential Access  
Method.  
Federal Communications Commission (FCC). The  
FCC is a board of commissioners, appointed by the  
President under the Communications Act of 1934, and  
having the power to regulate all interstate and foreign  
communications by wire and radio originating in the  
United States.  
E
Electronic Code Book (ECB). ECB is a mode of  
operation used with block cipher cryptographic  
algorithms in which plaintext or ciphertext is placed in  
the input to the algorithm and the result is contained in  
the output of the algorithm.  
Federal Information Processing Standard (FIPS).  
FIPS is a standard published by the US National  
Institute of Science and Technology.  
financial PIN. (1) A Personal Identification Number  
used to identify an individual in some financial  
transactions. To maintain the security of the PIN,  
processes and data structures have been adopted for  
creating, communicating, and verifying PINs used in  
financial transactions. (2) See also Personal  
Identification Number.  
Electronics Industries Association (EIA). EIA is an  
organization of electronics manufacturers that advances  
the technological growth of the industry, represents the  
views of its members, and develops industry standards.  
encipher. (1) To scramble data or to convert data to a  
secret code that masks the meaning of the data to  
unauthorized recipients. (2) Synonym for encrypt.  
(3) Contrast with decipher. (4) See also encode.  
Flash-Erasable Programmable Read-Only Memory.  
A memory that has to be erased before new data can  
be saved into the memory.  
enciphered data. Data whose meaning is concealed  
from unauthorized users or observers. See also  
ciphertext.  
G
Generalized Trace Facility (GTF). GTF is an optional  
service program that records significant system events,  
such as supervisor calls and start I/O operations, for the  
purpose of problem determination.  
encode. (1) To convert data by the use of a code in  
such a manner that reconversion to the original form is  
possible. (T) (2) In the CCA implementation, decode  
and encode relate to the Electronic Code Book mode of  
Glossary X-5  
CCA Release 2.54  
key label. In the CCA implementation, an identifier of  
a key-record in key storage. See “Key Labels” on  
page 5-14 and “Key-Label Content” on page 7-2.  
H
host. (1) In this publication, same as host computer or  
host processor. The machine in which the Coprocessor  
resides. (2) In a computer network, the computer that  
usually performs network-control functions and provides  
end-users with services such as computation and  
database access. (T)  
key storage. In the CCA implementation, a data file  
that contains cryptographic keys which are accessed by  
key label.  
key token. In the CCA implementation, a data  
structure that can contain a cryptographic key, a control  
vector, and other information related to the key.  
I
IMPORTER key. (1) In the CCA implementation, a  
type of DES Key-Encrypting Key that can decipher a  
key at a receiving mode. (2) Contrast with EXPORTER  
key.  
L
link. (1) The logical connection between nodes  
including the end-to-end control procedures. (2) The  
combination of physical media, protocols, and  
programming that connects devices on a network.  
(3) In computer programming, the part of a program, in  
some cases a single instruction or an address, that  
passes control and parameters between separate  
portions of the computer program. (A) (I) (4) To  
interconnect items of data or portions of one or more  
computer programs. (T) (5) In SNA, the combination of  
the link connection and link stations joining network  
nodes.  
initialize. (1) In programming languages, to give a  
value to a data object at the beginning of its lifetime. (I)  
(2) To set counters, switches, addresses, or contents of  
storage to zero or other starting values at the beginning  
of, or at prescribed points in, the operation of a  
computer routine. (A)  
Integrated Cryptographic Service Facility (ICSF).  
ICSF is an IBM licensed program that supports the  
cryptographic hardware feature for the high-end  
System/390 processor running in an MVS environment.  
M
International Organization for Standardization  
(ISO). ISO is an organization of national standards  
bodies established to promote the development of  
standards to facilitate the international exchange of  
goods and services, and develop cooperation in  
intellectual, scientific, technological, and economic  
activity.  
make file. A composite file that contains either device  
configuration data or individual user profiles.  
master key (MK, KM). In computer security, the  
top-level key in a hierarchy of key-encrypting keys.  
Message Authentication Code (MAC). (1) A number  
or value derived by processing data with an  
authentication algorithm, (2) The cryptographic result of  
block cipher operations on text or data using a cipher  
block chaining (CBC) mode of operation, (3) A digital  
signature code.  
J
jumper. A wire that joins two unconnected circuits on  
a printed circuit board.  
migrate. (1) To move data from one hierarchy of  
storage to another. (2) To move to a changed  
operating environment, usually to a new release or a  
new version of a system.  
K
key. In computer security, a sequence of symbols  
used with a cryptographic algorithm to encrypt or  
decrypt data.  
Modification Detection Code (MDC). In cryptography,  
the MDC is a number or value that interrelates all bits of  
a data stream so that, when enciphered, modification of  
any bit in the data stream results in a new MDC.  
Key-Encrypting Key (KEK). (1) A KEK is a key used  
for the encryption and decryption of other keys.  
(2) Contrast with data-encrypting key.  
multi-user environment. A computer system that  
provides terminals and keyboards for more than one  
user at the same time.  
key half. In the CCA implementation, one of the two  
DES keys that make up a double-length key.  
key identifier. In the CCA implementation, a 64-byte  
variable which is either a key label or a key token.  
X-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Power-On Self Test (POST). POST is a series of  
diagnostic tests run automatically by a device when the  
power is turned on.  
N
National Institute of Science and Technology  
(NIST). This is the current name for the US National  
Bureau of Standards.  
private key. (1) In computer security, a key that is  
known only to the owner and used together with a  
public-key algorithm to decipher data. The data is  
enciphered using the related public key. (2) Contrast  
with public key. (3) See also public-key algorithm.  
network. (1) A configuration of data-processing  
devices and software programs connected for  
information interchange. (2) An arrangement of nodes  
and connecting branches. (T)  
procedure call. In programming languages, a  
language construct for invoking execution of a  
procedure. (I) A procedure call usually includes an  
entry name and possible parameters.  
Network Security Processor (IBM 4753). The IBM  
4753 is a processor that uses the Data Encryption  
Algorithm to provide cryptographic support for systems  
requiring secure transaction processing (and other  
cryptographic services) at the host computer.  
profile. Data that describes the significant  
characteristics of a user, a group of users, or  
one-or-more computer resources.  
node. In a network, a point at which one-or-more  
functional units connect channels or data circuits. (I)  
Programmed Cryptographic Facility (PCF). PCF is  
an IBM licensed program that provides facilities for  
enciphering and deciphering data and for creating,  
maintaining, and managing cryptographic keys.  
O
Operating System/2 (OS/2). OS/2 is an operating  
system for the IBM Personal System/2 computers.  
protocol. (1) A set of semantic and syntactic rules  
that determines the behavior of functional units in  
achieving communication. (I) (2) In SNA, the meanings  
of and the sequencing rules for requests and responses  
used to manage the network, transfer data, and  
synchronize the states of network components. (3) A  
specification for the format and relative timing of  
information exchanged between communicating parties.  
Operating System/400 (OS/400). OS/400 is an  
operating system for the IBM eServer iSeries, formerly  
known as Application System/400 computers.  
P
public key. (1) In computer security, a key that is  
widely known, and used with a public-key algorithm to  
encrypt data. The encrypted data can be decrypted  
only with the related private key. (2) Contrast with  
private key. (3) See also public-key algorithm.  
panel. The complete set of information shown in a  
single image on a display station screen.  
parameter. In the CCA security API, an address  
pointer passed to a verb to address a variable  
exchanged between an application program and the  
verb.  
Public-Key Algorithm (PKA). (1) In computer  
security, PKA is an asymmetric cryptographic process  
that uses a public key to encrypt data and a related  
private key to decrypt data. (2) Contrast with Data  
Encryption Algorithm and Data Encryption Standard  
algorithm. (3) See also Rivest-Shamir-Adleman  
algorithm.  
password. In computer security, a string of characters  
known to the computer system and a user; the user  
must specify it to gain full or limited access to a system  
and to the data stored within it.  
Personal Identification Number (PIN). In some  
financial-transaction-authentication systems, the PIN is  
the secret number given to a consumer with an  
identification card. This number is selected by the  
consumer, or it is assigned by the financial institution.  
public-key hardware. That portion of the security  
module in an IBM 4758 that performs  
modulus-exponentiation arithmetic.  
R
profile ID. In the CCA implementation, the value used  
to access a profile within the CCA access-control  
system.  
Random Access Memory (RAM). RAM is a storage  
device into which data are entered and from which data  
are retrieved in a non-sequential manner.  
plaintext. (1) Data that has nor been altered by a  
cryptographic process. (2) Synonym for cleartext. See  
also ciphertext.  
Read-Only Memory (ROM). ROM is memory in which  
stored data cannot be modified by the user except  
under special conditions.  
Glossary X-7  
CCA Release 2.54  
reason code. (1) A value that provides a specific  
result as opposed to a general result. (2) Contrast with  
return code.  
(2) The period of time during which a user of a terminal  
can communicate with an interactive system (usually,  
the elapsed time between logon and logoff).  
replicated key-half. In the CCA implementation, a  
double-length DES key where the two halves of the  
clear-key value are equal.  
Session-Level Encryption (SLE). SLE is a Systems  
Network Architecture (SNA) protocol that provides a  
method for establishing a session with a unique key for  
that session. This protocol establishes a cryptographic  
key and the rules for deciphering and enciphering  
information in a session.  
Resource Access Control Facility (RACF). RACF is  
an IBM licensed program that enables access control by  
identifying and verifying the users to the system,  
authorizing access to protected resources, logging  
detected unauthorized attempts to enter the system,  
and logging detected accesses to protected resources.  
string. A sequence of elements of the same nature,  
such as characters, considered as a whole. (T)  
subsystem. A secondary or subordinate system,  
usually capable of operating independently of, or  
asynchronously with, a controlling system. (T)  
return code. (1) A code used to influence the  
execution of succeeding instructions. (A) (2) A value  
returned to a program to indicate the results of an  
operation requested by that program. (3) In the CCA  
implementation, a value that provides a general result  
as opposed to a specific result. (4) Contrast with  
reason code.  
system administrator. The person at a computer  
installation who designs, controls, and manages the use  
of the computer system.  
System Authorization Facility (SAF). SAF is a  
program that provides access to the resource access  
control facility or its equivalent.  
Rivest-Shamir-Adleman (RSA) algorithm. RSA is a  
public-key cryptography process developed by R.  
Rivest, A. Shamir, and L. Adleman.  
Systems Network Architecture (SNA). SNA  
describes logical structure, formats, protocols, and  
operational sequences for transmitting information units  
through, and controlling the configuration and operation  
of, networks. Note: The layered structure of SNA  
allows the ultimate origins and destinations of  
RS-232. A specification that defines the interface  
between data terminal equipment and data  
circuit-terminating equipment, using serial binary data  
interchange.  
RS-232C. A standard that defines the specific physical,  
electronic, and functional characteristics of an interface  
line that uses a 25-pin connector to connect a  
workstation to a communication device.  
information, that is, the end users, to be independent of  
and unaffected by the specific SNA network services  
and facilities used for information exchange.  
T
RSA algorithm. Rivest-Shamir-Adleman encryption  
algorithm.  
throughput. (1) A measure of the amount of work  
performed by a computer system over a given period of  
time; for example, number of jobs per day. (A) (I) (2) A  
measure of the amount of information transmitted over  
a network in a given period of time; for example, a  
network’s data-transfer-rate is usually measured in bits  
per second.  
S
security. The protection of data, system operations,  
and devices from accidental or intentional ruin, damage,  
or exposure.  
security server. In the CCA implementation, the  
functions provided through calls made to the security  
API.  
TLV. A widely used construct, Tag, Length, Value, to  
render data self-identifying. For example, such  
constructs are used with EMV smart cards.  
server. On a Local Area Network, a data station that  
provides facilities to other data stations; for example, a  
file server, a print server, a mail server. (A)  
token. (1) In a Local Area Network, the symbol of  
authority passed successively from one data station to  
another to indicate the station is temporarily in control of  
the transmission medium. (T) (2) A string of characters  
treated as a single entity.  
session. (1) In network architecture, for the purpose  
of data communication between functional units, all the  
activities that take place during the establishment,  
maintenance, and release of the connection. (T)  
trace file. A file that contains a record of trace  
information for the selected processing.  
X-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
computer and its associated devices. Each virtual  
machine is controlled by a suitable operating system.  
VM controls concurrent execution of multiple virtual  
machines on one host computer.  
U
Unique Key Per Transaction (UKPT). UKPT is a  
cryptographic process that can be used to decipher PIN  
blocks in a transaction.  
VISA. A financial institution consortium which defines  
four PIN-block formats and a method of PIN verification.  
user-exit routine. A user-written routine that receives  
control at predefined user-exit points.  
W
user ID. User identification.  
workstation. A terminal or microcomputer, usually one  
that is connected to a mainframe or to a network, at  
which a user can perform applications.  
userid. A string of characters that uniquely identifies a  
user to the system.  
utility program. A computer program in general  
support of computer processes. (T)  
Numerics  
4758. IBM 4758 PCI Cryptographic Coprocessor.  
V
verb. A function that has an entry-point-name and a  
fixed-length parameter list. The procedure call for a  
verb uses the standard syntax of a programming  
language.  
virtual machine (VM). A functional simulation of a  
Glossary X-9  
CCA Release 2.54  
X-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
Index  
clear keys 5-16  
cloning a master key  
A
Access Control, CCA 2-2  
Access_Control_Initialization (CSUAACI) 2-21  
Access_Control_Maintenance (CSUAACM) 2-24  
American Express  
certificate 2-15  
coding procedure calls 1-8  
common parameters 1-11  
confidentiality, data 6-1  
control vectors (CVs)  
transaction validation verb 8-75  
American National Standards Institute (ANSI)  
X3.106 (CBC) method D-7  
X9.19 method D-13  
bit map  
EXPORT bit C-8  
format C-5  
gks bits C-8  
IMPORT bit C-8  
X9.23 method D-7  
X9.9 method D-13  
ANSI X9.24 DUKPT 8-37, 8-42  
ANSI X9.31 hash format D-19  
asymmetric keys 5-6  
attributes 5-7  
automated teller machine 8-3  
Key-part bit C-11  
parity bits C-11  
XLATE bit C-8  
changing 5-26  
Control_Vector_Translate Verb C-20  
pre-exclusive-OR technique C-16  
checking 5-5  
control information C-20  
default values 5-6  
description 5-4  
determining values C-7  
generating 5-24  
B
battery-low indicator 2-30  
battery-low indicator (latch) 2-10  
Bellare-Rogaway D-19  
key form bits, fff C-7  
key separation 5-4  
C
calculation methods, PIN 8-8  
card verification code E-16  
card verification value E-16  
carriage return (CR) B-25  
CCA, common cryptographic architecture  
control-vector definitions C-1  
key encryption C-1  
key-half processing mode C-23  
keywords 5-10  
mask array information C-20  
multiply-deciphering keys C-12  
multiply-enciphering keys C-12  
specifying values C-7  
testing C-20  
translating 5-26  
values C-1  
verbs 5-24, 5-26  
list of security API verbs F-1  
relationship to security API 1-8  
certificate 2-15  
chaining vector 6-4  
chaining-vector-record format B-20  
cipher-class keys 5-7  
violation C-20  
Control_Vector_Translate  
example C-24  
ciphering  
Control_Vector_Translate (CSNBCVT) 5-26  
Control_Vector_Translate, mask array C-20  
controlling the cryptographic facility 2-9  
Coprocessor resource selection 2-44, 2-46  
CR (carriage return) B-25  
cryptographic engine 1-4  
cryptographic-variable-class keys 5-8  
Cryptographic_Facility_Control (CSUACFC) 2-30  
Cryptographic_Facility_Query (CSUACFQ) 2-34  
Cryptographic_Variable_Encipher (CSNBCVE) 5-29  
CSNBCKI (Clear_Key_Import) 5-22  
CSNBCKM (Multiple_Clear_Key_Import) 5-71  
CCA DES-key verification algorithm D-2  
keys 5-7, 5-10  
methods  
3624 PIN E-3, E-5  
3624 PIN offset E-4  
ANSI X3.106 (CBC) D-7  
German Bank Pool Institution PIN E-6  
Interbank PIN E-8  
message authentication code (MAC) D-13  
modification detection code (MDC) D-3  
NL-PIN-1 E-5  
VISA PIN Validation Value (PVV) E-7  
Copyright IBM Corp. 1997, 2005  
X-11  
CCA Release 2.54  
CSNBCPA (Clear_PIN_Generate_Alternate) 8-21  
CSNBCPE (Clear_PIN_Encrypt) 8-15  
CSNBCSG (CVV_Generate) 8-27  
CSNDPKI (PKA_Key_Import) 3-11  
CSNDPKR (PKA_Public_Key_Register) 3-28  
CSNDPKX (PKA_Public_Key_Extract) 3-24  
CSNDRKD (Retained_Key_Delete) 7-21  
CSNDRKL (Retained_Key_List) 7-22  
CSNDSBC (SET_Block_Compose) 8-66  
CSNDSBD (SET_Block_Decompose) 8-70  
CSNDSYG (PKA_Symmetric_Key_Generate) 5-81  
CSNDSYI (PKA_Symmetric_Key_Import) 5-86  
CSNDSYX (PKA_Symmetric_Key_Export) 5-78  
CSUAACI (Access_Control_Initialization) 2-21  
CSUAACM (Access_Control_Maintenance) 2-24  
CSUACFC (Cryptographic_Facility_Control) 2-30  
CSUACFQ (Cryptographic_Facility_Query) 2-34  
CSUALCT (Logon_Control) 2-52  
CSNBCSV (CVV_Verify) 8-30  
CSNBCVE (Cryptographic_Variable_Encipher) 5-29  
CSNBCVG (Control_Vector_Generate) 5-24  
CSNBCVT (Control_Vector_Translate) 5-26  
CSNBDEC (Decipher) 6-5  
CSNBDKG (Diversified_Key_Generate) 5-35  
CSNBDKM (Data_Key_Import) 5-33  
CSNBDKX (Data_Key_Export) 5-31  
CSNBENC (Encipher) 6-8  
CSNBEPG (Encrypted_PIN_Generate) 8-33  
CSNBKET (Key_Encryption_Translate) 8-49  
CSNBKEX (Key_Export) 5-42  
CSNBKGN 5-17  
CSNBKGN (Key_Generate) 5-44  
CSNBKIM (Key_Import) 5-51  
CSUAMKD (Master_Key_Distribution) 2-55  
CSUARNT (Random_Number_Tests) 2-64  
CVARENC key type 5-8  
CSNBKPI (Key_Part_Import) 5-54  
CVARXCVL key type 5-8  
CSNBKRC (DES_Key_Record_Create) 7-4  
CSNBKRL (Key_Record_List) 7-7  
CVARXCVR key type 5-8  
CVC 8-27, 8-30, E-16  
CSNBKRR (Key_Record_Read) 7-9  
CSNBKRW (Key_Record_Write) 7-10  
CSNBKTB (Key_Token_Build) 5-61  
CSNBKTC (Key_Token_Change) 5-64  
CSNBKTP (Key_Token_Parse) 5-66  
CSNBKTR (Key_Translate) 5-69  
CSNBKYT (Key_Test) 5-58  
CSNBMDG (MDC_Generate) 4-10  
CSNBMGN (MAC_Generate) 6-11  
CSNBMKP (Master_Key_Process) 2-59  
CSNBMVR (MAC_Verify) 6-14  
CVV 8-27, 8-30, E-16  
D
DASD (direct access storage device) B-21  
data  
confidentiality 6-1  
ensuring 6-1  
integrity 6-1, 6-3  
segmented 6-3  
validation 8-8  
data confidentiality 1-1  
data integrity 1-1  
CSNBOWH (One_Way_Hash) 4-13  
CSNBPCU (PIN_Change/Unblock) 8-52  
CSNBPEX (Prohibit_Export) 5-90  
DATA-class keys 5-7, 5-10  
deactivating keys 3-22, 7-5, 7-13, 7-21  
deallocating a Coprocessor resource 2-46  
decimalization table 8-8  
defaults, control vectors 5-6  
DES key-storage initialization 2-50  
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  
device key 1-4  
CSNBPGN (Clear_PIN_Generate) 8-18  
CSNBPTR (Encrypted_PIN_Translate) 8-37  
CSNBPVR (Encrypted_PIN_Verify) 8-42  
CSNBRNG (Random_Number_Generate) 5-91  
CSNBSKY (Secure_Messaging_for_Keys) 8-59  
CSNBSPN (Secure_Messaging_for_PINs) 8-62  
CSNBTRV (Transaction_Validation) 8-75  
CSNDDSG (Digital_Signature_Generate) 4-4  
CSNDDSV (Digital_Signature_Verify) 4-7  
CSNDKRC (PKA_Key_Record_Create) 7-11  
CSNDKRD (PKA_Key_Record_Delete) 7-13  
CSNDKRL (PKA_Key_Record_List) 7-15  
CSNDKRR (PKA_Key_Record_Read) 7-17  
CSNDKRW (PKA_Key_Record_Write) 7-19  
CSNDKTC (PKA_Key_Token_Change) 3-22  
CSNDPKB (PKA_Key_Token_Build) 3-14  
CSNDPKD (PKA_Decrypt) 5-73  
digital signature 1-1  
ANSI X9.31 D-19  
hash formats D-19  
PKCS #1 D-19  
direct access storage device (DASD) B-21  
diversifying (smart card) keys 5-19  
dual control security policy 5-55  
CSNDPKE (PKA_Encrypt) 5-75  
CSNDPKG (PKA_Key_Generate) 3-7  
CSNDPKH (PKA_Public_Key_Hash_Register) 3-26  
X-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
financial personal identification number (PIN)  
(continued)  
E
EMV (Europay, Mastercard, VISA)  
application transaction counter (ATC) E-18  
MAC padding method D-13  
PIN-block self-encryption E-19  
PIN_Change/Unblock verb 8-52  
Secure_Messaging_for_Keys verb 8-59  
Secure_Messaging_for_PINs verb 8-62  
session key derivation, TDES-XOR E-18  
session-key tree-based key-diversification E-18  
smart-card-specific key E-17  
unique derivation key E-17  
working with EMV smart cards 8-13  
entry-point names 1-8  
data array (continued)  
transaction security data 8-9  
validation data 8-9  
description 8-2  
extraction methods 8-12  
format control 8-11  
generating clear PIN 8-18  
institution-assigned 8-42  
key types 8-7  
key-usage bits 8-7  
personal account number (PAN) 8-13  
PIN profile  
format control element 8-11  
pad digit element 8-11  
PIN-block format element 8-10  
processing  
environment identifier 2-15  
Environment, supported 1-9  
establishing master keys 2-13  
EX (exportable) keys 5-4  
exit_data parameter 1-11  
exit_data_length parameter 1-11  
exportable (EX) keys 5-4  
exporting, description 5-18, C-17  
external  
description 8-2  
extraction methods 8-10  
security 8-6  
supporting multiple PIN-calculation methods 8-8  
verbs 8-2  
security 8-6  
verbs  
key tokens  
building 5-61  
format B-5  
Key_Token_Build verb 5-61  
PKA, RSA B-6  
CSNBCPA  
(Clear_PIN_Generate_Alternate) 8-21  
CSNBCPE (Clear_PIN_Encrypt) 8-15  
CSNBEPG (Encrypted_PIN_Generate) 8-33  
CSNBKET (Key_Encryption_Translate) 8-49  
CSNBPCU (PIN_Change/Unblock) 8-52  
CSNBPGN (Clear_PIN_Generate) 8-18  
CSNBPTR (Encrypted_PIN_Translate) 8-37  
CSNBPVR (Encrypted_PIN_Verify) 8-42  
CSNBSKY (Secure_Messaging_for_Keys) 8-59  
CSNBSPN (Secure_Messaging_for_PINs) 8-62  
flag bytes B-6  
key tokens, description 5-14  
keys 5-4, 5-18  
extraction methods, financial PIN 8-12  
F
financial personal identification number (PIN)  
3624 PIN (CSNBPVR) 8-42  
blocks  
format  
3624 8-11, E-9  
chaining_vector record B-20  
control, financial PIN 8-11  
key tokens  
and PIN-calculation methods E-1  
description 8-6, 8-10, E-9  
format control 8-11  
ISO-0 8-11, E-10  
ISO-1 8-11, E-11  
ISO-2 8-11, E-12  
external B-5  
internal B-3  
null B-2  
key-record-list data set B-25  
key-storage record B-21  
formatting hashes and keys D-19  
function control vector B-42  
multiple 8-10  
profile 8-10  
calculation  
3624 PIN E-3, E-5  
3624 PIN Offset E-4  
descriptions 8-8, E-2  
German Bank Pool Institution PIN E-6  
Interbank PIN E-8  
H
hash formatting D-19  
supporting multiple PIN-calculation methods 8-8  
VISA-PVV E-7  
data array  
decimalization table 8-8  
Index X-13  
CCA Release 2.54  
key token (continued)  
flag byte 2 B-6  
format 5-12, B-1  
internal 5-14  
I
IM (importable) keys 5-4  
importable (IM) keys 5-4  
importing, description 5-18, C-17  
initializing key storage 2-48, 2-50  
input/output (I/O) parameters 1-10  
installing keys 5-15  
Key_Token_Build verb 5-61  
PKA_Key_Record_Delete service 7-13  
PKA_Key_Token_Change verb 3-22  
Key_Token_Build verb 5-61  
Key_Token_Parse verb 5-66  
listing 7-22  
null 5-14, B-2  
PKA, RSA B-6  
Record-Validation Value (RVV) B-2  
section sequence, PKA/RSA B-7  
token-validation value (TVV) B-2  
transport key B-1  
intermediate PIN-block (IPB) E-10  
internal 5-14  
key tokens  
building 5-61  
copying into application storage 7-9  
copying into key storage 7-10, 7-19  
format B-3  
Key_Token_Build verb 5-61  
PKA, RSA B-6  
key token verification patterns D-2  
key-encrypting-key-class keys 5-7  
key-export operation 5-18  
introduction 1-1  
Introduction of master-key parts 2-13  
intrusion latch 2-10, 2-30  
IPB (intermediate PIN-block) E-10  
ISO-0 PIN-block format E-10  
ISO-1 PIN-block format E-11  
ISO-2 PIN-block format E-12  
Key-generating keys 5-11  
key-generating-key-class keys 5-8  
key-half processing mode C-23  
key-import operation 5-18  
key-management keys  
Common Cryptographic Architecture  
support 5-1  
K
key-processing and key-storage verbs 5-15  
Control_Vector_Translate (CSNBCVT) 5-26  
DES_Key_Record_Delete (CSNBKRD) 7-5  
Key_Record_List (CSNBKRL) 7-7  
Key_Record_Read (CSNBKRR) 7-9  
Key_Record_Write (CSNBKRW) 7-10  
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  
key-storage initialization 2-48, 2-50  
key-storage selection 2-48  
key cache, host side 1-7  
key diversification 5-19  
key formatting D-19  
key identifier 5-14  
key label 5-12, 5-14, 7-2  
key shares 2-14  
key storage  
description 5-20  
key-record-list data set  
creating 7-7, 7-15  
format B-25  
verbs 5-15  
key token  
assembling 5-61  
changing 3-22  
contents 5-12  
deleting 3-22, 7-13, 7-21  
DES B-3  
Key_DES_Key_Record_Delete (CSNBKRD) 7-5  
Key_Export (CSNBKEX) 5-42  
Key_Generate (CSNBKGN) 5-17, 5-44  
Key_Import (CSNBKIM) 5-51  
Key_Part_Import (CSNBKPI) 5-54  
Key_Record_List (CSNBKRL) 7-7  
Key_Record_List (CSNDKRL) 7-15  
Key_Record_Read (CSNBKRR) 7-9  
Key_Record_Write (CSNBKRW) 7-10  
Key_Storage_Designate (CSUAKSD) 2-48  
Key_Storage_Initialization (CSNBKSI) 2-50  
Key_Storage_Initialization (CSUACRA) 2-44  
Key_Storage_Initialization (CSUACRD) 2-46  
Key_Token_Build (CSNBKTB) 5-61  
Key_Token_Parse (CSNBKTP) 5-66  
DES external B-5  
DES internal B-3  
description 5-12  
description, external B-1  
description, internal B-1  
disassembling 5-66  
external 5-14  
Key_Token_Build verb 5-61  
PKA_Key_Record_Delete service 7-13  
PKA_Key_Token_Change verb 3-22  
flag byte 1 B-6  
X-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
keys  
keys (continued)  
activating 3-22  
asymmetric 5-6  
ciphering 5-7, 5-10  
RSA token sections B-6  
secure-messaging 5-7  
separation 5-4  
clear 5-16  
storing 5-20  
control vectors 5-4  
symmetric 5-5  
deactivating 3-22  
transport B-1  
deleting 3-22, 7-13, 7-21  
double-length 5-6  
types  
and verbs 5-7  
exportable (EX) 5-4  
exporting, asymmetric techniques 5-19  
exporting, symmetric techniques 5-18  
external 5-4  
generating, DES 5-16  
generating, RSA D-15  
identifiers 5-14  
asymmetric 5-6  
CIPHER 5-7  
cipher-class keys 5-7  
cryptographic-variable-class keys 5-8  
CVARENC 5-8  
CVARXCVL 5-8  
CVARXCVR 5-8  
importable (IM) 5-4  
DATA 5-7  
importing 5-18  
importing, asymmetric techniques 5-19  
installing 5-15  
DATA-class keys 5-7  
DECIPHER 5-7  
description 5-5  
key management 5-1, 5-2  
key-storage initialization 2-48, 2-50  
key-usage keywords 5-6  
label 5-12  
ENCIPHER 5-7  
EXPORTER 5-7  
IKEYXLAT 5-8  
IMPORTER 5-7  
label, content 7-2  
labels  
definition 5-14  
length 5-12, 5-46  
IPINENC 5-8, 8-7  
key-encrypting-key-class keys 5-7  
key-generating-key-class keys 5-8  
key-usage keywords 5-10  
MAC 5-7  
listing 7-22  
managing 5-1, 5-2  
MAC-class keys 5-7  
MACVER 5-7  
OKEYXLAT 5-8  
one-way key-distribution channels 5-6  
OPINENC 5-8, 8-8  
PIN security 8-7  
master-key loading 2-59, 2-64  
multiply-deciphered 5-4, 5-18  
multiply-enciphered 5-3, 5-16  
operational (OP) 5-4  
parity 5-4  
parts  
PIN-class keys 5-8  
PINGEN 5-8, 8-7  
PINVER 5-8, 8-7  
secure-messaging-class keys 5-7  
symmetric 5-5  
generating 5-16  
secure 5-15  
processing  
verbs 5-15  
records  
UKPTBASE 8-8  
deleting 7-5, 7-13, 7-21  
DES_Key_Record_Deleteservice 7-5  
Key_Record_List service 7-7  
Key_Record_Read service 7-9  
Key_Record_Write service 7-10  
listing 7-7, 7-15, 7-22  
PKA_Key_Record_Delete service 7-13  
PKA_Key_Record_List service 7-15  
PKA_Key_Record_Read service 7-17  
PKA_Key_Record_Write service 7-19  
reading 7-9, 7-17  
unique-key-per-transaction (UKPT) 8-37, 8-42  
usage  
bits 8-7  
key form 5-17  
key type 5-17  
keywords 5-6  
verification pattern 5-15  
verifying 5-15  
keywords, key-usage 5-6  
L
Retained_Key_Delete service 7-21  
Retained_Key_List service 7-22  
writing 7-10, 7-19  
LF (line feed) B-25  
line feed (LF) B-25  
reenciphering 3-22  
Index X-15  
CCA Release 2.54  
listing keys 7-22  
O
loading a master key 2-59, 2-64  
Logging on and logging off 2-7  
logon context information 2-8  
Logon Control (CSUALCT) 2-52  
Logon_Control (CSUALCT) 2-52  
OAEP D-19  
object protection key (OPK) B-13, B-14  
OCV (output chaining value) D-7  
OP (operational) keys 5-4, 5-18  
operating environments 1-8  
operational (OP) keys 5-18  
operational keys (OP) 5-4  
M
OPK, object protection key B-13, B-14  
output chaining value (OCV) D-7  
overlapped processing restrictions 1-7  
m-of-n master-key shares 2-14  
MAC_Generate (CSNBMGN) 6-3  
MAC_Verify (CSNBMVR) 6-3  
MACVER key type, MAC_Verify verb 5-7  
managing  
P
DES keys  
pad digit 8-11  
Common Cryptographic Architecture 5-1  
mask array preparation C-20  
master key 1-4  
PAN (personal account number) 8-13  
parity, key 5-4  
parity, key parts 5-54  
cloning, 2-15  
current master-key 2-12  
environment identifier 2-15  
establishing 2-13  
Introduction of master-key parts 2-13  
m-of-n 2-14  
master-key cloning 2-14  
multi-Coprocessor considerations 2-17  
new master-key 2-12  
old master-key 2-12  
Random generation of a new master-key 2-14  
shares 2-14  
personal account number (PAN) 8-13  
PIN block-encrypting key 8-7  
PIN-class keys 5-8, 5-10  
PIN-processing 1-1  
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  
PKA_Key_Token_Change (CSNDKTC) 3-22  
PKCS #1 formats D-19  
pre-exclusive-OR technique C-16  
private key  
Integrity B-8  
OPK, object protection key B-13, B-14  
procedure calls 1-8  
symmetric and asymmetric 2-13  
understanding and managing master keys 2-12  
master-key cloning 2-14  
master-key loading 2-50, 2-59, 2-64  
master-key verification pattern 2-12  
Master_Key_Distribution (CSUAMKD) 2-55  
Master_Key_Process (CSNBMKP) 2-59  
MasterCard, CVC 8-27, 8-30, E-16  
MDC keyed hash 4-12  
processing a master key 2-59, 2-64  
processing overlap 1-7  
profiles  
activating  
Overview 2-4  
Passphrase verification protocol D-16  
Passphrases 2-7  
personal identification number (PIN)  
PIN profile 8-10  
multi-coprocessor  
0S/400 support 2-11, 2-17, 2-18  
AIX, Windows and OS/2 support 2-11  
capability 2-10  
Profile data structures B-32  
Verbs for initialization and management 2-5  
pseudonyms 1-8, F-1  
CCA host implementation 2-11  
master key considerations 2-17  
multiple PIN-calculation methods 8-8  
multiply-deciphered keys 5-4, 5-18  
multiply-enciphered keys 5-3, 5-16  
R
Random generation of a new master-key 2-14  
Random_Number_Generate (CSNBRNG) 5-91  
Random_Number_Tests (CSUARNT) 2-64  
reason codes A-1  
N
non-repudiation 1-1  
null key-token 5-14, B-2  
reason_code parameter 1-11  
record-validation value (RVV) B-2  
X-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005  
CCA Release 2.54  
reenciphering keys 3-22  
replicated key-half  
export restriction 5-34, 5-42, 5-52  
export restriction an EXPORTER transport key 5-31  
Required Commands  
V
validation data 8-8  
verbs  
common parameters  
exit_data 1-11  
Description B-30  
exit_data_length 1-11  
reason_code 1-11  
return_code 1-11  
rule_array 1-12  
List of access-control-point codes G-1  
Overview 2-3  
Retained_Key_Delete (CSNDRKD) 7-21  
Retained_Key_List (CSNDRKL) 7-22  
return_code parameter 1-11  
roles, access control  
data confidentiality 6-1  
data integrity 6-1  
descriptions 1-8  
direction 1-11  
entry-point names 1-8  
list of 1-8  
parameters 1-11  
procedure calls 1-8  
processing A-1  
Default role 2-3  
Overview 2-2  
Role data structures B-29  
Verbs for initialization and management 2-5  
RSA key-pair generation D-15  
rule_array parameter description 1-12  
RVV (record-validation value) B-2  
pseudonyms 1-8, F-1  
reason codes A-1  
return codes A-1  
supported environments 1-8  
type 1-11  
S
secure-messaging-class keys 5-7  
security precautions 5-21  
variables 1-11  
segmented data 6-3  
verification pattern 5-15  
Visa, CVV 8-27, 8-30, E-16  
refid-emv.EMV PIN-block E-17  
selecting a Coprocessor resource 2-44, 2-46  
selecting key storage 2-48  
self encryption, EMV related PIN block E-19  
smart-card PIN transport E-17  
special encryption E-15  
split-knowledge security policy 5-55  
Supported environment descriptor 1-9  
symmetric and asymmetric master-keys 2-13  
symmetric keys 5-5  
X
X3.106 (CBC) method D-7  
X9.31 hash format D-19  
T
tests, control vectors C-20  
token-validation value (TVV) 5-13, B-2  
Transaction_Validation verb (CSNBTRV) 8-75  
transport key B-1  
trial pin 8-3  
TVV (token-validation value) 5-13, B-2  
U
UKPT E-13  
UKPT (unique key per transaction) 8-37, 8-42  
understanding and managing master keys 2-12  
current master-key 2-12  
new master-key 2-12  
old master-key 2-12  
unique key per transaction (UKPT) 8-37, 8-42  
unique-key-per-transaction E-13  
Index X-17  
IBM  
CCA Release 2.54  
PDF File  

HP Hewlett Packard Vp15 User Manual
Insignia NS L7HTV 10ATV User Manual
JVC 0902 NIC JET User Manual
JVC AV 32X5SU User Manual
JVC AV 1435EE User Manual
Philips 2 32E+04 User Manual
Philips 24PT633R User Manual
Philips 1015D User Manual
Philips CH1 User Manual
Philips HTS3325 User Manual