CCA Basic Services Reference and Guide for the IBM 4758 PCI and IBM 4764 PCI-X Cryptographic Coprocessors Releases 2.53, 2.54, 3.20, 3.23, 3.24, 3.25, and 3.27

Eighteenth edition, October 2006

This edition describes the IBM Common Cryptographic Architecture (CCA) Basic Services API for Releases 2.53, 2.54, 3.20, 3.23, 3.24, 3.25, and 3.27.

Copyright International Business Machines Corporation 1997, 2006. All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

|

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

About this document . . . . . . . . . . . . . . . . . . . . . . xiii Revision history . . . . . . . . . . . . . . . . . . . . . . . . xiii

Eighteenth edition, October 2006, CCA Support Program, Releases 2.53, 2.54, 3.20, 3.23, 3.24, 3.25, and 3.27 . . . . . . . . . . . . . . . xiii

Seventeenth edition, May 2006, CCA Support Program, Releases 2.53, 2.54, 3.20, 3.23, 3.24, and 3.25 . . . . . . . . . . . . . . . . . . . xv

Sixteenth edition, October 2005, CCA Support Program, Releases 2.53, 2.54, 3.20, 3.23, and 3.24 . . . . . . . . . . . . . . . . . . . xvii

Fifteenth edition, July 2005, CCA Support Program, Releases 2.53, 2.54, 3.20, and 3.23 . . . . . . . . . . . . . . . . . . . . . . . xvii

Fourteenth edition, April 2005, CCA Support Program, Releases 2.53, 2.54, and 3.20 . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Thirteenth edition, February 2005, CCA Support Program, Release 2.54 xviii Twelfth edition, December 2004, CCA Support Program, Release 2.53 xviii

How this document is organized . . . . . . . . . . . . . . . . . . xviii Related publications . . . . . . . . . . . . . . . . . . . . . . . xix

Cryptography publications . . . . . . . . . . . . . . . . . . . . xx

Chapter 1. Introduction to programming for the IBM Common Cryptographic Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 1

Available Common Cryptographic Architecture verbs . . . . . . . . . . . 1 Common Cryptographic Architecture functional overview . . . . . . . . . . 1

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

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

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

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

Understanding access control . . . . . . . . . . . . . . . . . . 16 Role-based access control . . . . . . . . . . . . . . . . . . . 16 Initializing and managing the access-control system . . . . . . . . . . 19 Logging on and logging off . . . . . . . . . . . . . . . . . . . 21 Protecting your transaction information . . . . . . . . . . . . . . . 23

Controlling the cryptographic facility . . . . . . . . . . . . . . . . . 23 Multi-coprocessor capabilities . . . . . . . . . . . . . . . . . . . 25

i5/OS multi-coprocessor support . . . . . . . . . . . . . . . . . 25 AIX, Linux, and Windows multi-coprocessor support . . . . . . . . . . 26

Understanding and managing master keys . . . . . . . . . . . . . . . 26 Symmetric and asymmetric master keys . . . . . . . . . . . . . . 27 Establishing master keys . . . . . . . . . . . . . . . . . . . . 27 Master-key considerations with multiple CCA coprocessors . . . . . . . 31

Initializing cryptographic key-storage . . . . . . . . . . . . . . . . . 34 Using the CCA node, access control, and master-key management verbs . . . 34

Access_Control_Initialization (CSUAACI) . . . . . . . . . . . . . . 35 Access_Control_Maintenance (CSUAACM) . . . . . . . . . . . . . 38 Cryptographic_Facility_Control (CSUACFC) . . . . . . . . . . . . . 44

iii

|||

Cryptographic_Facility_Query (CSUACFQ) . . . . . . . . . . . . . . 49 Cryptographic_Resource_Allocate (CSUACRA) . . . . . . . . . . . . 60 Cryptographic_Resource_Deallocate (CSUACRD) . . . . . . . . . . . 62 Key_Storage_Designate (CSUAKSD) . . . . . . . . . . . . . . . 64 Key_Storage_Initialization (CSNBKSI) . . . . . . . . . . . . . . . 66 Logon_Control (CSUALCT) . . . . . . . . . . . . . . . . . . . 68 Master_Key_Distribution (CSUAMKD) . . . . . . . . . . . . . . . 71 Master_Key_Process (CSNBMKP) . . . . . . . . . . . . . . . . . 75 Random_Number_Tests (CSUARNT) . . . . . . . . . . . . . . . . 80

Chapter 3. RSA key-management . . . . . . . . . . . . . . . . . 81 RSA key-management . . . . . . . . . . . . . . . . . . . . . . 81

Key generation . . . . . . . . . . . . . . . . . . . . . . . . 83 Key import . . . . . . . . . . . . . . . . . . . . . . . . . 84 Reenciphering a private key under an updated master key . . . . . . . . 85 Using the PKA keys . . . . . . . . . . . . . . . . . . . . . . 85 Using the private key at multiple nodes . . . . . . . . . . . . . . . 86 Extracting a public key . . . . . . . . . . . . . . . . . . . . . 86 Registering and retaining a public key . . . . . . . . . . . . . . . 86

