with ibm corp....ensuring data integrity . 473 data confidentiality and data integrity verbs . 475...

CCA Basic Services Reference and Guidefor the IBM 4767 and IBM 4765 PCIeCryptographic CoprocessorsReleases 5.3, 5.2, 4.4, and 4.2

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 1069. The IBM LicenseAgreement for Machine Code is included in this guide. Carefully read the agreement. By using this product, you agree toabide by the terms of this agreement and applicable copyright laws.

Thirty-third edition (November 2016)

This edition describes the IBM Common Cryptographic Architecture (CCA) Basic Services API for Releases 5.3, 5.2,4.4, and 4.2.

© Copyright IBM Corporation 2007, 2016.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

|

||

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiSummary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Thirty-third edition, November 2016, Releases 5.3, 5.2, 4.4, and 4.2 . . . . . . . . . . . . . . . xviiiThirty-second edition, November 2016, Releases 5.3, 5.2, 4.4, and 4.2 . . . . . . . . . . . . . . . xixThirty-first edition, August 2016, Releases 5.3, 5.2, 4.4, and 4.2 . . . . . . . . . . . . . . . . . xixThirtieth edition, April 2016, Releases 5.2, 4.4, and 4.2 . . . . . . . . . . . . . . . . . . . . xxTwenty-ninth edition, October 2015, Releases 4.4, 4.2, 3.30, and 3.25 . . . . . . . . . . . . . . . xxiiTwenty-eighth edition, August 2015, Releases 4.4, 4.3, 4.2, 4.1, 3.30, and 3.25 . . . . . . . . . . . . xxiiiTwenty-seventh edition, May 2014, Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25 . . . . . . . xxivTwenty-sixth edition, April 2014, Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25 . . . . . . . . xxivTwenty-fifth edition, November 2013, Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25 . . . . . . . xxivTwenty-fourth edition, September 2011, CCA Support Program, Releases 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and3.25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii

How this document is organized . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii

Documentation for optional smart cards . . . . . . . . . . . . . . . . . . . . . . . . xxxiiCryptography publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii

Chapter 1. Introduction to programming for the IBM Common CryptographicArchitecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Available Common Cryptographic Architecture verbs. . . . . . . . . . . . . . . . . . . . . . 1Common Cryptographic Architecture functional overview . . . . . . . . . . . . . . . . . . . . 2

How application programs obtain service. . . . . . . . . . . . . . . . . . . . . . . . . 5Overlapped processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Security API programming fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . 7Verbs, variables, and parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Commonly encountered parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 10

API verb organization in the remainder of this document . . . . . . . . . . . . . . . . . . . . 12

Chapter 2. CCA node management and access control . . . . . . . . . . . . . . . 15Using CCA access-control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Understanding access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Role-based access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Initializing and managing the access-control system . . . . . . . . . . . . . . . . . . . . . 19Logging on and logging off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Changing your user profile passphrase . . . . . . . . . . . . . . . . . . . . . . . . . 22Protecting your transaction information . . . . . . . . . . . . . . . . . . . . . . . . . 22

Controlling the cryptographic facility . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Multi-coprocessor capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

IBM i multi-coprocessor support . . . . . . . . . . . . . . . . . . . . . . . . . . . 28AIX, Linux, and Windows multi-coprocessor support . . . . . . . . . . . . . . . . . . . . 29

Understanding and managing master keys . . . . . . . . . . . . . . . . . . . . . . . . . 29Symmetric and asymmetric master keys . . . . . . . . . . . . . . . . . . . . . . . . . 31Establishing master keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Master-key considerations with multiple CCA coprocessors . . . . . . . . . . . . . . . . . . 35

Initializing cryptographic key-storage. . . . . . . . . . . . . . . . . . . . . . . . . . . 37Testing the random-number generator and known-answer tests . . . . . . . . . . . . . . . . . . 37Using the CCA node, access control, and master-key management verbs . . . . . . . . . . . . . . . 37

Access_Control_Initialization (CSUAACI) . . . . . . . . . . . . . . . . . . . . . . . . 38Access_Control_Maintenance (CSUAACM) . . . . . . . . . . . . . . . . . . . . . . . . 41

© Copyright IBM Corp. 2007, 2016 iii

||||

