How it Works
IBM
Loading...
02L1333
User Manual
508 pgs1.2 Mb0
User Manual
6 pgs136.24 Kb0

IBM 02L1333 User Manual

IBM PCI Cryptographic Coprocessor
CCA Basic Services Reference and Guide Release 2.54 IBM iSeries PCICC Feature
CCA Release 2.54
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page xiii.
| Thirteenth Edition (December, 2004)
| This manual describes the IBM Common Cryptographic Architecture (CCA) Basic Services API, Release 2.54 as revised in | December 2004, implemented for the IBM eServer iSeries PCI Cryptographic Coprocessor hardware feature (#4801) and OS/400 | Option 35, CCA CSP. This Basic Services manual replaces the manuals for Releases 2.50, 2.51, 2.52, and 2.53.
IBM does not stock publications at the address given below. This and other publications related to the IBM 4758 Coprocessor can be obtained in PDF format from the Library page at http://www.ibm.com/security/cryptocards.
Readers’ comments can be communicated to IBM by using the Comments and Questions form located on the product Web site at http://www.ibm.com/security/cryptocards, or by sending a letter to:
IBM Corporation Department VM9A Security Solutions and Technology 8501 IBM Drive Charlotte, NC 28262-8563 USA
IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 1997, 2005. All rights reserved.
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
CCA Release 2.54
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
About This Publication ................................ xv
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Cryptography Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Chapter 1. Introduction to Programming for the IBM CCA ......... 1-1
What CCA Services Are Available with the IBM 4758 ............... 1-1
An Overview of the CCA Environment ........................ 1-2
How Application Programs Obtain Service .................... 1-6
Overlapped Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Host-side Key Caching ............................. 1-7
The Security API, Programming Fundamentals .................. 1-8
Verbs, Variables, and Parameters ........................ 1-8
Commonly Encountered Parameters ...................... 1-11
Parameters Common to All Verbs ...................... 1-11
Rule_Array and Other Keyword Parameters ................ 1-12
Key Tokens, Key Labels, and Key Identifiers ............... 1-12
How the Verbs Are Organized in the Remainder of the Book ......... 1-13
Chapter 2. CCA Node-Management and Access-Control .......... 2-1
CCA Access-Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Understanding Access Control .......................... 2-2
Role-Based Access Control ............................ 2-2
Understanding Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Understanding Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Initializing and Managing the Access-Control System ............. 2-5
Access-Control Management and Initialization Verbs ............ 2-5
Permitting Changes to the Configuration ................... 2-5
Configuration and Greenwich Mean Time (GMT) .............. 2-6
Logging On and Logging Off ............................ 2-7
Use of Logon Context Information ....................... 2-8
Protecting Your Transaction Information ..................... 2-9
Controlling the Cryptographic Facility ........................ 2-9
Multi-Coprocessor Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Multi-Coprocessor CCA Host Implementation ................. 2-11
OS/400 Multi-Coprocessor Support ..................... 2-11
AIX, Windows and OS/2 Multi-Coprocessor Support ........... 2-11
Understanding and Managing Master Keys .................... 2-12
Symmetric and Asymmetric Master-Keys ................... 2-13
Establishing Master Keys ............................ 2-13
Master-Key Considerations with Multiple CCA Coprocessors ........ 2-17
Access_Control_Initialization (CSUAACI) . . . . . . . . . . . . . . . . . . . . . 2-21
Access_Control_Maintenance (CSUAACM) . . . . . . . . . . . . . . . . . . . . 2-24
Cryptographic_Facility_Control (CSUACFC) . . . . . . . . . . . . . . . . . . . 2-30
Cryptographic_Facility_Query (CSUACFQ) . . . . . . . . . . . . . . . . . . . . 2-34
Cryptographic_Resource_Allocate (CSUACRA) . . . . . . . . . . . . . . . . . 2-44
Copyright IBM Corp. 1997, 2005 iii
Cryptographic_Resource_Deallocate (CSUACRD) . . . . . . . . . . . . . . . . 2-46
Key_Storage_Designate (CSUAKSD)
Key_Storage_Initialization (CSNBKSI) . . . . . . . . . . . . . . . . . . . . . . . 2-50
Logon_Control (CSUALCT)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
Master_Key_Distribution (CSUAMKD)
Master_Key_Process (CSNBMKP) . . . . . . . . . . . . . . . . . . . . . . . . . 2-59
Random_Number_Tests (CSUARNT) . . . . . . . . . . . . . . . . . . . . . . . 2-64
Chapter 3. RSA Key-Management . . . . . . . . . . . . . . . . . . . . . . . . 3-1
RSA Key-Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Key Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Key Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Reenciphering a Private Key Under an Updated Master-Key ......... 3-5
Using the PKA Keys ................................ 3-5
Using the Private Key at Multiple Nodes ..................... 3-6
Extracting a Public Key ............................... 3-6
Registering and Retaining a Public Key
PKA_Key_Generate (CSNDPKG)
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
. . . . . . . . . . . . . . . . . . . . . . . 2-48
. . . . . . . . . . . . . . . . . . . . . . . 2-55
..................... 3-6
. . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
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) Key_Export (CSNBKEX)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-42
. . . . . . . . . . . . . . . . . . . . . . 5-35
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) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-90
Random_Number_Generate (CSNBRNG) . . . . . . . . . . . . . . . . . . . . 5-91
Chapter 6. Data Confidentiality and Data Integrity .............. 6-1
Encryption and Message Authentication Codes .................. 6-1
Ensuring Data Confidentiality ........................... 6-1
Ensuring Data Integrity ............................... 6-3
MACing Segmented Data ............................ 6-3
Decipher (CSNBDEC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Encipher (CSNBENC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
MAC_Generate (CSNBMGN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
MAC_Verify (CSNBMVR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
Chapter 7. Key-Storage Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Key Labels and Key-Storage Management ..................... 7-1
Key-Label Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
DES_Key_Record_Create (CSNBKRC) ...................... 7-4
DES_Key_Record_Delete (CSNBKRD) ....................... 7-5
DES_Key_Record_List (CSNBKRL) ......................... 7-7
DES_Key_Record_Read (CSNBKRR) ....................... 7-9
DES_Key_Record_Write (CSNBKRW) ...................... 7-10
PKA_Key_Record_Create (CSNDKRC) ..................... 7-11
PKA_Key_Record_Delete (CSNDKRD) ...................... 7-13
PKA_Key_Record_List (CSNDKRL) ........................ 7-15
PKA_Key_Record_Read (CSNDKRR) ...................... 7-17
PKA_Key_Record_Write (CSNDKRW) ...................... 7-19
Retained_Key_Delete (CSNDRKD) ........................ 7-21
Retained_Key_List (CSNDRKL) .......................... 7-22
Chapter 8. Financial Services Support Verbs ................. 8-1
Processing Financial PINs .............................. 8-2
PIN-Verb Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
PIN-Calculation Method and PIN-Block Format Summary ......... 8-6
Contents v
Providing Security for PINs ............................ 8-6
Using Specific Key Types and Key-Usage Bits to Help Ensure PIN
Security
Supporting Multiple PIN-Calculation Methods
PIN-Calculation Methods
Data_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
Supporting Multiple PIN-Block Formats and PIN-Extraction Methods ... 8-10
PIN Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
PIN-Extraction Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
Personal Account Number (PAN) ...................... 8-13
Working With EMV Smart Cards .......................... 8-13
Clear_PIN_Encrypt (CSNBCPE) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Clear_PIN_Generate (CSNBPGN) . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Clear_PIN_Generate_Alternate (CSNBCPA) . . . . . . . . . . . . . . . . . . . 8-21
CVV_Generate (CSNBCSG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
CVV_Verify (CSNBCSV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-30
Encrypted_PIN_Generate (CSNBEPG) Encrypted_PIN_Translate (CSNBPTR)
Encrypted_PIN_Verify (CSNBPVR) . . . . . . . . . . . . . . . . . . . . . . . . 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
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
.................. 8-8
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
. . . . . . . . . . . . . . . . . . . . . . 8-33
. . . . . . . . . . . . . . . . . . . . . . 8-37
Appendix A. Return Codes and Reason Codes ............... A-1
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Return Code 0 ................................... A-2
Return Code 4 ................................... A-3
Return Code 8 ................................... A-4
Return Code 12 .................................. A-10
Return Code 16 .................................. A-11
Appendix B. Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Key Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Master Key Verification Pattern ......................... B-1
Token-Validation Value and Record-Validation Value ............ B-2
Null Key-Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
DES Key-Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Internal DES Key-Token ........................... B-3
External DES Key-Token ............................. B-5
RSA PKA Key-Tokens .............................. B-6
RSA Key-Token Sections ........................... B-7
PKA Key-Token Integrity ........................... B-8
Number Representation in PKA Key-Tokens ................ B-8
Chaining-Vector Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-20
Key-Storage Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21
Key_Record_List Data Set ............................. B-25
Access-Control Data Structures .......................... 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
Basic Structure of a Profile
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-32
.......................... B-32
Aggregate Profile Structure .......................... B-33
Authentication Data Structure ........................ B-33
Examples of the Data Structures ........................ B-36
Passphrase authentication data ....................... B-36
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 ............... D-2
Asymmetric Master Key MDC-Based Verification Method ........ 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
MDC-2 Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
MDC-4 Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
Ciphering Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
General Data Encryption Processes ...................... D-6
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
Triple-DES Ciphering Algorithms ........................ D-10
MAC Calculation Methods
RSA Key-Pair Generation .............................. D-15
Access-Control Algorithms
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
PIN-Calculation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2
IBM 3624 PIN-Calculation Method ....................... E-3
IBM 3624 PIN Offset Calculation Method Netherlands PIN-1 Calculation Method
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
Performing the Special Encryption and Special Decryption Processes .. E-15
CVV and CVC Method ................................ E-16
VISA and EMV-Related Smart Card Formats and Processes ......... E-17
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 ............... E-18
Derivation of the EMV TDESEMVn Tree-Based Session-Key ........ E-18
PIN-Block Self-encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-19
.............................. D-13
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-16
........................ D-16
................... E-4
..................... E-5
Appendix F. Verb List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1
Appendix G. Access-Control-Point Codes . . . . . . . . . . . . . . . . . . G-1
List of Abbreviations ................................ X-1
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-3
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-11
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-1
3-2. PKA96 Verbs with Key-Token Flow .................... 3-2
3-3. PKA_Key_Token_Build Key-Values-Structure Contents ....... 3-17
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 ................. 4-11
5-1. Basic CCA DES Key-Management Verbs ................ 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-6. Key_Token Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
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 .............. 6-1
7-1. Key-Storage-Record Services . . . . . . . . . . . . . . . . . . . . . . . 7-1
7-2. DES_Key_Record_Delete Rule_Array Keywords ............ 7-5
7-3. PKA_Key_Record_Delete Rule_Array Keywords ........... 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-35
8-9. Encrypted_PIN_Translate Rule_Array Keywords ........... 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
A-3. Reason Codes for Return Code 4 .................... A-3
A-4. Reason Codes for Return Code 8
A-5. Reason Codes for Return Code 12 ................... A-10
A-6. Reason Codes for Return Code 16 B-1. PKA Null Key-Token Format 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
B-9. RSA Private Key, 1024-Bit Modulus-Exponent Format ........ B-10
B-10. Private Key, 2048-Bit Chinese-Remainder Format .......... 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-14. RSA Private-Key Name
.............................. B-16
.......................... 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-18
B-21. RSA Public-Key Certificate(s) Signature Subsection ......... 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
.................... A-4
................... A-11
....................... B-2
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-5. PKA96 Clear DES Key Record
..................... C-14
...... C-13
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-9. Control_Vector_Translate Verb Process ................ C-23
D-1. Versions of the MDC Calculation Method ............... 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-9
D-6. Deciphering Using the ANSI X9.23 Method .............. D-9
D-7. Triple-DES CBC Encryption Process .................. D-11
D-8. Triple-DES CBC Decryption Process D-9. EDE Algorithm
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-12
.................. D-11
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-10
E-4. ISO-1 PIN-Block Format ......................... E-11
E-5. ISO-2 PIN-Block Format ......................... 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
xii IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Notices
Trademarks
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.
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 AS/400 CICS Enterprise System/3090 Enterprise System/9000 Enterprise System/9370 eServer ES/3090 ES/9000 ES/9370 IBM IBM Registry IBM World Registry iSeries Micro Channel MVS/DFP MVS/ESA MVS/SP MVS/XA Operating System/2 OS/2 Operating System/400 OS/400 Personal Security Personal System/2 pSeries PS/2 PS/ValuePoint POWERserver POWERstation RACF RS/6000 System/370 System/390 S/390 G3 Enterprise Server S/390 Multiprise Systems Application Architecture XGA xSeries zSeries
Copyright IBM Corp. 1997, 2005 xiii
The following terms, denoted by a double asterisk (**) in this publication, are the trademarks of other companies:
Diebold Diebold Inc. Docutel Docutel MasterCard MasterCard International, Inc. Pentium Intel Corporation NCR National Cash Register Corporation RSA RSA Data Security, Inc. UNIX UNIX Systems Laboratories, Inc. VISA VISA International Service Association SET 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 CoprocessorAn overview of cryptographySupported cryptographic functionsSystem hardware features and softwareOrganization 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
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
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
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-10Cryptographic_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

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 Security card 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
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 4758An overview of the CCA environmentThe Security API, programming fundamentalsHow 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
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.
The runtime software can be divided into the following categories:
1
– 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 generationDigital signature generation and verificationCryptographic key wrapping and unwrapping, including the SET-standardized
“OAEP” key-wrapping process
Data encryption and MAC generation/verificationPIN processing for the financial services industryOther 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
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 key
2
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.
2
Unless, out of the 2
Chapter 1. Introduction to Programming for the IBM CCA
168
possible values, another node randomly generates the same master-key data.
1-5
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
Loading...
+ 478 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use