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

IBM 02L1333 User Manual

Download
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
CCA Release 2.54
The security server and a directory server manage key storage. Applications can store locally used cryptographic keys in a key-storage facility. This is especially useful for long-life keys. Keys stored in key storage are referenced through the use of a key label. Before deciding whether to use the key-storage facility or to let the application retain the keys, you must consider system design trade-off factors, such as key backup, the impact of master-key changing, the lifetime of a key, and so forth.
Overlapped Processing
Calls to the CCA API are synchronous; your program loses control until the verb completes. Multiple-process threads can make concurrent calls to the API. The CCA implementation for IBM OS/2 and for Windows NT and Windows 2000 restrict the number of concurrent outstanding calls for a Coprocessor to 32.
You can maximize throughput by organizing your application(s) to make multiple, overlapping calls to the CCA API. You can also increase throughput by employing multiple Coprocessors, each with CCA (see “Multi-Coprocessor Capability” on page 2-10). The limit of 32 concurrent CCA calls applies to each Coprocessor, and therefore with multiple Coprocessors you can have more than 32 outstanding CCA API calls.
3
Within the Coprocessor, the CCA software is organized into multiple threads of processing. This multi-processing design is intended to enable concurrent use of the Coprocessor's main engine, PCI communications, DES and SHA-1 engine, and modular-exponentiation engine.
Host-side Key Caching
Beginning with Release 2, the CCA implementation provided caching of key records obtained from key storage within the CCA host code. However, the host cache is unique for each host process. If different host processes access the same key record, an update to a key record caused in one process will not affect the contents of the key cache held for other process(es). Beginning with Release 2.41, caching of key records within the key storage system can be suppressed so that all processes will access the most current key records. The techniques used to suppress key-record caching are discussed in the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual.
3
The limitation of 32 concurrent API calls does not apply to the implementation for AIX.
Chapter 1. Introduction to Programming for the IBM CCA
1-7
The Security API, Programming Fundamentals
You obtain CCA cryptographic services from the PCI Cryptographic Coprocessor through procedure calls to the CCA security application programming interface (API). Most of the services provided are considered an implementation of the IBM Common Cryptographic Architecture (CCA). Most of the extensions that differ from other IBM CCA implementations are in the area of the access-control services. If your application program will be used with other CCA products, you should compare the other-product literature for differences.
Your application program requests a service through the security API by using a procedure call for a verb.4 The procedure call for a verb uses the standard syntax of a programming language, including the entry-point name of the verb, the parameters of the verb, and the variables for the parameters. Each verb has an entry-point name and a fixed-length parameter list. See the first page of each of the following chapters to learn what verbs are provided.
The security API is designed for use with high-level languages, such as C, COBOL (OS/400), or RPG (OS/400), and for low-level languages, such as assembler. It is also designed to enable you to use the same verb entry-point names and variables in the various supported environments. Therefore, application code that you write for use in one environment generally can be ported to additional environments with minimal change.
Verbs, Variables, and Parameters
This section explains how each verb (service) is described in the reference material and provides an explanation of the characteristics of the security API.
Each callable service, or verb, has an entry-point name and a fixed-length parameter list. The reference material describes each verb and includes the following information for each verb:
Pseudonym Entry-point name Supported environment(s) Description Restrictions Format Parameters
Hardware command requirements.
Pseudonym and Entry-Point Name: Each verb has a pseudonym (general-language name) and an entry-point name (computer-language name). The entry-point name is used in your program to call the verb. Each verb's entry-point name begins with one of the following:
CSNB Generally the DES services
CSND RSA public-key services (PKA96)
4
The term verb implies an action that an application program can initiate; other systems and publications might use the term callable service instead of verb.
1-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
CSUA Cryptographic-node and hardware-control services.
The last three letters in the entry-point name identify the specific service in a group and are often the first letters of the principal words in the verb pseudonym.
Supported Environments: At the start of each verb description is a table that describes which CCA implementations support the verb. For example:
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The table indicates which models of Coprocessor support the verb and which operating system platform(s) are supported. An X indicates that the verb is supported as described.
Description: The verb is described in general terms. Be sure to read the parameter descriptions as these add additional detail. A Related Information section appears at the end of the verb material for a very few verbs.
Restrictions: Restrictions are as noted.
Format: The format section in each verb description lists the entry-point name on
the first line in bold type. This is followed by the list of parameters for the verb. Generally the input/output direction in which the variable identified by the parameter is passed is listed along with the type of variable (integer or string), and the size, number, or other special information about the variable.
The format section for each verb lists the parameters after the entry-point name in the sequence in which they must be coded.
Parameters: All information that is exchanged between your application program and a verb is through the variables that are identified by the parameters in the procedure call. These parameters are pointers to the variables contained in application program storage that contain information to be exchanged with the verb. Each verb has a fixed-length parameter list, and though all parameters are not always used by the verb, they must be included in the call. The entry-point name and the parameters for each verb are shown in the following format:
Parameter name Direction Data
Type
entry_point_name
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes parameter_5 Direction Data
Type
parameter_6 Direction Data
.
.
. parameter_n Direction Data
Type
Type
Length of Data
length
length
length
The first four parameters are the same for all of the verbs. For a description of these parameters, see “Parameters Common to All Verbs” on page 1-11. The remaining parameters (parameter_5, parameter_6, ..., parameter_n) are unique for
Chapter 1. Introduction to Programming for the IBM CCA
1-9
each verb. For descriptions of these parameters, see the definitions with the individual verbs.
Variable Direction: The parameter descriptions use the following terms to identify the flow of information:
Input The application program sends the variable to the verb (to the
called routine)
Output The verb returns the variable to the application program
In/Output The application program sends the variable to the verb, or the verb
returns the variable to the application program, or both.
Variable Type: A variable that is identified by a verb parameter can be a single value or a one-dimensional array. If a parameter identifies an array, each data element of the array is of the same data type. If the number of elements in the array is variable, a preceding parameter identifies a variable that contains the actual number of elements in the associated array. Unless otherwise stated, a variable is a single value, not an array.
For each verb, the parameter descriptions use the following terms to describe the type of variable:
Integer A four-byte (32-bit), signed, two's-complement binary number.
In the AIX and OS/400 environments, integer values are presented in four bytes in the sequence high-order to low-order (big endian). In the personal computer (Intel) environments, integer values are presented in four bytes in the sequence low-order to high-order (little endian).
String A series of bytes where the sequence of the bytes must be maintained.
Each byte can take on any bit configuration. The string consists only of the data bytes. No string terminators, field-length values, or type-casting parameters are included. Individual verbs can restrict the byte values within the string to characters or numerics.
Character data must be encoded in the native character set of the computer where the data is used. Exceptions to this rule are noted where necessary.
Array An array of values, which can be integers or strings. Only
one-dimensional arrays are permitted. For information about the parameters that use arrays, see “Rule_Array and Other Keyword Parameters” on page 1-12.
Variable Length: This is the length, in bytes, of the variable identified by the parameter being described. This length may be expressed as a specific number of bytes or it may be expressed in terms of the contents of another variable.
For example, the length of the exit_data variable is expressed in this manner. The length of the exit_data string variable is specified in the exit_data_length variable. This length is shown in the parameter tables as “exit_data_length bytes,” The rule_array variable, on the other hand, is an array whose elements are eight-byte strings. The number of elements in the rule array is specified in the rule_array_count variable and its length is shown as “rule_array_count * 8 bytes.”
Note: Variable lengths (integer, for example) that are implied by the variable data type are not shown in these tables.
1-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Commonly Encountered Parameters
Some parameters are common to all verbs, other parameters are used with many of the verbs. This section describes several groups of these parameters:
Parameters common to all verbsRule_array and other keyword parametersKey_identifiers, key_labels, and key_tokens.
Parameters Common to All Verbs
The first four parameters (return_code, reason_code, exit_data_length, and exit_data) are the same for all verbs. A parameter is an address pointer to the
associated variable in application storage.
entry_point_name
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes
return_code
The return_code parameter is a pointer to an integer value that expresses the general results of processing. See “Return Code and Reason Code Overview” for more information about return codes
reason_code
The reason_code parameter is a pointer to an integer value that expresses the specific results of processing. Each possible result is assigned a unique reason code value. See “Return Code and Reason Code Overview” for more information about reason codes.
exit_data_length
The exit_data_length parameter is a pointer to an integer value containing the length of the string (in bytes) that is returned by the exit_data value. The
exit_data_length parameter should point to a value of zero to ensure compatibility with any future extension or other operating environment.
exit_data
The exit_data parameter is a pointer to a variable-length string that contains installation-exit-dependent data that is exchanged with a preprocessing user exit or a post-processing user exit.
Note: The IBM 4758 CCA Support Program does not currently support user exits. The exit_data_length and exit_data variables must be declared in the parameter list. The exit_data_length parameter should be set to zero to ensure compatibility with any future extension or other operating environment.
Return Code and Reason Code Overview: The return code provides a general indication of the results of verb processing and is the value that your application program should use in determining the course of further processing. The reason code provides more specific information about the outcome of verb processing. Note that reason code values generally differ between CCA product implementations. Therefore, the reason code values should generally be returned to individuals who can understand the implications in the context of your application on a specific platform.
The return codes have these general meanings:
Chapter 1. Introduction to Programming for the IBM CCA
1-11
Value Meaning
0 Indicates normal completion; a few nonzero reason codes are associated with
this return code.
4 Indicates the verb processing completed, but without full success. For example,
this return code can signal that a supplied PIN was found to be invalid.
8 Indicates that the verb prematurely stopped processing. Generally the
application programmer will need to investigate the problem and will need to know the associated reason code.
12 Indicates that the verb prematurely stopped processing. The reason is most
likely related to a problem in the setup of the hardware or in the configuration of the software.
16 Indicates that the verb prematurely stopped processing. A processing error
occurred in the product. If these errors persist, a repair of the hardware or a correction to the product software may be required.
See Appendix A, “Return Codes and Reason Codes” for a detailed discussion of return codes and a complete list of all return and reason codes.
Rule_Array and Other Keyword Parameters
Rule_array parameters and some other parameters use keywords to transfer information. Generally, a rule array consists of a variable number of data elements that contain keywords that direct specific details of the verb process. Almost all keywords, in a rule array or otherwise, are eight bytes in length, and should be uppercase, left-justified, and padded with space characters. While some implementations can fold lowercase characters to uppercase, you should always code the keywords in uppercase.
The number of keywords in a rule array is specified by a rule_array_count variable, an integer that defines the number of (eight-byte) elements in the array.
In some cases, a rule_array is used to convey information other than keywords between your application and the server. This is, however, an exception.
Key Tokens, Key Labels, and Key Identifiers
Essentially all cryptographic operations employ one or more keys. In CCA, keys are retained within a structure called a key token. A verb parameter can point to a variable that contains a key token. Generally you do not need to be concerned with the details of a key token and can deal with it as an entity. See “Key Tokens” on page B-1 for a detailed description of the key-token structures.
Keys are described as either internal, operational, or external, as follows:
Internal A key that is encrypted for local use. The cryptographic engine will
decrypt (unwrap) an internal key to use the key in a local operation. Once a key is entered into the system it is always encrypted (wrapped) if it appears outside of the protected environment of the cryptographic engine. The engine has a special key-encrypting key designated a master key. This key is held within the engine to wrap and unwrap locally used keys.
Operational An internal key that is complete and ready for use. During entry of a
key, the internal key-token can have a flag set that indicates the key information is incomplete.
1-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
External A key that is either in the clear, or is encrypted (wrapped) by some
key-encrypting key other than the master key. Generally, when a key is to be transported from place to place, or is to be held for a significant period of time, it is required to encrypt the key with a transport key. A key wrapped by a transport key-encrypting key is designated external.
RSA public-keys are not encrypted values (in PKA96), and when not accompanied by private-key information, are retained in an external key-token.
Internal key-tokens can be stored in a file that is maintained by the directory server. These key tokens are referenced by use of a key label. A key label is an alphanumeric string that you place in a variable and reference with a verb parameter.
Verb descriptions specify how you can provide a key using these terms:
Key token The variable must contain a proper key-token structure.
Key label The variable must contain a key label string used to locate a key
record in key storage.
Key identifier The variable must contain either a key token or a key label. The
first byte in the variable defines if the variable contains a key token or a key label. When the first byte is in the range X'20' through X'FE', the variable is processed as a key label. There are additional restrictions on the value of a key label. See “Key-Label Content” on page 7-2. The first byte in all key-token structures is in the range of X'01' to X'1F'.X'00' indicates a DES null key-token. X'FF' as the first byte of a key-related variable passed to the API raises an error condition.
How the Verbs Are Organized in the Remainder of the Book
Now that you have a basic understanding of the API, you can find these topics in the remainder of the book:
Chapter 2, “CCA Node-Management and Access-Control” explains how the
cryptographic engine and the rest of the cryptographic node is administered. There are four topics:
– Access-control administration
– Controlling the cryptographic facility – Multi-Coprocessor support – Master-key administration.
Keeping cryptographic keys private or secret can be accomplished by retaining them in secure hardware. Keeping the keys in secure hardware can be inconvenient or impossible if there are a large number of keys, or the key has to be usable with more than one hardware device. In the CCA implementation, a master key is used to encrypt (wrap) locally used keys. The master key itself is securely installed within the cryptographic engine and cannot be retrieved as an entity from the engine.
As you examine the verb descriptions throughout this book, you will see reference to “Required Commands.” Almost all of the verbs request the cryptographic engine (the “adapter” or “Coprocessor”) to perform one or more
Chapter 1. Introduction to Programming for the IBM CCA 1-13
commands in the performance of the verb. Each of these commands has to be authorized for use. Access-control administration concerns managing these authorizations.
Chapter 3, “RSA Key-Management” explains how you can generate and
protect an RSA key-pair. The chapter also explains how you can control the distribution of the RSA private key for backup and archive purposes and to enable multiple cryptographic engines to use the key for performance or availability considerations. Related services for creating and parsing RSA key-tokens are also described.
When you wish to backup an RSA private key, or supply the key to another node, you will use a double-length DES key-encrypting key, a transport key. You will find it useful to have a general understanding of the DES key-management concepts found in chapter Chapter 5, “DES Key-Management.”
Chapter 4, “Hashing and Digital Signatures” explains how you can:
– Provide for demonstrations of the integrity of data -- demonstrate that data
has not been changed
– Attribute data uniquely to the holder of a private key.
These problems can be solved through the use of a digital signature. The chapter explains how you can hash data (obtain a number that is characteristic of the data, a digest) and how you can use this to obtain and validate a digital signature.
Chapter 5, “DES Key-Management” explains the many services that are
available to manage the generation, installation, and distribution of DES keys.
An important aspect of DES key-management is the means by which these keys can be restricted to selected purposes. Deficiencies in key management are the main means by which a cryptographic system can be broken. Controlling the use of a key and its distribution is almost as important as keeping the key a secret. CCA employs a non-secret quantity, the control vector, to determine the use of a key and thus improve the security of a node. Control vectors are described in detail in Appendix C, “CCA Control-Vector Definitions and Key Encryption.”
Chapter 6, “Data Confidentiality and Data Integrity” explains how you can
encrypt data. The chapter also describes how you can use DES to demonstrate the integrity of data through the production and verification of message authentication codes.
Chapter 7, “Key-Storage Verbs” explains how you can label, store, retrieve,
and locate keys in the cryptographic-services access-layer-managed key storage.
Chapter 8, “Financial Services Support Verbs” explains three groups of verbs
of especial use in finance industry transaction processing:
– Processing keys and information related to the Secure Electronic
Transaction (SET) protocol
– A suite of verbs for processing personal identification numbers (PIN) in
various phases of automated teller machine and point-of-sale transaction
processing
– Verbs to generate and verify credit-card and debit-card validation codes.
1-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Chapter 2. CCA Node-Management and Access-Control
This chapter discusses:
The access-control system that you can use to control who can perform various
sensitive operations at what times
Controlling the cryptographic facility
Multi-Coprocessor support
The CCA master-key, what it is, and how you manage the key
How you can initialize the cryptographic key-storage that is managed by the
support software.
The verbs that you use to accomplish these tasks are listed in Figure 2-1.
Figure 2-1. CCA Node, Access-Control, and Master-Key Management Verbs
Verb Page Service Entry
Point
Access_Control_Initialization 2-21 Initializes or updates access-control tables in the
Coprocessor.
Access_Control_Maintenance 2-24 Queries or controls installed roles and user
profiles.
Cryptographic_Facility_Control 2-30 Reinitializes the CCA application, sets the
adapter clock, resets the intrusion latch, sets the CCA environment identifier (EID), sets the number of master-key shares required and possible for distributing the master key, loads the CCA function control vector (FCV) that manages international export and import regulation limitations.
Cryptographic_Facility_Query 2-34 Retrieves information about the Coprocessor
and the state of master-key-shares distribution processing.
Cryptographic_Resource_Allocate 2-44 Connects subsequent calls to an alternative
cryptographic resource (Coprocessor).
Cryptographic_Resource_Deallocate 2-46 Reverts subsequent calls to the default
cryptographic resource (Coprocessor).
Key_Storage_Designate 2-48 Specifies the key-storage file used by the
process.
Key_Storage_Initialization 2-50 Initializes one or the other of the key-storage
files that can store DES or RSA (public/private) keys.
Logon_Control 2-52 Logs on or off the Cryptographic Coprocessor. CSUALCT E
Master_Key_Distribution 2-55 Supports the distribution and reception of
master-key shares.
Master_Key_Process 2-59 Enables the introduction of a master key into the
Coprocessor, the random generation of a master key, the setting and clearing of the master-key registers.
Random_Number_Tests 2-64 Enables tests of the random-number generator
and performance of the FIPS-mandated known-answer tests.
Service location (Svc Lcn): E=Cryptographic Engine, S=Security API software
CSUAACI E
CSUAACM E
CSUACFC E
CSUACFQ E
CSUACRA S
CSUACRD S
CSUAKSD S
CSNBKSI S/E
CSUAMKD E
CSNBMKP E
CSUARNT E
Svc Lcn
Copyright IBM Corp. 1997, 2005 2-1
CCA Access-Control
This section describes these CCA access-control system topics:
Understanding access controlRole-based access controlInitializing and managing the access-control systemLogging on and logging offProtecting your transaction information.
Understanding Access Control
Access control is the process that determines which CCA services or “commands” of the IBM 4758 PCI Cryptographic Coprocessor are available to a user at any given time. The system administrator can give users differing authority, so that some users have the ability to use CCA services that are not available to others. In addition, a given user's authority may be limited by parameters such as the time of day or the day of the week.
Also see the discussion of Access Controls in Chapter 6 of the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual.
1
Role-Based Access Control
The IBM 4758 CCA implementation uses role-based access control. In a role-based system, the administrator defines a set of roles, which correspond to the classes of Coprocessor users. Each user is enrolled by defining a user profile, which maps the user to one of the available roles. Profiles are described in “Understanding Profiles” on page 2-4.
Note: For purposes of this discussion, a user is defined as either a human user or an automated, computerized process.
As an example, a simple system might have the following three roles:
General User A user class which includes all Coprocessor users who do not have
any special privileges
Key-Management Officer Those people who have the authority to change
cryptographic keys for the Coprocessor
Access-Control Administrator Those people who have the authority to enroll new
users into the Coprocessor environment, and to modify the access rights of those users who are already enrolled.
Normally, only a few users would be associated with the Key-Management Officer role, but there generally would be a large population of users associated with General User role. The Access-Control Administrator role would likely be limited to a single “super user” since he can make any change to the access control settings. In some cases, once the system is setup, it is desirable to delete all profiles linked to Access-Control Administrator roles to prevent further changes to the access controls.
1
At the end of each CCA verb description you will find a list of commands that must be enabled to use specific capabilities of the CCA verb.
2-2 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
A role-based system is more efficient than one in which the authority is assigned individually for each user. In general, users can be segregated into just a few different categories of access rights. The use of roles allows the administrator to define each of these categories just once, in the form of a role.
Understanding Roles
Each role defines the permissions and other characteristics associated with users having that role. The role contains the following information:
Role ID A character string which defines the name of the role. This name is
referenced in user profiles, to show which role defines the user's authority.
Required User-Authentication Strength Level The access-control system is
designed to allow a variety of user authentication mechanisms. Although the only one supported today is passphrase authentication, the design is ready for others that may be used in the future.
All user-authentication mechanisms are given a strength rating, namely an integer value where zero is the minimum strength corresponding to no authentication at all. If the strength of the user's authentication mechanism is less than the required strength for the role, the user is not permitted to log on.
Valid Time and Valid Days-of-Week These values define the times of the day and
the days of the week when the users with this role are permitted to log on. If the current time is outside the values defined for the role, logon is not allowed. It is possible to choose values that let users log on at any time on any day of the week.
Notes:
1. Times are specified in Greenwich Mean Time (GMT).
2. If you physically move a Coprocessor between time zones, remember that you must resynchronize the CCA-managed clock with the host-system clock.
Permitted Commands A list defining which commands the user is allowed to
perform in the Coprocessor. Each command corresponds to one of the primitive functions which collectively comprise the CCA implementation.
Comment A 20-byte comment can be incorporated into the role for future
reference.
In addition, the role contains control and error-checking fields. The detailed layout of the role data-structure can be found in “Role Structure” on page B-29.
The Default Role: Every CCA Coprocessor must have at least one role, called the default role. Any user who has not logged on and been authenticated will operate with the capabilities and restrictions defined in the default role.
Note: Since unauthenticated users have authentication strength equal to zero, the Required User-Authentication Strength Level of the Default Role must also be zero.
The Coprocessor can have a variable number of additional roles, as needed and defined by the customer. For simple applications, the default role by itself may be sufficient. Any number of roles can be defined, as long as the Coprocessor has enough available storage to hold them.
Chapter 2. CCA Node-Management and Access-Control 2-3
Understanding Profiles
Any user who needs to be authenticated to the Coprocessor must have a user profile. Users who only need the capabilities defined in the default role do not need
a profile.
A user profile defines a specific user to the CCA implementation. Each profile contains the following information:
User ID This is the “name” used to identify the user to the Coprocessor. The User
ID is an eight-byte value, with no restrictions on its content. Although it will typically be an unterminated ASCII (or EBCDIC on OS/400) character string, any 64-bit string is acceptable.
Comment A 20-byte comment can be incorporated into the profile for future
reference.
Logon Failure Count This field contains a count of the number of consecutive
times the user has failed a logon attempt, due to incorrect authentication data. The count is reset each time the user has a successful logon. The user is no longer allowed to log on after three consecutive failures. This lockout condition can be reset by an administrator whose role has sufficient authority.
2
Role ID This character string identifies the role that contains the user's
authorization information. The authority defined in the role takes effect after the user successfully logs on to the Coprocessor.
Activation and Expiration Dates These values define the first and last dates on
which this user is permitted to log on to the Coprocessor. An administrator whose role has the necessary authority can reset these fields to extend the user's access period.
Authentication Data Authentication data is the information used to verify the
identity of the user. It is a self-defining structure, which can accommodate many different authentication mechanisms. In the current CCA implementation, user identification is accomplished by means of a passphrase supplied to the Logon_Control verb.
The profile's authentication-data field can hold data for more than one authentication mechanism. If more than one is present in a user's profile, any of the mechanisms can be used to log on. Different mechanisms, however, may have different strengths.
The structure of the authentication data is described in “Authentication Data Structure” on page B-33.
In addition, the profile contains other control and error-checking fields. The detailed layout of the profile data-structure can be found in “Profile Structure” on page B-32.
Profile(s) are stored in non-volatile memory inside the secure module on the Coprocessor. When a user logs on, his stored profile is used to authenticate the information presented to the Coprocessor. In most applications, the majority of the users will operate under the default role, and will not have user profiles. Only the security officers and other special users will need profiles.
2
In many cases, a utility program will be used to enter the user ID. That utility may restrict the ID to a specific character set.
2-4 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Initializing and Managing the Access-Control System
Before you can use a Coprocessor with newly loaded or initialized CCA support you should initialize roles, profiles, and other data. You may also need to update some of these values from time to time. Access-control initialization and management are the processes you will use to accomplish this.
You can initialize and manage the access-control system in either of two ways:
You can use the IBM-supplied utility program for your platform:
– Cryptographic Node Management utility program3 (“CNM”) (not for OS/400) – OS/400 Cryptographic Coprocessor web-based configuration utility.
You can write programs that use the access-control verbs described in this
chapter.
The verbs allow you to write programs that do more than the utility program included with the CCA Support Program. If your needs are simple, however, the utility program may do everything you need.
Access-Control Management and Initialization Verbs
Two verbs provide all of the access-control management and initialization functions:
CSUAACI Perform access-control initialization functions
CSUAACM Perform access-control management functions.
With Access_Control_Initialization, you can perform functions such as:
Loading roles and user profilesChanging the expiration date for a user profileChanging the authentication data in a user profileResetting the authentication failure-count in a user profile.
With Access_Control_Maintenance, you can perform functions such as:
Getting a list of the installed roles or user profilesRetrieving the non-secret data for a selected role or user profileDeleting a selected role or user profile from the CoprocessorGet a list of the users who are logged on to the Coprocessor.
These two verbs are fully described on pages 2-21 and 2-24, respectively. See also “Access-Control Data Structures” on page B-28.
Permitting Changes to the Configuration
It is possible to setup the Coprocessor so no one is authorized to perform any functions, including further initialization. It is also possible to setup the Coprocessor where operational commands are available, but not initialization commands, meaning you could never change the configuration of the Coprocessor. This happens if you setup the Coprocessor with no roles having the authority to perform initialization functions.
3
The Cryptographic Node Management utility is described in the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual.
Chapter 2. CCA Node-Management and Access-Control
2-5
Take care to ensure that you define roles that have the authority to perform initialization, including the RQ-TOKEN and RQ-REINT options of the Cryptographic_Facility_Control (CSUACFC) verb. You must also ensure there are active profiles that use these roles.
If you configure your Coprocessor so that initialization is not allowed, you can recover by reloading
4
the Coprocessor CCA software. This will delete all information previously loaded, and restore the Coprocessor's CCA function to its initial state.
Configuration and Greenwich Mean Time (GMT)
CCA always operates with GMT time. This means that the time, date, and day-of-the-week values in the Coprocessor are measured according to GMT. This can be confusing because of its effect on access-control checking.
All users have operating time limits, based on values in their roles and profiles. These include:
Profile activation and expiration dates Time-of-day limits Day-of-the-week limits.
All of these limits are measured using time in the Coprocessor's frame of reference, not the user's. If your role says that you are authorized to use the Coprocessor on days Monday through Friday, it means Monday through Friday in the GMT time zone, not your local time zone. In like manner, if your profile expiration date is December 31, it means December 31 in GMT.
In the Eastern United States, your time differs from GMT by four hours during the part of the year Daylight Savings Time is in effect. At noon local time, it is 4:00 PM GMT. At 8:00 PM local time, it is midnight GMT, which is the time the Coprocessor increments its date and day-of-the-week to the next day.
For example, at 7:00 PM on Tuesday, December 30 local time, it is 11:00 PM, Tuesday, December 30 to the Coprocessor. Two hours later, however, at 9:00 PM, Tuesday, December 30 local time, it is 1:00 AM Wednesday, December 31 to the Coprocessor. If your role only allows you to use the Coprocessor on Tuesday, you would have access until 8:00 PM on Tuesday. After that, it would be Wednesday in the GMT time frame used by the Coprocessor.
This happens because the Coprocessor does not know where you are located, and how much your time differs from GMT. Time zone information could be obtained from your local workstation, but this information could not be trusted by the Coprocessor; it could be forged in order to obtain access at times the system administrator intended to keep you from using the Coprocessor.
4
Use file CNWxxxyy.CLU. See Chapter 4 of the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual.
2-6 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Notes:
1. During the portions of the year when Daylight Savings Time is not in effect, the time difference between Eastern Standard Time and GMT is 5 hours.
2. In the OS/400 environment, no translation is provided for Role and Profile names. The Coprocessor will initialize the default role name to DEFAULT encoded in ASCII. OS/400 CCA users will need to consider the encoding of Role and Profile names.
Logging On and Logging Off
A user must log on to the Coprocessor in order to activate a user profile and the associated role. This is the only way to use a role other than the default role. You log on and log off using the Logon_Control verb, which is described on page 2-52.
When you successfully log on, the CCA implementation establishes a session between your application program and the Coprocessor's access-control system. The Security Application Program Interface (SAPI) code stores the logon context information, which contains the session information needed by the host computer to protect and validate transactions sent to the Coprocessor. As part of that session, a randomly derived session key, generated in the Coprocessor, is subsequently used to protect information you interchange with the Coprocessor. This protection is described in “Protecting Your Transaction Information” on page 2-9. The logon process and its algorithms are described in “Passphrase Verification Protocol” on page D-16.
On OS/2, AIX, and NT, the logon context information resides in memory associated with the process thread which performed the Logon_Control verb. On OS/400, the logon context information resides in memory owned by the process in which the application runs. Host-side logon context information can be saved and shared with other threads, processes, or programs; see “Use of Logon Context Information” on page 2-8.
Thus, on OS/2, AIX, and NT, each thread in any process can log on to the CCA access control system within a specific CCA Coprocessor. Because the Coprocessor code creates the session key, and the session key is stored in the active context information, a thread cannot concurrently be logged on to more that one Coprocessor.
In order to log on, you must prove the user's identity to the Coprocessor. This is accomplished using a passphrase, a string of up to 64 characters which are known only to you and the Coprocessor. A good passphrase should not be too short, and it should contain a mixture of alphabetic characters, numeric characters, and special symbols such as “*,” “+,” “!,” and others. It should not be comprised of familiar words or other information which someone might be able to guess.
When you log on, no part of the passphrase ever travels over any interface to the Coprocessor. The passphrase is hashed and processed into a key that encrypts information passed to the Coprocessor. The Coprocessor has a copy of the hash and can construct the same key to recover and validate the log-on information. CCA does not communicate your passphrase outside of the memory owned by the calling process.
When you have finished your work with the Coprocessor, you must log off in order to end your session. This invalidates the session key you established when you
Chapter 2. CCA Node-Management and Access-Control 2-7
logged on, and frees resources you were using in the host system and in the Coprocessor.
Use of Logon Context Information
The Logon_Control verb offers the capability to save and restore logon context information through the GET-CNTX and PUT-CNTX rule-array keywords.
The GET-CNTX keyword is used to retrieve a copy of your active logon context information, which you can then store for subsequent use. The PUT-CNTX keyword is used to make active previously stored context information. Note that the Coprocessor is unaware of what thread, program, or process has initiated a request. The host CCA code supplies session information from the active context information in each request to the Coprocessor. The Coprocessor attempts to match this information with information it has retained for its active sessions. Unmatched session information will cause the Coprocessor to reject the associated request.
As an example, consider a simple application which contains two programs, LOGON and ENCRYPT:
The program LOGON logs you on to the Coprocessor using your passphrase.
The program ENCRYPT encrypts some data. The roles defined for your
system require you to be logged on in order to use the ENCIPHER function.
These two programs must use the GET-CNTX and PUT-CNTX keywords in order to work properly. They should work as follows:
LOGON
1. Log the user on to the Coprocessor using CSUALCT verb with the PPHRASE keyword.
2. Retrieve the logon context information using CSUALCT with the GET-CNTX keyword.
3. Save the logon context information in a place that will be available to the ENCIPHER program. This could be as simple as a disk file, or it could be something more complicated such as shared memory or a background process.
ENCRYPT
1. Retrieve the logon context information saved by the LOGON program.
2. Restore the logon context information to the CCA API code using the CSUALCT verb with the PUT-CNTX keyword.
3. Encipher the data.
Note: You should take care in storing the logon context information. Design your software so that the saved context is protected from disclosure to others who may be using the same computer. If someone is able to obtain your logon context information, they may be able to impersonate you for the duration of your logon session.
2-8 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Protecting Your Transaction Information
When you are logged on to the Coprocessor, the information transmitted to and from the CCA Coprocessor application is cryptographically protected using your session key. A message authentication code is used to ensure that the data was not altered during transmission. Since this code is calculated using your session key, it also verifies that you are the originator of the request, not someone else attempting to impersonate you.
For some verbs, it is also important to keep the information secret. This is especially important with the Access_Control_Initialization verb, which is used to send new role and profile data to the Coprocessor. To ensure secrecy, some verbs offer a special protected option, which causes the data to be encrypted using your session key. This prevents disclosure of the critical data, even if the message is intercepted during transmission to the Coprocessor.
Controlling the Cryptographic Facility
There are six verbs that you can call to manage aspects of the CCA Coprocessor. One of these, the Key_Storage_Designate verb, is unique to the OS/400 implementation and allows you to select among key-storage files.
The Cryptographic_Facility_Query verb enables you to obtain the status of the CCA node. You specify one of several status categories, and the verb returns that category of status. Status information you can obtain includes:
The condition of the master-key registers: clear, full, and so forth. Note that the
extended CCA status returns information about both the symmetric and the asymmetric master-key-register sets.
The role name in effect for your processing thread.
Information about the Coprocessor hardware including the unique eight-byte
serial number. This serial number is also printed on the label on the Coprocessor's mounting bracket.
The state of the Coprocessor's battery: OK or change the battery soon.
Various tamper indications. Note that this information is also returned in
X'8040xxxx' status messages, for example, when you use the Coprocessor Load Utility.
Time and date from the Coprocessor's internal clock.
The Environment Id (EID), which is a 16-byte identifier used in the PKA92 key
encryption scheme and in master-key cloning. You assign an EID to represent the Cryptographic Coprocessor.
Diagnostic information that could be of value to product development in the
event of malfunction.
The Cryptographic_Facility_Control verb enables you to:
Reinitialize (“zeroize”) the CCA node. This is a two-step process that requires
your application to compute an intermediate value as insurance against any inadvertent reinitialize action.
Set parameters into the CCA node, other than those related to the
access-control system, including: the date and time, the function control vector
Chapter 2. CCA Node-Management and Access-Control 2-9
used to establish the maximum strength of certain cryptographic functions, the environment identifier, and the maximum number of master-key-cloning shares, and the minimum number of shares needed to reconstitute a master key.
Reset the intrusion latch. The intrusion latch circuit can be set by breaking an
external circuit connected to jack 6 (J6) on the Coprocessor. Normally the pins of J6 are connected to each other with a jumper; see the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual, Chapter
2. In your installation you might connect an external circuit to J6 that opens if covers on your host machine are opened. Note that setting the intrusion latch does not cause zeroization of the Coprocessor. If the intrusion latch is set, exception status is reported on most verb calls.
Reset the battery-low indicator (latch). The Coprocessor electronics sets the
battery-low indicator when the reserve power in the battery falls below a predetermined level. You acknowledge and reset the battery-low condition using the RESETBAT rule-array keyword. Of course if the battery has not been replaced, you should expect the low-battery-power condition to return.
The Key_Storage_Initialization verb is used to establish a fresh symmetric or asymmetric (DES or PKA) key-storage data set. The data file that holds the key records is initialized with header records that contain a verification pattern for the master key. Any existing key records in the key storage are lost. The index file is also initialized. The file names and paths for the key storage and its index file are obtained from different sources depending on the operating system:
The AIX ODM registryThe Windows registry.
See the CCA Support Program Installation Manual for information.
The Cryptographic_Resource_Allocate and Cryptographic_Resource_Deallocate verbs allow your application to steer requests to one of multiple CCA Coprocessors. See the “Multi-Coprocessor Capability” for further information.
Multi-Coprocessor Capability
Multi-Coprocessor support operates with up to eight Coprocessors installed in a single machine, some or all of which are loaded with the CCA application. When more than one Coprocessor with CCA is installed, an application program can explicitly select which cryptographic resource (Coprocessor) to use, or it can optionally accept the default Coprocessor. To explicitly select a Coprocessor, use the Cryptographic_Resource_Allocate verb. This verb allocates a Coprocessor loaded with the CCA software. Once allocated, CCA requests are routed to it until it is deallocated. To deallocate a currently allocated Coprocessor, use the Cryptographic_Resource_Deallocate verb. When a Coprocessor is not allocated (either before an allocation occurs or after the cryptographic resource is deallocated), requests are routed to the default CCA Coprocessor.
Except for the OS/400 environment, a multi-threaded application program can use all of the installed CCA Coprocessors simultaneously. A program thread can use only one of the installed CCA Coprocessors at any given time, but it can switch to a different installed CCA Coprocessor as needed. To perform the switch, a program thread must deallocate a currently allocated cryptographic resource, if any, then it must allocate the desired cryptographic resource. The
2-10 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
Cryptographic_Resource_Allocate verb will fail if a cryptographic resource is already allocated.
To determine the number of CCA Coprocessors installed in a machine, use the Cryptographic_Facility_Query verb with the STATCARD rule-array keyword. The verb returns the number of Coprocessors running CCA software. The count includes any Coprocessors loaded with CCA UDX code.
When using multiple CCA Coprocessors, you must consider the implications of the master keys in each of the Coprocessors. See “Master-Key Considerations with Multiple CCA Coprocessors” on page 2-17. You must also consider the implications of a logged-on session. See “Logging On and Logging Off” on page 2-7.
When you log on to a Coprocessor, the Coprocessor creates a session key and communicates this to the CCA host code which saves the key in a “session context” memory area. If your processing alternates between Coprocessors, be sure to save and restore the appropriate session context information.
Multi-Coprocessor CCA Host Implementation
The implementation in OS/400 host systems varies somewhat from that in the other environments. The following sections describe each approach:
OS/400 multi-coprocessor implementationAIX and Windows multi-coprocessor implementation.
OS/400 Multi-Coprocessor Support
With OS/400, the kernel-level code detects all new Coprocessors at IPL time and assigns them a resource name in the form of CRP01, CRP02, and so forth. In order to use a Coprocessor, a user must create a cryptographic device description object. When creating the device description object, the user specifies the cryptographic resource name. The name of the device description object itself is completely arbitrary. A user can call the object “BANK1,” “CRYPTO,” “CRP01,” or whatever. The device-description-object name has no bearing on which resource it names. A user could create a device-description-object named CRP01 that internally names the CRP03 resource. (Unless you are intentionally renaming a resource, such a practice would likely lead to confusion.) With the Cryptographic_Resource_Allocate and Cryptographic_Resource_Deallocate verbs, you specify a device-description-object name (and not an OS/400 resource name). If no device has been allocated, the CCA code will default to use of the object named “CRP01,” if any. If no such object exists, the verb will terminate abnormally.
Note: The scope of the Cryptographic_Resource_Allocate and the Cryptographic_Resource_Deallocate verbs is operating-system dependent. For OS/400, these verbs are scoped to a process.
AIX, Windows and OS/2 Multi-Coprocessor Support
With the first call to CCA from a process, the CCA host code associates Coprocessor designators CRP01 through CRP08 with specific Coprocessors. The host code determines the total number of Coprocessors installed through a call to
Chapter 2. CCA Node-Management and Access-Control 2-11
the Coprocessor device driver.5 The host code then polls each Coprocessor in turn to determine which ones contain the CCA application. As each Coprocessor is evaluated, the CCA host code associates the identifiers CRP01, CRP02, and so forth to the Coprocessors with CCA.
In the absence of a specific Coprocessor allocation, the host code employs the device designated CRP01 by default. You can alter the default designation by explicitly setting the CSU_DEFAULT_ADAPTER environment variable. The selection of a default device occurs with the first CCA call to a Coprocessor. Once selected, the default remains constant throughout the life of the thread. Changing the value of the environment variable after a thread uses a Coprocessor does not affect the assignment of the default CCA Coprocessor.
If a thread with an allocated Coprocessor terminates without first deallocating the Coprocessor, excess memory consumption will result. It is not necessary to deallocate a cryptographic resource if the process itself is terminating; it is only suggested if individual threads terminate while the process continues to run.
Note: The scope of the Cryptographic_Resource_Allocate and the Cryptographic_Resource_Deallocate verbs is operating-system dependent. For the AIX and Windows implementations, these verbs are scoped to a thread. "Scoped to a thread" means that each of several threads within a process can allocate a specific Coprocessor.
6
Understanding and Managing Master Keys
In a CCA node, the master key is used to encrypt (wrap) working keys used by the node that can appear outside of the cryptographic engine. The working keys are triple encrypted. This method of securing keys enables a node to operate on an essentially unlimited number of working keys without concern for storage space within the confines of the secured cryptographic engine.
The CCA design supports three master-key registers: new, current, and old. While a master key is being assembled, it is accumulated in the new master-key register. Then the Master_Key_Process verb is used to transfer (set) the contents of the new master-key register to the current master-key register.
Working keys are normally encrypted by the current master-key. To facilitate continuous operations, CCA implementations also have an old master-key register. When a new master-key is transferred to the current master-key register, the preexisting contents (if any) of the current master-key register are transferred to the old master-key register. With the IBM 4758 CCA implementation, whenever a working key must be decrypted by the master key, master-key verification pattern information that is included in the key token is used to determine if the current or the old master-key must be used to recover the working key. Special status (return code 0, reason code 10001) is returned in case of use of the old master-key so that your application programs can arrange to have the working key updated to encryption by the current master-key (using the Key_Token_Change and
5
The device driver designates the Coprocessors using numbers 0, 1, ..., 7. The number assignment is based on the design of the BIOS in a machine. BIOS routines “walk the bus” to determine the type of device in each PCI slot. Adding, removing, or relocating Coprocessors can alter the number associated with a specific Coprocessor.
6
Coprocessors loaded with a UDX extension to CCA will also be assigned a CRP0x identifier.
2-12 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
PKA_Key_Token_Change verbs). Whenever a working key is encrypted for local use, it is encrypted using the current master-key.
Symmetric and Asymmetric Master-Keys
The CCA Version 2 implementation incorporates a second set of master-key registers. One register set is used to encrypt DES (symmetric) working-keys. The second register set is used to encrypt PKA (asymmetric) private working-keys. The verbs that operate on the master keys permit you to specify a register set (with keywords SYM-MK and ASYM-MK). If your applications that modify the master-key registers never explicitly select a register set, the master keys in the two register sets are modified in the same way and will contain the same keys. However, if at any time you modify only one of the register sets, your applications will thereafter need to manage the two register sets independently.
The Cryptographic Node Management (CNM) utility does not contain logic to select a specific register set, and therefore use of CNM results in operation as though there were only a single set of registers. Note that if you use another program to modify a register in only one of the register sets, the CNM utility will no longer be usable for updating the master keys.
For consistency with the S/390 CCA implementation, you can use a symmetric-key master-key that has an effective double-length (usually master keys are triple length). To accomplish this, use the same key value for the first and third 8-byte portion of the key.
Establishing Master Keys
Master keys are established in one of three ways:
1. From clear key parts (components)
2. Through random generation internal to the Coprocessor
3. Cloning (copying encrypted shares).
Establishing a master key from clear information. Individual “key-parts”
(components) are supplied as clear information and the parts are exclusive-ORed within the cryptographic engine. Knowledge of a single part gives no information about the final key when multiple (random-valued) parts are exclusive-ORed.
A common technique is to record the values of the parts (typically on paper or diskette) and independently store these values in locked safes. When the master key is to be instantiated in a cryptographic engine, individuals who are trusted to not share the key-part information retrieve the parts and enter the information into the cryptographic engine. The Master_Key_Process verb supports this operation.
Entering the first and subsequent parts is authorized by two different control points so that a cryptographic engine (the Coprocessor) can enforce that two different roles, and thus profiles, are activated to install the master-key parts. Of course this requires that roles exist that enforce this separation of responsibility.
Setting of the master key is also a unique command with its own control point. Therefore you can set up the access-control system to require the participation of at least three individuals or three groups of individuals.
You can check the contents of any of the master-key registers, and the key parts as they are entered into the new master-key register, using the Key_Test verb.
Chapter 2. CCA Node-Management and Access-Control 2-13
The verb performs a one-way function on the key-of-interest, the result of which is either returned or compared to a known correct result.
Establishing a master key from an internally generated random value. The
Master_Key_Process verb can be used to randomly generate a new master-key within the cryptographic engine. The value of the new master-key is not available outside of the cryptographic engine.
This method, which is a separately authorized command invoked through use of the Master_Key_Process verb, ensures that no one has access to the value of the master key. Random generation of a master key is useful when the shares technique described next is used, and when keys shared with other nodes are distributed using public key techniques or when DES transport keys are established between nodes. In these cases, there is no need to re-establish a master key with the same value.
“Cloning” a master key from one cryptographic engine to another
cryptographic engine. In certain high-security applications, it is desirable to
copy a master key from one cryptographic engine to another without exposing the value of the master key. The IBM 4758 CCA implementation supports cloning the master key through a process of splitting the master key into n shares, of which m shares, 1≤m≤n≤15, are required to reconstitute the master key in another engine. The term “cloning” is used to differentiate the process from “copying” because no one share, or any combination of fewer than m shares, provide sufficient information needed to reconstitute the master key.
This secure master-key cloning process is supported by the Cryptographic Node Management (CNM) utility. See Chapter 5 and Appendix F of the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual. That utility can hold the certificates and shares in a “data base” that you can transport on diskette between the various nodes:
The certifying node public-key certificateThe Coprocessor (master key) Share-Source node public-key certificateThe Coprocessor (master key) Share-Receiving node public-key certificateThe master-key shares.
You establish the 'm' and 'n' values through the use of the Cryptographic_Facility_Control verb.
Shares of the current master-key are obtained using the Obtain mode of the Master_Key_Distribution verb. The Receive mode of the Master_Key_Distribution verb is used to enter an individual share into the receiving (target) cryptographic-engine. When sufficient shares have been entered, the verb returns status (return code 4, reason code 1024) that indicates the cloned master-key is now complete within the new master-key register of the target cryptographic-engine.
The master-key shares are signed by the source engine. Each signed share is then triple-encrypted by a fresh triple-length DES key, the share-encrypting key. A certified public-key from the target cryptographic-engine is validated, and the share-encrypting key is wrapped (encrypted) using the public key from the certificate.
At the target cryptographic-engine, an encrypted share and the wrapped share-encrypting key are presented to the engine. The private key to unwrap the share-encrypting key must exist within the cryptographic engine as a “retained key” (a private key that never leaves the engine). This private key
2-14 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
must also have been marked as suitable for operation with the Master_Key_Distribution verb when it was generated.
When receiving a share, you must also supply the share-signing key in a certificate to the Master_Key_Distribution verb. The engine validates the certificate, and uses the validated public key to validate the individual master-key share.
The certificates used to validate the share-signing public key and the target-engine public key used to wrap the share-encrypting key are validated by the cryptographic engines using a retained public-key. A retained public-key is introduced into a cryptographic engine in a two-part process using the PKA_Public_Key_Hash_Register and PKA_Public_Key_Register verbs. This allows you to establish two distinct roles to enforce dual control. Two different individuals are authorized so that split authority and dual control can be enforced in setting up the certificate validating public key.
You identify the nodes with unique 16-byte identifiers of your choice. The environment ID (EID) is also established through the use of the Cryptographic_Facility_Control verb.
The processing of a given share (share 1, 2, ..., n) requires authorization to a distinct control point so that you can enforce split responsibility in obtaining and installing the shares.
The certifying node can be either the share source or target node as you desire, or can be an independent node that might be located in a cryptographic control center.
Although not currently supported by IBM products, the shares could be stored on intermediate devices (for example, smart cards), provided that the devices could perform the required key-management and digital-signature functions.
With the current capabilities of the IBM 4758 CCA Support Program, you must initialize the target Coprocessor with its retained private key and have the associated public-key certified before you obtain shares for the target Coprocessor. This implies that the target Coprocessor has been initialized and is not reset before a master key is cloned to the Coprocessor.
Chapter 2. CCA Node-Management and Access-Control 2-15
┌──────────────────────────────────┐
3. │ │ ││
└─────────│─────────│──────────────┘ ││ ┌────────────────────────┐ │ │ ┌────────────────────────┐ │CCA Cryptographic Engine│ │ │ │CCA Cryptographic Engine│ │(Primary = 'a') │ │ │ │('b') │ │ │ │ │ │ │ │ 1 ──── Roles, Profiles, │ Roles, Profiles,──── 1 │ │ │ m_of_n, EID│ │ m_of_n, EID │ │ │ │ │ │ │ │ │ 2 ──── Audit │ │ Audit ──── 2 │ │ │ │ │ │ │ │ 4 ──────────────────────────┴───────────────────── 4 │ │ │ │ │ │ │ 5 ────────────────┴─────────────────────────────── 5 │ │ │ │ │ │ │ Certify by SA │ │ │ │ ││ │ │ │ Gererate CSS 6 ─────────Pu{CSS}─┘ ││ │ │ │ │ │─CERT{SA}(Pu{CSS})┘│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─Pu{CSR_i}──────── 7 Generate CSR │ │ │ │ └CERT{SA}(Pu{CSR_i})─│ │ │ ││ ││ │ │ 8 ─────┼────────────────────────────────────┘ │ │ │ │ │ │ │ │ ──────┼─Pu{CSR_i}(SE_j), │ │ │ │ │ eSE_j(j,mks_j,SIG{CSS}(j,mks_j))───── 9 │ │ │ │ (m times) │ │ │ │ └────────────────────────────────────────── │ │ │ │ │ │ │ Set and Verify ──── 1 │ │ │ the master key ──── │ │ │ │ │ └────────────────────────┘ └────────────────────────┘
│Share─Administration Control Point│
│ CERT{SA}(SA) H(CERT{SA}(SA)) │ │ ───────┬──── ───┬─────────── │ │ │ │ │
Figure 2-2. Coprocessor-to-Coprocessor Master-Key Cloning
Figure 2-2 depicts the steps of a master-key cloning scenario. These steps include:
1. Install appropriate access-control roles and profiles, m-of-n, and EID values. Have operators change their profile passwords. Ensure that the roles provide the degree of responsibility-separation that you require.
2. Audit the setup of the Share Administration, Share Source, and Share Receiving nodes.
3. Generate a retained RSA private key, the Share-Administration (SA) key. This key is used to certify the public keys used in the scheme. Self-certify the SA key. Distribute the hash of this certificate to the source and share-receiving node(s) under dual control.
4. Install (register) the hash of the SA public-key in both the source and receiving nodes.
5. Install (register) the SA public-key in both the source and receiving nodes. Two different roles can be used to permit this and the prior step to aid in ensuring dual control of the cloning process.
6. In the source node, generate a retained key usable for master-key administration, the Coprocessor Share Signing (CSS) key, and have this key certified by the SA key.
2-16 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
7. In the target node, generate a retained key usable for master-key administration, the Coprocessor Share Receiving (CSR) key, and have this key certified by the SA key.
8. Once a master key has been established in the source node, perhaps through random master-key generation, obtain shares of the master key. Also obtain master-key verification information for use in step 10 using the Key_Test verb. Note that generally fewer shares are required to reconstitute the master key than that which can be obtained from the source node. Thus corruption of some of the information that is in transit between source and target can be tolerated.
9. Deliver and install the master-key shares.
10. Verify that the new master-key in the target node has the proper value. Then set the master key.
Master-Key Considerations with Multiple CCA Coprocessors
Master keys are used to wrap (encrypt) working keys (as opposed to clear keys or keys wrapped by key-encrypting keys or RSA keys). Master-key-wrapped keys are either stored in the CCA key storage, or are held and managed by your application(s). When multiple Coprocessors are installed, it is a responsibility of the using organization(s) to ensure that appropriate current and old master-keys, both symmetric and asymmetric, are installed in the multiple Coprocessors. The most straightforward approach is to ensure that when you change (“set”) master keys on one CCA Coprocessor, you also change the master keys (both asymmetric and symmetric) on the other Coprocessor(s).
The approach to multiple Coprocessors differs in detail between OS/400 and the workstation environments. Each type of environment is discussed:
OS/400
AIX and Windows.
OS/400 Multi-Coprocessor Master-Key Support: IBM recommends loading all CCA Coprocessors with the same current and the same old master-keys, especially if your applications perform load balancing among the Coprocessors or if the Coprocessors will be used for SSL.
With OS/400, multiple key-storage files can exist. To avoid confusion, keep all keys in the key-storage files encrypted by a common, current master-key. The master-key verification pattern is not stored in the header record of any key-storage file. Therefore, it is important that when you change the master key, you re-encipher all of the keys in all of your key-storage files. The organization that manages all users of the Coprocessors must arrange procedures for keeping all key-storage files up to date with the applicable current master-key. Note that the person changing the master key may not have authorization to (or knowledge of) all key-storage files on the system.
The order of loading and setting of the master key between Coprocessors is not significant. However, be sure that after all Coprocessor master-keys have been updated that you then update all key-storage files. Remember that if you import a key or generate a key, it is returned encrypted by the current master-key within the Coprocessor used for the task.
Chapter 2. CCA Node-Management and Access-Control 2-17
AIX and Windows Multi-Coprocessor Master-Key Support: It is a general recommendation that all of the CCA Coprocessors within the system use the same current and old master keys. When setting a new master-key, it is essential that all of the changes are performed by a single program running on a single thread. If the thread-process is ended before all of the Coprocessor master-keys are changed, significant complications can arise. It is suggested that you start the CNM utility and use it to make all of the changes before you end the utility.
If you fail to change all of the master keys with the same program running on the same thread, either because there is an unplanned interruption, or perhaps because you intend to have different master keys between Coprocessors, you need to understand the design of the CCA host code that is described next.
CCA Host Code Design: (AIX and Windows) CCA keeps a copy of the symmetric or the asymmetric current-master-key verification pattern in the key-storage header records. This information is used to ensure that a given key-storage file is associated with a Coprocessor having the same current master-key. This can prevent accessing an out-of-date key-storage backup file. The verification pattern is written into the header record when key storage is initialized, and when the current master-key is changed in a Coprocessor.
CCA also keeps two flags in memory associated with a host-processing thread. If there are multiple threads, each thread has its own set of flags. The flags, symmetric-directory-open (SDO) and asymmetric-directory-open (ADO), are set to false when CCA processing begins on the thread.
When a CCA verb is called and a key storage is referenced, and if the associated flag (SDO or ADO) is false, CCA obtains the verification pattern for the current master-key and compares this to the header-record information. If the patterns match, the flag is set to true, and processing continues. If the existing patterns do not match, processing is terminated with an error indication. If there is no current master-key or if key storage has not been initialized, processing continues although, depending on the CCA verb, other error conditions may arise.
A key-storage reference occurs in two cases:
1. When the verb call employs a key label
2. When the SET master-key option is used on the Master_Key_Process verb.
Situations to Consider: Given the design of the host code, when you employ multiple Coprocessors with CCA, you should consider the following cases in regard to master keys. Remember that if you explicitly manage the symmetric or the asymmetric master keys (using the SYM-MK or ASYM-MK keywords on the Master_Key_Process verb), you have both master keys and both key storages to consider. If you do not explicitly manage the two classes of master keys, then the implementation will operate as though there is a single set of master keys. The CNM utility provided with the CCA Support Program does not explicitly manage the two sets of keys and the program design assumes that the master keys have always been managed without explicit reference to the symmetric or the asymmetric keys.
Setting master keys in multiple Coprocessors.
If, as recommended, you keep the master keys the same in all of the CCA Coprocessors, and you set the master key in each of the Coprocessors from a single program running on the same thread, the following will take place:
2-18 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54
When all of the Coprocessors are newly initialized, that is, their
current-master-key registers are empty, first install the same master key in each of the new-master-key registers. Then set the master key in each of the Coprocessors. Finally, if you are going to use key storage, initialize key storage.
If all of the Coprocessors have the same current master-key, when you
undertake to set the master key in the first Coprocessor, the code will attempt to set the directory-open flags (SDO and ADO). This should succeed if you have the proper key-storage files (or key storage is not initialized). Note that the verification pattern in the key-storage header is changed as soon as the first master-key is set.
When you set the master key in the additional Coprocessors, because the directory-open flags are already set, no check is made to ensure that the verification patterns in key storage and for the current-master-key match (and they would not match because the header was updated when the first Coprocessor master-key was set). As soon as the master key is set, its verification pattern will be copied to the header in key storage.
Note that the key in the new-master-key register is not verified. You may wish to confirm the proper and consistent contents of these registers using the key-test service prior to undertaking setting of the master keys.
Setting the master key in a Coprocessor after other Coprocessor(s) are
successfully in operation.
If you have one or more Coprocessors in operation and then wish to add an additional Coprocessor and need to set its current, and possibly old, master keys to the keys already in the other Coprocessors, special care must be taken. Two cases should be considered:
1. If the new Coprocessor has a current master-key that is not the same as that in the other Coprocessors, and if key storage is initialized for use with the other Coprocessors, when you start a new thread and attempt to set the master key, the action will fail unless you take precautions. Because the directory-open flag(s) are initially set to false, the CCA host code will compare the verification pattern for the current master-key in the Coprocessor and in the key-storage header record. This comparison will fail and processing will terminate with an error indication.
2. If the new Coprocessor did not have a key in the current master-key register, the set-master-key operation would proceed. Note that the verification pattern for this master key will be copied to an initialized key-storage header record.
A solution to the first situation is to proceed as follows:
Allocate a Coprocessor that has the desired current master key(s)Perform a DES_Key_Record_List or other action that will cause the
key-storage-valid flag(s) to be set.
Deallocate the CoprocessorAllocate the new CoprocessorSet the master key.
Note that you may need to install two master keys into the new Coprocessor in order have both the current and the old master-keys agree with those in the other Coprocessor(s).
Chapter 2. CCA Node-Management and Access-Control 2-19
Intentionally using different master keys in a set of Coprocessors.
This situation becomes very complicated if you are using key storage with a subset of the Coprocessors. The preceding discussion provides information that you can use to manage this case. If you are not using key storage and have not initialized key storage files, then the situation is quite simple. Just load and set the master keys as you would in a single-Coprocessor situation.
Note that while you are changing master keys in a multiple-Coprocessor arrangement, it may be undesirable to continue other cryptographic processing. Several problems should be considered:
1. Keys generated or imported and returned enciphered with the latest master key are not usable with other Coprocessors until they too have been updated with the latest master key. Existing keys may still be usable since the previous master key in the updated Coprocessor(s) will be in the old master-key register and CCA can use this to recover the working keys.
2. The header record in the key-storage file may have been altered to an undesirable value--refer to the earlier discussion.
3. If you set the master key without specifically mentioning symmetric or asymmetric keys (this is the way the CNM utility operates), and if you are using key storage, you will need to have both the symmetric and the asymmetric key storage files initialized, even if you do not place keys in one or both of the key storages files.
2-20 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Access_Control_Initialization
Access_Control_Initialization (CSUAACI)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Access_Control_Initialization verb is used to initialize or update parameters and tables for the Access-Control system in the 4758 Cryptographic Coprocessor.
You can use this verb to perform the following services:
Load roles and user profiles
Change the expiration date for a user profile
Change the authentication data, such as a passphrase, in a user profile
Reset the authentication failure count in a user profile.
You select which service to perform by specifying the corresponding keyword in the input rule-array. You can only perform one of these services per verb call.
Restrictions
None
Format
CSUAACI
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one, two, or three rule_array Input String
verb_data_1_length Input Integer verb_data_1 Input String verb_data_1_length bytes verb_data_2_length Input Integer verb_data_2 Input String verb_data_2_length bytes
rule_array_count * 8 bytes
array
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one, two, or three for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
Chapter 2. CCA Node-Management and Access-Control 2-21
Keyword Meaning
Function to perform (one required)
INIT-AC Initializes roles and user profiles.
CHGEXPDT Changes the expiration date in a user profile.
CHG-AD Changes authentication data in a user profile or changes a
user's passphrase.
Note: The PROTECTD keyword must also be used whenever you use CHG-AD. You must authenticate yourself before you are allowed to change authentication data, and the use of protected mode verifies that you have been authenticated.
RESET-FC Resets the count of consecutive failed logon attempts for a
user. Clearing the failure count permits a user to log on again, after being locked out due to too many failed consecutive attempts.
Options (one or two, optional)
PROTECTD Specifies to operate in protected mode. Data sent to the
Coprocessor is protected by encrypting the data with the user's session key, KS.
If the user has not successfully logged on, there is no session key in effect, and the PROTECTD keyword will result in an abnormal termination.
REPLACE Specifies that a new profile can replace an existing profile with
the same name. This keyword applies only when the rule array contains the INIT-AC keyword.
Without the REPLACE keyword, any attempt to load a profile which already exists will be rejected. This protects against accidentally overlaying a user's profile with one for a different user who has chosen the same profile ID as one that is already on the Coprocessor.
verb_data_1_length
The verb_data_1_length parameter is a pointer to an integer variable containing the number of bytes of data in the verb_data_1 variable.
verb_data_1
The verb_data_1 parameter is a pointer to a string variable containing data used by the verb.
This field is used differently depending on the function being performed.
Rule-Array Keyword
INIT-AC The field contains a list of zero or more user profiles to be
CHGEXPDT, CHG-AD, or RESET-FC
Contents of verb_data_1 field
loaded into the Coprocessor. See “Profile Structure” on page B-32.
The field contains the eight-character profile ID for the user profile that is to be modified.
2-22 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Access_Control_Initialization
verb_data_length_2
The verb_data_length_2 parameter is a pointer to an integer variable containing the number of bytes of data in the verb_data_2 variable.
verb_data_2
The verb_data_2 parameter is a pointer to a string variable containing data used by the verb. Authentication data structures are described in “Access-Control Data Structures” on page B-28.
This field is used differently depending on the function being performed.
Rule-Array Keyword
INIT-AC The field contains a list of zero or more roles to be loaded into
CHGEXPDT The field contains the new expiration date to be stored in the
CHG-AD The field contains the new authentication-data, to be used in
RESET-FC The verb_data_2 field is empty. Its length is zero.
Required Commands
The Access_Control_Initialization verb requires the following commands to be enabled:
 Initialize the access-control system roles and profiles (offset X'0112') with the