Access_Control_Tracking (CSUAACT) . . . . . . . . . . . . . . . . . . . . . . . . . 46Cryptographic_Facility_Control (CSUACFC) . . . . . . . . . . . . . . . . . . . . . . . 53Cryptographic_Facility_Query (CSUACFQ) . . . . . . . . . . . . . . . . . . . . . . . . 61Cryptographic_Facility_Version (CSUACFV) . . . . . . . . . . . . . . . . . . . . . . . 72Cryptographic_Resource_Allocate (CSUACRA) . . . . . . . . . . . . . . . . . . . . . . 74Cryptographic_Resource_Deallocate (CSUACRD) . . . . . . . . . . . . . . . . . . . . . . 76Key_Storage_Designate (CSUAKSD) . . . . . . . . . . . . . . . . . . . . . . . . . . 78Key_Storage_Initialization (CSNBKSI) . . . . . . . . . . . . . . . . . . . . . . . . . 80Logon_Control (CSUALCT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Log_Query (CSUALGQ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Master_Key_Distribution (CSUAMKD) . . . . . . . . . . . . . . . . . . . . . . . . . 92Master_Key_Process (CSNBMKP) . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Random_Number_Tests (CSUARNT) . . . . . . . . . . . . . . . . . . . . . . . . . 101

Chapter 3. PKA key-management . . . . . . . . . . . . . . . . . . . . . . . . 103PKA key-management services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Key generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Key import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Reenciphering a private key or its OPK under an updated master key . . . . . . . . . . . . . . 107Using the PKA keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Using the PKA private key at multiple nodes. . . . . . . . . . . . . . . . . . . . . . . 108Extracting a PKA public key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Registering and retaining an RSA public-key . . . . . . . . . . . . . . . . . . . . . . . 108Controlling the wrapping of an asymmetric key with a weaker key . . . . . . . . . . . . . . . 108

Using verbs to perform cryptographic functions and obtain key-token data structures . . . . . . . . . . 109PKA_Key_Generate (CSNDPKG) . . . . . . . . . . . . . . . . . . . . . . . . . . . 110PKA_Key_Import (CSNDPKI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117PKA_Key_Token_Build (CSNDPKB) . . . . . . . . . . . . . . . . . . . . . . . . . . 121PKA_Key_Token_Change (CSNDKTC) . . . . . . . . . . . . . . . . . . . . . . . . . 133PKA_Key_Translate (CSNDPKT) . . . . . . . . . . . . . . . . . . . . . . . . . . . 136PKA_Public_Key_Extract (CSNDPKX) . . . . . . . . . . . . . . . . . . . . . . . . . 143PKA_Public_Key_Hash_Register (CSNDPKH) . . . . . . . . . . . . . . . . . . . . . . 145PKA_Public_Key_Register (CSNDPKR) . . . . . . . . . . . . . . . . . . . . . . . . . 147

Chapter 4. Hashing and digital signatures . . . . . . . . . . . . . . . . . . . . 149Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Digital signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Verbs used in hashing and digital signature services . . . . . . . . . . . . . . . . . . . . . 152

Digital_Signature_Generate (CSNDDSG) . . . . . . . . . . . . . . . . . . . . . . . . 152Digital_Signature_Verify (CSNDDSV) . . . . . . . . . . . . . . . . . . . . . . . . . 157MDC_Generate (CSNBMDG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163One_Way_Hash (CSNBOWH) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Chapter 5. AES, DES, and HMAC symmetric-key management . . . . . . . . . . . 171AES, DES, and HMAC key-management . . . . . . . . . . . . . . . . . . . . . . . . . 175

Triple-DES key wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Export DES key under AES transport key . . . . . . . . . . . . . . . . . . . . . . . . 183Controlling the wrapping of a symmetric key with a weaker key . . . . . . . . . . . . . . . . 183

Control vectors, key types, key-usage, and key-management restrictions. . . . . . . . . . . . . . . 184Checking a DES control vector before processing a cryptographic command . . . . . . . . . . . . 184AES, DES, and HMAC key types . . . . . . . . . . . . . . . . . . . . . . . . . . . 185AES and HMAC key usage and key management restrictions . . . . . . . . . . . . . . . . . 189DES key usage restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Key tokens, key labels, and key identifiers. . . . . . . . . . . . . . . . . . . . . . . . . 227AES, DES, and variable-length symmetric key tokens . . . . . . . . . . . . . . . . . . . . 227Key labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Key identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Key-processing and key-storage verbs for symmetric keys . . . . . . . . . . . . . . . . . . . 233Installing and verifying symmetric keys . . . . . . . . . . . . . . . . . . . . . . . . 235Generating symmetric keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

iv CCA Basic Services November, 2016

Exporting and importing DES keys, symmetric techniques . . . . . . . . . . . . . . . . . . 238Exporting and importing symmetric keys, asymmetric techniques . . . . . . . . . . . . . . . . 239Diversifying symmetric keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Storing keys in key-storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Improved remote key distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Remote key-loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Trusted block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Changes to the CCA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245The RKX key-token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246Using trusted blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Remote key distribution scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 252Remote key distribution benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Security precautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260AES, DES, and HMAC key-management verbs . . . . . . . . . . . . . . . . . . . . . . . 260

Clear_Key_Import (CSNBCKI). . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Control_Vector_Generate (CSNBCVG) . . . . . . . . . . . . . . . . . . . . . . . . . 263Control_Vector_Translate (CSNBCVT) . . . . . . . . . . . . . . . . . . . . . . . . . 266Cryptographic_Variable_Encipher (CSNBCVE) . . . . . . . . . . . . . . . . . . . . . . 269Data_Key_Export (CSNBDKX). . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Data_Key_Import (CSNBDKM) . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Diversified_Key_Generate (CSNBDKG) . . . . . . . . . . . . . . . . . . . . . . . . . 276Diversified_Key_Generate2 (CSNBDKG2) . . . . . . . . . . . . . . . . . . . . . . . . 284EC_Diffie-Hellman (CSNDEDH) . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Key_Encryption_Translate (CSNBKET) . . . . . . . . . . . . . . . . . . . . . . . . . 300Key_Export (CSNBKEX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Key_Generate (CSNBKGN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Key_Generate2 (CSNBKGN2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Key_Import (CSNBKIM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Key_Part_Import (CSNBKPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Key_Part_Import2 (CSNBKPI2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Key_Test (CSNBKYT). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Key_Test2 (CSNBKYT2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Key_Test_Extended (CSNBKYTX). . . . . . . . . . . . . . . . . . . . . . . . . . . 351Key_Token_Build (CSNBKTB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Key_Token_Build2 (CSNBKTB2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Key_Token_Change (CSNBKTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Key_Token_Change2 (CSNBKTC2) . . . . . . . . . . . . . . . . . . . . . . . . . . 370Key_Token_Parse (CSNBKTP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372Key_Token_Parse2 (CSNBKTP2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Key_Translate (CSNBKTR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383Key_Translate2 (CSNBKTR2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Multiple_Clear_Key_Import (CSNBCKM) . . . . . . . . . . . . . . . . . . . . . . . . 392PKA_Decrypt (CSNDPKD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396PKA_Encrypt (CSNDPKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Prohibit_Export (CSNBPEX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Prohibit_Export_Extended (CSNBPEXX) . . . . . . . . . . . . . . . . . . . . . . . . 404Random_Number_Generate (CSNBRNG) . . . . . . . . . . . . . . . . . . . . . . . . 406Random_Number_Generate_Long (CSNBRNGL) . . . . . . . . . . . . . . . . . . . . . 408Remote_Key_Export (CSNDRKX). . . . . . . . . . . . . . . . . . . . . . . . . . . 410Restrict_Key_Attribute (CSNBRKA) . . . . . . . . . . . . . . . . . . . . . . . . . . 423Symmetric_Key_Export (CSNDSYX) . . . . . . . . . . . . . . . . . . . . . . . . . . 428Symmetric_Key_Export_with_Data (CSNDSXD) . . . . . . . . . . . . . . . . . . . . . . 436Symmetric_Key_Generate (CSNDSYG) . . . . . . . . . . . . . . . . . . . . . . . . . 440Symmetric_Key_Import (CSNDSYI) . . . . . . . . . . . . . . . . . . . . . . . . . . 446Symmetric_Key_Import2 (CSNDSYI2) . . . . . . . . . . . . . . . . . . . . . . . . . 452Trusted_Block_Create (CSNDTBC) . . . . . . . . . . . . . . . . . . . . . . . . . . 459Unique_Key_Derive (CSNBUKD). . . . . . . . . . . . . . . . . . . . . . . . . . . 463

Chapter 6. Data confidentiality and data integrity . . . . . . . . . . . . . . . . . 471Encryption and message authentication codes . . . . . . . . . . . . . . . . . . . . . . . 472

Ensuring data confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

Contents v

Ensuring data integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473Data confidentiality and data integrity verbs . . . . . . . . . . . . . . . . . . . . . . . . 475

Cipher_Text_Translate2 (CSNBCTT2) . . . . . . . . . . . . . . . . . . . . . . . . . 475Decipher (CSNBDEC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481Encipher (CSNBENC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484HMAC_Generate (CSNBHMG) . . . . . . . . . . . . . . . . . . . . . . . . . . . 487HMAC_Verify (CSNBHMV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490MAC_Generate (CSNBMGN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493MAC_Generate2 (CSNBMGN2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 496MAC_Verify (CSNBMVR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500MAC_Verify2 (CSNBMVR2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503Symmetric_Algorithm_Decipher (CSNBSAD) . . . . . . . . . . . . . . . . . . . . . . . 507Symmetric_Algorithm_Encipher (CSNBSAE) . . . . . . . . . . . . . . . . . . . . . . . 513

Chapter 7. Key-storage mechanisms . . . . . . . . . . . . . . . . . . . . . . 519Key labels and key-storage management . . . . . . . . . . . . . . . . . . . . . . . . . 520

Key-label content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521Key-storage verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

AES_Key_Record_Create (CSNBAKRC). . . . . . . . . . . . . . . . . . . . . . . . . 523AES_Key_Record_Delete (CSNBAKRD). . . . . . . . . . . . . . . . . . . . . . . . . 525AES_Key_Record_List (CSNBAKRL). . . . . . . . . . . . . . . . . . . . . . . . . . 527AES_Key_Record_Read (CSNBAKRR) . . . . . . . . . . . . . . . . . . . . . . . . . 529AES_Key_Record_Write (CSNBAKRW) . . . . . . . . . . . . . . . . . . . . . . . . . 531DES_Key_Record_Create (CSNBKRC) . . . . . . . . . . . . . . . . . . . . . . . . . 533DES_Key_Record_Delete (CSNBKRD) . . . . . . . . . . . . . . . . . . . . . . . . . 535DES_Key_Record_List (CSNBKRL) . . . . . . . . . . . . . . . . . . . . . . . . . . 537DES_Key_Record_Read (CSNBKRR) . . . . . . . . . . . . . . . . . . . . . . . . . . 539DES_Key_Record_Write (CSNBKRW) . . . . . . . . . . . . . . . . . . . . . . . . . 541PKA_Key_Record_Create (CSNDKRC) . . . . . . . . . . . . . . . . . . . . . . . . . 543PKA_Key_Record_Delete (CSNDKRD) . . . . . . . . . . . . . . . . . . . . . . . . . 545PKA_Key_Record_List (CSNDKRL) . . . . . . . . . . . . . . . . . . . . . . . . . . 547PKA_Key_Record_Read (CSNDKRR) . . . . . . . . . . . . . . . . . . . . . . . . . 549PKA_Key_Record_Write (CSNDKRW) . . . . . . . . . . . . . . . . . . . . . . . . . 551Retained_Key_Delete (CSNDRKD) . . . . . . . . . . . . . . . . . . . . . . . . . . 553Retained_Key_List (CSNDRKL) . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

Chapter 8. Financial services support . . . . . . . . . . . . . . . . . . . . . . 557Processing financial PINs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

PIN-verb summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561PIN-calculation method and PIN-block format summary . . . . . . . . . . . . . . . . . . . 561Providing security for PINs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562Supporting multiple PIN calculation methods . . . . . . . . . . . . . . . . . . . . . . 563Supporting multiple PIN-block formats and PIN-extraction methods . . . . . . . . . . . . . . . 565

Generating and verifying card security codes . . . . . . . . . . . . . . . . . . . . . . . . 568Working with EMV smart cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569Visa Data Secure Platform with Point-to-Point Encryption . . . . . . . . . . . . . . . . . . . 569Financial services support verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

Authentication_Parameter_Generate (CSNBAPG) . . . . . . . . . . . . . . . . . . . . . 572Clear_PIN_Encrypt (CSNBCPE) . . . . . . . . . . . . . . . . . . . . . . . . . . . 575Clear_PIN_Generate (CSNBPGN). . . . . . . . . . . . . . . . . . . . . . . . . . . 578Clear_PIN_Generate_Alternate (CSNBCPA) . . . . . . . . . . . . . . . . . . . . . . . 581CVV_Generate (CSNBCSG). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586CVV_Key_Combine (CSNBCKC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 589CVV_Verify (CSNBCSV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594Encrypted_PIN_Generate (CSNBEPG) . . . . . . . . . . . . . . . . . . . . . . . . . 597Encrypted_PIN_Translate (CSNBPTR) . . . . . . . . . . . . . . . . . . . . . . . . . 601Encrypted_PIN_Translate_Enhanced (CSNBPTRE) . . . . . . . . . . . . . . . . . . . . . 607Encrypted_PIN_Verify (CSNBPVR) . . . . . . . . . . . . . . . . . . . . . . . . . . 616FPE_Decipher (CSNBFPED) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622FPE_Encipher (CSNBFPEE). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629

vi CCA Basic Services November, 2016

FPE_Translate (CSNBFPET). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636PIN_Change/Unblock (CSNBPCU) . . . . . . . . . . . . . . . . . . . . . . . . . . 643Recover_PIN_from_Offset (CSNBPFO) . . . . . . . . . . . . . . . . . . . . . . . . . 650Secure_Messaging_for_Keys (CSNBSKY) . . . . . . . . . . . . . . . . . . . . . . . . 654Secure_Messaging_for_PINs (CSNBSPN) . . . . . . . . . . . . . . . . . . . . . . . . 657SET_Block_Compose (CSNDSBC). . . . . . . . . . . . . . . . . . . . . . . . . . . 662SET_Block_Decompose (CSNDSBD) . . . . . . . . . . . . . . . . . . . . . . . . . . 665Transaction_Validation (CSNBTRV) . . . . . . . . . . . . . . . . . . . . . . . . . . 669

Chapter 9. Financial services support for DK. . . . . . . . . . . . . . . . . . . 673Financial services support for DK verbs . . . . . . . . . . . . . . . . . . . . . . . . . 674

DK_Deterministic_PIN_Generate (CSNBDDPG) . . . . . . . . . . . . . . . . . . . . . . 675DK_Migrate_PIN (CSNBDMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . 681DK_PAN_Modify_in_Transaction (CSNBDPMT) . . . . . . . . . . . . . . . . . . . . . . 686DK_PAN_Translate (CSNBDPT) . . . . . . . . . . . . . . . . . . . . . . . . . . . 691DK_PIN_Change (CSNBDPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696DK_PIN_Verify (CSNBDPV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705DK_PRW_Card_Number_Update (CSNBDPNU) . . . . . . . . . . . . . . . . . . . . . . 708DK_PRW_CMAC_Generate (CSNBDPCG) . . . . . . . . . . . . . . . . . . . . . . . . 713DK_Random_PIN_Generate (CSNBDRPG). . . . . . . . . . . . . . . . . . . . . . . . 716DK_Regenerate_PRW (CSNBDRP) . . . . . . . . . . . . . . . . . . . . . . . . . . 721

Chapter 10. TR-31 symmetric-key management . . . . . . . . . . . . . . . . . . 727TR-31 symmetric key management verbs . . . . . . . . . . . . . . . . . . . . . . . . . 728

Key_Export_to_TR31 (CSNBT31X) . . . . . . . . . . . . . . . . . . . . . . . . . . 729TR31_Key_Import (CSNBT31I) . . . . . . . . . . . . . . . . . . . . . . . . . . . 754TR31_Key_Token_Parse (CSNBT31P) . . . . . . . . . . . . . . . . . . . . . . . . . 778TR31_Optional_Data_Build (CSNBT31O) . . . . . . . . . . . . . . . . . . . . . . . . 782TR31_Optional_Data_Read (CSNBT31R) . . . . . . . . . . . . . . . . . . . . . . . . 785

Appendix A. Return codes and reason codes . . . . . . . . . . . . . . . . . . 789Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789Reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789

Reason codes that accompany return code 0 . . . . . . . . . . . . . . . . . . . . . . . 790Reason codes that accompany return code 4 . . . . . . . . . . . . . . . . . . . . . . . 790Reason codes that accompany return code 8 . . . . . . . . . . . . . . . . . . . . . . . 791Reason codes that accompany return code 12. . . . . . . . . . . . . . . . . . . . . . . 804Reason codes that accompany return code 16. . . . . . . . . . . . . . . . . . . . . . . 805

Appendix B. Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . 807Key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807

Master-key verification pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . 807Token-validation value and record-validation value. . . . . . . . . . . . . . . . . . . . . 808Null key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808Internal fixed-length AES key tokens . . . . . . . . . . . . . . . . . . . . . . . . . 808Fixed-length DES key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810External RKX DES key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812PKA key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814Trusted blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841Variable-length symmetric key-token . . . . . . . . . . . . . . . . . . . . . . . . . 855

TR-31 optional block data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937Key-storage data sets and records . . . . . . . . . . . . . . . . . . . . . . . . . . . 938Key-record-list data sets and records . . . . . . . . . . . . . . . . . . . . . . . . . . 941Access-control data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943

Role structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943Profile structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948Examples of the access-control data structures . . . . . . . . . . . . . . . . . . . . . . 952

Master-key shares data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955Distributed function control vector . . . . . . . . . . . . . . . . . . . . . . . . . . . 956Visa Format-Preserving Encryption supporting information . . . . . . . . . . . . . . . . . . . 960

Contents vii

Appendix C. CCA control-vector definitions and key encryption . . . . . . . . . . 965Understanding DES control vector values . . . . . . . . . . . . . . . . . . . . . . . . . 965

Key-form bits, 'fff' and 'FFF' . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972Specifying a control-vector-base value . . . . . . . . . . . . . . . . . . . . . . . . . . 972Changing control vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975

Changing control vectors with the pre-exclusive-OR technique . . . . . . . . . . . . . . . . . 976Changing control vectors with the Control_Vector_Translate verb . . . . . . . . . . . . . . . . 978Changing control vectors with the Remote_Key_Export verb . . . . . . . . . . . . . . . . . 982

Understanding DES and RSA key encryption and decryption processes . . . . . . . . . . . . . . . 982DES key encryption and decryption processes . . . . . . . . . . . . . . . . . . . . . . 982RSA private-key encryption and decryption process . . . . . . . . . . . . . . . . . . . . 983PKA92 key format and encryption process . . . . . . . . . . . . . . . . . . . . . . . 985Encrypting a key-encrypting key in the NL-EPP-5 format . . . . . . . . . . . . . . . . . . 986

Appendix D. Algorithms and processes . . . . . . . . . . . . . . . . . . . . . 989Cryptographic key-verification techniques . . . . . . . . . . . . . . . . . . . . . . . . . 989

Master-key verification algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . 989CCA DES-key verification algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . 991Encrypt zeros AES-key verification algorithm. . . . . . . . . . . . . . . . . . . . . . . 991Encrypt zeros DES-key verification algorithm. . . . . . . . . . . . . . . . . . . . . . . 991

Modification Detection Code calculation . . . . . . . . . . . . . . . . . . . . . . . . . 992Ciphering methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

General data-encryption processes . . . . . . . . . . . . . . . . . . . . . . . . . . 993Triple-DES ciphering algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997MAC calculation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000

ANS X9.9 Option 1 MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000ANS X9.19 Optional Procedure MAC . . . . . . . . . . . . . . . . . . . . . . . . . 1001CMAC (block cipher-based MAC algorithm) . . . . . . . . . . . . . . . . . . . . . . 1001EMV MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001ISO 16609 Triple-DES MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002Keyed-hash MAC (HMAC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002

RSA key-pair generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002Passphrase verification protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

Design criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003Description of the protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004

Master-key-splitting algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005Formatting hashes and keys in public-key cryptography . . . . . . . . . . . . . . . . . . . 1005

ANS X9.31 hash format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005PKCS #1 hash formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006

Appendix E. Financial system verbs calculation methods and data formats . . . . . 1009PIN calculation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009

IBM 3624 PIN-calculation method . . . . . . . . . . . . . . . . . . . . . . . . . . 1010IBM 3624 PIN-offset calculation method . . . . . . . . . . . . . . . . . . . . . . . . 1010Netherlands PIN-1 calculation method . . . . . . . . . . . . . . . . . . . . . . . . 1011IBM German Bank Pool Institution PIN-calculation method . . . . . . . . . . . . . . . . . 1011Visa PIN-validation value PIN-calculation method . . . . . . . . . . . . . . . . . . . . 1012InterBank PIN-calculation method . . . . . . . . . . . . . . . . . . . . . . . . . . 1012

PIN-block formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012IBM 3624 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013ISO-0 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013ISO-1 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014ISO-2 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014ISO-3 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015

Derived unique-key-per-transaction calculation method . . . . . . . . . . . . . . . . . . . . 1016Deriving an ANS X9.24 DUKPT key . . . . . . . . . . . . . . . . . . . . . . . . . 1016Performing the special encryption and special decryption processes . . . . . . . . . . . . . . . 1017

CVV and CVC card-verification method . . . . . . . . . . . . . . . . . . . . . . . . . 1018Visa and EMV-related smart card formats and processes . . . . . . . . . . . . . . . . . . . 1019

Deriving the smart-card-specific authentication code . . . . . . . . . . . . . . . . . . . . 1020

viii CCA Basic Services November, 2016

Constructing the PIN-block for transporting an EMV smart-card PIN . . . . . . . . . . . . . . 1020Deriving the CCA TDES-XOR session key . . . . . . . . . . . . . . . . . . . . . . . 1021Deriving of the EMV TDESEMVn tree-based session key . . . . . . . . . . . . . . . . . . 1021PIN-block self-encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021

Appendix F. Verb list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023

Appendix G. Access-control-point codes . . . . . . . . . . . . . . . . . . . . 1031

Appendix H. Observations on secure operations. . . . . . . . . . . . . . . . . 1047Ensuring code levels match and IBM CCA code is installed . . . . . . . . . . . . . . . . . . 1047Managing access controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047

Locking the access-control system . . . . . . . . . . . . . . . . . . . . . . . . . . 1047Changing a passphrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048Defining roles and profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048

Protecting cryptographic keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049CCA asymmetric DES keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049Clear key parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050Key export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051Key unwrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052Clear-key operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052DES replicated keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053PKA keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053

PIN data considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054Validating coprocessor status data . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054RS-232 port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054Master-key cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055Sample access-control regimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055

Digital-signing server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055Secured code-signing node . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062

Appendix I. Java Native Interface . . . . . . . . . . . . . . . . . . . . . . . 1067

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069IBM agreement for licensed internal code . . . . . . . . . . . . . . . . . . . . . . . . 1070

Actions you must not take . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071

Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073

List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085

Contents ix

x CCA Basic Services November, 2016

Figures

1. CCA security API, access layer, and cryptographic engine . . . . . . . . . . . . . . . . . . 22. CCA master key protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303. Coprocessor-to-coprocessor DES or PKA master-key cloning . . . . . . . . . . . . . . . . . 344. PKA96 verbs with key-token flow. . . . . . . . . . . . . . . . . . . . . . . . . . 1045. Default key-wrapping method configuration . . . . . . . . . . . . . . . . . . . . . . 1796. Flow of cryptographic command processing in a cryptographic facility . . . . . . . . . . . . . 1857. Key_Token_Build2 keyword combinations for AES CIPHER keys . . . . . . . . . . . . . . . 1918. Key_Token_Build2 keyword combinations for AES MAC keys . . . . . . . . . . . . . . . . 1949. Key_Token_Build2 keyword combinations for HMAC MAC keys . . . . . . . . . . . . . . . 197

10. Key_Token_Build2 keyword combinations for AES EXPORTER keys . . . . . . . . . . . . . . 20011. Key_Token_Build2 keyword combinations for AES IMPORTER keys . . . . . . . . . . . . . . 20412. Key_Token_Build2 keyword combinations for AES PINPROT keys. . . . . . . . . . . . . . . 20813. Key_Token_Build2 keyword combinations for AES PINCALC keys. . . . . . . . . . . . . . . 21114. Key_Token_Build2 keyword combinations for AES PINPRW keys . . . . . . . . . . . . . . . 21415. Key_Token_Build2 keyword combinations for AES DKYGENKY keys . . . . . . . . . . . . . . 21716. Key_Token_Build2 keyword combinations for AES SECMSG keys (4.4.55 or later). . . . . . . . . . 22117. Control_Vector_Generate and Key_Token_Build CV keyword combinations for fixed-length DES key tokens 22418. AES and DES fixed-length key-token contents . . . . . . . . . . . . . . . . . . . . . 22819. Use of fixed-length AES key tokens and key labels . . . . . . . . . . . . . . . . . . . . 23020. Use of fixed-length DES key tokens and key labels . . . . . . . . . . . . . . . . . . . . 23121. Key-processing and key-storage verbs for keys in fixed-length AES key tokens . . . . . . . . . . 23422. Key-processing and key-storage verbs for keys in fixed-length DES key tokens . . . . . . . . . . 23523. DES key exporting and key importing . . . . . . . . . . . . . . . . . . . . . . . . 23924. Overview of trusted block contents . . . . . . . . . . . . . . . . . . . . . . . . . 24325. Simplified RKX key-token structure . . . . . . . . . . . . . . . . . . . . . . . . . 24726. Trusted block creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24727. Exporting DES keys using a trusted block . . . . . . . . . . . . . . . . . . . . . . . 24828. Generating DES keys using a trusted block . . . . . . . . . . . . . . . . . . . . . . 25129. Typical flow of verbs for remote key export . . . . . . . . . . . . . . . . . . . . . . 25230. Financial PIN verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56031. Access-control system profile structure . . . . . . . . . . . . . . . . . . . . . . . . 94832. Format of profile activation date and expiration date . . . . . . . . . . . . . . . . . . . 94833. Aggregate profile structure with header. . . . . . . . . . . . . . . . . . . . . . . . 94934. Layout of the authentication data field . . . . . . . . . . . . . . . . . . . . . . . . 95035. Passphrase authentication data structure example . . . . . . . . . . . . . . . . . . . . 95236. User profile data structure example . . . . . . . . . . . . . . . . . . . . . . . . . 95237. Aggregate profile structure example . . . . . . . . . . . . . . . . . . . . . . . . . 95338. Access-control-point list example . . . . . . . . . . . . . . . . . . . . . . . . . . 95339. Role data structure example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 95440. Aggregate role data structure example . . . . . . . . . . . . . . . . . . . . . . . . 95541. DES control-vector-base bit map (Part 1 of 3) . . . . . . . . . . . . . . . . . . . . . . 96942. DES control-vector-base bit map (Part 2 of 3) . . . . . . . . . . . . . . . . . . . . . . 97043. DES control-vector-base bit map (Part 3 of 3) . . . . . . . . . . . . . . . . . . . . . . 97144. Exchanging a key with a non-control-vector system . . . . . . . . . . . . . . . . . . . . 97745. Control_Vector_Translate verb mask_array processing . . . . . . . . . . . . . . . . . . . 98046. Control_Vector_Translate verb process . . . . . . . . . . . . . . . . . . . . . . . . 98147. Multiply-enciphering and multiply-deciphering DES and RSA keys . . . . . . . . . . . . . . 98448. Triple-DES data encryption and decryption . . . . . . . . . . . . . . . . . . . . . . 99449. Enciphering using the NIST SP 800-38A CBC method . . . . . . . . . . . . . . . . . . . 99550. Deciphering using the CBC method . . . . . . . . . . . . . . . . . . . . . . . . . 99551. Enciphering using the ANS X9.23 method . . . . . . . . . . . . . . . . . . . . . . . 99652. Deciphering using the ANS X9.23 method . . . . . . . . . . . . . . . . . . . . . . . 99753. Triple-DES CBC encryption process . . . . . . . . . . . . . . . . . . . . . . . . . 99854. Triple-DES CBC decryption process . . . . . . . . . . . . . . . . . . . . . . . . . 99855. EDE algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

© Copyright IBM Corp. 2007, 2016 xi

56. DED process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100057. MAC calculation method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100258. Example of logon key computation . . . . . . . . . . . . . . . . . . . . . . . . . 100459. 3624 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101360. ISO-0 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101361. ISO-1 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101462. ISO-2 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101463. ISO-3 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101564. CVV track 2 algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019

xii CCA Basic Services November, 2016

Tables

1. Coprocessor product by platform and CCA Release. . . . . . . . . . . . . . . . . . . . xvii2. Software offering by CCA release . . . . . . . . . . . . . . . . . . . . . . . . . xviii3. PKA key-management services . . . . . . . . . . . . . . . . . . . . . . . . . . . 64. Verb parameter format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95. CCA node, access control, and master-key management verbs. . . . . . . . . . . . . . . . . 156. Summary of available CCA coprocessor information . . . . . . . . . . . . . . . . . . . . 237. Key-storage location by operating system . . . . . . . . . . . . . . . . . . . . . . . 288. CCA node wrapping methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 309. Role tracking data header format . . . . . . . . . . . . . . . . . . . . . . . . . . 49

10. GETDATA output_data format . . . . . . . . . . . . . . . . . . . . . . . . . . . 4911. GETSTATE output_data format . . . . . . . . . . . . . . . . . . . . . . . . . . . 5112. Configuration_Facility_Control weak PIN structure header. . . . . . . . . . . . . . . . . . 5913. Configuration_Facility_Control WPIN-AC, WPIN-LD, WPIN-RM weak PIN structure (type X'00') . . . . . 5914. Cryptographic_Facility_Query information returned in the rule array . . . . . . . . . . . . . . 6315. Cryptographic_Facility_Query information returned in the verb_data variable . . . . . . . . . . . 7016. Cryptographic_Facility_Query STATWPIN weak PIN entry structure (type X'30') . . . . . . . . . . 7117. Questionable DES keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10018. PKA key-management services. . . . . . . . . . . . . . . . . . . . . . . . . . . 10319. Description of PKA key token types that CCA can build . . . . . . . . . . . . . . . . . . 12120. PKA_Key_Token_Build key-values-structure contents, RSA keys . . . . . . . . . . . . . . . 12521. PKA_Key_Token_Build key-values-structure contents, ECC keys . . . . . . . . . . . . . . . 12722. PKA_Key_Token_Build key-derivation data format for ECC private keys . . . . . . . . . . . . 12923. Sample key values structure data for RSA keys . . . . . . . . . . . . . . . . . . . . . 13024. Sample key-values structure data for ECC keys . . . . . . . . . . . . . . . . . . . . . 13125. Sample key-derivation data for ECC key-derivation information section (X'23'), Release 5.2 or later . . . . 13126. Hashing and digital signature services . . . . . . . . . . . . . . . . . . . . . . . . 14927. Basic AES and DES key-management verbs . . . . . . . . . . . . . . . . . . . . . . 17128. DES translation control rule-array keyword . . . . . . . . . . . . . . . . . . . . . . 18029. DES key-wrapping method rule-array keywords . . . . . . . . . . . . . . . . . . . . . 18030. Summary of verbs and DES key-wrapping method selection criteria . . . . . . . . . . . . . . 18231. AES key types and verb usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 18532. HMAC key types and verb usage . . . . . . . . . . . . . . . . . . . . . . . . . . 18633. DES key types and verb usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 18634. Key_Token_Build2 rule array keywords for AES CIPHER keys . . . . . . . . . . . . . . . . 19135. Key_Token_Build2 rule array keywords for AES MAC keys (Release 4.4 or later) . . . . . . . . . . 19436. Key_Token_Build2 rule array keywords for HMAC MAC keys . . . . . . . . . . . . . . . . 19737. Key_Token_Build2 rule array keywords for AES EXPORTER keys . . . . . . . . . . . . . . . 20138. Key_Token_Build2 rule array keywords for AES IMPORTER keys . . . . . . . . . . . . . . . 20539. Key_Token_Build2 rule array keywords for AES PINPROT keys (Release 4.4 or later) . . . . . . . . 20840. Key_Token_Build2 rule array keywords for AES PINCALC keys (Release 4.4 or later) . . . . . . . . 21141. Key_Token_Build2 rule array keywords for AES PINPRW keys (Release 4.4 or later) . . . . . . . . . 21442. Key_Token_Build2 rule array keywords for AES DKYGENKY keys (Release 4.4 or later) . . . . . . . 21843. Related key usage fields when Key_Token_Build2 builds a DKYGENKY key-token . . . . . . . . . 22044. Key_Token_Build2 rule array keywords for AES SECMSG keys (4.4.55) . . . . . . . . . . . . . 22245. DES control vector key-subtype and key-usage keywords . . . . . . . . . . . . . . . . . . 22546. Sample rule section GENERAT1 . . . . . . . . . . . . . . . . . . . . . . . . . . 25347. Verb inputs and outputs for sample rule GENERAT1 . . . . . . . . . . . . . . . . . . . 25448. Sample rule section GENERAT2 . . . . . . . . . . . . . . . . . . . . . . . . . . 25549. Verb inputs and outputs for sample rule GENERAT2 . . . . . . . . . . . . . . . . . . . 25550. Sample rule section EXPORT1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 25651. Verb inputs and outputs for sample rule EXPORT1 . . . . . . . . . . . . . . . . . . . . 25752. Sample rule section EXPORT2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 25753. Verb inputs and outputs for sample rule EXPORT2 . . . . . . . . . . . . . . . . . . . . 25854. Sample rule section EXPORT3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 25955. Verb inputs and outputs for sample rule EXPORT3 . . . . . . . . . . . . . . . . . . . . 259

© Copyright IBM Corp. 2007, 2016 xiii

56. CSNBDKG2 tokens with generating_key_identifier1. . . . . . . . . . . . . . . . . . . . 28757. CSNDEDH concatenation string format for DERIV01 . . . . . . . . . . . . . . . . . . . 29058. DERIV01 supplied public information . . . . . . . . . . . . . . . . . . . . . . . . 29159. CSNDEDH concatenation string format for DERIV02 . . . . . . . . . . . . . . . . . . . 29260. CSNBKGN key_form keywords and their usage . . . . . . . . . . . . . . . . . . . . . 30861. CSNBKGN key_length values . . . . . . . . . . . . . . . . . . . . . . . . . . . 31062. Key_type and key_form keywords for one key . . . . . . . . . . . . . . . . . . . . . 31363. Key_type and key_form keywords for a DES key pair . . . . . . . . . . . . . . . . . . . 31464. Key lengths by AES key-type . . . . . . . . . . . . . . . . . . . . . . . . . . . 31565. Key lengths by DES key-type . . . . . . . . . . . . . . . . . . . . . . . . . . . 31566. Key_Generate2 key_type and key_form keywords for one AES or HMAC key . . . . . . . . . . . 32367. Key_type and key_form keywords for a pair of AES or HMAC keys . . . . . . . . . . . . . . 32468. Key_Generate2 access control requirements for DK enabled keys (Release 4.4 or later) . . . . . . . . 32669. Key_Test GENERATE outputs and VERIFY inputs . . . . . . . . . . . . . . . . . . . . 34170. Key_Test_Extended GENERATE outputs and VERIFY inputs. . . . . . . . . . . . . . . . . 35271. Key_Token_Parse2 key_type keywords . . . . . . . . . . . . . . . . . . . . . . . . 37772. Key_Translate2 key tokens for reencipherment keywords V0PYLD and V1PYLD (Release 4.4 or later) 38673. Key_Translate2 key tokens for reencipherment keyword REFORMAT. . . . . . . . . . . . . . 38774. Key_Translate2 key tokens based on algorithm and reencipherment keyword TRANSLAT . . . . . . . 38875. Parameters format for public-key certificate . . . . . . . . . . . . . . . . . . . . . . 41776. Symmetric_Key_Export source key tokens . . . . . . . . . . . . . . . . . . . . . . . 42877. Symmetric_Key_Export key formatting methods by source key-token . . . . . . . . . . . . . . 42978. Symmetric_Key_Import2 key-wrapping method of target key when system default is ECB (Legacy) 45379. Symmetric_Key_Import2 key-wrapping method of target key when system default is CBC (Enhanced) 45480. Data confidentiality and data integrity verbs . . . . . . . . . . . . . . . . . . . . . . 47181. Key-storage-record services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51982. Financial services support verbs . . . . . . . . . . . . . . . . . . . . . . . . . . 55783. PIN verb, PIN-calculation method, and PIN-block format support summary . . . . . . . . . . . 56184. PIN calculation methods and keywords . . . . . . . . . . . . . . . . . . . . . . . . 56385. PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56586. Pad-digit specification by PIN-block format . . . . . . . . . . . . . . . . . . . . . . 56687. PIN-extraction method keywords by PIN-block format. . . . . . . . . . . . . . . . . . . 56788. Verbs affected by enhanced PIN security mode . . . . . . . . . . . . . . . . . . . . . 56889. Clear_PIN_Generate_Alternate rule_array keywords (first element) . . . . . . . . . . . . . . 58390. Clear_PIN_Generate_Alternate rule_array keywords (second element) . . . . . . . . . . . . . 58491. Key-wrapping matrix for CVV_Key_Combine. . . . . . . . . . . . . . . . . . . . . . 59192. Encrypted_PIN_Translate PIN-extraction method rule_array keywords . . . . . . . . . . . . . 60493. VDSP Encrypted_PIN_Translate PIN-extraction method rule_array keywords . . . . . . . . . . . 61194. Encrypted_PIN_Verify PIN-extraction method rule_array keywords . . . . . . . . . . . . . . 61995. Financial services support for DK verbs. . . . . . . . . . . . . . . . . . . . . . . . 67396. TR-31 symmetric key management verbs . . . . . . . . . . . . . . . . . . . . . . . 72897. Export translation table for a TR-31 BDK base derivation key (BDK) . . . . . . . . . . . . . . 73698. Export translation table for a TR-31 CVK card verification key (CVK) . . . . . . . . . . . . . . 73799. Export translation table for a TR-31 data encryption key (ENC) . . . . . . . . . . . . . . . . 739

100. Export translation table for a TR-31 key encryption or wrapping, or key block protection key (KEK orKEK-WRAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739

101. Export translation table for a TR-31 ISO MAC algorithm key (ISOMACn) . . . . . . . . . . . . 740102. Export translation table for a TR-31 PIN encryption or PIN verification key (PINENC, PINVO, PINV3624,

VISAPVV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742103. Export translation table for a TR-31 EMV/chip issuer master-key key (DKYGENKY, DATA) . . . . . . 746104. Import translation table for a TR-31 BDK base derivation key (usage "B0") . . . . . . . . . . . . 759105. Import translation table for a TR-31 CVK card verification key (usage "C0"). . . . . . . . . . . . 760106. Import translation table for a TR-31 data encryption key (usage "D0"). . . . . . . . . . . . . . 761107. Import translation table for a TR-31 key encryption or wrapping, or key block protection key (usages "K0",

"K1") . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762108. Import translation table for a TR-31 ISO MAC algorithm key (usages "M0", "M1", "M3") . . . . . . . 764109. Import translation table for a TR-31 PIN encryption or PIN verification key (usages "P0", "V0", "V1", "V2") 765110. Import translation table for a TR-31 EMV/chip issuer master-key key (usages "E0", "E1", "E2", "E3", “E4",

"E5") . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769111. CSNBT31I CV sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773112. CSNBT31I protection methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 773

xiv CCA Basic Services November, 2016

113. Return code values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789114. Reason codes for return code 0 . . . . . . . . . . . . . . . . . . . . . . . . . . 790115. Reason codes for return code 4 . . . . . . . . . . . . . . . . . . . . . . . . . . 790116. Reason codes for return code 8 . . . . . . . . . . . . . . . . . . . . . . . . . . 791117. Reason codes for return code 12 . . . . . . . . . . . . . . . . . . . . . . . . . . 804118. Reason codes for return code 16 . . . . . . . . . . . . . . . . . . . . . . . . . . 805119. Internal fixed-length AES key-token format, version X'04' . . . . . . . . . . . . . . . . . . 809120. Internal fixed-length AES key-token flag byte . . . . . . . . . . . . . . . . . . . . . . 810121. Internal fixed-length DES key-token format, version X'00' (version 2 and later software) . . . . . . . 810122. Internal fixed-length DES key-token format, version X'03' . . . . . . . . . . . . . . . . . . 811123. External fixed-length DES key-token format, version X'00'. . . . . . . . . . . . . . . . . . 811124. External fixed-length DES key-token format, version X'01' . . . . . . . . . . . . . . . . . 812125. Internal and external fixed-length DES key-token flag byte 1 . . . . . . . . . . . . . . . . . 812126. Internal and external fixed-length DES key-token flag byte 2 . . . . . . . . . . . . . . . . . 812127. External RKX DES key-token format, version X'10' . . . . . . . . . . . . . . . . . . . . 813128. PKA key token section data structures . . . . . . . . . . . . . . . . . . . . . . . . 814129. Optional RSA private key sections . . . . . . . . . . . . . . . . . . . . . . . . . 815130. Optional ECC private-key section . . . . . . . . . . . . . . . . . . . . . . . . . . 816131. PKA key-token header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818132. PKA null key-token format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818133. RSA private key, 1024-bit Modulus-Exponent format section (X'02') . . . . . . . . . . . . . . 818134. RSA private key, 2048-bit Chinese-Remainder Theorem format section (X'05') . . . . . . . . . . . 819135. RSA private key, 1024-bit Modulus-Exponent format with OPK section (X'06') . . . . . . . . . . . 821136. RSA private key, 4096-bit Modulus-Exponent format with AES-encrypted OPK section (X'30') . . . . . . 823137. RSA private key, 4096-bit Modulus-Exponent format section (X'09') . . . . . . . . . . . . . . 825138. RSA private key, Chinese-Remainder Theorem format with OPK section (X'08') . . . . . . . . . . 827139. RSA private key, 4096-bit Chinese-Remainder Theorem format with AES-encrypted OPK section (X'31') 829140. RSA public-key section (X'04') . . . . . . . . . . . . . . . . . . . . . . . . . . . 831141. PKA private-key name section (X'10') . . . . . . . . . . . . . . . . . . . . . . . . 832142. PKA public-key certificate section (X'40') . . . . . . . . . . . . . . . . . . . . . . . 832143. ECC public-key subsection (X'22') of PKA public-key certificate section (X'40') (Release 5.2 or later) . . . . 833144. RSA public-key subsection (X'41') of PKA public-key certificate section (X'40') . . . . . . . . . . . 833145. PKA certificate-information subsection (X'42') of PKA public-key certificate section (X'40') . . . . . . . 834146. PKA user-data TLV object (X'50') of PKA certificate-information subsection (X'42') . . . . . . . . . 834147. PKA private-key EID TLV object (X'51') of PKA certificate-information subsection (X'42') . . . . . . . 834148. PKA serial number TLV object (X'52') of PKA certificate-information subsection (X'42') . . . . . . . . 835149. PKA signature subsection (X'45') of PKA public-key certificate section (X'40') . . . . . . . . . . . 835150. ECC key-derivation information section (X'23') (Release 5.2 or later) . . . . . . . . . . . . . . . . 835151. ECC supported Brainpool elliptic curves by size, name, and object identifier . . . . . . . . . . . 836152. ECC supported Prime elliptic curves by size, name, and object identifier. . . . . . . . . . . . . 837153. ECC private-key section (X'20'). . . . . . . . . . . . . . . . . . . . . . . . . . . 837154. ECC section hash TLV object (X'60') of Version 1 ECC private-key section (X'20') (Release 5.2 or later) 840155. ECC public-key section (X'21') . . . . . . . . . . . . . . . . . . . . . . . . . . . 840156. RSA private-key blinding information . . . . . . . . . . . . . . . . . . . . . . . . 840157. Trusted block header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843158. Trusted block trusted RSA public-key section (X'11'). . . . . . . . . . . . . . . . . . . . 844159. Trusted block rule section (X'12') . . . . . . . . . . . . . . . . . . . . . . . . . . 845160. Summary of trusted block rule subsection . . . . . . . . . . . . . . . . . . . . . . . 846161. Transport key variant subsection (X'0001') of trusted block rule section (X'12') . . . . . . . . . . . 847162. Transport key rule reference subsection (X'0002') of trusted block rule section (X'12') . . . . . . . . . 847163. Common export key parameters subsection (X'0003') of trusted block rule section (X'12') . . . . . . . 848164. Source key rule reference subsection (X'0004') of trusted block rule section (X'12') . . . . . . . . . . 849165. Export key CCA token parameters subsection (X'0005') of trusted block rule section (X'12'). . . . . . . 850166. Trusted block key label (name) section (X'13') . . . . . . . . . . . . . . . . . . . . . . 852167. Trusted block information section (X'14') . . . . . . . . . . . . . . . . . . . . . . . 852168. Summary of trusted block information subsections . . . . . . . . . . . . . . . . . . . . 852169. Protection information subsection (X'0001') of trusted block information section (X'14') . . . . . . . . 853170. Activation and expiration dates subsection (X'0002') of trusted block information section (X'14') . . . . . 854171. Trusted block application-defined data section (X'15') . . . . . . . . . . . . . . . . . . . 854172. Summary of variable-length symmetric-key token key types, algorithms, and formats . . . . . . . . 855173. Variable-length symmetric key-token, version X'05' general format . . . . . . . . . . . . . . . 857

Tables xv

174. HMAC keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869175. Variable-length symmetric key-token, Version X'05' AES CIPHER format . . . . . . . . . . . . . 870176. Variable-length symmetric key-token, Version X'05' AES MAC format (Release 4.4 or later) . . . . . . 878177. Variable-length symmetric key-token, Version X'05' HMAC MAC format. . . . . . . . . . . . . 887178. Variable-length symmetric key-token, Version X'05' AES EXPORTER and IMPORTER formats. . . . . . 895179. Variable-length symmetric key-token, Version X'05' AES PINPROT, PINCALC, and PINPRW formats

(Release 4.4 or later) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906180. Variable-length symmetric key-token, Version X'05' DES key type DESUSECV format (Release 4.4 or later) 914181. Variable-length symmetric key-token, Version X'05' AES key type DKYGENKY format (Release 4.4 or later) 918182. Variable-length symmetric key-token, Version X'05' AES key type SECMSG format (Release 4.4.55 or later) 927183. Common key-usage field 1, low-order byte . . . . . . . . . . . . . . . . . . . . . . 933184. Common key-management field 1 . . . . . . . . . . . . . . . . . . . . . . . . . 934185. Common key-management field 2 . . . . . . . . . . . . . . . . . . . . . . . . . 935186. Common key-management field 3 . . . . . . . . . . . . . . . . . . . . . . . . . 936187. IBM optional block data in a TR-31 key block. . . . . . . . . . . . . . . . . . . . . . 937188. Key-storage file, header record 1 (not IBM i) . . . . . . . . . . . . . . . . . . . . . . 938189. Key-storage file, header record 2 (not IBM i) . . . . . . . . . . . . . . . . . . . . . . 939190. Key-record format in key storage (not IBM i) . . . . . . . . . . . . . . . . . . . . . . 940191. DES key-record format, IBM i key storage . . . . . . . . . . . . . . . . . . . . . . . 941192. AES and PKA key-record format, IBM i key storage . . . . . . . . . . . . . . . . . . . 941193. Key-record-list data set format (other than IBM i) . . . . . . . . . . . . . . . . . . . . 941194. Access-control system role structure . . . . . . . . . . . . . . . . . . . . . . . . . 944195. Aggregate role structure with header . . . . . . . . . . . . . . . . . . . . . . . . 946196. Access-control-point list structure . . . . . . . . . . . . . . . . . . . . . . . . . . 947197. Bit-map segment structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947198. Commands permitted in default role. . . . . . . . . . . . . . . . . . . . . . . . . 947199. Authentication data for each authentication mechanism . . . . . . . . . . . . . . . . . . 950200. Cloning information token data structure . . . . . . . . . . . . . . . . . . . . . . . 955201. Master-key-share TLV. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956202. Cloning information signature TLV . . . . . . . . . . . . . . . . . . . . . . . . . 956203. FCV distribution structure, FCV format version X'01' . . . . . . . . . . . . . . . . . . . 957204. VFPE alphabet by field type . . . . . . . . . . . . . . . . . . . . . . . . . . . 961205. VFPE BASE-10 alphabet for PAN data and Track 2 Discretionary Data . . . . . . . . . . . . . 962206. VFPE Track 1 Discretionary Data and Cardholder Name alphabets. . . . . . . . . . . . . . . 963207. DES key classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965208. Key-type default control-vector values . . . . . . . . . . . . . . . . . . . . . . . . 967209. PKA92 clear DES key-record (PKR) . . . . . . . . . . . . . . . . . . . . . . . . . 985210. NL-EPP-5 key-record format . . . . . . . . . . . . . . . . . . . . . . . . . . . 987211. SHA2VP1 master-key verification method prepend data . . . . . . . . . . . . . . . . . . 990212. Versions of the MDC calculation method . . . . . . . . . . . . . . . . . . . . . . . 992213. MDC calculation procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 992214. Financial PIN-calculation methods, data formats, and other items. . . . . . . . . . . . . . . 1009215. Security API verbs in supported environments . . . . . . . . . . . . . . . . . . . . . 1023216. Alphabetical list of security API command and subcommand codes returned by STATDIAG. . . . . . 1027217. Supported CCA commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031218. Example roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048219. PIN data exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054220. Roles and permissions for a digital-signing server . . . . . . . . . . . . . . . . . . . . 1060221. Roles and permissions for a simple certification authority case. . . . . . . . . . . . . . . . 1063

xvi CCA Basic Services November, 2016

About this document

This document is intended for systems analysts, applications analysts, and application programmers whoevaluate or create programs that employ the IBM® Common Cryptographic Architecture (CCA)application programming interface (API). IBM also offers a CCA implementation on IBM System z® thatis described in other publications.

IBM provides two PCIe cryptographic coprocessors for your cryptographic needs. These coprocessors aresupported on each platform as shown in Table 1.

Table 1. Coprocessor product by platform and CCA Release

PlatformCryptographiccoprocessor CCA Release Coprocessor product

IBM PowerSystems™

PCIe 4.4.55 (IBM AIX® only)4.4.20 (IBM AIX only)4.2.8 (IBM i only)

Feature code 4807, Customer Card IdentificationNumber 4765 (IBM POWER6® withoutblind-swap cassette custom carrier)

Feature code 4808, Customer Card IdentificationNumber 4765 (IBM POWER6 with blind-swapcassette custom carrier and instruction ECN23386)

Feature code 4809, Customer Card IdentificationNumber 4765 (IBM POWER7® with blind-swapcassette customer carrier and instruction ECN23597)

5.3.12 (IBM AIX, IBM i,and PowerLinux™)

Feature code EJ32, Customer Card IdentificationNumber 4767 (IBM POWER8® withoutblind-swap cassette custom carrier)

Feature code EJ33, Customer Card IdentificationNumber 4767 (IBM POWER8 with blind-swapcassette custom carrier)

x86 (formerly IBMSystem x)

PCIe 5.3.125.2.23

IBM machine type-model 4767-002

4.4.554.4.20

IBM machine type-model 4765-001

On Power Systems, the following operating systems are supported:v IBM AIXv IBM iv PowerLinux

– Red Hat Enterprise Linux (RHEL) Server– SUSE Linux Enterprise Server (SLES) from Novell– Ubuntu by Canonical

Servers that are x86 based have the following operating systems supported:v Microsoft Windows Serverv Red Hat Enterprise Linux (RHEL) Serverv SUSE Linux Enterprise Server (SLES) from Novell

© Copyright IBM Corp. 2007, 2016 xvii

|||||

|||

|

|

|

|

The different software offerings that are supported for each CCA release are shown in Table 2.

Table 2. Software offering by CCA release

Operating system PlatformCCARelease Software offering

IBM AIX Power Systems 4.4.55 Release 7.1, 32-bit and 64-bit

Release 6.1, 32-bit and 64-bit

4.4.20 Release 7.1, 32-bit and 64-bit



5.3.12 Release 7.2, 32-bit and 64-bit



IBM i Power Systems 4.2.8 Option 35 Cryptographic ServiceProvider 7.1 and 6.1

5.3.12 Release 7.3 Technology Refresh 1, 32-bitand 64-bit

Release 7.2, Technology Refresh 5,32-bit and 64-bit

Microsoft Windows x86 (formerlySystem x)

5.3.12 Windows Server 2012 R2, 64-bit

Red Hat Enterprise Linux (RHEL)Server

x86 (formerlySystem x)

5.3.12 RHEL 7.2, 64-bit

5.2.23 RHEL 6.7, 64-bit

Power Systems 5.3.12 RHEL 7.3, 64-bit

RHEL 7.2, 64-bit

SUSE Linux Enterprise Server fromNovell (SLES)

x86 (formerlySystem x)

5.3.12 SLES 12 Service Pack 1, 64-bit

5.2.23

4.4.55 SLES 11 Service Pack 3, Service Pack 2and Service Pack 1, 32-bit

4.4.20 SLES 11 Service Pack 3, Service Pack 2and Service Pack 1, 32-bit

Power Systems 5.3.12 SLES 12 Service Pack 2 (little endian),64-bit

Ubuntu Canonical Power Systems 5.3.12 Ubuntu 16.04.1

Note: Refer to the HSM 4767 link or the HSM 4765 link at www.ibm.com/security/cryptocards for thelatest supported environments and product ordering information. From there, click on Product supportand then click on Software updates.

Summary of changes

Thirty-third edition, November 2016, Releases 5.3, 5.2, 4.4, and 4.2This edition describes the IBM CCA Basic Services API for Releases 5.3, 5.2, 4.4, and 4.2, as of November2016.

xviii CCA Basic Services November, 2016

||

|

|

|||

||

|||

|

||||

||||

|

||

http://www.ibm.com/security/cryptocards

Changes for Release 5.3.12

As of November 2016, Release 5.3.12 includes support for IBM Power Systems with any of the followingoperating systems installed:v IBM AIXv IBM iv PowerLinux

– Red Hat Enterprise Linux (RHEL) Server– SUSE Linux Enterprise Server (SLES) from Novell– Ubuntu by Canonical

Thirty-second edition, November 2016, Releases 5.3, 5.2, 4.4, and 4.2This edition describes the IBM CCA Basic Services API for Releases 5.3, 5.2, 4.4, and 4.2, as of September2016.


As of November 2016, Release 5.3.12 includes support for Linux.

Thirty-first edition, August 2016, Releases 5.3, 5.2, 4.4, and 4.2This edition describes the IBM CCA Basic Services API for Releases 5.3, 5.2, 4.4, and 4.2, as of August2016.


Beginning with Release 5.3.12, support is added to the Windows operating system of Microsoft.

CCA Release 5.3.12 provides the following enhancements to the CCA API:

The addition of support for the PKCS #1 v2.2 RSA Probabilistic Signature Scheme (RSA-PSS). RSA-PSS isbased on the RSA cryptosystem and provides increased security assurance:v Digital_Signature_Generate

– New digital-signature hash formatting method rule-array keyword PKCS-PSS.– The addition of the SHA-224 hashing-method specification rule-array keyword.

v Digital_Signature_Verify– New digital-signature hash formatting method rule-array keyword PKCS-PSS.– New signature checking rule rule-array keyword group, with keywords EXMATCH and

NEXMATCH, and related new required command Allow Not Exact Salt Length (offset X'033B').

The addition of digital signature support to optionally process the text supplied in the data variable(formerly hash variable) as a message that is to be hashed using the specified hashing-method:v Digital_Signature_Generate

– New input type rule-array keyword group, with keywords HASH and MESSAGE.v Digital_Signature_Verify

– New input type rule-array keyword group, with keywords HASH and MESSAGE.– New hashing-method specification rule-array keyword group, with keywords MD5, RPMD-160,

SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.

About this document xix

|

||

|

|

|

|

|

|

|

||

|

|

The addition of format restrictions for PKA private key tokens of type RSA-AESC (token version X'31')and RSA-AESM (X'30') to optionally restrict these private keys to a particular digital-signature hashformatting method, or not restrict them (the default). Options include ISO-9796, PKCS-1.0, PKCS-1.1,PKCS-PSS, X9.31, or ZERO-PAD.v PKA_Key_Token_Build and PKA_Key_Translate

New rule array keyword format restriction group, including keywords FR-I9796, FR-NONE, FR-PK10,FR-PK11, FR-PSS, FR-X9.31, and FR-ZPAD.

v Addition of key token definitions for format restriction for digital-signature hash-formatting method,offset 51, in RSA private key RSA private key sections X'30' and X'31' (4096-bit M-E format and CRTformat, with AES-encrypted OPK section).

Thirtieth edition, April 2016, Releases 5.2, 4.4, and 4.2This edition describes the IBM CCA Basic Services API for Releases 5.2, 4.4, and 4.2, as of April 2016.


With CCA Release 5.2.23, IBM introduces the latest generation and fastest of its PCIe hardware securitymodules (HSMs), the IBM 4767 PCIe Cryptographic Coprocessor. The 4767 is redesigned for improvedperformance and security rich services for your sensitive workloads, and to deliver high throughput forcryptographic functions. The 4767 can be installed in IBM-approved x86 architecture servers (refer towww.ibm.com/security/cryptocards/pciecc2/overx86servers.shtml) running one of the followingoperating systems:v Novell Red Hat Enterprise Linux (RHEL)v SUSE Linux Enterprise Server (SLES)

Release 5.2.23 is the initial release of CCA for the 4767. This release provides the following enhancementsto the CCA API:v Applications can now use 64-bit integers when calling the CCA API.v Access_Control_Maintenance (CSUAACM)

– New function to perform rule-array keyword QTSN is added that specifies to retrieve the currentrandom 20-byte Transaction Sequence Number (TSN). The TSN is required by users to change theirown passphrase.

v Access_Control_Tracking (CSUAACT)– This new verb provides tracking information on a role ID basis about which access control points

are queried by applications.v Logon_Control (CSUALCT)

– New service to perform rule-array keyword CHG-PW that specifies to change your own passphrase.Requires new Change Own Passphrase command (offset X'0047') to be enabled in the active role.

– New logon identification method rule-array keyword PPHRASE2 that uses new Type '6'Passphrase2 authentication mechanism (PPHRASE uses Type '1'). Passphrase2 requires at least onealphabetic (A-Z, a-z) and at least one numeric (0-9) character. In addition, Passphrase2 requires aminimum passphrase length of 7 characters unless the new Validate Passphrase Length command(offset X'0039') is enabled in the active role, in which case a minimum passphrase length of 8characters is required.

– New access control command Validate Passphrase Length (offset X'0039'). With this offset enabled inthe active role, a more secure passphrase is required. Requirements include a passphrase length of atleast 8 characters, at least one alphabetic character, and and least one numeric character. Note thatenabling this command in an active role has the effect of disabling the PPHRASE logonidentification method and requiring the PPHRASE2 method. This is due to the fact that thePPHRASE method does not have the capability to validate a passphrase length.

xx CCA Basic Services November, 2016

– New service to perform rule-array keyword GETPBKDF that specifies to generate a 32-byte value(using Password Based Key Derivation Function 2) to be used as an AES key for the authenticationdata field of a Type '6' authentication mechanism required by the new passphrase2 (PPHRASE2)logon identification method.

v Random_Number_Tests (CSUARNT)– New test selection rule-array keyword KAT2 for performing AES Galois/Counter Mode (GCM)

functions.v Symmetric_Algorithm_Decipher (CSNBSAD)

– New processing rule rule-array keyword GCM and ICV selection keyword ONLY to allow data tobe deciphered in AES Galois/Counter Mode (GCM)

v Symmetric_Algorithm_Encipher (CSNBSAE)– New processing rule rule-array keyword GCM and ICV selection keyword ONLY to allow data to

be enciphered in AES Galois/Counter Mode (GCM)v New financial services support verbs for Visa Data Secure Platform with Point-to-Point Encryption

(VDSP with P2PE), including Visa Format Preserving Encryption (VFPE):– Encrypted_PIN_Verify_Extended (CSNBPTRE)– FPE_Decipher (CSNBFPED)– FPE_Encipher (CSNBFPEE)– FPE_Translate (CSNBFPET)

v EC_Diffie-Hellman (CSNDEDH)– New key agreement class rule-array keyword DERIV02. Specifies to use key derivation method

ANSI-9.63-KDF as specified in section 5.6.3 of ANSI X9.63-2011.– New hash method rule-array group in support of DERIV02 rule-array keyword.– New access-control command Allow EDH DERIV02 Keyword (offset X'035F') in support of

DERIV02 rule-array keyword.v ECC private-key section (X'20') changes in support of CSNDEDH ANSI-9.63-KDF

– A new key-token format is defined for ECC private keys (section identifier X'20') using sectionversion number X'01' (located at offset 1 of the section). The new Version 1 format differs from thelegacy Version 0 format as follows (only affected offsets are shown):

ECC private-key section(X'20') offset (bytes) Length (bytes)

Section version numberX'00' - legacy

Section version numberX'01' - Release 5.2

001 001 Section version number:X'00'

Section version number:X'01'

011 001 Reserved, binary zero Pedigree/Key source flagbyte

Start of IBM associated data

076 001 Associated data sectionversion number:X'00' LegacyOnly defined for Sectionversion number X'00' atoffset 001.

Associated data sectionversion number:X'01' Release 5.2 or laterOnly defined for sectionversion number X'01' atoffset 001.

078 002 Length in bytes of the IBMassociated data, includingkey label and IBMextended associated data: ≥16

Length in bytes of the IBMassociated data, includingkey label and IBMextended associated data: ≥52

080 002 Length in bytes of the IBMextended associated data: 0

Length in bytes of the IBMextended associated data:36

About this document xxi

ECC private-key section(X'20') offset (bytes) Length (bytes)

Section version numberX'00' - legacy

Section version numberX'01' - Release 5.2

088 001 Reserved, binary zero. Pedigree/Key source flagbyte of associated datasection

092 + kl 0 or 36 No optional IBM extendedassociated data

Note: A section hash TLVobject cannot be present.

Optional IBM extendedassociated data

Consists of a single newlydefined ECC section hashTLV object with TLV tagidentifier X'60' (Release 5.2or later).

Note: A section hash TLVobject is always present,and contains the SHA-256hash digest of all theoptional sections thatfollow the public-keysection, if any, otherwisecontains binary zeros.

v New optional ECC key-derivation information section X'23' in support of CSNDEDH ANSI-9.63-KDFv PKA_Key_Token_Build (CSNDPKB)

– New key_derivation_data_length and key_derivation_data parameters used to create new optional ECCkey-derivation information section X'23', which is required by CSNDEDH ANSI-9.63-KDF

– New ECC token version rule-array keyword group with keywords ECC-VER0 for a Version 0 ECCprivate-key section (X'20'), and ECC-VER1 for a Version 1, which is required by CSNDEDHANSI-9-.63-KDF. Note that the Version 1 section has security enhancements not included in Version0. Therefore, use of ECC-VER0 (the default) is discouraged.

v Newly selectable RSA public exponents 5, 17, and 257. This addition completes the series of the firstfive Fermat numbers. Fermat numbers take the form Fn = 2(2n) + 1, where n is a non-negative integer.The first five Fermat numbers are known to be prime.– PKA_Key_Token_Build (CSNDPKB). The "Related information" section of the CSNDPKB verb has

examples added to the sample key values structure data for RSA keys that include the newlyselectable public exponents.

– PKA_Key_Generate (CSNDPKG). The CSNDPKG verb now accepts RSA skeleton key tokens thathave the public exponent valued 0 (full random), 3, 5, 17, 257, and 65537.

v New distributed Function Control Vector (FCV) format for use by the IBM 4767. This FCV is digitallysigned by IBM using a 521-bit ECC key using ECDSA. This provides an increased protection levelcompared to the FCV signed by IBM for the IBM 4765, which has a 4096-bit key using ANS X9.31.

Twenty-ninth edition, October 2015, Releases 4.4, 4.2, 3.30, and 3.25This edition describes the IBM CCA Basic Services API for Releases 4.4, 4.2, 3.30, and 3.25 as of October2015. Beginning in October 2015, there are these modification levels of Release 4.4 available: 4.4.20, whichwas made available April 2014, and 4.4.55, which was made available October 2015. Release 4.4.55supersedes Release 4.4.54, which was made available August 2015. Release 4.4.55 corrects a problem witha non-maskable interrupt (NMI) being detected when the Server has a Xeon Version 2 or Version 3processor.


Beginning in October 2015, support for Release 4.4.55 is added to the IBM AIX operating system of IBMPower Systems.

xxii CCA Basic Services November, 2016

Twenty-eighth edition, August 2015, Releases 4.4, 4.3, 4.2, 4.1, 3.30,and 3.25This edition describes the IBM CCA Basic Services API for Releases 4.4, 4.3, 4.2, 4.1, 3.30, and 3.25 as ofAugust 2015. Beginning in August 2015, there are these modification levels of Release 4.4 available: 4.4.20,which was made available April 2014, and 4.4.55, which was made available August 2015.

Beginning with Release 4.4.55, the IBM CCA Support Program provides support for the followingenhancements:v Encryption mode ANY-MODE is added to AES key type CIPHER variable-length symmetric key

tokens.v Type of key to diversify D-SECMSG is added and key-derivation sequence levels DKYL1 and DKYL2

are added to the AES key type DKYGENKY variable-length symmetric key tokens.v AES key type SECMSG is added to variable-length symmetric key tokens.v Diversified_Key_Generate2 (CSNBDKG2)

– Two diversification process rule array keywords are added. One is KDFFM-DK (DK version of KeyDerivation Function in Feedback Mode). The other is MK-OPTC (EMV Master Key DerivationOption C).

– A bit length of generated key keyword group is added. The keywords in this group are KLEN128,KLEN192, and KLEN256.

– Three required commands are added, namely Diversified Key Generate2 (KDFFM-DK) (offsetX'02D3'), Allow Generated Key Length Option with KDFFM-DK Keyword (offset X'02D4'), andDiversified Key Generate2 (MK-OPTC) (offset X'02D2').

– The verb can used to generate the new AES SECMSG key type.v Key_Test2 (CSNBKYT2) has added to its rule array a KVP calculation keyword CMACZERO.v Key_Token_Build2 (CSNBKTB2) can build an AES SECMSG key token, and Key_Token_Parse2

(CSNBKTP2) can parse an AES SECMSG key token.v PKA_Decrypt (CSNDPKD) and PKA_Encrypt (CSNDPKE)

– A CSNDPKD recovery method and a CSNDPKE format method rule-array keyword are added. Thekeyword is PKCSOAEP.

– A hash method keyword group is added. The keywords in this group are SHA-1 and SHA-256.– Three required commands are added to CSNDPKD, namely PKA Decipher Clear Key Disallow

PKCS-1.2 (offset x'020A'), PKA Decipher Clear Key Disallow PKCSOAEP (offset X'020C'), and PKADecipher Clear Key Disallow ZERO-PAD (offset X'020B').

– Four required commands are added to CSNDPKE, namely PKA Encipher Clear Key Disallow MRP(offset X'0208'), PKA Encipher Clear Key Disallow PKCS-1.2 (offset X'0206'), PKA Encipher Clear KeyDisallow PKCSOAEP (offset X'0209'), and PKA Encipher Clear Key Disallow ZERO-PAD (offsetX'0207').

v MAC_Verify2 (CSNBMVR2) supports a MAC length of 8.v DK_PIN_Change (CSNBDPC)

– A script selection algorithm method rule-array keyword is added. The keyword is AES-CBC.– A MAC cipher method rule-array keyword is added. The keyword is CMAC.– A MAC length and presentation rule-array keyword is added. The keyword is MACLEN16.– The script_key_identifier parameter can identify an operational AES SECMSG key token.– The script_MAC_key_identifier parameter can identify an operational AES MAC key token that has a

MAC mode of CMAC.

About this document xxiii

Twenty-seventh edition, May 2014, Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60,3.30, 3.27, and 3.25This edition describes the IBM CCA Basic Services API for Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60, 3.30, 3.27and 3.25 as of May 2014. Beginning in May 2014, support for Release 4.4.20 is added to the IBM AIXoperating system of IBM Power Systems.


Beginning with Release 4.4.2.0, the IBM CCA Support Program provides support for the followingenhancements.v A new financial services verb that is based on the PIN methods of and meets the requirements

specified by the German banking Industry Committee, Die Deutsch Kreditwirtschaft, also known as DK.The intellectual property rights regarding the methods and specification belong to the German BankingIndustry Committee. The following DK verb is added:– DK_Migrate_PIN (CSNBDMP). Creates a PIN reference value or word (PRW) from a single input

PIN, without validation by an existing DK PIN block or PRW.

Twenty-sixth edition, April 2014, Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60,3.30, 3.27, and 3.25This edition describes the IBM CCA Basic Services API for Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60, 3.30, 3.27and 3.25 as of April 2014. Beginning in April 2014, there are two modification levels of Release 4.4available, namely 4.4.16, which was made available November 2013, and 4.4.20, which was madeavailable April 2014.


Beginning with Release 4.4.2.0, the IBM CCA Support Program provides support for the followingenhancements.v A new financial services verb that is based on the PIN methods of and meets the requirements

specified by the German banking Industry Committee, Die Deutsch Kreditwirtschaft, also known as DK.The intellectual property rights regarding the methods and specification belong to the German BankingIndustry Committee. The following DK verb is added:– DK_Migrate_PIN (CSNBDMP). Creates a PIN reference value or word (PRW) from a single input

PIN, without validation by an existing DK PIN block or PRW.

Twenty-fifth edition, November 2013, Releases 4.4, 4.3, 4.2, 4.1, 4.0,3.60, 3.30, 3.27, and 3.25This edition describes the IBM CCA Basic Services API for Releases 4.4, 4.3, 4.2, 4.1, 4.0, 3.60, 3.30, 3.27and 3.25 as of November 2013.

Changes for Release 4.4

Support for Release 4.4 is added to System x.

Beginning with Release 4.4, the IBM CCA Support Program provides support for the followingenhancements.v New financial services verbs that are based on the PIN methods of and meet the requirements

specified by the German Banking Industry Committee, Die Deutsche Kreditwirtschaft, also known as DK.The intellectual property rights regarding the methods and specification belong to the German BankingIndustry Committee. Chapter 9, “Financial services support for DK,” on page 673 is dedicated to DKverbs. The following DK verbs are added:

xxiv CCA Basic Services November, 2016

– DK_Deterministic_PIN_Generate (CSNBDDPG). Generates a PIN of a selected length that is basedon a deterministic method, formats it into a DK-defined PIN block, and creates a PIN referencevalue or word (PRW) over the PIN block and other information, then creates and encrypts adifferent DK-defined PIN block to use in a PIN-mailer printing system.

– DK_PAN_Modify_in_Transaction (CSNBDPMT). Creates a new PIN reference value or word (PRW)when a merger has occurred but the PIN that is to be retained comes from a PIN block that is partof a transaction. The DK_PRW_CMAC_Generate verb must be called prior to using this verb.

– DK_PAN_Translate (CSNBDPT). Generates a new encrypted PIN block with the same PIN as acurrent encrypted PIN block but with a different primary account number (PAN). This verb returnsa new encrypted PIN block and a new PIN block MAC. The returned data can be used at anauthorization node to accept the changed PAN and create a PIN reference value or word (PRW).

– DP_PIN_Change (CSNBDPC). Updates the PIN reference value or word (PRW) for a specifiedaccount. Current and new ISO-1 encrypted PIN blocks are entered along with the PIN referencevalue and other data needed to verify the current PIN.

– DK_PIN_Verify (CSNBDPV). Extracts a PIN from an encrypted PIN-block that has been formattedusing ISO-1, and converts it to an encrypted PIN block using a format specified by DK. A test PINreference value or word (PRW) is created and that value is bitwise compared to the input PINreference value.

– DK_PRW_Card_Number_Update (CSNBDPNU). Updates a PIN reference value or word (PRW) withnew time-sensitive card data, but without changing either the customer PIN or the primary accountnumber. The updated PIN reference value and associated new PRW random number value arereturned to be used as input by other PIN processes to verify the PIN.

– DK_PRW_CMAC_Generate (CSNBDPCG). Generates a message authentication code (MAC) overspecific values involved in a primary account number change transaction. The output of this verb isused as input to the DK_PAN_Modify_in_Transaction verb which creates the actual PIN referencevalue or word (PRW) used to verify the PIN in future transactions.

– DK_Random_PIN_Generate (CSNBDRPG). Generates a random PIN of a selected length andcalculates a PIN reference value or word (PRW). Other PIN processes can use the PRW to verify thePIN.

– DK_Regenerate_PRW (CSNBDRP). Generates a new PIN reference value or word (PRW) for achanged primary account number.

v A requirement for new DK verbs DK_Deterministic_PIN_Generate, DK_Random_PIN_Generate, andDK_PIN_Change to reject a generated or changed PIN that is considered weak.– For the Cryptographic_Facility_Control verb, keywords WPIN-AC, WPIN-LD, WPIN-RM, and

WPIN-RMA are added to the rule array to activate, load, or remove weak PIN entries from a tableon the coprocessor that is used by these verbs to determine if a PIN is weak.

– For the Cryptographic_Facility_Query verb, keywords SIZEWPIN and STATWPIN are added to therule array to query the size of the weak PIN table and to obtain the state information of the weakPIN table.

v New AES key types MAC for CMAC, PINCALC, PINPROT, and PINPRW, which are added tovariable-length symmetric key tokens in support of the new DK verbs.

v New MAC_Generate2 (CSNBMGN2) and MAC_Verify2 (CSNBMVR2) verbs, which are added togenerate and verify a new AES MAC variable-length symmetric key-token. The verbs also take as inputan HMAC MAC key.

v A new Diversified_Key_Generate2 (CSNBDKG2) verb, which generates an AES key based on a functionof a key-generating key, the diversification process rule, and derivation data that you supply. Forvariable-length symmetric key tokens, a new AES key-generating key is added with key typeDKYGENKY in support of the Diversified_Key_Generate2 verb.

v A new Recover_PIN_from_Offset (CSNBPFO) verb, which calculates the customer-entered PIN from aPIN generating key, account information, and an IBM-PINO offset. The IBM-PINO PIN calculationmethod is the only one supported by this verb.

About this document xxv

v A new Authentication_Parameter_Generate (CSNBAPG) verb, which generates an authenticationparameter as specified by S

with ibm corp....ensuring data integrity . 473 data confidentiality and data integrity verbs . 475...

Documents