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