INIT-AC keyword. See “Profile Structure” on page B-32.
Contents of verb_data_2 field
the Coprocessor. See “Role Structure” on page B-29.
specified user profile. The expiration date is an eight-character string, in the form YYYYMMDD.
the specified user profile.
If the profile currently contains authentication data for the same authentication mechanism, that data is replaced by the new data. If the profile does not contain authentication data for the mechanism, the new data is added to the data currently stored for the specified profile.
 Change the expiration date in a user profile (offset X'0113') with the
CHGEXPDT keyword.
 Change the authentication data in a user profile (offset X'0114') with the
CHG-AD keyword.
 Reset the logon failure count in a user profile (offset X'0115') with the
RESET-FC keyword.
Chapter 2. CCA Node-Management and Access-Control 2-23
Access_Control_Maintenance (CSUAACM)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Access_Control_Maintenance verb is used to query or control installed roles and user profiles.
You can use this verb to perform the following services:
Retrieve a list of the installed roles or user profiles
Retrieve the non-secret data for a selected role or user profile
Delete a selected role or user profile from the Coprocessor
Retrieve a list of the users who are logged on to the Coprocessor.
You select which service to perform by specifying the corresponding keyword in the input rule-array. You can only perform one of these services per verb call.
Restrictions
None
Format
CSUAACM
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one rule_array Input String
name Input String 8 bytes output_data_length In/Output Integer output_data Output String output_data_length bytes
rule_array_count * 8 bytes
array
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
2-24 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Access_Control_Maintenance
Keyword Meaning
Function to perform (one required)
LSTPROFS Retrieves a list of the user profiles currently installed in the
Coprocessor.
Keyword Q-NUM-RP shows how to determine how much data this request will return to the application program.
LSTROLES Retrieves a list of the roles currently installed in the
Coprocessor.
Keyword Q-NUM-RP shows how to determine how much data this request will return to the application program.
GET-PROF Retrieves the non-secret part of a specified user profile.
GET-ROLE Retrieve the non-secret part of a role definition from the
Coprocessor.
DEL-PROF Deletes a specified user profile.
DEL-ROLE Deletes a specified role definition from the Coprocessor.
Q-NUM-RP Queries the number of roles and profiles presently installed in
the Coprocessor. This allows the application program to know how much data will be returned with the LSTROLES or
LSTPROFS keywords.
Q-NUM-UR Queries the number of users currently logged on to the
Coprocessor. This allows the application program to know how much data will be returned with the LSTUSERS keyword.
Users may log on or log off between the time you use Q-NUM-UR and the time you use LSTUSERS, so the list of users may not always contain exactly the number the Coprocessor reported was logged on.
LSTUSERS Retrieves a list of the profile IDs for all users who are
currently logged on to the Coprocessor.
name
The name parameter is a pointer to a string variable containing the name of a role or user profile which is the target of the request.
This field is used differently depending on the function being performed.
Rule-Array Keyword
LSTPROFS, LSTROLES, Q-NUM-RP, Q-NUM-UR, or LSTUSERS
GET-PROF or DEL-PROF
GET-ROLE or DEL-ROLE
Chapter 2. CCA Node-Management and Access-Control 2-25
Contents of name variable
The name field is unused.
The name field contains the eight-character profile ID for the user profile that is to be retrieved or deleted.
The name field contains the eight-character role ID for the role definition that is to be retrieved or deleted.
output_data_length
The output_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the output_data variable. The value must be a multiple of four bytes.
On input, the output_data_length variable must be set to the total size of the variable pointed to by the output_data parameter. On output, this variable will contain the number of bytes of data returned by the verb in the output_data variable.
output_data
The output_data parameter is a pointer to a string variable containing data returned by the verb. Any integer value returned in the output_data field is in big-endian format; the high-order byte of the value is in the lowest-numbered address in storage. Authentication data structures are described in “Access-Control Data Structures” on page B-28.
This field is used differently depending on the function being performed.
Rule-Array Keyword
LSTPROFS Contains a list of the profile IDs for all the user profiles stored
LSTROLES Contains a list of the role IDs for all the roles stored in the
Contents of output_data Variable
in the Coprocessor.
Coprocessor.
2-26 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Access_Control_Maintenance
Rule-Array Keyword
GET-PROF Contains the non-secret portion of the selected user profile.
Contents of output_data Variable
This includes the following data, in the order listed.
Profile version Two bytes containing 2 one-byte integer
values, where the first byte contains the major version number and the second byte contains the minor version number.
Comment A 20-character field, padded on the right with
spaces, which describes the profile. This field is not X'00' terminated.
Role The eight-character name of the user's assigned
role.
Logon failure count A one-byte integer containing the
number of consecutive failed logon attempts by the user.
Pad A one-byte padding value containing X'00'.
Activation date The first date on which the profile is valid.
The date consists of a two-byte integer containing the year, followed respectively by a one-byte integer for the month and a one-byte integer for the day of the month.
Expiration date The last date on which the profile is valid.
The format is the same as the Activation date described above.
List of enrolled authentication mechanism information For
each authentication mechanism associated with the profile, the verb returns a series of three integer values:
1. The two-byte Mechanism ID
2. The two-byte Mechanism Strength
3. The four-byte authentication data Expiration
date, which has the same format as the Activation date described above.
Note that the authentication data itself is not returned, only the IDs, strength, and expiration date of the data are returned.
Chapter 2. CCA Node-Management and Access-Control 2-27
Rule-Array Keyword
GET-ROLE The field contains the non-secret portion of the selected role.
DEL-PROF or DEL-ROLE
Q-NUM-RP The variable contains an array of two four-byte integers. The
Q-NUM-UR The variable contains a single integer value which indicates
LSTUSERS The variable contains an array of eight-character profile IDs,
Contents of output_data Variable
This includes the following data, in the order listed.
Role version Two bytes containing integer values, where the
first byte contains the major version number and the second byte contains the minor version number.
Comment A 20-character field, padded with spaces,
containing a comment which describes the role. This field is not X'00' terminated.
Required authentication-strength level A two-byte integer
defining how secure the user authentication must be in order to authorize this role.
Lower time-limit The earliest time of day that this role can be
used. The time limit consists of two integer values, a one-byte hour, followed by a one-byte minute. The hour can range from 0-23, and the minute can range from 0-59.
Upper time-limit The latest time of day that this role can be
used. The format is the same as the Lower time-limit.
Valid days of the week A one-byte field defining which days
of the week this role can be used. Seven bits of the byte are used to represent Sunday through Saturday, where a '1' bit means that the day is allowed, while a '0' bit means it is not.
The first bit (MSB) is for Sunday, and the last bit (LSB) is unused and is set to zero.
Access-control-point list The access-control-point bit map
defines which functions a user with this role is permitted to run.
The variable is empty. Its length is zero.
first integer is the number of roles currently loaded with use of the Access_Control_Initialization verb, while the second integer is the number of user profiles currently loaded with use of the same verb.
the number of users currently logged on to the Coprocessor.
one for each user currently logged on to the Coprocessor. The list is not in any meaningful order.
2-28 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Access_Control_Maintenance
Required Commands
The Access_Control_Maintenance verb requires the following commands to be enabled in the hardware:
Read public access-control information (offset X'0116') with the LSTPROFS,
LSTROLES, GET-PROF, GET-ROLE, and Q-NUM-RP keywords
Delete a User Profile (offset X'0117') with the DEL-PROF keyword
Delete a Role (offset X'0118') with the DEL-ROLE keyword.
Chapter 2. CCA Node-Management and Access-Control 2-29
Cryptographic_Facility_Control (CSUACFC)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
Use the Cryptographic_Facility_Control verb to perform the following services:
Reinitialize the CCA application in the Coprocessor.
Set the date and time in the Coprocessor clock.
Reset the Coprocessor Intrusion Latch (see page 2-10)
Reset the Coprocessor Battery-Low Indicator (see page 2-10)
Load or clear the Function Control Vector, which defines limitations on the
cryptographic functions available in the Coprocessor.
Establish the environment identifier (EID), which is a user-defined identifier.
Once set, the EID can only be set again following a CCA reinitialization.
Establish the minimum and maximum number of “cloning information” shares
that are required and that can be used to pass sensitive information from one Coprocessor to another Coprocessor.
Select which service to perform by specifying the corresponding keyword in the input rule-array. You can only perform one of these services per verb call.
Restrictions
Format
Use only these characters in an environment identifier (EID): A...Z, a...z, 0...9, and these additional characters relating to different character symbols in the various national language character sets as listed below:
ASCII Systems
X'20' X'40' space character X'26' X'50' & X'3D' X'7E' = X'40' X'7C' @
EBCDIC Systems
USA Graphic (for reference)
The alphabetic and numeric characters should be encoded in the normal character set for the computing platform that is in use, either ASCII or EBCDIC.
CSUACFC
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one or two rule_array Input String
array
verb_data_length In/Output Integer verb_data In/Output String verb_data_length bytes
rule_array_count * 8 bytes
2-30 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Control
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters.
This verb requires two keywords in the rule array. One specifies the Coprocessor for which the request is intended, the other specifies the function to perform. No rule-array elements are set by the verb. The rule_array keywords are shown below:
Keyword Meaning
Coprocessor to use (optional)
ADAPTER1 This keyword is ignored. It is accepted for backward
compatibility.
Control function to perform (one required)
RQ-TOKEN Requests a random eight-byte token from the adapter, which
is returned in the verb_data variable. This is the first step when reinitializing the Coprocessor.
The second step for reinitialization uses RQ-REINT, described below.
RQ-REINT Reinitializes the CCA application in the Coprocessor. For
RQ-REINT, you must set the verb_data field to the one's
complement of the token that was returned by the Coprocessor when you executed the verb using the RQ-TOKEN keyword. This is the second and final step when reinitializing the Coprocessor.
This two-step process provides protection against accidental reinitialization of the Coprocessor.
SETCLOCK Sets the date and time of the Coprocessor's secure clock.
You must put the date and time values in the verb_data variable, as described under the description of that parameter.
RESET-IL Clears the Intrusion Latch on the Coprocessor.
RESETBAT Clears the Battery-Low Indicator (latch) on the Coprocessor.
LOAD-FCV Loads a new Function Control Vector into the Coprocessor.
CLR-FCV Clears the Function Control Vector from the Coprocessor.
SET-EID Sets an environment identifier (EID) value.
SET-MOFN Sets the minimum and maximum number of “cloning
information” shares that are required and that can be used to pass sensitive information from one Coprocessor to another Coprocessor.
Chapter 2. CCA Node-Management and Access-Control 2-31
verb_data_length
The verb_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the verb_data variable. On input, specify the size of the variable. The verb updates the variable with the size of the returned data.
verb_data
The verb_data parameter is a pointer to a string variable containing data used by the verb on input, or generated by the verb on output.
This field is used differently depending on the value of the control function selected by a rule-array keyword.
For RQ-TOKEN, verb_data is an output parameter. It receives an
eight-byte randomly generated value, which the application uses with the RQ-REINT keyword on a subsequent call.
On input, the verb_data_length variable must contain the length of the buffer addressed by the verb_data pointer. Allocate an eight-byte buffer and specify this length in the verb_data_length variable.
For RQ-REINT, verb_data is an input parameter. You must set it to the
one's complement of the token you received as a result of the RQ-TOKEN call. Allocate an eight-byte buffer and specify this length in the verb_data_length variable.
For SETCLOCK, verb_data is an input variable. It must contain a
character string which contains the current GMT date and time. Allocate a 16-byte buffer and specify this length in the verb_data_length variable. This string has the form YYYYMMDDHHmmSSWW, where these fields are defined as follows.
YYYY The current year
MM The current month, from 01 to 12
DD The current day of the month, from 01 to 31
HH The current hour of the day, from 00 to 23
mm The current minutes past the hour, from 00 to 59
SS The current seconds past the minute, from 00 to 59
WW The current day of the week, where Sunday is represented as 01,
and Saturday by 07.
For LOAD-FCV, verb_data is an input variable. It must contain a character
string which contains the function control vector (FCV) as described in “Function Control Vector” on page B-42. Allocate a 204-byte buffer and specify this length in the verb_data_length variable.
For CLR-FCV, no data is provided and the verb_data_length variable
should be set to zero.
For SET-EID, verb_data is an input variable. The variable contains a
16-byte environment identifier, or EID, value. This identifier is used in verbs such as PKA_Key_Generate and PKA_Symmetric_Key_Import. See “Restrictions” on page 2-30 for a list of valid characters in an environment identifier. Allocate a 16-byte buffer and specify this length in the verb_data_length variable.
2-32 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Control
For SET-MOFN, verb_data is an input variable. The variable contents
establish the minimum and maximum number of “cloning information” shares that are required and that can be used to pass sensitive information from one Coprocessor to another Coprocessor. The verb_data variable contains a two-element array of integers. The first element is the m minimum required number of shares to reconstruct cloned information (see the Master_Key_Distribution verb). The second element is the n maximum number of shares that can be issued to reconstruct cloned information (see the Master_Key_Distribution verb). Allocate an eight-byte buffer (two, four-byte integers) and specify this length in the verb_data_length variable.
Required Commands
The Cryptographic_Facility_Control verb requires the following commands to be enabled in the hardware:
Reinitialize Device (offset X'0111') with the RQ-TOKEN, RQ-REINT keywords
Set Clock (offset X'0110') with the SETCLOCK keyword
Reset Intrusion Latch (offset X'010F') with the RESET-IL keyword
Reset Battery-LOW Indicator (offset X'030B') with the RESETBAT keyword
Load a Function Control Vector (offset X'0119') with the LOAD-FCV keyword
Clear the Function Control Vector (offset X'011A') with the CLR-FCV keyword
Set EID command (offset X'011C') with the SET-EID keyword
Initialize Master Key Cloning command (offset X'011D') with the SET-MOFN
keyword.
Chapter 2. CCA Node-Management and Access-Control 2-33
Cryptographic_Facility_Query (CSUACFQ)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Cryptographic_Facility_Query verb is used to retrieve information about the Cryptographic Coprocessor and the CCA application program in that Coprocessor. This information includes the following:
General information about the CoprocessorGeneral information about the CCA application program in the CoprocessorStatus of master-key shares distributionEnvironment identifier, EIDDiagnostic information from the CoprocessorExport-control information from the CoprocessorTime and date information.
On input, you specify:
A rule-array count of one or twoOptionally a rule-array keyword of ADAPTER1The class of information queried with a rule-array keyword.
The verb returns information elements in the rule array and sets the rule-array-count variable to the number of returned elements.
Restrictions
Format
Parameters
You cannot limit the number of returned rule-array elements. Figure 2-3 on page 2-35 describes the number and meaning of the information in output rule-array elements. You are advised to allocate a minimum of 30 rule-array
elements to allow for extensions of the returned information.
CSUACFQ
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length rule_array_count In/Output Integer one or two on input rule_array In/Output String
array
verb_data_length In/Output Integer verb_data In/Output String verb_data_length bytes
rule_array_count * 8 bytes
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. On input, the value must be one or two for this verb.
2-34 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Query
On output, the verb sets the variable to the number of rule-array elements it returns to the application program.
Note: With this verb, the number of returned rule-array elements can exceed the rule-array count that you specified on input. Be sure that you allocate adequate memory to receive all of the information elements according to the information class that you select on input with the information-to-return keyword in the rule-array.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters.
On input, set the rule array to specify the type of information to retrieve. There are two input rule_array elements, as described below.
Keyword Meaning
Adapter to use (optional)
ADAPTER1 This keyword is ignored. It is accepted for backward
compatibility.
Information to return (one required)
STATCCA Gets CCA-related status information.
STATCCAE Gets CCA-related extended status information.
STATCARD Gets Coprocessor-related basic status information.
STATDIAG Gets diagnostic information.
STATEID Gets the environment identifier, EID.
STATEXPT Gets function control vector-related status information.
STATMOFN Gets master-key shares distribution information.
TIMEDATE Reads the current date, time, and day of the week from the
secure clock within the Coprocessor.
The format of the output rule-array depends on the value of the rule-array element which identifies the information to be returned. Different sets of rule-array elements are returned depending on whether the input keyword is
STATCCA, STATCCAE, STATCARD, STATDIAG, STATEID, STATEXPT, or STATMOFN, TIMEDATE.
For rule-array elements that contain numbers, those numbers are represented by numeric characters which are left-justified and padded on the right with space characters. For example, a rule-array element which contains the number two will contain the character string “2 ”.
On output, the rule-array elements can have the values shown in the table below.
Chapter 2. CCA Node-Management and Access-Control 2-35
Figure 2-3 (Page 1 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element
Number
Output rule-array for option STATCCA
1 NMK Status State of the New Master-Key register:
2 CMK Status State of the Current Master-Key register:
3 OMK Status State of the Old Master-Key register:
4 CCA Application
5 CCA Application
6 User Role A character string containing the Role identifier
Name Description
One means the register is clearTwo means the register contains a partially
complete key
Three means the register contains a
complete key.
One means the register is clearTwo means the register contains a key.
One means the register is clearTwo means the register contains a key.
A character string that identifies the version of
Version
Build Date
the CCA application program that is running in the Coprocessor.
A character string containing the build date for the CCA application program that is running in the Coprocessor.
which defines the host application user's current authority.
2-36 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Query
Figure 2-3 (Page 2 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element Number
Output rule-array for option STATCCAE
1 Symmetric NMK
2 Symmetric CMK
3 Symmetric OMK
4 CCA Application
5 CCA Application
6 User Role A character string containing the Role identifier
7 Asymmetric NMK
8 Asymmetric CMK
9 Asymmetric OMK
Name Description
State of the Symmetric New Master-Key
Status
Status
Status
Version
Build Date
Status
Status
Status
register:
One means the register is clearTwo means the register contains a partially
complete key
Three means the register contains a
complete key.
State of the Symmetric Current Master-Key register:
One means the register is clearTwo means the register contains a key.
State of the Symmetric Old Master-Key register:
One means the register is clearTwo means the register contains a key.
A character string that identifies the version of the CCA application program that is running in the Coprocessor.
A character string containing the build date for the CCA application program that is running in the Coprocessor.
which defines the host application user's current authority.
State of the Asymmetric New Master-Key register:
One means the register is clearTwo means the register contains a partially
complete key
Three means the register contains a
complete key.
State of the Asymmetric Current Master-Key register:
One means the register is clearTwo means the register contains a key.
State of the Asymmetric Old Master-Key register:
One means the register is clearTwo means the register contains a key.
Chapter 2. CCA Node-Management and Access-Control 2-37
Figure 2-3 (Page 3 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element
Number
Output rule-array for option STATCARD
1 Number of Installed
2 DES Hardware
3 RSA Hardware
4 POST Version A character string identifying the version of the
5 Coprocessor
6 Coprocessor
7 Coprocessor Part
8 Coprocessor EC
9 Miniboot Version A character string identifying the version of the
10 CPU Speed A numeric character string containing the
11 Adapter ID
Name Description
The number of active Cryptographic
Adapters
Level
Level
Operating System Name
Operating System Version
Number
Level
Also see element number 15.
Coprocessors installed in the machine. Note that this only includes Coprocessors that have CCA software loaded (including those with CCA UDX software). Non-CCA Coprocessors are not included in this number.
A numeric character string containing an integer value identifying the version of DES hardware that is on the Coprocessor.
A numeric character string containing an integer value identifying the version of RSA hardware that is on the Coprocessor.
Coprocessor's Power-On Self Test (POST) firmware.
The first four characters define the POST0 version, and the last four characters define the POST1 version.
A character string identifying the operating system firmware on the Coprocessor.
A character string identifying the version of the Coprocessor's operating system firmware.
A character string containing the eight-character part number identifying the version of the Coprocessor.
A character string containing the eight-character EC (Engineering Change) level for this version of the Coprocessor.
Coprocessor's Miniboot firmware. This firmware controls the loading of programs into the Coprocessor.
The first four characters define the MiniBoot0 version, and the last four characters define the MiniBoot1 version.
operating speed of the microprocessor chip, in Megahertz.
A unique identifier manufactured into the Coprocessor. The Coprocessor's Adapter ID is an eight-byte binary value where the high-order byte is X'78' for an IBM 4758-001 and 4758-013, and is X'71' for an IBM 4758-002 and 4758-023. The remaining bytes are a random value.
2-38 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Query
Figure 2-3 (Page 4 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element Number
12 Flash Memory Size A numeric character string containing the size
13 DRAM Memory
14 Battery-Backed
15 Serial Number A character string containing the unique serial
Output rule-array for option STATDIAG
1 Battery State A numeric character string containing a value
2 Intrusion Latch
3 Error Log Status A numeric character string containing a value
4 Mesh Intrusion A numeric character string containing a value to
Name Description
of the flash EPROM memory on the Coprocessor, in 64-kilobyte increments.
A numeric character string containing the size
Size
Memory Size
State
of the dynamic RAM (DRAM) memory on the Coprocessor, in kilobytes.
A numeric character string containing the size of the battery-backed RAM on the Coprocessor, in kilobytes.
number of the Coprocessor. The serial number is factory installed and is also reported by the CLU utility in a Coprocessor-signed status message.
which indicates whether the battery on the Coprocessor needs to be replaced:
One means that the battery is goodTwo means that the battery should be
replaced.
A numeric character string containing a value which indicates whether the Intrusion Latch on the Coprocessor is set or cleared:
One means that the latch is clearedTwo means that the latch is set.
which indicates whether there is data in the Coprocessor CCA error log:
One means that the error log is emptyTwo means that the error log contains data,
but is not yet full
Three means that the error log is full, and
cannot hold any more abnormal termination data.
indicate whether the Coprocessor has detected tampering with the protective mesh that surrounds the secure module. This indicates a probable attempt to physically penetrate the module:
One means no intrusion had been detectedTwo means an intrusion attempt detected.
Chapter 2. CCA Node-Management and Access-Control 2-39
Figure 2-3 (Page 5 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element
Number
5 Low Voltage
6 High Voltage
7 Temperature
8 Radiation Detected A numeric character string containing a value to
9, 11,
13, 15,
17
10, 12, 14, 16,
18
Name Description
A numeric character string containing a value to
Detected
Detected
Range Exceeded
Last Five Commands Run
Last Five Return Codes
indicate whether a power supply voltage was below the minimum acceptable level. This may indicate an attempt to attack the security module:
One means only acceptable voltages have
been detected
Two means a voltage has been detected
below the low-voltage tamper threshold.
A numeric character string containing a value to indicate whether a power supply voltage was above the maximum acceptable level. This may indicate an attempt to attack the security module:
One means only acceptable voltages have
been detected
Two means a voltage has been detected
above the high-voltage tamper threshold.
A numeric character string containing a value to indicate whether the temperature in the secure module was outside of the acceptable limits. This may indicate an attempt to obtain information from the module:
One means the temperature is acceptableTwo means the temperature has been
detected outside of an acceptable limit.
indicate whether radiation was detected inside the secure module. This may indicate an attempt to obtain information from the module:
One means no radiation has been detectedTwo means radiation has been detected.
These five rule-array elements contain the last five commands that were executed by the Coprocessor CCA application. They are in chronological order, with the most recent command in element 9. Each element contains the security API command code in the first four characters, and the subcommand code in the last four characters.
These five rule-array elements contain the SAPI return codes and reason codes corresponding to the five commands in rule-array elements 9, 11, 13, 15, and 17. Each element contains the return code in the first four characters, and the reason code in the last four characters.
2-40 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Query
Figure 2-3 (Page 6 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element Number
Output rule-array for option STATEID (Environment Identifier)
1,2 EID The two elements when concatenated provide
Output rule-array for option STATEXPT
1 Base CCA
2 CDMF Availability A numeric character string containing a value to
3 56-bit DES
4 Triple-DES
5 SET Services
6 Maximum Modulus
Name Description
the 16-byte EID value.
A numeric character string containing a value to Services Availability
Availability
Availability
Availability
for Symmetric Key Encryption
indicate whether base CCA services are
available:
Zero means base CCA services are not
available
One means base CCA services are
available.
indicate whether CDMF encryption is available:
Zero means CDMF encryption is not
available
One means CDMF encryption is available.
A numeric character string containing a value to
indicate whether 56-bit DES encryption is
available:
Zero means 56-bit DES encryption is not
available
One means 56-bit DES encryption is
available.
A numeric character string containing a value to
indicate whether Triple-DES encryption is
available:
Zero means Triple-DES encryption is not
available
One means Triple-DES encryption is
available.
A numeric character string containing a value to
indicate whether SET (Secure Electronic
Transaction) services are available:
Zero means SET services are not availableOne means SET services are available.
A numeric character string containing the
maximum modulus size that is enabled for the
encryption of symmetric keys. This defines the
longest public-key modulus that can be used
for key management of symmetric-algorithm
keys.
Chapter 2. CCA Node-Management and Access-Control 2-41
Figure 2-3 (Page 7 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array
Element
Number
Output rule-array for option STATMOFN
Elements one and two, and elements three and four, are each treated as a 16-byte string with the high-order 15 bytes having meaningful information and the 16th byte containing a space character. Each byte provides status information about the 'i'th share, 1≤i≤15, of master-key information.
1, 2 Master-Key Shares
3, 4 Master-Key Shares
5 'm' The minimum number of shares required to
6 'n' The maximum number of distinct shares
Output rule-array for option TIMEDATE
1 Date The current date is returned as a character
2 Time The current GMT time of day is returned as a
3 Day of the Week The day of the week is returned as a number
Name Description
The 15 individual bytes are set to one of these
Generation
Reception
character values:
0 Cannot be generated 1 Can be generated 2 Has been generated but not
3 Generated and distributed once 4 Generated and distributed more
The 15 individual bytes are set to one of these character values:
0 Cannot be received 1 Can be received 3 Has been received 4 Has been received more than once.
instantiate a master key through the master-key-shares process. The value is returned in two characters, valued from 01 to 15, followed by six space characters.
involved in the master-key shares process. The value is returned in two characters, valued from 01 to 15, followed by six space characters.
string of the form YYYYMMDD, where YYYY represents the year, MM represents the month (01-12), and DD represents the day of the month (01-31).
character string of the form HHMMSS.
between 1 (Sunday) and 7 (Saturday).
distributed
than once.
verb_data_length
The verb_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the verb_data variable.
verb_data
The verb_data parameter is a pointer to a string variable containing data sent to the Coprocessor for this verb, or received from the Coprocessor as a result
2-42 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Facility_Query
of this verb. Its use depends on the options specified by the host application program.
The verb_data parameter is not currently used by this verb.
Required Commands
Cryptographic_Facility_Query is a universally authorized verb. There are no access-control restrictions on its use.
Chapter 2. CCA Node-Management and Access-Control 2-43
Cryptographic_Resource_Allocate (CSUACRA)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Cryptographic_Resource_Allocate verb is used to allocate a specific CCA Coprocessor for use by the thread or process, depending on the scope of the verb. For the OS/400, this verb is scoped to a process; for the other implementations, this verb is scoped to a thread. When a thread (or process, depending on the scope) allocates a cryptographic resource, requests will be routed to that resource. When a cryptographic resource is not allocated, requests will be routed to the default cryptographic resource.
You can set the default cryptographic resource. If you take no action, the default assignment is CRP01.
You cannot allocate a cryptographic resource while one is already allocated. Use the Cryptographic_Resource_Deallocate verb to deallocate a currently allocated cryptographic resource.
Be sure to review “Multi-Coprocessor Capability” on page 2-10 and “Master-Key Considerations with Multiple CCA Coprocessors” on page 2-17.
Restrictions
None
Format
Parameters
CSUACRA
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one rule_array Input String
array
resource_name_length Input Integer resource_name Input String resource_name_length bytes
rule_array_count * 8 bytes
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
2-44 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Resource_Allocate
Keyword Meaning
Cryptographic resource (required)
DEVICE Specifies an (IBM 4758) CCA Coprocessor.
resource_name_length
The resource_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the resource_name variable. The length must be within the range of 1 to 64.
resource_name
The resource_name parameter is a pointer to a string variable containing the name of the Coprocessor to be allocated.
Required Commands
None
Chapter 2. CCA Node-Management and Access-Control 2-45
Cryptographic_Resource_Deallocate (CSUACRD)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Cryptographic_Resource_Deallocate verb is used to deallocate a specific CCA Coprocessor that is currently allocated by the thread or process, depending on the scope of the verb. For the OS/400, this verb is scoped to a process; for the other implementations, this verb is scoped to a thread. When a thread (or process, depending on the scope) deallocates a cryptographic resource, requests will be routed to the default cryptographic resource.
You can set the default cryptographic resource. If you take no action, the default assignment is CRP01.
Be sure to review “Multi-Coprocessor Capability” on page 2-10 and “Master-Key Considerations with Multiple CCA Coprocessors” on page 2-17.
If a thread with an allocated Coprocessor terminates without first deallocating the Coprocessor, excess memory consumption will result. It is not necessary to deallocate a cryptographic resource if the process itself is terminating; it is only suggested if individual threads terminate while the process continues to run.
Restrictions
None
Format
Parameters
CSUACRD
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one rule_array Input String
array
resource_name_length Input Integer resource_name Input String resource_name_length bytes
rule_array_count * 8 bytes
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
2-46 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Cryptographic_Resource_Deallocate
Keyword Meaning
Cryptographic resource (required)
DEVICE Specifies an (IBM 4758) CCA Coprocessor.
resource_name_length
The resource_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the resource_name variable. The length must be within the range of 1 to 64.
resource_name
The resource_name parameter is a pointer to a string variable containing the name of the Coprocessor to be deallocated.
Required Commands
None
Chapter 2. CCA Node-Management and Access-Control 2-47
Key_Storage_Designate (CSUAKSD)
Platform/
Product
IBM 4758-2/23 X
OS/2 AIX Win NT/
2000
OS/400
The Key_Storage_Designate verb specifies the key-storage file used by the process.
You select the type of key storage, for DES keys or for public keys, using a rule-array keyword.
Restrictions
None
Format
CSUAKSD
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one rule_array Input String
key_storage_file_name_length Input Integer key_storage_file_name Input String key_storage_file_name_length
rule_array_count * 8 bytes
array
bytes
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
Keyword Meaning
Key-storage type (one required)
DES Indicates that the file name applies to the DES key-storage
specification.
PKA Indicates that the file name applies to the public-key
key-storage specification.
2-48 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Key_Storage_Designate
key_storage_file_name_length
The key_storage_file_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_storage_file_name variable. The length must be within the range of 1 to 64.
key_storage_file_name
The key_storage_file_name parameter is a pointer to a string variable containing the fully qualified file name of the key-storage file to be selected.
Required Commands
None
Chapter 2. CCA Node-Management and Access-Control 2-49
Key_Storage_Initialization (CSNBKSI)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Key_Storage_Initialization verb initializes a key-storage file using the current symmetric or asymmetric master-key. The initialized key storage will not contain any pre-existing key records. The name and path of the key storage data and index file are established differently in each operating environment. See the IBM 4758 PCI Cryptographic Coprocessor CCA Support Program Installation Manual for information on these files.
Restrictions
None
Format
CSNBKSI
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer two rule_array Input String
key_storage_file_name_length Input Integer key_storage_file_name Input String key_storage_file_name_length
key_storage_description_length Input Integer ≤64 key_storage_description Input String key_storage_description_length
clear_master_key Input String 24 bytes
rule_array_count * 8 bytes
array
bytes
bytes
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be two for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
Keyword Meaning
Master-key source (required)
CURRENT Specifies that the current symmetric master-key of the default
cryptographic facility is to be used for the initialization.
2-50 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Key_Storage_Initialization
Keyword Meaning
Key-storage selection (one required)
DES Initialize DES key-storage.
PKA Initialize PKA key-storage.
key_storage_file_name_length
The key_storage_file_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_storage_file_name variable. The length must be within the range of 1 to 64.
key_storage_file_name
The key_storage_file_name parameter is a pointer to a string variable containing the fully qualified file name of the key-storage file to be initialized. If the file does not exist, it is created. If the file does exist, it is overwritten and all existing keys are lost.
key_storage_description_length
The key_storage_description_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_storage_description variable.
key_storage_description
The key_storage_description parameter is a pointer to a string variable containing the description string that is stored in the key-storage file when it is initialized.
clear_master_key
The clear_master_key parameter is unused, but it must be declared and point to 24 data bytes in application storage.
Required Commands
Except in the OS/400 environment, the Key_Storage_Initialization verb requires the Compute Verification Pattern command (offset X'001D') to be enabled in the hardware. In the OS/400 environment, no commands are issued to the Coprocessor and therefore command authorization does not apply.
Chapter 2. CCA Node-Management and Access-Control 2-51
Logon_Control (CSUALCT)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
Use the Logon_Control verb to perform the following services:
Log on to the Coprocessor, using your access-control profile
Log off of the Coprocessor
Save or restore logon content information.
Select the service to perform by specifying the corresponding keyword in the input rule-array. Only one service is performed for each call to this verb.
If you log on to the adapter when you are already logged on, the existing logon session is replaced with a new session.
Restrictions
None
Format
CSUALCT
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length rule_array_count Input Integer one or two rule_array Input String
user_id Input String 8 bytes auth_parms_length Input Integer auth_parms Input String auth_parms_length bytes auth_data_length In/Output Integer auth_data Input String auth_data_length bytes
rule_array_count * 8 bytes
array
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
2-52 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Logon_Control
Keyword Meaning
Keywords used to log on
LOGON Tells the Coprocessor that you want to log on. When you use
the LOGON keyword, you must also use a second keyword, PPHRASE, to indicate how you will identify yourself to the Coprocessor.
PPHRASE Specifies that you are going to identify yourself using a
passphrase.
Keywords used to log off
LOGOFF Tells the Coprocessor you want to log off.
FORCE Tells the Coprocessor that a specified user is to be logged off.
The user's profile ID is specified by the user_id parameter.
Keywords used to save and restore logon context information
GET-CNTX Obtains a copy of the logon context information that is
currently active in your session. See “Use of Logon Context Information” on page 2-8.
PUT-CNTX Restores the logon context information that was saved using
the GET_CNTX keyword. See “Use of Logon Context Information” on page 2-8.
user_id
The user_id parameter is a pointer to a string variable containing the ID string which identifies the user to the system. The user ID must be exactly eight characters in length. Shorter user IDs should be padded on the right with space characters.
The user_id parameter is always used when logging on. It is also used when the LOGOFF keyword used in conjunction with the FORCE keyword to force a user off.
auth_parms_length
The auth_parms_length parameter is a pointer to an integer variable containing the number of bytes of data in the auth_parms variable.
On input, this variable contains the length (in bytes) of the auth_parms variable. On output, this variable contains the number of bytes of data returned in the auth_parms variable.
auth_parms
The auth_parms parameter is a pointer to a string variable containing data used in the authentication process.
This field is used differently depending on the authentication method specified in the rule array.
Keyword Contents of auth_parms field
PPHRASE The authentication parameter field is empty. Its length is zero.
auth_data_length
The auth_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the auth_data variable.
Chapter 2. CCA Node-Management and Access-Control 2-53
On input, this field contains the length (in bytes) of the auth_data variable. When no usage is defined for the auth_data parameter, set the length variable to zero.
On output, this field contains the number of bytes of data returned in the auth_data variable.
auth_data
The auth_data parameter is a pointer to a string variable containing data used in the authentication process.
This field is used differently depending on the keywords specified in the rule array.
Rule-Array Keyword
PPHRASE and LOGON
GET-CNTX The authentication data field receives the active logon context
PUT-CNTX The authentication data field contains your active logon
Required Commands
The Logon_Control verb requires the Force User Logoff of a Specified User command (offset X'011B') to be enabled in the hardware for use with the FORCE keyword.
Contents of auth_data field
The authentication data field contains the user-provided passphrase.
information. The size of the buffer provided for the auth_data field must be at least 256 bytes.
context.
2-54 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Master_Key_Distribution
Master_Key_Distribution (CSUAMKD)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Master_Key_Distribution verb is used to perform these operations related to the distribution of shares of the master key:
Generate and distribute a share of the current master-keyReceive a master-key share. When sufficient shares are received, reconstruct
the master key in the new master-key register.
You choose which class of master key, either symmetric or asymmetric, to clone with the SYM-MK and the ASYM-MK rule-array keywords. If neither keyword is specified, the verb performs the same operation on both classes of registers, provided that the registers already contain the same values.
OBTAIN and INSTALL rule-array keywords control the operation of the verb.
With the OBTAIN keyword...
You specify:
– The share number, i, where 1 ≤ i ≤ 15 and i ≤ the maximum number of
shares to be distributed as defined by the SET-MOFN option in the Cryptographic_Facility_Control verb
– The private_key_name of the Coprocessor-retained key used to sign a
generated master-key share. This key must have the CLONE attribute set at the time of key generation.
– The certifying_key_name of the public key already registered in the
Coprocessor used to validate the following certificate
– The certificate and its length that provides the public key used to encrypt
the clone_information_encrypting_key
– The length and location of the clone_information field that will receive the
encrypted cloning information (master-key share).
The verb performs:
– Generation of master-key shares, as required, and formatting of the
information to be cloned – Signing of the cloning_information – Generation of an encryption key and encryption of the cloning information – Recovery and validation of the public key used to encrypt the
clone_info_encrypting_key – Encryption of the clone_info_encrypting_key.
The verb returns:
– The encrypted cloning information – The encrypted clone_info_encrypting_key.
With the INSTALL keyword...
You specify:
– The share number, i, presented in this request
Chapter 2. CCA Node-Management and Access-Control 2-55
– The private_key_name of the Coprocessor-retained key used to decrypt the
clone_info_encrypting_key. This key must have the CLONE attribute set at the time of key generation.
– The certifying_key_name of the public key already registered in the
Coprocessor used to validate the following certificate
– The certificate and its length that provides the public key used to validate
the signature on the cloning information
– The length and location of the clone_info field that provides the encrypted
cloning information (master-key share).
The verb performs:
– Recovery of the clone_info_encrypting_key – Decryption of the cloning information – Recovery and validation of the public key used to validate the cloning
information signature
– Validation of the cloning information signature – Retention of a master-key share – Regeneration of a master key in the new master-key register when
sufficient shares have been received.
The verb returns:
Restrictions
Format
– A return code valued to four if the master key has been recovered into the
new master-key register. A return code of zero indicates that processing was normal, but a master key was not recovered into the new master-key register. (Other return codes, and various reason codes, can also occur in abnormal cases.)
When using the OBTAIN keyword, the current master-key register must be full.
When using the INSTALL keyword, the new master-key register must be clear (empty).
CSUAMKD
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one or two rule_array Input String
array
share_index Input Integer private_key_name Input String 64 bytes certifying_key_name Input String 64 bytes certificate_length Input Integer certificate Input String certificate_length bytes clone_info_encrypting_key_length In/Output Integer clone_info_encrypting_key In/Output String clone_info_encrypting_key_length
clone_info_length In/Output Integer clone_info In/Output String clone_info_length bytes
rule_array_count * 8 bytes
bytes
2-56 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Master_Key_Distribution
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
Keyword Meaning
Operation (one required)
OBTAIN Generate and output a master-key share and other cloning
information.
INSTALL Receive a master-key share and other cloning information.
Master-key choice (one, optional)
SYM-MK Operate with the symmetric master-key registers.
ASYM-MK Operate with the asymmetric master-key registers.
share_index
The share_index parameter is a pointer to an integer variable containing the index number of the share to be generated or received by the Coprocessor.
private_key_name
The private_key_name parameter is a pointer to a string variable containing the name of the Coprocessor-retained private key used to sign the cloning information (OBTAIN mode), or recover the cloning-information encrypting key (INSTALL mode).
certifying_key_name
The certifying_key_name parameter is a pointer to a string variable containing the name of the Coprocessor-retained public key used to verify the offered certificate.
certificate_length
The certificate_length parameter is a pointer to an integer variable containing the number of bytes of data in the certificate variable.
certificate
The certificate parameter is a pointer to a string variable containing the public-key certificate that can be validated using the public key identified with the certifying_key_name variable.
clone_info_encrypting_key_length
The clone_info_encrypting_key_length parameter is a pointer to an integer variable containing the number of bytes of data in the clone_info_encrypting_key variable.
Chapter 2. CCA Node-Management and Access-Control 2-57
clone_info_encrypting_key
The clone_info_encrypting_key parameter is a pointer to a string variable containing the encrypted key used to recover the cloning information.
clone_info_length
The clone_info_length parameter is a pointer to an integer variable containing the number of bytes of data in the clone_info variable.
clone_info
The clone_info parameter is a pointer to a string variable containing the encrypted cloning information (master-key share).
Required Commands
The Master_Key_Distribution verb requires the following commands to be enabled based on the requested share-number, 1≤i≤15, and the use of either the OBTAIN or the INSTALL rule-array keyword:
 Clone-info Obtain command (offset X'0210'+share_index, for example, for
share 10, X'021A')
 Clone-info Install command (offset X'0220'+share_index, for example, for
share 12, X'022C').
2-58 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Master_Key_Process
Master_Key_Process (CSNBMKP)
Platform/
Product
IBM 4758-2/23 X X X X
OS/2 AIX Win NT/
2000
OS/400
The Master_Key_Process verb operates on the three master-key registers: new, current, and old. Use the verb to:
Clear the new and clear the old master-key registers
Generate a random master-key value in the new master-key register
Exclusive-OR a clear value as a key part into the new master-key register
Set the master key which transfers the current master-key to the old master-key
register, the new master-key to the current master-key register, and clear the new master-key register. SET also clears the master-key-shares tables.
For IBM 4758 Cryptographic Coprocessor implementations, the master key is a triple-length, 168-bit, 24-byte value.
You choose processing of the symmetric or asymmetric registers by specifying one of the SYM-MK and the ASYM-MK rule-array keywords. If neither keyword is specified, the verb performs the same operation on both classes of registers, provided that the registers already contain the same values.
Before starting to load new master-key information, ensure that the new master-key register is cleared. Do this by using the CLEAR keyword in the rule array.
To form a master key from key parts in the new master-key register, use the verb several times to complete the following tasks:
Clear the register, if it is not already clearLoad the first key partLoad any middle key-parts, calling the verb once for each middle key_partLoad the last key_part.
You can remove a prior master-key from the Coprocessor with the CLR-OLD keyword. The contents of the old master-key register are removed and subsequently only current-master-key encrypted keys will be usable. If there is a value in the old master-key register, this master key can also be used to decrypt an enciphered working key.
For symmetric master-keys, the low-order bit in each byte of the key is used as parity for the remaining bits in the byte. Each byte of the key part should contain an odd number of one bits. If this is not the case, a warning is issued. The product maintains odd parity on the accumulated symmetric master-key value.
When the LAST master-key part is entered, this additional processing is performed:
If any two of the eight-byte parts of the new master-key have the same value, a
warning is issued. This warning should not be ignored and a key with this property should generally not be used.
Chapter 2. CCA Node-Management and Access-Control 2-59
Restrictions
Format
The master-key verification pattern (MKVP) of the new master-key is compared
against the MKVP of the current and the old master-keys. If they are the same, the service fails with return code 8, reason code 704.
If any of the eight-byte parts of the new master-key compares equal to one of
the weak DES-keys, the service fails with return code 8, reason code 703. See page 2-62 for a list of these “weak” keys. (A parity-adjusted version of the asymmetric master-key is used to look for weak keys.)
Except in the OS/400 environment, as part of the SET process, if a DES and/or PKA key-storage exists, the header record of each key storage is updated with the verification pattern of the (new) current master-key. The OS/400 environment does not have master-key verification records in the key-storage data set.
None
CSNBMKP
return_code Output Integer reason_code Output Integer exit_data_length In/Output Integer exit_data In/Output String exit_data_length bytes rule_array_count Input Integer one, two, or three rule_array Input String
array
key_part Input String 24 bytes
rule_array_count * 8 bytes
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one, two, or three for this verb.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below:
Keyword Meaning
Cryptographic component (optional)
ADAPTER Specifies the Coprocessor. This is the default for IBM 4758
implementations.
Master-key choice (one, optional)
SYM-MK Operate with the symmetric master-key registers.
ASYM-MK Operate with the asymmetric master-key registers.
2-60 IBM 4758 CCA Basic Services, Release 2.54, February 2005
CCA Release 2.54 Master_Key_Process
Keyword Meaning
Master-key process (one required)
CLEAR Specifies to clear the new master-key register.
CLR-OLD Specifies to clear the old master-key register and set the
status for this register to empty.
You can use the CLR-OLD keyword to cause the old master-key register to be cleared. The status response in the Cryptographic_Facility_Query verb, STATCCA, shows the condition of this register.
FIRST Specifies to load the first key_part.
MIDDLE Specifies to XOR the second, third, or other intermediate
key_part into the new master-key register.
LAST Specifies to XOR the last key_part into the new master-key
register.
RANDOM Causes generation of a random master-key value in the new
master-key register.
SET Specifies to advance the current master-key to the old
master-key register, to advance the new master-key to the current master-key register, and to clear the new-master-key register.
key_part
The key_part parameter is a pointer to a string variable containing a 168-bit (3x56-bit, 24-byte) clear key-part that is used when you specify one of the keywords FIRST, MIDDLE, or LAST
If you use the CLEAR, RANDOM, or SET keywords, the information in the variable is ignored, but you must declare the variable.
Required Commands
The Master_Key_Process verb requires the following commands to be enabled in the hardware:
To process the symmetric master-keys, and also the asymmetric master-keys
when neither master-key set is specified:
– Clear New Master Key Register command (offset X'0032') with the
– Clear Old Master Key Register command (offset X'0033') with the
– Load First Master Key Part command (offset X'0018') with the FIRST
– Combine Master Key Parts command (offset X'0019') with the MIDDLE or
– Generate Random Master Key command (offset X'0020') with the
– Set Master Key command (offset X'001A') with the SET keyword.
CLEAR keyword
CLR-OLD keyword
keyword
LAST keyword
RANDOM keyword
To process the asymmetric master-keys:
– Clear New PKA Master Key Register command (offset X'0060') with the
CLEAR keyword
Chapter 2. CCA Node-Management and Access-Control 2-61
Related Information
The following are considered questionable DES keys:
– Clear Old PKA Master Key Register command (offset X'0061') with the
CLR-OLD keyword
– Load First PKA Master Key Part command (offset X'0053') with the FIRST
keyword
– Combine PKA Master Key Parts command (offset X'0054') with the
MIDDLE or LAST keywords
– Generate Random PKA Master Key command (offset X'0120') with the
RANDOM keyword
– Set PKA Master Key command (offset X'0057') with the SET keyword.
1 1 1 1 1 1 1 1 / weak / FE FE FE FE FE FE FE FE / weak / 1F 1F 1F 1F E E E E / weak / E E E E F1 F1 F1 F1 / weak / 1 FE 1 FE 1 FE 1 FE / semi-weak / FE 1 FE 1 FE 1 FE 1 / semi-weak / 1F E 1F E E F1 E F1 / semi-weak / E 1F E 1F F1 E F1 E / semi-weak / 1 E 1 E 1 F1 1 F1 / semi-weak / E 1 E 1 F1 1 F1 1 / semi-weak / 1F FE 1F FE E FE E FE / semi-weak / FE 1F FE 1F FE E FE E / semi-weak / 1 1F 1 1F 1 E 1 E / semi-weak / 1F 1 1F 1 E 1 E 1 / semi-weak / E FE E FE F1 FE F1 FE / semi-weak / FE E FE E FE F1 FE F1 / semi-weak / 1F 1F 1 1 E E 1 1 / possibly semi-weak / 1 1F 1F 1 1 E E 1 / possibly semi-weak / 1F 1 1 1F E 1 1 E / possibly semi-weak / 1 1 1F 1F 1 1 E E / possibly semi-weak / E E 1 1 F1 F1 1 1 / possibly semi-weak / FE FE 1 1 FE FE 1 1 / possibly semi-weak / FE E 1F 1 FE F1 E 1 / possibly semi-weak / E FE 1F 1 F1 FE E 1 / possibly semi-weak / FE E 1 1F FE F1 1 E / possibly semi-weak / E FE 1 1F F1 FE 1 E / possibly semi-weak / E E 1F 1F F1 F1 E E / possibly semi-weak / FE FE 1F 1F FE FE E E / possibly semi-weak / FE 1F E 1 FE E F1 1 / possibly semi-weak / E 1F FE 1 F1 E FE 1 / possibly semi-weak / FE 1 E 1F FE 1 F1 E / possibly semi-weak / E 1 FE 1F F1 1 FE E / possibly semi-weak / 1 E E 1 1 F1 F1 1 / possibly semi-weak / 1F FE E 1 E FE F1 1 / possibly semi-weak / 1F E FE 1 E F1 FE 1 / possibly semi-weak / 1 FE FE 1 1 FE FE 1 / possibly semi-weak / 1F E E 1F E F1 F1 E / possibly semi-weak / 1 FE E 1F 1 FE F1 E / possibly semi-weak / 1 E FE 1F 1 F1 FE E / possibly semi-weak / 1F FE FE 1F E FE FE E / possibly semi-weak / E 1 1 E F1 1 1 F1 / possibly semi-weak / FE 1F 1 E FE E 1 F1 / possibly semi-weak / FE 1 1F E FE 1 E F1 / possibly semi-weak / E 1F 1F E F1 E E F1 / possibly semi-weak /
2-62 IBM 4758 CCA Basic Services, Release 2.54, February 2005
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use