Using verbs to perform cryptographic functions and obtain key-token data structures . . . . . . . . . . . . . . . . . . . . . . . . . . 86 PKA_Key_Generate (CSNDPKG) . . . . . . . . . . . . . . . . . 87 PKA_Key_Import (CSNDPKI) . . . . . . . . . . . . . . . . . . 91 PKA_Key_Token_Build (CSNDPKB) . . . . . . . . . . . . . . . . 94 PKA_Key_Token_Change (CSNDKTC) . . . . . . . . . . . . . . 100 PKA_Public_Key_Extract (CSNDPKX) . . . . . . . . . . . . . . . 102 PKA_Public_Key_Hash_Register (CSNDPKH) . . . . . . . . . . . . 104 PKA_Public_Key_Register (CSNDPKR) . . . . . . . . . . . . . . 106

Chapter 4. Hashing and digital signatures . . . . . . . . . . . . . 109 Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Digital signatures . . . . . . . . . . . . . . . . . . . . . . . . 111 Verbs used in hashing and digital signature services . . . . . . . . . . 112

Digital_Signature_Generate (CSNDDSG) . . . . . . . . . . . . . . 113 Digital_Signature_Verify (CSNDDSV) . . . . . . . . . . . . . . . 117 MDC_Generate (CSNBMDG) . . . . . . . . . . . . . . . . . . 121 One_Way_Hash (CSNBOWH) . . . . . . . . . . . . . . . . . . 124

Chapter 5. DES key-management . . . . . . . . . . . . . . . . . 127 CCA DES-key management . . . . . . . . . . . . . . . . . . . . 129 Control vectors, key types, and key-usage restrictions . . . . . . . . . . 131

Checking a control vector before processing a cryptographic command 131 Key types . . . . . . . . . . . . . . . . . . . . . . . . . 132 Key-usage restrictions . . . . . . . . . . . . . . . . . . . . . 133

Key tokens, key labels, and key identifiers . . . . . . . . . . . . . . 139 Key tokens . . . . . . . . . . . . . . . . . . . . . . . . . 139 Key labels . . . . . . . . . . . . . . . . . . . . . . . . . 141 Key identifiers . . . . . . . . . . . . . . . . . . . . . . . . 142

Key-processing and key-storage verbs . . . . . . . . . . . . . . . . 142 Installing and verifying keys . . . . . . . . . . . . . . . . . . . 143 Generating keys . . . . . . . . . . . . . . . . . . . . . . . 144 Exporting and importing keys, symmetric techniques . . . . . . . . . 145 Exporting and importing keys, asymmetric techniques . . . . . . . . . 146 Diversifying keys . . . . . . . . . . . . . . . . . . . . . . . 147 Storing keys in DES key-storage . . . . . . . . . . . . . . . . . 148

Improved remote key distribution . . . . . . . . . . . . . . . . . . 148

iv CCA Basic Services Reference and Guide for the IBM 4758 PCI and IBM 4764 PCI-X Cryptographic Coprocessors

Remote key-loading . . . . . . . . . . . . . . . . . . . . . 148 Trusted block . . . . . . . . . . . . . . . . . . . . . . . . 149 Changes to the CCA API . . . . . . . . . . . . . . . . . . . . 153 The RKX key-token . . . . . . . . . . . . . . . . . . . . . . 154 Using trusted blocks . . . . . . . . . . . . . . . . . . . . . 155 Remote key distribution scenario . . . . . . . . . . . . . . . . . 159 Remote key distribution benefits . . . . . . . . . . . . . . . . . 167

Security precautions . . . . . . . . . . . . . . . . . . . . . . 168 CCA DES key-management verbs . . . . . . . . . . . . . . . . . 168

Clear_Key_Import (CSNBCKI) . . . . . . . . . . . . . . . . . . 169 Control_Vector_Generate (CSNBCVG) . . . . . . . . . . . . . . . 171 Control_Vector_Translate (CSNBCVT) . . . . . . . . . . . . . . . 173 Cryptographic_Variable_Encipher (CSNBCVE) . . . . . . . . . . . . 176 Data_Key_Export (CSNBDKX) . . . . . . . . . . . . . . . . . . 178 Data_Key_Import (CSNBDKM) . . . . . . . . . . . . . . . . . 180 Diversified_Key_Generate (CSNBDKG) . . . . . . . . . . . . . . 182 Key_Encryption_Translate (CSNBKET) . . . . . . . . . . . . . . 189 Key_Export (CSNBKEX) . . . . . . . . . . . . . . . . . . . . 192 Key_Generate (CSNBKGN) . . . . . . . . . . . . . . . . . . . 194 Key_Import (CSNBKIM) . . . . . . . . . . . . . . . . . . . . 201 Key_Part_Import (CSNBKPI) . . . . . . . . . . . . . . . . . . 204 Key_Test (CSNBKYT) . . . . . . . . . . . . . . . . . . . . . 208 Key_Test_Extended (CSNBKYTX) . . . . . . . . . . . . . . . . 212 Key_Token_Build (CSNBKTB) . . . . . . . . . . . . . . . . . . 216 Key_Token_Change (CSNBKTC) . . . . . . . . . . . . . . . . . 219 Key_Token_Parse (CSNBKTP) . . . . . . . . . . . . .