Bs Latest Edition

CCA Basic Services Reference and Guide
for the IBM 4765 PCIe and IBM 4764

PCI-X Cryptographic Coprocessors
Releases 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25
Twenty-fourth edition (October 2011)
| This edition describes the IBM Common Cryptographic Architecture (CCA) Basic Services API for Releases 4.2, 4.1,
| 4.0, 3.60, 3.30, 3.27, and 3.25.
Copyright International Business Machines Corporation 2007, 2011.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Summary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
| Twenty-fourth edition, September 2011, CCA Support Program, Releases 4.2, 4.1, 4.0, 3.60, 3.30,
| 3.27, and 3.25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Twenty-third edition, June 2011, CCA Support Program, Releases 4.1, 4.0, 3.60, 3.30, 3.27, and
3.25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Twenty-second edition, February 2011, CCA Support Program, Releases 4.1, 4.0, 3.60, 3.30, 3.27,
and 3.25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Twenty-first edition, September 2010, CCA Support Program, Releases 4.1, 4.0, 3.60, 3.30, 3.27,
and 3.25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Twentieth edition, April 2010, CCA Support Program, Releases 3.20, 3.23, 3.24, 3.25, 3.27, 3.30
and 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Nineteenth edition, September 2008, CCA Support Program, Releases 3.20, 3.23, 3.24, 3.25, 3.27,
and 3.30 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Eighteenth edition, October 2006, CCA Support Program, Releases 3.20, 3.23, 3.24, 3.25, and
3.27 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Seventeenth edition, May 2006, CCA Support Program, Releases 3.20, 3.23, 3.24, and 3.25 xxvii
How this document is organized . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Cryptography publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
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 . . . . . . . . . . . . . . . . . . . . . . 6 . .
Verbs, variables, and parameters . . . . . . . . . . . . . . . . . . . . . . . . 7 . .
Commonly encountered parameters . . . . . . . . . . . . . . . . . . . . . . . 9 . .
API verb organization in the remainder of this document . . . . . . . . . . . . . . . . . . 11
Chapter 2. CCA node management and access control . . . . . . . . . . . . . . . . . 13

Using CCA access-control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Understanding access control . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Role-based access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Initializing and managing the access-control system . . . . . . . . . . . . . . . . . . . 16
Logging on and logging off . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Protecting your transaction information . . . . . . . . . . . . . . . . . . . . . . . 19
Controlling the cryptographic facility . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Multi-coprocessor capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
IBM i multi-coprocessor support . . . . . . . . . . . . . . . . . . . . . . . . . . 26
AIX, Linux, and Windows multi-coprocessor support. . . . . . . . . . . . . . . . . . . 26
Understanding and managing master keys . . . . . . . . . . . . . . . . . . . . . . . 27
Symmetric and asymmetric master keys . . . . . . . . . . . . . . . . . . . . . . . 27
Establishing master keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Master-key considerations with multiple CCA coprocessors . . . . . . . . . . . . . . . . 31
Initializing cryptographic key-storage . . . . . . . . . . . . . . . . . . . . . . . . . 33
Testing the random-number generator and known-answer tests . . . . . . . . . . . . . . . 34
Using the CCA node, access control, and master-key management verbs. . . . . . . . . . . . 34
iii
Access_Control_Initialization (CSUAACI) . . . . . . . . . . . . . . . . . . . . . . . 35
Access_Control_Maintenance (CSUAACM) . . . . . . . . . . . . . . . . . . . . . . 38
Cryptographic_Facility_Control (CSUACFC) . . . . . . . . . . . . . . . . . . . . . . 42
Cryptographic_Facility_Query (CSUACFQ) . . . . . . . . . . . . . . . . . . . . . . 48
Cryptographic_Facility_Version (CSUACFV) . . . . . . . . . . . . . . . . . . . . . . 58
Cryptographic_Resource_Allocate (CSUACRA) . . . . . . . . . . . . . . . . . . . . 59
Cryptographic_Resource_Deallocate (CSUACRD) . . . . . . . . . . . . . . . . . . . 61
Key_Storage_Designate (CSUAKSD) . . . . . . . . . . . . . . . . . . . . . . . . 63
Key_Storage_Initialization (CSNBKSI) . . . . . . . . . . . . . . . . . . . . . . . . 65
Logon_Control (CSUALCT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Master_Key_Distribution (CSUAMKD) . . . . . . . . . . . . . . . . . . . . . . . . 70
Master_Key_Process (CSNBMKP) . . . . . . . . . . . . . . . . . . . . . . . . . 74
Random_Number_Tests (CSUARNT) . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 3. PKA key-management . . . . . . . . . . . . . . . . . . . . . . . . . . 81

PKA key-management services . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 an RSA 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) . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
PKA_Key_Token_Build (CSNDPKB) . . . . . . . . . . . . . . . . . . . . . . . . 95
PKA_Key_Token_Change (CSNDKTC) . . . . . . . . . . . . . . . . . . . . . . . 103
PKA_Key_Translate (CSNDPKT) . . . . . . . . . . . . . . . . . . . . . . . . . 105
PKA_Public_Key_Extract (CSNDPKX) . . . . . . . . . . . . . . . . . . . . . . . 108
PKA_Public_Key_Hash_Register (CSNDPKH) . . . . . . . . . . . . . . . . . . . . 110
PKA_Public_Key_Register (CSNDPKR) . . . . . . . . . . . . . . . . . . . . . . . 112
Chapter 4. Hashing and digital signatures . . . . . . . . . . . . . . . . . . . . . . 115

Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Digital signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Verbs used in hashing and digital signature services . . . . . . . . . . . . . . . . . . . 117
Digital_Signature_Generate (CSNDDSG) . . . . . . . . . . . . . . . . . . . . . . 118
Digital_Signature_Verify (CSNDDSV) . . . . . . . . . . . . . . . . . . . . . . . . 122
MDC_Generate (CSNBMDG) . . . . . . . . . . . . . . . . . . . . . . . . . . 126
One_Way_Hash (CSNBOWH) . . . . . . . . . . . . . . . . . . . . . . . . . . 134
| Chapter 5. AES, DES, and HMAC symmetric-key management . . . . . . . . . . . . . . 137

| AES, DES, and HMAC key-management . . . . . . . . . . . . . . . . . . . . . . . 140
Triple-DES key wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
| Control vectors, key types, key-usage, and key-management restrictions . . . . . . . . . . . 147
Checking a DES control vector before processing a cryptographic command . . . . . . . . . 148
| AES, DES, and HMAC key types . . . . . . . . . . . . . . . . . . . . . . . . . 149
| AES and HMAC key usage and key management restrictions. . . . . . . . . . . . . . . 152
DES key usage restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Key tokens, key labels, and key identifiers . . . . . . . . . . . . . . . . . . . . . . . 164
AES, DES, and variable-length symmetric key tokens. . . . . . . . . . . . . . . . . . 165
Key labels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Key identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Key-processing and key-storage verbs for symmetric keys . . . . . . . . . . . . . . . . . 170
Installing and verifying symmetric keys . . . . . . . . . . . . . . . . . . . . . . . 172
iv CCA Basic Services October 14, 2011

Generating symmetric keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Exporting and importing DES keys, symmetric techniques . . . . . . . . . . . . . . . . 175
Exporting and importing symmetric keys, asymmetric techniques . . . . . . . . . . . . . 176
Diversifying DES keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Storing keys in AES and DES key-storage . . . . . . . . . . . . . . . . . . . . . . 178
Improved remote key distribution . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Remote key-loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Trusted block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Changes to the CCA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
The RKX key-token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Using trusted blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Remote key distribution scenario . . . . . . . . . . . . . . . . . . . . . . . . . 189
Remote key distribution benefits . . . . . . . . . . . . . . . . . . . . . . . . . 197
Security precautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
AES, DES, and HMAC key-management verbs . . . . . . . . . . . . . . . . . . . . . 197
Clear_Key_Import (CSNBCKI) . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Control_Vector_Generate (CSNBCVG) . . . . . . . . . . . . . . . . . . . . . . . 200
Control_Vector_Translate (CSNBCVT) . . . . . . . . . . . . . . . . . . . . . . . 203
Cryptographic_Variable_Encipher (CSNBCVE) . . . . . . . . . . . . . . . . . . . . 205
Data_Key_Export (CSNBDKX) . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Data_Key_Import (CSNBDKM) . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Diversified_Key_Generate (CSNBDKG) . . . . . . . . . . . . . . . . . . . . . . . 211
| EC_Diffie-Hellman (CSNDEDH) . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Key_Encryption_Translate (CSNBKET) . . . . . . . . . . . . . . . . . . . . . . . 224
Key_Export (CSNBKEX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Key_Generate (CSNBKGN) . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Key_Generate2 (CSNBKGN2) . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Key_Import (CSNBKIM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Key_Part_Import (CSNBKPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Key_Part_Import2 (CSNBKPI2) . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Key_Test (CSNBKYT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Key_Test2 (CSNBKYT2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Key_Test_Extended (CSNBKYTX) . . . . . . . . . . . . . . . . . . . . . . . . . 265
Key_Token_Build (CSNBKTB) . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Key_Token_Build2 (CSNBKTB2) . . . . . . . . . . . . . . . . . . . . . . . . . 275
Key_Token_Change (CSNBKTC) . . . . . . . . . . . . . . . . . . . . . . . . . 279
Key_Token_Change2 (CSNBKTC2) . . . . . . . . . . . . . . . . . . . . . . . . 281
Key_Token_Parse (CSNBKTP) . . . . . . . . . . . . . . . . . . . . . . . . . . 283
| Key_Token_Parse2 (CSNBKTP2) . . . . . . . . . . . . . . . . . . . . . . . . . 286
Key_Translate (CSNBKTR) . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Key_Translate2 (CSNBKTR2) . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Multiple_Clear_Key_Import (CSNBCKM) . . . . . . . . . . . . . . . . . . . . . . 301
PKA_Decrypt (CSNDPKD). . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
PKA_Encrypt (CSNDPKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Prohibit_Export (CSNBPEX) . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Prohibit_Export_Extended (CSNBPEXX) . . . . . . . . . . . . . . . . . . . . . . 311
Random_Number_Generate (CSNBRNG) . . . . . . . . . . . . . . . . . . . . . . 313
Random_Number_Generate_Long (CSNBRNGL) . . . . . . . . . . . . . . . . . . . 315
Remote_Key_Export (CSNDRKX) . . . . . . . . . . . . . . . . . . . . . . . . . 317
Restrict_Key_Attribute (CSNBRKA) . . . . . . . . . . . . . . . . . . . . . . . . 328
Symmetric_Key_Export (CSNDSYX) . . . . . . . . . . . . . . . . . . . . . . . . 333
Symmetric_Key_Generate (CSNDSYG) . . . . . . . . . . . . . . . . . . . . . . . 339
Symmetric_Key_Import (CSNDSYI) . . . . . . . . . . . . . . . . . . . . . . . . 345
Symmetric_Key_Import2 (CSNDSYI2) . . . . . . . . . . . . . . . . . . . . . . . 350
Trusted_Block_Create (CSNDTBC) . . . . . . . . . . . . . . . . . . . . . . . . 353
Contents v
Chapter 6. Data confidentiality and data integrity . . . . . . . . . . . . . . . . . . . 357
Encryption and message authentication codes . . . . . . . . . . . . . . . . . . . . . 357
Ensuring data confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Ensuring data integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Data confidentiality and data integrity verbs . . . . . . . . . . . . . . . . . . . . . . 359
Decipher (CSNBDEC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Encipher (CSNBENC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
HMAC_Generate (CSNBHMG) . . . . . . . . . . . . . . . . . . . . . . . . . . 366
HMAC_Verify (CSNBHMV) . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
MAC_Generate (CSNBMGN). . . . . . . . . . . . . . . . . . . . . . . . . . . 372
MAC_Verify (CSNBMVR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Symmetric_Algorithm_Decipher (CSNBSAD) . . . . . . . . . . . . . . . . . . . . . 378
Symmetric_Algorithm_Encipher (CSNBSAE) . . . . . . . . . . . . . . . . . . . . . 383
Chapter 7. Key-storage mechanisms . . . . . . . . . . . . . . . . . . . . . . . . 389

Key labels and key-storage management . . . . . . . . . . . . . . . . . . . . . . . 390
Key-label content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Key-storage verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
AES_Key_Record_Create (CSNBAKRC) . . . . . . . . . . . . . . . . . . . . . . 392
AES_Key_Record_Delete (CSNBAKRD) . . . . . . . . . . . . . . . . . . . . . . 394
AES_Key_Record_List (CSNBAKRL) . . . . . . . . . . . . . . . . . . . . . . . . 396
AES_Key_Record_Read (CSNBAKRR) . . . . . . . . . . . . . . . . . . . . . . . 398
AES_Key_Record_Write (CSNBAKRW) . . . . . . . . . . . . . . . . . . . . . . . 400
DES_Key_Record_Create (CSNBKRC) . . . . . . . . . . . . . . . . . . . . . . . 402
DES_Key_Record_Delete (CSNBKRD) . . . . . . . . . . . . . . . . . . . . . . . 404
DES_Key_Record_List (CSNBKRL) . . . . . . . . . . . . . . . . . . . . . . . . 406
DES_Key_Record_Read (CSNBKRR) . . . . . . . . . . . . . . . . . . . . . . . 408
DES_Key_Record_Write (CSNBKRW) . . . . . . . . . . . . . . . . . . . . . . . 409
PKA_Key_Record_Create (CSNDKRC) . . . . . . . . . . . . . . . . . . . . . . . 410
PKA_Key_Record_Delete (CSNDKRD) . . . . . . . . . . . . . . . . . . . . . . . 412
PKA_Key_Record_List (CSNDKRL) . . . . . . . . . . . . . . . . . . . . . . . . 414
PKA_Key_Record_Read (CSNDKRR) . . . . . . . . . . . . . . . . . . . . . . . 416
PKA_Key_Record_Write (CSNDKRW) . . . . . . . . . . . . . . . . . . . . . . . 418
Retained_Key_Delete (CSNDRKD) . . . . . . . . . . . . . . . . . . . . . . . . 420
Retained_Key_List (CSNDRKL) . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Chapter 8. Financial services support . . . . . . . . . . . . . . . . . . . . . . . 425

Processing financial PINs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
PIN-verb summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
PIN-calculation method and PIN-block format summary . . . . . . . . . . . . . . . . . 430
Providing security for PINs . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Supporting multiple PIN calculation methods . . . . . . . . . . . . . . . . . . . . . 431
Supporting multiple PIN-block formats and PIN-extraction methods . . . . . . . . . . . . . 433
Generating and verifying card security codes . . . . . . . . . . . . . . . . . . . . . . 436
Working with EMV smart cards . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Financial services support verbs . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Clear_PIN_Encrypt (CSNBCPE) . . . . . . . . . . . . . . . . . . . . . . . . . 438
Clear_PIN_Generate (CSNBPGN) . . . . . . . . . . . . . . . . . . . . . . . . . 441
Clear_PIN_Generate_Alternate (CSNBCPA) . . . . . . . . . . . . . . . . . . . . . 444
CVV_Generate (CSNBCSG) . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
| CVV_Key_Combine (CSNBCKC) . . . . . . . . . . . . . . . . . . . . . . . . . 452
CVV_Verify (CSNBCSV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Encrypted_PIN_Generate (CSNBEPG) . . . . . . . . . . . . . . . . . . . . . . . 459
Encrypted_PIN_Translate (CSNBPTR) . . . . . . . . . . . . . . . . . . . . . . . 463
Encrypted_PIN_Verify (CSNBPVR) . . . . . . . . . . . . . . . . . . . . . . . . 469
PIN_Change/Unblock (CSNBPCU). . . . . . . . . . . . . . . . . . . . . . . . . 475
vi CCA Basic Services October 14, 2011

Secure_Messaging_for_Keys (CSNBSKY) . . . . . . . . . . . . . . . . . . . . . . 481
Secure_Messaging_for_PINs (CSNBSPN) . . . . . . . . . . . . . . . . . . . . . . 484
SET_Block_Compose (CSNDSBC) . . . . . . . . . . . . . . . . . . . . . . . . 489
SET_Block_Decompose (CSNDSBD) . . . . . . . . . . . . . . . . . . . . . . . 492
Transaction_Validation (CSNBTRV) . . . . . . . . . . . . . . . . . . . . . . . . 496
| Chapter 9. TR-31 symmetric-key management . . . . . . . . . . . . . . . . . . . . 499

| TR-31 symmetric key management verbs . . . . . . . . . . . . . . . . . . . . . . . 500
| Key_Export_to_TR31 (CSNBT31X) . . . . . . . . . . . . . . . . . . . . . . . . 501
| TR31_Key_Import (CSNBT31I) . . . . . . . . . . . . . . . . . . . . . . . . . . 528
| TR31_Key_Token_Parse (CSNBT31P) . . . . . . . . . . . . . . . . . . . . . . . 551
| TR31_Optional_Data_Build (CSNBT31O) . . . . . . . . . . . . . . . . . . . . . . 555
| TR31_Optional_Data_Read (CSNBT31R) . . . . . . . . . . . . . . . . . . . . . . 558
Appendix A. Return codes and reason codes . . . . . . . . . . . . . . . . . . . . 561

Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Reason codes that accompany return code 0. . . . . . . . . . . . . . . . . . . . . 562
Reason codes that accompany return code 12 . . . . . . . . . . . . . . . . . . . . 573
Reason codes that accompany return code 16 . . . . . . . . . . . . . . . . . . . . 574
Appendix B. Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

Key tokens and trusted blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Master-key verification pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Token-validation value and record-validation value . . . . . . . . . . . . . . . . . . . 578
Null key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Internal fixed-length AES key tokens . . . . . . . . . . . . . . . . . . . . . . . . 578
Fixed-length DES key tokens. . . . . . . . . . . . . . . . . . . . . . . . . . . 580
External RKX DES key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . 583
PKA key tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Trusted blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Variable-length symmetric key-token . . . . . . . . . . . . . . . . . . . . . . . . 614
| TR-31 optional block data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
ACI smart card formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
Format 1 Visa proprietary format. . . . . . . . . . . . . . . . . . . . . . . . . 631
Format 2 Common personalization for ModulusExponent format . . . . . . . . . . . . 632
Format 3 Common personalization for CRT format . . . . . . . . . . . . . . . . . . 632
Chaining-vector work areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
Key-storage datasets and records . . . . . . . . . . . . . . . . . . . . . . . . . . 633
Key-record-list datasets and records . . . . . . . . . . . . . . . . . . . . . . . . . 637
Access-control data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
Role structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
Profile structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Examples of the access-control data structures . . . . . . . . . . . . . . . . . . . . 646
Master-key shares data formats. . . . . . . . . . . . . . . . . . . . . . . . . . . 649
Distributed function control vector . . . . . . . . . . . . . . . . . . . . . . . . . . 650
Appendix C. CCA control-vector definitions and key encryption . . . . . . . . . . . . . 655

Understanding DES control-vector values . . . . . . . . . . . . . . . . . . . . . . . 655
Key-form bits, 'fff' and 'FFF' . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
Specifying a control-vector-base value . . . . . . . . . . . . . . . . . . . . . . . . 661
Changing control vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
Changing control vectors with the pre-exclusive-OR technique . . . . . . . . . . . . . . 665
Changing control vectors with the Control_Vector_Translate verb . . . . . . . . . . . . . 667
Contents vii
Changing control vectors with the Remote_Key_Export verb . . . . . . . . . . . . . . . 671
Understanding DES and RSA key encryption and decryption processes . . . . . . . . . . . . 671
DES key encryption and decryption processes . . . . . . . . . . . . . . . . . . . . 671
RSA private-key encryption and decryption process . . . . . . . . . . . . . . . . . . 671
PKA92 key format and encryption process . . . . . . . . . . . . . . . . . . . . . . 674
Encrypting a key-encrypting key in the NL-EPP-5 format . . . . . . . . . . . . . . . . 675
Appendix D. Algorithms and processes . . . . . . . . . . . . . . . . . . . . . . . 677

Cryptographic key-verification techniques . . . . . . . . . . . . . . . . . . . . . . . 677
Master-key verification algorithms . . . . . . . . . . . . . . . . . . . . . . . . . 677
CCA DES-key verification algorithm . . . . . . . . . . . . . . . . . . . . . . . . 678
| Encrypt zeros AES-key verification algorithm . . . . . . . . . . . . . . . . . . . . . 679
Encrypt zeros DES-key verification algorithm . . . . . . . . . . . . . . . . . . . . . 679
Modification Detection Code calculation . . . . . . . . . . . . . . . . . . . . . . . . 679
Ciphering methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
General data-encryption processes . . . . . . . . . . . . . . . . . . . . . . . . 682
Triple-DES ciphering algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
MAC calculation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
ANS X9.9 Option 1 MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
ANS X9.19 Optional Procedure MAC . . . . . . . . . . . . . . . . . . . . . . . . 690
EMV MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
ISO 16609 Triple-DES MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
| Keyed-hash MAC (HMAC). . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
RSA key-pair generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Passphrase verification protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Design criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Description of the protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Master-key-splitting algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Formatting hashes and keys in public-key cryptography . . . . . . . . . . . . . . . . . . 694
ANS X9.31 hash format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
PKCS #1 hash formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
Appendix E. Financial system verbs calculation methods and data formats . . . . . . . . . 697
PIN calculation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
IBM 3624 PIN-calculation method . . . . . . . . . . . . . . . . . . . . . . . . . 698
IBM 3624 PIN-offset calculation method. . . . . . . . . . . . . . . . . . . . . . . 698
Netherlands PIN-1 calculation method . . . . . . . . . . . . . . . . . . . . . . . 699
IBM German Bank Pool Institution PIN-calculation method . . . . . . . . . . . . . . . . 699
Visa PIN-validation value PIN-calculation method . . . . . . . . . . . . . . . . . . . 700
InterBank PIN-calculation method . . . . . . . . . . . . . . . . . . . . . . . . . 700
PIN-block formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
IBM 3624 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
ISO-0 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
Derived unique-key-per-transaction calculation method . . . . . . . . . . . . . . . . . . 704
Deriving an ANS X9.24 unique-key-per-transaction key . . . . . . . . . . . . . . . . . 704
Performing the special encryption and special decryption processes . . . . . . . . . . . . 705
CVV and CVC card-verification method . . . . . . . . . . . . . . . . . . . . . . . . 706
Visa and EMV-related smart card formats and processes . . . . . . . . . . . . . . . . . 707
Deriving the smart-card-specific authentication code . . . . . . . . . . . . . . . . . . 708
Constructing the PIN-block for transporting an EMV smart-card PIN . . . . . . . . . . . . 708
Deriving the CCA TDES-XOR session key . . . . . . . . . . . . . . . . . . . . . . 708
Deriving of the EMV TDESEMVn tree-based session key . . . . . . . . . . . . . . . . 709
PIN-block self-encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
viii CCA Basic Services October 14, 2011

Appendix F. Verb list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Appendix G. Access-control-point codes . . . . . . . . . . . . . . . . . . . . . . 715
Appendix H. Observations on secure operations . . . . . . . . . . . . . . . . . . . 725

Ensuring code levels match and IBM CCA code is installed . . . . . . . . . . . . . . . . 725
Managing access controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Locking the access-control system. . . . . . . . . . . . . . . . . . . . . . . . . 725
Changing a passphrase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Defining roles and profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Protecting cryptographic keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
CCA asymmetric DES keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Clear key parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Key export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
Key unwrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
Clear-key operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
DES replicated keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
RSA keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
PIN data considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Validating coprocessor status data . . . . . . . . . . . . . . . . . . . . . . . . . . 732
RS-232 port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Master-key cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Sample access-control regimes . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Digital-signing server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Secured code-signing node . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Appendix I. Java Native Interface . . . . . . . . . . . . . . . . . . . . . . . . . 743
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
IBM agreement for licensed internal code . . . . . . . . . . . . . . . . . . . . . . . 758
Actions you must not take . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
Contents ix
x CCA Basic Services October 14, 2011
Figures
1. CCA security API, access layer, and cryptographic engine . . . . . . . . . . . . . . . . 2
2. Coprocessor-to-coprocessor DES or RSA master-key cloning . . . . . . . . . . . . . . 30
| 3. PKA96 verbs with key-token flow . . . . . . . . . . . . . . . . . . . . . . . . . 82
4. Default key-wrapping method configuration . . . . . . . . . . . . . . . . . . . . . 144
5. Flow of cryptographic command processing in a cryptographic facility . . . . . . . . . . . 149
| 6. Key_Token_Build2 keyword combinations for AES CIPHER keys. . . . . . . . . . . . . 154
| 7. Key_Token_Build2 keyword combinations for AES EXPORTER keys . . . . . . . . . . . 155
| 8. Key_Token_Build2 keyword combinations for AES IMPORTER keys . . . . . . . . . . . 156
| 9. Key_Token_Build2 keyword combinations for HMAC MAC keys . . . . . . . . . . . . . 157
| 10. Control_Vector_Generate and Key_Token_Build CV keyword combinations for fixed-length DES
| key tokens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
| 11. AES and DES fixed-length key-token contents . . . . . . . . . . . . . . . . . . . 165
| 12. Use of fixed-length AES key tokens and key labels . . . . . . . . . . . . . . . . . . 167
13. Use of fixed-length DES key tokens and key labels. . . . . . . . . . . . . . . . . . 168
| 14. Key-processing and key-storage verbs for keys in fixed-length AES key tokens . . . . . . . 170
15. Key-processing and key-storage verbs for keys in fixed-length DES key tokens . . . . . . . 172
16. DES key exporting and key importing . . . . . . . . . . . . . . . . . . . . . . . 176
17. Overview of trusted block contents . . . . . . . . . . . . . . . . . . . . . . . . 180
18. Simplified RKX key-token structure. . . . . . . . . . . . . . . . . . . . . . . . 184
19. Trusted block creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
20. Exporting DES keys using a trusted block . . . . . . . . . . . . . . . . . . . . . 185
21. Generating DES keys using a trusted block . . . . . . . . . . . . . . . . . . . . 188
22. Typical flow of verbs for remote key export . . . . . . . . . . . . . . . . . . . . . 189
23. Financial PIN verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
24. Access-control system role structure . . . . . . . . . . . . . . . . . . . . . . . 639
25. Aggregate role structure with header . . . . . . . . . . . . . . . . . . . . . . . 640
26. Access-control-point structure. . . . . . . . . . . . . . . . . . . . . . . . . . 641
27. Access-control system profile structure . . . . . . . . . . . . . . . . . . . . . . 642
28. Format of profile activation date and expiration date . . . . . . . . . . . . . . . . . 642
29. Aggregate profile structure with header . . . . . . . . . . . . . . . . . . . . . . 643
30. Layout of the authentication data field. . . . . . . . . . . . . . . . . . . . . . . 644
31. Passphrase authentication data structure example . . . . . . . . . . . . . . . . . . 646
32. User profile data structure example . . . . . . . . . . . . . . . . . . . . . . . 646
33. Aggregate profile structure example . . . . . . . . . . . . . . . . . . . . . . . 647
34. Access-control-point list example . . . . . . . . . . . . . . . . . . . . . . . . 647
35. Role data structure example . . . . . . . . . . . . . . . . . . . . . . . . . . 648
36. Aggregate role data structure example . . . . . . . . . . . . . . . . . . . . . . 649
37. DES control-vector-base bit map . . . . . . . . . . . . . . . . . . . . . . . . 658
38. Exchanging a key with a non-control-vector system. . . . . . . . . . . . . . . . . . 666
39. Control_Vector_Translate verb mask_array processing . . . . . . . . . . . . . . . . 669
40. Control_Vector_Translate verb process . . . . . . . . . . . . . . . . . . . . . . 670
41. Multiply-enciphering and multiply-deciphering DES and RSA keys . . . . . . . . . . . . 673
42. Triple-DES data encryption and decryption . . . . . . . . . . . . . . . . . . . . . 682
43. Enciphering using the NIST SP 800-38A CBC method . . . . . . . . . . . . . . . . 683
44. Deciphering using the CBC method . . . . . . . . . . . . . . . . . . . . . . . 684
45. Enciphering using the ANS X9.23 method . . . . . . . . . . . . . . . . . . . . . 685
46. Deciphering using the ANS X9.23 method . . . . . . . . . . . . . . . . . . . . . 685
47. Triple-DES CBC encryption process . . . . . . . . . . . . . . . . . . . . . . . 686
48. Triple-DES CBC decryption process . . . . . . . . . . . . . . . . . . . . . . . 687
49. EDE algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
50. DED process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
51. MAC calculation method . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
52. Example of logon key computation . . . . . . . . . . . . . . . . . . . . . . . . 692
xi
53. 3624 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
54. ISO-0 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
58. CVV track 2 algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
xii CCA Basic Services October 14, 2011

Tables
| 1. Coprocessor product by platform and CCA Release. . . . . . . . . . . . . . . . . . xvii
| 2. Software offering by CCA Release . . . . . . . . . . . . . . . . . . . . . . . . xviii
3. Verb parameter format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. CCA node, access control, and master-key management verbs. . . . . . . . . . . . . . 13
5. Summary of available CCA coprocessor information . . . . . . . . . . . . . . . . . . 21
6. Key-storage location by operating system . . . . . . . . . . . . . . . . . . . . . . 25
7. Cryptographic_Facility_Query information returned in the rule array . . . . . . . . . . . . 50
| 8. Cryptographic_Facility_Query information returned in the verb_data variable . . . . . . . . . 57
9. Questionable DES keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
10. Public administration services . . . . . . . . . . . . . . . . . . . . . . . . . . 81
11. PKA_Key_Token_Build key-values-structure contents, RSA keys . . . . . . . . . . . . . 98
12. PKA_Key_Token_Build key-values-structure contents, ECC keys . . . . . . . . . . . . . 99
13. Sample key-values structure data for RSA keys . . . . . . . . . . . . . . . . . . . 101
14. Sample key-values structure data for ECC keys (Release 4.1 or later). . . . . . . . . . . 101
15. Hashing and digital signature services . . . . . . . . . . . . . . . . . . . . . . 115
16. Basic AES and DES key-management verbs . . . . . . . . . . . . . . . . . . . . 137
17. DES translation control rule-array keyword . . . . . . . . . . . . . . . . . . . . . 145
18. DES key-wrapping method rule-array keywords . . . . . . . . . . . . . . . . . . . 145
19. Summary of verbs and DES key-wrapping method selection criteria . . . . . . . . . . . 147
| 20. AES key types and verb usage (Release 3.30 or later) . . . . . . . . . . . . . . . . 149
21. HMAC key types and verb usage (Release 4.1 or later) . . . . . . . . . . . . . . . . 150
22. DES key types and verb usage . . . . . . . . . . . . . . . . . . . . . . . . . 150
| 23. Key_Token_Build2 variable-length AES and HMAC key-token keywords . . . . . . . . . . 157
24. DES control vector key-subtype and key-usage keywords . . . . . . . . . . . . . . . 162
25. Sample rule section GENERAT1 . . . . . . . . . . . . . . . . . . . . . . . . 191
26. Verb inputs and outputs for sample rule GENERAT1 . . . . . . . . . . . . . . . . . 191
27. Sample rule section GENERAT2 . . . . . . . . . . . . . . . . . . . . . . . . 192
28. Verb inputs and outputs for sample rule GENERAT2 . . . . . . . . . . . . . . . . . 192
29. Sample rule section EXPORT1 . . . . . . . . . . . . . . . . . . . . . . . . . 193
30. Verb inputs and outputs for sample rule EXPORT1 . . . . . . . . . . . . . . . . . . 194
35. Key_form keywords and their usage . . . . . . . . . . . . . . . . . . . . . . . 231
36. Key_length values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
37. Key_type and key_form keywords for one key . . . . . . . . . . . . . . . . . . . 236
38. Key_type and key_form keywords for a DES key pair . . . . . . . . . . . . . . . . . 236
39. Key lengths by AES and DES key-type . . . . . . . . . . . . . . . . . . . . . . 238
| 40. Key type and key form keywords for one AES or HMAC key . . . . . . . . . . . . . . 244
| 41. Key type and key form keywords for a pair of AES or HMAC keys . . . . . . . . . . . . 244
| 42. Key_Test GENERATE outputs and VERIFY inputs . . . . . . . . . . . . . . . . . . 257
| 43. Key_Test_Extended GENERATE outputs and VERIFY inputs . . . . . . . . . . . . . . 266
| 44. Key_Translate2 key tokens based on algorithm and reencipherment keywords . . . . . . . 297
45. Parameters format for public-key certificate. . . . . . . . . . . . . . . . . . . . . 324
| 46. Symmetric_Key_Export source key tokens . . . . . . . . . . . . . . . . . . . . . 333
| 47. Symmetric_Key_Export key formatting methods by source key-token . . . . . . . . . . . 334
48. Data confidentiality and data integrity verbs . . . . . . . . . . . . . . . . . . . . 357
49. Key-storage-record services . . . . . . . . . . . . . . . . . . . . . . . . . . 389
50. Financial services support verbs. . . . . . . . . . . . . . . . . . . . . . . . . 425
51. PIN verb, PIN-calculation method, and PIN-block format support summary . . . . . . . . . 430
52. PIN calculation methods and keywords . . . . . . . . . . . . . . . . . . . . . . 432
53. PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
xiii
54. Pad-digit specification by PIN-block format . . . . . . . . . . . . . . . . . . . . . 434
55. PIN-extraction method keywords by PIN-block format . . . . . . . . . . . . . . . . . 435
56. Verbs affected by enhanced PIN security mode . . . . . . . . . . . . . . . . . . . 436
57. Clear_PIN_Generate_Alternate rule_array keywords (first element) . . . . . . . . . . . . 446
58. Clear_PIN_Generate_Alternate rule_array keywords (second element) . . . . . . . . . . 447
| 59. Key-wrapping matrix for CVV_Key_Combine . . . . . . . . . . . . . . . . . . . . 454
60. Encrypted_PIN_Translate PIN-extraction method rule_array keywords . . . . . . . . . . . 466
61. Encrypted_PIN_Verify PIN-extraction method rule_array keywords . . . . . . . . . . . . 472
| 62. TR-31 symmetric key management verbs . . . . . . . . . . . . . . . . . . . . . 500
| 63. Export translation table for a TR-31 BDK base derivation key (BDK) . . . . . . . . . . . 508
| 64. Export translation table for a TR-31 CVK card verification key (CVK) . . . . . . . . . . . 509
| 65. Export translation table for a TR-31 data encryption key (ENC) . . . . . . . . . . . . . 511
| 66. Export translation table for a TR-31 key encryption or wrapping, or key block protection key
| (KEK or KEK-WRAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
| 67. Export translation table for a TR-31 ISO MAC algorithm key (ISOMACn) . . . . . . . . . . 513
| 68. Export translation table for a TR-31 PIN encryption or PIN verification key (PINENC, PINVO,
| PINV3624, VISAPVV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
| 69. Export translation table for a TR-31 EMV/chip issuer master-key key (DKYGENKY, DATA) 520
| 70. Import translation table for a TR-31 BDK base derivation key (usage "B0") . . . . . . . . . 533
| 71. Import translation table for a TR-31 CVK card verification key (usage "C0") . . . . . . . . . 533
| 72. Import translation table for a TR-31 data encryption key (usage "D0") . . . . . . . . . . . 534
| 73. Import translation table for a TR-31 key encryption or wrapping, or key block protection key
| (usages "K0", "K1") . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
| 74. Import translation table for a TR-31 ISO MAC algorithm key (usages "M0", "M1", "M3") . . . . 537
| 75. Import translation table for a TR-31 PIN encryption or PIN verification key (usages "P0", "V0",
| "V1", "V2"). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
| 76. Import translation table for a TR-31 EMV/chip issuer master-key key (usages "E0", "E1", "E2",
| "E3", E4", "E5") . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
| 77. CSNBT31I CV sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
| 78. CSNBT31I protection methods . . . . . . . . . . . . . . . . . . . . . . . . . 546
79. Return code values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
80. Reason codes for return code 0 . . . . . . . . . . . . . . . . . . . . . . . . . 562
83. Reason codes for return code 12 . . . . . . . . . . . . . . . . . . . . . . . . 573
84. Reason codes for return code 16 . . . . . . . . . . . . . . . . . . . . . . . . 574
85. Internal fixed-length AES key-token format, version X'04'. . . . . . . . . . . . . . . . 579
86. Internal fixed-length AES key-token flag byte . . . . . . . . . . . . . . . . . . . . 580
87. Internal fixed-length DES key-token format, version X'00' (version 2 and later software) . . . . 581
88. Internal fixed-length DES key-token format, version X'03' . . . . . . . . . . . . . . . 581
89. External fixed-length DES key-token format, version X'00' . . . . . . . . . . . . . . . 582
90. External fixed-length DES key-token format, version X'01' . . . . . . . . . . . . . . . 582
91. Internal and external fixed-length DES key-token flag byte 1 . . . . . . . . . . . . . . 583
92. Internal and external fixed-length DES key-token flag byte 2 (Release 4.1 or later) . . . . . . 583
93. External RKX DES key-token format, version X'10' . . . . . . . . . . . . . . . . . . 584
94. PKA key-token header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
95. Null PKA key-token format . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
96. Private key, 1024-bit Modulus-Exponent format section (X'02'). . . . . . . . . . . . . . 588
97. RSA private key, 2048-bit Chinese-Remainder Theorem format section (X'05') . . . . . . . . 589
98. RSA private key, 1024-bit Modulus-Exponent format with OPK section (X'06') . . . . . . . . 590
| 99. Private key, 4096-bit Modulus-Exponent format section (X'09'). . . . . . . . . . . . . . 591
100. RSA private key, Chinese-Remainder Theorem format with OPK section (X'08') . . . . . . . 592
101. Public-key section (X'04') of RSA key token . . . . . . . . . . . . . . . . . . . . 593
102. Private-key name section (X'10') of RSA key token . . . . . . . . . . . . . . . . . . 594
103. Public-key certificate section (X'40') of RSA key token. . . . . . . . . . . . . . . . . 595
104. Public-key subsection (X'41') of RSA public-key certificate . . . . . . . . . . . . . . . 595
xiv CCA Basic Services October 14, 2011

105. Optional-information subsection (X'42') of RSA public-key certificate . . . . . . . . . . . 595
106. User-data TLV object (X'50') of RSA public-key certificate . . . . . . . . . . . . . . . 596
107. TLV object (X'51') of private-key environment identifier of RSA public-key certificate . . . . . . 596
108. Serial-number TLV object (X'52') of RSA public-key certificate . . . . . . . . . . . . . . 596
109. Signature subsection (X'45') of RSA public-key certificate . . . . . . . . . . . . . . . 596
| 110. Supported Prime elliptic curves by size, name, and object identifier . . . . . . . . . . . . 597
| 111. Supported Brainpool elliptic curves by size, name, and object identifier . . . . . . . . . . 597
| 112. ECC private-key section. . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
113. ECC public-key section . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
114. Blinding information of RSA private-key . . . . . . . . . . . . . . . . . . . . . . 600
115. Trusted block header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
116. Trusted block trusted RSA public-key section (X'11') . . . . . . . . . . . . . . . . . 603
117. Trusted block rule section (X'12') . . . . . . . . . . . . . . . . . . . . . . . . 604
118. Summary of trusted block rule subsection . . . . . . . . . . . . . . . . . . . . . 605
119. Transport key variant subsection (X'0001') of trusted block rule section (X'12') . . . . . . . . 606
120. Transport key rule reference subsection (X'0002') of trusted block rule section (X'12') . . . . . 607
121. Common export key parameters subsection (X'0003') of trusted block rule section (X'12') 607
122. Source key rule reference subsection (X'0004') of trusted block rule section (X'12') . . . . . . 609
123. Export key CCA token parameters subsection (X'0005') of trusted block rule section (X'12') 609
124. Trusted block key label (name) section (X'13') . . . . . . . . . . . . . . . . . . . 610
125. Trusted block information section (X'14') . . . . . . . . . . . . . . . . . . . . . . 611
126. Summary of trusted block information subsections . . . . . . . . . . . . . . . . . . 611
127. Protection information subsection (X'0001') of trusted block information section (X'14') . . . . . 612
128. Activation and expiration dates subsection (X'0002') of trusted block information section (X'14') 613
129. Trusted block application-defined data section (X'15') . . . . . . . . . . . . . . . . . 613
130. Variable-length symmetric key-token, version X'05' general format (Release 4.1 or later) 614
| 131. Variable-length symmetric key-token, key type CIPHER (Release 4.2 or later) . . . . . . . . 617
132. Variable-length symmetric key-token, key type MAC (Release 4.1 or later) . . . . . . . . . 620
| 133. Variable-length symmetric key-token, key types EXPORTER and IMPORTER (Release 4.2 or
| later) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
| 134. Common key-usage field 1, low-order byte . . . . . . . . . . . . . . . . . . . . . 627
| 135. Common key-management field 1 . . . . . . . . . . . . . . . . . . . . . . . . 627
| 138. IBM optional block data in a TR-31 key block . . . . . . . . . . . . . . . . . . . . 630
139. Modulus-Exponent components . . . . . . . . . . . . . . . . . . . . . . . . . 631
140. CRT components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
141. Visa proprietary format data fields . . . . . . . . . . . . . . . . . . . . . . . . 631
142. Visa proprietary format private key format . . . . . . . . . . . . . . . . . . . . . 631
143. Common personalization ModulusExponent data fields . . . . . . . . . . . . . . . . 632
144. Common Personalization ModulusExponent private key format . . . . . . . . . . . . . 632
145. Common personalization CRT data fields . . . . . . . . . . . . . . . . . . . . . 632
146. Common personalization CRT private key format . . . . . . . . . . . . . . . . . . 632
147. Encipher, Decipher, MAC_Generate, MAC_Verify, and MDC_Generate chaining-vector format 633
148. Key-storage file, header record 1 (not IBM i) . . . . . . . . . . . . . . . . . . . . 634
149. Key-storage file, header record 2 (not IBM i) . . . . . . . . . . . . . . . . . . . . 635
150. Key-record format in key storage (not IBM i) . . . . . . . . . . . . . . . . . . . . 636
151. DES key-record format, IBM i key storage . . . . . . . . . . . . . . . . . . . . . 636
152. AES and PKA key-record format, IBM i key storage . . . . . . . . . . . . . . . . . 636
153. Key-record-list dataset format (other than IBM i) . . . . . . . . . . . . . . . . . . . 637
154. Commands permitted in default role . . . . . . . . . . . . . . . . . . . . . . . 641
155. Authentication data for each authentication mechanism . . . . . . . . . . . . . . . . 644
156. Cloning information token data structure . . . . . . . . . . . . . . . . . . . . . . 650
157. Master-key-share TLV . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
158. Cloning information signature TLV . . . . . . . . . . . . . . . . . . . . . . . . 650
159. FCV distribution structure, FCV format version X'00' (releases before Release 4.1) . . . . . . 651
Tables xv
160. FCV distribution structure, FCV format version X'01' (Release 4.1 or later) . . . . . . . . . 653
161. DES key classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
162. Key-type default control-vector values. . . . . . . . . . . . . . . . . . . . . . . 657
163. PKA92 clear DES key-record (PKR) . . . . . . . . . . . . . . . . . . . . . . . 674
164. NL-EPP-5 key-record format . . . . . . . . . . . . . . . . . . . . . . . . . . 676
165. Versions of the MDC calculation method. . . . . . . . . . . . . . . . . . . . . . 680
166. MDC calculation procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 681
167. Financial PIN-calculation methods, data formats, and other items . . . . . . . . . . . . 697
168. Security API verbs in supported environments. . . . . . . . . . . . . . . . . . . . 711
169. Supported CCA commands . . . . . . . . . . . . . . . . . . . . . . . . . . 715
170. Example roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
171. PIN data exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
172. Roles and permissions for a digital-signing server . . . . . . . . . . . . . . . . . . 738
173. Roles and permissions for a simple certification authority case . . . . . . . . . . . . . 740
174. Format summary of JNI calls . . . . . . . . . . . . . . . . . . . . . . . . . . 743
xvi CCA Basic Services October 14, 2011

About this document
| This document is intended for systems analysts, applications analysts, and application programmers who
| evaluate 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 that is described in
| other publications.
| IBM provides a PCIe cryptographic coprocessor and an older PCI-X cryptographic coprocessor for your
| cryptographic needs. These coprocessors are supported on IBM Power Systems and IBM System x
| servers. The PCI-X cryptographic coprocessor is also provided on IBM System i and System p, which
| has since been changed to Power Systems. The different coprocessor products that are available on each
| platform are shown in Table 1.
| Table 1. Coprocessor product by platform and CCA Release
| Cryptographic CCA
| Platform coprocessor Release Coprocessor product
| IBM Power Systems PCIe 4.1 Feature code 4807 (without custom carrier)
| 4.0
| Feature code 4808 (IBM POWER6 custom carrier and
| instruction EC N23386)
| Feature code 4809 (IBM POWER7 customer carrier
| and instruction EC N23597)
| IBM System i PCI-X 3.30 Feature code 4806
| 3.25
| IBM System p PCI-X 3.30 Feature code 4764
| 3.27
| IBM System x PCIe 4.2 IBM machine type-model 4765-001
| 4.1
| PCI-X 3.60 IBM machine type-model 4764-001
| 3.30
|
| On Power Systems, the following operating systems are supported:

| v IBM AIX (also supported on IBM System p)
| v IBM i (also supported on IBM System i)
| System x has the following operating systems supported:

| v Microsoft Windows Server 2003
| v Red Hat Enterprise Linux
| v SUSE Linux Enterprise Server from Novell
| The different software offerings that are supported for each CCA release are shown in Table 2 on page
| xviii.
xvii
| Table 2. Software offering by CCA Release
| CCA
| Operating system Platform Release Software offering
| IBM AIX Power Systems 4.1 Release 7.10 and later, 32-bit
| Release 6.1L and later, 32-bit
| Release 5.3X and later, 32-bit
| 4.0 Release 6.1J and later, 32-bit
| Release 5.3X and later, 32-bit
| System p 3.30 Release 6.1 and later
| Release 5.3 TL7 and later
| 3.27 Release 5.3H and later
| Release 5.2Q and later
| IBM i Power Systems 4.1 Option 35 Cryptographic Service
| Provider 7.1
| System i 3.30 Option 35 Cryptographic Service
| Provider 6.1
| 3.25 Option 35 Cryptographic Service
| Provider 5.3
| Microsoft Windows Server 2003 System x 3.60 Standard Edition, 32-bit
| R2, Standard Edition, 32-bit
| 3.30 Standard Edition, 32-bit
| Red Hat Enterprise Linux (RHEL) System x 3.60 RHEL 5.4, Server Edition, 32-bit
| RHEL 5.2, Server Edition, 32-bit
| 3.30 RHEL 5.2, Server Edition, 32-bit
| SUSE Linux Enterprise Server from System x 4.2 SLES 11 Service Pack 1, 32-bit
| Novell (SLES)
| 4.1 SLES 11 Service Pack 1, 32-bit
| 3.60 SLES 11 Service Pack 1, 32-bit
| SLES 10 Service Pack 1, 32-bit
| SLES 10, 32-bit
| 3.30 SLES 10, 32-bit
|
| Note: See the PCIe Cryptographic Coprocessor or PCI-X Cryptographic Coprocessor link at
| http://www.ibm.com/security/cryptocards for the latest supported environments and product ordering
| information. From there, click on Product support and then click on Software updates.
Summary of changes
| Twenty-fourth edition, September 2011, CCA Support Program,

| Releases 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25
| This edition describes the IBM CCA Basic Services API for Releases 4.2, 4.1, 4.0, 3.60, 3.30, 3.27, and
| 3.25.
| Other Release 4.2 changes

| Release 4.2 changes to the CCA API include:
xviii CCA Basic Services October 14, 2011

| v Added Elliptic Curve Diffie-Hellman (ECDH) support. This enhancement includes a new
| EC_Diffie-Hellman (CSNDEDH) verb that can be used with a pair of ECC (elliptic curve cryptography)
| keys to create a shared symmetric key using the ANS X9.63 protocol static unified model
| key-agreement scheme. Also included are related changes to the following verbs:
| PKA_Key_Import (CSNDPKI) now supports an AES transport key that can be used to decipher an
| encrypted ECC private key that is in an external key-token, so that it can be returned reenciphered in
| an internal ECC key-token
| PKA_Key_Generate (CSNDPKG) can now return an ECC key that has been enciphered under an
| AES transport key. New keywords OKEK-DES and OKEK-AES have been added to specify which
| key-storage dataset to use when a key label is provided.
| v Added support for X9 TR-31. This support enables the secure exchange of DES and Triple-DES keys
| between CCA and other CCA or non-CCA systems using a method that has been ANSI approved.
| Chapter 9, TR-31 symmetric-key management, on page 499 is now dedicated to TR-31. This
| enhancement includes these new verbs:
| Key_Export_to_TR31 (CSNBT31X), which converts an external or internal CCA DES key-token and
| its attributes to a TR-31 key block for export to another party with or without a CCA system.
| TR31_Key_Import (CSNBT31I), which converts a TR-31 key block and its attributes into an external
| or internal CCA DES key-token.
| TR31_Key_Token_Parse (CSNBT31P), which disassembles a TR-31 key block header into standard
| predefined fields without importing the key.
| TR31_Optional_Data_Build (CSNBT31O), which constructs a complete and properly formatted set of
| optional blocks that can be provided to the Key_Export_to_TR31 verb for inclusion in the returned
| TR-31 key block.
| TR31_Optional_Data_Read (CSNBT31R), which obtains lists of block identifiers and their lengths
| from a TR-31 key block optional header, or obtains the data for a particular optional block.
| In addition to the new TR-31 verbs, this verb has support added for TR-31 key blocks:
| Key_Test2 (CSNBKYT2) can now generate and verify a test pattern for an encyrpted DES key or key
| part wrapped in a TR-31 key block. New keywords DES, ENC-ZERO, and TR-31 have been added
| to support TR-31 key blocks.
| v In support of TR-31, previously reserved control vector bit 57 has been redefined as a TR-31
| export-control bit. The value of this bit either allows (T31XPTOK) or prohibits (NOT31XPT) the export of
| a CCA DES key-token into a TR-31 key block. The following verbs are changed in support of this
| control vector bit definition:
| Control_Vector_Generate (CSNBCVG)
| Key_Token_Build (CSNBKTB)
| Key_Token_Parse (CSNBKTP)
| Restrict_Key_Attribute (CSNBRKA), which can now lower the export authority of DES keys, including
| the new TR-31 export control attribute.
| v Added support to the new variable-length symmetric key-token. This includes the following:
| A new algorithm type of AES, in addition to the existing HMAC algorithm
| New key type of CIPHER for use with the AES algorithm
| New key types of EXPORTER and IMPORTER key-encrypting keys for use with the AES algorithm
| Extended key-management field 2 for the HMAC MAC key, which includes a new definition for the
| low-order byte that provides security history of the key
| Extended key-management field 3 for the HMAC MAC key that provides key-pedigree information to
| indicate how the key was originally created and how it got into the current system
| v These verbs have support added to build and generate new key types CIPHER, EXPORTER, and
| IMPORTER:
| Key_Generate2 (CSNBKGN2)
| Key_Part_Import2 (CSNBKPI2)
About this document xix

| Key_Token_Build2 (CSNBKTB2)
| v Added the Key_Token_Parse2 (CSNBKTP2) verb to parse the information contained in an external or
| internal variable-length symmetric key-token.
| v Added support to the Key_Token_Change2 (CSNBKTC2) verb to re-encipher an AES key contained in a
| variable-length symmetric key-token to encipherment under the current AES master-key
| v Added support to the following verbs for AES key type CIPHER, in clear or encrypted form, contained
| within a variable-length AES key-token.
| Symmetric_Algorithm_Decipher (CSNBSAD) to decipher data using the AES algorithm
| Symmetric_Algorithm_Encipher (CSNBSAE) to encipher data using the AES algorithm
| v Extended AES key support with the introduction of AES key-encrypting keys. Added support to the
| following verbs for AES key types EXPORTER and IMPORTER:
| Key_Generate2 (CSNBKGN2), which can now use operational AES EXPORTER and IMPORTER
| key-encrypting keys to wrap external keys
| Symmetric_Key_Export (CSNDSYX), which can now unwrap an AES or HMAC key contained in an
| internal variable-length symmetric key-token, wrapped using the AESKW key-formatting method, and
| encrypted under the AES master-key, and return the key in an external variable-length symmetric
| key-token using key-formatting method AESKW encrypted under an AES EXPORTER key-encrypting
| key, or PKOAEP2 encrypted under an RSA public-key
| Symmetric_Key_Import2 (CSNDSYI2), which can now use an AES IMPORTER key-encrypting key or
| RSA private-key to unwrap an AES or HMAC key contained in an external variable-length symmetric
| key-token, wrapped using either the AESKW or PKOAEP2 key-formatting method, and rewrap the
| key under the AES master-key in an internal variable-length symmetric key-token using
| key-formatting method AESKW
| PKA_Key_Generate (CSNDPKG), which can now use an AES EXPORTER or IMPORTER
| key-encrypting key to wrap an ECC key
| Key_Test2 (CSNBKYT2), which can now use an AES EXPORTER or IMPORTER key-encrypting key
| to test the value of a key or key part contained in an external variable-length symmetric key-token
| Restrict_Key_Attribute (CSNBRKA), which can now use an AES EXPORTER or IMPORTER
| key-encrypting key for lowering the export authority of a key in an external AES or HMAC
| variable-length symmetric key-token
| Key_Translate2 (CSNBKTR2), which can now use AES EXPORTER and IMPORTER key encrypting
| keys to reformat or translate an AES or HMAC key contained in an external variable-length
| symmetric key-token into a different external variable-length symmetric key token
| v Added support to the following verbs to optionally disallow the wrapping of a stronger key with a weaker
| key-encrypting key, including the master key:
| EC_Diffie-Hellman (CSNDEDH)
| PKA_Key_Generate (CSNDPKG)
| Symmetric_Key_Export (CSNDSYX)
| To disallow the wrapping of a stronger key with a weaker key, enable the Disallow Weak Key Wrap
| command (offset X'0328') in the active role.
| Also added support to the following verb to optionally disallow the wrapping of a stronger key with a
| weaker key-encrypting key, including the master key, during an import operation:
| Symmetric_Key_Import2 (CSNDSYI2)
| To disallow the wrapping of a stronger key with a weaker key during import, enable the Disallow Weak
| Import command (offset X'032B') in the active role.
| If the access-control system disallows the wrapping, the verb returns an error with reason code 2145
| (X'861'), meaning: "An attempt to wrap a stronger key with a weaker key was disallowed."
| v Added support to the following verbs to return an informational message when a stronger key is
| returned that has been wrapped under a weaker key:
xx CCA Basic Services October 14, 2011

| PKA_Key_Generate (CSNDPKG)
| Symmetric_Key_Import2 (CSNDSYI2)
| To receive an informational message when wrapping weak keys, enable the Warn When Wrapping
| Weak Keys command (offset X'032C') in the active role. If the access-control system allows the
| message, the verb returns return code 0 reason code 2146 (X'862'), meaning: "A weaker key was used
| to wrap a stronger key and the Warn When Wrapping Keys command (offset X'032C') was enabled in
| the active role."
| v Added support to the EC_Diffie-Hellman (CSNDEDH) verb to optionally disable a weaker key from
| being used to generate a stronger key, by enabling the Prevent Weaker Keys from Being Used to
| Generate Stronger Keys command (offset X'036F') in the active role. If the access-control system
| disallows the key from being used, the verb returns an error with reason code 2149 (X'865'), meaning:
| "The key to be generated is stronger than the input material."
| v Added SHA-256 support for PKCSOAEP key-formatting method when using the following verbs:
| Symmetric_Key_Generate (CSNDSYG)
| Symmetric_Key_Import (CSNDSYI)
| v Added support to these PIN verbs to improve security and control for PIN decimalization tables:
| Clear_PIN_Generate (CSNBPGN )
| Clear_PIN_Generate_Alternate (CSNBCPA)
| Encrypted_PIN_Generate (CSNBEPG)
| Encrypted_PIN_Verify (CSNBPVR)
| This support utilizes the new access control command Use Only Valid Decimalization Tables (offset
| X'0356').
| v Added support to control and manage loading, removing, and activating authorized PIN decimalization
| tables:
| Cryptographic_Facility_Control (CSUACFC) has new keywords PINTB-LD, PINTB-RM, and
| PINTB-AC.
| New access control commands:
| - Load Decimalization Tables (offset X'0353') for keyword PINTB-LD
| - Delete Decimalization Tables (offset X'0354') for keyword PINTB-RM
| - Activate Decimalization Tables (offset X'0355') for keyword PINTB-AC
| Cryptographic_Facility_Query (CSUACFQ) has new keywords NUM-DECT and STATDECT to return
| information on the PIN decimalization tables that are currently stored on the coprocessor.
| v Added support for a new double-length CVV key with key attribute CVVKEY-A.
| Added a new CVV_Key_Combine (CSNBCKC) verb that combines two MAC-capable single-length
| internal DES keys (CVV key-A and CVV key-B) into one double-length internal DES key with key
| type MAC and with the CVVKEY-A attribute.
| Added support to the CVV_Generate (CSNBCSG) and CVV_Verify (CSNBCSV) verbs to accept the
| new double-length CVVKEY-A key as input when generating or verifying a Visa CVV or MasterCard
| CVC.
Twenty-third edition, June 2011, CCA Support Program, Releases 4.1,

4.0, 3.60, 3.30, 3.27, and 3.25
This edition describes the IBM CCA Basic Services API for Releases 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25.
About this document xxi

Other Release 4.1 changes
With this edition, Release 4.1 makes the IBM 4765 PCIe Cryptographic Coprocessor available on IBM
System x running Linux SLES 11 SP1. Other Release 4.1 changes include:
v Addition of Java Native Interface (JNI) support to the CCA API.
Twenty-second edition, February 2011, CCA Support Program,

Releases 4.1, 4.0, 3.60, 3.30, 3.27, and 3.25
The SUSE Linux Enterprise Server 9 from Novell operating system has been withdrawn from all releases
for IBM System x.
In addition, support for Release 3.25 on IBM System x has been withdrawn.

Release 3.60 changes to the CCA API include the addition of the PKA_Key_Translate (CSNDPKT) verb to
translate a source RSA key token into a target external smart-card key token. New ACI smart-card formats
related to this verb are defined in ACI smart card formats on page 630.
Release 3.60 adds support for new operating systems on IBM System x. See Table 2 on page xviii.
Twenty-first edition, September 2010, CCA Support Program, Releases

4.1, 4.0, 3.60, 3.30, 3.27, and 3.25

Release 4.1 changes to the CCA API include:
v New Elliptic Curve Cryptography (ECC) key generation, along with support for digital signature
generation and verification using the Elliptic Curve Digital Signature Algorithm (ECDSA).
This enhancement includes a new PKA key-token for housing ECC public-key cryptographic keys and a
new asymmetric APKA master-key (32-byte AES key) for wrapping an ECC key-token, along with added
support to the Master_Key_Process verb. Enhancements are made to these verbs:
Cryptographic_Facility_Query
Digital_Signature_Generate
Digital_Signature_Verify
PKA_Key_Generate
PKA_Key_Import
PKA_Key_Token_Build
PKA_Key_Token_Change
PKA_Public_Key_Extract
Key_Test
Key_Test_Extended
This enhancement also includes related changes to the function control vector (FCV). ECC key tokens
are now part of PKA key-storage.
v Addition of MAC generation and verification using HMAC based on FIPS PUB 198-1, The Keyed-Hash
Message Authentication Code (HMAC).
New verbs HMAC_Generate and HMAC_Verify are added. A new variable-length symmetric key-token is
added to house the new MAC keys under the HMAC algorithm. Internal HMAC keys are wrapped by the
xxii CCA Basic Services October 14, 2011

AES master-key and are now part of AES key-storage. The Symmetric_Key_Export verb is updated and
a new Symmetric_Key_Import2 verb is added to support the export and import of HMAC keys under
appropriate RSA keys.
v The following verbs are added in support of the new variable-length symmetric key token:
Key_Generate2
Key_Part_Import2
Key_Test2
Key_Token_Build2
Key_Token_Change2
Restrict_Key_Attribute
v A second key-wrapping method is added for DES that is a more secure version of Triple-DES ECB
mode currently used by CCA.
The enhanced version of key wrapping complies with current cryptographic standards that require key
bundling. This new key-wrapping method can coexist with the CCA legacy ECB mode of wrapping
Triple-DES keys. The two methods can coexist on the same or multiple systems. Affected DES
key-wrapping verbs include:
Clear_Key_Import
Control_Vector_Translate
Data_Key_Export
Data_Key_Import
Diversified_Key_Generate
Key_Encryption_Translate
Key_Export
Key_Generate
Key_Import
Key_Part_Import
Key_Token_Change
Key_Translate
Key_Translate2
Multiple_Clear_Key_Import
Prohibit_Export
Prohibit_Export_Extended
Symmetric_Key_Import
Symmetric_Key_Generate
v Enhanced PIN security with the addition of ANS X9.8 restriction capabilities. Three new access control
points are added to enhance PIN security by blocking PIN attacks. See the Required commands
sections of the Clear_PIN_Generate_Alternate (CSNBCPA), Encrypted_PIN_Translate (CSNBPTR), and
Secure_Messaging_for_PINs (CSNBSPN) verbs.
Twentieth edition, April 2010, CCA Support Program, Releases 3.20,

3.23, 3.24, 3.25, 3.27, 3.30 and 4.0
This edition describes the IBM CCA Basic Services API for Releases 3.20, 3.23, 3.24, 3.25, 3.27, 3.30 and
4.0.

Release 4.0 introduces the IBM 4765 PCIe Cryptographic Coprocessor. The PCIe coprocessor is available
on IBM System p running IBM AIX. Release 4.0 changes to the CCA API include:
About this document xxiii

v The addition of the PKA_Key_Translate (CSNDPKT) verb to translate a source RSA key token into a
target external smart-card key token. New ACI smart-card formats related to this verb are defined in
ACI smart card formats on page 630.
v The addition of the Cryptographic_Facility_Version (CSUACFV) verb to return the CCA application
version and the CCA application build date.
v The One_Way_Hash (CSNBOWH) verb now supports two additional secure hash algorithms:
SHA-384, which produces a 48-byte, 384-bit hash value. The hash method is selected by specifying
the new SHA-384 rule_array keyword.
SHA-512, which produces a 64-byte, 512-bit hash value. The hash method is selected by specifying
v New access control points for verb One_Way_Hash (CSNBOWH):
One-Way Hash, SHA-224 (offset X'0135')
v The addition of the SHA-384 and SHA-512 hashing methods to the public-key cryptographic services
Digital_Signature_Generate (CSNDDSG) and Digital_Signature_Verify (CSNDDSV).
v An enhanced version of the Cryptographic_Facility_Query (CSUACFQ) verb to return the POST2
version of the CCA coprocessor. New rule-array keyword STATCRD2 (replaces STATCARD rule-array
keyword beginning with Release 4.0).
Nineteenth edition, September 2008, CCA Support Program, Releases

3.20, 3.23, 3.24, 3.25, 3.27, and 3.30
This edition describes the IBM CCA Basic Services API for Releases 3.20, 3.23, 3.24, 3.25, 3.27 and 3.30.

v It was discovered that in releases before Release 3.30 the MDC_Generate (CSNBMDG) verb produced
incorrect MDC values under certain atypical conditions. Release 3.30.05 does not produce these
incorrect results. Before using Release 3.30.05 or later to validate MDC values produced using an
earlier release, corrective action might be required. See MDC_Generate (CSNBMDG) on page 126 for
more information.
v Addition of support for the Red Hat Enterprise Linux (RHEL) 5.2 operating system, Server Edition
(32-bit).
v Addition of the SHA-256 hashing method to the Digital_Signature_Generate (CSNDDSG) and
Digital_Signature_Verify (CSNDDSV) verbs when using the X9.31 digital-signature-hash formatting
method.
v Addition of AES (Advanced Encryption Standard) support, with AES key lengths of 128, 192, and 256
bits.
All AES keys are of type DATA, and the only control vector defined for an AES key is for a DATA key.
Unlike DES keys, which utilize control vectors to control key usage, there is no other key-usage control
for AES keys. The following changes for AES support are included:
1. The distributed function control vector structure is enhanced to allow for export control of AES
algorithm enablement for keys with a length of 128, 192, or 256 bits.
2. An enhanced version of the Cryptographic_Facility_Control (CSUACFC) verb with the LOAD-FCV
keyword that enables the verb to load the enhanced version of the function control vector (FCV)
needed for export control of AES key strength.
3. An enhanced version of the Cryptographic_Facility_Query (CSUACFQ) verb to query the status of
the AES key size enabled in the function control vector (FCV). New rule-array keyword STATAES.
xxiv CCA Basic Services October 14, 2011

4. An enhanced version of the Key_Storage_Initialization (CSNBKSI) verb to initialize the new AES
key-storage file. New rule-array keyword AES.
5. An enhanced version of the Master_Key_Process (CSNBMKP) verb to manage the new 256-bit
AES master-key used to encrypt and decrypt keys in AES internal key tokens. A new AES-MK
keyword is added to the verb. Master-key management functions are added to load the AES
master key in multiple cleartext key parts.
Note: The Master_Key_Distribution (CSUAMKD) verb is not enhanced to support cloning of the
AES master key.
6. New access control points for verb Master_Key_Process (CSNBMKP):
Clear AES OMK Register (CLR-OLD) (offset X'0123')
Clear AES NMK Register (CLEAR) (offset X'0124')
Load First AES Master Key Part (offset X'0125')
Combine Intermediate AES Master Key Parts (offset X'0126')
Activate New AES Master Key (SET) (offset X'0128')
7. An enhanced version of the CNM utility to support key management of AES master keys and the
loading of AES keys using cleartext key parts.
8. The addition of a new symmetric CCA key-token structure for internal AES key tokens.
9. An enhanced version of the Key_Generate (CSNBKGN) verb to generate AES internal key tokens
containing encrypted or cleartext keys. New key-type keywords AESDATA and AESTOKEN. New
key-length keywords KEYLN24 and KEYLN32.
10. An enhanced version of the Key_Token_Build (CSNBKTB) verb to build AES internal key tokens.
New key-type keyword CLRAES, and new key-length keywords KEYLN24 and KEYLN32.
11. Enhanced versions of the Key_Test (CSNBKYT) and Key_Test_Extended (CSNBKYTX) verbs to
support both the AES master-key and AES encryption/decryption keys. New rule-array keywords
CLR-A128, CLR-A192, CLR-A256, TOKEN, AES-MK, and SHA-256 for Key_Test (CSNBKYT).
New rule-array keywords TOKEN, AES-MK, and SHA-256 for Key_Test_Extended (CSNBKYTX).
12. An enhanced version of the Key_Token_Change (CSNBKTC) verb to reencipher AES internal key
tokens when the AES master key is changed. New rule-array keywords AES and DES.
13. An enhanced version of the Multiple_Clear_Key_Import (CSNBCKM) verb to load AES keys using
multiple cleartext key parts. New rule-array keyword AES.
14. New access control point for verb Multiple_Clear_Key_Import (CSNBCKM): Encipher Under AES
Master Key (offset X'0129').
15. Enhanced versions of the asymmetric-key-based verbs Symmetric_Key_Export (CSNDSYX),
Symmetric_Key_Generate (CSNDSYG), and Symmetric_Key_Import (CSNDSYI) to transport AES
keys to and from other systems under RSA keys. New rule-array keywords AES and DES. New
rule-array keywords KEYLN24 and KEYLN32 for Symmetric_Key_Generate (CSNDSYG).
Note: Excluding generating an AES key and encrypting it under the AES master key, there is no
symmetric-key-based management of AES keys, only RSA key management of AES keys.
There are no functions to import or export AES keys encrypted under DES, TDES, or AES
keys.
16. New access control points for verb Symmetric_Key_Generate (CSNDSYG):
Generate AES DATA Key (PKCSOAEP or PKCS-1.2) (offset X'012C')
Generate AES DATA Key (ZERO-PAD) (offset X'012D')
17. New access control points for verb Symmetric_Key_Import (CSNDSYI):
Import AES Key (PKCSOAEP or PKCS-1.2) (offset X'012E')
Import AES Key (ZERO-PAD) (offset X'012F')
18. New access control points for verb Symmetric_Key_Export (CSNDSYX):
Export AES Key (PKCSOAEP or PKCS-1.2) (offset X'0130')
About this document xxv

Export AES Key (ZERO-PAD) (offset X'0131')
19. The addition of the Symmetric_Algorithm_Decipher (CSNBSAD) and
Symmetric_Algorithm_Encipher (CSNBSAE) verbs to decrypt and encrypt data using AES keys.
20. New access control point for Symmetric_Algorithm_Decipher (CSNBSAD): Decipher Data Using
AES (offset X'012B').
21. New access control point for Symmetric_Algorithm_Encipher (CSNBSAE): Encipher Data Using
AES (offset X'012A').
22. The addition of a new AES key-storage dataset to store internal AES key tokens, separate from the
DES and PKA key-storage datasets. The AES key-storage dataset is managed by CCA in the
same manner as DES and PKA key-storage datasets. The following new AES key-storage verbs
are added:
AES_Key_Record_Create (CSNBAKRC)
AES_Key_Record_Delete (CSNBAKRD)
AES_Key_Record_List (CSNBAKRL)
AES_Key_Record_Read (CSNBAKRR)
AES_Key_Record_Write (CSNBAKRW)
23. New return code/reason code messages in support of AES, and modified descriptions of some
return code/reason codes in support of AES.
Note: The ATM remote key loading verbs Trusted_Block_Create (CSNDTBC) and
Remote_Key_Export (CSNDRKX), which rely on control vectors and key typing, do not
support AES keys.
v The addition of ISO/DIS 9564-1 Format 3 PIN-block support (ISO-3).
ISO-3 is identical to ISO-0, except it uses random pad digits ranging from X'A' through X'F' instead of
only X'F' pad digits. The following verbs are enhanced to include support for ISO-3 format PIN blocks:
Clear_PIN_Encrypt (CSNBCPE)
Clear_PIN_Generate_Alternate (CSNBCPA)
Encrypted_PIN_Generate (CSNBEPG)
Encrypted_PIN_Translate (CSNBPTR)
Encrypted_PIN_Verify (CSNBPVR)
PIN_Change/Unblock (CSNBPCU)
Secure_Messaging_for_PINs (CSNBSPN)
v Enhanced versions of the following verbs to add 4096-bit RSA key support (RSA-CRT and RSA-PUBL):
Cryptographic_Facility_Control (CSUACFC) enables the verb to load the enhanced version of the
function control vector (FCV) needed for export control of 4096-bit RSA key strength
Cryptographic_Facility_Query (CSUACFQ) enables the verb to query the status of the 4096-bit RSA
key size enabled in the function control vector (FCV)
Digital_Signature_Generate (CSNDDSG)
Digital_Signature_Verify (CSNDDSV)
Master_Key_Distribution (CSUAMKD)
PKA_Decrypt (CSNDPKD)
PKA_Encrypt (CSNDPKE)
PKA_Key_Generate (CSNDPKG)
PKA_Key_Import (CSNDPKI)
PKA_Key_Record_Create (CSNDKRC)
PKA_Key_Record_Delete (CSNDKRD)
PKA_Key_Record_Read (CSNDKRR)
PKA_Key_Record_Write (CSNDKRW)
xxvi CCA Basic Services October 14, 2011

PKA_Key_Token_Build (CSNDPKB)
PKA_Key_Token_Change (CSNDKTC)
PKA_Public_Key_Extract (CSNDPKX)
PKA_Public_Key_Hash_Register (CSNDPKH)
PKA_Public_Key_Register (CSNDPKR)
Remote_Key_Export (CSNDRKX)
Symmetric_Key_Export (CSNDSYX)
Symmetric_Key_Generate (CSNDSYG)
Symmetric_Key_Import (CSNDSYI)
Trusted_Block_Create (CSNDTBC)
The distributed function control vector structure is enhanced to allow for export control of a maximum
modulus length for symmetric encryption of 4096 bits.
v Addition of the Random_Number_Generate_Long (CSNBRNGL) verb, which allows the length of the
random number to be specified, from 1 - 8192 bytes long.
Eighteenth edition, October 2006, CCA Support Program, Releases

3.20, 3.23, 3.24, 3.25, and 3.27
This edition describes the IBM CCA Basic Services API for Releases 3.20, 3.23, 3.24, 3.25, and 3.27.
Seventeenth edition, May 2006, CCA Support Program, Releases 3.20,

3.23, 3.24, and 3.25
This edition describes the IBM CCA Basic Services API for Releases 3.20, 3.23, 3.24, and 3.25.

v New support for remote key loading, which is a method of secured transport of DES keys from a
Tamper Resistant Security Module (TRSM) to an ATM or other remote device using asymmetric
techniques. The new features allow support of the methods defined in the following standards:
ANS X9.24-2 Retail Financial Services Symmetric Key Management Part 2: Using Asymmetric
Techniques for the Distribution of Symmetric Keys
ISO/IEC 11770-3
Information Technology Security Techniques Key Management Part 3:
Mechanisms Using Asymmetric Techniques
Support includes:
1. The addition of an overview section describing improved remote key distribution and remote
key-loading.
2. The addition of a new key-token structure called a trusted block that is an extension of CCA PKA
key tokens. A trusted block is an integral part of the remote key loading process. It consists of the
following parts, some of which are optional, and some of which can be present in different forms:
A header
Trusted public-key section
Rule section with (1) transport key variant, (2) transport key rule references, (3) common export
key parameters, (4) source key rule reference, and (5) export key CCA token parameters
subsections
Name (key label) section
Information section with (1) protection information and (2) activation and expiration dates
subsections
About this document xxvii

Application-defined data section
A trusted block contains a randomly generated confounder and triple-length MAC key that is
encrypted. The MAC key is used to calculate an ISO 16609 CBC-mode Triple-DES MAC of the
trusted block contents. An external trusted block has the confounder and MAC key encrypted under
a variant of an IMP-PKA key. This newly defined IMP-PKA key type is an IMPORTER
key-encrypting key with only its IMPORT key-usage bit (bit 21) on; its other key-usage bits (IMEX,
OPIM, IMIM, and XLATE) must be off. An internal trusted block has the confounder and MAC key
encrypted under a variant of the PKA master key.
3. The addition of a new Trusted_Block_Create (CSNDTBC) verb that creates an external trusted
block under dual control. The verb:
Creates an external trusted block that is inactive (rule_array keyword INACTIVE). Use of the
INACTIVE rule_array keyword requires the new Create a Trusted Block in Inactive Form
command (offset X'030F') to be enabled in the active role.
Activates an inactive external trusted block (rule_array keyword ACTIVE). The output is an
external trusted block that is active. This requires the Activate an Inactive Trusted Block
command (offset X'0310') to be enabled in the active role.
4. The PKA_Key_Import verb now supports the import of an active external trusted block that was
created using the new Trusted_Block_Create verb using the ACTIVATE rule_array keyword. The
verb imports the trusted block into an internal trusted block with the confounder and MAC key
encrypted under a variant of the PKA master key. Use of this verb requires the new Convert
Trusted Block from External to Internal Form command (offset X'0311') to be enabled in the active
role.
5. The addition of a new Remote_Key_Export (CSNDRKX) verb that uses as input an internal trusted
block to generate or export DES keys for local use and for distribution to an ATM or other remote
device.
6. The addition of a new external version X'10' DES key-token called an RKX key-token. An RKX
key-token is a special structure used by the Remote_Key_Export verb that holds encrypted
symmetric keys in a way that binds them to the trusted block, and allows sequences of
Remote_Key_Export calls to be bound together as if they were an atomic operation.
7. The PKA_Key_Token_Change verb now supports changing the confounder and MAC key of an
internal trusted block from encipherment with the old asymmetric master-key to encipherment with
the current asymmetric master-key.
8. The Digital_Signature_Verify verb now supports the verification of a digital signature using public
keys contained in an internal trusted block. The rule array has a new trusted public key restriction
and an associated rule_array keyword TPK-ONLY. By specifying this optional trusted public key
only keyword, the use of regular CCA RSA key tokens is rejected and only a trusted public key
contained in a trusted block supplied by the PKA_public_key_identifier parameter can be used to
verify the digital signature, thus assuring a sensitive signature verification operation is limited to
trusted public keys.
9. The DES key-storage verbs (for example, DES_Key_Record_Write) now support external DES key
tokens, such as RKX key tokens.
10. The addition of new return code/reason codes and their meanings.
v The One_Way_Hash verb now supports two additional secure hash algorithms:
SHA-224, which produces a 28-byte, 224-bit hash value. This hash method is selected by specifying
SHA-256, which produces a 32-byte, 256-bit hash value. This hash method is selected by specifying
v The MAC_Generate and MAC_Verify verbs now provide support for the ANS X9.9 Option 1 (binary
data) procedure using ISO 16609 CBC-mode Triple-DES MAC encryption to generate a MAC. This
MAC-ciphering method is selected by specifying the new TDES-MAC rule_array keyword. This method
encrypts the text using CBC-mode Triple-DES with a double-length key and extracts the MAC from the
xxviii CCA Basic Services October 14, 2011

last block. The extracted MAC value is processed according to other specifications supplied to the verb
call. A description of the ISO 16609 Triple-DES MAC calculation method is now included in MAC
calculation methods on page 689.
v The following PIN verbs now support an optional enhanced PIN security mode:
1. Clear_PIN_Encrypt (CSNBCPE)
2. Clear_PIN_Generate_Alternate (CSNBCPA)
3. Encrypted_PIN_Generate (CSNBEPG)
4. Encrypted_PIN_Translate (CSNBPTR)
5. Encrypted_PIN_Verify (CSNBPVR)
6. PIN_Change/Unblock (CSNBPCU)
This optional mode is selected by enabling the Enhanced PIN Security Mode command (offset X'0313')
in the active role. When active, this command affects all PIN verbs that extract or format a PIN using a
PIN-block format of 3621 or 3624 with a PIN-extraction method of PADDIGIT.
v The CVV_Verify verb now correctly checks for the Verify CVV command (offset X'00E0') to be enabled
in the active role.
How this document is organized

The document includes these topics:
v Chapter 1, Introduction to programming for the IBM Common Cryptographic Architecture presents an
introduction to programming for the CCA application programming interface and products.
v Chapter 2, CCA node management and access control provides a basic explanation of the
access-control system implemented within the hardware. The section also explains the master-key
concept and administration, and introduces CCA key-management.
v Chapter 3, PKA key-management explains how to generate and distribute RSA and ECC keys
between CCA nodes and with other RSA and ECC implementations.
v Chapter 4, Hashing and digital signatures explains how to protect and confirm the integrity of data
using data hashing and digital signatures.
v Chapter 5, AES, DES, and HMAC symmetric-key management explains basic AES and DES
key-management services available with CCA.
v Chapter 6, Data confidentiality and data integrity explains how to cipher (encipher and decipher) data
using AES or DES, and how to verify the integrity of data using the DES-based message authentication
code (MAC) process. The AES and DES ciphering and DES MAC services are described.
v Chapter 7, Key-storage mechanisms explains how to use key labels and how to employ external key
storage.
v Chapter 8, Financial services support explains services for the financial services industry including
PIN-processing services and credit-card validation functions.
| v Chapter 9, TR-31 symmetric-key management explains how to use the TR-31 interface to interchange
| DES and Triple-DES keys.
v Appendix A, Return codes and reason codes describes the return codes and reason codes issued by
the CCA host code and the coprocessor.
v Appendix B, Data structures describes the various data structures for key tokens and trusted blocks,
ACI smart-card formats, chaining-vector records, key-storage datasets and records, key-record-list
datasets, access-control datasets, master-key shares, and the distributed function control vector
dataset.
v Appendix C, CCA control-vector definitions and key encryption describes the control-vector bits and
provides rules for the construction of a control vector, techniques to change a control vector, and key
encryption and decryption processes for DES and RSA.
v Appendix D, Algorithms and processes describes in further detail the algorithms and processes
mentioned in this book.
About this document xxix

v Appendix E, Financial system verbs calculation methods and data formats describes processes and
formats implemented by the PIN-processing support.
v Appendix F, Verb list lists the supported CCA verbs. their entry point names, and page reference.
v Appendix G, Access-control-point codes lists the access-control points (offsets) used by the various
verbs and suggests appropriate security settings and considerations.
v Appendix H, Observations on secure operations describes setup and use considerations for enhanced
security operations.
v Appendix I, Java Native Interface, on page 743 describes the Java Native Interface.
v Notices provides legal notices.
v Trademarks provides trademark information.
v List of abbreviations provides a list of abbreviations used throughout the manual.
v Glossary contains definitions of terms used.
Related publications
In addition to the documents listed below, you might want to refer to other CCA product publications.
These publications might be of use with applications and systems you might develop for use with the IBM
4765 and IBM 4764. While there is substantial commonality in the API supported by the CCA products,
and while this document seeks to guide you to a common subset supported by all CCA products, other
individual product publications might provide further insight into potential issues of compatibility.
IBM 4765 PCIe and IBM 4764 PCI-X Cryptographic Coprocessors
All of the IBM 4765-related and 4764-related publications can be obtained from the Library page
that you can reach from the product Web site at http://www.ibm.com/security/cryptocards
IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual and the
IBM 4764 PCI-X Cryptographic Coprocessor CCA Support Program Installation Manual
Describe the installation of the CCA Support Program and the operation of the
Cryptographic Node Management utility.
IBM 4765 PCIe Cryptographic Coprocessor Installation Manual and the IBM 4764 PCI-X
Cryptographic Coprocessor Installation Manual
Describe the physical installation of the IBM 4765 and the IBM 4764, and also the
battery-changing procedure.
Custom Programming for the IBM 4765 and the IBM 4764
The Library portion of the product Web site also includes programming information for creating
applications that perform within the IBM 4765 and the IBM 4764. See the reference to custom
programming. The product Web site is located at http://www.ibm.com/security/cryptocards
Cryptography publications
The following publications describe cryptographic standards, research, and practices relevant to the
coprocessor:
| v Accredited Standards Committee X9, Inc.: X9 TR-31 2010: Interoperable Secure Key Exchange Block
| Specification for Symmetric Algorithms
v American National Standards Institute (ANSI). ANSI is the official U.S. representative to the International
Organization for Standardization (ISO) and, via the U.S. National Committee, the International
Electrotechnical Commission (IEC). ANSI is also a member of the International Accreditation Forum
(IAF).
ANS X9.8-1:2003 Banking -- Personal Identification Number Management and Security -- Part 1: PIN
Protection Principles and Techniques for Online PIN Verification in ATM & POS Systems.
ANS X9.9:1986 Financial Institution Message Authentication (Wholesale).
ANS X9.19:1998 Financial Institution Retail Message Authentication.
ANS X9.23:1998 Financial Institution Encryption of Wholesale Financial Messages.
xxx CCA Basic Services October 14, 2011

ANS X9.24-1:2004 Retail Financial Services Symmetric Key Management -- Part 1: Using Symmetric
Techniques.
ANS X9.24-2:2006 Retail Financial Services Symmetric Key Management -- Part 2: Using
Asymmetric Techniques for the Distribution of Symmetric Keys.
ANS X9.31:1998 Digital Signature Using Reversible Public Key Cryptography for the Financial
Services Industry.
ANS X9.52:1998 Triple Data Encryption Algorithm Modes of Operation.
ANS X9.62:2005 Public Key Cryptography for the Financial Services Industry: The Elliptic Curve
Digital Signature Algorithm (ECDSA).
| ANS X9.63:2001 Public Key Cryptography for the Financial Services Industry: Key Agreement and
| Key Transport Using Elliptic Curve Cryptography.
v Applied Cryptography: Protocols, Algorithms, and Source Code in C, Second Edition, Bruce Schneier,
John Wiley & Sons, Inc., 1996, ISBN 0-471-12845-7 or ISBN 0-471-11709-9
| v ECC Brainpool Standard Curves and Curve Generation, v.1.0, October 19, 2005
| Available at http://www.ecc-brainpool.org/download/Domain-parameters.pdf.
| v Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation (RFC 5639),
| Manfred Lochter and Johannes Merkle, IETF Trust, March 2010. Available at http://www.rfc-editor.org/
| rfc/rfc5639.txt
v EMV 2000 Integrated Circuit Card Specifications for Payment Systems, Book 2 -- Security and Key
Management, Version 4.0, EMVCo, LLC, December 2000.
v Federal Information Processing Standards (FIPS), issued by the U.S. National Institute of Standards
and Technology (S).
FIPS PUB 46-3 Data Encryption Standard (DES), October 25, 1999. Available at
http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf.
FIPS PUB 81 DES Modes of Operation, December 2, 1980. Available at http://www.itl.nist.gov/
fipspubs/fip81.htm.
FIPS PUB 140-1 Security Requirements for Cryptographic Modules, January 11, 1994. Available at
http://csrc.nist.gov/publications/fips/fips1401.htm.
FIPS PUB 140-2 Security Requirements for Cryptographic Modules, May 25, 2001. Available at
http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf.
FIPS PUB 180-2 Secure Hash Standard (SHS), August 1, 2002. Available at http://csrc.nist.gov/
publications/fips/fips180-2/fips180-2.pdf.
FIPS PUB 186-2 Digital Signature Standard (DSS), January 27, 2000. Available at
http://csrc.nist.gov/publications/fips/archive/fips186-2/fips186-2.pdf.
FIPS PUB 186-3 Digital Signature Standard (DSS), June, 2009. Available at http://csrc.nist.gov/
publications/fips/fips186-3/fips_186-3.pdf.
FIPS PUB 197 Advanced Encryption Standard (AES), November 26, 2001. Available at
http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf.
FIPS PUB 198-1 The Keyed-Hash Message Authentication Code (HMAC), July, 2008. Available at
http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf.
v International Organization for Standardization (ISO). ISO is the world's largest developer and publisher
of International Standards. ISO is a network of the national standards institutes of many countries, one
member per country, with a Central Secretariat in Geneva, Switzerland, that coordinates the system.
ISO 16609:2004 Banking -- Requirements for Message Authentication Using Symmetric Techniques.
ISO/DIS 9564-1 Financial Services -- Personal Identification Number (PIN) Management and
Security -- Part 1: Basic Principles and Requirements for PINs in Card-Based Systems.
v International Organization for Standardization/International Electrotechnical Commission (ISO/IEC)
ISO/IEC 9796-1:1997 Information Technology -- Security Techniques -- Digital Signature Schemes
Giving Message Recovery -- Part 1: Mechanisms Using Redundancy.
About this document xxxi

ISO/IEC 9796-2:2002 Information Technology -- Security Techniques -- Digital Signature Schemes
Giving Message Recovery -- Part 2: Integer Factorization Based Mechanisms.
ISO/IEC 9797-1:1999 Information technology -- Security techniques -- Message Authentication
Codes (MACs) -- Part 1: Mechanisms Using a Block Cipher.
ISO/IEC 11770-3:2008 Information Technology -- Security Techniques -- Key Management -- Part 3:
Mechanisms Using Asymmetric Techniques.
v National Institute of Standards and Technology (NIST) Special Publications (SP), U.S. Dept. of
Commerce
NIST SP 800-38A Recommendation for Block Cipher Modes of Operations: Methods and
Techniques, 2001 Edition. Available at http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-
38a.pdf.
| NIST SP 800-56A Recommendation for Pair-Wise Key Establishment Schemes Using Discrete
| Logarithm Cryptography (Revised), March 2007 Edition
| Available at http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf.
v RSA Laboratories (http://www.rsa.com/rsalabs/pkcs).
PKCS #1: RSA Encryption Standard, Version 1.5, November 1, 1993.
PKCS #1 v2.0: RSA Cryptography Standard, October 1, 1998.
PKCS #1 v2.1: RSA Cryptography Standard, June 14, 2002.
PKCS #10 v1.7: Certification Request Syntax Standard, May 26, 2000.
v SET Secure Electronic Transaction, Version 1.0, May 31, 1997, Secure Electronic Transaction LLC.
| v Standards for Efficient Cryptography 2 (SEC 2): Recommended Elliptic Curve Domain Parameters
| Version 2.0, Standards for Efficient Cryptography Group (SECG), Certicom Research, January 27, 2010.
| Available at http://www.secg.org/download/aid-784/sec2-v2.pdf
v The MD5 Message-Digest Algorithm, Internet Engineering Task Force Request for Comments (RFC)
1321, MIT Laboratory for Computer Science and RSA Data Security, Inc., April 1992. Available at
http://www.ietf.org/rfc/rfc1321.txt.
v Visa Integrated Circuit Card Specification, Version 1.4.0, Visa International, October 31, 2001.
v Visa Integrated Circuit Card Specification (VIS) 1.4.0 Corrections and Updates, Visa International.
xxxii CCA Basic Services October 14, 2011

Chapter 1. Introduction to programming for the IBM Common
Cryptographic Architecture
This section introduces the IBM Common Cryptographic Architecture (CCA) application programming
interface (API). The section explains basic concepts and describes how you can obtain cryptographic and
other services from the IBM 4765 and IBM 4764 Cryptographic Coprocessors and CCA.
Section topics include:

v Available CCA verbs
v CCA functional overview
v Security API programming fundamentals
v How the API services are organized in the remainder of this document
Available Common Cryptographic Architecture verbs

CCA products provide a variety of cryptographic processes and data-security techniques. Your application
program can call verbs (sometimes called services) to perform the following functions:
Data confidentiality
Encrypt and decrypt information, typically using the AES or DES algorithms in Cipher Block
Chaining (CBC) mode to enable data confidentiality.
Data integrity
Hash data to obtain a digest, or process the data to obtain a message authentication code (MAC)
or keyed hash MAC (HMAC), that is useful in demonstrating data integrity.
Non-repudiation
Generate and verify digital signatures using either the RSA algorithm or the ECDSA algorithm, to
demonstrate data integrity and form the basis for non-repudiation.
Authentication
Generate, encrypt, translate, and verify finance industry personal identification numbers (PINs) and
American Express, MasterCard and Visa card security codes with a comprehensive set of
finance-industry-specific services.
Key management
Manage the various AES, DES, ECC, and RSA keys necessary to perform the above operations.
Java interaction
Interact with the Java Native Interface (JNI). Some of the CCA verbs have a specific version that
can be used for JNI work.
CCA management
Control the initialization and operation of CCA.
Subsequent sections group the many available services by topic. Each section lists the services in
alphabetical order by verb pseudonym.
The remainder of this section provides an overview of the structure of a CCA cryptographic framework and
introduces some important concepts and terms.
Common Cryptographic Architecture functional overview

Figure 1 on page 2 provides a conceptual framework for positioning the CCA security API which you use
to access a common cryptographic architecture. Application programs make procedure calls to the CCA
security API to obtain cryptographic and related I/O services. The CCA security API is designed so that a
call can be issued from essentially any high-level programming language. The call, or request, is
1
forwarded to the cryptographic services access layer and receives a synchronous response; that is, your
application program loses control until the access layer returns a response after processing your request.
Figure 1. CCA security API, access layer, and cryptographic engine
Note: AES is not supported in releases before Release 3.30.
The products that implement the CCA security API consist of both hardware and software components.
CCA software support: The software consists of application development and runtime software
components.
v The application development software primarily consists of language bindings that can be included in
new applications to assist in accessing services available at the API. Language bindings are provided
for the C and C++ programming languages. The IBM i Option 35, CCA Cryptographic Service Provider
feature also provides language bindings for COBOL, RPG, and CL.
Note: For availability of the various IBM i code levels, see the IBM i information center
(http://www.ibm.com/eserver/iseries/infocenter).
v The runtime software can be divided into the following categories:
Service-requesting programs, including application and utility programs.
The security API, an agent function that is logically part of the calling application program or utility.
The cryptographic services access layer: an environment-dependent request routing function,
key-storage (directory) support services, and device driver to access one or more hardware
cryptographic engines.
2 CCA Basic Services October 14, 2011

The cryptographic engine software that gives access to the cryptographic engine hardware.
The cryptographic engine is implemented in the hardware of the IBM 4765 and IBM 4764
Cryptographic Coprocessors. Security-sensitive portions of CCA are implemented in the
cryptographic engine software running in the coprocessor-protected environment.
Utility programs and tools provide support for administering the CCA access-controls, administering
AES, DES, and public-key cryptographic keys, and configuring the software support.
On the IBM i software platform, the utility functions to set up and administer the coprocessor are
accessible through a Web-based configuration utility. Refer to the Cryptographic Coprocessor section
of the IBM i information center (http://www.ibm.com/eserver/iseries/infocenter). Also, IBM i provides
sample programs for your consideration that administer CCA access-controls, and manage DES and
public-key cryptographic keys.
You can create application programs that employ the CCA security API, or you can purchase applications
from IBM or other sources that use the products. This document is the primary source of information for
designing systems and application programs that use the CCA security API with the cryptographic
coprocessors.
Cryptographic engine: The CCA architecture defines a cryptographic subsystem that contains a
cryptographic engine operating within a protected boundary. The coprocessor's tamper-resistant,
tamper-responding environment provides physical security for this boundary, and the CCA architecture
provides the logical security needed for the full protection of critical information.
IBM 4765 PCIe and IBM 4764 PCI-X Cryptographic Coprocessors: The cryptographic coprocessors
provide a secure programming and hardware environment wherein AES (beginning with Release 3.30),
DES, ECC (beginning with Release 4.1), and RSA processes are performed. Each cryptographic
coprocessor includes a general-purpose processor, nonvolatile storage, and specialized cryptographic
electronics. These components are encapsulated in a protective environment to enhance security.
The IBM CCA Support Program enables applications to employ a set of cryptographic services based on
AES, DES, ECC, HMAC, and RSA, utilizing the coprocessor hardware. Services include:
| v AES, DES, HMAC, and PKA (ECC and RSA) key and key-pair generation
v Digital signature generation and verification using either the RSA algorithm or ECDSA algorithm
v Cryptographic key wrapping and unwrapping
v Data encryption and decryption, and MAC generation/verification
v PIN and card security code processing for the financial services industry
v Other services, including DES key-management based on CCA's control-vector-enforced key separation
CCA: The IBM Common Cryptographic Architecture (CCA) is the basis for a consistent cryptographic
product family. Applications employ the CCA security API to obtain services from, and to manage the
operation of, a cryptographic system that meets CCA architecture specifications.
CCA access control: Each CCA node has an access-control system enforced by the hardware and
protected software. This access-control system permits you to determine whether programs and persons
can use the cryptographic and data-storage services. Although your computing environment might be
considered open, the specialized processing environment provided by the cryptographic engine can be
kept secure because selected services are provided only when logon requirements are met. The
access-control decisions are performed within the secured environment of the cryptographic engine and
cannot be subverted by rogue code that might run on the main computing platform.
Coprocessor certification: After quality checking a newly manufactured coprocessor, IBM loads and
certifies the embedded software. Following the loading of basic, authenticated software, the coprocessor
generates an RSA key-pair and retains the private key within the cryptographic engine. The associated
public key is signed by a certification key securely held at the manufacturing facility, and then the certified
Chapter 1. Introduction to programming for the IBM Common Cryptographic Architecture 3

device key is stored within the coprocessor. The manufacturing facility key has itself been certified by a
securely held key unique to the IBM 4765 and IBM 4764 Cryptographic Coprocessor product lines.
The private key within the coprocessor, known as the device private key, is retained in the coprocessor.
From this time on, if tampering is detected or if the coprocessor loses power (batteries are removed or
lose power in the absence of bus power), the coprocessor sets all security-relevant keys and data items to
zero. This process is irreversible and results in the permanent loss of the factory-certified device key, the
device private key, and all other data stored in battery-protected memory. Security-sensitive data stored in
the coprocessor flash memory is encrypted. The key used to encrypt such data is itself retained in the
battery-backed memory.
CCA master keys: When using the CCA architecture, working keysincluding session keys and the RSA
and ECC private keys used at a node to form or verify digital signatures or to unwrap other keysare
generally stored outside of the cryptographic-engine protected environment. These working keys are
wrapped (AES encrypted or DES triple-encrypted) by the AES, APKA, DES, or PKA master keys. The
master keys are held in the clear (not enciphered) within the cryptographic engine.
The number of keys usable with a CCA subsystem is thus restricted only by the host server storage, not
by the finite amount of storage within the coprocessor secure module. In addition, the working keys can be
used by additional CCA cryptographic engines which have the same master key. This CCA characteristic is
useful in high-availability and high-throughput environments where multiple cryptographic processors must
function in parallel.
Establishing CCA master keys: To protect working keys, master keys must be generated and initialized
in a secure manner. For DES and PKA master keys (but not AES and APKA master keys), one method
uses the internal random-number generator for the source of the master key. In this case, the master key
is never external to the node as an entity, and no other node has the same master key unless master-key
cloning is authorized and in use (unless, out of the 2168 possible values, another node randomly generates
the same master-key data). If an uncloned coprocessor loses its random DES or PKA master key (for
example, the coprocessor detects tampering and destroys the master key), there is no way to recover the
working keys that it wrapped.
Another master-key-establishment method enables authorized users to enter multiple, separate, 256-bit
AES key parts for AES or APKA master keys, or 168-bit DES key parts for DES or PKA master keys, into
the cryptographic engine. As each key part is entered, that part is exclusive-ORed with the contents of the
specified new-master-key register. When all parts have been accumulated, a separate command is issued
to promote the contents of the current-master-key register to the old-master-key register, and to promote
the contents of the new-master-key register to the current-master-key register.
A DES or PKA master key (but not an AES or APKA master key) can be cloned (copied) from one
coprocessor node to another coprocessor node through master-key-shares distribution. This process is
protected using digital certificates and authorizations. In this process, the master key can be reconstituted
in one or more additional coprocessors by transporting encrypted shares of the master key.
Understanding and managing master keys on page 27 provides additional detail about master-key
management.
CCA verbs: Application and utility programs called requestors obtain service from the CCA Support
Program by issuing service requests (verb calls or procedure calls) to the runtime subsystem. To fulfill
these requests, the Support Program obtains service from the coprocessor software and hardware.
The available services are collectively described as the CCA security API. All of the software and hardware
accessed through the CCA security API should be considered an integrated subsystem. A command
processor performs the verb request within the cryptographic engine.
Commands and access control, roles, profiles: In order to ensure that only designated individuals (or
programs) can run commands such as master-key loading, each command processor that performs

sensitive processing interrogates one or more control-point values within the cryptographic engine
access-control system for permission to perform the request.
The access-control system includes one or more roles. Each role defines the permissible control points for
users of that role. The access-control system also supports user profiles that are referenced by a user ID.
Each profile associates the user ID with a role, logon verification method and authentication information,
and a logon session-key. Within a host process, one and only one profile, and thus role, can be logged on
at a time. In the absence of a logged-on user, a default role defines the permitted commands (using the
control points in the role) that a process can use.
For the coprocessor, there can be multiple logons by different users from different host processes. There
can also be requests from multiple threads within a single host process.
A user is logged on and off by the Logon_Control verb. During logon, the Logon_Control verb establishes
a logon session key. This key is held in user-process memory space and in the cryptographic engine. All
verbs append and verify a MAC based on this key on verb control information exchanged with the
cryptographic engine. Logoff causes the cryptographic engine to destroy its copy of the session key and to
mark the user profile as not active.
Using CCA access-control on page 14 provides a further explanation of the access-control system, and
Logon_Control (CSUALCT) on page 67 provides details about the Logon_Control verb.
How application programs obtain service

Application programs and utility programs obtain services from the security product by issuing service
requests to the runtime subsystem of software and hardware. Use a procedure call according to the rules
of your application language. The available services are collectively described as the security API. All of
the software and hardware accessed through the security API should be considered an integrated
subsystem.
When the cryptographic-services access layer receives requests concurrently from multiple application
programs, it serializes the requests and returns a response for each request. There are other
multiprocessing implications arising from the existence of a common master-key and a common
key-storage facility. These topics are covered later in this manual.
The way application programs and utilities are linked to the API services depends on the computing
environment. In the AIX, Linux, and Microsoft Windows Server 2003 environments, the operating systems
dynamically link application security API requests to the subsystem DLL code (AIX: shared library; IBM i:
service program; Linux: shared object). In the IBM i environment, the CCA API is implemented in a set of
64-bit entry-point service programs, one for each security API verb. Details for linking to the API on the
IBM i platform can be found by following the IBM i link from the CCA support section of the product Web
site, http://www.ibm.com/security/cryptocards.
Details for linking to the API are covered in the individual software product documentation. See either the
IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual, or the IBM 4764
PCI-X Cryptographic Coprocessor CCA Support Program Installation Manual.
Together, the security API DLL and the environment-dependent request routing mechanism act as an
agent on behalf of the application and present a request to the server. Requests can be issued by one or
more programs. Each request is processed by the server as a self-contained unit of work. The
programming interface can be called concurrently by applications running as different processes. The
security API can be used by multiple threads in a process and is thread safe.
In each server environment, a device driver provided by IBM supplies low-level control of the hardware
and passes the request to the hardware device. Requests can require one or more I/O commands from
the security server to the device driver and hardware.

The security server and a directory server manage key storage. Applications can store locally used
cryptographic keys in a key-storage facility. This is especially useful for long-life keys. Keys stored in key
storage are referenced using a key label. Before deciding whether to use the key-storage facility or to let
the application retain the keys, consider system design trade-off factors, such as key backup, the impact of
master-key changing, the lifetime of a key, and so forth.
Overlapped processing
Calls to the CCA security API are synchronous, that is, your program loses control until the verb
completes. Multiple processing-threads can make concurrent calls to the API. CCA for Windows and Linux
restricts the number of concurrent outstanding calls for a coprocessor to 32.
Note: The limitation of 32 concurrent API calls does not apply to AIX implementations.
You can maximize throughput by organizing your application or applications to make multiple, overlapping
calls to the CCA API. You can also increase throughput by employing multiple coprocessors, each with
CCA (see Multi-coprocessor capabilities on page 25).
Within the coprocessor, the CCA software is organized into multiple threads of processing. This
multiprocessing design is intended to enable concurrent use of the coprocessor's main engine, PCIe or
PCI-X communications, AES, DES, and Secure Hash Algorithm (SHA-1, SHA-224, SHA-256, SHA-384,
and SHA-512) engine, and modular-exponentiation engine.
Host-side key caching

CCA, on other than IBM i, provides caching of key records obtained from key storage within the CCA host
code. However, the host cache is unique for each host process. If different host processes access the
same key record, an update to a key record caused in one process does not affect the contents of the key
cache held for other processes. Caching of key records within the key-storage system can be suppressed
so that all processes access the most current key-records. The techniques used to suppress key-record
caching are discussed in the IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program
Installation Manual and the IBM 4764 PCI-X Cryptographic Coprocessor CCA Support Program Installation
Manual.
Security API programming fundamentals

You obtain CCA cryptographic services from the coprocessor through procedure calls to the CCA security
application programming interface (API). Most of the services that are provided are considered an
implementation of the IBM Common Cryptographic Architecture (CCA). Most of the extensions that differ
from other IBM CCA implementations are in the area of the access-control services. If your application
program is used with other CCA products, compare the product literature for differences.
Your application program requests a service through the security API by using a procedure call for a verb.
The term verb implies an action that an application program can initiate; other systems and publications
might use the term callable service instead. The procedure call for a verb uses the standard syntax of a
programming language, including the entry-point name of the verb, the parameters of the verb, and the
variables for the parameters. Each verb has an entry-point name and a fixed-length parameter list.
The security API is designed for use with high-level languages, such as C, COBOL (IBM i), or RPG (IBM
i), and for low-level languages, such as assembler. It is also designed to enable you to use the same verb
entry-point names and variables in the various supported environments. Therefore, application code that
you write for use in one environment generally can be ported to additional environments with minimal
change.

Verbs, variables, and parameters
This section explains how each verb is described in the reference material and provides an explanation of
the characteristics of the security API. Each callable verb has an entry-point name and a fixed-length
parameter list. The reference material describes each verb and includes the following information for each
verb:
v Pseudonym
v Entry-point name
v Valid environments, coprocessors, and releases
v Description
v Restrictions
v Format
v Parameters
v Required commands
Each verb has a pseudonym (also called a general-language name) and an entry-point name (known as a
computer-language name). The entry-point name is used in your program to call the verb. Each verb's
7-character or 8-character entry-point name begins with one of the following prefixes:
CSNB Symmetric algorithm (AES and DES) services
CSND RSA public-key services
CSUA Cryptographic-node and hardware-control services
The last three or four letters in the entry-point name after the prefix identify the specific service in a group
and are often the first letters of the principal words in the verb pseudonym.
Description: The verb is described in general terms. Be sure to read the parameter descriptions as these
add additional detail. A Related information section appears at the end of the verb material for some
verbs.
Restrictions: Any restrictions are noted. The Restrictions section for each verb starts with a table that
describes which operating systems and CCA releases use the verb. For example:
CCA CCA CCA CCA CCA CCA CCA

Operating system 4.2 4.1 4.0 3.60 3.30 3.27 3.25
AIX X X X X
IBM i X X X
Red Hat Enterprise Linux X X
SUSE Linux Enterprise Server X X X X
Windows X X
Note: See Table 2 on page xviii for a list of supported operating system releases.
| The left column of the table indicates which operating systems are valid. The top row indicates which CCA
| releases are valid. An 'X' indicates that the verb is supported for that CCA release for the operating system
| indicated.
Format: The format section for each verb lists the entry-point name on the first line in bold type. This is
followed by the list of parameters for the verb. Generally the input or output direction in which the variable
identified by the parameter is listed along with the type of variable (integer or string), and the size, number,
or other special information about the variable. You must code all of the parameters and in the order listed.
Parameters: All information that is exchanged between your application program and a verb is through the
variables that are identified by the parameters in the procedure call. These parameters are pointers to the

variables contained in application program storage that contain information to be exchanged with the verb.
Each verb has a fixed-length parameter list, and though all parameters are not always used by the verb,
they must be included in the call. The entry-point name and the parameters for each verb are shown in
Table 3.
Table 3. Verb parameter format
Parameter name Direction Data type Data length or value
entry-point name
return_code Output Integer See Appendix A.
reason_code Output Integer See Appendix A.
exit_data_length In/Output Integer 0
exit_data In/Output String exit_data_length bytes
parameter_5 Direction Data type length
parameter_6 Direction Data type length
.
.
.
parameter_n Direction Data type length
The first four parameters are the same for all of the verbs. For a description of these parameters, see
Parameters common to all verbs on page 9. The remaining parameters (parameter_5, parameter_6, ...,
parameter_n) are unique for each verb. For descriptions of these parameters, see the definitions with the
individual verbs.
Direction: The parameter descriptions use the following terms to identify the flow of information:
Input The application program sends the variable to the verb (to the called routine).
Output The verb returns the variable to the application program.
In/Output The application program sends the variable to the verb, or the verb returns the variable to
the application program, or both.
Data type: Data that is identified by a verb parameter can be a single value or a one-dimensional array. If
a parameter identifies an array, each data element of the array is of the same data type. If the number of
elements in the array is variable, a preceding parameter identifies a variable that contains the actual
number of elements in the associated array. Unless otherwise stated, a variable is a single value, not an
array.
For each verb, the parameter descriptions use the following terms to describe the data type of the
variable:
Integer A 4-byte (32-bit), signed, two's-complement binary number. In the IBM i environment,
integer values are presented in 4 bytes in the sequence high-order to low-order
(little-endian). All integer values are greater than or equal to 0.
String A series of bytes where the sequence of the bytes must be maintained. Each byte can
take on any bit configuration. The string consists only of the data bytes. No string
terminators, field-length values, or typecasting parameters are included. Individual verbs
can restrict the byte values within the string to characters or numerics.
Character data must be encoded in the native character set of the computer where the
data is used. Exceptions to this rule are noted where necessary.
Array An array of values, which can be integers or strings. Only one-dimensional arrays are
permitted. For information about the parameters that use arrays, see Rule_array and
other keyword parameters on page 10.

Data length or value: This is the length, in bytes, of the data identified by the parameter being described or
its value. This length can be expressed as a specific number of bytes or it might be expressed in terms of
the contents of another variable.
For example, the length of the exit_data variable is expressed in this manner. The length of the exit_data
string variable is specified in the exit_data_length variable. This length is shown in the parameter tables as
exit_data_length bytes. The rule_array variable, however, is an array whose elements are 8-byte strings.
The number of elements in the rule array is specified in the rule_array_count variable and its length is
shown as rule_array_count * 8 bytes.
As you examine the verb descriptions throughout this book, you see references to Required commands.
See Appendix G, Access-control-point codes for a summary of all access-control commands, along with
the verbs that use them. Almost all of the verbs request the cryptographic engine (coprocessor) to perform
one or more commands in the performance of the verb. Each of these commands must be authorized for
use. Access-control administration concerns managing these authorizations.
Commonly encountered parameters

Some parameters are common to all verbs, other parameters are used with many of the verbs. This
section describes several groups of these parameters:
v Parameters common to all verbs
v rule_array and other keyword parameters
v Key tokens, key labels, and key identifiers
Parameters common to all verbs

The first four parameters (return_code, reason_code, exit_data_length, and exit_data) are the same for all
verbs (see Table 3 on page 8). A parameter is an address pointer to the associated variable in application
program storage.
return_code
The return_code parameter is a pointer to an integer variable that expresses the general results of
processing. See Return code and reason code overview for more information about return codes.
reason_code
The reason_code parameter is a pointer to an integer variable that expresses the specific results of
processing. Each possible result is assigned a unique reason code value. See Return code and
reason code overview for more information about reason codes.
exit_data_length
The exit_data_length parameter is a pointer to an integer variable containing the number of bytes in
the exit_data variable. The exit_data_length parameter should point to a value of zero, to ensure
compatibility with any future extension or other operating environment.
exit_data
The exit_data parameter is a pointer to a variable-length string that contains installation-exit-dependent
data that is exchanged with a preprocessing user exit or a post-processing user exit.
Restriction: You cannot use the IBM 4765 and IBM 4764 CCA Support Programs with user exits. The
exit_data_length and exit_data variables must be declared in the parameter list. The
exit_data_length parameter should be set to 0.
Return code and reason code overview: The return_code variable provides a general indication of the
results of verb processing and is the value that your application program should generally use in
determining the course of further processing. For a list of return codes and their meanings, see Table 79
on page 561.

The reason_code variable provides more specific information about the outcome of verb processing.
Reason code values generally differ between CCA product implementations. Therefore, the reason code
values should generally be returned to individuals who can understand the implications in the context of
your application on a specific platform.
See Appendix A, Return codes and reason codes for a detailed discussion of return codes and a
complete list of all return and reason codes.
Rule_array and other keyword parameters

Rule_array parameters and some other parameters use keywords to transfer information. Generally, a rule
array consists of a variable number of data elements that contain keywords that direct specific details of
the verb process. Almost all keywords, in a rule array or otherwise, are 8 bytes in length, and should be
uppercase, left-aligned, and padded on the right with space characters. Not all implementations fold
lowercase characters to uppercase, so you should always code the keywords in uppercase.
The number of keywords in a rule array is specified by a rule_array_count variable, an integer that defines
the number of (8-byte) elements in the array.
In some cases, a rule_array variable is used to convey information other than keywords between your
application and the server. This is, however, an exception.
Key tokens, key labels, and key identifiers

Essentially all cryptographic operations employ one or more keys. In CCA, keys are retained within a
structure called a key token. A verb parameter can point to a variable that contains a key token. Generally
you do not need to be concerned with the details of a key token and can deal with it as an entity. See
Key tokens and trusted blocks on page 577 for a detailed description of the key-token structures.
Key tokens are described as either internal, operational, or external, as follows:

Internal A key token that can contain an encrypted key, or in the case of AES and variable-length
symmetric key tokens, a clear key, for local use. The cryptographic engine decrypts an
encrypted internal key to use the key in a local operation. Once an encrypted key is
entered into the system, it is always encrypted if it appears outside of the protected
environment of the cryptographic engine. The engine has a special key-encrypting key
designated a master key. This key is held within the engine to wrap and unwrap locally
used keys.
Operational An internal key token that is complete and ready for use, and contains a usable key that is
typically encrypted under a master key. During entry of a key, the internal key-token can
have a flag set to indicate that the key information is incomplete. An incomplete key is not
an operational key.
External A key token that can contain a key that is either in the clear, or is encrypted by some
key-encrypting key other than the master key. Generally, when a key is to be transported
from place to place, or is to be held for a significant period of time, the key must be
encrypted with a transport key. A key wrapped by a (transport) key-encrypting key is
designated as being external.
RSA and ECC public keys are not encrypted values, and when not accompanied by
private-key information, are retained in an external key-token.
| Beginning with Release 4.2. support is added for a non-CCA TR-31 external key-token,
| called a key block in TR-31 terminology. A TR-31 key block cannot be stored in key
| storage.
Key tokens can be stored in a file that is maintained by the directory server. These key tokens are
referenced by use of a key label. A key label is an alphanumeric string that you place in a variable and
reference with a verb parameter.

Verb descriptions specify how you can provide a key using these terms:
Key token Unless otherwise noted in the parameter description, the variable must contain a proper
key-token structure.
Key label The variable must contain a key-label string used to locate a key record in key storage.
Key identifier The variable must contain either a key token or a key label. The first byte in the variable
defines if the variable contains a key token or a key label.
X'00' Indicates a null key-token.
X'01' - X'1F'
Indicates that the variable is to be processed as a key token.
X'20' - X'FE'
Indicates that the variable is to be processed as a key label. There are additional
restrictions on the value of a key label. See Key-label content on page 390.
X'FF' Indicates that an error condition is to be raised when passed to the API.
API verb organization in the remainder of this document

Now that you have a basic understanding of the API, you can find these topics in the remainder of the
book:
v Chapter 2, CCA node management and access control explains the organization of the cryptographic
engine and node. There are five topics:
Access-control administration
Controlling the cryptographic facility
Multi-coprocessor support
Master-key administration
Cryptographic key-storage initialization
Keeping cryptographic keys private or secret can be accomplished by retaining them in secure
hardware. Keeping the keys in secure hardware can be inconvenient or impossible if there are a large
number of keys, or the key has to be usable with more than one hardware device. In the CCA
implementation, an AES, APKA, DES or PKA master key is used to encrypt (wrap) locally used keys.
The master key itself is securely installed within the cryptographic engine and cannot be retrieved as an
entity from the engine.
v Chapter 3, PKA key-management explains how you can generate and protect RSA and ECC key-pairs.
The section also explains how you can control the distribution of the RSA private key for backup and
archival purposes, and to enable multiple cryptographic engines to use the key for performance or
availability considerations. Related services for creating and parsing PKA key-tokens are also described.
When you wish to backup an RSA private key, or supply the key to another node, you use a
double-length DES key-encrypting key, also called a transport key. It is useful to have a general
understanding of the DES key-management concepts found in Chapter 5, AES, DES, and HMAC
symmetric-key management.
v Chapter 4, Hashing and digital signatures explains how you can:
Provide for demonstrations of the integrity of data, that is, demonstrate that data has not been
changed
Attribute data uniquely to the holder of a private key
These problems can be solved using hashing and a digital signature. The section explains how you can
hash data (obtain a number that is characteristic of the data, a digest) and how you can use this to
obtain and validate a digital signature.
| v Chapter 5, AES, DES, and HMAC symmetric-key management explains the many services that are
| available to manage the generation, installation, verification, usage, and distribution of AES and DES

| keys. Chapter 9 explains TR-31 symmetric-key management. Added beginning with Release 4.2,
| Chapter 9 should be considered an extension of this chapter.
| An important aspect of DES key-management is the means by which these keys can be restricted to
| selected purposes. Deficiencies in key management provide the main means by which a cryptographic
| system can be broken. Controlling the use of a key and its distribution is almost as important as
| keeping the key a secret. CCA employs a non-secret quantity, the control vector, to determine the use
| of a key and thus improve the key security. Control vectors are described in detail in Appendix C, CCA
| control-vector definitions and key encryption.
v Chapter 6, Data confidentiality and data integrity explains how you can encrypt and decrypt (cipher)
data. The section also describes how you can use DES and HMAC to demonstrate the integrity of data
through the generation and verification of message authentication codes (MACs).
v Chapter 7, Key-storage mechanisms explains how you can label, store, retrieve, and locate keys in the
cryptographic-services access-layer-managed key storage.
v Chapter 8, Financial services support explains three groups of verbs of especial use in finance
industry transaction processing:
A suite of verbs for processing personal identification numbers (PINs) in various phases of
automated teller machine and point-of-sale transaction processing
Processing keys and information related to the Secure Electronic Transaction (SET) protocol
Verbs to generate and verify credit-card and debit-card security codes
| v Chapter 9, TR-31 symmetric-key management explains how to use the TR-31 interface to interchange
| DES and Triple-DES keys between CCA and non-CCA systems.
v Appendix A, Return codes and reason codes lists all of the numeric return codes and reason codes
that can be reported at the conclusion of verb processing, and provides an explanation of what each
return code and reason code means.
v Appendix B, Data structures describes AES, DES, variable-length symmetric, and PKA (both RSA and
ECC) key tokens, chaining-vector work areas of the Encipher, Decipher, MAC_Generate, and
MAC_Verify verbs, key-storage datasets and records, key-record-list datasets and records, the data
structures used in the access-control system, data structures containing cloning information and
master-key shares, and the function control vector distribution structure.
v Appendix C, CCA control-vector definitions and key encryption describes CCA DES key-token control
vector values, control-vector-base values, techniques to change the control vector associated with a
key, and the CCA key-encryption and key-decryption processes.
v Appendix D, Algorithms and processes describes cryptographic key-verification techniques, the four
versions of the Modification Detection Code calculation method supported by the MDC_Generate verb,
ciphering methods of the DES algorithm, MAC calculation methods, RSA key-pair generation, algorithms
and protocols used by the access-control system, the mathematical and cryptographic basis of the
master-key-splitting algorithm (m-of-n key shares scheme), and formatting hashes and keys in
public-key cryptography.
v Appendix E, Financial system verbs calculation methods and data formats describes PIN-calculation
methods, PIN-block formats, the ANS X9.24 derived unique-key-per-transaction calculation method, the
method used to generate a Visa card-verification value and a Mastercard card-verification code, and the
Visa and EMV-related smart card formats and processes.
v Appendix F, Verb list provides a list of all the CCA Support Program verbs by pseudonym, entry-point
name, and page number.
v Appendix G, Access-control-point codes lists all the access-control commands by hexadecimal offset,
and includes the command name, which verbs require the command to be enabled (by pseudonym and
entry-point name), and usage recommendations for the command.
v Appendix H, Observations on secure operations offers a series of observations about the setup and
use of a CCA cryptographic node to consider that could enhance secure operations, including ensuring
code levels match and IBM CCA code is installed, using access controls, using cryptographic keys,
using PIN data, and using coprocessor status data.
v Appendix I, Java Native Interface, on page 743 describes the Java Native Interface.

Chapter 2. CCA node management and access control
This section discusses:
v The access-control system that you can use to control who can perform various sensitive operations,
and at what times
v Controlling the cryptographic facility
v Understanding multi-coprocessor capabilities
v Understanding and managing master keys
v Initializing cryptographic key-storage
v Testing the random-number generator and known-answer tests.
Table 4 lists the verbs used to accomplish these tasks. See Using the CCA node, access control, and
master-key management verbs on page 34 for a detailed description of these verbs.
Table 4. CCA node, access control, and master-key management verbs
Entry Service
Verb Page Service point location
Access_Control_Initialization 35 Initializes or updates access-control tables in the coprocessor. CSUAACI E
Access_Control_Maintenance 38 Queries or controls installed roles and user profiles. CSUAACM E
Cryptographic_Facility_Control 42 Reinitializes the CCA application, sets the coprocessor clock, CSUACFC E
resets the intrusion latch, resets the battery-low indicator, sets
the CCA EID, sets the number of master-key shares required
and possible for distributing the DES or PKA master key,
loads or clears the CCA function control vector (FCV) that
manages international export and import regulation
limitations, initiates a hardware error (for testing purposes),
| loads, activates, and deletes PIN decimalization tables.
Cryptographic_Facility_Query 48 Retrieves information about the coprocessor and the state of CSUACFQ E
master-key-shares distribution processing.
Cryptographic_Facility_Version 58 Retrieves the CCA application version and the CCA CSUACFV E
application build date.
Cryptographic_Resource_Allocate 59 Connects subsequent calls to an alternative cryptographic CSUACRA S
resource (coprocessor).
Cryptographic_Resource_Deallocate 61 Reverts subsequent calls to the default cryptographic CSUACRD S
resource (coprocessor).
Key_Storage_Designate 63 Specifies the key-storage file used by the process. CSUAKSD S
Key_Storage_Initialization 65 Initializes one of the key-storage files that can store AES, CSNBKSI S/E
DES, variable-length symmetric, or PKA (both RSA and ECC)
keys.
Logon_Control 67 Logs a user on or off the coprocessor. CSUALCT E
Master_Key_Distribution 70 Supports the distribution and reception of DES and PKA CSUAMKD E
master-key shares.
Master_Key_Process 74 Enables the introduction of an AES, DES, APKA, or PKA CSNBMKP E
master key into the coprocessor, the random generation of a
DES or PKA master key, and the setting and clearing of the
AES, DES, APKA, or PKA master key registers.
Random_Number_Tests 78 Performs tests of the random-number generator and CSUARNT E
FIPS-mandated known-answer tests.
E=cryptographic engine, S=Security API host software
13
Using CCA access-control
This section describes these CCA access-control system topics:
v Understanding access control
v Role-based access control
v Initializing and managing the access-control system
v Logging on and logging off
v Protecting your transaction information
Understanding access control

Access control is the process that determines which CCA services or commands of the coprocessor are
available to a user at any given time.
Note: At the end of each CCA verb description, you find a list of commands that must be enabled to use
specific capabilities of the CCA verb.
The system administrator can give users differing authority so that some users have the ability to use CCA
services that are not available to others. In addition, a given user's authority might be limited by
parameters such as the time of day or the day of the week.
See Appendix H, Observations on secure operations, on page 725 for more information.
Role-based access control

This CCA implementation uses role-based access control. In a role-based system, the administrator
defines a set of roles, which correspond to the classes of coprocessor users. Each user is enrolled by
defining a user profile, which maps the user to one of the available roles. Profiles are described in
Understanding profiles on page 15.
Note: For purposes of this discussion, a user is defined as either a human user or an automated,
computerized process.
As an example, a simple system might have the following three roles:

General user
A user class which includes all coprocessor users who do not have any special privileges
Key-management officer
Those people who have the authority to change cryptographic keys for the coprocessor
Access-control administrator
Those people who have the authority to enroll new users into the coprocessor environment, and to
modify the access rights of those users who are already enrolled
Typically, only a few users are associated with the Key-Management Officer role, but a large population of
users associated with General User role. The Access-Control Administrator role is typically limited to a
single super user, because he can make any change to the access control settings. In some cases, once
the system is set up, it is desirable to delete all profiles linked to Access-Control Administrator roles to
prevent further changes to the access controls.
A role-based system is more efficient than one in which the authority is assigned individually for each user.
In general, users can be segregated into just a few different categories of access rights. The use of roles
allows the administrator to define each of these categories just once, in the form of a role.
Permissions and characteristics of roles

Each role defines the permissions and other characteristics associated with users having that role. The
role contains the following information:

Role ID
A character string which defines the name of the role. This name is referenced in user profiles, to
show which role defines the user's authority.
Required user-authentication strength level
The access-control system is designed to allow a variety of user authentication mechanisms. The
one that is available for use is passphrase authentication.
All user-authentication mechanisms are given a strength rating, namely an integer value where
zero is the minimum strength corresponding to no authentication at all. If the strength of the user's
authentication mechanism is less than the required strength for the role, the user is not permitted
to log on.
Valid time and valid days-of-week
The times of the day and the days of the week when the users with this role are permitted to log
on. If the current time is outside the values defined for the role, logon is not allowed. You can
choose values that let users log on at any time on any day of the week.
Notes:
1. Times are specified in Coordinated Universal Time (UTC).
2. If you physically move a coprocessor between time zones, remember that you must
resynchronize the CCA-managed clock with the host-system clock.
Permitted commands
A list defining which commands the user is allowed to perform in the coprocessor. Each command
corresponds to one of the primitive functions that collectively comprise the CCA implementation.
Comment
A 20-byte comment can be incorporated into the role.
In addition, the role contains control and error-checking fields. The detailed layout of the role data-structure
can be found in Role structures on page 638.
The default role: Every coprocessor must have at least one role, called the default role. Any user who
has not logged on and been authenticated can operate with the capabilities and restrictions defined in the
default role.
Requirement: Because unauthenticated users have authentication strength equal to zero, the Required
User-Authentication Strength Level of the Default Role must also be zero.
The coprocessor can have a variable number of additional roles, as needed and defined by the customer.
For simple applications, the default role by itself might be sufficient. Any number of roles can be defined,
as long as the coprocessor has enough available storage to hold them.
Understanding profiles
Any user who needs to be authenticated to the coprocessor must have a user profile. Users who only
need the capabilities defined in the default role do not need a profile.
A user profile defines a specific user to the CCA implementation. Each profile contains the following
information:
User ID
The name used to identify the user to the coprocessor. The user ID is an 8-byte value, with no
restrictions on its content. Although it is typically an unterminated ASCII (or EBCDIC on IBM i)
character string, any 64-bit string is acceptable. A utility program is used to enter the user ID. That
utility might restrict the ID to a specific character set.
Comment
A 20-byte comment can be incorporated into the profile.
Chapter 2. CCA node management and access control 15

Logon failure count
A count of the number of consecutive times the user has failed a logon attempt, due to incorrect
authentication data. The count is reset each time the user has a successful logon. The user is no
longer allowed to log on after three consecutive failures. This lockout condition can be reset by an
administrator whose role has sufficient authority.
Role ID
A character string that identifies the role that contains the user's authorization information. The
authority defined in the role takes effect after the user successfully logs on to the coprocessor.
Activation and expiration dates
Values that define the first and last dates on which this user is permitted to log on to the
coprocessor. An administrator whose role has the necessary authority can reset these fields to
extend the user's access period.
Authentication data
The information used to verify the identity of the user. It is a self-defining structure, which can
accommodate many different authentication mechanisms. In the current CCA implementation, user
identification is accomplished by means of a passphrase supplied to the Logon_Control verb.
The profile's authentication-data field can hold data for more than one authentication mechanism.
If more than one is present in a user's profile, any of the mechanisms can be used to log on.
Different mechanisms, however, might have different strengths.
The structure of the authentication data is described in Authentication data structure on page
643.
In addition, the profile contains other control and error-checking fields. The detailed layout of the profile
data-structure can be found in Profile structures on page 642.
Profiles are stored in non-volatile memory inside the secure module of the coprocessor. When a user logs
on, his stored profile is used to authenticate the information presented to the coprocessor. In most
applications, the majority of the users operate under the default role, and do not have user profiles. Only
the security officers and other special users need profiles.
Initializing and managing the access-control system

Before using a coprocessor with newly loaded or initialized CCA support, initialize roles, profiles, and other
data. It might also be necessary to update some of these values from time to time. Access-control
initialization and management are the processes used to accomplish this.
Initialize and manage the access-control system in either of two ways:

1. Use the IBM-supplied utility program for your platform:
v Cryptographic Node Management utility program (CNM) (not for IBM i)
Note: The Cryptographic Node Management utility is described in the IBM 4765 PCIe
Cryptographic Coprocessor CCA Support Program Installation Manual and in the IBM 4764
PCI-X Cryptographic Coprocessor CCA Support Program Installation Manual.
v IBM i Cryptographic Coprocessor Web-based configuration utility.
2. Write programs that use the access-control verbs described in this section.
Use the verbs to write programs that do more than the utility program. If your needs are simple, the utility
program might do everything you need.
Access-control management and initialization verbs

Two verbs provide all of the access-control management and initialization functions:
CSUAACI
Perform access-control initialization functions
CSUAACM
Perform access-control management functions
With Access_Control_Initialization, you can perform functions such as:

v Loading roles and user profiles
v Changing the expiration date for a user profile
v Changing the authentication data in a user profile
v Resetting the authentication logon failure-count in a user profile
Note: See Access_Control_Initialization (CSUAACI) on page 35 for additional information about this
verb.
With Access_Control_Maintenance, you can perform functions such as:

v Getting a list of the installed roles or user profiles
v Retrieving the non-secret data for a selected role or user profile
v Deleting a selected role or user profile from the coprocessor
v Getting a list of the users who are logged on to the coprocessor
Note: See Access_Control_Maintenance (CSUAACM) on page 38 for additional information about this
verb.
See Access-control data structures on page 638 for additional information about data structures.
Permitting changes to the configuration

You can set up the coprocessor so no one is authorized to perform any functions, including further
initialization. It is also possible to set up the coprocessor where operational commands are available but
not initialization commands, meaning you could never change the configuration of the coprocessor. This
happens if you set up the coprocessor with no roles having the authority to perform initialization functions.
Ensure that you define roles that have the authority to perform initialization, including the RQ-TOKEN and
RQ-REINT options of the Cryptographic_Facility_Control (CSUACFC) verb. You must also ensure there
are active profiles that use these roles.
If you configure the coprocessor so that initialization is not allowed, you can recover.
Important: To recover from this condition, all the data stored in the coprocessor, including master keys,
retained keys, roles, and profiles, will be destroyed. There is no way to recover retained keys
that have been destroyed.
On an IBM i software platform, instructions on how to reinitialize the coprocessor can be found in the
Troubleshooting article of the Cryptographic Coprocessor topic in the IBM i information center
(http://www.ibm.com/eserver/iseries/infocenter). On a software platform other than IBM i, use the
coprocessor load utility (CLU) and the file CRSxxyy.CLU to reset the coprocessor CCA software. This
deletes all information previously loaded. Then use CLU and the file CNWxxxyy.CLU to load a new copy of
the coprocessor CCA software. This restores the coprocessor's CCA function to its initial state.
Configuration and Coordinated Universal Time (UTC)

CCA always operates with UTC time. This means that the time, date, and day-of-the-week values in the
coprocessor are measured according to UTC. This can be confusing because of its effect on
access-control checking.
All users have operating time limits, based on values in their roles and profiles. These include:
v Profile activation and expiration dates
v Time-of-day limits
v Day-of-the-week limits

All of these limits are measured using time in the coprocessor's frame of reference, not the user's. If your
role says that you are authorized to use the coprocessor on days Monday through Friday, it means
Monday through Friday in the UTC time zone, not your local time zone. In like manner, if your profile
expiration date is December 31, it means December 31 in UTC.
In the Eastern United States, your time differs from UTC by 4 hours during the part of the year Daylight
Savings Time is in effect. At noon EDT, it is 4:00 PM UTC. At 8:00 PM EDT, it is midnight UTC, which is
the time that the coprocessor increments its date and day-of-the-week to the next day.
For example, at 7:00 PM EDT on Tuesday, December 30, it is 11:00 PM, Tuesday, December 30 to the
coprocessor. Two hours later, however, at 9:00 PM EDT, Tuesday, December 30, it is 1:00 AM Wednesday,
December 31 to the coprocessor. If your role only allows you to use the coprocessor on Tuesday, you
would have access until 8:00 PM on Tuesday. After that, it would be Wednesday in the UTC time frame
used by the coprocessor.
This happens because the coprocessor does not know where you are located, and how much your time
differs from UTC. Time zone information can be obtained from your local workstation or server, but this
information cannot be trusted by the coprocessor; it could be forged in order to obtain access at times the
system administrator intended to keep you from using the coprocessor.
Notes:
1. During the portions of the year when Daylight Savings Time is not in effect, the time difference
between EST and UTC is 5 hours.
2. In the IBM i environment, no translation is provided for Role and Profile names. The coprocessor
initializes the default role name to DEFAULT encoded in ASCII. Users of the IBM i CCA need to
consider the encoding of Role and Profile names.
Logging on and logging off

A user must log on to the coprocessor in order to activate a user profile and the associated role. This is
the only way to use a role other than the default role. You log on and log off using the Logon_Control verb,
which is described in Logon_Control (CSUALCT) on page 67.
When you successfully log on, the CCA implementation establishes a session between your application
program and the coprocessor's access-control system. Security Application Program Interface (SAPI)
stores the logon context information, which contains the session information needed by the host computer
to protect and validate transactions sent to the coprocessor. As part of that session, a randomly derived
session key, generated in the coprocessor, is subsequently used to protect information you interchange
with the coprocessor. This protection is described in Protecting your transaction information on page 19.
The logon process and its algorithms are described in Passphrase verification protocol on page 692.
With AIX, Linux, and Windows, the logon context information resides in memory associated with the
process thread that performed the Logon_Control verb. With IBM i, the logon context information resides in
memory owned by the process in which the application runs. Host-side logon context information can be
saved and shared with other threads, processes, or programs; see Using logon context information on
page 19.
Thus, with AIX, Linux, and Windows, each thread in any process can log on to the CCA access control
system within a specific CCA coprocessor. Because the coprocessor code creates the session key, and
the session key is stored in the active context information, a thread cannot concurrently be logged on to
more than one coprocessor.
In order to log on, you must prove the user's identity to the coprocessor. This is accomplished using a
passphrase, a string of up to 64 characters which are known only to you and the coprocessor. A good
passphrase meets the following criteria:
v Is not too short.

v Contains a mixture of alphabetic characters, numeric characters, and special symbols such as the
asterisk (*), the plus sign (+), exclamation point (!), and others.
v Is not comprised of familiar words or other information which someone might be able to guess.
When you log on, no part of the passphrase ever travels over any interface to the coprocessor. The
passphrase is hashed and processed into a key that encrypts information passed to the coprocessor. The
coprocessor has a copy of the hash and can construct the same key to recover and validate the logon
information. CCA does not communicate your passphrase outside of the memory owned by the calling
process.
When you have finished your work with the coprocessor, you must log off in order to end your session.
This invalidates the session key you established when you logged on, and frees resources you were using
in the host system and in the coprocessor.
Using logon context information

The Logon_Control verb offers the capability to save and restore logon context information through the
GET-CNTX and PUT-CNTX rule-array keywords.
The GET-CNTX keyword is used to retrieve a copy of your active logon context information, which you can
then store for subsequent use. The PUT-CNTX keyword is used to make active previously stored context
information. The coprocessor is unaware of what thread, program, or process has initiated a request. The
host CCA supplies session information from the active context information in each request to the
coprocessor. The coprocessor attempts to match this information with information it has retained for its
active sessions. Unmatched session information causes the coprocessor to reject the associated request.
As an example, consider a simple application that contains two programs, LOGON and ENCRYPT:
v The program LOGON logs you on to the coprocessor using your passphrase.
v The program ENCRYPT encrypts some data. The roles defined for your system require you to be
logged on in order to use the ENCIPHER function.
These two programs must use the GET-CNTX and PUT-CNTX keywords in order to work properly. They
work as follows:
LOGON
1. Log the user on to the coprocessor using the CSUALCT verb with the PPHRASE keyword.
2. Retrieve the logon context information using CSUALCT with the GET-CNTX keyword.
3. Save the logon context information in a place that is available to the ENCIPHER program. This
can be as simple as a disk file, or it can be something more complicated such as shared
memory or a background process.
ENCRYPT
1. Retrieve the logon context information saved by the LOGON program.
2. Restore the logon context information to the CCA API using the CSUALCT verb with the
PUT-CNTX keyword.
3. Encipher the data.
Important: Take care in storing the logon context information. Design your software so that the saved
context is protected from disclosure to others who might be using the same computer. If
someone is able to obtain your logon context information, they might be able to impersonate
you for the duration of your logon session.
Protecting your transaction information

When you are logged on to the coprocessor, the information transmitted to and from the CCA coprocessor
application is cryptographically protected using your session key. A MAC is used to ensure that the data

was not altered during transmission. Because this code is calculated using your session key, it also
verifies that you are the originator of the request, not someone else attempting to impersonate you.
For some verbs, it is also important to keep the information secret. This is especially important with the
Access_Control_Initialization verb, which is used to send new role and profile data to the coprocessor. To
ensure secrecy, some verbs offer a special protected option, which causes the data to be encrypted using
your session key. This prevents disclosure of the critical data, even if the message is intercepted during
transmission to the coprocessor.
Controlling the cryptographic facility

In addition to the three verbs that manage access control, there are six other verbs related to managing
various aspects of CCA coprocessors:
1. Cryptographic_Facility_Control. This verb manages some of the coprocessor status settings. See
Table 5 on page 21 for a summary of keyword-controlled coprocessor status settings that this verb can
change.
2. Cryptographic_Facility_Query. This verb lists coprocessor status information, some of which is user
controlled, and some of which is not. See Table 5 on page 21 for a summary of the coprocessor
information that this verb can query.
3. Cryptographic_Resource_Allocate. This verb causes requests to be routed to a specific CCA
coprocessor (resource) for use by a thread or process instead of being routed to a default
cryptographic resource.
4. Cryptographic_Resource_Deallocate. This verb stops requests from being routed to a specific CCA
coprocessor for use by a thread or process, and instead causes requests to be routed to a default
cryptographic coprocessor.
5. Key_Storage_Designate. This verb is unique to the IBM i implementation. It specifies which AES, DES,
or PKA key-storage file is used by a process.
6. Key_Storage_Initialization. This verb initializes an AES, DES, or PKA key-storage dataset using the
appropriate current master key. A key-storage dataset cannot be used until it has been initialized.

Table 5. Summary of available CCA coprocessor information
CSUACFQ CSUACFC
keyword CCA coprocessor status information keyword Related verbs
| NUM-DECT Size of PIN decimalization tables PINTB-LD, CSNBPGN, CSNBCPA, CSNBEPG,
| (Rel. 4.2 or later) output structures returned by PINTB-RM, and CSNBPVR with Use Only Valid
| CSUACFQ keyword STATDECT PINTB-AC Decimalization Tables command
STATAES AES new-master-key (NMK) register RQ-REINT CSNBMKP with keywords AES-MK
(Release 3.30 or status and either CLEAR, FIRST, MIDDLE,
later) LAST, or SET
AES current-master-key (CMK) register RQ-REINT CSNBMKP with keywords AES-MK
status and SET
AES old-master-key (OMK) register RQ-REINT CSNBMKP with keywords AES-MK
status and either SET or CLR-OLD
AES key-length enablement LOAD-FCV, CSNBSAD and CSNBSAE
CLR-FCV
STATAPKA APKA NMK register status RQ-REINT CSNBMKP with keywords APKA-MK
(Release 4.1 or and either CLEAR, FIRST, MIDDLE,
later) LAST, or SET
APKA CMK register status RQ-REINT CSNBMKP with keywords APKA-MK
and SET
APKA OMK register status RQ-REINT CSNBMKP with keywords APKA-MK
and either SET or CLR-OLD
ECC key-agreement services LOAD-FCV, CSNDDSG and CSNDDSV
enablement CLR-FCV
STATCCA DES NMK register status RQ-REINT CSNBMKP with keywords SYM-MK
and either CLEAR, FIRST, MIDDLE,
LAST, or SET
DES CMK register status RQ-REINT CSNBMKP with keywords SYM-MK
and SET
DES OMK register status RQ-REINT CSNBMKP with keywords SYM-MK
and either SET or CLR-OLD
CCA application version
CCA application build date
User role ID RQ-REINT CSUAACI with keyword INIT-AC,
CSUALCT with keyword LOGON, all
verbs that have one or more required
commands

Table 5. Summary of available CCA coprocessor information (continued)
CSUACFQ CSUACFC
STATCCAE DES NMK register status RQ-REINT Same as STATCCA
DES CMK register status RQ-REINT Same as STATCCA
DES OMK register status RQ-REINT Same as STATCCA
CCA application version
CCA application build date
User role ID RQ-REINT Same as STATCCA
PKA NMK register status RQ-REINT CSNBMKP with keywords ASYM-MK
and either CLEAR, FIRST, MIDDLE,
LAST, or SET
PKA CMK register status RQ-REINT CSNBMKP with keywords ASYM-MK
and SET
PKA OMK register status RQ-REINT CSNBMKP with keywords ASYM-MK
and either CLR-OLD or SET
STATCRD2 Number of installed coprocessors
(Release 4.0 or
DES hardware level
later) or
STATCARD RSA hardware level
(before Release POST0 and POST1 version
4.0)
Operating system name
Operating system version
Part number (version)
EC level
Miniboot version
CPU speed
Coprocessor ID
Flash memory size
DRAM memory size
Battery-backed memory size
Serial number
POST2 version (STATCRD2 keyword
only)
| STATDECT (Rel. Contents of PIN decimalization tables PINTB-LD, CSNBPGN, CSNBCPA, CSNBEPG,
| 4.2 or later) stored on coprocessor PINTB-RM, and CSNBPVR with Use Only Valid
| PINTB-AC Decimalization Tables command

CSUACFQ CSUACFC
STATDIAG Battery state RESETBAT
Intrusion latch state RESET-IL
Error log status
Mesh intrusion
Low voltage detected
High voltage detected
Temperature range exceeded
Radiation detected (IBM 4764 only)
Last five commands run
Last five return codes or reason codes
STATEID Node environment identifier SET-EID, CSNBMKP with keyword OBTAIN;
RQ-REINT CSNDPKG if token contains public-key
certificate section (X'42') with EID tag
(X'51'); CSNDSYG, CSNDSYI, or
CSNDSYX with keyword PKA92
STATEXPT Base CCA services availability LOAD-FCV, Setting currently ignored
CLR-FCV
| CDMF availability (IBM 4758 only) LOAD-FCV, CSNBMKP with keywords AES-MK
CLR-FCV and SET
56-bit DES availability LOAD-FCV, CSNBDEC or CSNBENC with DES
CLR-FCV keyword and single-length key
Triple-DES availability LOAD-FCV, CSNBDEC or CSNBENC with DES
CLR-FCV keyword and double-length key
SET services availability LOAD-FCV, CSNDSBC and CSNDSBD
CLR-FCV
Maximum modulus for symmetric key LOAD-FCV, CSNDPKD, CSNDPKE, CSNDPKX,
encryption CLR-FCV CSNDSYG, CSNDSYI, CSNDSYX,
and CSUAMKD
STATMOFN Master-key shares generation SET-MOFN, CSUAMKD; CSNBMKP with keyword
RQ-REINT CLEAR or SET
Master-key shares reception SET-MOFN, CSUAMKD; CSNBMKP with keyword
m SET-MOFN, CSUAMKD; CSNBMKP with keyword
n SET-MOFN, CSUAMKD; CSNBMKP with keyword
TIMEDATE Date SETCLOCK CSUALCT
Time SETCLOCK CSUALCT
Day of the week SETCLOCK CSUALCT

CSUACFQ CSUACFC
WRAPMTHD Default wrapping method for internal WRAPMTHD CSNBCKI, CSNBCKM, CSNBDKM,
DES keys CSNBDKG, CSNBKGN, CSNBKIM,
CSNBKPI, CSNBKTC, CSNDSYG, and
CSNDSYI
Default wrapping method for external WRAPMTHD CSNBCVT, CSNBDKX, CSNBKET,
DES keys CSNBKEX, CSNBKGN, CSNBKTR,
CSNBPEXX, CSNDRKX, and
CSNDSYG
Hardware error for testing purposes ERRINJ1
The Cryptographic_Facility_Query verb enables you to obtain the status of the CCA node. You specify one
of several status categories, and the verb returns that category of status. Status information you can
obtain includes:
| v The size and contents of PIN decimalization tables, if any, stored on the coprocessor.
v The condition of the AES, DES, or PKA new, current, and old master-key registers: clear, contains a
partially complete key, or contains a complete key. The extended CCA status returns information about
both the DES and the PKA master-key-register sets.
v The name of the role ID in effect for your processing thread (the active role).
v Information about the coprocessor hardware including the unique 8-byte IBM serial number. This serial
number is also printed on the label on the coprocessor's mounting bracket.
v Information about the coprocessor's operating system.
v The state of the coprocessor's battery: OK or change the battery within at most two weeks.
v Various tamper indications. This information is also returned in X'8040xxxx' status messages, for
example, when using the coprocessor load utility (CLU).
v Export status information about available algorithms.
v Information about master-key shares distribution for master-key cloning.
v Time and date from the coprocessor's internal clock, used to control access.
| v The environment ID (EID), which is a 16-byte identifier. It is used in the PKA92 key
| encryption/decryption scheme, when generating an RSA token from a skeleton token that contains an
| RSA public-key certificate section (X'40') that includes an EID tag (X'51'), and in master-key cloning.
| See PKA92 key format and encryption process on page 674. Assign an EID to represent the
| coprocessor node.
v Diagnostic information that could be of value to product development in the event of malfunction.
The Cryptographic_Facility_Control verb enables you to:

| v Load, activate, or remove PIN decimalization tables onto or from the coprocessor.
v Reinitialize (zeroize) the CCA node. This is a two-step process that requires your application to compute
an intermediate value as insurance against any inadvertent reinitialization action. The two steps must be
completed within 5 minutes of each other.
| v Cause a simulated coprocessor hardware error.
| Note: This capability is not supported on IBM i.

v Reset the intrusion latch.
Note: This capability is not supported on IBM i.

The intrusion latch circuit can be set by breaking an external circuit connected to jack on the
coprocessor. Normally the pins of this jack are connected to each other with a jumper. Contact IBM

support for more information about possible use of the intrusion latch. Setting the intrusion latch does
not cause zeroing of the coprocessor. To determine the intrusion latch state, use the STATDIAG
rule-array option of the Cryptographic_Facility_Query verb. See Cryptographic_Facility_Query
(CSUACFQ) on page 48 for more information.
v Reset the battery-low indicator (latch). The coprocessor electronics sets the battery-low indicator when
the reserve power in the battery falls below a predetermined level as tested during power-up. You
acknowledge and reset the battery-low condition using the RESETBAT rule-array keyword. If the battery
has not been replaced, expect the low-battery-power condition to return.
v Set parameters into the CCA node, other than those related to the access-control system, including: the
date and time, the function control vector used to establish the usage capabilities of certain
cryptographic functions, the EID, and the maximum number of master-key-cloning shares, and the
minimum number of shares needed to reconstitute a master key.
The Key_Storage_Initialization verb is used to establish a fresh symmetric (AES or DES) or asymmetric
(PKA) key-storage dataset. The dataset that holds the key records is initialized with header records that
contain a verification pattern for the applicable master key. Any existing key records in the key storage are
lost if you initialize the key-storage dataset. The index file associated with the key-record file is also
initialized. The file names and paths for the key storage and its index file are obtained from different
sources depending on the operating system:
Table 6. Key-storage location by operating system
Source AIX Linux Windows
ODM registry X
Environment variables X
Registry X
See the CCA Support Program Installation Manual for more information.
Restriction: The IBM i does not use an index file, nor does it provide master-key verification information
in the key-storage dataset.
The Cryptographic_Resource_Allocate and Cryptographic_Resource_Deallocate verbs allow your

application to steer requests to one of possibly multiple coprocessors.
Multi-coprocessor capabilities
Multi-coprocessor capabilities allow you to employ more than one coprocessor, some or all of which might
be loaded with the CCA application. When more than one coprocessor with CCA is installed, an
application program can explicitly select which cryptographic resource (coprocessor) to use, or it can
optionally employ the default coprocessor. To explicitly select a coprocessor, use the
Cryptographic_Resource_Allocate verb. This verb allocates a coprocessor loaded with the CCA software.
Once allocated, CCA requests are routed to it until it is deallocated. To deallocate an allocated
coprocessor, use the Cryptographic_Resource_Deallocate verb. When a coprocessor is not allocated
(either before an allocation occurs or after the cryptographic resource is deallocated), requests are routed
to the default coprocessor.
To determine the number of CCA coprocessors installed in a machine, or in an IBM i partition, use the
Cryptographic_Facility_Query verb with the STATCRD2 (Release 4.0 or later) or STATCARD (before
Release 4.0) rule-array keyword. The verb returns the number of coprocessors running CCA software. The
count includes any coprocessors loaded with CCA user defined function (UDX) code.
When using multiple coprocessors, consider the implications of the master keys in each of the
coprocessors. See Master-key considerations with multiple CCA coprocessors on page 31. You must also
consider the implications of a logged-on session. See Logging on and logging off on page 18.
When you log on to a coprocessor, the coprocessor creates a session key and communicates this to the
CCA, which saves the key in a session-context memory area. If your processing alternates between
coprocessors, be sure to save and restore the appropriate session context information.
Using a multi-coprocessor CCA in IBM i host systems varies from that in the other environments. The
following sections describe each approach:
v IBM i multi-coprocessor
v AIX, Linux, and Windows multi-coprocessor
IBM i multi-coprocessor support

The kernel-level code detects all new coprocessors at IPL time and assigns them a resource name in the
form of CRP01, CRP02, and so forth. In order to use a coprocessor, a user must create a cryptographic
device description object. When creating the device description object, the user specifies the cryptographic
resource name. The name of the device description object itself is completely arbitrary. For example, a
user might call the object BANK1CRYPTO, or CRP01. The device-description-object name has no bearing
on which resource it names. A user might create a device-description-object named CRP01 that internally
names the CRP03 resource. (Unless you are intentionally renaming a resource, such a practice would
likely lead to confusion.) With the Cryptographic_Resource_Allocate and
Cryptographic_Resource_Deallocate verbs, you specify a device-description-object name (and not an IBM
i resource name). If no device has been allocated, the CCA defaults to use of the object named CRP01, if
any. If no such object exists, the verb ends abnormally.
Note: The scope of the Cryptographic_Resource_Allocate verb and the

Cryptographic_Resource_Deallocate verb is a process. All threads within the process employs the
same coprocessor. Carefully consider the implications to additional threads if you employ these
verbs.
AIX, Linux, and Windows multi-coprocessor support

With the first call to CCA from a process, CCA associates coprocessor designators CRP01, CRP02, and
so on with specific coprocessors. The host determines the total number of coprocessors installed through
a call to the coprocessor device driver. The device driver designates the coprocessors using numbers 0, 1,
..., 7. The number assignment is based on the design of the BIOS in a machine. BIOS routines walk the
bus to determine the type of device in each PCI and PCI-X slot. Adding, removing, or relocating
coprocessors can alter the number associated with a specific coprocessor. The host then polls each
coprocessor in turn to determine which ones contain the CCA application. As each coprocessor is
evaluated, the CCA host associates the identifiers CRP01, CRP02, and so forth to the coprocessors with
CCA. Coprocessors loaded with a UDX extension to CCA are also assigned a CRP0x identifier.
In the absence of a specific coprocessor allocation, the host code employs the device designated CRP01
by default. You can alter the default designation by explicitly setting the CSU_DEFAULT_ADAPTER
environment variable. The selection of a default device occurs with the first CCA call to a coprocessor.
Once selected, the default remains constant throughout the life of the thread. Changing the value of the
environment variable after a thread uses a coprocessor does not affect the assignment of the default
coprocessor.
If a thread with an allocated coprocessor ends without first deallocating the coprocessor, excess memory
consumption results. It is not necessary to deallocate a cryptographic resource if the process itself is
ended; it is only suggested if individual threads end while the process continues to run.
Note: The scope of the Cryptographic_Resource_Allocate and the Cryptographic_Resource_Deallocate

verbs is operating-system dependent. For AIX, Linux, and Windows, these verbs are scoped to a
thread, a process in which each of several threads within a process can allocate a specific
coprocessor.

A multithreaded application program can use all of the installed CCA coprocessors simultaneously. A
program thread can use only one of the installed coprocessors at any given time, but it can switch to a
different installed coprocessor as needed. To perform the switch, a program thread must deallocate an
allocated cryptographic resource, if any, and then it must allocate the desired cryptographic resource. The
Cryptographic_Resource_Allocate verb fails if a cryptographic resource is already allocated.
Understanding and managing master keys

In a CCA node, AES, DES, APKA, and PKA master keys are used to encrypt or wrap working keys used
by the node that can appear outside of the cryptographic engine. The AES and ECC keys are encrypted
using 32-byte keys. The DES and RSA working keys are Triple-DES encrypted. Beginning with Release
4.1, DES working keys can be encrypted by a more secure method than Triple-DES using ECB mode.
This method is called the enhanced key-wrapping method, and is explained in Triple-DES key wrapping
on page 142. These methods of securing keys enables a node to operate on an essentially unlimited
number of working keys, without concern for storage space within the confines of the secured
cryptographic engine.
The CCA design supports a set of three master-key registers for each master key: new, current, and old.
While a master key is being assembled, it is accumulated in the new-master-key register, then the
Master_Key_Process verb is used to transfer the contents of the new-master-key register to the
current-master-key register.
Working keys are normally encrypted by their associated current master key. To facilitate continuous
operations, CCA also has an old-master-key register. When a new master-key is transferred to the
current-master-key register, the preexisting contents, if any, of the current-master-key register are
transferred to the old-master-key register. With CCA, whenever a working key must be decrypted by the
master key, master-key verification pattern information that is included in the key token is used to
determine if the current or the old master-key must be used to recover the working key. Special status
(return code 0, reason code 10001) is returned in case of use of the old master-key so that application
programs can arrange to have the working key updated to encryption by the current master-key (using the
Key_Token_Change and PKA_Key_Token_Change verbs). Whenever a working key is encrypted for local
use, it is encrypted using the current master-key.
Symmetric and asymmetric master keys

CCA incorporates the following sets of master-key registers:
v The DES master-key register set is used to encrypt and decrypt DES (symmetric) working keys.
v The PKA master-key register set is used to encrypt and decrypt RSA (asymmetric) private working keys.
v The AES master-key register set is used to encrypt and decrypt AES (symmetric) and variable-length
symmetric working keys. Variable-length symmetric keys are introduced to CCA beginning with Release
4.1.
v The APKA master-key register set, introduced to CCA beginning with Release 4.1, is used to encrypt
and decrypt the Object Protection Key (OPK) that is itself used to wrap the key material of an Elliptic
Curve Cryptography (ECC) key. ECC keys are asymmetric.
The verbs that operate on the master keys permit you to specify a register set (with keywords AES-MK,
APKA-MK, SYM-MK and ASYM-MK). For DES and PKA master keys, if applications that modify these
master-key registers never explicitly select a register set, the master keys in the two register sets are
modified in the same way and contain the same keys. However, if at any time you modify only one of the
DES or PKA register sets, applications thereafter need to manage the two register sets independently.
Using the Cryptographic Node Management (CNM) utility to manage DES and PKA master keys results in
operating as though there were only a single set of DES and PKA master key registers. If another program
is used to modify a register in only one of the DES or PKA register sets, the CNM utility is no longer

usable for updating these master keys until they are set to equal again. The AES and APKA master key
registers work independently from the DES and PKA registers.
Establishing master keys

An AES master key is established from clear key parts (components). Beginning with Release 4.1, an
APKA master key is also established from clear key parts. DES and PKA master keys are established in
one of three ways:
v From clear key parts
v Through random generation internal to the coprocessor
v Copying encrypted master-key shares, called cloning
Establishing a master key from clear information
Individual key parts are supplied as clear information, and the parts are exclusive-ORed within the
cryptographic engine. Knowledge of a single part gives no information about the final key when
multiple, random-valued parts are exclusive-ORed.
| A common technique is to record the values of the parts (typically on paper or diskette) and
| independently store these values in locked safes. For customers who have implemented the
| optional smart card hardware, the CNM utility can be used to store the master key parts securely
| onto individual smart cards and loaded onto a coprocessor. When installing the master key,
| individuals trusted to not share the key-part information retrieve the parts and enter the information
| into the cryptographic engine. Use the Master_Key_Process verb for this operation.
Entering the first and subsequent parts is authorized by two different control points so that a
cryptographic engine, the coprocessor, can enforce that two different roles, and thus profiles, are
activated to install the master-key parts. This requires that roles exist that enforce this separation
of responsibility.
Setting the master key uses a unique command with its own control point. You can set up the
access-control system to require the participation of at least three individuals or three groups of
individuals.
You can check the contents of any of the master-key registers, and the key parts as they are
entered into the new-master-key register, using the Key_Test verb. The verb performs a one-way
function on the key-of-interest, the result of which is either returned or compared to a known
correct result.
Establishing a DES or PKA master key from an internally generated random value
The Master_Key_Process verb can be used to randomly generate a new DES or PKA master key
within the cryptographic engine. The value of the new master-key is not available outside of the
cryptographic engine. The verb does not support random generation of an AES master key.
This random method, which is a separately authorized command invoked through use of the
Master_Key_Process verb, ensures that no one has access to the value of the master key.
Randomly generating a master key is useful when the shares technique described next is used,
and when keys shared with other nodes are distributed using public key techniques or when DES
transport keys are established between nodes. In these cases, there is no need to reestablish a
master key with the same value.
Cloning a DES or PKA master key from one cryptographic engine to another cryptographic engine
In certain high-security applications, it is desirable to copy a master key from one cryptographic
engine to another without exposing the value of the master key. Do this by cloning the DES or
PKA master key, splitting the master key into n shares, of which m shares, 1mn15, reconstitute
the master key in another engine.
Note: Neither an AES nor an APKA master key can be cloned.

The term cloning is used to differentiate the process from copying because no one share, or any
combination of fewer than m shares, provide sufficient information needed to reconstitute the
master key.
For this secure master-key cloning process, use the CNM utility. See Chapter 5 and Appendix D of
the IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual or the
IBM 476 PCI-X Cryptographic Coprocessor CCA Support Program Installation Manual. The utility
can hold the certificates and shares in a database that you can transport on diskette between the
various nodes:
v The certifying node public-key certificate
v The coprocessor master-key share-source node public-key certificate
v The coprocessor master-key share-receiving node public-key certificate
v The master-key shares
You establish the m and n values using the Cryptographic_Facility_Control verb.
Shares of the current master-key are obtained using the Obtain mode of the
Master_Key_Distribution verb. The Receive mode of the Master_Key_Distribution verb is used to
enter an individual share into the receiving (target) cryptographic engine. When sufficient shares
have been entered, the verb returns status (return code 4, reason code 1024) that indicates the
cloned master-key is now complete within the new-master-key register of the target cryptographic
engine.
The master-key shares are signed by the source engine. Each signed share is then
triple-encrypted by a fresh triple-length DES key, the share-encrypting key. A certified public-key
from the target cryptographic-engine is validated, and the share-encrypting key is wrapped using
the public key from the certificate.
At the target cryptographic-engine, an encrypted share and the wrapped share-encrypting key are
presented to the engine. The private key to unwrap the share-encrypting key must exist within the
cryptographic engine as a retained key (a private key that never leaves the engine). This private
key must also have been marked as suitable for operation with the Master_Key_Distribution verb
when it was generated.
When receiving a share, you must also supply the share-signing key in a certificate to the
Master_Key_Distribution verb. The engine validates the certificate, and uses the validated public
key to validate the individual master-key share.
The certificates used to validate the share-signing public key and the target-engine public key
used to wrap the share-encrypting key are validated by the cryptographic engines using a retained
public key. A retained public key is introduced into a cryptographic engine in a two-part process
using the PKA_Public_Key_Hash_Register and PKA_Public_Key_Register verbs. This enables you
to establish two distinct roles to enforce dual control. Two different individuals are authorized so
that split authority and dual control can be enforced in setting up the certificate validating public
key.
You identify the nodes with unique 16-byte identifiers of your choice. The environment ID (EID) is
also established using the Cryptographic_Facility_Control verb.
The processing of a given share (share 1, 2, ..., n) requires authorization to a distinct control point
so that you can enforce split responsibility in obtaining and installing the shares.
The certifying node can be any of the following:
v Share source node
v Share target node
v Independent node that might be located in a cryptographic control center
You must initialize the target coprocessor with its retained private key and have the associated
public key certified before you obtain shares for the target coprocessor. This implies that the target
coprocessor has been initialized and is not reset before a master key is cloned to the coprocessor.

3.
Shareadministration control point

Audit 2

Generate, 3 |
self-certify, | |
distribute
CERT{SA}(SA) H(CERT{SA}(SA))

CCA cryptographic engine CCA cryptographic engine
source node target node

1 Roles, Profiles, Roles, Profiles,
1
m_of_n, EID m_of_n, EID

2
Audit Audit 2

4
4

5
5

Certify by SA

Generate CSS 6
Pu{CSS}
CERT{SA}(Pu{CSS})

Pu{CSR_i} 7 Generate CSR

CERT{SA}(Pu{CSR_i})

8

Pu{CSR_i}(SE_j),
e*SE_j(j,mks_j,SIG{CSS}(j,mks_j))
9
(m times)

Verify then Set
10
the master key

Figure 2. Coprocessor-to-coprocessor DES or RSA master-key cloning
Figure 2 depicts the steps of a master-key cloning scenario. These steps include:
1. Install appropriate access-control roles and profiles, m-of-n, and EID values. Have operators change
their profile passwords. Ensure that the roles provide the degree of responsibility-separation that you
require.
2. Audit the setup of the share administration, share source, and share receiving nodes.
3. Generate a retained RSA private key, the Share-Administration (SA) key. This key is used to certify
the public keys used in the scheme. Self-certify the SA key. Distribute the hash of this certificate to
the source and share-receiving nodes under dual control.
4. Install (register) the hash of the SA public-key in both the source and receiving nodes. Two different
roles can be used to permit this and the next step to aid in ensuring dual control of the cloning
process.
5. Install (register) the SA public-key in both the source and receiving nodes.
6. In the source node, generate a retained key usable for master-key administration, the coprocessor
share signing (CSS) key, and have this key certified by the SA key.

7. In the target node, generate a retained key usable for master-key administration, the coprocessor
share receiving (CSR) key, and have this key certified by the SA key.
8. Once a master key has been established in the source node, for example through random master-key
generation, obtain shares of the master key. Also obtain master-key verification information for use in
step 10 using the Key_Test verb. Generally, fewer shares are required to reconstitute the master key
than that which can be obtained from the source node.
9. Deliver and install the master-key shares.
10. Use the Key_Test verb to verify that the new master-key in the target node has the proper value.
Then set the master key.
Master-key considerations with multiple CCA coprocessors

Master keys are used to wrap working keys (as opposed to clear keys or keys wrapped by key-encrypting
keys, RSA keys, or ECC keys). Master-key-wrapped keys are either stored in the CCA key storage, or are
held and managed by your application or applications. When multiple coprocessors are installed, it is a
responsibility of the using organization to ensure that appropriate current and old master-keys, both
symmetric and asymmetric, are installed in the multiple coprocessors. The most straightforward approach
is to ensure that when you change master keys on one CCA coprocessor, you also change the master
keys (both asymmetric and symmetric) on the other coprocessors.
The approach to multiple coprocessors differs in detail between IBM i and the workstation or server
environments. Each type of environment is discussed:
v IBM i
v AIX, Linux, and Windows
IBM i multi-coprocessor master-key support

Load all CCA coprocessors with the same current and the same old master-keys, especially if your
applications perform load balancing among the coprocessors or if the coprocessors are used for SSL.
With IBM i, multiple key-storage files can exist. To avoid confusion, keep all keys in the key-storage files
encrypted by a common, current master-key. The master-key verification pattern is not stored in the
header record of any key-storage file. Therefore, it is important that when you change the master key, you
reencipher all of the keys in all of your key-storage files. The organization that manages all users of the
coprocessors must arrange procedures for keeping all key-storage files up to date with the applicable
current master-key. The person changing the master key might not have authorization to, or knowledge of,
all key-storage files on the system.
The order for loading and setting of the master key between coprocessors is not significant. However, be
sure that after all coprocessor master keys have been updated that you then update all key-storage files.
Remember that if you import a key or generate a key, it is returned encrypted by the current master key
within the coprocessor used for the task.
AIX, Linux, and Windows multi-coprocessor master-key support

All of the CCA coprocessors within the system should use the same current and old master keys. When
setting a new master-key, it is essential that all of the changes are performed by a single program running
on a single thread. If the thread-process is ended before all of the coprocessor master-keys are changed,
significant complications can arise. It is suggested that you start the CNM utility and use it to make all of
the changes before you end the utility.
If you fail to change all of the master keys with the same program running on the same thread, either
because there is an unplanned interruption, or perhaps because you intend to have different master keys
between coprocessors, you need to understand the design of the CCA host code that is described next.
CCA host code design (AIX, Linux, and Windows)

CCA keeps a copy of the symmetric (AES or DES) or the asymmetric (PKA) current master-key verification
pattern in the key-storage header records. This information is used to ensure that a given key-storage file

is associated with a coprocessor having the same current master-key. This can prevent accessing an
out-of-date key-storage backup file. The verification pattern is written into the header record when key
storage is initialized, and when the current master-key is changed in a coprocessor.
CCA keeps two flags in memory associated with a host-processing thread. If there are multiple threads,
each thread has its own set of flags. Both flags, symmetric-directory-open (SDO) and
asymmetric-directory-open (ADO), are set to false when CCA processing begins on the thread.
When a CCA verb is called and a key storage is referenced, and if the associated flag (SDO or ADO) is
false, CCA obtains the verification pattern for the current master-key and compares this to the
header-record information. If the patterns match, the flag is set to true, and processing continues. If the
existing patterns do not match, processing ends with an error indication. If there is no current master key
or if key storage has not been initialized, processing continues although, depending on the CCA verb,
other error conditions might arise.
A key-storage reference occurs in two cases:

v When the verb call employs a key label
v When the SET master-key option is used on the Master_Key_Process verb
Situations to consider
When you employ multiple coprocessors with CCA, consider the following cases regarding DES and PKA
master keys. Remember that if you explicitly manage the DES (symmetric) or the PKA (asymmetric)
master keys (using the SYM-MK or ASYM-MK keywords with the Master_Key_Process verb), you have
both master keys and both key storages to consider. If you do not explicitly manage these two classes of
master keys, then CCA operates as though there is a single set of DES and PKA master keys. The CNM
utility provided with the CCA program does not explicitly manage the two sets of keys, and the program
design assumes that the DES and PKA master keys have always been managed without explicit reference
to the symmetric or the asymmetric keys.
Setting master keys in multiple coprocessors
If you keep the DES and PKA master keys the same in all of the CCA coprocessors, and you set
the master key in each of the coprocessors from a single program running on the same thread,
the following steps take place:
v When all of the coprocessors are newly initialized, that is, their current-master-key registers are
clear, install the same master key in each of the DES and PKA new-master-key registers. Then
set the master key in each of the coprocessors. Finally, if you are going to use DES or PKA
key-storage, initialize key storage.
v If all of the coprocessors have the same DES and PKA current master-key, when you undertake
to set the master key in the first coprocessor, the code attempts to set the directory-open flags
(SDO and ADO). This succeeds if you have the proper key-storage files (or key storage is not
initialized). The verification pattern in the key-storage header is changed as soon as the first
master key is set.
When you set the master key in the additional coprocessors, because the directory-open flags
are already set, no check is made to ensure that the verification patterns in key storage and for
the current master-key match (and they would not match because the header was updated
when the first coprocessor master-key was set). As soon as the master key is set, its
verification pattern is copied to the header in key storage.
The key in the new-master-key register is not verified. You might want to confirm the proper and
consistent contents of these registers using the Key_Test verb prior to undertaking setting of the
master keys.
Setting the master key in a coprocessor after other coprocessors are successfully in operation
If you have one or more coprocessors in operation, and then wish to do the following:
v Add an additional coprocessor
v Set its current, and possibly old, master keys to the keys already in the other coprocessors

Consider the following cases:
1. If the new coprocessor has a current master key that is not the same as that in the other
coprocessors, and if key storage is initialized for use with the other coprocessors, when you
start a new thread and attempt to set the master key, the action fails unless you take
precautions. Because the directory-open flags are initially set to false, the CCA host code
compares the verification pattern for the current master-key in the coprocessor and in the
key-storage header record. This comparison fails and processing ends with an error indication.
2. If the new coprocessor did not have a key in the current-master-key register, the
set-master-key operation proceeds. The verification pattern for this master key is copied to an
initialized key-storage header record.
A solution to the first situation is to proceed as follows:
v Allocate a coprocessor that has the desired current master key or keys
v Perform a DES_Key_Record_List or other action that causes the key-storage-valid flags to be
set.
v Deallocate the coprocessor
v Allocate the new coprocessor
v Set the master key
You might need to install two master keys into the new coprocessor in order to have both the
current and the old master keys agree with those in the other coprocessors.
Intentionally using different master keys in a set of coprocessors
This situation becomes very complicated if you are using key storage with a subset of the
coprocessors. If you are not using key storage and have not initialized key storage files, just load
and set the master keys as you would in a single-coprocessor situation.
While you are changing master keys in a multiple-coprocessor arrangement, it might be undesirable to
continue other cryptographic processing. Consider the following possibilities:
v Keys generated or imported and returned enciphered with the latest master key are not usable with
other coprocessors until they too have been updated with the latest master key. Existing keys might still
be usable because the previous master key in the updated coprocessors are in the old-master-key
register and CCA can use this to recover the working keys.
v The header record in the key-storage file might have been altered to an undesirable valuerefer to the
earlier discussion.
v When the Master_Key_Process verb is used to set the master key without specifying a master-key
register class keyword, you need to have both the DES and PKA key-storage files initialized, even if you
do not place keys in one or both of the key storages files.
Initializing cryptographic key-storage

| Key storage is an external repository of keys that you access by key label, using user-defined labels.
| There are three separate external key-storage datasets: AES, DES, and PKA. Fixed-length AES and
| variable-length AES key tokens are stored in the AES dataset. DES key tokens are stored in the DES
| dataset. RSA and ECC key tokens are stored in the PKA dataset.
| Note: Keys stored in the coprocessor (master keys and RSA retained keys) are not considered part of
| external key-storage. The coprocessor has limited internal storage for RSA retained keys.
Use the Key_Storage_Initialization (CSNBKSI) verb to initialize an AES, DES, or PKA key-storage file.
Before using the Key_Storage_Initialization verb, you must establish the appropriate master keys.

Testing the random-number generator and known-answer tests
The U.S. National Institute of Standards and Technology (NIST) produced a Federal Information
Processing Standards (FIPS) Publication 140-1 (FIPS PUB 140-1), which designates a standard entitled
"Security Requirements for Cryptographic Modules." Included in this standard is a requirement to
incorporate the capability to perform statistical tests for randomness for cryptographic modules that
implement a random or pseudorandom number generator. Specific recommended tests include:
v The monobit test
v The poker test
v The runs test
v The long-run test
In addition, the standard specifies that the cryptographic module provide a means to initiate
"known-answer" tests on demand for periodic testing of the cryptographic algorithms.
Use the Random_Number_Tests (CSUARNT) verb to perform the FIPS-mandated tests described above.
The known-answer tests include testing of DES encipher and decipher, PKA encipher and decipher, and
SHA-1 hash.
Using the CCA node, access control, and master-key management

verbs

Access_Control_Initialization (CSUAACI)
The Access_Control_Initialization verb is used to initialize or update parameters and tables for the
access-control system in the IBM 4765 and IBM 4764 Cryptographic Coprocessors.
You can use this verb to perform the following services:

v Load roles and user profiles
v Change the expiration date for a user profile
v Change the authentication data, such as a passphrase, in a user profile
v Reset the authentication logon failure-count in a user profile
You select which function to perform by specifying the corresponding keyword in the input rule-array. You
can only perform one of these services per verb call.
Note: Use the Access_Control_Maintenance (CSUAACM) verb to query or control installed roles and user
profiles. See page 38 for more information.
Restrictions
| The following table shows the supported releases and associated operating systems for this verb:
|| CCA CCA CCA CCA CCA CCA CCA

| Operating system 4.2 4.1 4.0 3.60 3.30 3.27 3.25
| AIX X X X X
| IBM i X X X
| Red Hat Enterprise Linux X X
| SUSE Linux Enterprise Server X X X X
| Windows X X
| Note: See Table 2 on page xviii for a list of supported operating system releases.
|
| Format
CSUAACI
rule_array_count Input Integer 1, 2, or 3
rule_array Input String array rule_array_count * 8 bytes
verb_data_1_length Input Integer
verb_data_1 Input String verb_data_1_length bytes
verb_data_2_length Input Integer
verb_data_2 Input String verb_data_2_length bytes
See Appendix I, Java Native Interface, on page 743 for information about calling this verb using the JNI.
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see
Parameters common to all verbs on page 9.

rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of elements
in the rule_array variable. The value must be 1, 2, or 3.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are 8 bytes in length and must be left-aligned and padded on the right with space
characters.
The rule_array keywords are:
Keyword Meaning
Function to perform (one required)
INIT-AC Initializes roles and user profiles.
CHGEXPDT Changes the expiration date in a user profile.
CHG-AD Changes authentication data in a user profile or changes a user's passphrase.
Note: The PROTECTD keyword must also be used whenever the CHG-AD keyword is
used. You must authenticate yourself before being allowed to change authentication
data, and the use of protected mode verifies that you have been authenticated.
RESET-FC Resets the count of consecutive failed logon attempts for a user. Clearing the logon
failure-count permits a user to log on again, after being locked out due to too many failed
consecutive attempts.
Options (one or two, optional)
PROTECTD Specifies to operate in protected mode. Data sent to the coprocessor is protected by
encrypting the data with the user's session key, KS.
If the user has not successfully logged on, there is no session key in effect, and the
PROTECTD keyword results in a not-logged-on error.
REPLACE Specifies that a new profile can replace an existing profile with the same name. This
keyword applies only when the rule array contains the INIT-AC keyword.
Without the REPLACE keyword, any attempt to load a profile which already exists are
rejected. This protects against accidentally overlaying a user's profile with one for a
different user who has chosen the same profile ID as one that is already on the
coprocessor.
verb_data_1_length
The verb_data_1_length parameter is a pointer to an integer variable containing the number of bytes
of data in the verb_data_1 variable.
verb_data_1
The verb_data_1 parameter is a pointer to a string variable containing data used by the verb.
This variable is used differently depending on the function being performed.
Rule-array Contents of verb_data_1 variable

keyword
INIT-AC The variable contains a list of zero or more user profiles to be loaded into the coprocessor.
See Profile structures on page 642.
CHGEXPDT, The variable contains the eight-character profile ID for the user profile that is to be modified.
CHG-AD, or
RESET-FC
verb_data_length_2
The verb_data_length_2 parameter is a pointer to an integer variable containing the number of bytes
of data in the verb_data_2 variable.

verb_data_2
The verb_data_2 parameter is a pointer to a string variable containing data used by the verb.
Authentication data structures are described in Access-control data structures on page 638.
The manner in which this variable is used depends on the function being performed.
Rule-array keyword Contents of verb_data_2 variable

INIT-AC The variable contains a list of zero or more roles to be loaded into the coprocessor.
See Role structures on page 638. See Appendix G, Access-control-point codes,
on page 715.
CHGEXPDT The field contains the new expiration date to be stored in the specified user profile.
The expiration date is an 8-character string, in the form YYYYMMDD.
CHG-AD The field contains the new authentication-data, to be used in the specified user
profile.
If the profile currently contains authentication data for the same authentication
mechanism, that data is replaced by the new data. If the profile does not contain
authentication data for the mechanism, the new data is added to the data currently
stored for the specified profile.
RESET-FC The verb_data_2 field is empty. Its length is zero.
Required commands
The Access_Control_Initialization verb requires the following commands to be enabled in the active role:
Rule-array keyword Offset Command

INIT-AC X'0112' Initialize Access-Control System
CHGEXPDT X'0113' Change User Profile Expiration Date
CHG-AD X'0114' Change User Profile Authentication Data
RESET-FC X'0115' Reset User Profile Logon-Attempt-Failure Count

Access_Control_Maintenance (CSUAACM)
The Access_Control_Maintenance verb is used to query or control installed roles and user profiles.
You can use this verb to perform the following services:

v Retrieve a list of the installed roles or user profiles
v Retrieve the non-secret data for a selected role or user profile
v Delete a selected role or user profile from the coprocessor
v Retrieve a list of the users who are logged on to the coprocessor
You select which service to perform by specifying the corresponding keyword in the input rule-array. You
can only perform one of these services per verb call.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSUAACM
rule_array_count Input Integer 1
name Input String 8 bytes
output_data_length In/Output Integer
output_data Output String output_data_length bytes
Parameters
rule_array_count
in the rule_array variable. The value must be 1.

rule_array
characters. The rule_array keywords are:
Keyword Meaning
Function to perform (one required)
LSTPROFS Retrieves a list of the user profiles installed in the coprocessor.
Keyword Q-NUM-RP shows how to determine how much data this request returns to the
application program.
LSTROLES Retrieves a list of the roles installed in the coprocessor.
Keyword Q-NUM-RP shows how to determine how much data this request returns to the
application program.
GET-PROF Retrieves the non-secret part of a specified user profile.
GET-ROLE Retrieves the non-secret part of a role definition from the coprocessor.
DEL-PROF Deletes a specified user profile.
DEL-ROLE Deletes a specified role definition from the coprocessor.
Q-NUM-RP Queries the number of roles and profiles presently installed in the coprocessor. This enables
the application program to know how much data is returned with the LSTROLES or
LSTPROFS keywords.
Q-NUM-UR Queries the number of users logged on to the coprocessor. This enables the application
program to know how much data is returned with the LSTUSERS keyword.
Users can log on or log off between the time Q-NUM-UR is used and the time LSTUSERS is
used, so the list of users might not always contain exactly the number the coprocessor
reported was logged on.
LSTUSERS Retrieves a list of the profile IDs for all users who are logged on to the coprocessor.
name
The name parameter is a pointer to a string variable containing the name of a role or user profile
which is the target of the request.
The manner in which this variable is used depends on the function being performed.
Rule-array keyword Contents of name variable

LSTPROFS, LSTROLES, The name variable is unused.
Q-NUM-RP, Q-NUM-UR, or
LSTUSERS
GET-PROF or DEL-PROF The name variable contains the 8-character profile ID for the user profile
that is to be retrieved or deleted.
GET-ROLE or DEL-ROLE The name variable contains the 8-character role ID for the role definition
that is to be retrieved or deleted.
output_data_length
The output_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the output_data variable. The value must be a multiple of four bytes.
On input, the output_data_length variable must be set to the total size of the variable pointed to by the
output_data parameter. On output, this variable contains the number of bytes of data returned by the
verb in the output_data variable.
output_data
The output_data parameter is a pointer to a string variable containing data returned by the verb. Any

integer value returned in the output_data variable is in big-endian format; the high-order byte of the
value is in the lowest-numbered address in storage. Authentication data structures are described in
Access-control data structures on page 638.
This manner in which this variable is used depends on the function being performed.
Rule-array Contents of output_data variable

keyword
LSTPROFS Contains a list of the profile IDs for all the user profiles stored in the coprocessor.
LSTROLES Contains a list of the role IDs for all the roles stored in the coprocessor.
GET-PROF The variable contains the non-secret portion of the selected user profile. This includes the
following data, in the order listed.
Profile version
Two bytes containing two 1-byte integer values, where the first byte contains the major
version number and the second byte contains the minor version number.
Comment
A 20-character variable padded on the right with spaces, which describes the profile. This
variable is not X'00' terminated.
Role
The 8-character name of the user's assigned role.
Logon failure count
A 1-byte integer containing the number of consecutive failed logon attempts by the user.
Pad
A 1-byte padding value containing X'00'.
Activation date
The first date on which the profile is valid. The date consists of a 2-byte integer
containing the year, followed respectively by a 1-byte integer for the month and a 1-byte
integer for the day of the month.
Expiration date
The last date on which the profile is valid. The format is the same as the Activation date
described above.
List of enrolled authentication mechanisms information
For each authentication mechanism associated with the profile, the verb returns a series
of three integer values:
v The 2-byte Mechanism ID
v The 2-byte Mechanism Strength
v The 4-byte authentication data Expiration date, which has the same format as the
Activation date described above
The authentication data itself is not returned; only the IDs, strength, and expiration date of
the data are returned.

Rule-array Contents of output_data variable
keyword
GET-ROLE The variable contains the non-secret portion of the selected role. This includes the following
data, in the order listed.
Role version
Two bytes containing 2 one-byte integer values, where the first byte contains the major
version number and the second byte contains the minor version number.
Comment
A 20-character variable padded on the right with spaces, containing a comment which
describes the role. This variable is not X'00' terminated.
Required authentication-strength level
A 2-byte integer defining how secure the user authentication must be in order to
authorize this role.
Lower time-limit
The earliest time of day that this role can be used. The time limit consists of two 1-byte
integer values, a 1-byte hour, followed by a 1-byte minute. The hour can range from 0 -
23, and the minute can range from 0 - 59.
Upper time-limit
The latest time of day that this role can be used. The format is the same as the Lower
time-limit.
Valid days of the week
A 1-byte variable defining which days of the week this role can be used. Seven bits of the
byte are used to represent Sunday through Saturday, where a 1 bit means that the day is
allowed, while a 0 bit means it is not.
The first bit (MSB) is for Sunday, and the last bit (LSB) is unused and is set to B'0'.
Access-control-point list
The access-control-point bit map defines which functions a user with this role is permitted
to run.
DEL-PROF or The variable is empty. Its length is 0.
DEL-ROLE
Q-NUM-RP The variable contains an array of two 4-byte integers. The first integer is the number of roles
loaded using the Access_Control_Initialization verb, while the second integer is the number
of user profiles loaded with use of the same verb.
Q-NUM-UR The variable contains a single integer value which indicates the number of users logged on
to the coprocessor.
LSTUSERS The variable contains an array of 8-character profile IDs, one for each user logged on to the
coprocessor. The list is not in any specific order.
Required commands
The Access_Control_Maintenance verb requires the following commands to be enabled in the active role:

LSTPROF X'0116' Read Public Access-Control Information
LSTROLE
GET-PROF
GET-ROLE
Q-NUM-RP
DEL-PROF X'0117' Delete User Profile
DEL-ROLE X'0118' Delete Role

Cryptographic_Facility_Control (CSUACFC)
Use the Cryptographic_Facility_Control verb to perform the following operations:
v Re-initialize the CCA application of the coprocessor.
v Set the date and time of the coprocessor clock.
v Reset the coprocessor Intrusion Latch (see page 24).
v Reset the coprocessor Battery-Low Indicator (see page 25).
v Load or clear the function control vector (FCV), which defines limitations on the cryptographic functions
available in the coprocessor. See Distributed function control vector on page 650.
v Establish the node environment identifier (EID), which is a user-defined identifier. Once set, the EID can
only be set again following a CCA reinitialization. The EID is used in master-key cloning, when
generating an RSA token from a skeleton token that contains an RSA public-key certificate section
(X'40') that includes an EID tag (X'51'), and verbs Symmetric_Key_Generate and
Symmetric_Key_Import when using the PKA92 keyword.
v Establish the minimum and maximum number (m of n) of cloning-information shares that are required
and that can be used to pass sensitive information from one coprocessor to another coprocessor. Once
set, the m of n values can only be set again following a CCA reinitialization.
v Force a coprocessor hardware error for testing purposes.
v Beginning with Release 4.1, change the configuration settings for the default key-wrapping method for
DES internal tokens and DES external tokens.
| v Beginning with Release 4.2, load onto the coprocessor from 1 - 100 different authorized copies of PIN
| decimalization tables. Also, activate loaded tables or delete loaded or active tables from the
| coprocessor. Depending on access control, input decimalization tables provided by PIN verbs are
| compared to the active tables that are stored on the coprocessor, and only those PIN verbs that provide
| a matching input table are authorized to process a PIN. See the Required commands section of the
| following PIN verbs for information on how to use stored PIN decimalization tables to improve PIN
| security and control:
| Clear_PIN_Generate (CSNBPGN)
| Clear_PIN_Generate_Alternate (CSNBCPA)
| Encrypted_PIN_Generate (CSNBEPG)
| Encrypted_PIN_Verify (CSNBPVR)
Table 5 on page 21 shows the relationship between CSUACFC keywords and CSUACFQ keywords.
Select which operation to perform by specifying the corresponding control function keyword in the input
rule-array. You can perform only one of these services per verb call.
Restrictions
| v The following table shows the supported releases and associated operating systems for this verb:
| AIX X X X X
| IBM i X X X
| Windows X X
|

| v Use only these characters in an EID: A...Z, a...z, 0...9, and these additional characters relating to
different character symbols in the various national language character sets as listed in the following
table:
ASCII systems EBCDIC systems USA graphic (for reference)

X'20' X'40' space character
X'26' X'50' &
X'3D' X'7E' =
X'40' X'7C' @
The alphabetic and numeric characters should be encoded in the normal character set for the
computing platform that is in use, either ASCII or EBCDIC.
v It is possible to force a hardware error using the ERRINJ1 keyword. This capability is not available on
IBM i.
v The CHGKEYWR keyword is not supported in releases before Release 4.1.
| v The PINTB-LD, PINTB-RM, and PINTB-AC keywords are not supported in releases before Release 4.2.
Format
CSUACFC
rule_array_count Input Integer 1 or 2
verb_data_length In/Output Integer 0 - 588
verb_data In/Output String verb_data_length bytes
Parameters
rule_array_count
in the rule_array variable. The value must be 1 or 2.
rule_array
characters.
This verb accepts two keywords in the rule array. One specifies the coprocessor for which the request
is intended, the other specifies the function to perform. No rule-array elements are set by the verb.

Keyword Meaning
Coprocessor to use (optional)
ADAPTER1 This keyword is ignored. It is accepted for backward compatibility.
Control function to perform (one required)
RQ-TOKEN Requests a masked 8-byte token from the coprocessor, which is returned in the verb_data
variable. This is the first step when reinitializing the coprocessor.
Note: The returned token is valid for a period of 5 minutes.
The second step for reinitialization uses RQ-REINT.

RQ-REINT Reinitializes the CCA application in the coprocessor. For RQ-REINT, you must set the
verb_data variable to the one's complement of the token that was returned by the
coprocessor when you ran the verb using the RQ-TOKEN keyword. This is the second and
final step when reinitializing the coprocessor.
This two-step process provides protection against accidental reinitialization of the

coprocessor.
SETCLOCK Sets the date and UTC time of the coprocessor's secure clock, and the day of the week.
You must put the date, UTC time, and the current day of the week values in the verb_data
variable.
RESET-IL Clears the intrusion latch on the coprocessor.
RESETBAT Clears the battery-low indicator (latch) on the coprocessor.
LOAD-FCV Loads a new distributed function control vector into the coprocessor. See page 650.
CLR-FCV Clears the function control vector from the coprocessor.
SET-EID Sets a node environment identifier value.
Note: See Restrictions on page 42.
SET-MOFN Sets the minimum and maximum number of cloning-information shares that are required and
that can be used to pass sensitive information from one coprocessor to another coprocessor.
| ERRINJ1 Causes a simulated coprocessor hardware error. This capability can be used for testing
purposes. Using this keyword results in return code 16, reason code 336.
Note: See Restrictions on page 42.
CHGKEYWR Sets the default key-wrapping method for either internal or external key tokens.
(Rel. 4.1 or later)
| PINTB-LD (Rel. Loads one or more authorized PIN decimalization tables onto the coprocessor.
| 4.2 or later)
| Notes:
| 1. When loading more than one table at a time, no tables are changed if an error occurs
| while processing any of the tables provided by the verb_data variable.
| 2. If a table to be loaded from the verb_data variable has the same PIN decimalization
| table identifier as one that is already stored on the coprocessor (1 - 100), the previously
| stored table is replaced.
| 3. In order to replace a table that is currently in the active state on the coprocessor, the
| Delete Decimalization Tables command (offset X'0354') must be enabled in the active
| role.
| PINTB-RM (Rel. Deletes (removes) one or more authorized PIN decimalization tables from the coprocessor.
| 4.2 or later)
| Notes:
| 1. When deleting more than one table at a time, no tables are changed if an error occurs
| while processing any of the tables identified by the verb_data variable.
| 2. A warning is issued when an attempt is made to delete one or more tables that are not
| currently stored on the coprocessor. This does not result in an error.

Keyword Meaning
| PINTB-AC (Rel. Activates one or more PIN decimalization tables that are in the loaded state. The state of
| 4.2 or later) each identified table is changed from loaded to active.
| Notes:
| 1. When activating more than one table at a time, no tables are activated if an error occurs
| while processing any of the tables identified by the verb_data variable.
| 2. It is an error when an attempt is made to activate one or more tables that are not
| currently in the loaded state.
| 3. It is an error if any PIN decimalization table presented by the verb_data variable does
| not match the corresponding PIN decimalization table that is loaded on the coprocessor.
verb_data_length
The verb_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the verb_data variable. On input, specify the size of the variable. The verb updates the variable
with the size of the returned data.
verb_data
The verb_data parameter is a pointer to a string variable containing data used by the verb on input, or
generated by the verb on output.
The manner in which this variable is used differs depending on the value of the control function
selected by a rule_array keyword.
| Control Variable
| function length
| keyword Direction (bytes) Description
RQ-TOKEN Output 8 The verb_data variable receives an 8-byte randomly generated
and masked token. The one's complement of this returned value,
which is provided as input in the verb_data variable with the
RQ-REINT keyword, is required to reinitialize the CCA application
in the coprocessor.
RQ-REINT Input 8 The verb_data variable must contain the one's complement of the
token most recently returned using the RQ-TOKEN keyword.
SETCLOCK Input 16 The verb_data variable contains the UTC date and time to set in
the coprocessor clock. The character string has the form
YYYYMMDDHHmmSSWW, where:
YYYY Is the current year
MM Is the current month, from 01 12
DD Is the current day of the month, from 01 31
HH Is the current hour of the day, from 00 23
mm Is the current minutes past the hour, from 00 59
SS Is the current seconds past the minute, from 00 59
WW Is the current day of the week, from 01 - 07, where
Sunday is represented as 01, and Saturday is
represented as 07
Note: Some functions can return the day of the week in a format
different than that required. Be sure to adjust such a value for
WW. For example, if a function returns 00 to represent Sunday
and 06 to represent Saturday, add 1 to the value returned for
WW.
RESET-IL N/A 0 The verb_data variable is not used for this function.
RESETBAT N/A 0 The verb_data variable is not used for this function.

| Control Variable
| function length
| LOAD-FCV Input 204 (before The verb_data variable must contain the function control vector
| Rel 4.1); 588 (FCV) as described in Distributed function control vector on
| (Rel 4.1 or page 650.
| later)
CLR-FCV N/A 0 The verb_data variable is not used for this function.
SET-EID Input 16 The verb_data variable contains a 16-byte environment (node)
identifier value called the EID. The EID is used in master-key
cloning, and verbs such as Symmetric_Key_Generate and
Symmetric_Key_Import with the PKA92 keyword. See
Restrictions on page 42 for a list of valid characters in an EID.
SET-MOFN Input 8 The contents of the verb_data variable establish the minimum (m)
number and the maximum (n ) number of shares needed to
reconstruct cloned information (see Master_Key_Distribution
(CSUAMKD) on page 70). The verb_data_length variable is an
8-byte string. The left 4-byes of the string contains a 4-byte
integer that defines m, and the right 4 bytes of the string contains
a 4-byte integer that defines n, where 1mn15.
ERRINJ1 N/A 0 The verb_data variable is not used for this function.
CHGKEYWR Input 4 The verb_data variable contains a 4-byte string that specifies the
(Rel. 4.1 or default key-wrapping method for either internal DES key tokens
later) or external DES key tokens. Verbs that wrap DES keys will use
the default key-wrapping method when no other method is
specified.
Use one of the following strings for the verb_data variable to set
the default key-wrapping method.
X'00000100' Internal key tokens, enhanced (WRAP-ENH)
X'00000000' Internal key tokens, legacy (WRAP-ECB)
X'00010100' External key tokens, enhanced (WRAP-ENH)
X'00010000' External key tokens, legacy (WRAP-ECB)
Note: When a coprocessor is initialized, the default key-wrapping

method is set to legacy for internal and external DES key tokens.
| PINTB-LD (Rel. Input 22 - 1804 The verb_data variable contains the decimalization tables input
| 4.2 or later) structure. This structure has the following format:
| Offset Length Description
| 0 2 Length of overall structure (4 + 18 * n), in big
| endian format.
| 2 1 Version (X'00').
| 3 1 Count of 18-byte PIN decimalization table
| structures (1 - 100): n.
| 4 18 * n Start of PIN decimalization table structures to
| load.
| PIN decimalization table structure:

| 0 1 Reserved.
| 1 1 PIN decimalization table identifier (1 - 100).
| Duplicate identifiers are not allowed.
| 2 16 PIN decimalization table to be stored onto
| coprocessor. Only ASCII digits 0 - 9 (X'30' -
| X'39'), in the clear, are valid.

| Control Variable
| function length
| PINTB-RM (Rel. Input 1 - 100 The verb_data variable contains an array of unique bytes, where
| 4.2 or later) each byte is an integer valued from 1 - 100, corresponding to the
| PIN decimalization table identifier of the table to be deleted
| (removed) from the coprocessor. No duplicate table identifiers are
| allowed.
| PINTB-AC (Rel. Input 22 - 1804 The verb_data variable contains the decimalization tables
| 4.2 or later) structure. This structure has the same format as the PINTB-LD
| control function keyword.
Required commands
The Cryptographic_Facility_Control verb requires the following commands to be enabled in the active role:

RQ-TOKEN X'0111' Reinitialize Device
RQ-REINT
SETCLOCK X'0110' Set Clock
RESET-IL X'010F' Reset Intrusion Latch
RESETBAT X'030B' Reset Battery-Low Indicator
LOAD-FCV X'0119' Load Function-Control Vector
CLR-FCV X'011A' Clear Function-Control Vector
SET-EID X'011C' Set EID
SET-MOFN X'011D' Initialize Master Key Cloning
ERRINJ1 X'0304' Error Injection 1
| PINTB-LD X'0353' Load Decimalization Tables
| X'0354' Delete Decimalization Tables
| Note: This command must be enabled in the active role in order to load a
| new table in place of a table that is in the active state.
| X'0355' Activate Decimalization Tables
| Note: When this command is enabled in the active role, the state of the
| stored table is set to active immediately, otherwise it is set to loaded.
| PINTB-RM X'0354' Delete Decimalization Tables
| PINTB-AC X'0355' Activate Decimalization Tables
In the case of the CHGKEYWR rule-array keyword (Release 4.1 or later), the value of the verb_data
variable determines which command is required to be enabled in the active role:
Rule-array verb_data
keyword variable Offset Command
CHGKEYWR X'00000100' X'0139' Wrap Internal Key with Enhanced Method
X'00000000' X'013A' Wrap Internal Key with ECB Method
X'00010100' X'013B' Wrap External Key with Enhanced Method
X'00010000' X'013C' Wrap External Key with ECB Method

Cryptographic_Facility_Query (CSUACFQ)
The Cryptographic_Facility_Query verb is used to retrieve information about the coprocessor and the CCA
application program in that coprocessor. This information includes the following:
v General information about the coprocessor, its operating system, and CCA application
v Status of AES, APKA, DES, and PKA master-key registers
v Status of master-key shares distribution
v Node environment identifier (EID)
v Diagnostic information from the coprocessor
v Export-control information from the coprocessor
v Time and date information from the coprocessor
| v Beginning with Release 4.2, the contents and size of the authorized PIN decimalization tables loaded
| onto the coprocessor
Table 5 on page 21 shows the relationship between CSUACFC keywords and CSUACFQ keywords.
On input, you specify a rule-array count of 1 or 2 and the class of information queried with a rule-array
keyword.
Tip: Allocate a minimum of 30 rule-array elements to allow for extensions of the returned information.
The verb returns information elements in the rule array and sets the rule_array_count variable to the
number of returned elements.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v You cannot limit the number of returned rule-array elements. Table 7 on page 50 describes the number
and meaning of the information in output rule-array elements.
v It is possible to obtain diagnostic information using the DBGREGS1 keyword. This capability is for use
by IBM Support. The returned information is non-sensitive and not publicly defined.
v The STATAES rule-array keyword is not supported in releases before Release 3.30.
v The STATCRD2 rule-array keyword is not supported in releases before Release 4.0.
v The STATAPKA and WRAPMTHD rule-array keywords are not supported in releases before Release
4.1.
| v The NUM-DECT and STATDECT rule array keywords are not supported in releases before Release 4.2.

Format
CSUACFQ
exit_data In/Output String exit_data_length
rule_array_count In/Output Integer 1 or 2 on input
rule_array In/Output String array rule_array_count * 8 bytes
verb_data_length In/Output Integer
verb_data In/Output String verb_data_length bytes
Parameters
rule_array_count
in the rule_array variable. On input, the value must be 1 or 2.
On output, the verb sets the variable to the number of rule_array elements it returns to the application
program.
Tip: With this verb, the number of returned rule_array elements can exceed the rule_array_count that
you specified on input. Be sure that you allocate adequate memory to receive all of the
information elements according to the information class that you select on input with the
information-to-return keyword in the rule_array.
rule_array
characters.
On input, set the rule array to specify the type of information to retrieve. There are two input rule-array
elements, as described in the following table.
Keyword Meaning
Adapter to use (optional)
ADAPTER1 This keyword is ignored. It is accepted for backward compatibility.
Information to return (one required)
DBGREGS1 Obtains non-sensitive coprocessor information. This option is for diagnostic purposes.
The returned information is not publicly defined. See Restrictions on page 48.
| NUM-DECT (Rel. 4.2 Returns the number of bytes of data required for the verb_data variable when the
| or later) STATDECT rule-array keyword is specified.
STATAES (Rel. 3.30 Obtains status information on AES master-key registers and AES key-length enablement.
or later) See also STATEXPT.
STATAPKA (Rel. 4.1 Obtains status information on AES PKA master-key registers and ECC key-length
or later) enablement. See also STATEXPT.

Keyword Meaning
STATCCA Obtains CCA-related status information.
Note: Use of this keyword is provided for backward compatibility. Use STATCCAE
instead.
STATCCAE Obtains extended CCA-related status information.
STATCARD (before Obtains basic status information about the coprocessor.
Rel. 4.0) Note: Beginning with Release 4.0, use of this keyword is provided for backward
compatibility. Use STATCRD2 instead.
STATCRD2 (Rel. 4.0 Obtains extended basic status information about the coprocessor.
or later)
| STATDECT (Rel. 4.2 Obtains the information on all of the authorized PIN decimalization tables that are
| or later) currently stored on the coprocessor. Output is returned in the verb_data variable. See
| Table 8 on page 57.
STATDIAG Obtains diagnostic information.
STATEID Obtains the node environment identifier.
STATEXPT Obtains function control vector related export status information about available
algorithms. See Distributed function control vector on page 650. See also STATAES
and STATAPKA.
STATMOFN Obtains master-key shares distribution information.
TIMEDATE Reads the current date, time, and day of the week from the secure clock within the
coprocessor.
WRAPMTHD Obtains the default key-wrapping configuration options for internal and external DES key
tokens.
The format of the output rule-array depends on the value of the rule-array element which identifies the
information to be returned. Different sets of rule-array elements are returned depending on whether the
input keyword is DBGREGS1, STATAES, STATAPKA, STATCCA, STATCCAE, STATCARD,
| STATCRD2, STATDIAG, STATEID, STATEXPT, STATMOFN, TIMEDATE, or WRAPMTHD. Keywords
| NUM-DECT and STATDECT return output in the verb_data variable.
For rule-array elements that contain numbers, those numbers are represented by numeric characters
which are left-aligned and padded on the right with space characters. For example, a rule-array
element which contains the number 2 contains the character string 2 (the number 2
followed by 7 space characters).
On output, the rule-array elements can have the values shown in Table 7.
Table 7. Cryptographic_Facility_Query information returned in the rule array
Element Name Description
Output rule-array for option DBGREGS1
Twelve rule-array elements are filled with non-sensitive information from
the coprocessor's control registers. This information is for debugging
purposes and is not publicly disclosed. See Restrictions on page 48.
Output rule-array for option STATAES
1 AES NMK status The state of the AES new-master-key register:
1 Register is clear.
2 Register contains a partially complete key.
3 Register contains a complete key.
2 AES CMK status The state of the AES current-master-key register:
2 Register contains a key.

Table 7. Cryptographic_Facility_Query information returned in the rule array (continued)
3 AES OMK status The state of the AES old-master-key register:
4 AES key-length A numeric character string containing the maximum AES key-length, in
enablement bits, enabled by the function control vector. Valid values are 0, 128, 192,
or 256. A value of 0 means that no AES key-length is enabled.
Output rule-array for option STATAPKA
1 APKA NMK status The state of the APKA new-master-key register:
2 APKA CMK status The state of the APKA current-master-key register:
3 APKA OMK status The state of the APKA old-master-key register:
4 ECC A numeric character string containing the maximum supported curve
key-agreement order or size, in bits, for ECC key-agreement services enabled by the
services function control vector. Valid values are 0 and 521. A value of 0 means
enablement that no ECC key-agreement services are enabled.
Output rule-array for option STATCCA
1 NMK status The state of the DES and PKA new-master-key register:
2 CMK status The state of the DES and PKA current-master-key register:
3 OMK status The state of the DES and PKA old-master-key register:
4 CCA application A character string that identifies the version of the CCA application
version program that is running in the coprocessor.
5 CCA application A character string containing the build date for the CCA application
build date program that is running in the coprocessor.
6 User role ID A character string containing the role identifier which defines the host
application user's current (active) authority.
Output rule-array for option STATCCAE
1 DES NMK status The state of the DES new-master-key register:
2 DES CMK status The state of the DES current-master-key register:
3 DES OMK status The state of the DES old-master-key register:

4 CCA application A character string that identifies the version of the CCA application
version program that is running in the coprocessor.
5 CCA application A character string containing the build date for the CCA application
build date program that is running in the coprocessor.
6 User role ID A character string containing the Role identifier which defines the host
application user's current (active) authority.
7 Asymmetric NMK The state of the asymmetric new-master-key register:
status 1 Register is clear.
8 Asymmetric CMK The state of the asymmetric current-master-key register:
9 Asymmetric OMK The state of the asymmetric old-master-key register:
Output rule-array for option STATCARD
1 Number of A numeric character string containing the number of active coprocessors
installed installed in the machine. This only includes coprocessors that have CCA
coprocessors software loaded (including those with CCA UDX software). Non-CCA
coprocessors are not included in this number.
2 DES hardware A numeric character string containing an integer value identifying the
level version of DES hardware that is on the coprocessor.
3 RSA hardware A numeric character string containing an integer value identifying the
level version of RSA hardware that is on the coprocessor.
4 POST0 version A character string identifying the version of the coprocessor's Power-On
and POST1 Self Test (POST) firmware.
version
The first four characters define the POST0 version, and the last four
characters define the POST1 version.
5 Coprocessor A character string identifying the operating system firmware on the
operating system coprocessor.
name
6 Coprocessor A character string identifying the version of the coprocessor's operating
operating system system firmware.
version
7 Coprocessor part A character string containing the 8-character part number identifying the
number version of the coprocessor.
8 Coprocessor EC A character string containing the 8-character EC (engineering change)
level level for this version of the coprocessor.
9 Miniboot version A character string identifying the version of the coprocessor's miniboot
firmware. This firmware controls the loading of programs into the
coprocessor.
The first four characters define the MiniBoot0 version, and the last four
characters define the MiniBoot1 version.
10 CPU speed A numeric character string containing the operating speed of the
microprocessor chip, in megahertz.

11 Coprocessor ID A unique identifier manufactured into the coprocessor. The coprocessor
(see also element adapter ID is an 8-byte binary value where the high-order byte is X'85'
number 15) for an IBM 4765-001, and is X'71' for an IBM 4764-001. The remaining
bytes are a random value.
12 Flash memory A numeric character string containing the size of the flash EPROM
size memory on the coprocessor, in 64-kilobyte increments.
13 DRAM memory A numeric character string containing the size of the dynamic RAM
size (DRAM) memory on the coprocessor, in kilobytes.
14 Battery-backed A numeric character string containing the size of the battery-backed RAM
memory size on the coprocessor, in kilobytes.
15 Serial number A character string containing the unique serial number of the
coprocessor. The serial number is factory installed and is also reported
by the CLU utility in a coprocessor-signed status message.
Output rule-array for option STATCRD2 (Release 4.0 or later)
1 Number of A numeric character string containing the number of active coprocessors
installed installed in the machine. This only includes coprocessors that have CCA
coprocessors software loaded (including those with CCA UDX software). Non-CCA
coprocessors are not included in this number.
2 DES hardware A numeric character string containing an integer value identifying the
level version of DES hardware that is on the coprocessor.
3 RSA hardware A numeric character string containing an integer value identifying the
level version of RSA hardware that is on the coprocessor.
4 POST0 version A character string identifying the version of the coprocessor's Power-On
and POST1 Self Test (POST) firmware.
version
characters define the POST1 version.
5 Coprocessor A character string identifying the operating system firmware on the
operating system coprocessor.
name
6 Coprocessor A character string identifying the version of the coprocessor's operating
operating system system firmware.
version
7 Coprocessor part A character string containing the 8-character part number identifying the
number version of the coprocessor.
8 Coprocessor EC A character string containing the 8-character EC (engineering change)
level level for this version of the coprocessor.
9 Miniboot version A character string identifying the version of the coprocessor's miniboot
firmware. This firmware controls the loading of programs into the
coprocessor.
The first four characters define the MiniBoot0 version, and the last four
characters define the MiniBoot1 version.
10 CPU speed A numeric character string containing the operating speed of the
microprocessor chip, in megahertz.
11 Coprocessor ID A unique identifier manufactured into the coprocessor. The coprocessor
(see also element adapter ID is an 8-byte binary value where the high-order byte is X'85'
number 15) for an IBM 4765-001, and is X'71' for an IBM 4764-001. The remaining
bytes are a random value.

12 Flash memory A numeric character string containing the size of the flash EPROM
size memory on the coprocessor, in 64-kilobyte increments.
13 DRAM memory A numeric character string containing the size of the dynamic RAM
size (DRAM) memory on the coprocessor, in kilobytes.
14 Battery-backed A numeric character string containing the size of the battery-backed RAM
memory size on the coprocessor, in kilobytes.
15 Serial number A character string containing the unique serial number of the
coprocessor. The serial number is factory installed and is also reported
by the CLU utility in a coprocessor-signed status message.
16 POST2 version A character string identifying the version of the coprocessor's POST2
firmware.
characters are reserved and valued to space characters.
Output rule-array for option STATDIAG
1 Battery state A numeric character string containing a value which indicates whether
the battery on the coprocessor needs to be replaced:
1 Battery is good.
2 Battery should be replaced.
2 Intrusion latch A numeric character string containing a value which indicates whether
state the intrusion latch on the coprocessor is set or cleared:
1 Latch is cleared.
2 Latch is set.
3 Error log status A numeric character string containing a value which indicates whether
there is data in the coprocessor CCA error log:
1 Error log is empty.
2 Error log contains abnormal termination data, but is not yet full.
3 Error log is full, and cannot hold any more data.
4 Mesh intrusion A numeric character string containing a value to indicate whether the
coprocessor has detected tampering with the protective mesh that
surrounds the secure module. This indicates a probable attempt to
physically penetrate the module:
1 No intrusion has been detected.
2 An intrusion attempt has been detected
5 Low voltage A numeric character string containing a value to indicate whether a
detected power-supply voltage was below the minimum acceptable level. This
might indicate an attempt to attack the security module:
1 Only acceptable voltages have been detected.
2 A voltage has been detected below the low-voltage tamper threshold.
6 High voltage A numeric character string containing a value indicates whether a
detected power-supply voltage was above the maximum acceptable level. This
might indicate an attempt to attack the security module:
1 Only acceptable voltages have been detected.
2 A voltage has been detected above the high-voltage tamper
threshold.
7 Temperature A numeric character string containing a value to indicate whether the
range exceeded temperature in the secure module was outside of the acceptable limits.
This might indicate an attempt to attack the security module:
1 Temperature is acceptable.
2 Temperature has been detected outside of an acceptable limit.

8 Radiation On the 4764, a numeric character string containing a value to indicate
detected (4764); whether radiation was detected inside the secure module. This might
reserved (4765) indicate an attempt to attack the security module:
1 No radiation has been detected.
2 Radiation has been detected.
9, 11, 13, 15, 17 Last 5 commands These five rule-array elements contain the last five commands that were
run run by the coprocessor CCA application. They are in chronological order,
with the most recent command in element 9. Each element contains the
security API command code in the first four characters, and the
subcommand code in the last four characters.
10, 12, 14, 16, 18 Last 5 return and These five rule-array elements contain the security API return codes and
reason codes reason codes corresponding to the five commands in rule-array elements
9, 11, 13, 15, and 17. Each element contains the return code in the first
four characters, and the reason code in the last four characters.
Output rule-array for option STATEID
1, 2 EID The two elements, when concatenated, provide the 16-byte node
environment identifier value.
Output rule-array for option STATEXPT (see also STATAES and STATAPKA)
1 Base CCA A numeric character string containing a value to indicate whether base
services CCA services are available:
availability 0 Base CCA services are not available.
1 Base CCA services are available.
Note: This value is currently ignored.

2 CDMF availability A numeric character string containing a value to indicate whether CDMF
| (IBM 4758 only) encryption is available:
0 CDMF encryption is not available.
| 1 CDMF encryption is available.
3 56-bit DES A numeric character string containing a value to indicate whether 56-bit
availability DES encryption is available:
0 56-bit DES encryption is not available.
1 56-bit DES encryption is available.
4 Triple-DES A numeric character string containing a value to indicate whether
availability Triple-DES encryption is available:
0 Triple-DES encryption is not available.
1 Triple-DES encryption is available.
5 SET services A numeric character string containing a value to indicate whether SET
availability (secure electronic transaction) services are available:
0 SET services are not available.
1 SET services are available.
6 Maximum A numeric character string containing the maximum modulus size that is
modulus for enabled for the encryption of symmetric keys. This defines the longest
symmetric key public-key modulus that can be used for key management of
encryption symmetric-algorithm keys.
Output rule-array for option STATMOFN
Elements 1 and 2 are treated as a 16-byte string, as are elements 3 and 4, with the high-order 15 bytes
containing meaningful information and the 16th byte containing a space character. Each byte provides status
information about the ith share, 1 i 15, of master-key information.

1, 2 Master-key The 15 individual bytes are set to one of these character values:
shares generation 0 Cannot be generated
1 Can be generated
2 Has been generated but not distributed
3 Generated and distributed once
4 Generated and distributed more than once
3, 4 Master-key The 15 individual bytes are set to one of these character values:
shares reception 0 Cannot be received
1 Can be received
3 Has been received
4 Has been received more than once
5 m The minimum number of shares required to instantiate a master key
through the master-key-shares process. The value is returned in two
characters, valued from 01 15, followed by six space characters.
6 n The maximum number of distinct shares involved in the master-key
shares process. The value is returned in two characters, valued from 01
- 15, followed by six space characters.
Output rule-array for option TIMEDATE
1 Date The current date is returned as a character string of the form
YYYYMMDD, where YYYY represents the year, MM represents the
month (0112), and DD represents the day of the month (0131).
2 Time The current UTC time of day is returned as a character string of the form
HHMMSS.
3 Day of the week The day of the week is returned as a number between 1 (Sunday) and 7
(Saturday).
Output rule-array for option WRAPMTHD
1 Default wrapping 0 Legacy (WRAP-ECB)
method for 1 Enhanced (WRAP-ENH)
internal keys
2 Default wrapping 0 Legacy (WRAP-ECB)
method for 1 Enhanced (WRAP-ENH)
external keys
verb_data_length
The verb_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the verb_data variable.
verb_data
The verb_data parameter is a pointer to a string variable containing data sent to the coprocessor for
this verb, or received from the coprocessor as a result of this verb. Its use depends on the options
specified by the host application program. In releases before Release 4.2, the verb_data parameter is
| not used by this verb. Beginning with Release 4.2, this parameter is used by the NUM-DECT and
| STATDECT keywords as shown in Table 8 on page 57.

| Table 8. Cryptographic_Facility_Query information returned in the verb_data variable
| Output verb data for option NUM-DECT
| 0 4 Integer value of the number of bytes of data that the verb_data variable requires
| when the STATDECT rule-array keyword is specified.
| Output verb data for option STATDECT
| 0 3 PIN decimalization table identifier in ASCII digits 001 - 100 (X'303031' - X'310000').
| 3 1 Table state (in ASCII):
| Code Description
| A (X'41') Active
| L (X'4C') Loaded
| 4 16 PIN decimalization table. Contains ASCII digits 0 - 9 (X'30' - X'39'), in the clear,
|
| Required commands
None

Cryptographic_Facility_Version (CSUACFV)
The Cryptographic_Facility_Version verb returns the CCA application version and the CCA application build
date.
The CCA application version is a character string returned in the first eight bytes of the version_data
variable, and the CCA application build date is a character string returned in the second eight bytes. The
version_data variable is null terminated and has a total length of 17 bytes.
Restrictions
| AIX X X
| IBM i X
| Red Hat Enterprise Linux
| SUSE Linux Enterprise Server X X
| Windows
|
| Format
CSUACFV
version_data_length In/Output Integer 17
version_data Output String version_data_length bytes
Parameters
Parameters common to all verbs on page 9. Note that there is no rule_array.
version_data_length
The version_data_length parameter is a pointer to an integer variable containing the number of bytes
in the version_data variable. The value must be at least 17 bytes.
On input, the version_data_length variable must be set to the total size of the variable pointed to by
the version_data parameter. On output, this variable contains the number of bytes of data returned by
the verb in the version_data variable.
version_data
The version_data parameter is a pointer to a string variable containing data returned by the verb. An
8-byte character string that identifies the version of the Security Application Program Interface library,
followed by an 8-byte character string containing the build date for the Security Application Program
Interface library, followed by a null terminating character.
Required commands
None
Cryptographic_Resource_Allocate (CSUACRA)
The Cryptographic_Resource_Allocate verb is used to allocate a specific CCA coprocessor for use by the
thread or process, depending on the scope of the verb. For the IBM i, this verb is scoped to a process; for
the other implementations, this verb is scoped to a thread. When a thread or process, depending on the
scope, allocates a cryptographic resource requests are routed to that resource. When a cryptographic
resource is not allocated, requests are routed to the default cryptographic resource.
You can set the default cryptographic resource. See the IBM 4765 PCIe Cryptographic Coprocessor CCA
Support Program Installation Manual or IBM 4764 PCI-X Cryptographic Coprocessor CCA Support
Program Installation Manual for more information. If you take no action, the default assignment is CRP01.
You cannot allocate a cryptographic resource while one is already allocated. Use the
Cryptographic_Resource_Deallocate verb to deallocate an allocated cryptographic resource.
Be sure to review Multi-coprocessor capabilities on page 25 and Master-key considerations with multiple
CCA coprocessors on page 31.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSUACRA
resource_name_length Input Integer 1 - 64
resource_name Input String resource_name_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Cryptographic resource (required)
DEVICE Specifies an IBM 4765 or IBM 4764 CCA Cryptographic Coprocessor.
resource_name_length
The resource_name_length parameter is a pointer to an integer variable containing the number of
bytes of data in the resource_name variable. The length must be 1 64.
resource_name
The resource_name parameter is a pointer to a string variable containing the name of the coprocessor
to be allocated.
Required commands
None

Cryptographic_Resource_Deallocate (CSUACRD)
The Cryptographic_Resource_Deallocate verb is used to deallocate a specific CCA coprocessor that is
allocated by the thread or process, depending on the scope of the verb. For the IBM i, this verb is scoped
to a process; for all other implementations, this verb is scoped to a thread. When a thread or process,
depending on the scope, deallocates a cryptographic resource, requests are routed to the default
cryptographic resource.
You can set the default cryptographic resource. See the IBM 4765 PCIe Cryptographic Coprocessor CCA
Support Program Installation Manual or IBM 4764 PCI-X Cryptographic Coprocessor CCA Support
Program Installation Manual for more information. If you take no action, the default assignment is CRP01.
Be sure to review Multi-coprocessor capabilities on page 25 and Master-key considerations with multiple
CCA coprocessors on page 31.
If a thread with an allocated coprocessor ends without first deallocating the coprocessor, excess memory
consumption results. It is not necessary to deallocate a cryptographic resource if the process itself is
ending, only if individual threads end while the process continues to run.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSUACRD
resource_name_length Input Integer 1 - 64
resource_name Input String resource_name_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Cryptographic resource (required)
DEVICE Specifies an IBM 4765 or IBM 4764 CCA Cryptographic Coprocessor.
resource_name_length
The resource_name_length parameter is a pointer to an integer variable containing the number of
bytes of data in the resource_name variable. The length must be 1 64.
resource_name
The resource_name parameter is a pointer to a string variable containing the name of the coprocessor
to be deallocated.
Required commands
None

Key_Storage_Designate (CSUAKSD)
Use the Key_Storage_Designate verb to specify the AES, DES, or PKA key-storage file name to be used
by subsequent processes that access key storage. There is no default.
Beginning with Release 3.30, a key-storage file name can be undesignated by specifying a value of 0 for
the key_storage_file_name_length variable. A length of 0 is not supported in releases before Release 3.30.
If a process that accesses AES key-storage does not have an AES key-storage file designated, the
process will try to use the value of the QIBM_CCA_AES_KEYSTORE environment variable for the
key-storage file name. If a process that accesses DES or PKA key-storage does not have the applicable
key-storage file designated, the process will try to use the name from the device description, followed by
the value of the applicable environment variable, as shown in the table below. The device description is
not used for the AES key-storage file.
Key-storage file Device description Environment variable

AES Not used QIBM_CCA_AES_KEYSTORE
DES Overrides environment variable QIBM_CCA_DES_KEYSTORE
PKA Overrides environment variable QIBM_CCA_PKA_KEYSTORE
When a job designates a key-storage file name, the designated name overrides the device description or
environment variable setting for the life of the job or until the name is undesignated.
Select the type of key storage, either AES, DES, or PKA, using a rule-array keyword. There is no default.
Restrictions
| AIX
| IBM i X X X
| SUSE Linux Enterprise Server
| Windows
|
| v A length of 0 is not supported for the key_storage_file_name_length variable in releases before Release
3.30.
v AES key-storage is not supported in releases before Release 3.30.
v ECC and variable-length symmetric key tokens are not supported in releases before Release 4.1.

Format
CSUAKSD
key_storage_file_name_length Input Integer 0 - 64
key_storage_file_name Input String key_storage_file_name_length bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
Key-storage type (one required)
AES (Rel. 3.30 or Indicates that the file name applies to the AES key-storage specification. (AES and,
later) beginning with Release 4.1, variable-length symmetric key tokens).
DES Indicates that the file name applies to the DES key-storage specification.
PKA Indicates that the file name applies to the PKA key-storage specification (RSA and,
beginning with Release 4.1, ECC key tokens).
key_storage_file_name_length
The key_storage_file_name_length parameter is a pointer to an integer variable containing the number
of bytes of data in the key_storage_file_name variable. The length must be within the range of 0 - 64.
If the value is 0, the key_storage_file_name parameter is ignored, and any previous key-storage file
name becomes undesignated.
key_storage_file_name
The key_storage_file_name parameter is a pointer to a string variable containing the fully qualified file
name of the key-storage file to be selected.
The file name must follow standard naming conventions for objects in the IBM i QSYS.LIB file system.
Required commands
None

Key_Storage_Initialization (CSNBKSI)
The Key_Storage_Initialization verb initializes a key-storage dataset using the AES, DES, or PKA current
master-key. The initialized key storage does not contain any preexisting key records. The name and path
of the key-storage data and index file are established differently in each operating environment. See the
IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual or IBM 4764 PCI-X
Cryptographic Coprocessor CCA Support Program Installation Manual for information on the key-storage
data and index files.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The AES rule-array keyword is not supported in releases before Release 3.30.
v ECC and variable-length symmetric key tokens are not supported in releases before Release 4.1.
Format
CSNBKSI
key_storage_file_name_length Input Integer 1 - 64
key_storage_file_name Input String key_storage_file_name_length bytes
key_storage_description_length Input Integer 64
key_storage_description Input String key_storage_description_length bytes
clear_master_key Input String 24 or 32 bytes
Parameters
rule_array_count

rule_array
Keyword Meaning
Master-key source (optional)
CURRENT Specifies that the current master-key of the default cryptographic facility is to be used for the
initialization.
Note: This keyword is ignored. It is accepted for backward compatibility.
Key-storage selection (one required)
| AES (Rel. 3.30 Initialize AES key-storage (fixed-length AES and, beginning with Release 4.1, variable-length
| or later) AES and HMAC key tokens).
DES Initialize DES key-storage.
| Note: Use of this keyword requires both the symmetric and the asymmetric master keys
| (SYM-MK and ASYM-MK) to be set. See Master_Key_Process (CSNBMKP) on page 74 for
| information on setting these master keys.
PKA Initialize PKA key-storage (PKA and, beginning with Release 4.1, ECC key tokens).
key_storage_file_name_length
The key_storage_file_name_length parameter is a pointer to an integer variable containing the number
of bytes of data in the key_storage_file_name variable. The length must be within the range of 1 - 64.
key_storage_file_name
The key_storage_file_name parameter is a pointer to a string variable containing the fully qualified file
name of the key-storage file to be initialized. If the file does not exist, it is created. If the file does
exist, it is overwritten and all existing keys are lost.
key_storage_description_length
The key_storage_description_length parameter is a pointer to an integer variable containing the
number of bytes of data in the key_storage_description variable.
key_storage_description
The key_storage_description parameter is a pointer to a string variable containing the description
string that is stored in the key-storage file when it is initialized.
clear_master_key
The clear_master_key parameter is unused, but it must be declared and requires 24 data bytes in
application storage for DES and PKA, and 32 data bytes for AES.
Required commands
Except in the IBM i environment, the Key_Storage_Initialization verb requires the Compute Verification
Pattern command (offset X'001D') to be enabled in the active role. In the IBM i environment, no
commands are issued to the coprocessor and command authorization does not apply.

Logon_Control (CSUALCT)
Use the Logon_Control verb to perform the following services:
v Log on to the coprocessor, using your access-control profile
v Log off of the coprocessor
v Save or restore logon content information
Select the service to perform by specifying the corresponding keyword in the input rule-array. Only one
service is performed for each call to this verb.
When an application logs on to a coprocessor, the CCA implementation establishes a session between the
application program and the coprocessor's access-control system. Logon context information is created
during logon, including a randomly derived session key that is generated in the coprocessor. The
coprocessor is unaware of which thread, program, or process has initiated a request. The logon context
information resides in memory associated with the process thread that performed the Logon_Control verb.
If a process thread already has valid logon context information (put there by logging on or by using the
GET-CNTX keyword), then trying to log on a second time results in an 'already logged on' error. If a
process thread does not have valid logon context information, it can log on. Any logon context information
in the coprocessor is updated with new session information (including a new randomly derived session
key), and any previous logon context information becomes invalid (session key no longer recognized).
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSUALCT
exit_data In/Output String exit_data_length
user_id Input String 8 bytes
auth_parms_length In/Output Integer
auth_parms In/Output String auth_parms_length bytes
auth_data_length In/Output Integer
auth_data In/Output String auth_data_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Keywords used to log on (zero or two)
LOGON Tells the coprocessor that you want to log on. When the LOGON keyword is used, a second
keyword, PPHRASE, must also be used to indicate how you identify yourself to the
coprocessor.
PPHRASE Specifies that you are going to identify yourself using a passphrase.
Keywords used to log off (zero, one, or two)
LOGOFF Tells the coprocessor you want to log off.
FORCE Tells the coprocessor that a specified user is to be logged off. The user's profile ID is specified
by the user_id parameter. When the FORCE keyword is used, the LOGOFF keyword must also
be used.
Keywords used to save and restore logon context information (zero or one)
GET-CNTX Obtains a copy of the logon context information that is active in your session. See Using logon
context information on page 19.
PUT-CNTX Restores the logon context information that was saved using the GET_CNTX keyword. See
Using logon context information on page 19.
user_id
The user_id parameter is a pointer to a string variable containing the ID string which identifies the user
to the system. The user ID must be exactly 8 characters in length. Shorter user IDs should be padded
on the right with space characters.
The user_id parameter is always used when logging on. It is also used when the LOGOFF keyword
used in conjunction with the FORCE keyword to force a user off.
auth_parms_length
The auth_parms_length parameter is a pointer to an integer variable containing the number of bytes of
data in the auth_parms variable.
On input, this variable contains the length (in bytes) of the auth_parms variable. On output, this
variable contains the number of bytes of data returned in the auth_parms variable.
auth_parms
The auth_parms parameter is a pointer to a string variable containing data used in the authentication
process.
This variable is used differently depending on the authentication method specified in the rule array.
Rule-array keyword Contents of auth_parms variable

PPHRASE The auth_parms variable is empty. Its length is zero.

auth_data_length
The auth_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the auth_data variable.
On input, this variable contains the length (in bytes) of the auth_data variable. When no usage is
defined for the auth_data parameter, set the length variable to zero.
On output, this variable contains the number of bytes of data returned in the auth_data variable.
auth_data
The auth_data parameter is a pointer to a string variable containing data used in the authentication
process.
This variable is used differently depending on the keywords specified in the rule array.
Rule-array Contents of auth_data variable

keyword
PPHRASE and The auth_data variable contains the user-provided passphrase.
LOGON
GET-CNTX The auth_data variable receives the active logon context information. The size of the buffer
provided for the auth_data variable must be at least 256 bytes.
PUT-CNTX The auth_data variable contains your active logon context.
Required commands
The Logon_Control verb requires the following command to be enabled in the active role:

FORCE X'011B' Force User Logoff

Master_Key_Distribution (CSUAMKD)
The Master_Key_Distribution verb is used to perform these operations related to the distribution of shares
of the DES or PKA master key:
v Generate and distribute a share of the current master-key.
v Receive a master-key share and, when sufficient shares are received, reconstruct the master key in the
new-master-key register.
You choose which class of master key, either symmetric (DES) or asymmetric (PKA), to clone with the
SYM-MK and the ASYM-MK rule-array keywords. If neither keyword is specified, the verb performs the
same operation on both classes of registers, provided that the registers contain the same values.
The OBTAIN and INSTALL rule-array keywords control the operation of the verb.
Specify the following information when using the OBTAIN keyword:

v The share number, i, where 1 i 15 and i the minimum and the maximum number of shares to be
distributed as defined by the SET-MOFN control function keyword in the Cryptographic_Facility_Control
verb.
v The private_key_name of the coprocessor-retained key used to sign a generated master-key share.
This key must have the CLONE attribute set at the time of key generation.
v The certifying_key_name of the public key already registered in the coprocessor used to validate the
following certificate.
v The certificate and its length that provides the public key used to encrypt the clone_info_encrypting_key.
v The length and location of the clone_info variable that receives the encrypted master-key share.
v The verb performs the following functions:
Generation of master-key shares, as required, and formatting of the information to be cloned
Signing of the cloning information
Generation of an encryption key and encryption of the cloning information
Recovery and validation of the public key used to encrypt the clone_info_encrypting_key
Encryption of the clone_info_encrypting_key
v The verb returns the following information:
Encrypted cloning information
Encrypted clone_info_encrypting_key
Specify the following information when using the INSTALL keyword:

v The share number, i, presented in this request.
v The private_key_name of the coprocessor-retained key used to decrypt the clone_info_encrypting_key.
This key must have the CLONE attribute set at the time of key generation.
v The certifying_key_name of the public key already registered in the coprocessor used to validate the
following certificate.
v The certificate and its length that provides the public key used to validate the signature on the cloning
information.
v The length and location of the clone_info variable that provides the encrypted master-key share.
v The verb performs the following tasks:
Recovery of the clone_info_encrypting_key
Decryption of the cloning information
Recovery and validation of the public key used to validate the cloning information signature
Validation of the cloning information signature
Retention of a master-key share
Regeneration of a master key in the new-master-key register when sufficient shares have been
received
v The verb returns the following information:

A return code of 4 if the master key has been recovered into the new-master-key register. A return
code of 0 indicates that processing was normal, but a master key was not recovered into the
new-master-key register. Other return codes, and various reason codes, can also occur in abnormal
cases.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v When using the OBTAIN keyword, the current-master-key register must contain a key and the EID must
be set.
v When using the INSTALL keyword, the new-master-key register must be clear.
v AES and APKA master keys are not supported by this verb.
Format
CSUAMKD
exit_data In/Output String exit_data _length bytes
rule_array Input String array rule_array _count * 8 bytes
share_index Input Integer 1 - 15
private_key_name Input String 64 bytes
certifying_key_name Input String 64 bytes
certificate_length Input Integer
certificate Input String certificate_length bytes
clone_info_encrypting_key_length In/Output Integer
clone_info_encrypting_key In/Output String clone_info_encrypting_key_length bytes
clone_info_length In/Output Integer
clone_info In/Output String clone_info_length bytes
Parameters

rule_array_count
rule_array
Keyword Meaning
Operation (one required)
OBTAIN Generate and output a master-key share and other cloning information.
INSTALL Receive a master-key share and other cloning information.
Master-key register class (one, optional)
SYM-MK Operate with the symmetric (DES) master-key registers.
ASYM-MK Operate with the asymmetric (PKA) master-key registers.
No keyword Operate with both the SYM-MK and ASYM-MK master-key registers. This is the default.
share_index
The share_index parameter is a pointer to an integer variable containing the index number of the
share to be generated or received by the coprocessor.
private_key_name
The private_key_name parameter is a pointer to a string variable containing the name of the
coprocessor-retained private key used to sign the cloning information or recover the
cloning-information encrypting key.
certifying_key_name
The certifying_key_name parameter is a pointer to a string variable containing the name of the
coprocessor-retained public key used to verify the offered certificate.
certificate_length
The certificate_length parameter is a pointer to an integer variable containing the number of bytes of
data in the certificate variable.
certificate
The certificate parameter is a pointer to a string variable containing the public-key certificate that can
be validated using the public key identified with the certifying_key_name variable.
clone_info_encrypting_key_length
The clone_info_encrypting_key_length parameter is a pointer to an integer variable containing the
number of bytes of data in the clone_info_encrypting_key variable.
clone_info_encrypting_key
The clone_info_encrypting_key parameter is a pointer to a string variable containing the encrypted key
used to recover the cloning information.
clone_info_length
The clone_info_length parameter is a pointer to an integer variable containing the number of bytes of
data in the clone_info variable.
clone_info
The clone_info parameter is a pointer to a string variable containing the encrypted cloning information
(master-key share).

Required commands
Rule-array Share index
keyword number Offset Command
INSTALL 1 X'0221' Clone-info (Share) Install 1
2 X'0222' Clone-info (Share) Install 2
10 X'022A' Clone-info (Share) Install 10
11 X'022B' Clone-info (Share) Install 11
12 X'022C' Clone-info (Share) Install 12
13 X'022D' Clone-info (Share) Install 13
14 X'022E' Clone-info (Share) Install 14
15 X'022F' Clone-info (Share) Install 15
OBTAIN 1 X'0211' Clone-info (Share) Obtain 1
2 X'0212' Clone-info (Share) Obtain 2
10 X'021A' Clone-info (Share) Obtain 10
11 X'021B' Clone-info (Share) Obtain 11
12 X'021C' Clone-info (Share) Obtain 12
13 X'021D' Clone-info (Share) Obtain 13
14 X'021E' Clone-info (Share) Obtain 14
15 X'021F' Clone-info (Share) Obtain 15

Master_Key_Process (CSNBMKP)
The Master_Key_Process verb manages the CCA master keys. Use the Master_Key_Process verb to
manage the AES, DES, and PKA master-key register classes. Beginning with Release 4.1, the verb also
manages the APKA class of master-key registers. Each master-key register class has three master key
registers: new, current, and old. See Understanding and managing master keys on page 27.
Use the verb to perform the following services:

v Clear the new-master-key and the old-master-key registers.
v Exclusive-OR a clear value as a key part into the new-master-key register.
v Generate a random master-key value in the new-master-key register. This can be done for the DES and
PKA master keys, but not for the AES or APKA master keys.
v Set the specified master key, which transfers the current master-key to the old-master-key register, and
the new master-key to the current-master-key register. It then clears the new-master-key register. SET
also clears the master-key-shares tables when used for the DES or PKA master-key registers.
The IBM implementations of DES and PKA master keys are triple-length 168-bit, 24-byte values. The AES
and APKA master keys are 256-bit, 32-byte values.
AES and DES master keys are a symmetric master-key class of registers. APKA and PKA master keys are
an asymmetric master-key class of registers. Choose to process the AES, APKA, DES, or PKA master-key
register class by specifying the AES-MK, APKA-MK, SYM-MK, or ASYM-MK rule-array keyword. If none
of these keywords is specified, the verb performs the same operation on both the SYM-MK and ASYM-MK
classes (DES and PKA) of registers. For operations that query the default register-class contents, this
occurs only if the DES and PKA registers already contain the same values. This default mode of operation
is compatible with early versions of CCA, which used only a single master key to protect both DES and
PKA keys.
Tip: Before starting to load new master-key information, ensure that the new-master-key register is
cleared. Do this by using the CLEAR keyword in the rule array.
To form a master key from key parts in the new-master-key register, use the Master_Key_Process verb
several times to complete the following tasks:
v Clear the register, if it is not already clear.
v Load the first key part.
v Load any middle key parts, calling the verb once for each middle key part.
v Load the last key part.
If there is a value in the old-master-key register, this master key can also be used to decrypt an
enciphered working key. You can remove a prior master key from the coprocessor with the CLR-OLD
keyword. The contents of the old-master-key register are removed and subsequently only
current-master-key encrypted keys are usable.
For DES and PKA master-keys, the low-order bit in each byte of the key is used as parity for the
remaining bits in the byte. Each byte of the key part must contain an odd number of one bits. If this is not
the case, return code 0, reason code 702 (X'2BE') is issued. The product maintains odd parity on the
accumulated symmetric master-key value. AES and APKA master keys do not use parity bits.
When a last master-key part is entered, this additional processing is performed:

v For DES and PKA master keys, if any two of the 8-byte parts of the new master-key have the same
value, return code 0, reason code 701 (X'2BD') is issued. Do not ignore this warning. Do not use a key
with this property.
v The master-key verification pattern (MKVP) of the new master-key is compared against the MKVP of
the current and the old master keys. If they are the same, the service fails with return code 8, reason
code 704 (X'2C0'). For information about MKVP, see Master-key verification pattern on page 577.

v For the DES and PKA master keys, if any of the 8-byte parts of the new master-key compares equal to
one of the weak DES-keys, the service fails with return code 8, reason code 703 (X'2BF'). See Table 9
on page 77 for a list of these weak keys. A parity-adjusted version of the PKA master-key is used to
look for weak keys.
Except in the IBM i environment, as part of the SET process, if a key-storage file exists, the header record
of each key-storage file is updated with the verification pattern of the newly set current master-key. The
IBM i environment does not have master-key verification records in the key-storage dataset.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The AES-MK rule-array keyword is not supported in releases before Release 3.30.
v The APKA-MK rule-array keyword is not supported in releases before Release 4.1.
Format
CSNBMKP
key_part Input String 24 or 32 bytes
Parameters
rule_array_count
rule_array

Keyword Meaning
Cryptographic component (optional)
ADAPTER This keyword is ignored. It is accepted for backward compatibility.
Master-key register class (one, optional)
AES-MK (Rel. Specifies operation with the AES master-key registers.
3.30 or later)
APKA-MK (Rel. Specified operation with the AES PKA master-key registers.
4.1 or later)
SYM-MK Specifies operation with the DES (symmetric) master-key registers.
ASYM-MK Specifies operation with the PKA (asymmetric) master-key registers.
No keyword Specifies operation with both the SYM-MK and ASYM-MK master-key registers. This is the
default.
Master-key operation (one required)
CLEAR Specifies to clear the new-master-key (NMK) register, and set its status to empty.
CLR-OLD Specifies to clear the old-master-key (OMK) register, and set its status to empty.
Note: Any keys enciphered under the OMK will become unusable.
You can use the CLR-OLD keyword to cause the OMK register to be cleared. The status
response in the Cryptographic_Facility_Query verb, STATCCA or STATAES, shows the
condition of this register.
FIRST Specifies to load the first master-key-part to the NMK register.
MIDDLE Specifies to exclusive-OR the second, third, or other intermediate key_part into the value
currently in the NMK register.
LAST Specifies to exclusive-OR the last key_part into the value currently in the NMK register.
RANDOM Generates a random master-key value in the NMK register. This is not valid with AES-MK
and APKA-MK master keys.
SET Specifies to activate the new master key. This does the following:
1. Copies the value from the current-master-key (CMK) register to the OMK register.
2. Copies the value from the NMK register to the CMK register.
3. Clears the NMK register.
Note: An application system is responsible for keeping all of its keys in a usable form.
When a master key is changed (SET), the IBM 4765 and IBM 4764 implementations can
use an internal key that is enciphered by either the appropriate current master key or,
assuming that the CLR-OLD keyword was not used to clear it, the old master key. Before a
master key is changed a second time, it is important to first reencipher any keys enciphered
under the old master key to the new master key. Use the Key_Token_Change verb for
internal AES and DES key tokens, and the PKA_Key_Token_Change verb for internal PKA
key tokens and active trusted blocks.
key_part
The key_part parameter is a pointer to a string variable containing a cleartext key part that is used
when one of the keywords FIRST, MIDDLE, or LAST is specified. The value is either a 192-bit
(24-byte) DES key-part or a 256-bit (32-byte) AES or APKA key-part.
If the CLEAR, CLR-OLD, RANDOM, or SET keywords are used, the information in the variable is
ignored, but the variable must be declared.
Required commands
The Master_Key_Process verb requires the following commands to be enabled in the active role based on
the master-key class and master-key operation:

Master-key Master-key
operation class Offset Command
CLEAR AES-MK X'0124' Clear AES New Master Key Register
APKA-MK X'031F' Clear APKA NMK Register (CLEAR)
SYM-MK X'0032' Clear New Master Key Register
ASYM-MK X'0060' Clear New Asymmetric Master Key Register
CLR-OLD AES-MK X'0123' Clear AES Old Master Key Register
APKA-MK X'031E' Clear APKA OMK Register (CLR-OLD)
SYM-MK X'0033' Clear Old Master Key Register
ASYM-MK X'0061' Clear Old Asymmetric Master Key Register
FIRST AES-MK X'0125' Load First AES Master Key Part
APKA-MK X'0320' Load First APKA Master Key Part
SYM-MK X'0018' Load First Master Key Part
ASYM-MK X'0053' Load First Asymmetric Master Key Part
MIDDLE or AES-MK X'0126' Combine Intermediate AES Master Key Parts
LAST APKA-MK X'0321' Combine Intermediate APKA Master Key Parts
SYM-MK X'0019' Combine Master Key Parts
ASYM-MK X'0054' Combine Asymmetric Master Key Parts
RANDOM SYM-MK X'0020' Generate Random Master Key
ASYM-MK X'0120' Generate Random Asymmetric Master Key
SET AES-MK X'0128' Activate New AES Master Key (SET)
APKA-MK X'0322' Activate New APKA Master Key (SET)
SYM-MK X'001A' Set Master Key
ASYM-MK X'0057' Set Asymmetric Master Key
Related information
Table 9 provides a list of DES keys that are considered questionable.
Table 9. Questionable DES keys
Key strength Questionable DES keys
Weak X'01010101 01010101' X'1F1F1F1F 0E0E0E0E' X'E0E0E0E0 F1F1F1F1'
X'FEFEFEFE FEFEFEFE'
Semi-weak X'011F011F 010E010E' X'1FE01FE0 0EF10EF1' X'E0FEE0FE F1FEF1FE'
X'01E001E0 01F101F1' X'1FFE1FFE 0EFE0EFE' X'FE01FE01 FE01FE01'
X'01FE01FE 01FE01FE' X'E001E001 F101F101' X'FE1FFE1F FE0EFE0E'
X'1F011F01 0E010E01' X'E01FE01F F10EF10E' X'FEE0FEE0 FEF1FEF1'
Possibly X'01011F1F 01010E0E' X'1F1FE0E0 0E0EF1F1' X'E0E0FEFE F1F1FEFE'
semi-weak X'0101E0E0 0101F1F1' X'1F1FFEFE 0E0EFEFE' X'E0FE011F F1FE010E'
X'0101FEFE 0101FEFE' X'1FE001FE 0EF101FE' X'E0FE1F01 F1FE0E01'
X'011F1F01 010E0E01' X'1FE0E01F 0EF1F10E' X'E0FEFEE0 F1FEFEF1'
X'011FE0FE 01E0F1FE' X'1FE0FE01 0EF1FE01' X'FE0101FE FE0101FE'
X'011FFEE0 010EFEF1' X'1FFE01E0 E0FE01F1' X'FE011FE0 FE010EF1'
X'01E01FFE 01F10EFE' X'1FFEE001 0EFEF101' X'FE01E01F FE01F10E'
X'01E0E001 01F1F101' X'1FFEFE1F 0EFEFE0E' X'FE1F01E0 FE0E01F1'
X'01E0FE1F 01F1FE0E' X'E00101E0 F10101F1' X'FE1F1FFE FE0E0EFE'
X'01FE1FE0 01FE0EF1' X'E0011FFE F1010EFE' X'FE1FE001 FE0EF101'
X'01FEE01F 01FEF10E' X'E001FE1F F101FE0E' X'FEE0011F FEF1010E'
X'01FEFE01 01FEFE01' X'E01F01FE F10E01FE' X'FEE01F01 FEF10E01'
X'1F01011F 0E01010E' X'E01F1FE0 F10E0EF1' X'FEE0E0FE FEF1F1FE'
X'1F01E0FE 0E01F1FE' X'E01FFE01 F10EFE01' X'FEFE0101 FEFE0101'
X'1F01FEE0 0E01FEF1' X'E0E00101 F1F10101' X'FEFE1F1F FEFE0E0E'
X'1F1F0101 0E0E0101' X'E0E01F1F F1F10E0E' X'FEFEE0E0 FEFEF1F1'

Random_Number_Tests (CSUARNT)
The Random_Number_Tests verb invokes the USA NIST FIPS PUB 140-1 specified cryptographic
operational tests. The tests are performed three times. If any test fails, the verb returns return code 4 and
reason code 1. These tests, selected by a rule-array keyword, consist of:
v For random numbers: a monobit test, poker test, runs test, and long-run test
v Known-answer tests of DES encryption and decryption, RSA encryption and decryption, and SHA-1
hash processes
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSUARNT
Parameters
rule_array_count
rule_array
Keyword Meaning
Test selection (one required)
FIPS-RNT Perform the FIPS PUB 140-1 specified tests on the random number generation output.
KAT Perform the FIPS PUB 140-1 specified known-answer tests on DES encryption and
decryption, RSA encryption and decryption, and SHA-1 hashing.

Required commands
None

Chapter 3. PKA key-management
This section describes the management of Public Key Architecture (PKA) public and private keys, and how
you can perform the following tasks:
v Generate keys with various characteristics
v Import keys from other systems
v Protect and move a private key from one node to another
The verbs listed in Table 10 are used to perform cryptographic functions and assist you in obtaining
key-token data structures. See Using verbs to perform cryptographic functions and obtain key-token data
structures on page 86 for detailed information on these verbs.
Table 10. Public administration services
Service
Verb Page Service Entry point location
| PKA_Key_Generate 87 Generates an external RSA or ECC CSNDPKG E
| public-private key-pair.
| PKA_Key_Import 92 Imports either an external RSA or ECC CSNDPKI E
| public-private key-pair, or an active external
| trusted block.
PKA_Key_Token_Build 95 Builds a PKA key-token. CSNDPKB S
| PKA_Key_Token_Change 103 Reenciphers either a private RSA or ECC CSNDKTC E
| key, or an internal trusted block, from
| encipherment with the old asymmetric
| master-key to encipherment with the
| current asymmetric master-key.
| PKA_Key_Translate 105 Translates a source external RSA CSNDPKT E
| key-token into a target external smart-card
| key token.
| PKA_Public_Key_Extract 108 Extracts a public key from a public-private CSNDPKX S
| RSA or ECC key-token and returns the key
| in a PKA public-key token.
| PKA_Public_Key_Hash_Register 110 Registers the hash value of an RSA CSNDPKH E
| public-key used later to verify an offered
| RSA public-key. See
| PKA_Public_Key_Register.
PKA_Public_Key_Register 112 Registers an RSA public-key used later to CSNDPKR E
verify an offered public-key. Registration
requires that a hash of the RSA public-key
has previously been registered within the
coprocessor. See
PKA_Public_Key_Hash_Register.
E=cryptographic engine, S=security API host software
PKA key-management services

With CCA, you can use a set of public-key cryptographic services that are collectively designated PKA96.
The PKA96 services support the public key architecture and related hashing methods including:
v MD5
v MDC
v RIPEMD-160
v SHA-1
v SHA-224
v SHA-256
81
v SHA-384
v SHA-512
Figure 3 shows the relationship among the services, the public-private key-token, and other data involved
with supporting digital signatures and symmetric (AES and DES) key exchange.
|
|
| PKA_Key_Token_Build
|
|
| (Skeleton)
|
| PKA_Key_Import PKA_Key_Generate
|
|
|
|
| Data
| PKA96 PUPR key token
| PU: Clear
| PR: e*MK(PR) One_Way_Hash
| or e*KEK(PR)
| or Clear
|
|
|
|
|
| Digital_Signature_Generate
| PKA_Public_Key_Extract
|
|
| e*MK.CV(K)
| Digital
| (AES or PU key token signature
| DES key)
|
|
| Symmetric_Key_Export Digital_Signature_Verify
| Symmetric_Key_Generate
|
|
| yes/no
|
| ePU(K),CV
| (Private key)
|
|
|
| Symmetric_Key_Import
| Designates verb
|
|
|
| e*MK.CV(K)
| Data structure
| (AES or DES key)
|
| Figure 3. PKA96 verbs with key-token flow
These topics are discussed in this section:

v How to generate a public-private key pair

v How to import keys from other systems
v How to update a private key when the master key that protects a private key or its OPK is changed
v How to use the keys and provide for private-key protection
v How to use a private key at multiple nodes
v How to extract a public key
v How to register and retain a public key
Key generation
You generate RSA or, beginning with Release 4.1, ECC public-private key-pairs using the
PKA_Key_Generate verb. You specify certain facts about the desired key in a skeleton key token that you
can create using the PKA_Key_Token_Build verb.
When generating the key-pair you must determine:

v The key length
v How, or if, the private key should be encrypted
v For an ECC key, the curve type
v If an RSA key should be retained within the coprocessor, and if so, its name (label)
v The format of the private key: modular-exponent, Chinese-Remainder Theorem, or ECC
v A key name if access-control on the name is employed
v Whether the key should be usable in symmetric key-exchange operations
v Whether the key should be usable in digital signature generation operations
The PKA_Key_Generate verb either retains the generated RSA private-key within the coprocessor
(excluding ECC private keys), or the verb produces output which is the generated RSA private-key in one
of three forms, or the generated ECC private key in one of two forms, so that you can control where the
private key is deployed.
It is possible to request that the generated non-ECC RSA private-key be retained within the secure
cryptographic-engine using the RETAIN keyword on the PKA_Key_Generate verb. In this case, only the
public key is returned. Use the retained private key by referring to it with a key label which you specify in
the key-name section of the skeleton key-token.
Note: A retained private key cannot be copied or backed up; once deleted or destroyed, a retained key
cannot be recovered.
If you do not retain the RSA private-key within the coprocessor, you select how to receive the private key:
v Cleartext
Both the private and public keys are returned as clear text. This option requires that you provide
protection for the private key by means other than encryption within the key-generating step. With this
option, you can test or interface with other systems or applications that require the private key to be in
the clear.
v Enciphered by the local master-key
You can request that the key-generating service return the RSA private-key or OPK enciphered by the
PKA master-key or the ECC OPK enciphered by the APKA master-key, within the cryptographic engine.
Because there is no service available to re-encrypt the private key or OPK other than by the current or
a replacement master-key, the generated private key is effectively locked to the generating node, or
other nodes that you establish with the same master key. Generally these would be backup nodes or
parallel nodes for greater throughput.
v Enciphered by a transport key-encrypting-key (not valid with an ECC key)
Chapter 3. PKA key-management 83

You can request the service to encrypt the generated private key under either a DES IMPORTER key or
a DES EXPORTER key. An IMPORTER key permits the private key to be imported and used later at
the generating node.
The key-encrypting key can also be an EXPORTER transport key. An EXPORTER key is shared with
one or more nodes. This enables you to distribute the key to another node or nodes. For example, you
could obtain an RSA private-key in this form, for distribution to a System z large server's integrated RSA
cryptographic processor.
Related reading: EXPORTER and IMPORTER key-encrypting transport keys are discussed in
Chapter 5, AES, DES, and HMAC symmetric-key management.
Because you can obtain the private key, it can be made functional on more than one cryptographic engine
and used for backup or additional throughput. Your administration procedures control where the key can
be used. The private key can be transported securely between nodes in its encrypted form. You can set up
one-way key distribution channels between nodes and lock the receiving transport key-encrypting key to
particular nodes so that you can be certain where the private key exists. This ability to replicate a key to
multiple nodes is especially important to high-throughput server systems and important for backup
processing purposes.
In systems with an access monitor, such as IBM z/OS Security Server RACF, the key name that you
associate with a private key gives you the ability to enforce restricted key usage. These systems can
determine whether a requesting process has the right to use the particular key name that is
cryptographically bound to the private key. You specify such a key name when you build the
skeleton_key_token in the PKA_Key_Token_Build verb.
For RSA keys, you decide whether the key should be returned in modular-exponent form or in
Chinese-Remainder Theorem (CRT) format. ECC keys are returned only in one form. Generally the CRT
form performs faster in services that use the private key. This decision is represented by the form of the
private key that you indicate in the skeleton_key_token. You can reuse an existing key-token having the
desirable properties, or you can build the skeleton_key_token with the PKA_Key_Token_Build verb.
Certain implementations such as the IBM System z (z/OS) server CMOS Cryptographic Coprocessor
feature (CCF) cannot employ a private key in the CRT form generated by the PKA_Key_Generate verb.
For RSA keys, you also decide if the public exponent should be valued to three, 216+1, or fully random.
Also, in the PKA_Key_Token_Build verb you can indicate that the key should be usable for both digital
signature signing and symmetric key exchange (KEY-MGMT), or you can indicate that the key should be
usable only for digital signature signing (SIG-ONLY), or only key decryption (KM-ONLY).
The key can be generated as a random value, or the key can be generated based on a seed derived from
regeneration data provided by the application program.
You can also have a newly generated RSA public-key certified by an RSA private-key held within the
coprocessor. You can obtain a self-signature, a signature from another key, or both. To obtain these
signatures or certificates, you must extend the skeleton key-token yourself because the
PKA_Key_Token_Build verb cannot do so.
The formats of the key tokens are described in PKA key tokens on page 585. The key tokens are a
concatenation of several sections with each section providing information pertaining to the key. All of the
described formats can be input to any version, but only selected formats are output by Version 2 and later
support.
Key import
To be secure and useful in services, a private key must be enciphered by a PKA or APKA master-key on
the CCA node where it is used. (Of course, an RSA private-key generated as a retained private-key is also
secure, but in this case PKA_Key_Import does not apply.) You can use the PKA_Key_Import verb to get

an RSA private-key deciphered from a transport key and enciphered by the PKA master-key. Also, you can
get a clear, unenciphered RSA or ECC private-key enciphered by its master key using the
PKA_Key_Import verb.
The public and private keys must be presented in an external PKA key-token (see PKA key tokens on
page 585). You can use the PKA_Key_Token_Build verb to structure the key into the proper token format.
You provide or identify the operational DES transport key (key-encrypting key) and the encrypted private
key with its associated public key to the import service. The service returns the RSA private-key or Object
Protection Key (OPK) encrypted under the current PKA master-key, or the private ECC OPK encrypted
under the APKA master-key, along with the public key.
The coprocessor is designed to generate and employ RSA CRT-form keys having p > q. When importing a
private key having q > p, the key is accepted. However, each time that an application uses such a key, it
incurs substantial overhead to recalculate the multiplicative inverse of the quantity U. See Table 100 on
page 592 for the components of an RSA CRT key.
Reenciphering a private key under an updated master key

When the PKA master-key or the APKA master-key at a CCA node is changed, internal keys, such as RSA
and ECC private keys enciphered by the master key, must be securely decrypted from under the
preexisting master key and enciphered under the replacement master-key. You can accomplish this task
using the PKA_Key_Token_Change verb.
After the preexisting PKA or APKA master-key has become the old master-key and the replacement
master-key has become the current master-key, use the PKA_Key_Token_Change verb to effect the
reencipherment of the private keys.
Using the PKA keys

The public-private keys that you create or import can be used in these services:
For private keys:
v Digital_Signature_Generate
v Master_Key_Distribution
v PKA_Decrypt
v SET_Block_Decompose
v Symmetric_Key_Import
For public keys:
v Digital_Signature_Verify
v Master_Key_Distribution
v PKA_Encrypt
v SET_Block_Compose
v Symmetric_Key_Export
v Symmetric_Key_Generate
Arranging appropriate protection for the private key is a must. A CCA node can help ensure that the key
remains confidential. However, you must ensure that the master key and any transport keys are protected,
for example, through split-knowledge, dual-control procedures. Or, for an RSA key-pair, you can choose to
retain the private key in the secure cryptographic-engine.
Besides the confidentiality of the private key, you must also ensure that only authorized applications can
use the private key. You can hold the private key in application-managed storage and pass the key to the
cryptographic services as required. Generally, this limits the access other applications might have to the

key. In systems with an access monitor, such as RACF on z/OS systems, it is possible to associate a key
name with the private key and have use of the key name authorized by the access monitor.
Using the private key at multiple nodes

You can arrange to use a private key at multiple nodes if the nodes have the same PKA or APKA
master-key, or if you arrange to have the same transport key installed at each of the target nodes. In the
latter case, you need to arrange to have the transport key under which the private key is enciphered
installed at each target node.
Having the private key installed at multiple nodes enables you to provide increased service levels for
greater throughput, and to maintain operation when a primary node goes out of service. Having a private
key installed at more than one node increases the risk of someone misusing or compromising the key. You
have to weigh the advantages and disadvantages as you design your system or systems.
Extracting a public key

CCA PKA key generation returns an RSA or ECC public-private key-pair in a single key-token, provided
that your application is not retaining the private RSA key within the coprocessor. You can obtain a key
token with only the public-key information using the PKA_Public_Key_Extract verb.
If the public-private key-token is used in verbs that only require the public key, the implementation might
attempt to recover the private key which in the usual case would fail (because normally the private key
should not be usable where use is being made of the public key).
Registering and retaining an RSA public-key

You can use the PKA_Public_Key_Hash_Register and the PKA_Public_Key_Register verbs to register an
RSA public-key in the secure cryptographic engine under dual control. Authorize the related commands in
two different roles to enforce a dual-control policy. Your applications can subsequently reference the
registered RSA public-key stored within the engine with the confidence that the key has been entered
under dual control. The Master_Key_Distribution verb makes use of registered RSA public keys in the
master-key-shares distribution scheme.
Using verbs to perform cryptographic functions and obtain key-token

data structures

PKA_Key_Generate (CSNDPKG)
The PKA_Key_Generate verb is used to generate an RSA public-private key-pair for use with the RSA
algorithm. Beginning with Release 4.1, the verb can also be used to generate an ECC public-private key
pair for use with the ECC algorithm.
A skeleton_key_token can be created using the PKA_Key_Token_Build verb. See PKA_Key_Token_Build

(CSNDPKB) on page 95.
The skeleton_key_token provided to the verb determines the following characteristics of the generated
key-pair:
v The key type: RSA or ECC
| v The RSA key length (modulus size) or ECC Brainpool or Prime curve size of p in bits
v The RSA public-key exponent: valued to 3, 216 + 1, or random. See Restrictions on page 88.
v Any RSA private-key optimization (Modulus-Exponent versus Chinese-Remainder Theorem format)
v Any signatures and signature-information that should be associated with the public key
An ECC key is always randomly generated by this verb. An RSA key is either randomly generated or
derived using regeneration data.
Normally an RSA key is randomly generated. By providing regeneration data for an RSA key, a seed can
be supplied so that the same value of the generated key can be obtained in multiple instances. This can
be useful in testing situations or where the regeneration data can be securely held for key generation. The
process for generating a particular key pair from regeneration data might vary between products.
Therefore, do not expect to obtain the same key pair for a given regeneration data string between
products.
The generated private-key can be returned in one of three forms for RSA and ECC:
v In cleartext form (CLEAR).
| v Enciphered by the CCA PKA master-key (MASTER) if it is an RSA key, or by an Object Protection Key
| (OPK) that is encrypted by the APKA master-key if it is an ECC key.
| v Enciphered by a transport (key-encrypting) key (XPORT).
| A private key enciphered by an EXPORTER transport key can be imported to a node where the
| corresponding IMPORTER key is installed, while one enciphered by an IMPORTER transport key can
| be imported to the generating node.
| For RSA, the transport key is an operational key-encrypting key in a fixed-length DES key-token.
| For ECC, the transport key is an operational key-encrypting key in a variable-length AES key-token.
| This option is not available for ECC keys in releases before Release 4.2.
Use the RETAIN rule-array keyword to cause the RSA private-key to be retained within the coprocessor.
Incorporate the key label to be used later to reference the newly generated key in the key name section of
the skeleton key-token. Later, use this label to employ the key in verbs such as
Digital_Signature_Generate, Symmetric_Key_Import, Master_Key_Distribution, SET_Block_Decompose,
and PKA_Decrypt. On output, the verb returns an external key-token containing the public key in the
generated_key_identifier variable. The generated_key_identifier variable returned by the verb does not
contain the private key.
Note: When using the RETAIN private-key encryption option, the key label supplied in the skeleton
key-token references the key storage within the coprocessor, and, in this case, must not reference
a record in the host-system PKA key-storage.
The rule-array keyword CLONE flags a generated and retained RSA private-key as usable in an engine
cloning process. Cloning is a technique for copying sensitive coprocessor information from one
coprocessor to another. (See Understanding and managing master keys on page 27.)

If you include a public-key certificate section within the RSA skeleton key-token, the cryptographic engine
signs a certificate with the key that is designated in the RSA public-key certificate signature subsection.
This technique causes the cryptographic engine to sign the newly generated public key using another key
that has been retained within the engine, including the newly generated key (producing a self-signature).
You can obtain more than one signature on the public key when you include multiple signature
subsections in the skeleton key token. See RSA public-key certificate section on page 594.
Tip: The verb returns a section X'06' RSA private-key token format when you request a
Modulus-Exponent internal key even though you have specified a type X'02' skeleton token.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The maximum public exponent is 17 bits for any key that has a modulus greater than 2048 bits.
v Not all IBM implementations of CCA support a CRT form of the RSA private key; check the
product-specific literature. The IBM implementations support an optimized RSA private key (a key in
Chinese-Remainder Theorem format). The formats vary between versions.
v See PKA key tokens on page 585 for the formats used when generating the various forms of key
tokens.
v Keys with a modulus length greater than 2048 bits are not supported in releases before Release 3.30.
v When generating a key for use with ANS X9.31 digital signatures, the modulus length must be 1024,
1280, 1536, 1792, 2048, or 4096 bits.
v The key label used for a retained key must not exist in the external PKA key-storage held on the hard
disk drive.
v Due to potential loss of a retained private key within the cryptographic engine, retained keys should be
avoided for key management purposes.
v Rule-array keyword ITER-38 is not supported in releases before Release 4.1.
v ECC key tokens are not supported in releases before Release 4.1.
v The regeneration_data_length variable must be 0 for ECC keys.
| v Beginning with Release 4.2 for ECC keys, the NIST security strength requirements will be enforced,
| with respect to ECC curve type and AES key length.
| v The XPORT rule-array keyword is not valid for an ECC key in releases before Release 4.2.
| v The use of regeneration data for generating an ECC key is not supported.

Format
CSNDPKG
| rule_array_count Input Integer 1, 2, or 3
regeneration_data_length Input Integer 0, 8 - 256
regeneration_data Input String regeneration_data_length bytes
skeleton_key_token_length Input Integer 3500
skeleton_key_token Input String skeleton_key_token_length bytes
| transport_key_identifier Input String 64 bytes
generated_key_identifier_length In/Output Integer 3500
generated_key_identifier In/Output String generated_key_identifier_length bytes
Parameters
rule_array_count
| The rule_array_count parameter is a pointer to an integer variable containing the number of elements
| in the rule_array variable. The value must be 1, 2, or 3.
rule_array
Keyword Meaning
Private-key form (one required)
CLEAR Returns the private key in cleartext.
| MASTER Enciphers the private key or OPK using the PKA master-key for an RSA key, or the OPK
| using the APKA master-key for an ECC key. The transport_key_identifier parameter should
| specify a null key-token.
RETAIN Retains the RSA private-key within the cryptographic engine and returns the RSA public-key
as specified by the generated_key_identifier parameter. The name presented in the
generated_key_identifier variable is used later to access the retained private key.
Note: A retained private key cannot be copied or backed up. Once deleted or destroyed, a
retained key cannot be recovered. Not valid with an ECC private key.
| XPORT Enciphers the private key under the key-encrypting key identified by the
| transport_key_identifier parameter. For an RSA key, this is an EXPORTER or IMPORTER
| transport key in a fixed-length operational DES key-token. For an ECC key, this is an
| EXPORTER or IMPORTER transport key in an operational variable-length AES key-token.
RETAIN option (one, optional). Valid only with the RETAIN keyword.
CLONE Flags, as usable, a retained private RSA key in a cryptographic engine cloning operation.
Regeneration data option (one, optional). Valid only with regeneration data. Release 4.1 or later.

Keyword Meaning
ITER-38 Force 38 iterations of tests for primality, as required by ANS X9.31 for the Miller-Rabin
primality tests. This option produces a more secure key, but it is labor intensive.
| Transport key-type (one, optional; one required if transport_key_identifier is a label). If this keyword is specified,
| it must match the type of key to be transported, whether the identifier is a label or not.
| OKEK-AES The outbound key-encrypting key represents an AES key-token.
| OKEK-DES The outbound key-encrypting key represents a DES key-token.
regeneration_data_length
The regeneration_data_length parameter is a pointer to an integer variable containing the number of
bytes of data in the regeneration_data variable. This value must be 0 for an ECC key. For an RSA key,
this must be a value of 0, or in the range 8 - 256, inclusive.
If the value is 0, the generated keys are based on a random-seed value. If this value is between 8 -
256, the regeneration data is hashed to form a seed value used in the key generation process to
provide a means for recreating a public-private key pair.
regeneration_data
The regeneration_data parameter is a pointer to a string variable containing a value used as the basis
for creating a particular public-private key pair in a repeatable manner. The regeneration data is
hashed to form a seed value used in the key generation process and provides a means for recreating
a public-private key pair.
skeleton_key_token_length
The skeleton_key_token_length parameter is a pointer to an integer variable containing the number of
bytes of data in the skeleton_key_token variable. The maximum length is 3500 bytes.
skeleton_key_token
The skeleton_key_token parameter is a pointer to a string variable containing a skeleton key-token.
This information provides the characteristics for the ECC or RSA key-pair to be generated. A skeleton
key-token can be created using the PKA_Key_Token_Build verb.
transport_key_identifier
| The transport_key_identifier parameter is a pointer to a string variable containing an operational AES
| (Release 4.2 or later) or DES key-encrypting-key token, a null key-token, or a key label of such a key.
| Use an IMPORTER key to encipher a private key to be used at this node. Use an EXPORTER key to
| encipher a private key to be used at another node. Choose one of the following:
| v When generating an ECC key with the XPORT rule_array keyword (Release 4.2 or later), provide
| the variable-length symmetric IMPORTER or EXPORTER key-token to be used to wrap the
| generated ECC key. Key bit lengths of 128, 192, and 256 are supported. If this parameter points to
| a key label, specify rule-array keyword OKEK-AES to indicate that the AES key-storage dataset
| contains the key token.
| v When generating an RSA key with the XPORT rule_array keyword, provide the fixed-length DES
| IMPORTER or EXPORTER key-token to be used to wrap the generated RSA key. If this parameter
| points to a key label, specify rule-array keyword OKEK-DES to indicate that the DES key-storage
| dataset contains the key token.
| v If the XPORT rule_array keyword is not specified, specify a null key-token. If this parameter points
| to a key label, specify keyword OKEK-AES for an ECC key or keyword OKEK-DES for an RSA key.
generated_key_identifier_length
The generated_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the generated_key_identifier variable. The maximum length is 3500 bytes.
On output, and if the size is of sufficient length, the variable is updated with the actual length of the
generated_key_identifier variable.
generated_key_identifier
The generated_key_identifier parameter is a pointer to a string variable containing either a key label

identifying a key-storage record, or is other information to be overwritten. If the key label identifies a
key record in PKA key-storage, the generated key token replaces any key token associated with the
label. If the first byte of the identified string does not indicate a key label (that is, not in the range X'20'
- X'FE'), and the variable is of sufficient length to receive the result, then the generated key token is
returned in the identified variable.
When generating an RSA retained key, on output the verb returns the public token in this variable.
Required commands
The PKA_Key_Generate verb requires the PKA96 PKA Key Generate command (offset X'0103') to be
enabled in the active role.
Also enable one of these commands in the hardware, depending on rule-array-keyword usage and the
content of the skeleton key-token:
v With the CLONE rule-array keyword, PKA Clone Key Generate (offset X'0204')
v With the CLEAR rule-array keyword, PKA Clear Key Generate (offset X'0205') when generating an RSA
key, or Generate ECC Keys in the Clear (offset X'0326') when generating an ECC key
To generate keys based on the value supplied in the regeneration_data variable, you must enable at least
one of these commands (not valid with ECC keys):
v When not using the RETAIN keyword, Permit Regeneration Data (offset X'027D')
v When using the RETAIN keyword, Permit Regeneration Data for Retained Keys (offset X'027E')
| The following access-control points are added beginning with Release 4.2:
| v To disable the wrapping of a stronger key with a weaker key, the Disallow Weak Key Wrap command
| (offset X'0328') must be enabled in the active role. This command affects multiple verbs. See Table 169
| on page 715.
| v To receive a warning when wrapping a key with a weaker key-encrypting key, enable the Warn when
| Wrapping Weak keys command (offset X'032C') in the active role. The Disallow Weak Key Wrap
| command overrides this command.

PKA_Key_Import (CSNDPKI)
The PKA_Key_Import verb is used to import an RSA or, beginning with Release 4.1, an ECC public-private
key pair. A private key must be accompanied by the associated public key. A source RSA private-key either
| can be in the clear or it can be enciphered. A source ECC private-key can only be in the clear in Release
| 4.1. Beginning with Release 4.2, an ECC private key can be enciphered as well as in the clear. The verb
can also be used to import an active external trusted block. A trusted block does not contain a private key.
Instead, it contains an encrypted confounder and triple-length MAC key. The MAC key is used to calculate
an ISO 16609 CBC-mode Triple-DES MAC of the trusted block contents. In an external trusted block, the
MAC key is encrypted under a DES IMP-PKA key.
To import a public-private key pair:

v Identify the external RSA or ECC key-token to be imported using the source_key_token parameter. Use
the PKA_Key_Generate verb to obtain the token or, if the key originates in a non-CCA system, use the
PKA_Key_Token_Build verb.
| v Use the transport_key_identifier parameter to identify the key used to encipher the source key-token:
| 1. For an enciphered ECC source-key-token, provide an AES key-encrypting key in a variable-length
| symmetric key-token (not supported in releases before Release 4.2).
| 2. For an enciphered RSA source key-token, provide an IMPORTER key in a fixed-length DES
| key-token.
| 3. For a clear source key-token, provide a null key-token.
An RSA private key is enciphered under the PKA master-key. Beginning with Release 4.1, the private key
material of an ECC key-token is enciphered under a randomly-generated object protection key (OPK). The
OPK is itself enciphered under the APKA master-key. The result is returned in an internal PKA key-token
identified by the target_key_identifier parameter. The verb also updates the target_key_identifier_length
variable to the length of the returned token, or 0 if a key label was identified.
To import an external trusted block so that it can be used as input by the Remote_Key_Export verb:
v Identify the active external trusted block to be imported using the source_key_token parameter. Use the
Trusted_Block_Create verb with the ACTIVATE rule-array keyword to obtain the token.
v Use the transport_key_identifier parameter to identify the DES IMP-PKA key used to encipher the
confounder and triple-length MAC key contained within the trusted block.
The confounder and MAC key are enciphered under the asymmetric master-key and returned along with
the updated MAC value in an internal trusted block identified by the target_key_identifier parameter. The
verb also updates the target_key_identifier_length variable to the length of the returned token, or 0 if a key
label was identified.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|

| v Not all IBM implementations of this verb might support an optimized form of the RSA private-key. Check
the product-specific literature. The IBM implementations support an optimized RSA private key (a key in
Chinese-Remainder Theorem format).
Beginning with Version 2, a clear, external RSA private-key in Modulus-Exponent format is presented in
a key section type X'02'. When imported, the enciphered private-key is returned in a X'06' type
private-token section.
v Not all IBM implementations of this verb support the use of a key label with the target-key identifier.
Check the product-specific literature.
v ECC keys and the token type keywords (ECC and RSA) are not supported in releases before Release
4.1.
| v An ECC private-key cannot be enciphered in releases before Release 4.2.
Format
CSNDPKI
source_key_token_length Input Integer 3500
source_key_token Input String source_key_token_length bytes
| transport_key_identifier Input String 64 bytes
target_key_identifier_length In/Output Integer 3500
target_key_identifier In/Output String target_key_identifier_length bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
Token type (one, optional). Release 4.1 or later.
ECC Specifies that the key being imported is an ECC key.
RSA Specifies that the key being imported is an RSA key or a trusted block. This is the default.

source_key_token_length
The source_key_token_length parameter is a pointer to an integer variable containing the number of
bytes of data in the source_key_token variable. The maximum length is 3500 bytes.
source_key_token
| The source_key_token parameter is a pointer to a string variable containing a PKA96 key-token or an
| active external trusted block. Beginning with Release 4.1, this parameter can also point to a string
| variable containing an ECC key-token. For a PKA96 or an ECC key-token, the token must contain
| both public-key and private-key information. The private key can be in cleartext or, in the case of an
| RSA key, it can be enciphered.
| The transport_key_identifier parameter is a pointer to a string variable containing an operational
| fixed-length DES key-encrypting-key token, an operational AES variable-length symmetric key-token
| (Release 4.2 or later), a null key-token, or a key label of such a record. This key is used to decipher
| an encrypted RSA private key or an encrypted MAC key contained in an external trusted block.
| Beginning with Release 4.2, this key can also be used to decipher an encrypted ECC private key.
| v When importing an encrypted ECC key, this key must be an AES key-encrypting key with a key type
| of IMPORTER that can be used for IMPORT.
| v When importing an encrypted RSA key, this key must be a fixed-length DES key-encrypting key with
| a key type of IMPORTER that can be used for IMPORT (control vector bit 21 on).
| v When importing an encrypted MAC key contained in an external trusted block, this key must be a
| fixed-length DES key-encrypting key with a key type of IMP-PKA.
| v When importing a source key that is not encrypted, this parameter must identify a null key-token
| (first byte of the key token must be X'00').
target_key_identifier_length
The target_key_identifier_length parameter is a pointer to an integer variable containing the number of
bytes of data in the target_key_identifier variable. The maximum length is 3500 bytes. On output, and
if the size is of sufficient length, the variable is updated with the actual length of the
target_key_identifier variable. The output length is 0 for a key label.
target_key_identifier
| The target_key_identifier parameter is a pointer to a string variable containing either a key label
| identifying a PKA key-storage record (internal ECC, RSA, or trusted block), or is other information that
| is overwritten with the imported key. If the key label identifies a key record in PKA key storage, the
| returned key-token replaces any key token associated with the label. If the first byte of the identified
| string does not indicate a key label (that is, not in the range X'20' - X'FE'), and the variable is of
| sufficient length to receive the result, then the key token is returned in the identified variable.
Required commands
The PKA_Key_Import verb requires the PKA96 PKA Key Import command (offset X'0104') to be enabled in
the active role.
If the source_key_token parameter points to a trusted block, also enable the Convert Trusted Block from
External to Internal Form command (offset X'0311').

PKA_Key_Token_Build (CSNDPKB)
The PKA_Key_Token_Build verb constructs a public-key architecture (PKA) key-token for an RSA key from
the supplied information. Beginning with Release 4.1, the verb can also construct a PKA key-token for an
ECC key.
This verb is used to create the following:

v A skeleton_key_token for use with the PKA_Key_Generate verb
v A key token with a public key that has been obtained from another source
v A key token with a clear private-key and the associated public key
Other than a skeleton key-token prepared for use with the PKA_Key_Generate verb, every PKA key-token
contains a public-key value. A token optionally contains a private-key value.
See PKA key tokens on page 585 for a description of the key token formats. You can create RSA private
key tokens for section types:
X'08' Using the RSA-CRT keyword to obtain a token format for an RSA key usable with the
Chinese-Remainder Theorem (CRT) algorithm with an Object Protection Key (OPK)
X'02' Using the RSA-PRIV keyword to obtain a token format for an RSA key in Modulus-Exponent (M-E)
format
X'04' Using the RSA-PUBL keyword to obtain a token format for an RSA public-key
| Beginning with Release 4.1, RSA private-key tokens can also be created for this section type:
| X'09' Using the RSAMEVAR keyword to obtain a token format for a key in M-E format.
For the ECC private key tokens:

X'20' Using the ECC-PAIR or ECC-PUBL keyword to obtain a token format for an ECC key
Specify the following factors:

v The token type:
ECC-PAIR for an ECC public and private key pair
ECC-PUBL for an ECC public key
RSA-CRT for an RSA public and RSA private key in CRT format with an OPK
RSA-PRIV for an RSA public and private key pair in M-E format
RSA-PUBL for an RSA public key in CRT format
RSAMEVAR for an RSA public and private key pair in M-E format
v The usage limits for a private key:
If an RSA private-key can be allowed to import a symmetric key, and the key can also be used to
create digital signatures, include the KEY-MGMT keyword in the rule array.
If a private key cannot be used in digital signature generation, include the KM-ONLY keyword in the
rule array.
If an RSA private-key cannot be used in importing of DES keys, you can include the SIG-ONLY
keyword in the rule array. This is the default.
v A key name when:
You need to specify the key-label for a retained private key in a skeleton key-token.
v Optional user-definable associated data for an ECC private key that is bound to the key and can
provide usage-control information.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The RSA-OPT rule-array keyword is not supported beginning with Version 2. Instead, use keyword
RSA-CRT to obtain a X'08' private-key section type.
v The RSA key length is limited to the range of 512 - 4096 bits, with specific formats restricted to a
maximum of 1024 or 2048 bits.
v When generating a key for use with ANS X9.31 digital signatures, the key length must be 1024, 1280,
1536, 1792, 2048, or 4096 bits.
v CCA permits the construction of a key token that has a modulus greater than 2048 bits and a public
exponent greater than 17 bits, but CCA does not permit such a token to be otherwise used within CCA.
| v Token types ECC-PAIR, ECC-PUBL, and RSAMEVAR are not supported in releases before Release
| 4.1
Format
CSNDPKB
key_values_structure_length Input Integer 3500
key_values_structure Input String key_values_structure_length bytes
key_name_length Input Integer 0 or 64
key_name Input String key_name_length bytes
user_definable_associated_data_length Input Integer null pointer or 0 - 100
| user_definable_associated_data Input String user_definable_associated_data_length bytes
reserved_2_length Input Integer null pointer or 0
reserved_2 Input String null pointer


token_length In/Output Integer 3500
token Output String token_length bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
Token type (one required)
ECC-PAIR Create a key token for an ECC public and private key-pair. Release 4.1 or later.
ECC-PUBL Create a key token for an ECC public-key. Release 4.1 or later.
RSA-CRT Create a key token for an RSA public-key and an RSA private-key in Chinese-Remainder Theorem
format with an OPK.
RSA-OPT Note: This keyword is not supported with Version 2 and later software.
RSA-PRIV Create a key token for an RSA public and private key pair in Modulus-Exponent format.
RSA-PUBL Create a key token for an RSA public key in Modulus-Exponent format.
RSAMEVAR Create a key token for an RSA public and private key pair in Modulus-Exponent format.
Translate control (one, optional). Not valid with token type ECC-PUBL or RSA-PUBL.
NO-XLATE Private key translation is not allowed. This is the default.
XLATE-OK Private key translation is allowed.
RSA key-usage control (one, optional). Not valid with token type ECC-PUBL or RSA-PUBL.
SIG-ONLY Selects a usage control to render the private key usable in digital-signature operations but not in
(DES) key import operations. This is the default.
KEY-MGMT Selects a usage control that allows an RSA private-key to be used in distribution of symmetric keys
and in digital-signature services.
KM-ONLY Selects a usage control to render the private key usable in (DES) key-import operations but not in
digital-signature operations.
key_values_structure_length
The key_values_structure_length parameter is a pointer to an integer variable containing the number
of bytes of data in the key_values_structure variable. The maximum length is 3500 bytes.
key_values_structure
The key_values_structure parameter is a pointer to a string variable containing a structure of the
lengths and data for the components of the key or keys. The contents of this structure are shown in
Table 11 on page 98, and sample data is described in Related information on page 100.

Table 11. PKA_Key_Token_Build key-values-structure contents, RSA keys
Offset (bytes) Length (bytes) Description
| RSA key-values structure, Modulus-Exponent form (RSA-PRIV, RSA-PUBL, or RSAMEVAR)
000 002 Length of the modulus in bits
512 - 1024 for RSA-PRIV
512 - 4096 for RSA-PUBL
512 - 4096 for RSAMEVAR
002 002 Length of the modulus field, n, in bytes: nnn. This value must not exceed
512 for a 4096-bit-length key.
This value should be zero when preparing a skeleton key token for use with
the PKA_Key_Generate verb.
004 002 Length of the public exponent field, e, in bytes: eee.
This value should be zero when preparing a skeleton key token to generate
a random-exponent public key in the PKA_Key_Generate verb. This value
must not exceed 512.
006 002 Private exponent field length in bytes, ddd. This value can be zero indicating
that private key information is not provided. This value must not exceed 512.
008 nnn Modulus, n, integer value, 1 < n < 24096; n = pq for prime p and prime q.
8 + nnn eee Public exponent field, e, integer value, 1 < e < n, e must be odd. When you
are building a skeleton_key_token to control the generation of an RSA key
pair, the public key exponent can be one of three values: 3, 65537 (216+1),
or 0 (zero) to indicate that a full-random exponent should be generated. The
exponent field can be a null-length field when preparing a
skeleton_key_token.
8 + nnn + eee ddd Private exponent, d, integer value, 1 < d < n, d = e-1mod(p-1)(q-1).
RSA key-values structure, Chinese-Remainder Theorem form (RSA-CRT)
000 002 Length of the modulus in bits (512 - 4096).
002 002 Length of the modulus field, n, in bytes: nnn. This value must not exceed
512.
This value should be zero when preparing a skeleton_key_token for use with
the PKA_Key_Generate verb.
004 002 Length of the public exponent field, e, in bytes: eee.
This value should be zero when preparing a skeleton key token to generate
a random-exponent public key in the PKA_Key_Generate verb. This value
must not exceed 512.
006 002 Reserved, binary zero.
008 002 Length of the prime number field, p, in bytes: ppp. Should be zero in a
skeleton key-token. The maximum value of ppp+qqq is 512 bytes.
010 002 Length of the prime number field, q, in bytes: qqq. Should be zero in a
skeleton key-token. The maximum value of ppp+qqq is 512 bytes.
012 002 Length of the dp field, in bytes: rrr. Should be zero in a skeleton key-token.
The maximum value of rrr + sss is 512 bytes.
014 002 Length of the dq field, in bytes: sss. Should be zero in a skeleton key-token.
The maximum value of rrr + sss is 512 bytes.
016 002 Length of the U field, in bytes: uuu. Should be zero in a skeleton key-token.
The maximum length of U is 256 bytes.
018 nnn Modulus, n.

Table 11. PKA_Key_Token_Build key-values-structure contents, RSA keys (continued)
018 + nnn eee Public exponent, e, integer value, 1 < e < n, e must be odd.
When you are building a skeleton_key_token to control the generation of an

RSA key pair, the public key exponent can be one of the following values: 3,
65537 (216+1), or 0 (zero) to indicate that a full-random exponent should be
generated. The exponent field can be a null-length field if the exponent value
is zero.
018 + nnn + ppp Prime number, p.
eee
018 + nnn + qqq Prime number, q.
eee + ppp
018 + nnn + rrr dp = d mod(p-1).
eee + ppp +
qqq
018 + nnn + sss dq = d mod(q-1).
eee + ppp +
qqq + rrr
018 + nnn + uuu U = q-1mod(p).
eee + ppp +
qqq + rrr + sss
Note: All length fields are in binary, and all binary fields (exponents, lengths, and so on) are stored with the
high-order byte first (left, low-address, big-endian, z/OS format).
Table 12. PKA_Key_Token_Build key-values-structure contents, ECC keys

ECC key-values structure, ECC-PAIR
000 001 Curve type:
X'00' Prime
X'01' Brainpool
| 002 002 Length of prime p in bits. See Table 110 on page 597 and Table 111 on
| page 597.
| X'00A0' 160 (Brainpool)
| X'00C0' 192 (Brainpool, Prime)
| X'00E0' 224 (Brainpool, Prime)
| X'0100' 256 (Brainpool, Prime)
| X'0140' 320 (Brainpool)
| X'0209' 521 (Prime)
004 002 Length of the private key field, d, in bytes: ddd. Maximum value is 66.
006 002 Length of the public key, Q, in bytes: xxx. Maximum value is 133 (including
one byte to indicate if the value is compressed).
| 008 ddd Private key, d. Should be zero in a skeleton key-token.
| 008 + ddd qqq Public key, Q. Should be zero in a skeleton key-token.

Table 12. PKA_Key_Token_Build key-values-structure contents, ECC keys (continued)
ECC key-values structure, ECC-PUBL
000 001 Curve type:
X'00' Prime
X'01' Brainpool
002 002 Length of p in bits.
004 002 Length of the public key, Q, in bytes: qqq. Maximum value is 133 (including
one byte to indicate if the value is compressed).
006 qqq Public key, Q.
key_name_length
The key_name_length parameter is a pointer to an integer variable containing the number of bytes of
data in the optional key_name variable. If the length is zero, the key-name section is not included in
the target token. To include a key name, set the length to 64. For token type RSA-PUBL, the value
must be 0.
key_name
The key_name parameter is a pointer to a string variable containing the name of the key. The name of
the key can consist of alphanumeric characters, the pound sign (#), the at sign (@), the dollar sign ($),
and the period (.), and must begin with an alphabetic character. See Key-label content on page 390.
user_definable_associated_data_length
The user_definable_associated_data_length parameter is a pointer to an integer variable containing
the number of bytes of data in the user_definable_associated_data variable. For token type keyword
ECC-PAIR, the value must be 0 - 100. For all other token types, the value must be 0 or the parameter
must be a null pointer.
user_definable_associated_data
The user_definable_associated_data parameter is a pointer to a string variable containing the
associated data defined by the user that will be placed following the IBM associated data in the output
token. See Table 112 on page 597. Associated data is not confidential, but is protected by a key wrap
mechanism.
reserved_n_lengths
Each reserved_n_length parameter is a pointer to an integer variable containing the number of bytes
of data in the corresponding reserved_n variable. These length variables are reserved for future use,
and each variable should be set to a null pointer or zero.
reserved_n's
Each reserved_n parameter is a pointer to a string variable that is reserved for future use. Each
reserved_n parameter should be set to a null pointer.
token_length
The token_length parameter is a pointer to an integer variable containing the number of bytes of data
in the token variable. On output, the variable contains the length of the token returned in the token
variable. The maximum length is 3500 bytes.
token
The token parameter is a pointer to a string variable containing the assembled token returned by the
verb.
Related information
Samples for the key_values_structure are shown in Table 13 on page 101 and Table 14 on page 101, (and
see the note following the examples).

Table 13. Sample key-values structure data for RSA keys
Key Structure
length Public length
Token type (bits) exponent Key-values structure (hexadecimal) (bytes)
Random (0) 0200 0000 0000 0000 0000 0000 0000 0000 0000 18
512 3 0200 0000 0001 0000 0000 0000 0000 0000 0000 03 19
65537 0200 0000 0003 0000 0000 0000 0000 0000 0000 010001 21
Random (0) 0300 0000 0000 0000 0000 0000 0000 0000 0000 18
768 3 0300 0000 0001 0000 0000 0000 0000 0000 0000 03 19
65537 0300 0000 0003 0000 0000 0000 0000 0000 0000 010001 21
Random (0) 0400 0000 0000 0000 0000 0000 0000 0000 0000 18
RSA-CRT 1024 3 0400 0000 0001 0000 0000 0000 0000 0000 0000 03 19
65537 0400 0000 0003 0000 0000 0000 0000 0000 0000 010001 21
Random (0) 0800 0000 0000 0000 0000 0000 0000 0000 0000 18
2048 3 0800 0000 0001 0000 0000 0000 0000 0000 0000 03 19
65537 0800 0000 0003 0000 0000 0000 0000 0000 0000 010001 21
Random (0) * 1000 0000 0000 0000 0000 0000 0000 0000 0000 18
4096 3 1000 0000 0001 0000 0000 0000 0000 0000 0000 03 19
65537 1000 0000 0003 0000 0000 0000 0000 0000 0000 010001 21
Random (0) 0200 0000 0000 0000 8
512 3 0200 0000 0001 0000 03 9
65537 0200 0000 0003 0000 010001 11
Random (0) 0300 0000 0000 0000 8
RSA-PRIV 768 3 0300 0000 0001 0000 03 9
65537 0300 0000 0003 0000 010001 11
Random (0) 0400 0000 0000 0000 8
1024 3 0400 0000 0001 0000 03 9
65537 0400 0000 0003 0000 010001 11
* CCA permits the construction of a key token that has a modulus greater than 2048 bits and a public exponent
greater than 17 bits, but CCA does not permit such a token to be otherwise used within CCA.
Table 14. Sample key-values structure data for ECC keys (Release 4.1 or later)
Length of Length of
| Length of private key d public key Q Key-values structure Structure
| ECC curve type prime p (bits) (bytes) (bytes) (hexadecimal) length (bytes)
192 0 0 0000 00C0 0000 0000 8
224 0 0 0000 00E0 0000 0000 8
Prime 256 0 0 0000 0100 0000 0000 8
384 0 0 0000 0180 0000 0000 8
521 0 0 0000 0209 0000 0000 8

Table 14. Sample key-values structure data for ECC keys (Release 4.1 or later) (continued)
Length of Length of
| Length of private key d public key Q Key-values structure Structure
| ECC curve type prime p (bits) (bytes) (bytes) (hexadecimal) length (bytes)
160 0 0 0100 00A0 0000 0000 8
192 0 0 0100 00C0 0000 0000 8
224 0 0 0100 00E0 0000 0000 8
Brainpool 256 0 0 0100 0100 0000 0000 8
320 0 0 0100 0140 0000 0000 8
384 0 0 0100 0180 0000 0000 8
| 512 0 0 0100 0200 0000 0000 8
Note: All values in the key_values_structure must be stored in big-endian format to ensure compatibility
among different computing platforms. Big-endian format specifies the high-order byte be stored at
the low address in the field.
Data stored by Intel architecture processors is normally stored in little-endian format. Little-endian format
specifies the low-order byte be stored in the low address in the field.
Required commands
None

PKA_Key_Token_Change (CSNDKTC)
The PKA_Key_Token_Change verb changes the enciphered data of an internal RSA private key-token and
of an active internal trusted block from encipherment under the old PKA master-key to encipherment under
the current PKA master-key. Beginning with Release 4.1, the verb can also change the enciphered object
protection key (OPK) of an ECC private key-token, from encipherment under the old APKA master-key, to
encipherment under the current APKA master-key. You identify the task with the rule-array keyword, and
the internal key-token to change with the key_identifier parameter.
Note: This verb is similar in function to the CSNBKTC Key_Token_Change verb used with CCA DES key
tokens.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Not all CCA implementations support this verb.
v ECC keys and the token type keywords (ECC and RSA) are not supported in releases before Release
4.1.
Format
CSNDKTC
key_identifier_length In/Output Integer 3500
key_identifier In/Output String key_identifier_length bytes
Parameters
rule_array_count

rule_array
Keyword Meaning
Token type (one, optional)
ECC Specifies that the key being changed is an ECC key.
RSA Specifies that the key being changed is an RSA key or a trusted block. This is the default.
Reencipherment method (required)
RTCMK Changes an RSA private key or a trusted block from encipherment under the old PKA
master-key, to encipherment under the current PKA master-key. Beginning with Release 4.1,
also changes an OPK of an ECC private key from encipherment under the old APKA
master-key to encipherment under the current APKA master-key.
key_identifier_length
The key_identifier_length parameter is a pointer to an integer variable containing the number of bytes
of data in the key_identifier variable. On output, the variable contains the length of the key token
returned by the verb if a key token (not a key label) was specified. The maximum length is 3500 bytes.
key_identifier
The key_identifier parameter is a pointer to a string variable containing an internal RSA or ECC
key-token, or an active internal trusted block, or a key label of an internal RSA or ECC key-token
record, or an active internal trusted block RSA key-token record. The enciphered data within the RSA
key-token or trusted block is securely reenciphered under the current PKA master-key. Beginning with
Release 4.1, the enciphered OPK of an ECC private key-token is securely reenciphered under the
current APKA master-key.
Required commands
The PKA_Key_Token_Change verb requires the PKA96 Reencipher to Current Master Key command
(offset X'0102') to be enabled in the active role.

PKA_Key_Translate (CSNDPKT)
The PKA_Key_Translate verb translates an external source RSA key-token into a target external smart
card key-token. The source RSA key-token must be wrapped with a transport (key-encrypting) key. The
XLATE bit must also be turned on in the key-usage byte of the source key-token. The source key-token is
unwrapped using the specified source transport key. The target key-token is then wrapped with the
specified target transport key. Existing information in the target token is overwritten.
To use this verb, specify the following:

v The smart card format with a keyword in the rule array:
SCVISA The Visa proprietary format
SCCOMME The common Modulus-Exponent (M-E) format
SCCOMCRT The common Chinese-Remainder Theorem (CRT) format
| v The source RSA external key-token or key identifier, which has been wrapped by a fixed-length DES
| transport key
v The source key-token or key identifier length
v The source transport key identifier to be used to unwrap the source key
v The target transport key identifier to be used to wrap the target key
v The target key-token length and buffer
Note: Specification of an EXPORTER source transport key and an IMPORTER target transport key is not
allowed.
The verb will build the external key-token:

v The source key-token will be unwrapped using the source transport key.
v The key material will be formatted into the specified target smart card format.
v The key material will be Triple-DES encrypted in ECB mode using the target transport key.
v The completed external smart card token is then written to the variable identified by the target token
parameter, and the target length is updated.
Restrictions
| AIX X X
| IBM i X X X
| Windows
|
| v RSA M-E key tokens are not translated to the SCCOMCRT format.
v RSA CRT key tokens are not translated to the SCCOMME format.
v SCVISA supports only M-E keys. ACI Smart Chip Manager Product Suite, System Design Specification,
RSA Private Key Formats 2008-2009 by ACI Worldwide B.V. All rights reserved. Author: V. Kessels.
v The maximum modulus size for keys that will be translated into the SCVISA format is 2040 bits,
because the length field for that format is limited to one byte.

Format
CSNDPKT
source_key_identifier_length Input Integer 3500
source_key_identifier Input String source_key_identifier_length
source_transport_key_identifier_length Input Integer 64
source_transport_key_identifier Input String source_transport_key_identifier_length bytes
target_transport_key_identifier_length Input Integer 64
target_transport_key_identifier Input String target_transport_key_identifier_length bytes
target_key_token_length In/Output Integer 3500
| target_key_token Output String target_key_token_length bytes
Parameters
rule_array_count
rule_array
Keyword Description
Smart card format (one required)
SCVISA Translate the key into the smart card Visa proprietary format.
SCCOMME Translate the key into the smart card Modulus-Exponent format.
SCCOMCRT Translate the key into the smart card Chinese-Remainder Theorem format.
See ACI smart card formats on page 630 for descriptions of the smart card formats.
source_key_identifier_length
The source_key_identifier_length parameter is a pointer to an integer variable containing the number
of bytes of data in the source_key_identifier variable. The maximum length is 3500 bytes.
source_key_identifier
| The source_key_identifier parameter is a pointer to a string variable containing either a key label
| identifying a PKA key-storage record for an RSA private-key, or an external RSA public-private
| key-token. The private key must be wrapped with a fixed-length DES key-encrypting key.

source_transport_key_identifier_length
The source_transport_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the source_transport_key_identifier variable. This value must be 64.
source_transport_key_identifier
The source_transport_key_identifier parameter is a pointer to a string variable containing the internal
key-token or a label for an internal key-token record in DES key-storage for a fixed-length DES
key-encrypting key. This key is used to unwrap the input PKA key-token identified by the
source_key_identifier parameter. See Required commands for details on the type of transport key
that is allowed.
target_transport_key_identifier_length
The target_transport_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the target_transport_key_identifier variable. This value must be 64.
target_transport_key_identifier
| The target_transport_key_identifier parameter is a pointer to a string variable containing the internal
| key-token or a label for an internal key-token record in DES key-storage for a fixed-length DES
| key-encrypting key. This key is used to wrap the output RSA key returned with parameter
| target_key_token. See Required commands for details on the type of transport key that is allowed.
target_key_token_length
The target_key_token_length parameter is a pointer to an integer variable containing the length of the
target_key_token variable in bytes. On output, the value in this variable is updated to contain the
actual length of the target_key_token produced by the verb. The maximum length is 3500 bytes.
target_key_token
The target_key_token parameter is a pointer to a string variable containing the buffer for the translated
RSA key.
Required commands
The PKA_Key_Translate verb requires the following commands to be enabled in the active role based on
the keyword:

SCVISA X'0318' Translate from CCA RSA to SC Visa Format
SCCOMME X'0319' Translate from CCA RSA to SC M-E Format
SCCOMCRT X'031A' Translate from CCA RSA to SC CRT Format
These commands must also be enabled to allow the key type combinations shown in this table:
Source transport key Target transport key

type type Offset Command
EXPORTER EXPORTER X'031B' XLATE from encryption under source EXP KEK to
target EXP KEK
IMPORTER EXPORTER X'031C' XLATE from encryption under source IMP KEK to
target EXP KEK
IMPORTER IMPORTER X'031D' XLATE from encryption under source IMP KEK to
target IMP KEK
EXPORTER IMPORTER N/A This key type combination is not allowed.

PKA_Public_Key_Extract (CSNDPKX)
The PKA_Public_Key_Extract verb is used to extract an RSA public-key from a PKA key-token that
contains a public-private RSA key-pair. Beginning with Release 4.1, the public-private keys can be an ECC
key-pair. The extracted public key is returned in a PKA public-key token.
Both the public key and the related private key must be present in the source PKA key-token. The source
RSA private-key can be in the clear or enciphered. The source ECC private-key can be in the clear.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Keys with a modulus length greater than 2048 bits are not supported in releases before Release 3.30.
v ECC keys are not supported in releases before Release 4.1.
Format
CSNDPKX
source_key_identifier Input String source_key_identifier_length bytes
target_key_token_length In/Output Integer 3500
target_key_token Output String target_key_token_length bytes
Parameters
rule_array_count
rule_array

characters. The rule_array parameter is not presently used by this verb, but must be specified.
of bytes of data in the source_key_identifier variable. The maximum length is 3500 bytes.
The source_key_identifier parameter is a pointer to a string variable containing either a key label
identifying a PKA key-storage record or a PKA key-token. The key token must contain an RSA
public-private key pair or, beginning with Release 4.1, and ECC public-private key pair.
The target_key_token_length parameter is a pointer to an integer variable containing the number of
bytes of data in the target_key_token variable. On output, the variable contains the length of the key
token returned by the verb. The maximum length is 3500 bytes.
target_key_token
The target_key_token parameter is a pointer to a string variable containing the PKA key-token with the
extracted public key returned by the verb.
Required commands
None

PKA_Public_Key_Hash_Register (CSNDPKH)
The PKA_Public_Key_Hash_Register verb is used to register a hash value for an RSA public-key in
anticipation of verifying the public key offered in a subsequent use of the PKA_Public_Key_Register verb.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNDPKH
public_key_name Input String 64 bytes
| hash_data_length Input Integer 20 - 128
hash_data Input String hash_data_length bytes
Parameters
rule_array_count
rule_array

Keyword Meaning
Hash type (required)
SHA-1 The hash algorithm used to create the hash value.
Special usage (optional)
CLONE Indicates that the RSA public-key associated with this hash value can be employed in a CCA
node-cloning process provided that this usage is confirmed when the public key is registered.
public_key_name
The public_key_name parameter is a pointer to a string variable containing the name under which the
registered public key is accessed.
hash_data_length
The hash_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the hash_data variable.
hash_data
The hash_data parameter is a pointer to a string variable containing the SHA-1 hash of an RSA
public-key certificate that is offered with the use of the PKA_Public_Key_Register verb. The format of
the public-key certificate is defined in RSA public-key certificate section on page 594.
Required commands
The PKA_Public_Key_Hash_Register verb requires the PKA Register Public Key Hash command (offset
X'0200') to be enabled in the active role.

PKA_Public_Key_Register (CSNDPKR)
The PKA_Public_Key_Register verb is used to register an RSA public-key in the cryptographic engine.
Keywords in the rule array designate the subsequent permissible uses of the registered public key.
Note: Currently the only supported use of a registered RSA public-key is for a CCA node cloning process.
The RSA public-key offered for registration must be contained in a PKA key-token that contains a
certificate section (see Table 103 on page 595). The public-key value contained in the certificate is the key
that is registered. A preregistered hash value over the certificate section, exclusive of the certificate
signature bits, is used to independently validate the offered key. See the PKA_Public_Key_Hash_Register
verb and PKA key tokens on page 585 for more information.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNDPKR
| rule_array_count Input Integer 1
public_key_name Input String 64 bytes
public_key_certificate_length Input Integer
public_key_certificate Input String public_key_certificate_length bytes
Parameters
rule_array_count
| in the rule_array variable. The value must be 1.

rule_array
Keyword Meaning
| Special usage (one required)
CLONE Indicates that the registered RSA public-key can be employed in a CCA node cloning process
provided that this usage was also asserted when the hash value was registered.
public_key_name
The public_key_name parameter is a pointer to a string variable containing the name under which the
registered public key is accessed.
public_key_certificate_length
The public_key_certificate_length parameter is a pointer to an integer variable containing the number
of bytes of data in the public_key_certificate variable.
public_key_certificate
The public_key_certificate parameter is a pointer to a string variable containing an RSA public-key to
be registered. The public key must be presented in a public-key certificate section. See RSA
public-key certificate section on page 594.
Required commands
The PKA_Public_Key_Register verb requires the PKA Public Key Register command (offset X'0201') to be
If you specify the CLONE rule-array keyword, also enable the PKA Public Key Register with Cloning
command (offset X'0202').

Chapter 4. Hashing and digital signatures
This section discusses the data hashing and the digital signature techniques you can use to determine
data integrity. A digital signature might also be used to establish the nonrepudiation security property.
(Another approach to data integrity based on DES message authentication codes is discussed in
Chapter 6, Data confidentiality and data integrity.)
v Data integrity and data authentication techniques enable you to determine that a data object (a string of
bytes) has not been altered from some known state.
v Nonrepudiation permits you to assert that the originator of a digital signature might not later deny having
created the digital signature.
This section explains how to determine the integrity of data. Determining data integrity involves
determining whether individual values of a string of bytes have been altered. Two techniques are
described:
v Hashing
v Digital signatures
Digital signatures use both hashing and RSA public-key cryptography. Beginning with Release 4.1, ECC
public-key cryptography support is added.
The following table describes verbs used in hashing and digital signature services. See Verbs used in
hashing and digital signature services on page 117 for a detailed description of the verbs.
Table 15. Hashing and digital signature services
Service
Digital_Signature_Generate 118 This verb generates a digital signature. CSNDDSG E
Digital_Signature_Verify 122 This verb verifies a digital signature. CSNDDSV E
MDC_Generate 126 This verb generates a hash value using the CSNBMDG E
Modification Detection Code (MDC) one-way
function.
One_Way_Hash 134 This verb generates a hash value using CSNBOWH S/E
SHA-1, SHA-224, SHA-256, SHA-384,
SHA-512, Message Digest-5 (MD5), or
RIPEMD-160 one-way hashing functions.
Note: Keys with a modulus length greater than 2048 bits are not supported in releases before Release
3.30.
Hashing
Data hashing functions have long been used to determine the integrity of a block of data. The application
of a hash function to a data string produces a quantity called a hash value (also referred to as a hash, a
message digest, or a fingerprint). The most common hashing functions produce hash values of 128 or 160
bits. Newer, stronger hash functions that produce hash values of 224, 256, 384, 512, or more bits are also
available. While many different strings supplied to a cryptographically-useful hashing function produce the
same hash value, it is computationally infeasible to determine a modification to a data string that results in
a desired hash-value.
Hash functions for data integrity applications have a one-way property: given a hash value, it is highly
improbable that a second data string can be found that hashes to the same value as the original.
Consequently, if a hash value for a string is known, you can compute the hash value for another string
115
suspected to be the same and compare the two hash values. If both hash values are identical, there is a
very high probability that the strings producing them are identical.
The CCA products provide support for the following hash functions:
Secure Hash Algorithms
FIPS 180-2 defines multiple secure hash algorithms. CCA products support these secure hash
algorithms, namely SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.
| v SHA-1 produces a 20-byte, 160-bit hash value. SHA-1 is specified for use with the Digital
| Signature Standard (DSS).
v SHA-224 produces a 28-byte, 224-bit hash value.
| Notes:
| 1. Secure hash algorithms perform best on big-endian, general-purpose computers.
| 2. The SHA-1, SHA-256, SHA-384, and SHA-512 methods are specified in FIPS 180-2, August 1,
| 2002. The SHA-1 method was originally specified in FIPS 180-1, May 31, 1994. The MD5
| method is specified in RFC 1321, dated April 1992.
RIPEMD-160
| RIPEMD-160 is a 160-bit cryptographic hash function. It is intended to be used as a secure
| replacement for the 128-bit hash functions MD5 and RIPEMD. The RIPEMD-160 method is an
| outgrowth of the EU project RIPE (RACE Integrity Primitives Evaluation); further information can
| be found on the Internet under RIPEMD.
Message Digest-5 (MD5)
| MD5 is specified in the Internet Engineering Task Force RFC 1321 and produces a 16-byte,
| 128-bit hash value. This algorithm performs best on little-endian, general-purpose computers (for
| example, Intel). Note that SHA is usually preferred over MD5 if the application designers have a
| choice of algorithms.
Modification Detection Code (MDC)
MDC is based on the DES algorithm and produces a 16-byte, 128-bit hash value. This hashing
algorithm is considered quite strong. However, it performs rapidly only when supported by
DES-hardware units specifically designed for MDC. See Modification Detection Code calculation
on page 679 for a description of the MDC algorithm.
There are many different approaches to data integrity verification. In some cases, you can simply make
known the hash value for a data string. Anyone wanting to verify the integrity of the data would recompute
the hash value and compare the result to the known-to-be-correct hash value. In other cases, you might
want someone to prove to you that they possess a specific data string, in which case you could randomly
generate a challenge string, append the challenge string to the string in question, and hash the result. You
would then provide the other party with the challenge string, ask them to perform the same hashing
process, and return the hash value to you. This method forces the other party to rehash the data. When
the two hash values are the same you can be confident that the strings are the same, and the other party
actually possesses the data string, and not merely a hash value.
The hashing services described in this section allow you to divide a string of data into parts, and compute
the hash value for the entire string in a series of calls to the appropriate verb. This can be useful if it is not
possible to bring the entire string into memory at one time.

Digital signatures
You can protect data from undetected modification by including a proof-of-data-integrity value. This value is
called a digital signature, and relies on both public-key cryptography and hashing. To create a digital
signature, hash the data and encrypt the results of the hash using your RSA private-key. Beginning with
Release 4.1, an ECC private-key can be used to encrypt the results of the hash.
Anyone with access to the associated RSA or ECC public-key can verify the digital signature information
by performing the following steps:
1. Hash the data using the same hashing algorithm used to create the digital signature.
2. Decrypt the digital signature using the associated RSA or ECC public-key.
3. Compare the decrypted results to the hash value obtained from hashing the data.
4. An equal comparison confirms that the verified data is the same as the digitally signed data.
The Digital_Signature_Generate and the Digital_Signature_Verify verbs described in this section perform
the hash encrypting and decrypting operations. The requirements are:
v No one else should have access to the private key used to sign the data, and the use of the private key
must be controlled so that someone else cannot sign data as though they were you.
v The verifying party must have your associated RSA or ECC public-key. They assure themselves that
they do have your public key using one or more certificates from one or more Certification Authorities.
Tip: Verifying public keys also involves using digital signatures.

v The value that is encrypted and decrypted using RSA public-key technology must be the same length in
bits as the modulus of the keys. This bit length is normally 512, 768, 1024, 2048, or 4096. Because the
hash value is either 128 or 160 bits in length, some process for formatting the hash into a structure for
RSA encrypting must be selected. Unlike the DES algorithm, the strength of the RSA algorithm is
sensitive to the characteristics of the data being encrypted. Beginning with Release 4.1, the value can
be encrypted using ECC public-key cryptography.
With the Digital_Signature_Generate and the Digital_Signature_Verify verbs, several different
digital-signature hash formatting methods are available using RSA keys. The rule-array keywords for the
digital signature verbs contain brief descriptions of these formatting approaches:
ANS X9.31
ISO/IEC 9796-1
PKCS #1 block-type 00 (RSA PKCS #1 v1.5 standard)
PKCS #1 block-type 01 (RSA PKCS #1 v2.0 standard, signature scheme RSASSA-PKCS1 v1_5)
Zero-bit padding
There is only one digital-signature hash formatting method available for using ECC keys.
The receiver of data signed using digital signature techniques can, in some cases, assert non-repudiation
of the data. Non-repudiation means that the originator of the digital signature cannot later deny having
originated the signature and, therefore, the data. The use of digital signatures in legally binding situations
is gaining favor as commerce is increasingly conducted through networked communications. The
techniques described in this section are the most common methods of digital signing.
Verbs used in hashing and digital signature services
Chapter 4. Hashing and digital signatures 117

Digital_Signature_Generate (CSNDDSG)
The Digital_Signature_Generate verb is used to generate a digital signature, using an RSA private-key,
either contained in a PKA key-token or a trusted block. Beginning with Release 4.1, an ECC private-key
can be used to generate a digital signature.
You supply the following information:

v Beginning with Release 4.1, an optional rule-array keyword to select the signature algorithm
v An optional rule-array keyword to select the digital-signature hash formatting method
v For ANS X9.31, a rule-array keyword to select the hashing-method specification
v The RSA private key or, beginning with Release 4.1, the ECC private key
v The hash value
v The address where the verb returns the digital signature
The hash quantity can be created using the One_Way_Hash or the MDC_Generate verb.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v An RSA private-key flagged as a key-management-only key (in the private-key section, offset 50, valued
to X'C0') is not usable in this verb. An ECC private-key flagged as a key-agreement-only key (in the
private key section, offset 8, valued to X'C0') is not usable in this verb. See PKA_Key_Token_Build
(CSNDPKB) on page 95 and PKA_Key_Generate (CSNDPKG) on page 87.
v Starting with Release 3, the hash length is restricted to less than or equal to 36 bytes when using an
RSA private-key flagged as a key-management-capable key (in the private-key section, offset 50,
high-order bit on). You can override this restriction with the use of the Override DSG ZERO-PAD Length
Restriction command, offset X'030C'.
v Not all IBM implementations of this verb might use an optimized form of the RSA private-key, however,
the IBM 4765 and IBM 4764 can use this verb with an optimized RSA private-key in Chinese-Remainder
Theorem format.
v Not all CCA implementations use each digital-signature hash formatting method.
v The modulus length of a key used with ANS X9.31 digital signatures must be one of 1024, 1280, 1536,
1792, 2048, or 4096 bits.
v ECC keys and the token algorithm keywords (ECDSA and RSA) are not supported in releases before
Release 4.1.

Format
CSNDDSG
rule_array_count Input Integer 0, 1, 2, or 3
PKA_private_key_identifier_length Input Integer 3500
PKA_private_key_identifier Input String PKA_private_key_identifier_length bytes
hash_length Input Integer 512
hash Input String hash_length bytes
signature_field_length In/Output Integer 512
signature_bit_length Output Integer
signature_field Output String signature_field_length bytes
Parameters
rule_array_count
in the rule_array variable. The value must be 0, 1, 2, or 3.
rule_array
Keyword Meaning
Signature algorithm (one, optional). Release 4.1 or later.
ECDSA Specifies to generate an ECC digital signature.
RSA Specifies to generate an RSA digital signature. This is the default.
Digital-signature hash formatting method (one, optional). Not valid with ECDSA keyword.
ISO-9796 Specifies to format the hash according to the ISO/IEC 9796-1 standard and generates
the digital signature. This is the default. See Formatting hashes and keys in public-key
cryptography on page 694.
PKCS-1.0 Specifies to format the digital signature on the string supplied in the hash variable as
defined in the RSA PKCS #1 standard for block-type 00. The PKCS #1 v2.0 standard
no longer defines this signature scheme. See PKCS #1 hash formats on page 694.
PKCS-1.1 Specifies to format the digital signature on the string supplied in the hash variable as
defined in the RSA PKCS #1 v2.0 standard for the RSASSA-PKCS1-v1_5 signature
scheme. This was formerly known as block-type 01. See PKCS #1 hash formats on
page 694.
X9.31 Specifies to format the hash according to the ANS X9.31 standard and generates the
digital signature. See ANS X9.31 hash format on page 694.

Keyword Meaning
| ZERO-PAD Specifies to place the input value supplied in the hash variable in the low-order bit
| positions of a bit-string of the same length as the modulus. Sets each non-hash-value
| bit position to B'0'. Enciphers the padded hash value to obtain the digital signature.
Hashing-method specification (one required). Valid only with X9.31 digital-signature hash formatting method.
SHA-1 The input value supplied in the hash variable is generated using the SHA-1 hash
method.
method (Release 3.30.05 or later).
method (Release 4.0 or later).
method (Release 4.0 or later).
RPMD-160 The input value supplied in the hash variable is generated using the RIPEMD-160 hash
method.
Tips:
1. Use the MD5 or SHA-1 algorithms to create the hash for PKCS-1.0 and PKCS-1.1.
2. Use any method to obtain the hash for ISO-9796 and ZERO-PAD.
3. See Formatting hashes and keys in public-key cryptography on page 694 for a discussion of
hash formatting methods.
4. Use SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512 to obtain the hash for ECDSA.
PKA_private_key_identifier_length
The PKA_private_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the PKA_private_key_identifier variable. The maximum length is 3500
bytes.
PKA_private_key_identifier
The PKA_private_key_identifier parameter is a pointer to a string variable containing either a key label
identifying an RSA key-token in PKA key-storage or retained key-storage, or an internal public-private
RSA key-token.
Beginning with Release 4.1, this parameter can also point to a string variable containing either a key
label identifying an ECC key-token in PKA key-storage, or an internal public-private ECC key-token.
hash_length
The hash_length parameter is a pointer to an integer variable containing the number of bytes of data
in the hash variable. Beginning with Release 4.1, this value must be 20 for SHA-1, 28 for SHA-224, 32
for SHA-256, 48 for SHA-384, and 64 for SHA-512.
hash
The hash parameter is a pointer to a string variable containing the information to be signed.
Notes:
1. For ISO-9796, the information identified by the hash parameter must be less than or equal to
one-half of the number of bytes required to contain the modulus of the RSA key. This verb requires
the input text to be a byte multiple up to the correct maximum length.
2. For PKCS-1.0 or PKCS-1.1, the information identified by the hash parameter must be 11 bytes
shorter than the number of bytes required to contain the modulus of the RSA key, and should be
the Abstract Syntax Notation One (ASN.1) Basic Encoding Rules (BER) encoding of the hash
value.
| You can create the BER encoding of an MD5, SHA-1, or SHA-256 value by prepending the
| appropriate string to the hash value. See PKCS #1 hash formats on page 694.

| 3. For ZERO-PAD, the information identified by the hash parameter must be less than or equal to the
| number of bytes required to contain the modulus of the RSA key. If the private key permits both
| signature and key-management usage, the hash length is restricted to not more than 36 bytes
| unless the Override DSG ZERO-PAD Length Restriction command (offset X'030C') is enabled in
| the active role.
| 4. See Formatting hashes and keys in public-key cryptography on page 694 for a discussion of
| hash formatting methods.
| signature_field_length
| The signature_field_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the signature_field variable. On output, if the size is sufficient, the variable contains the
| actual length of the digital signature returned by the verb. The maximum value is 512 for RSA digital
| signatures. For ECC, the maximum value is 132.
| signature_bit_length
| The signature_bit_length parameter is a pointer to an integer variable containing the number of bits of
| data of the digital signature returned in the signature_field variable.
| signature_field
| The signature_field parameter is a pointer to a string variable containing the stored digital signature.
| The digital signature bit-field is in the low-order bits of the byte string containing the digital signature.
| See ANS X9.62 for information on the ECDSA signature algorithm.
Required commands
v The Digital_Signature_Generate verb requires the PKA96 Digital Signature Generate command (offset
v With the use of the Override DSG ZERO-PAD Length Restriction command (offset X'030C'), the
hash-length restriction does not apply when using ZERO-PAD formatting.

Digital_Signature_Verify (CSNDDSV)
The Digital_Signature_Verify verb is used to verify a digital signature using an RSA public-key. Beginning
with Release 4.1, an ECC public-key can be used to verify a digital signature.
Provide the digital signature, the public key, an optional hash formatting method keyword, and the hash of
the data to be validated. The hash quantity can be created through use of the One_Way_Hash verb, or for
RSA, also the MDC_Generate verb. Beginning with Release 4.1, optionally provide a token-algorithm
keyword.
In addition to using RSA or ECC public keys that are contained in PKA key tokens, digital signatures can
be verified using RSA public keys that are contained in trusted blocks. This verification occurs regardless
of whether the block also contains rules to govern its use when generating or exporting keys with the
Remote_Key_Export (CSNDRKX) verb.
The digital-signature hash formatting method is selected through the use of a keyword in the rule array.
The supplied hash information is formatted and compared to the public-key-ciphered digital signature.
An optional trusted public key restriction can also be selected through the use of the TPK-ONLY keyword.
When this keyword is selected, the use of regular CCA RSA or ECC key tokens is rejected, and only the
use of a (trusted) RSA public-key contained in a trusted block (identified by the PKA_public_key_identifier
parameter) can be used to verify the digital signature. Use of the TPK-ONLY keyword assures that a
sensitive signature-verification is limited to operation with trusted public keys only.
If the digital signature is validated, the verb returns a return code of 0. If the digital signature is not
validated, and there are no other problems, the verb returns a return code of 4 and reason code of 429
(X'01AD').
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Not all CCA implementations support each digital-signature hash formatting method.
v The maximum public exponent is 17 bits for any key that has a modulus greater than 2048 bits.
v ECC keys and the token algorithm keywords (that is, ECDSA and RSA) are not supported in releases
before Release 4.1.

Format
CSNDDSV
PKA_public_key_identifier_length Input Integer 3500
PKA_public_key_identifier Input String PKA_public_key_identifier_length bytes
hash_length Input Integer 512
hash Input String hash_length bytes
signature_field_length Input Integer
signature_field Input String signature_field_length bytes
Parameters
rule_array_count
rule_array
characters. The rule_array keywords are shown below:

Keyword Meaning
Token algorithm (one, optional). Release 4.1 or later.
ECDSA Specifies to verify an ECC digital signature.
RSA Specifies to verify an RSA digital signature. This is the default.
Digital-signature hash formatting method (one, optional). Not valid with ECDSA keyword.
ISO-9796 Specifies to format the hash according to the ISO/IEC 9796-1 standard and
compares to the digital signature. This is the default. See Formatting hashes
and keys in public-key cryptography on page 694.
PKCS-1.0 Specifies to format the digital signature on the string supplied in the hash
variable as defined in the RSA PKCS #1 standard for block-type 00 and compare
to the digital signature. The PKCS #1 v2.0 standard no longer defines this
signature scheme. See PKCS #1 hash formats on page 694.
PKCS-1.1 Specifies to format the digital signature on the string supplied in the hash
variable as defined in the RSA PKCS #1 v2.0 standard for the
RSASSA-PKCS1-v1_5 signature scheme, and compare to the digital signature.
This was formerly known as block-type 01. See PKCS #1 hash formats on
page 694.
X9.31 Specifies to format the hash according to the ANS X9.31 standard and compares
to the digital signature. See ANS X9.31 hash format on page 694.
| ZERO-PAD Specifies to place the input value supplied in the hash variable in the low-order
| bit positions of a bit-string of the same length as the modulus with all
| non-hash-value bit positions set to zero. After enciphering the supplied digital
| signature, the result is compared to the hash-extended bit string.
Trusted public key restriction (one, optional). Not valid with ECDSA keyword. Valid only with trusted blocks.
TPK-ONLY Permits the use of only public keys contained in trusted blocks. By specifying this
Trusted Public Key only keyword, the use of regular CCA RSA key tokens is
rejected and only the use of a (trusted) public key supplied by the
PKA_public_key_identifier parameter can be used to verify the digital signature,
thus assuring a sensitive signature verification operation is limited to trusted
public keys.
If TPK-ONLY is specified, the PKA_public_key_identifier parameter must identify

a trusted block that contains two sections after the trusted block token header:
(1) trusted block trusted RSA public key (section X'11'), and (2) trusted block
information (section X'14'). Section X'14' is required for all trusted blocks. Section
X'11' contains the trusted public key, and its usage rules must indicate it can be
used in digital signature operations.
PKA_public_key_identifier_length
The PKA_public_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the PKA_public_key_identifier variable. The maximum length is 3500 bytes.
PKA_public_key_identifier
The PKA_public_key_identifier parameter is a pointer to a string variable containing an internal trusted
block or an RSA key-token, or the key label of an internal trusted block or an RSA key-token or
registered RSA public-token record. For ECC, the parameter is a pointer to a string variable containing
an ECC key-token, or the key label of an ECC key-token.
hash_length
in the hash variable.
hash
The hash parameter is a pointer to a string variable containing the hash information to be verified.

Notes:
1. For ISO-9796, the information identified by the hash parameter must be less than or equal to
one-half of the number of bytes required to contain the modulus of the RSA key. This verb requires
the input text to be a byte multiple up to the correct maximum length.
2. For PKCS-1.0 or PKCS-1.1, the information identified by the hash parameter must be 11 bytes
shorter than the number of bytes required to contain the modulus of the RSA key, and should be
the Abstract Syntax Notation One (ASN.1) Basic Encoding Rules (BER) encoding of the hash
value.
| You can create the BER encoding of an MD5, SHA-1, or SHA-256 value by prepending the
| appropriate string to the hash value. See PKCS #1 hash formats on page 694.
| 3. For ZERO-PAD, the information identified by the hash parameter must be less than or equal to the
| number of bytes required to contain the modulus of the RSA key.
| signature_field_length
| The signature_field_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the signature_field variable.
| signature_field
| The signature_field parameter is a pointer to a string variable containing the digital signature. The
| digital signature bit-field is in the low-order bits of the byte string containing the digital signature.
| Required commands
| The Digital_Signature_Verify verb requires the PKA96 Digital Signature Verify command (offset X'0101') to
| be enabled in the active role.

| MDC_Generate (CSNBMDG)
| IMPORTANT NOTICE:
| In releases before Release 3.30, it was discovered that under certain conditions the MDC_Generate
| verb produced incorrect MDC values. Beginning with Release 3.30.05, these conditions no longer
| produce incorrect results.
| If you have MDC values that were generated using a release before Release 3.30.05, corrective
| action might be required before using these values with Release 3.30 (or later) to validate data
| integrity. See Related information on page 128 for detailed information.
|
|
| Use the MDC_Generate verb to create a 128-bit hash value (Modification Detection Code) on a data string
| whose integrity you intend to confirm. After using this verb to generate an MDC, you can compare the
| MDC to a known value or communicate the value to another entity so that they can compare the MDC
| hash value to one that they calculate. The MDC_Generate verb enables you to perform the following
| tasks:
| v Specify the two-encipherment or four-encipherment version of the algorithm
| v Segment your text into a series of verb calls
| v Use the default or a keyed-hash algorithm
| For a description of the MDC calculations, see Modification Detection Code calculation on page 679.
| Specifying two or four encipherments: Four encipherments per algorithm round improve security; two
| encipherments per algorithm round improve performance. To specify the number of encipherments, use
| the MDC-2, MDC-4, PADMDC-2, or PADMDC-4 keyword with the rule_array parameter. Two
| encipherments create results that differ from four encipherments; ensure that the same number of
| encipherments are used to verify the MDC.
| Segmenting text: The MDC_Generate verb lets you segment text into a series of verb calls. If you can
| present all of the data to be hashed in a single invocation of the verb (32 MB) of data), use the rule array
| keyword ONLY. Alternatively, you can segment your text and present the segments with a series of verb
| calls. Use the rule array keywords FIRST and LAST for the first and last segments. If more than two
| segments are used, specify the rule_array keyword MIDDLE for the additional segments.
| Between verb calls, unprocessed text data and intermediate information from the partial MDC calculation is
| stored in the chaining_vector variable and the MDC key in the MDC variable. During segmented
| processing, the application program must not change the data in either of these variables.
| Keyed hash: The MDC_Generate verb can be used with a default key, or as a keyed-hash algorithm. A
| default key is used whenever the ONLY or FIRST segmenting and key control keywords are used. To use
| the verb as a keyed-hash algorithm, do the following:
| 1. On the first call to the verb, place the non-null key into the MDC variable.
| 2. Ensure that the chaining_vector variable is set to null (18 bytes of X'00').
| 3. Decide if the text will be processed in a single segment or multiple segments.
| v For a single segment of text, use the LAST keyword.
| v For multiple segments of text, begin with the MIDDLE keyword and continue using the MIDDLE
| keyword up to the final segment of text. For the final segment, use the LAST keyword.
| As with the default key, you must not alter the value of the MDC or chaining_vector variables between
| calls.

| Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v When padding is requested (by specifying an algorithm mode keyword of PADMDC-2 or PADMDC-4), a
text length of zero is valid for any segment-control keyword specified in the rule_array variable FIRST,
MIDDLE, LAST, or ONLY). When LAST or ONLY is specified, the supplied text is padded with X'FF'
bytes and a padding count in the last byte to bring the total text length to the next multiple of 8 that is
greater than or equal to 16.
v When no padding is requested (by specifying an algorithm mode keyword of MDC-2 or MDC-4), the
total length of text provided (over a single or segmented calls) must be at least 16 bytes and a multiple
of 8 bytes. For segmented calls (that is, segmenting and key control keyword is not ONLY), a text
length of zero is valid on any of the calls.
Format
CSNBMDG
return_code Input Integer See Appendix A.
reason_code Input Integer See Appendix A.
| text_length Input Integer 0
text Input String text_length bytes
chaining_vector In/Output String 18 bytes
MDC In/Output String 16 bytes
Parameters
text_length
The text_length parameter is a pointer to an integer variable containing the number of bytes of data in
the text variable. See Restrictions.
text
The text parameter is a pointer to a string variable containing the text for which the verb calculates the
MDC value.

rule_array_count
rule_array
Keyword Meaning
Segmenting and key control (one, optional)
ONLY Specifies that segmenting is not used and the default key is used. This is the
default.
FIRST Specifies the first segment of text, and use of the default key.
MIDDLE Specifies an intermediate segment of text, or the first segment of text and use of a
user-supplied key.
LAST Specifies the last segment of text, or that segmenting is not used, and use of a
user-supplied key.
Algorithm mode (one, optional)
MDC-2 Specifies two encipherments for each 8-byte block using MDC procedures. This is
the default.
MDC-4 Specifies four encipherments for each 8-byte block using MDC procedures.
PADMDC-2 Specifies two encipherments for each 8-byte block using PADMDC procedures.
PADMDC-4 Specifies four encipherments for each 8-byte block using PADMDC procedures.
chaining_vector
The chaining_vector parameter is a pointer to an 18-byte string variable the security server uses as a
work area to hold segmented data between verb invocations.
Important: When segmenting text, the application program must not change the data in this string
between verb calls to the MDC_Generate verb.
MDC
The MDC parameter is a pointer to a user-supplied MDC key or to a 16-byte string variable containing
the MDC value. This value can be the key that the application program provides. This variable is also
used to hold the intermediate MDC result when segmenting text.
Important: When segmenting text, the application program must not change the data in this string
between verb calls to the MDC_Generate verb.
Required commands
The MDC_Generate verb requires the Generate MDC command (offset X'008A') to be enabled in the
active role.
Related information
In releases before Release 3.30, it was discovered that the MDC_Generate verb produced incorrect MDC
values under certain conditions. If you have any MDC values generated using Release 3.30.04 or earlier,
read this section to determine what conditions produce incorrect MDC values. If necessary, take corrective
action as described below.
Audience: If you are an IBM System i, System p, or System x customer of the IBM CCA Support
Program who generated MDC values using the MDC_Generate (CSNBMDG) verb with Release 3.30.04 or
earlier, please read the following important information related to the integrity of your data.

Overview: It was discovered that under certain conditions, the CSNBMDG verb of the CCA Support
Program generates incorrect MDC values. This section describes in detail each scenario that results in
these incorrect MDC values.
Terminology: The following terminology is used to describe the conditions that produce incorrect MDC
values:
v Total text length (TTL). TTL is the total number of text bytes processed to calculate a final MDC value.
v Running text length (RTL). RTL is the total number of text bytes processed by all previous calls used to
calculate a final MDC value.
v Carryover length (COL). COL is the number of text bytes that could not be processed in the previous
call. The COL can range from 0 to 15 bytes and is stored in the chaining vector between calls.
v New text length (NTL). NTL is the carryover length plus the text length for the current call.
Notes:
1. An intermediate MDC calculation always operates on 8 bytes of text at a time. Any remaining text that
is not a multiple of 8 bytes gets passed in the chaining vector as carryover text.
2. A call with keyword FIRST must have a text length greater than or equal to 16 in order to calculate an
intermediate MDC value. If the text length is greater than or equal to 16, the COL is calculated as text
length modulo 8, otherwise the COL equals the text length. Any carryover text bytes get passed in the
chaining vector as carryover text to the next segment call.
3. A call with keyword MIDDLE calculates an intermediate MDC value if the text bytes to process (COL
plus text length) are greater than or equal to 16. If COL plus text length is less than 16, the text bytes
are carried over to the next call in the chaining vector. MIDDLE calls process text in multiples of 8 (for
example, 16, 24, 32). As with FIRST, the remaining text bytes (NTL modulo 8) get passed in the
chaining vector as carryover text to the next segment call.
4. An MDC value is final when calculated by keywords ONLY or LAST.
Examples:
1. Assume a text length of 19 for FIRST, 6 for MIDDLE, and 10 for LAST.
TTL = 19 + 6 + 10 = 35 bytes.
When FIRST is called, 16 of the 19 text bytes will be processed to produce an intermediate MDC. The
remaining 19 - 16 = 3 text bytes will be placed in the chaining vector.
When MIDDLE is called, RTL = 19, COL = 19 - 16 = 3, and NTL = COL + text length = 3 + 6 = 9 bytes
to process.
After the MIDDLE call completes, RTL = 19 + 6 = 25 and COL = 25 - 16 = 9. Because 16 bytes are
not available to be processed, the 9 text bytes will be placed in the chaining vector as carryover text.
LAST will process COL + text length = 9 + 10 = 19 bytes. The NTL for the LAST call is 19 bytes. If the
TTL is not a multiple of 8, use of a PADMDC-2 or PADMDC-4 method is required.
2. Assume a text length of 19 for FIRST, 25 for MIDDLE, and 12 for LAST.
TTL = 19 + 25 + 12 = 56 bytes.
When FIRST is called, 16 of the 19 text bytes will be processed to produce an intermediate MDC. The
remaining 19 - 16 = 3 text bytes will be placed in the chaining vector.
When MIDDLE is called, RTL = 19, COL = 19 - 16 = 3, and NTL = COL + text length = 3 + 25 = 28
bytes to process.
After the MIDDLE call completes, RTL = 19 + 25 = 44, COL = 28 modulo 8 = 4, and 28 4 = 24 bytes
will be used to produce an intermediate MDC. The 4 text bytes will be placed in the chaining vector as
carryover text.
LAST will process COL + text length = 4 + 12 = 16 bytes. The NTL for the LAST call is 16 bytes.
These text bytes will be used to produce the final MDC value.

Pre-Release 3.30 problems: The following scenarios describe different situations where the
MDC_Generate (CSNBMDG) verb was found to produce incorrect MDC values. These scenarios apply to
releases prior to Release 3.30.
Scenario 1 (pre-Release 3.30)
Error type: Segmentation error, not padding related.
Keywords affected:
v Algorithm MDC-2, MDC-4, PADMDC-2, PADMDC-4
v Segmenting and key control MIDDLE
The MDC value is calculated incorrectly whenever:
v RTL is greater than or equal to 16 and
v At least one MIDDLE segment is processed that has COL plus text length less than 16
Under the above conditions, the very next MIDDLE or LAST call loses the intermediate MDC value that
was passed on input.
WARNING: The integrity of any data processed up to the time that the intermediate MDC value is lost
cannot be confirmed.
Example:
MDC-2, MDC-4, PADMDC-2, or PADMDC-4
FIRST text length = 19, MIDDLE text length = 6, LAST text length greater than or equal to 0, an
incorrect MDC value is calculated.
Corrective action:
None. The intermediate MDC value calculated when keyword FIRST was used to process the 16 bytes
of text is lost. The integrity of these first 16 bytes of data cannot be confirmed.
Error type: Padding error related to segmenting.
Keywords affected:
v Algorithm PADMDC-2, PADMDC-4
v Segmenting and key control LAST
v LAST text length is equal to 0 and
v TTL is greater than or equal to 16 and
v TTL modulo 8 is equal to 0
Under the above conditions, 16 bytes of padding are incorrectly added to the text instead of the
required 8 bytes of padding.
Example:
PADMDC-2 or PADMDC-4
FIRST text length = 16, LAST text length = 0, an incorrect MDC value is calculated.
Corrective action:
Prior to migrating to Release 3.30.05 or later, recalculate each MDC value in the same manner used to
calculate the existing MDC value. If the newly calculated MDC value matches the older MDC value,
data integrity is confirmed. After all MDC values have been confirmed, migrate to the latest release and
recalculate each MDC value. Replace the old MDC values with the new ones.
Error type: Padding error, not segmenting related.

Keywords affected:
v Segmenting and key control ONLY, LAST
Under the above conditions, no padding is added to the text as required. The incorrect MDC value is
identical to calling either MDC-2 or MDC-4.
Example:
ONLY text length is equal to 16, 24, 32, and so forth, an incorrect MDC value is calculated. The MDC
value is calculated without adding the required 8 bytes of pad characters.
Corrective action:
Keywords affected:
v Segmenting and key control FIRST, MIDDLE
v LAST is called with COL plus text length greater than zero and less than 8
Under the above conditions, the text is padded with 8 bytes more than is required.
Example:
FIRST text length = 16, LAST = 7, an incorrect MDC value is calculated. The MDC value is calculated
with 9 pad bytes instead of the required 1 pad byte.
Corrective action:
Error type: Segmenting error, not padding related.
Keywords affected:
v Segmenting and key control MIDDLE without FIRST
v FIRST is not called
v For the first MIDDLE call only, text length is less than 16

v The chaining vector is set to zero
v The MDC value on input is set to a keyed hash value not equal to the default key
Under the above conditions, the keyed hash value that the caller set in the MDC is ignored and the
MDC value is incorrectly calculated using the default key.
Example:
Chaining vector is set to hex zeros.
MDC value is set to a non-default key value (default key = X'52525252 52525252 25252525
25252525').
MIDDLE text length = 8, LAST text length = 16, an incorrect MDC value is calculated. The MDC value
is calculated with the default key and not with the key value of the MDC parameter.
Corrective action:
Release 3.30.04 only problems: The following scenarios describe different situations where the
MDC_Generate (CSNBMDG) verb was found to produce incorrect MDC values. These scenarios apply to
Release 3.30.04 only.
Scenario 1 (Release 3.30 only)
Error type: Segmentation error, not padding related.
Keywords affected:
v Segmenting and key control MIDDLE
v MIDDLE is called with COL plus text length less than 16 and
v MIDDLE is called again
Under the above conditions, the first MIDDLE call causes a subsequent MIDDLE call to lose the
intermediate MDC value passed to it on input.
WARNING: The integrity of any data processed up to the time that the intermediate MDC value is lost
cannot be confirmed.
Example:
FIRST text length = 19, MIDDLE text length = 6, subsequent MIDDLE and LAST text length greater
than or equal to 0, an incorrect MDC value is calculated. The intermediate MDC value calculated when
FIRST processed the 16 bytes of text is lost.
Corrective action:
None. The intermediate MDC value calculated when keyword FIRST was used to process the 16 bytes
of text is lost. The integrity of these first 16 bytes of data cannot be confirmed.
Keywords affected:

v LAST text length is equal to 0 and
Under the above conditions, 16 bytes of padding are added to the text instead of the required 8 bytes
of padding.
Example:
FIRST text length = 16, LAST text length = 0, an incorrect MDC value is calculated.
Corrective action:
Keywords affected:
v TTL is greater than zero and less than 8
Under the above conditions, the text is incorrectly padded with 8 pad bytes less than required.
Example:
LAST text length = 7, an incorrect MDC value is calculated. The MDC value is calculated with only one
pad byte instead of the required 9 pad bytes.
Corrective action:
recalculate each MDC value. Replace the old MDC values with the new ones

One_Way_Hash (CSNBOWH)
The One_Way_Hash verb calculates and returns a hash value from a text string using the MD5,
RIPEMD-160, SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512 hashing methods. Specify a keyword in
the rule_array variable to select the hash method.
Provide all of the data to be hashed in a single call to the verb or provide the data to be hashed using
multiple calls. The keywords that you supply in the rule_array determine your intention.
For the MD5 and RIPEMD-160 hash algorithms, the verb hashes the text strings using software in the host
computer. For all of the other hash algorithms, the verb hashes the text strings using the coprocessor
hardware.
Note: Hashing can also be performed using the MDC_Generate (CSNBMDG) verb for the MDC-2,
MDC-4, PADMDC-2, and PADMDC-4 algorithm modes.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v If FIRST or MIDDLE calls are made, the text size must be greater than zero and a multiple of the
algorithm block size: 64 bytes.
v This verb requires that text to be hashed be a multiple of eight bits aligned in bytes. Only data that is a
byte multiple can be hashed.
| v Hash methods SHA-224 and SHA-256 are not supported in releases before Release 3.30.
| v Hash methods SHA-384 and SHA-512 are not supported in releases before Release 4.0.
Format
CSNBOWH
text_length Input Integer
chaining_vector_length Input Integer 128
chaining_vector In/Output String chaining_vector_length bytes
hash_length In/Output Integer 64
hash In/Output String hash_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Hash method (one required)
MD5 Specifies the use of the MD5 method.
RPMD-160 Specifies the use of the RIPEMD-160 method.
SHA-1 Specifies the use of the SHA-1 method.
SHA-224 Specifies the use of the SHA-224 method. Release 3.30 or later.
Segmenting control (one, optional)
FIRST Specifies the first in a series of calls to compute the hash; intermediate results are
stored in the hash variable.
MIDDLE Specifies that this is not the first nor the last in a series of calls to compute the
hash; intermediate results are stored in the hash variable.
LAST Specifies the last in a series of calls to compute the hash; intermediate results are
retrieved from the hash variable.
ONLY Specifies that this is the only call made to compute the hash. This is the default.
text_length
the text variable. The maximum length on IBM i systems is 64 MB 64 bytes, and on the other
systems is 32 MB 64 bytes.
Restriction: If FIRST or MIDDLE calls are made, the text size must be a multiple of the algorithm
block-size.
text
The text parameter is a pointer to a string variable containing the data on which the hash value is
computed.
chaining_vector_length
The chaining_vector_length parameter is a pointer to an integer variable containing the number of
bytes of data in the chaining_vector variable. The value must be 128.
chaining_vector
The chaining_vector parameter is a pointer to a string variable containing a work area used by this
verb. Application programs must not alter the contents of this variable between related FIRST,
MIDDLE, and LAST calls.

hash_length
in the hash variable. This table shows how many bytes of hash output is returned by each hash
method:
Hash method keyword Hash output (bytes)

MD5 16
RPMD-160 20
SHA-1 20
SHA-224 28
SHA-256 32
SHA-384 48
SHA-512 64
Beginning with Release 4.0, on output, this variable contains the number of bytes of data returned by
the verb in the hash variable.
hash
The hash parameter is a pointer to a string variable containing the hash value returned by the verb.
With use of the FIRST or MIDDLE keywords, the hash variable receives intermediate results.
Required commands
The One_Way_Hash verb requires the following commands to be enabled in the active role.

SHA-1 X'0107' One-Way-Hash, SHA-1
| SHA-224 (Rel. 3.30 or later) X'0135' One-Way-Hash, SHA-224

|
Chapter 5. AES, DES, and HMAC symmetric-key management
| This section describes verbs used to perform basic symmetric-key management of CCA AES, DES, and
| HMAC functions. Table 16 lists the verbs covered in this section. The following topics are presented:
| v AES, DES, and HMAC key-management
| v Control vectors, key types, key-usage, and key-management restrictions
v Key tokens, key labels, and key identifiers
v Key-processing and key-storage verbs
v Improved remote-key distribution
v Security precautions
Notes:
1. AES support is not available in releases before Release 3.30.
2. Variable-length symmetric key tokens are not supported in releases before Release 4.1.
| 3. TR-31 keys, which can contain a DES key, are not supported in releases before Release 4.2.
| The following table lists the basic AES, DES, and HMAC key-management verbs. See AES, DES, and
| HMAC key-management verbs on page 197 for a detailed description of the verbs. For information on
| TR-31 keys and the verbs used to perform basic symmetric-key management of the TR-31 DES functions,
| see Chapter 9, TR-31 symmetric-key management, on page 499, which is an extension of this chapter.
Table 16. Basic AES and DES key-management verbs
Service
Clear_Key_Import 198 Enciphers a clear DES key under the DES master-key, and CSNBCKI E
updates or creates an internal fixed-length DES key-token for
a DATA key.
Control_Vector_Generate 200 Builds a DES control vector from keywords. CSNBCVG S
Control_Vector_Translate 203 Changes the control vector associated with a key in an CSNBCVT E
external fixed-length DES key-token.
Cryptographic_Variable_Encipher 205 Encrypts modest quantities of data using a unique key-class, CSNBCVE E
CVARENC. The service is used to prepare the mask-array
variables for the Control_Vector_Translate verb.
Data_Key_Export 207 Exports a DES DATA key and creates an external fixed-length CSNBDKX E
DES key-token that contains a null control vector.
Data_Key_Import 209 Imports a DES DATA key from an enciphered key or an CSNBDKM E
external fixed-length DES key-token into an internal
fixed-length DES key-token. An internal fixed-length DES
DATA key-token is either created or updated.
Diversified_Key_Generate 211 Generates a DES key, based on supplied information and a CSNBDKG E
key-generating key contained in an internal fixed-length DES
key-token. The generated key is stored into a suitable internal
fixed-length DES key-token.
| EC_Diffie-Hellman (Rel. 4.2 or 217 Creates a shared symmetric key with a pair of ECC (Elliptic CSNDEDH E
| later) Curve Cryptography) keys using the ECDH (Elliptic Curve
| Diffie-Hellman) protocol and the ANS X9.63 protocol static
| unified model key-agreement scheme.
Key_Encryption_Translate 224 Translates an encrypted fixed-length DES DATA key with an CSNBKET E
all-zero control vector from ECB mode to CBC mode, or from
CBC mode to ECB mode.
Key_Export 227 Exports a DES key and creates an external fixed-length DES CSNBKEX E
key-token.
137
Table 16. Basic AES and DES key-management verbs (continued)
Service
Key_Generate 229 Generates a random AES or DES key or a random DES key CSNBKGN E
pair, enciphers the key, and updates or creates one or two
internal or external fixed-length DES key tokens.
| Key_Generate2 (Rel. 4.1 or later) 239 Generates a random AES or HMAC key, enciphers the key, CSNBKGN2 E
| and updates or creates one or two external or internal
| variable-length symmetric key tokens.
Key_Import 245 Imports a DES key from an enciphered key or an external CSNBKIM E
fixed-length DES key-token into an internal fixed-length DES
key-token. The internal fixed-length DES key-token is either
created or updated.
Key_Part_Import 247 Accumulates one or more parts of a DES key from CSNBKPI E
clear-key-part data and any previously accumulated key parts
recovered from an internal fixed-length DES key-token. The
user-provided and recovered clear key parts are
exclusive-ORed together and then encrypted using an internal
fixed-length DES key-token, either as a partial key or as the
final key.
| Key_Part_Import2 (Rel. 4.1 or 251 Accumulates one or more parts of an AES or HMAC key from CSNBKPI2 E
| later) clear-key-part data and any previously accumulated key parts
| recovered from an internal variable-length symmetric
| key-token. The user-provided and recovered clear key parts
| are exclusive-ORed together and then encrypted using an
| internal variable-length symmetric key-token, either as a partial
| or as the final key.
Key_Test 256 Generates or verifies the value of either an AES, APKA, DES, CSNBKYT E
or PKA master key register, a clear or encrypted AES key or
key part, or a clear or encrypted DES key or key part. A clear
AES key or key part can optionally be in an internal
fixed-length AES key-token. A clear DES key or key part
cannot be in a key token.
| Key_Test2 (Rel. 4.1 or later) 261 Generates or verifies the value of a clear or encrypted key or CSNBKYT2 E
| key part contained in an external or internal variable-length
| symmetric key-token, or a DES key or key part wrapped in an
| external TR-31 key block.
Key_Test_Extended 265 Same as Key_Test, except that in addition, CSNBKYTX E
Key_Test_Extended operates on an external DES key or key
part, and supports only clear keys that are contained in an
internal fixed-length AES key-token.
Key_Token_Build 270 Assembles an internal fixed-length AES key-token or an CSNBKTB S
external or internal fixed-length DES key-token from the
information provided.
Key_Token_Build2 (Rel. 4.1 or 275 Assembles an external or internal variable-length symmetric CSNBKTB2 S
later) key-token from the information provided.
Key_Token_Change 279 Reenciphers or reformats the key contained in an internal CSNBKTC E
fixed-length AES or DES key-token. Reencipher first recovers
the key from under the old master-key, then enciphers it under
the current master-key. Reformat is used to change the
key-wrapping method either to legacy ECB (WRAP-ECB) or
enhanced (WRAP-ENH). It recovers the key from under the
old or current master-key as needed, then reenciphers the key
using the same master key and specified key-wrapping
method.
Key_Token_Change2 (Rel. 4.1 or 281 Reenciphers the AES or HMAC key in an internal fixed or CSNBKTC2 E
later) variable-length symmetric key-token from encipherment under
the old AES symmetric master-key to the current AES
symmetric master-key.
Key_Token_Parse 283 Parses an external or internal fixed-length DES key-token and CSNBKTP S
provides the parsed information as individual variables.

Service
| Key_Token_Parse2 (Rel. 4.2 or 286 Parses an external or internal variable-length AES or HMAC CSNBKTP2 S
| later) key-token, and provides the parsed information as individual
| variables.
Key_Translate 294 Translates a DES key by deciphering the key of an external CSNBKTR E
fixed-length DES key-token using one key-encrypting key, and
then reenciphering the key using another key-encrypting key.
The reenciphered key is stored in a different external
Key_Translate2 (Rel. 4.1 or later) 296 Translates or reformats a key contained in an external CSNBKTR2 E
fixed-length or variable-length symmetric key-token. Translate
first recovers the key using one key-encrypting key, then
reenciphers the key using another key-encrypting key.
Reformat first recovers the key using a key-encrypting key,
then reenciphers the key either to the legacy ECB
(WRAP-ECB) or to the enhanced (WRAP-ENH) key-wrapping
| method using the original key-encrypting key. Reformat can
| covert a fixed-length AES key token to variable-length, and the
| other way around. The result is always stored in a different
external fixed-length or variable-length symmetric key-token.
Multiple_Clear_Key_Import 301 Imports a cleartext key into an internal fixed-length AES or CSNBCKM E
DES DATA key-token. AES keys can be 16, 24, or 32 bytes in
length. DES keys can be single or double in length.
PKA_Decrypt 305 Uses an RSA private-key to decrypt data formatted in an RSA CSNDPKD E
PKCS #1 RSAES-PKCS1-v1_5 structure and return the
unformatted data in the clear.
PKA_Encrypt 307 Formats input data into an RSA PKCS #1 CSNDPKE E
RSAES-PKCS1-v1_5 structure, then uses an RSA public-key
to encrypt the formatted data before it is returned.
Using the ZERO-PAD option, you can encipher information

including a hash value to validate digital signatures such as
ISO/IEC 9796-2.
Prohibit_Export 309 Modifies an internal fixed-length DES key-token so that the key CSNBPEX E
can no longer be exported.
Prohibit_Export_Extended 311 Modifies an external fixed-length DES key-token so that the CSNBPEXX E
key can no longer be exported, typically after it has already
been exported.
Random_Number_Generate 313 Generates a random 8-byte number with the specified parity. CSNBRNG E
Random_Number_Generate_Long 315 Generates a random number of user-specified length and CSNBRNGL E
parity.
Remote_Key_Export 317 Uses an internal trusted block to generate or export DES keys CSNDRKX E
in fixed-length DES key tokens for local use and for distribution
to an ATM or other remote device.
| Restrict_Key_Attribute (Rel. 4.1 or 328 Modifies an internal variable-length symmetric key-token so CSNBRKA E
| later) that the key can no longer be exported, or modifies the export
| authority of a fixed-length DES key-token, including the export
| control bit for TR-31.
| Symmetric_Key_Export 333 Exports a symmetric key, contained in a fixed-length AES or CSNDSYX E
| DES key-token or in a variable-length symmetric key-token.
| The key being exported can be returned either formatted and
| encrypted under an RSA public-key, or encrypted under an
| AES EXPORTER KEK.
Chapter 5. AES, DES, and HMAC symmetric-key management 139

Service
Symmetric_Key_Generate 339 Generates a new AES or DES key. For AES, returns one copy CSNDSYG E
in an internal fixed-length AES key-token enciphered under the
AES master-key, and another copy enciphered under an RSA
public-key. For DES, returns one copy in an internal
fixed-length DES key-token enciphered under the DES
master-key or in an external fixed-length DES key-token
enciphered under a DES key-encrypting key and another copy
enciphered under an RSA public-key.
| Symmetric_Key_Import 345 Imports a symmetric key that has been previously formatted CSNDSYI E
| and enciphered under an RSA public-key by the
| Symmetric_Key_Export verb. The opaque formatted and
| RSA-enciphered key is deciphered using the associated RSA
| private-key. The recovered key is reenciphered using the AES
| or DES master-key. The reenciphered key is returned in an
| internal fixed-length AES or DES DATA key-token, or an
| internal variable-length symmetric key-token.
| Symmetric_Key_Import2 (Rel. 4.1 350 Imports a symmetric key that has been previously formatted CSNDSYI2 E
| or later) and enciphered under an RSA public-key, or under an AES
| EXPORTER KEK, by the Symmetric_Key_Export verb. The
| formatted and enciphered key is contained in an external
| variable-length symmetric key-token. It is deciphered using the
| associated RSA private-key or the associated AES IMPORTER
| KEK. The recovered key is reenciphered using the AES
| master-key. The reenciphered key is returned in an internal
| variable-length symmetric key-token.
Trusted_Block_Create 353 Creates and activates an external trusted block under dual CSNDTBC E
control.
| AES, DES, and HMAC key-management

| The AES algorithm operates on 128 data-bits at a time, and uses a key size of 128, 192, or 256 bits.
| There are no parity bits.
The DES algorithm operates on 64 data-bits at a time: eight bytes of 8-bit-per-byte data. The results
produced by the algorithm are controlled by the value of a key that you supply. Each byte of the key
contains 7 bits of key information plus a parity bit (the low-order bit in the byte). The parity bit is set so that
there is an odd number of one bits for each key byte. The parity bits do not participate in the DES
algorithm.
| The HMAC algorithm operates on 64 data-bits at a time, and uses a key size of 80 - 2048 bits. There are
| no parity bits.
| The AES, DES, and HMAC algorithms are not secret. However, by using a secret key, the AES and DES
| algorithms can produce ciphertext that is impossible, for all practical purposes, to decrypt without knowing
| the secret key. The HMAC algorithm can produce a keyed hash MAC that can be used to authenticate
| both the source of a message and its integrity, provided that the key used is kept secret. The requirement
| to keep a key secret, and to have the key available at specific places and times, produces a set of
| activities known collectively as key management.
| Because the secrecy and reliability of AES-based, DES-based, and HMAC-based cryptography is strongly
related to the secrecy, control, and use of symmetric keys, the following aspects of key management are
important:
Securing a cryptographic facility or process
The hardware provides a secure, tamper-resistant environment for performing cryptographic

operations and for storing cryptographic keys in the clear. The hardware provides cryptographic
functions as a set of commands that are selectively enabled using different roles. To activate a
profile and its role to enable different hardware capabilities, users, or programs must supply
identification and a password for verification. Using these capabilities, you can control the use of
sensitive key-management capabilities.
Separating key types to restrict the use of each key
A user or a program should be restricted to performing only the processes that are required to
accomplish a specific task. Therefore, a key should be limited to a set of functions in which it can
be used. The cryptographic subsystem uses a system of CCA control vectors to separate the DES
cryptographic keys into a set of key types and restrict the use of a key. A control vector is a logical
extension of a key variant, which is a method of key separation that some other cryptographic
systems use. The subsystem enforces the use of a particular key type in each part of a
cryptographic command. To control the use of a DES key, the control vector is combined with the
key that is used to encipher the control vector's associated key. For example, a DES key that is
designated a key-encrypting key cannot be employed in the Decipher verb, thereby preventing the
use of a key-encrypting key to obtain a cleartext key.
Securely installing and verifying keys
Capabilities are provided to install keys, either in whole or in parts, and to determine the integrity
of the key or the key part to ensure the accurate and secure entry of key information. The
hardware commands and profiles allow you to enforce a split-knowledge, dual-control security
policy in the installation of keys from clear information.
Generating keys
| The system can generate random clear and enciphered keys. The key-generation services create
| a key type of DATA for fixed-length AES keys (Release 3.30 or later), CIPHER, IMPORTER, and
| EXPORTER key types for variable-length AES keys (Release 4.2 or later), a MAC key type for
| HMAC keys (Release 4.1 or later), and an extensive set of DES key types for use in both CCA
| subsystems and other AES-based, DES-based, and HMAC-based systems. Keys can be
| generated for local use and for distribution to remote nodes.
Securely distributing keys manually and electronically
| The system provides for unidirectional key-distribution channels and AES and HMAC keys in a
| variable-length key-token, and fixed-length DES key-translation services.
Your application programs should provide procedures to perform the following key-management activities:
v Generating and periodically replacing keys. A key should be used for a very limited period of time. This
might minimize the resulting damage should an adversary determine the value of a key.
v Archiving keys.
v Destroying keys and media used to distribute keys.
v Auditing the key generation, distribution, installation, archiving, and destruction processes.
v Reacting to unusual occurrences in the key-management process.
v Creating key-management controls.
Before an AES key or an HMAC key is removed from a CCA cryptographic facility for storage in AES
| key-storage or application storage, the key can be enciphered under a 256-bit AES master-key, or it can
| be formatted and enciphered under an RSA public-key.
Before a DES key is removed from a CCA cryptographic facility for storage in DES key-storage or in
application storage, the key is multiply-enciphered under a master key or another key-encrypting key. The
DES master key is a triple-length key composed of three 56-bit DES keys. The first and the second parts
of a DES master key (each 56-bit component) are required to be unique. For compatibility, the third part
can be the same as the first part, thus creating an effective double-length DES master-key.

Key-encrypting keys (KEKs) are sometimes designated transport keys. A DES KEK is a double-length key
composed of two halves, each half being a 56-bit DES key. The halves of a DES KEK can be the same
value, in which case the KEK operates as though it were a single-length, 56-bit DES key.
| An AES key-encrypting key was introduced to CCA beginning with Release 4.2. AES KEKs are contained
| in a variable-length symmetric key-token. They can have a key length of 128, 192, or 256 bits.
An internal fixed-length or variable-length symmetric key-token can have no key, a partial key, or a
complete key. An exception to this is a fixed-length AES key-token, which cannot have a partial key. A
complete key that is enciphered under the master key is an operational key. The key is operational
because a cryptographic facility can use the master key to decipher it to obtain the original key-value. A
key that is enciphered under a KEK (other than the master key) is called an external key. Two types of
external symmetric keys are used at a cryptographic node:
| v An importable key (IM) is enciphered under an operational key-encrypting key (KEK) whose control
| vector or key usage attributes provide key-importing authority.
| v An exportable key (EX) is enciphered under an operational KEK whose control vector or key usage
| attributes provide key-exporting authority.
Triple-DES key wrapping

The Triple Data Encryption Algorithm (TDEA), commonly referred to as Triple-DES or TDES, is a block
cipher specified by the National Institute of Standards and Technology (NIST). As computing power has
increased and code-breaking skills have improved, the traditional ECB mode of wrapping Triple-DES keys
is no longer strong enough for all applications. The issue is that ECB mode encrypts each eight-byte
portion of the Triple-DES key separately, and researchers have documented attacks that are possible if the
attacker can manipulate these eight-byte encrypted values individually. As a result, recent versions of
standards such as ANS X9.24-1 have added the requirement for key bundling, in which the entire key is
cryptographically bound into a single protected data object, where no part can be manipulated separately
from the other parts.
To thwart possible ECB-mode attacks, CCA has added support to more securely wrap Triple-DES keys.
The enhanced Triple-DES key-wrapping method complies with current cryptographic standards. This more
secure key-wrapping method is called the enhanced or WRAP-ENH method. The original method, which
uses Triple-DES with ECB mode, is called the legacy or WRAP-ECB method. Support for the enhanced
method is available beginning with Release 4.1. Due to the nature of the key bundling requirement,
single-length DES keys are not subject to the same security exposure as Triple-DES keys. For this reason,
the enhanced method will not be used to wrap single-length DES keys.
The added support made available for wrapping Triple-DES keys using the enhanced method attempts to
account for various key-exchange topology and exchange partners coping with importing and exporting
both legacy-wrapped keys and enhanced-wrapped keys. It also accounts for security of the system as well
as operational needs, including various enterprises requiring any combination of systems that have their
Triple-DES keys wrapped in only the legacy method, only the enhanced method, or both.
Here is a comprehensive list of the verbs that wrap DES keys:

v Clear_Key_Import (CSNBCKI)
v Control_Vector_Translate (CSNBCVT)
v Data_Key_Export (CSNBDKX)
v Data_Key_Import (CSNBDKM)
v Diversified_Key_Generate (CSNBDKG)
| v EC_Diffie-Hellman (CSNDEDH)
v Key_Encryption_Translate (CSNBDKM)
v Key_Export (CSNBKEX)
| v Key_Export_to_TR31 (CSNBT31X)

v Key_Generate (CSNBKGN)
v Key_Import (CSNBKIM)
v Key_Part_Import (CSNBKPI)
v Key_Token_Change (CSNBKTC)
v Key_Translate (CSNBKTR)
v Key_Translate2 (CSNBKTR2)
v Multiple_Clear_Key_Import (CSNBCKM)
v Prohibit_Export (CSNBPEX)
v Prohibit_Export_Extended (CSNBPEXX)
v Symmetric_Key_Generate (CSNDSYG)
v Symmetric_Key_Import (CSNDSYI)
| v TR31_Key_Import (CSNBT31I)
The following sections describe how the legacy and enhanced Triple-DES key wrapping methods work,
and how to use each verb to control which key-wrapping method is used.
Default key-wrapping method

Beginning with Release 4.1, a coprocessor contains a configuration setting that specifies the default
key-wrapping method. In the absence of any other controls, this default determines which key-wrapping
method is used to wrap a Triple-DES key for a verb that does not have a rule-array keyword. This default
is also used when a verb that accepts key-wrapping method keywords specifies to wrap the DES key
using the configuration setting for the default key-wrapping method, either explicitly (rule-array keyword
USECONFG) or by default.
Refer to Figure 4 on page 144. Internal and external DES key tokens each have their own coprocessor
configuration setting for the default key-wrapping method. When a coprocessor is initialized, CCA sets to
legacy (WRAP-ECB) the default key-wrapping methods for internal and external DES keys. Specify the
rule-array keyword CHGKEYWR to the Cryptographic_Facility_Control (CSUACFC) verb when a change of
default key-wrapping method is required. The verb_data variable for the CHGKEYWR operation
determines what setting is changed. and has four valid values as shown in Figure 4 on page 144. Each of
the four values of the verb_data variable requires its own access-control point to be enabled in the active
role.
Use the Cryptographic_Facility_Query (CSUACFQ) verb with rule-array keyword WRAPMTHD to obtain
the default key-wrapping configuration options for both internal and external DES keys.

Coprocessor initialization

Coprocessor configuration

Internal DES default External DES default
key-wrapping method key-wrapping method

Legacy (WRAP-ECB) Legacy (WRAP-ECB)

CSUACFC CHGKEYWR CSUACFC CHGKEYWR CSUACFC CHGKEYWR CSUACFC CHGKEYWR
verb_data verb_data verb_data verb_data
X00000000 X00000100 X00010100 X00010000

Wrap Internal Wrap Internal Wrap External Wrap External
Key with Key with Key with Key with
Legacy Method Enhanced Method Enhanced Method Legacy Method
(offset X013A) (offset X0139) (offset X013B) (offset X013C

Enhanced (WRAP-ENH) Enhanced (WRAP-ENH)
Figure 4. Default key-wrapping method configuration
Key-wrapping enhancements to DES key tokens

Beginning with Release 4.1, fixed-length DES key tokens have been enhanced to support both legacy and
enhanced key-wrapping methods. This modification caused two noticeable differences in DES internal and
external key tokens. One difference is a new flag byte 2, and the other is a newly defined control vector bit
56.
DES flag byte 2: DES key tokens now have a flag byte 2 defined. This flag byte is used to support the
addition of a second key-wrapping method. It serves to distinguish between a key that has been wrapped
by the legacy method and one that has been wrapped by the enhanced method. See the structures
defined for DES internal and external key-tokens in Fixed-length DES key tokens on page 580. Also see
Table 92 on page 583 for a layout of flag byte 2. Notice that the flag byte has three integral bits defined
that differentiate the key-wrapping method for a given DES encrypted key. The bit pattern B'000x xxxx'
indicates that the key is wrapped using the legacy (WRAP-ECB) method. This value is defined so as to
not impact legacy-wrapped DES key tokens that had this byte previously reserved. Bit pattern B'001x xxxx'
indicates that the encrypted key is wrapped using the enhanced (WRAP-ENH) method.
Note: Single-length DES keys are always wrapped using the legacy method, even if flag byte 2 indicates
that it is wrapped by the enhanced method. Such a condition can occur whenever a call is made to
wrap a single-length DES key with the enhanced method. Rather than return an error, the verb
simply wraps the single-length key using the legacy method, and then marks the token as if it were
wrapped using the enhanced method.
Control vector bit 56: Control vector bit 56 has been defined to provide added control over a key that
has been wrapped using the more secure enhanced method. This bit has the designation ENH-ONLY for
"enhanced-only." See Figure 37 on page 658. A control vector with its ENH-ONLY bit set to B'1' restricts
the key from being wrapped by the weaker legacy method, after having been wrapped by the enhanced

method. The only exception to this rule is when a single-length key, which is always wrapped using the
legacy method, is in a fixed-length DES key-token with the ENH-ONLY bit on.
Verbs that wrap DES keys and have a rule-array parameter can accept a translation control keyword that
causes control vector bit 56 to be turned on in any wrapped DES key tokens. The translation control
keyword and its meaning are shown in Table 17.
Table 17. DES translation control rule-array keyword
Keyword Definition
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the
default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary
zeros. Release 4.1 or later.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy method once it has been
wrapped with the enhanced method. Set bit 56 (ENH-ONLY) of the control vector to B'1'.
Verbs that wrap DES keys and do not accept rule-array keywords must provide a skeleton key-token that
has the desired translation-control value already set in control vector bit 56. To build a skeleton key-token
that has the ENH-ONLY bit on, you can use the Key_Token_Build (CSNBKTB) verb with translation-control
keyword ENH-ONLY.
Key-wrapping method keywords

Rule-array keywords have been added to a select group of verbs that wrap DES keys. These keywords
are shown in Table 18.
Table 18. DES key-wrapping method rule-array keywords
Keyword Definition
Key-wrapping method (one, optional). Release 4.1 or later.
USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. This is
the default.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method.
WRAP-ENH Specifies to wrap the key using the enhanced wrapping method. Valid only for DES keys.
Notes:
1. When no key-wrapping method keyword is used, wrapping of the DES key is based on the
coprocessor configuration setting (USECONFG).
2. To use WRAP-ECB when the current default key-wrapping method configuration setting is
WRAP-ENH, the active role must have the verb-specific Allow Configuration Override with Keyword
command enabled.
3. To use WRAP-ENH when the current default key-wrapping method configuration setting is
WRAP-ECB, the active role must have the verb-specific Allow Configuration Override with Keyword
command enabled.
Key-wrapping method based on rule array

Most verbs that wrap DES keys and have a rule-array parameter can accept the key-wrapping method
keywords shown in Table 18. These verbs are:
v Diversified_Key_Generate (CSNBDKG)
| v EC_Diffie-Hellman (CSNDEDH)
v Key_Part_Import (CSNBKPI)
v Key_Token_Change (CSNBKTC)
v Key_Translate2 (CSNBKTR2)
v Multiple_Clear_Key_Import (CSNBCKM)

v Symmetric_Key_Generate (CSNDSYG)
v Symmetric_Key_Import (CSNDSYI)
| v TR31_Key_Import (CSNBT31I)
See Table 19 on page 147. These verbs always use the contents of their rule array to determine the
method of key wrapping. An exception is the Control_Vector_Translate (CSNBCVT) verb, which has a
rule-array parameter but does not accept key-wrapping method keywords. This verb takes its key-wrapping
method from flag byte 2 of the target key-token.
Key-wrapping method based on target key-token

Several verbs that import keys into a DES key-token do not have a rule array, so they base their
key-wrapping method on the contents of the target key-token. These verbs are:
v Clear_Key_Import (CSNBCKI)
v Data_Key_Import (CSNBDKM)
v Key_Import (CSNBKIM)
See Table 19 on page 147. If the target key-token is null, these verbs wrap the target key based on the
configuration default DES key-wrapping method. Otherwise, the target key is wrapped with the method
from flag byte 2 of the target key-token. You can use the Key_Token_Build (CSNBKTB) verb with
key-wrapping method keyword WRAP-ECB or WRAP-ENH to build such a token.
Another verb that bases its key-wrapping method on the contents of the target key-token is the
Control_Vector_Translate (CSNBCVT) verb. This verb has a rule array parameter, but does not support
key-wrapping method keywords. Instead, it always wraps the target key based on the method assigned in
flag byte 2 of the target key-token.
Key-wrapping method based on source key-token

Several verbs that export keys into a DES key-token do not have a rule array, so they base their
key-wrapping method on the contents of the source key-token. These verbs are:
v Data_Key_Export (CSNBDKX)
v Key_Export (CSNBKEX)
v Key_Translate (CSNBKTR)
v Prohibit_Export (CSNBPEX)
v Prohibit_Export_Extended (CSNBPEXX)
See Table 19 on page 147.
Key-wrapping method based on key-type parameter

One verb, the Key_Generate (CSNBKGN) verb, does not have a rule array but does have a key-type
keyword parameter. If the key-type variable for the target key-token is not TOKEN, the verb uses the
configuration DES default key-wrapping method. Otherwise, the target key is wrapped with the method set
in flag byte 2 of the target key-token. See Table 19 on page 147.
Key-wrapping method of legacy only

There is one isolated verb that has not been modified to support enhanced key-wrapping. That verb is the
Key_Encryption_Translate (CSNBDKM) verb. It will continue to wrap its target key using the legacy
method. See Table 19 on page 147.
Summary of key-wrapping methods

Verbs that wrap DES keys rely on several different selection criteria to decide whether to wrap a DES key
with the legacy or the enhanced method. For verbs that have a rule-array parameter and can accept a
key-wrapping-method keyword, the method is based on the contents of the rule array. For the other verbs,
the method is based on the target key-token, source key-token, or a key type parameter. The

Key_Encryption_Translate (CSNBKET) verb is one exception to these criteria because it does not support
the enhanced key-wrapping method. See Table 19 for a summary of which verbs use what criteria.
Table 19. Summary of verbs and DES key-wrapping method selection criteria
DES key-wrapping-method selection criteria
Source
Rule array Target key-token key-token Key-type parameter
Key-wrapping If target If target Always Always If variable is If variable
Verb method is key-token is key-token from flag from flag not TOKEN, is TOKEN,
USECONFG, null, use is not null, byte 2 of byte 2 of from from flag
WRAP-ECB, configuration use flag target source configuration byte 2 of
or WRAP-ENH DES default byte 2 of key-token key-token DES default target
target key-token
key-token
CSNBDKG X
CSNBKPI X
CSNBKTC X
CSNBCKM X
CSNDSYG X
CSNDSYI X
CSNBKTR2 X
| CSNBT31I X
| CSNDEDH X
CSNBCKI X X
CSNBDKM X X
CSNBKIM X X
CSNBDKX X
CSNBKEX X
CSNBKTR X
CSNBPEX X
CSNBPEXX X
CSNBCVT Not supported X
CSNBKGN X X
Note: The Key_Encryption_Translate (CSNBKET) verb does not support the enhanced key-wrapping method. It can
wrap keys using only the legacy method.
| Control vectors, key types, key-usage, and key-management

| restrictions
The CCA cryptographic commands form a complete, consistent, secure command set that performs within
tamper-resistant hardware. The cryptographic commands use a set of distinct DES key types that provide
a secure cryptographic system that blocks many attacks that can be directed against it.
Note: Fixed-length AES keys are all DATA keys, and are not designed for specific purposes. If a
| fixed-length AES key has a control vector present, the control vector must be binary zeros.

CCA implementations use a control vector to separate fixed-length DES keys into distinct key types and to
further restrict the use of a key. A control vector is a non-secret value that is carried in the clear in the
DES key-token along with the encrypted key that it specifies.
| A control vector is cryptographically associated with a fixed-length DES key by being exclusive-ORed with
a DES master key or other DES key-encrypting key to form a key that is used to multiply-encipher or
multiply-decipher the DES key being associated with the control vector. This permanently binds the type
and use of the key to the key. Any change to the original control vector would result in later recovering an
altered key-value. If the control vector used to decipher a key is different from the control vector that was
used to encipher the same key, the correct clear key cannot be recovered. The key-encipherment
processes are described in detail at Understanding DES and RSA key encryption and decryption
processes on page 671.
After a DES key is multiply-enciphered, the originator of the key can ensure that the intended use of the
key is preserved by giving the key-encrypting key only to a system that implements the CCA control-vector
design and that is managed by an audited organization.
PIN keys and DES key-encrypting keys in CCA are double-length DES keys. A double-length DES key
consists of two (single-length) 56-bit DES keys that are used together as one key. The first half (left half)
of a double-length key, and all of a single-length key, are multiply-enciphered using the exclusive-OR of
the encrypting key and the control vector. The second half (right half) of a double-length key is
multiply-enciphered using the exclusive-OR of the encrypting key and a modification of the control vector;
the modification consists of the reversal of control vector bits 41 and 42.
Appendix C, CCA control-vector definitions and key encryption provides detailed information about the
construction of a control-vector value and the process for encrypting a CCA DES-key.
Checking a DES control vector before processing a cryptographic

command
Before a CCA cryptographic facility processes a command that uses a multiply-enciphered DES key, the
facilitys logic checks the control vector associated with the key. The control vector must indicate a valid
key type for the requested command, and any control-vector restriction (key-usage) bits must be set
appropriately for the command. If the command permits use of the control vector, the cryptographic facility
multiply-deciphers the key and uses the key to process the command. (Alteration of the control-vector
value to permit use of the key in the command would result in recovery of a different, unpredictable key
value.)
Figure 5 on page 149 shows the flow of cryptographic command processing in a cryptographic facility.

At the CCA API...
Fixed-length
Verb call DES key-token Data

Cryptographic Control Enciphered Data
command vector key

Tamper
resistant Control
cryptographic
vector
facility checking

Master key
Exclusive
(or KEK) OR

Multiply
decipher

Clear key

Process

Result
Figure 5. Flow of cryptographic command processing in a cryptographic facility
| AES, DES, and HMAC key types

The CCA implementation in this product defines the AES key type as shown in Table 20, the HMAC key
type as shown in Table 21 on page 150, and DES key types as shown in Table 22 on page 150. The key
type in an AES control vector is always DATA. The key type in a DES control vector determines the use of
the DES key, which verbs can use the key, and whether the cryptographic facility processes a key as a
| symmetric or asymmetric DES key. HMAC keys (Release 4.1 or later), and AES keys in a variable-length
| symmetric key-token (Release 4.2 or later) do not have a control vector. Instead, they have key usage
| fields and key management fields in an associated data section that is cryptographically bound to the
| encrypted key material.
| Table 20. AES key types and verb usage (Release 3.30 or later)
| AES key type Usable with verbs
| Fixed-length AES key-token, version X'04' (Rel. 3.30 or later)
| DATA Symmetric_Algorithm_Decipher, Symmetric_Algorithm_Encipher
| Variable-length AES key-token, version X'05' (Rel. 4.2 or later)
| Cipher class (data operation keys)
| CIPHER Symmetric_Algorithm_Decipher, Symmetric_Algorithm_Encipher
| Key-encrypting key class
| EXPORTER Key_Generate2, Key_Translate2, PKA_Key_Generate, Symmetric_Key_Export
| IMPORTER Key_Generate2, PKA_Key_Generate, Key_Test2, Restrict_Key_Attribute,
| Symmetric_Key_Import2, Key_Translate2
|

Table 21. HMAC key types and verb usage (Release 4.1 or later)
HMAC key type Usable with verbs
MAC class (data operation keys). This key is used to generate and verify a keyed hash message authentication code
(HMAC).
MAC HMAC_Generate, HMAC_Verify
Table 22. DES key types and verb usage

DES key type Usable with verbs
Cipher class (data operation keys)
These keys are used to cipher text. In operational form and in external form, these keys are associated with a control
vector.
CIPHER Encipher, Decipher
ENCIPHER Encipher
DECIPHER Decipher
MAC class (data operation keys)
These keys are used to generate and verify a message authentication code (MAC). In operational form and in
external form, these keys are associated with a control vector.
MAC CVV_Generate, CVV_Verify, MAC_Generate, MAC_Verify,
Transaction_Validation
MACVER CVV_Verify, MAC_Verify, Transaction_Validation
DATA class (data operation keys)
These keys are used to cipher text and to produce and verify message authentication codes. In operational form,
these keys are always associated with a control vector. In external form, the DATA key-type keys are not usually
associated with a control vector.
DATA CVV_Generate, CVV_Verify, Encipher, Decipher, MAC_Generate, MAC_Verify
DATAC Encipher, Decipher
DATAM MAC_Generate, MAC_Verify
DATAMV MAC_Verify
Secure-messaging class (data operation keys)
These keys are used to encrypt keys or PINs. They are double-length keys. In operational form and in external form,
these keys are associated with a control vector.
SECMSG Diversified_Key_Generate, Secure_Messaging_for_Keys,
Secure_Messaging_for_PINs
Key-encrypting key class
These keys are used to cipher other keys. They are double-length keys. In operational form and in external form,
these keys are associated with a control vector.
EXPORTER Control_Vector_Translate, Data_Key_Export, Key_Encryption_Translate,
Key_Export, Key_Generate, Key_Translate, PKA_Key_Generate,
Remote_Key_Export, Secure_Messaging_for_Keys, Symmetric_Key_Generate
IMPORTER Control_Vector_Translate, Data_Key_Import, Key_Encryption_Translate,
Key_Generate, Key_Import, Key_Translate, PKA_Key_Generate,
PKA_Key_Import, Remote_Key_Export, Secure_Messaging_for_Keys,
Symmetric_Key_Generate
IMP-PKA PKA_Key_Import, Remote_Key_Export, Trusted_Block_Create
IKEYXLAT, OKEYXLAT Control_Vector_Translate, Key_Translate

Table 22. DES key types and verb usage (continued)
DES key type Usable with verbs
PIN class
These keys are used in the various financial-PIN processing commands. They are double-length keys. In operational
form and in external form, these keys are associated with a control vector.
PINGEN Clear_PIN_Generate, Clear_PIN_Generate_Alternate, Encrypted_PIN_Generate,
Encrypted_PIN_Verify
PINVER Encrypted_PIN_Verify
IPINENC Clear_PIN_Generate_Alternate, Encrypted_PIN_Translate,
Encrypted_PIN_Verify, PIN_Change/Unblock, Secure_Messaging_for_PINs
OPINENC Clear_PIN_Encrypt, Encrypted_PIN_Generate, Encrypted_PIN_Translate,
PIN_Change/Unblock
Key-generating-key class
These keys are used to derive keys. They are double-length keys. In operational form and external form, these keys
are associated with a control vector.
KEYGENKY Diversified_Key_Generate, Encrypted_PIN_Translate, Encrypted_PIN_Verify
DKYGENKY Diversified_Key_Generate, PIN_Change/Unblock
Cryptographic-variable class
These keys are used in the special verbs that operate with cryptographic variables and are single-length keys. In
operational form and in external form, these keys are associated with a control vector.
CVARENC Cryptographic_Variable_Encipher
CVARXCVL Control_Vector_Translate
CVARXCVR Control_Vector_Translate
By differentiating keys with a control vector, a given key-value can be multiply-enciphered with different
control vectors so as to impart different capabilities to copies of the key. This technique creates DES keys
having an asymmetric property.
Symmetric DES keys
A symmetric DES key can be used in two related processes. The cryptographic facility can interpret
the following key types as symmetric:
v CIPHER and DATA. A key with these key types can be used to both encipher and decipher data.
Note: Uppercase letters are used for DATA to distinguish the meaning from a more general sense
in which the term data keys means keys used for ciphering and for MAC. In this document,
DATA means keys with control vector bits 8 -15 valued to X'00'.
v MAC. A key with this key type can be used to create a message authentication code (MAC) and to
verify a trial MAC
Asymmetric DES keys
An asymmetric DES key is a key in a key pair in which the keys are used as opposites.
v ENCIPHER and DECIPHER. Used to only encrypt data versus only to decrypt data.
v MAC and MACVER. Used in generating (and verifying) a MAC versus only verifying a MAC.
v PINGEN and PINVER. Used in generating (and verifying) a personal identification number (PIN)
versus only verifying a PIN.
v OPINENC and IPINENC. Used to only encrypt a PIN block versus only to decrypt a PIN block.
Similarly, these unusual DES key types are paired for other opposite purposes:
v CVARENC and CVARXCVL
v CVARENC and CVARXCVR

The cryptographic facility also interprets key-encrypting keys with the following key types as
asymmetric keys that can be used to create one-way key-distribution channels:
v EXPORTER or OKEYXLAT. A key with this key type can encipher a key at a node that exports the
key.
v IMPORTER or IKEYXLAT. A key with this key type can decipher a key at a node that imports the
key.
An EXPORTER key is paired with an IMPORTER or an IKEYXLAT key. An IMPORTER key is paired
with an EXPORTER or an OKEYXLAT key. These key types permit the establishment of a
unidirectional key-distribution channel which is important both to preserve the asymmetric capabilities
possible with CCA-architecture systems, and to further secure a key-distribution system from
unintended key-distribution possibilities.
For information about generating key pairs, see Generating symmetric keys on page 173.
Depending on the key type, a DES key can be single or double in length. A double-length key that has
different values in its left and right halves greatly increases the difficulty for an adversary to obtain the
clear value of the enciphered quantity. A double-length key that has the same values in its left and right
halves produces the same results as a single-length key and therefore has the strength of a single-length
key. See Table 22 on page 150 for a list of verbs that can use each data type.
Some verbs can create a default control-vector for a DES key type. For information about the values for
these control vectors, see Appendix C, CCA control-vector definitions and key encryption.
| AES and HMAC key usage and key management restrictions

| Beginning with Release 3.30, CCA added support for AES keys. This support defines a fixed-length
| key-token that either contains a control vector of all zeros or has no control vector. Either way, a key in a
| fixed-length AES key-token has a key type of DATA, and can be used by the
| Symmetric_Algorithm_Decipher and Symmetric_Algorithm_Encipher verbs for decryption and encryption of
| data using the AES algorithm.
| Beginning with Release 4.1, CCA added support for HMAC keys in a newly defined variable-length
| symmetric key-token. This key token consists of a header, a wrapping information section, an associated
| data section, and an optional payload. See Variable-length symmetric key-token on page 614.
| If a payload is not present, the key token is a skeleton. A skeleton key-token does not contain a key. To
| build a skeleton key-token, use the Key_Token_Build2 verb and specify the desired key attributes. After it
| is built, use this key token as input to the Key_Generate2 verb or Key_Part_Import2 verb. These verbs
| update the key token with an enciphered key or key part. The Key_Token_Build2 verb can also build a key
| token that contains a clear key.
| If a payload is present in a variable-length symmetric key-token, it contains key material. The key material
| can be clear or encrypted. Not all key types support a clear key. If the key material is in the clear, the
| payload contains only the key. If the key material is encrypted, the payload contains the key and other
| information, including a hash of the associated data section. The enciphered hash value securely binds the
| unencrypted associated data to the key.
| The associated data section contains fields for type of algorithm for which the key can be used, key type,
| key usage, and key management. In addition to the algorithm and key type, the values of the key-usage
| and key-management fields further restrict the use of a key. Key usage and key management restrictions
| can be varied by using keywords when constructing a variable-length symmetric key-token with the
| Key_Token_Build2 verb. It is also possible to manually construct a variable-length symmetric key-token
| that is a skeleton or that contains a clear key.

| An HMAC key can have a key type of MAC. A MAC key in a variable-length HMAC key-token can be used
| by the HMAC_Generate and HMAC_Verify verbs to generate or verify a keyed hash message
| authentication code (HMAC) against a message text.
| Beginning with release 4.2, CCA extended support for AES keys in the same variable-length symmetric
| key-token defined with Release 4.1. A variable-length HMAC key-token can have a key type of CIPHER,
| EXPORTER, or IMPORTER:
| v A CIPHER key can be used by the Symmetric_Algorithm_Decipher and Symmetric_Algorithm_Encipher
| verbs to decipher or encipher data using the AES algorithm.
| v An EXPORTER key can be used by the Symmetric_Key_Export verb to export an AES or HMAC key
| contained in an internal variable-length symmetric key-token, wrapped using the AESKW key-formatting
| method, and encrypted under the AES master-key, and return the key in an external variable-length
| symmetric key-token using key-formatting method AESKW, encrypted under an AES EXPORTER
| key-encrypting key.
| v An IMPORTER key can be used by this verb:
| The Symmetric_Key_Import2 verb can use an AES IMPORTER key-encrypting key to import an AES
| or HMAC key contained in an external variable-length symmetric key-token, wrapped using either the
| AESKW key-formatting method, and rewrap the key under the AES master-key in an internal
| variable-length symmetric key-token using key-formatting method AESKW.
| v An EXPORTER or IMPORTER key can be used by these verbs:
| The Key_Generate2 verb can use operational AES EXPORTER and IMPORTER key-encrypting keys
| to wrap external keys in a variable-length symmetric key-tokens.
| The Key_Test2 verb can use an AES EXPORTER or IMPORTER key-encrypting key to test the
| value of a key or key part contained in an external variable-length symmetric key-token.
| The Key_Translate2 verb can use AES EXPORTER and IMPORTER key encrypting keys to reformat
| or translate an AES or HMAC key contained in an external variable-length symmetric key-token into
| a different external variable-length symmetric key token.
| The Restrict_Key_Attribute verb can use an AES EXPORTER or IMPORTER key-encrypting key for
| lowering the export authority of a key in an external AES or HMAC variable-length symmetric
| key-token.
|

| Figure 6 shows all the valid keyword combinations and their defaults for AES key type CIPHER. For a
| description of these keywords, refer to Table 23 on page 157.
|
|
| Wrapping
| info. Key-usage
| Key type section fields Key-management fields
|
| Note: Note: Note:
| NOKEY XPRTSYM XPRTDES
| is default. Note 1 is default. is default
| >>+CIPHER+
| KEY-CLR DECRYPT NOEX-SYM NOEX-DES
| NOKEY ENCRYPT XPRT-SYM XPRT-DES
|
|
| Note 1: All keywords in this Note: Note:
| group are defaults XPRTUASY XPRTAES
| unless one or more Note 2 is default. is default
| keywords in the group
| are specified. V NOEXUASY NOEX-AES
| Note 2: Choose any number of UDX-ONLY XPRTUASY XPRT-AES
| keywords in this group. UDX-001
| No keywords in this UDX-010
| group are defaults. UDX-100 Note: Note:
| XPRTAASY XPRTRSA
| is default. is default
| Note: CBC
| is default. NOEXAASY NOEX-RSA
| CBC XPRTAASY XPRT-RSA>>
| CFB
| ECB
| GCM
| OFB
| XTS
|
| Figure 6. Key_Token_Build2 keyword combinations for AES CIPHER keys

| Figure 7 shows all the valid keyword combinations and their defaults for AES key type EXPORTER. For a
|
|
| Wrapping
| info. Key-usage
|
| Note: Note: Note:
| NOKEY XPRT-SYM XPRTDES
| is default. is default. is default
| >>+EXPORTER+ Note 1
| NOKEY NOEX-SYM NOEX-DES
| V XPRT-SYM XPRT-DES
| EXPORT
| Note 1: All keywords in the GEN-EXEX
| group are defaults GEN-IMEX Note: Note:
| unless one or more GEN-OPEX XPRTUASY XPRTAES
| keywords in the group GEN-PUB is default. is default
| are specified. TRANSLAT
| Note 2: Choose any number of NOEXUASY NOEX-AES
| keywords in this group. XPRTUASY XPRT-AES
| No keywords in the
| group are defaults. Note 2
| Note 3: Keywords WRAES, Note: Note:
| WRDES, and WRHMAC V XPRTAASY XPRT-RSA
| are defaults unless UDX-ONLY is default. is default
| one or more keywords UDX-001
| in the group are UDX-010 NOEXAASY NOEX-RSA
| specified. UDX-100 XPRTAASY XPRT-RSA>>
|
|
|
| Note 3
|
| V
| WR-AES
| WR-DES
| WR-ECC
| WR-HMAC
| WR-RSA
|
|
|
| Note 1
|
| V
| WR-CARD
| WR-DATA
| WR-KEK
| WR-PIN
| WRDERIVE
|
| Figure 7. Key_Token_Build2 keyword combinations for AES EXPORTER keys

| Figure 8 shows all the valid keyword combinations and their defaults for AES key type IMPORTER. For a
|
|
| Wrapping
| info. Key-usage
|
| Note: Note: Note:
| NOKEY XPRT-SYM XPRTDES
| is default. is default. is default
| >>+IMPORTER+ Note 1
| NOKEY NOEX-SYM NOEX-DES
| V XPRT-SYM XPRT-DES
| GEN-IMEX
| Note 1: All keywords in the GEN-IMIM
| group are defaults GEN-OPIM Note: Note:
| unless one or more GEN-PUB XPRTUASY XPRTAES
| keywords in the group IMPORT is default. is default
| are specified. TRANSLAT
| Note 2: Choose any number of NOEXUASY NOEX-AES
| keywords in this group. XPRTUASY XPRT-AES
| No keywords in the
| group are defaults. Note 2
| Note 3: Keywords WRAES, Note: Note:
| WRDES, and WRHMAC V XPRTAASY XPRT-RSA
| are defaults unless UDX-ONLY is default. is default
| one or more keywords UDX-001
| in the group are UDX-010 NOEXAASY NOEX-RSA
| specified. UDX-100 XPRTAASY XPRT-RSA>>
|
|
|
| Note 3
|
| V
| WR-AES
| WR-DES
| WR-ECC
| WR-HMAC
| WR-RSA
|
|
|
| Note 1
|
| V
| WR-CARD
| WR-DATA
| WR-KEK
| WR-PIN
| WRDERIVE
|
| Figure 8. Key_Token_Build2 keyword combinations for AES IMPORTER keys

| Figure 9 shows all the valid keyword combinations and their defaults for HMAC key type MAC. For a
| description of these keywords, refer to Table 23.
|
|
| Wrapping
| info. Key-usage
|
| Note: Note: Note:
| NOKEY Note: One XPRT-SYM XPRTDES
| is default. required. is default. is default
| >>+MAC+ GENERATE
| KEY-CLR VERIFY NOEX-SYM NOEX-DES
| NOKEY XPRT-SYM XPRT-DES
|
|
| Note 1: Choose any number of Note 1 Note: Note:
| keywords in this group. XPRTUASY XPRTAES
| No keywords in the V is default. is default
| group are defaults. UDX-ONLY
| Note 2: All keywords in the UDX-001 NOEXUASY NOEX-AES
| group are defaults UDX-010 XPRTUASY XPRT-AES
| unless one or more UDX-100
| keywords in the group
| are specified. Note: Note:
| XPRTAASY XPRT-RSA
| Note 2 is default. is default
|
| V NOEXAASY NOEX-RSA
| SHA-1 XPRTAASY XPRT-RSA>>
| SHA-224
| SHA-256
| SHA-384
| SHA-512
|
| Figure 9. Key_Token_Build2 keyword combinations for HMAC MAC keys
| Table 23. Key_Token_Build2 variable-length AES and HMAC key-token keywords

| Keyword Meaning
| Key-usage field 1, high-order byte
| Encrypt key-usage control (optional, any combination, CIPHER key type only). All keywords in this group are defaults
| unless one or more keywords are specified.
| ENCRYPT Key can be used for encryption. Used by Symmetric_Algorithm_Encipher.
| DECRYPT Key can be used for decryption. Used by Symmetric_Algorithm_Decipher.
| Generate key-usage control (one, required; MAC key type only).
| GENERATE Key can be used for generate and key can be used for verify. Used by HMAC_Generate.
| VERIFY Key cannot be used generate and key can be used for verify. Used by HMAC_Verify.
| EXPORTER key-usage control (any combination, optional; EXPORTER key type only). All keywords in this group are
| defaults unless one or more keywords are specified.
| EXPORT Key can be used for EXPORT. Used by Symmetric_Key_Export.
| TRANSLAT Key can be used for TRANSLAT. Used by Key_Translate2.
| GEN-OPEX Key can be used for GENERATE-OPEX. Used by Key_Generate2.
| GEN-IMEX Key can be used for GENERATE-IMEX. Used by Key_Generate2.
| GEN-EXEX Key can be used for GENERATE-EXEX. Used by Key_Generate2.
| GEN-PUB Key can be used for GENERATE-PUB. Used by Key_Generate2.

| Table 23. Key_Token_Build2 variable-length AES and HMAC key-token keywords (continued)
| Keyword Meaning
| IMPORTER key-usage control (any combination, optional; IMPORTER key type only). All keywords in this group are
| IMPORT Key can be used for IMPORT. Used by Symmetric_Key_Import.
| GEN-OPIM Key can be used for GENERATE-OPIM. Used by Key_Generate2.
| GEN-IMIM Key can be used for GENERATE-IMIM. Used by Key_Generate2.
| GEN-PUB Key can be used for GENERATE-PUB.
| Key-usage field 1, low-order byte
| User-defined extension control (any combination, optional; all key types; Release 4.2 or later). No keywords in this
| group are default. The default behavior is for the key to be usable by both CCA and UDXs, and that no user-defined
| UDX bits are set on.
| UDX-ONLY Specifies that this key can only be used in UDXs.
| UDX-001 Specifies that the rightmost user-defined UDX bit is set on.
| UDX-010 Specifies that the middle user-defined UDX bit is set on.
| UDX-100 Specifies that the leftmost user-defined UDX bit is set on.
| Key-usage mode (one, optional; CIPHER key type only)
| CBC Indicates that this key can be used for Cipher Block Chaining. This is the default.
| ECB Indicates that this key can be used for Electronic Code Book.
| CFB Indicates that this key can be used for Cipher Feedback.
| OFB Indicates that this key can be used for Output Feedback.
| GCM Indicates that this key can be used for Galois/Counter Mode.
| XTS Indicates that this key can be used for Xor-Encrypt-Xor-based Tweaked Stealing.
| Hash method (any combination, optional; MAC key type only). All keywords in this group are defaults unless one or
| more keywords are specified.
| SHA-1 SHA-1 hash method is allowed for the key.
| Byte is reserved.

| Keyword Meaning
| Key-usage wrap algorithm (any combination, optional; EXPORTER or IMPORTER key types only). Keywords
| WR-DES, WR-AES, and WR-HMAC are defaults unless one or more keywords are specified.
| WR-DES Key can wrap DES keys.
| WR-AES Key can wrap AES keys.
| WR-HMAC Key can wrap HMAC keys.
| WR-RSA Key can wrap RSA keys.
| WR-ECC Key can wrap ECC keys.
| Byte is reserved.
| Key-usage wrap class (any combination, optional; EXPORTER or IMPORTER key types only). All keywords are
| WR-DATA Key can wrap DATA class keys.
| WR-KEK Key can wrap KEK class keys.
| WR-PIN Key can wrap PIN class keys.
| WRDERIVE Key can wrap DERIVATION class keys.
| WR-CARD Key can wrap CARD class keys.
| Byte is reserved.
| Key-management field 1, high-order byte
| Symmetric-key export control (one, optional; all key types).
| NOEX-SYM Prohibit export using symmetric key.
| XPRT-SYM Allow export using symmetric key. This is the default.
| Unauthenticated asymmetric-key export control (one, optional; all key types).
| NOEXUASY Prohibit export using an unauthenticated asymmetric key (not a trusted block).
| XPRTUASY Allow export using an unauthenticated asymmetric key (not a trusted block). This is the
| default.
| Authenticated asymmetric-key export control (one, optional; all key types)
| NOEXAASY Prohibit export using an authenticated asymmetric key (trusted block).
| XPRTAASY Allow export using an authenticated asymmetric key (trusted block). This is the default.
| Key-management field 1, low-order byte
| DES-key export control (one, optional; all key types; Release 4.2 or later)
| NOEX-DES Prohibit export using DES key
| XPRT-DES Allow export using DES key. This is the default.
| AES-key export control (one, optional; all key types)
| NOEX-AES Prohibit export using AES key.
| XPRT-AES Allow export using AES key. This is the default.
| RSA-key export control (one, optional; all key types)
| NOEX-RSA Prohibit export using RSA key
| XPRT-RSA Allow export using RSA key. This is the default.

| Keyword Meaning
| Byte will contain key completeness (all key types; Release 4.2 or later). There is no user-defined content.
| Byte will contain security history (all key types; Release 4.2 or later). There is no user-defined content).
| Byte will contain pedigree original rules (all key types; Release 4.2 or later). There is no user-defined content).
| Byte will contain pedigree current rules (all key types; Release 4.2 or later). There is no user-defined content).
|
| DES key usage restrictions

In addition to a key type and subtype, a DES control vector contains key usage values that further restrict
the use of a key. Most key types define a default set of key usage restrictions in a control vector. See
Table 162 on page 657. DES key usage restrictions can be varied by using keywords when constructing
control-vector values using the Key_Token_Build verb or the Control_Vector_Generate verb, or by
manually setting key-usage bits in the control vector.
Figure 10 on page 161 shows the key-type, key subtype, and key-usage keywords that can be combined
in the Control_Vector_Generate verb and the Key_Token_Build verb to build a DES control vector. The left
column lists the key types, the middle column lists the subtype keywords, and the right column lists the
key-usage keywords that further define a control vector. Table 24 on page 162 describes the
control-vector-usage keywords.
For information about DES control-vector bits, see Appendix C, CCA control-vector definitions and key
encryption.

| Key typeKey subtypeKey usage
|
|
MAC Note: ANY-MAC is default Note: XPORTOK

| MACVER is default
| DATA ANY-MAC
| CIPHER ANSIX9.9 XPORTOK
| ENCIPHER CVVKEYA NO-XPORT
| DECIPHER CVVKEYB
| CVARDEC AMEXCSC
| CVARPINE
| CVARENC Note: SINGLE
| CVARXCVL is default KEYPART
| CVARXCVR
| Note: DKYL0 Note: DMAC SINGLE
| is default is default KEYLN8
| DKYGENKY DOUBLE
| DKYL0 DMAC KEYLN16 ENH-ONLY
| DKYL1 DDATA MIXED
| DKYL2 DMV
| DKYL3 DIMP
| DKYL4 DEXP Note: T31XPTOK
| DKYL5 DPVR is default
| DKYL6 DMKEY
| DKYL7 DMPIN T31XPTOK
| DALL NOT31XPT
| SECMSGSMKEY
| DATAC SMPIN
| DATAM
| DATAMV
| KEYGENKYCLR8ENC
| IKEYXLAT UKPT
| OKEYXLAT
| IMPORTERNote 1
|
|
| OPIM
| IMEX
| IMIM
| IMPORT
| EXPORTERNote 1
|
|
| OPEX
| IMEX
| EXEX
| EXPORT
| XLATE
| PINVER
| PINGENNote 1
|
|
| CPINGEN
| CPINGENA
| EPINGEN
| EPINGENA
| EPINVER
| IPINENCNote 1 Note: NOSPEC
| is default
|
| CPINGENA NOSPEC
| EPINVER IBMPIN
| REFORMAT GBPPIN
| TRANSLAT IBMPINO NOOFFSET
| OPINENCNote 1 GBPPINO
| VISAPVV
| INBKPIN
| CPINENC Note:
| EPINGEN DOUBLE
| REFORMAT is default
| TRANSLAT
| DOUBLE
| Note 1: All keywords in the list below are KEYLN16
| defaults unless one or more keywords MIXED
| in the list are specified.
|
|
| Figure 10. Control_Vector_Generate and Key_Token_Build CV keyword combinations for fixed-length DES key tokens

Table 24. DES control vector key-subtype and key-usage keywords
Keyword Meaning
Key-encrypting keys
OPIM IMPORTER keys that have a control vector with this attribute can be used in the
Key_Generate verb when the key form is OPIM.
IMEX IMPORTER and EXPORTER keys that have a control vector with this attribute can be
used in the Key_Generate verb when the key form is IMEX.
IMIM IMPORTER keys that have a control vector with this attribute can be used in the
Key_Generate verb when the key form is IMIM.
IMPORT IMPORTER keys that have a control vector with this attribute can be used to import a
key in the Key_Import verb.
OPEX EXPORTER keys that have a control vector with this attribute can be used in the
Key_Generate verb when the key form is OPEX.
EXEX EXPORTER keys that have a control vector with this attribute can be used in the
Key_Generate verb when the key form is EXEX.
EXPORT EXPORTER keys that have a control vector with this attribute can be used to export a
key in the Key_Export verb.
| XLATE IMPORTER and EXPORTER keys that have a control vector with this attribute can be
| used in the Key_Translate or Key_Translate2 verbs.
ANY Key-encrypting keys that have a control vector with this attribute can be used to
transport any type of key. The meaning of this keyword has been discontinued, and its
usage is allowed for backward compatibility reasons only.
NOT-KEK Key-encrypting keys that have a control vector with this attribute formerly could not be
used to transport key-encrypting keys. The meaning of this keyword has been
discontinued and its usage is allowed for backward compatibility reasons only.
DATA Key-encrypting keys that have a control vector with this attribute formerly could only be
used to transport keys with a key type of DATA, CIPHER, ENCIPHER, DECIPHER,
MAC, and MACVER. The meaning of this keyword has been discontinued and its usage
is allowed for backward compatibility reasons only.
| PIN Key-encrypting keys that have a control vector with this attribute formerly could only be
| used to transport keys with a key type of PINVER, IPINENC, and OPINENC. The
| meaning of this keyword has been discontinued and its usage is allowed for backward
| compatibility reasons only.
LMTD-KEK Key-encrypting keys that have a control vector with this attribute formerly could only be
used to exchange keys with key-encrypting keys that carry NOT-KEK, PIN, or DATA
key-type ciphering restrictions. The meaning of this keyword has been discontinued and
its usage is allowed for backward compatibility reasons only.
| MAC keys
| ANY-MAC Any MAC verb can use this key.
| ANSIX9.9 The meaning of this keyword has been discontinued and its usage is allowed for
backward compatibility reasons only.
| CVVKEY-A Restricts the usage to single-length key-A key or, beginning with Release 4.2,
double-length key-A and key-B keys for the CVV_Generate and CVV_Verify verbs.
| CVVKEY-B Restricts the usage to single-length key-B key for the CVV_Generate and CVV_Verify
verbs.
Data operation keys
SMKEY Enable the encryption of keys in an EMV secure message.
SMPIN Enable the encryption of PINs in an EMV secure message

Table 24. DES control vector key-subtype and key-usage keywords (continued)
Keyword Meaning
PIN keys
NO-SPEC The control vector does not require a specific PIN-calculation method.
IBM-PIN Select the IBM 3624 PIN-calculation method.
IBM-PINO Select the IBM 3624 PIN-calculation method with offset processing.
GBP-PIN Select the IBM German Bank Pool PIN-calculation method.
GBP-PINO Select the IBM German Bank Pool PIN-calculation method with institution-PIN input or
output.
VISA-PVV Select the Visa PVV PIN-calculation method.
INBK-PIN Select the InterBank PIN-calculation method.
NOOFFSET Indicates that a PINGEN or PINVER key cannot participate in the generation or
verification of a PIN when an offset process is requested.
CPINGEN The key can participate in the Clear_PIN_Generate verb.
CPINGENA The key can participate in the Clear_PIN_Generate_Alternate verb.
EPINGEN The key can participate in the Encrypted_PIN_Generate verb.
EPINVER The key can participate in the Encrypted_PIN_Verify verb.
CPINENC The key can participate in the Clear_PIN_Encrypt verb.
REFORMAT The key can participate in the Encrypted_PIN_Translate verb in the Reformat mode.
TRANSLAT The key can participate in the Encrypted_PIN_Translate verb in the Translate mode.
Key-generating keys
CLR8-ENC The key can be used to multiply encrypt eight bytes of clear data with a generating key.
DALL The key can be used to generate keys with the following key types: DATA, DATAC,
DATAM, DATAMV, DMKEY, DMPIN, EXPORTER, IKEYXLAT, IMPORTER, MAC,
MACVER, OKEYXLAT, and PINVER.
DDATA The key can be used to generate a single-length or double-length DATA or DATAC key.
DEXP The key can be used to generate an EXPORTER or an OKEYXLAT key.
DIMP The key can be used to generate an IMPORTER or an IKEYXLAT key.
DMAC The key can be used to generate a MAC or DATAM key.
DMKEY The key can be used to generate a SECMSG with SMKEY secure messaging key for
encrypting keys.
DMPIN The key can be used to generate a SECMSG with SMPIN secure messaging key for
encrypting PINs.
DMV The key can be used to generate a MACVER or DATAMV key.
DPVR The key can be used to generate a PINVER key.
DKYL0 A DKYGENKY key with this subtype can be used to generate a key based on the
key-usage bits.
DKYL1 A DKYGENKY key with this subtype can be used to generate a DKYGENKY key with a
subtype of DKYL0.
subtype of DKYL1.
subtype of DKYL2.
subtype of DKYL3.

Table 24. DES control vector key-subtype and key-usage keywords (continued)
Keyword Meaning
subtype of DKYL4.
subtype of DKYL5.
subtype of DKYL6.
Key lengths
MIXED Indicates that the key can be either a replicated single-length key or a double-length
key with two different, random 8-byte values.
SINGLE, KEYLN8 Specifies the key as a single-length key.
DOUBLE, KEYLN16 Specifies the key as a double-length key.
Miscellaneous attributes
| XPORT-OK Permits the key to be exported by Key_Export or Data_Key_Export. Also, beginning
| with Release 4.2, permits the key to be exported by the Key_Export_to_TR31 verb,
| unless NOT31XPT is set.
NO-XPORT Prohibits the key from being exported by Key_Export or Data_Key_Export.
KEY-PART Specifies the control vector is for a key part.
ENH-ONLY (Rel. 4.1 or Prohibits the key from being wrapped with the legacy method once it has been wrapped
later) with the enhanced method.
| T31XPTOK (Rel. 4.2 or Permits the key to be exported by the Key_Export_to_TR31 verb.
later)
| NOT31XPT (Rel. 4.2 or Prohibits the key from being exported by the Key_Export_to_TR31 verb.
later)
Key tokens, key labels, and key identifiers

In CCA, a cryptographic key is generally contained within a data structure called a key token. A CCA AES
key-token can contain a cleartext or enciphered key that is 16, 24, or 32 bytes (128, 192, or 256 bits) in
length, and other information pertaining to the key. AES key tokens can be null or internal, but not
external. AES key tokens are not supported in releases before Release 3.30.
A CCA variable-length symmetric key-token can contain a cleartext or enciphered key that is 80 - 2048 bits
in length, and other information pertaining to the key such as key usage and key management fields.
These key tokens can be null, internal, or external. Variable-length symmetric key tokens are not
supported in releases before Release 4.1.
A CCA fixed-length DES key-token can contain an encrypted single-length or double-length key, a control
vector, and other information pertinent to the key. DES key tokens can be null, internal, or external. An
internal key-token that is complete and ready for use is considered an operational key-token. In contrast,
an internal fixed-length DES key-token that has no control vector present, no key present, or has its
KEY-PART bit on in its control vector is not an operational key-token.
Key tokens can be stored in key storage and are accessed using a key label. The CCA API generally
permits an application to provide either a key token or a key label of an internal key-token, in which case
the parameter description is designated a key identifier. Key tokens, key labels, and key identifiers are
discussed in the following sections.

AES, DES, and variable-length symmetric key tokens
The CCA security API operates with a key token rather than operating simply with a key. Fixed-length AES
and DES key tokens are both 64-byte data structures. See Figure 11. Variable-length symmetric key
tokens are defined in Table 130 on page 614.
| v A fixed-length AES key-token must be an internal key-token. A variable-length AES key-token can be
| external or internal. An AES key-token can contain either a cleartext or enciphered key in addition to
| other information frequently needed with the key. EXPORTER and IMPORTER keys are always
| enciphered.
v A fixed-length DES key-token can either be external or internal. It can contain only an enciphered key in
addition to other information frequently needed with the key.
| v A variable-length symmetric key-token (AES or HMAC) can either be external or internal. It can contain
either a cleartext or an enciphered key payload, in addition to other information frequently needed with
the key. This information includes associated data that is cryptographically bound to the encrypted
payload, if there is one. The associated data includes key-usage and key-management fields.
For detailed information about AES, DES, and variable-length symmetric key tokens, see Appendix B,
Data structures, on page 577.
| AES fixed-length key-token:

0 8 16 48 56 60 63

Key-token Flags Master-key Internal enciphered or Control vectorKey TVV
identifier and verification cleartext key lengths
LRC pattern

| DES fixed-length key-token:

0 8 16 32 48 60 63

Key-token Flags Master-key Internal or Control TVV
identifier verification external vector
pattern enciphered
key

| Figure 11. AES and DES fixed-length key-token contents
The following describes in more detail the contents of AES and DES fixed-length key tokens:
| Key-token identifier
This identifies whether the fixed-length key token is for AES or DES. It also identifies if the key token is
an internal key-token, an external key-token, or a null key-token. AES currently does not use external
key tokens.
Flags
Flags are bit values that provide control information for using the key. For AES, the flags indicate if a
master-key verification pattern (MKVP) is present, if an enciphered or cleartext key is present, and if a
control vector (CV) is present. For DES, the flags indicate if an MKVP is present, if an enciphered key
is present, and if a CV is present. Beginning with Release 4.1, the flags also indicate the wrapping
method of the key in the key token.
LRC
| A longitudinal redundancy check is present in AES fixed-length key tokens that have an enciphered or
| cleartext key present. This checksum byte is valued to the exclusive-OR of each clear-key byte.
MKVP
A master-key verification pattern must be present if and only if the key token contains a key enciphered

under the master key. An MKVP permits the cryptographic engine to detect whether the key within the
token is enciphered by an available master key. Only internal key tokens have an MKVP.
Internal enciphered or cleartext key
| All AES fixed-length key tokens are internal, and are not supported by key-encrypting keys other than
| the master key, so there are no external fixed-length AES key tokens. If a fixed-length AES key-token
| has a key present, the key is either enciphered under the AES master-key or is in the clear. An AES
| clear-key that is 16 or 24 bytes in length is left-aligned in the 32-byte key field and padded on the right
| with binary zeros. An enciphered AES key is always 32 bytes in length. Variable-length AES key tokens
| can be external or internal, and are supported by AES key-encrypting keys.
Internal or external enciphered key
Fixed-length DES key tokens can be internal or external. If a DES key is present in a token, it is
enciphered. A key in a fixed-length DES internal key-token is enciphered under the DES master-key,
while a key in a fixed-length external DES key-token is enciphered under an IMPORTER or
EXPORTER DES key-encrypting key.
Control vector
| A control vector (CV) provides information about the permitted uses of the key in a fixed-length
| key-token. If a CV is present in a fixed-length AES key-token, it must be binary zeros. If it is not
| present, an enciphered key can still be present because an AES CV is not involved in the enciphering
| process. All fixed-length AES key tokens are treated as AES DATA keys, even those without a CV
| present. If a fixed-length DES key-token has a key present, it must also have a CV, which is used to
| encipher and decipher the key. The CV of a DES key provides information about the permitted uses of
| the key. A CV in a fixed-length DES key-token contains the key length of the enciphered key.
Key lengths
A fixed-length AES key-token has a clear-key bit length field and an encrypted-key byte length.
1. If a key is not present, both of these lengths are zero.
2. If a clear key is present, the clear-key bit length is the length of the key in bits (128, 192, or 256)
and the encrypted-key byte length is zero.
3. If an encrypted key is present, the clear-key bit length is the actual length of the key in bits (128,
192, or 256) and the encrypted-key byte length is 32. Before an AES key is enciphered, it is
left-aligned and padded on the right with binary zeros to a length of 32. The result of encrypting this
32-byte value under the AES master key is stored in the key token.
TVV
The token-validation value is a checksum of the fixed-length key token. It is calculated by taking the
two's complement add on four bytes at a time of the key token, starting with bytes 0 - 3 and ending
with bytes 56 - 59, ignoring carries and overflow.
You can use the Key_Token_Build verb to assemble a fixed-length internal AES or fixed-length external or
internal DES key-token, or use the Key_Token_Parse verb to disassemble a fixed-length DES key token.
| You can use the Key_Token_Build2 verb to assemble a variable-length symmetric key-token, or use the
| Key_Token_Parse2 verb to disassemble a variable-length symmetric key-token. You should keep in mind,
however, that the contents and format of key tokens are version and implementation sensitive. Key token
formats are described in Appendix B, Data structures, on page 577.
The cryptographic system uses key labels and internal and null AES key tokens as shown in Figure 12 on
page 167

| Internal AES key-token (version X04)
| 0 63
|
|
X01 e*KM.(KEY)
|
|
|
| Null AES key-token
| 0 63
|
| Key identifier
OR
X00 . . . X00
|
|
|
| Key label
| 0 63
|
|
Name_token_1.Name_token_2. -- .Name_token_n
|
|
|
| The first byte is
| in the range of
| X20 - XFE AES key-storage
|
|
|
|
|
|
| Key label Key token
|
| Figure 12. Use of fixed-length AES key tokens and key labels
Internal fixed-length AES key-token

A completed internal fixed-length AES key-token is specified in a verb call by using a key_token or
key_identifier parameter. These verbs produce or modify an internal fixed-length AES key-token:
v Key_Generate
v Key_Token_Build
v Key_Token_Change
v Multiple_Clear_Key_Import
Null fixed-length AES key-token

A null fixed-length AES key-token is a 64-byte string that begins with the value X'00'. A null fixed-length
AES key-token can reside in application storage or in AES key-storage. Some verbs that create an AES
fixed-length key-token with default values do so when you identify a null AES key-token.
The cryptographic system uses key labels and external, internal, and null fixed-length DES key tokens, as
shown in Figure 13 on page 168.

External fixed-length DES key-token (not version X'10')
0 63

X02 e*KEK.CV(KEY)

|

| External fixed-length RKX DES key-token (version X'10')
| 0 63
|
OR
X02 e*MAC.VAR(KEY)

|
Key identifier
|
Internal fixed-length DES key-token
0 63

OR
X01 e*KM.CV(KEY)

Null DES key-token
0 63

OR
X00 . . .

Key label
0 63

Name_token_1.Name_token_2. -- .Name_token_n

The first byte is
in the range of DES key-storage
X20 - XFE

Key label Key token
Figure 13. Use of fixed-length DES key tokens and key labels
External fixed-length DES key-token

A completed external fixed-length DES key-token contains an external key that is multiply-enciphered
under a key formed by the exclusive-OR of a key-encrypting key and the control vector that was assigned
when the key token was created or updated.
An external fixed-length DES key-token is specified in a verb call using a key_token or key_identifier
parameter. An external key-token resides in application storage or key storage. These verbs produce or
modify an external fixed-length DES key-token:
v Control_Vector_Translate
v Data_Key_Export
v DES_Key_Record_Read
v Key_Export
v Key_Generate
v Key_Token_Build

v Key_Translate
v Prohibit_Export_Extended
v Remote_Key_Export
External fixed-length RKX DES key-token

An RKX key-token is a special external fixed-length DES key-token used exclusively by the
Remote_Key_Export verb and DES key-storage verbs (for example, DES_Key_Record_Write). The token
is always external (see External RKX DES key tokens on page 583). It contains a confounder and
triple-length MAC key encrypted under a variant of the MAC key found in the protection information
subsection of a trusted block information section (see Trusted blocks on page 600).
Internal fixed-length DES key-token

A completed internal fixed-length DES key-token contains an operational key that is multiply-enciphered
under a key formed by the exclusive-OR of a DES master-key and the control vector that was used when
the key token was created or updated.
An internal fixed-length DES key-token is specified in a verb call by using a key_token or key_identifier
parameter. These verbs produce or modify an internal fixed-length DES key-token:
v Clear_Key_Import
v Data_Key_Import
v Diversified_Key_Generate
v Key_Generate
v Key_Import
v Key_Part_Import
v Key_Token_Build
v Key_Token_Change
v Prohibit_Export
Null fixed-length DES key-token

A null fixed-length DES key-token is a 64-byte string that begins with the value X'00'. A null fixed-length
DES key-token can reside in application storage or in DES key-storage. Some verbs that create a DES
key-token with default values do so when you identify a null DES key-token.
Internal variable-length symmetric key-token

A completed internal variable-length symmetric key-token contains a clear key payload, or a key payload
enciphered under the AES master-key.
An internal variable-length symmetric key-token is specified in a verb call by using a key_token or

key_identifier parameter. These verbs produce or modify an internal variable-length symmetric key-token:
v Key_Generate2
v Key_Part_Import2
v Key_Token_Build2
v Key_Token_Change2
v Restrict_Key_Attribute
v Symmetric_Key_Import2

External variable-length symmetric key-token
A completed external variable-length symmetric key-token contains a formatted key enciphered under an
| RSA public-key or an AES key-encrypting key. These verbs produce or modify an external variable-length
symmetric key-token:
| v Key_Generate2 (Release 4.2 or later)
| v Key_Token_Build2 (Release 4.2 or later)
v Key_Translate2
| v Symmetric_Key_Export (Release 4.1 or later)
Key labels
A key label serves as an indirect address for a key-token record in key storage. The security server uses a
key label to access key storage to retrieve or to store the key token. A key_identifier parameter can point
to either a key label or a key token. Key labels are discussed further at Key-label content on page 390.
Key identifiers
When a verb parameter is described as some form of a key_identifier, you can present either a key token
or a key label. The key label identifies a key-token record in key storage.
Key-processing and key-storage verbs for symmetric keys

Figure 14 shows AES key-processing and key-storage verbs for fixed-length AES key tokens, and how
they relate to key parts, internal key tokens, and key storage. The Key_Generate, Key_Token_Build,
Multiple_Clear_Key_Import, Symmetric_Key_Generate, and Symmetric_Key_Import verbs create internal
fixed-length AES key tokens in your application programs. The Key_Token_Change verb modifies existing
| internal CCA AES key tokens. CCA does not have fixed-length AES external key tokens.
|
| Figure 14. Key-processing and key-storage verbs for keys in fixed-length AES key tokens
Figure 15 on page 172 shows DES key-processing and key-storage verbs and how they relate to key
parts, internal and external key tokens, and key storage. The Clear_Key_Import, Data_Key_Import,

Diversified_Key_Generate, Key_Generate, Key_Import, Key_Part_Import, Key_Token_Build,
Multiple_Clear_Key_Import, Symmetric_Key_Generate, and Symmetric_Key_Import verbs create internal
fixed-length DES key tokens in your application programs. The Prohibit_Export and Key_Token_Change
verbs modify existing internal fixed-length DES key tokens. The Data_Key_Export, Key_Export,
Key_Generate, Key_Token_Build, Prohibit_Export_Extended, Remote_Key_Export, and
Symmetric_Key_Generate verbs create external fixed-length DES key tokens in your application programs.
The Control_Vector_Translate and Key_Translate verbs modify existing external fixed-length DES key
tokens.
CCA subsystems do not reveal the clear value of enciphered keys, and do provide significant control over
encrypted keys. Simple key-distribution is addressed by the Cryptographic Node Management (CNM)
utilitys capabilities to read and write encrypted keys from and to key storage and to process key parts with
support for dual control of the key parts. Application programs can use the key-processing and key-storage
verbs to implement a key-distribution system of your design.
Use the CNM utility, Multiple_Clear_Key_Import, Key_Test, and Key_Test_Extended verbs to install AES
keys and verify key installation. Use the CNM utility, Key_Part_Import, Clear_Key_Import,
Multiple_Clear_Key_Import, Key_Test, and Key_Test_Extended verbs to install DES keys and verify key
installation.

Figure 15. Key-processing and key-storage verbs for keys in fixed-length DES key tokens
Installing and verifying symmetric keys

To keep a key secret, it can be installed as a series of key parts. Different individuals can use an
application program that loads individual DES key parts into the cryptographic facility using the
Key_Part_Import verb or the Cryptographic Node Management utility to enter a key part from a keyboard
or diskette.
DES key parts are single or double in length, based on the type of key you are accumulating. Key-parts
are exclusive-ORed as they are accumulated. Thus, knowledge of a key-part value provides no knowledge
about the final key when it is composed of more than one part. An already-entered key-part is stored
outside the cryptographic facility enciphered under the DES master-key. When all the key parts are
accumulated, the KEY-PART bit (bit 44) is turned off in the DES key's control vector.
A master-part is loaded into the new-master-key register. The key part replaces the value in the
new-master-key register, or is exclusive-ORed with the existing contents of the register. In a separate

command, you can copy the contents of the current-master-key register to the old-master-key register and
write over the current-master-key register with the contents of the new-master-key register.
The access-control point commands to load master-key parts must be individually authorized by
appropriate bits being turned on in the active role. For AES, the commands are Load First AES Master
Key Part (offset X'0125') and Combine Intermediate AES Master Key Parts (offset X'0126'). For DES, the
commands are Load First Master Key Part (offset X'0018') and Combine Master Key Parts (offset X'0019').
| Use the Key_Test and Key_Test_Extended verbs to generate a verification pattern for AES and DES keys
| in fixed-length symmetric key tokens. For variable-length symmetric key tokens, or an external TR-31 key
| block, use the Key_Test2 verb.
| Note: Starting with Release 3.10, the Key_Test_Extended verb enables you to also operate on an
| external key.
The verification pattern can then be used to determine the equivalence of another key or a key part. An
| application program can use the Key_Test, Key_Test2, and Key_Test_Extended verbs to verify the
contents of an enciphered key, or an enciphered key-part. The CNM utility also includes services to
generate and use key and key-part verification patterns. With Release 3.10, the Key_Test and
Key_Test_Extended verbs optionally allow you to adjust the parity bits of a DES key prior to computing or
verifying the key-test pattern.
| Even though the value of the key or the key part is not known, a key, a key part, or the contents of a
| master-key register can be tested to ensure that it has a correct value. Provide the verification information
| to the individual who loads the key parts for the parts that should already be loaded. If the pattern does
| not verify, instruct the individual or application not to load an additional key part or not to set the master
| key. This procedure can ensure that only valid key parts are used.
In addition to the utilities that are supplied with the hardware, you can use the Key_Part_Import verb in an
application program to load DES keys from individual key parts.
Loading of key parts into the coprocessor with the Master_Key_Process and Key_Part_Import verbs or the
| CNM utility exposes the key parts to potential copying by unauthorized processes. If this exposure is a
| concern, randomly generate DES master keys within the coprocessor, or consider distribution of other
keys using public-key cryptographic techniques.
Generating symmetric keys

A CCA cryptographic facility can generate clear keys, clear key parts, and enciphered keys or enciphered
pairs of keys. These keys are generated as follows:
Generate a clear key
| 1. For AES, use the Random_Number_Generate_Long verb with the RANDOM rule-array keyword
| and a value of 16, 24, or 32 for the random_number_length variable, depending on the desired
| key size. Use the Multiple_Clear_Key_Import or Key_Part_Import2 verb to import the cleartext key
| into an AES internal key-token enciphered under the AES master key. Use the Key_Token_Build
| or Key_Token_Build2 verb to create an internal AES key-token with the cleartext key in it.
2. For DES, use the Random_Number_Generate verb with the ODD rule-array keyword for a
single-length key, or call the Random_Number_Generate_Long verb with the ODD rule-array
keyword and a random_number_length value of 16. Use the Clear_Key_Import or the
Multiple_Clear_Key_Import verb to import a single-length cleartext key into a DES internal DATA
key-token enciphered under the DES master key. Use the Multiple_Clear_Key_Import verb to
import a double-length cleartext key into a DES internal DATA key-token enciphered under the
DES master key.
| 3. For HMAC, use the Random_Number_Generate_Long verb with the RANDOM rule-array keyword
| and a value of 10 - 256 for the random_number_length variable, depending on the desired key

| size. Use the Key_Part_Import2 verb to import the cleartext key into an HMAC internal key-token
| enciphered under the AES master key. Use the Key_Token_Build2 verb to create an internal AES
| key-token with the cleartext key in it.
Generate a clear key-part
1. For AES, use the Random_Number_Generate_Long verb with the RANDOM rule-array keyword
and a random_number_length value of 32. Repeat for as many key parts as are needed. Use the
Master_Key_Process verb to accumulate the parts of the master key into the AES
new-master-key register.
Note: Support for accumulating parts of an AES key is limited to the Master_Key_Process verb.
2. For DES, use the Random_Number_Generate_Long verb with the ODD rule-array keyword and a
random_number_length value of 8, 16, or 24 for the first clear key-part. For intermediate clear
key-parts, use the Random_Number_Generate_Long verb with the EVEN rule-array keyword and
the same random_number_length value. Use the Key_Part_Import verb to import parts of a
single-length or double-length cleartext key into an existing internal fixed-length DES key-token
that has the desired control vector. Use the Master_Key_Process verb to load 24-byte cleartext
parts into the DES new-master-key register.
Generate an enciphered key
| 1. For AES, use the Key_Generate or Key_Generate2 verb to generate a random AES key and
| return it in an internal fixed-length or variable-length AES key-token enciphered under the AES
| master key.
2. For DES, use the Key_Generate verb to generate a random DES key and return it in an internal
fixed-length DES key-token enciphered under the DES master key.
| 3. For HMAC, use the Key_Generate2 verb to generate a random HMAC key and return it in an
| internal variable-length HMAC key-token enciphered under the AES master-key.
4. To generate a single-length, double-length, or triple-length key enciphered under the MAC key
contained in a trusted block, use the Remote_Key_Export verb. See Generating keys with
Remote_Key_Export on page 187.
Generate an enciphered pair of keys
1. For AES fixed-length key tokens, all keys are DATA keys. Except for the AES master-key, there
are no AES key-encrypting keys. AES supports only the encryption and decryption of data. It is for
these reasons that the generation of a pair of enciphered AES keys is not supported.
2. For DES fixed-length key tokens, use the Key_Generate verb to generate a random DES key and
return two enciphered copies of the key in any combination of DES internal or external
fixed-length key tokens.
| 3. For AES or HMAC variable-length key tokens, use the Key_Generate2 verb to generate a random
| symmetric key and return two enciphered copies of the key in any combination of AES external or
| internal variable-length key tokens or HMAC external or internal variable-length key tokens.
Key_Generate and AES keys

When the Key_Generate verb generates an AES key, it enciphers one copy of a random number with the
256-bit AES master key, without using a control vector. The verb returns the enciphered key in an internal
fixed-length AES key-token.
Key_Generate and DES keys

When the Key_Generate verb generates a DES key, it multiply-enciphers a random number using a
control vector and either the DES master key or a DES key-encrypting key. When generating a DES
asymmetric key-type pair (see AES, DES, and HMAC key types on page 149), the verb
multiply-enciphers the random number a second time with the opposite key-type control vector. The verb
restricts the combination of control vectors used for the two encipher tasks, and also places restrictions on
the use of master-key versus EXPORTER and IMPORTER encryption key types. This is done to ensure a
secure, asymmetric key-distribution system.

The Key_Generate verb can also do the following:
v Generate one random number for a single-length key or one or two random numbers for a
double-length key.
v Update a key token or create a key token that contains the default control-vector values for the key
type. If you update a fixed-length DES key-token, you can use your own control vector to add additional
restrictions.
Note: Keys can also be diversified from key-generating keys. See Diversifying DES keys on page 177.
Before generating a key, consider how the key is to be archived and recovered if unexpected events
occur. Before using the Key_Generate verb to generate a DES key, also consider the following aspects of
key processing:
v The use of the key determines the key type and can determine whether you create a fixed-length DES
key-token with the default control-vector or with your own updated control-vector that contains
non-default restrictions.
If you use Key_Generate to update a key token, first use the Control_Vector_Generate and
Key_Token_Build verbs to create the control vector and the key token, then use the Key_Generate verb
to generate the key and update the key token.
v Where and when the key is to be used determines the form of the key, whether the verb generates one
DES key or a key-pair, and whether the verb multiply-enciphers each DES key for operational, import,
or export use. The verb multiply-enciphers each key under a key that is formed by exclusive-ORing the
control vector in the new or updated key-token with one of the following keys:
The DES master key. This is the operational (OP) key form.
An IMPORTER key-encrypting key. This is the external, importable (IM) key form.
An EXPORTER key-encrypting key. This is the external, exportable (EX) key form.
If a DES key is to be used locally, it should be enciphered in the OP key form or IM key form. An IM
key form can be saved on external media and imported when its use is required. Saving a key locally in
the IM key form ensures that the key can be used if the DES master key is changed between the time
that the key was generated and the time that it is used. This enables you to maintain the IMPORTER
key-encrypting keys in operational form and to store keys that are not needed immediately on external
media.
If a DES key is to be used remotely (sent to another cryptographic node), it should be enciphered in the
EX key form under a local EXPORTER key. At the other node, the key is imported under the paired
IMPORTER key.
v Use the SINGLE keyword for a DES key that should be single length. Use the SINGLE-R keyword for a
double-length DES key that should perform as a single-length key. This is often required when such a
key is interchanged with a non-CCA system. Use the DOUBLE keyword for a double-length key.
Because the two halves are random numbers, it is unlikely that the result of the DOUBLE keyword will
produce two halves with the same 64-bit values.
Exporting and importing DES keys, symmetric techniques

To operate on data with the same DES key at two different nodes, you must transport the key securely
between the nodes. To do this, a transport key (key-encrypting key) must be installed at both nodes. You
can also use an RSA asymmetric key as a transport key. See Exporting and importing symmetric keys,
asymmetric techniques on page 176.
A DES key that is enciphered under a key-encrypting key other than the DES master-key is called an
external key. Deciphering a DES operational key with the DES master key and enciphering the key under
a key-encrypting key is called a key-export operation. A key-export operation changes a DES operational
key to an external key and is performed in the cryptographic facility so that the clear value of the key to be
exported is not revealed.

Note: When a key that has guaranteed unique halves is being exported, the key-encrypting key must also
have guaranteed unique halves. This restriction maintains the strength of the key being exported.
Deciphering an external DES key with a key-encrypting key and enciphering the DES key under the local
DES master key is called a key-import operation. A key-import operation changes an external key to an
operational key.
The control vector for the transport key-encrypting key at the source node must specify the key as an
EXPORTER key. The control vector at the target node must specify the transport key-encrypting key as an
IMPORTER key. The key to be transported must be multiply-enciphered under an EXPORTER
key-encrypting key at the source node and multiply-deciphered under an IMPORTER key-encrypting key at
the target node. Figure 16 shows both the Key_Export and Key_Import operations. Data operation keys,
PIN keys, and key-encrypting keys can be transported in this manner. The control vector specifies what
kind of keys can be enciphered by a key-encrypting key. For more information, see Appendix C, CCA
control-vector definitions and key encryption, on page 655.
Use the Key_Export and Key_Import verbs to export and import keys with key types permitted by the
control vectors associated with the EXPORTER or IMPORTER keys. Users can use the Data_Key_Export
verb and the Data_Key_Import verb to export and import DATA keys. These verbs do not import and
export key-encrypting keys and PIN keys. Use the Remote_Key_Export verb to export keys with a variant
or a control vector contained in a trusted block using symmetric techniques (see Exporting DES keys with
Remote_Key_Export on page 184).
The DES key-encipherment processes are described in detail at Understanding DES and RSA key
encryption and decryption processes on page 671.

Operational DES key to DES imported | Operational
form of key be exported key form of key
at Node A at Node B

Key_Export Key_Import
Multiply- Multiply-
DES master key
decipher encipher DES master key

Exporter Multiply- Multiply- Importer
key-encrypting key
encipher decipher key-encrypting key

DES external
|key |

Figure 16. DES key exporting and key importing
Exporting and importing symmetric keys, asymmetric techniques

An AES key and a DES key can be distributed from one node to another node by wrapping (encrypting)
the symmetric key in the public key of the receiver (IMPORTER). CCA provides two services for wrapping
the symmetric key in the public key of the recipient:

Use the Symmetric_Key_Import verb to unwrap the transported AES or DES key using the recipient's
matching private key.
Several techniques for formatting the key to be distributed are in common use and are supported by the
verbs. The verbs support processing of default DATA keys. The Symmetric_Key_Generate and
Symmetric_Key_Import verbs can also be used to exchange a DES key-encrypting key. Use the
Remote_Key_Export verb to export keys with a variant or a control vector contained in a trusted block
using asymmetric techniques (see Exporting DES keys with Remote_Key_Export on page 184).
| Data keys can be exchanged with CCA and non-CCA implementations using two encryption/decryption
| schemes defined in the RSA PKCS #1 standard:
| v RSAES-OAEP. Two formatting methods are defined. One is defined in PKCS #1 v2.0, and the other is
| defined in PKCS #1 v2.1.
| v RSAES-PKCS1-v1_5 (formerly block-type 02 format). This formatting method is defined in PKCS #1
| v2.0.
Key-encrypting keys can be exchanged between CCA implementations using the PKA92 formatting
method. PKA92 is an OAEP formatting method.
The formatting methods are discussed in Formatting hashes and keys in public-key cryptography on
page 694.
Diversifying DES keys

CCA supports several methods for diversifying a DES key using the Diversified_Key_Generate verb.
Key-diversification is a technique often used in working with smart cards. In order to secure interactions
with a population of cards, a key-generating key is used with some data unique to a card to derive
(diversify) keys for use with that card. The data is often the card serial number or other quantity stored
on the card. The data is often public, and therefore it is very important to handle the key-generating key
with a high degree of security lest the interactions with the whole population of cards be placed in
jeopardy.
In the current implementation, several methods of diversifying a key are supported: CLR8-ENC,
TDES-ENC, TDES-DEC, SESS-XOR, TDES-XOR, TDESEMV2 and TDESEMV4. The first two methods
triple-encrypt data using the generating_key to form the diversified key. The diversified key is then
multiply-enciphered by the DES master key modified by the control vector for the output key. The
TDES-DEC method is similar except that the data is triple-decrypted.
The SESS-XOR method provides a means for modifying an existing DATA, DATAC, MAC, DATAM, or
MACVER, DATAMV single-length or double-length key. The provided data is exclusive-ORed into the clear
value of the key. This form of key diversification is specified by several of the credit card associations.
The TDES-ENC and TDES-DEC methods permit the production of either another key-generating key, or a
final key. Control-vector bits 19 22 associated with the key-generating key specify the permissible type of
final key. (See DKYGENKY in Figure 37 on page 658.) Control-vector bits 12 14 associated with the
key-generating key specify if the diversified key is a final key or another in a series of key-generating keys.
Bits 12 14 specify a counter that is decreased by one each time the Diversified_Key_Generate verb is
used to produce another key-generating key. For example, if the key-generating key that you specify has
this counter set to B'010', then you must specify the control vector for the generated_key with a
DKYGENKY key type having the counter bits set to B'001' and specifying the same final key type in bits
19 22. Use of a generating_key with bits 12 14 set to B'000' results in the creation of the final key.
Thus you can control both the number of diversifications required to reach a final key, and you can closely
control the type of the final key.
The TDESEMV2, TDESEMV4, and TDES-XOR methods also derive a key by encrypting supplied data
including a transaction counter value received from an EMV smart card. The processes are described in

detail at Visa and EMV-related smart card formats and processes on page 707. Refer to Working with
EMV smart cards on page 437 to understand the various verbs you can use to operate with EMV smart
cards.
Storing keys in AES and DES key-storage

The verbs used to create, write, read, delete, and list records in AES and DES key-storage, and the format
of the key label used to access these records, are described in Chapter 7, Key-storage mechanisms.
Note: To use AES or DES key-storage, the Compute Verification Pattern command (offset X'001D') must
first be authorized. This command is used to validate that the symmetric master-key used to
encipher keys within the key-storage file had the same value as the symmetric master-key in the
cryptographic facility when the key-storage file is opened.
Improved remote key distribution

Methods are available for securely transferring DES encryption keys to remote devices, such as
Automated Teller Machines (ATMs), PIN-entry devices, and point of sale terminals. These methods allow
application programs to support the key distribution methods defined in the following standards:
ANS X9.24-2 Retail Financial Services Symmetric Key Management Part 2: Using Asymmetric
Techniques for the Distribution of Symmetric Keys
ISO/IEC 11770-3
Information Technology Security Techniques Key Management Part 3: Mechanisms
Using Asymmetric Techniques
These methods can also be used to transfer DES keys to another cryptographic system of any type, such
as a different kind of Hardware Security Module (HSM) in an IBM or non-IBM computer server. This
change is especially important to banks, because it replaces expensive human operations with network
transactions that can be processed quickly and inexpensively. This method supports a variety of
requirements, fulfilling the new needs of the banking community while simultaneously making significant
interoperability improvements to related cryptographic key-management functions.
For the purposes of this description, the ATM scenario will be used to illustrate operation of the new
methods. Other uses of this method are also valuable.
Remote key-loading
Remote key-loading refers to the process of installing DES encryption keys into a remotely located device
from a central administrative site. This encompasses two phases of key distributions.
v Distribution of initial key encrypting keys (KEKs) to a newly installed device. A KEK is a type of DES
encryption key that is used to encrypt other keys so they can be securely transmitted over unprotected
paths.
v Distribution of operational DES keys or replacement KEKs, enciphered under a KEK currently installed
in the device.
Old remote key-loading example

Use an ATM as an example of the remote key loading process. A new ATM has none of the bank's keys
installed when it is delivered from the manufacturer. The process of getting the first key securely loaded is
difficult. This has typically been done by loading the first KEK into each ATM manually, in multiple cleartext
key parts. Using dual control for key parts, two separate people must carry key part values to the ATM,
then load each key part manually. Once inside the ATM, the key parts are combined to form the actual
KEK. In this manner, neither of the two people has the entire key, protecting the key value from disclosure
or misuse. This method is labor-intensive and error-prone, making it expensive for the banks.

New remote key-loading methods
New remote key-loading methods have been developed to overcome some of the shortcomings of the old
manual key-loading methods. These new methods define acceptable techniques using public-key
cryptography to load keys remotely. Using these new methods, banks will be able to load the initial KEKs
without sending people to the remote device. This will reduce labor costs, be more reliable, and be much
less expensive to install and change keys. The new cryptographic features added provide new methods for
the creation and use of the special key forms needed for remote key distribution of this type. In addition,
they provide ways to solve long-standing barriers to secure key exchange with non-IBM cryptographic
systems.
Once an ATM is in operation, the bank can install new keys as needed by sending them enciphered under
a KEK installed earlier. This is straightforward in concept, but the cryptographic architecture in ATMs is
often different from that of the host system sending the keys, and it is difficult to export the keys in a form
understood by the ATM. For example, cryptographic architectures often enforce key-usage restrictions in
which a key is bound to data describing limitations on how it can be used for encrypting data, for
encrypting keys, for operating on message authentication codes (MACs), and so forth. The encoding of
these restrictions and the method used to bind them to the key itself differs among cryptographic
architectures, and it is often necessary to translate the format to that understood by the target device
before a key can be transmitted. It is difficult to do this without reducing security in the system; typically it
is done by making it possible to arbitrarily change key-usage restrictions. The methods described here
provide a mechanism through which the system owner can securely control these translations, preventing
the majority of attacks that could be mounted by modifying usage restrictions.
A new data structure called a trusted block is defined to facilitate the remote key-loading methods. The
trusted block is the primary vehicle supporting these new methods.
Trusted block
The trusted block is the central data structure to support all remote key-loading functions. It provides great
power and flexibility, but this means that it must be designed and used with care in order to have a secure
system. This security is provided through several features of the design.
v Dual control is used to create a trusted block. Two separate individuals must cooperate in order to
create a usable block.
v The trusted block includes cryptographic protection that prevents any modification after it is created.
v A number of fields in the rules of a trusted block offer the ability to limit how the block is used, reducing
the risk of it being used in unintended ways or with unintended keys.
The trusted block is the enabler which requires secure approval for its creation, then enables the export or
generation of DES and TDES keys in a wide variety of forms as approved by the administrators who
created the trusted block. For added security, the trusted blocks themselves can be created on a separate
system, such as a System x server with an IBM 4764 Cryptographic Coprocessor, locked in a secure
room. The trusted block can subsequently be imported into the System z server where they will be used to
support applications.
There are two new CCA verbs to manage and use trusted blocks. They are Trusted_Block_Create
(CSNDTBC) and Remote_Key_Export (CSNDRKX). Trusted_Block_Create creates a trusted block, and
Remote_Key_Export uses a trusted block to generate or export DES keys according to the parameters in
the trusted block. The trusted block consists of a header followed by several sections. Some elements are
required, while others are optional.
Figure 17 on page 180 shows the contents of a trusted block. The elements shown in the table give an
overview of the structure and do not provide all of the details of a trusted block.

Structure version information
Modulus
Public key Exponent
Attributes
MAC key
MAC
Trusted block protection information Flags
MKVP
Activation/Expiration dates
Public key name (optional) Label
Rule 1
Rule 2
Rules Rule 3
...
Rule N
Data defined and understood

Application defined data only by the application using the
trusted block
Figure 17. Overview of trusted block contents
Here is a brief description of the elements that are depicted.
Structure version information - This identifies the version of the trusted block structure. It is included so
that code can differentiate between this trusted block layout and others that could be developed in the
future.
Public key - This contains the RSA public key and its attributes. For distribution of keys to a remote ATM,
this will be the root certification key for the ATM vendor, and it will be used to verify the signature on
public-key certificates for specific individual ATMs. In this case, the trusted block will also contain rules that
will be used to generate or export symmetric keys for the ATMs. It is also possible for the trusted block to
be used simply as a trusted public key container, and in this case the public key in the block will be used
in general-purpose cryptographic functions such as digital signature verification. The public key attributes
contain information on key usage restrictions. This is used to securely control what operations will be
permitted to use the public key. If desired, the public key can be restricted to use for only digital signature
operations, or for only key-management operations.
Trusted block protection information - This section contains information that is used to protect the
trusted block contents against modification. According to the method in ISO 16609, a CBC-mode MAC is
calculated over the trusted block using a randomly-generated Triple-DES key, and the MAC key itself is
encrypted and embedded in the block. For the internal form of the block, the MAC key is encrypted with a
randomly chosen fixed-value variant of the PKA master key. For the external form, the MAC key is
encrypted with a fixed variant of a key-encrypting key. The MKVP field contains the master-key verification

pattern for the PKA master key that was used, and is filled with binary zeros if the trusted block is in
external format. Various flag fields contain the following boolean flags.
v Active flag - Contained within the flags field of the required trusted block information section, this flag
indicates whether the trusted block is active and ready for use by other verbs. Combined with the use of
two separate access-control points, the active flag is used to enforce dual control over creation of the
block. A person whose active role is authorized to create a trusted block in inactive form creates the
block and defines its parameters. An inactive trusted block can only be used to make it active. A person
whose active role is authorized to activate an inactive trusted block must approve the block by changing
its status to active. See Figure 19 on page 184. The Remote_Key_Export verb can only use an internal
active trusted block to generate or export DES keys according to the parameters defined in the trusted
block.
v Date checking flag - Contained within the optional activation and expiration date subsection of the
required trusted block information subsection, this flag indicates whether the coprocessor checks the
activation and expiration dates for the trusted block. If the date checking flag is on, the coprocessor
compares the activation and expiration dates in the optional subsection to the coprocessor internal real
time clock, and processing terminates if either date is out of range. If this flag is off or the activation and
expiration dates subsection is not defined, the device does no date checking. If this flag if off and the
activation and expiration dates subsection is defined, date checking can still be performed outside of the
device if required. The date checking flag enables use of the trusted block in systems where the
coprocessor clock is not set.
Trusted block name - This field optionally contains a text string that is a name (key label) for the trusted
block. It is included in the block for use by an external system such as a host computer, and not by the
card itself. In System z, the label can be checked by RACF to determine if use of the block is authorized.
It is possible to disable use of trusted blocks that have been compromised or need to be removed from
use for other reasons by publishing a revocation list containing the key names for the blocks that must not
be used. Code in the host system could check each trusted block before it is used in the cryptographic
coprocessor, to ensure that the name from that block is not in the revocation list.
Expiration and activation dates - The trusted block can optionally contain an expiration date and an
activation date. The activation date is the first day on which the block can be used, and the expiration date
is the last day when the block can be used. If these dates are present, the date checking flag in the
trusted block will indicate whether the coprocessor should check the dates using its internal real-time
clock. In the case of a system that does set the coprocessor clock, checking would have to be performed
by an application program before using the trusted block. This is not quite as secure, but it is still valuable,
and storing the dates in the block itself is preferable to making the application store it somewhere else and
maintain the association between the separate trusted block and activation and expiration dates.
Application-defined data - The trusted block can hold data defined and understood only by the host
application program. This data is included in the protected contents of the trusted block, but it is not used
or examined in any way by the coprocessor. By including its own data in the trusted block, an application
can guarantee that the data is not changed in any way, because it is protected in the same way as the
other trusted block contents.
Rules - A variable number of rules can be included in the block. Each rule contains information on how to
generate or export a symmetric key, including values for variants to be used in order to provide keys in the
formats expected by systems with differing cryptographic architectures. Uses of the rules are described as
part of the sections covering key generation and export using the Remote_Key_Export verb. The table
below summarizes the required and optional values that are part of each rule.

Field name Required field Description
Rule ID Yes Specifies the 8-character name of the rule.
Operation Yes Indicates whether this rule generates a new key or exports an existing
key.
Generated key length Yes Specifies the length of the key to be generated.
Key-check algorithm ID Yes Specifies which algorithm to use to compute the optional key-check value
(KCV). Options are:
v No KCV
v Encrypt zeros with the key
v Compute MDC-2 hash of the key
Symmetric-encrypted Yes Specifies the format of the required DES-encrypted key output. Options
output format are:
v Fixed-length DES key-token
v Fixed-length RKX key-token
Asymmetric-encrypted Yes Specifies the format of the optional asymmetric-encrypted key output (key
output format is encrypted with RSA). Options are:
v No asymmetric-encrypted key output
v Encrypt in PKCS-1.2 format
v Encrypt in RSA-OAEP format
Transport-key variant No Specifies the variant to apply to the transport key before it is used to
encrypt the key being generated or exported.
Export key CV No Specifies the CCA control vector to apply to the transport key before it is
used to encrypt the key being generated or exported. The CV defines
permitted uses for the exported key.
Export key length limits No Defines the minimum and maximum lengths of the key that can be
exported with this rule.
Output key variant No Specifies the variant to apply to the generated or exported key before it
is encrypted.
Export-key rule No Specifies the rule ID for the rule that must have been used to generate
reference the key being exported, if that key is an RKX key-token.
Export-key CV No Defines masks and templates to use to restrict the possible CV values
restrictions that a source key can have when being exported with RKX. Only applies
if the key is a fixed-length DES key-token. This can control the types of
CCA keys that can be processed using the rule.
Export-key label No Specifies the key label to be used as a mask to determine if a source
template key can be exported. A key label is a name used to identify a key. The
rule can optionally contain a key label template, which will be matched
against the host-supplied key label, using a wildcard (*) so that the
template can match a set of related key labels. The operation will only be
accepted if the supplied label matches the wildcard template in the rule.
Changes to the CCA API

The following changes have been made to the CCA API to support remote key-loading using trusted
blocks:
v A new Trusted_Block_Create (CSNDTBC) verb has been developed to securely create trusted blocks
under dual control.
v A new Remote_Key_Export (CSNDRKX) verb has been developed to generate or export DES and
Triple-DES keys under control of the rules contained in a trusted block.

v The Digital_Signature_Verify (CSNDDSV) verb has been enhanced so that, in addition to verifying
ordinary CCA RSA keys, it can use the RSA public key contained in a trusted block to verify digital
signatures.
v The PKA_Key_Import (CSNDPKI) verb has been enhanced so it can import an RSA key into the CCA
domain. In addition, the verb can import an external format trusted block into an internal format trusted
block, ready to be used in the local system.
v The PKA_Key_Token_Change (CSNDKTC) verb has been enhanced so that it can update trusted
blocks to the current PKA master key when the master key is changed. A trusted block contains an
embedded MAC key enciphered under the PKA master key. When the PKA master key is changed, the
outdated MAC key and the trusted block itself need to be updated to reflect the current PKA master key.
v The MAC_Generate (CSNBMGN) and MAC_Verify (CSNBMVR) verbs have been enhanced to add ISO
16609 Triple-DES (TDES) MAC support in which the text is CBC-TDES encrypted using a double-length
key and the MAC is extracted from the last block.
v The DES key-storage verbs support DES and Triple-DES keys that are either generated or exported
under control of the rules contained in a trusted block.
v The PKA key-storage verbs support trusted blocks.
The RKX key-token

CCA normally uses key tokens that are designed solely for the purposes of protecting the key value and
carrying metadata associated with the key to control its use by CCA cryptographic functions. The remote
key-loading design introduces a new type of key token called an RKX key-token. The purpose of this token
is somewhat different, and its use is connected directly with the Remote_Key_Export verb added to CCA
as part of the remote key-loading design.
The RKX key-token uses a special structure that binds the token to a specific trusted block, and enables
sequences of CSNDRKX calls to be bound together as if they were an atomic operation. This enables a
series of related key-management operations to be performed using the Remote_Key_Export verb. These
capabilities are made possible by incorporating the following three features into the RKX key-token
structure:
v The key is enciphered using a randomly-derived, fixed variant of the MAC key that is in the trusted
block. As a result, the enciphered key is protected against disclosure because the trusted block MAC
key is itself protected at all times.
v The structure includes the rule ID contained in the trusted block rule that was used to create the key. A
subsequent call to the CSNDRKX verb can use this key with a trusted block rule that references this
rule ID, effectively chaining use of the two rules together securely.
v A MAC is computed over the encrypted key and the rule ID, using the same MAC key that is used to
protect the trusted block itself. This MAC guarantees that the key and the rule ID cannot be modified
without detection, providing integrity and binding the rule ID to the key itself. In addition, the MAC will
only verify if the RKX key-token is used with the same trusted block that created the token, thus binding
the key to that specific trusted block.
The figure below shows a simplified conceptual view of the RKX key-token structure.

Enciphered key
MAC covers these areas
Rule ID
MAC
Figure 18. Simplified RKX key-token structure
Using trusted blocks

The following examples illustrate how trusted blocks are used with the new and enhanced CCA verbs.
Creating a trusted block

The figure below illustrates the steps used to create a trusted block.
Administrator 1 Administrator 2
TBC External trusted block TBC External trusted block
Inactive Active
Figure 19. Trusted block creation
This shows the two-step process which requires action by two different administrators in order to create an
external trusted block that can be used to import an internal trusted block that can be used to generate or
export DES keys according to the parameters defined in the trusted block. Trusted blocks are structures
that could be abused to circumvent security if an attacker could create them with undesirable settings, and
the requirement for two separate and properly authorized people makes it impossible for a single
dishonest employee to create such a block. A trusted block cannot be used for any operations until it is in
the active state. Any number of trusted blocks can be created in order to meet different needs of
application programs.
Exporting DES keys with Remote_Key_Export

The figure below shows the process for using a trusted block in order to export a DES or TDES key. This
representation is at a very high level in order to illustrate the basic flow.

Internal trusted
block
Active
RKX
Transport key
Validate
trusted block
Certificate
Validate parameter
against rules in
trusted block
Generate random key K

based on rules in trusted
block.
Apply rules in trusted block

to build output key value
from key K
Computer key check value

(KCV) on keyK if specified
by rule.
Apply rules to encrypt key

value with transport key
and optionally with public
key in certificate.
DES RSA-encrypted key Key check value

encrypted key (optional) (optional)
Figure 20. Exporting DES keys using a trusted block
The CSNDRKX verb is called with the following main parameters:

v An internal trusted block, in the active state, defines how the export operation is to be processed,
including values to be used for things such as variants to apply to the keys.
v The key to be exported, shown above as the source key. The source key takes one of two forms:
1. A fixed-length DES key-token
2. A fixed-length RKX key-token

v A key-encrypting key, shown in the figure as the imported key. This is used only if the source key is an
external fixed-length DES key-token, encrypted under a KEK. In this case, the KEK is the key needed to
obtain the cleartext value of the source key.
v A transport key, either an exporter KEK or an RKX key-token, used to encrypt the key being exported.
v An optional public-key certificate which, if included, contains the certified public key for a specific ATM.
The certificate is signed with the ATM vendor's private key, and its corresponding public key must be
contained in the trusted block so that this certificate can be validated. The public key contained in the
certificate can be used to encrypt the exported key.
The processing steps are simple at a high level, but there are many options and significant complexity in
the details.
v The trusted block itself is validated. This includes several types of validation.
Cryptographic validation using the MAC that is embedded in the block, in which the MAC key is
decrypted using the coprocessor's DES master key, and the MAC is then verified using that key. This
verifies that the block has not been corrupted or tampered, and it also verifies that the block is for
use with this coprocessor because it will only succeed if the master key is correct.
Consistency checking and field validation, in which the validity of the structure itself is checked, and
all values are verified to be within defined ranges.
Fields in the trusted block are checked to see if all requirements are met for use of this trusted block.
One check which is always required is to ensure that the trusted block is in the active state before
continuing. Another check, which is optional based on the contents of the trusted block, is to ensure
the operation is currently allowed by comparing the date of the coprocessor real-time clock to the
activation and expiration dates defined in the trusted block.
v Input parameters to the CSNDRKX verb are validated against rules defined for them within the trusted
block. For example:
The rule can restrict the length of the DES key to be exported.
The rule can restrict the control vector values for the DES key to be exported, so that only certain
key types can be exported with that rule.
v After the source key is decrypted, the rules embedded in the trusted block are then used to modify that
key to produce the desired output key value. For example, the trusted block can contain a variant to be
exclusive-ORed with the source key before that key is encrypted. Many non-IBM cryptographic systems
use variants to provide key separation to restrict a key from improper use.
v A key-check value (KCV) can be optionally computed for the source key. If the KCV is computed, the
trusted block allows for one of two key-check algorithms to be used:
1. Encrypting binary zeros with the key
2. Computing an MDC-2 hash of the key
The KCV is returned as an output of the CSNDRKX function.
v The source key, which could possibly be modified with a variant according to the rules in the trusted
block, is enciphered with the transport key. The rules can specify that the key be created in one of two
formats: (1) a fixed-length DES key-token, or (2) the new RKX key-token, described earlier. With proper
selection of rule options, the fixed-length DES key-token can create keys that can be used in non-CCA
systems. The key value can be extracted from the DES key-token resulting in a generic encrypted key,
with variants and other options as defined in the rule.
Two optional fields in the trusted block might modify the transport key before it is used to encrypt the
source key:
The trusted block can contain a DES control vector (CV) to be exclusive-ORed with the transport key
before that key is used to encrypt the source key. This exclusive-OR process is the standard way
CCA applies a CV to a DES key.
In addition to the CV described above, the trusted block can also contain a variant to be
exclusive-ORed with the transport key prior to its use.
If a variant and CV are both present in the trusted block, the variant is applied first, then the CV.

v The source key can optionally be encrypted with the RSA public key identified by the certificate
parameter of the CSNDRKX verb, in addition to encrypting it with the transport key as described above.
These two encrypted versions of the source key are provided as separate outputs of the CSNDRKX
verb. The trusted block permits a choice of encrypting the key in either PKCS-1.2 format or
PKCSOAEP format.
Generating keys with Remote_Key_Export

The figure below shows the process for using a trusted block to generate a new DES or TDES key. This
representation is at a very high level in order to illustrate the basic flow.

Internal trusted
block
Active
RKX
Transport key
Validate
trusted block
Certificate
Validate parameter
against rules in
trusted block
Generate random key K

based on rules in trusted
block.
Apply rules in trusted block

to build output key value
from key K
Computer key check value

(KCV) on keyK if specified
by rule.
Apply rules to encrypt key

value with transport key
and optionally with public
key in certificate.
DES RSA-encrypted key Key check value

encrypted key (optional) (optional)
Figure 21. Generating DES keys using a trusted block
For key generation, the CSNDRKX verb is called with the following main parameters:
v A trusted block, in the internal active state, which defines how the key generation operation is to be
processed, including values to be used for things such as variants to apply to the keys. The generated
key is encrypted by a variant of the MAC key contained in a trusted block.
v An optional public-key certificate which, if included, contains the certified public key for a specific ATM.
The certificate is signed with the ATM vendor's private key, and its corresponding public key must be

contained in the trusted block so that this certificate can be validated. The public key contained in the
certificate can be used to encrypt the generated key.
The processing steps are simple at a high level, but there are many options and significant complexity in
the details. Most of the processing steps are the same as those described above for key export.
Therefore, only those processing steps that differ are described below in detail.
v Validation of the trusted block and input parameters is done as described for export above.
v The DES or TDES key to be returned by the CSNDRKX verb is randomly generated. The trusted block
indicates the length for the generated key.
v The output key value is optionally modified by a variant as described above for export, and then
encrypted in the same way as for export using the transport key and optionally the public key in the
certificate parameter.
v The key check value (KCV) is optionally computed for the generated key using the same method as for
an exported key.
Remote key distribution scenario

The new and modified CCA functions for remote key loading are used together to create trusted blocks,
and then generate or export keys under the control of those trusted blocks. The figure below summarizes
the flow of the CCA functions to show how they are used:
Trusted block parameters

Transport key TBC Trusted block (external, inactive)
Option=INACTIVE
Trusted block
Transport key TBC Trusted block (external, active)
Option=ACTIVATE
Trusted block Trusted block (internal, active)

PKI
Transport key
Trusted block
Transport key DES-encrypted key
Source key RKX Asymmetric-encrypted key
Certificate Key check value
Importer key (if needed)
Possible to do one of these

if key format is an RKX token
Trusted block
Transport key DES-encrypted key
Source key RKX Asymmetric-encrypted key
Certificate Key check value
Importer key (if needed)
Figure 22. Typical flow of verbs for remote key export

Usage example
The scenario described below shows how these functions might be combined in a real-life application to
distribute a key to an ATM and keep a copy for local use. Some of the terminology used reflects typical
terms used in ATM networks. The example illustrates a fairly complex real-world key distribution scenario,
in which the following values are produced.
v A TMK (Terminal Master Key), which is the root KEK used by the ATM to exchange other keys, is
produced in two forms: (1) encrypted under the ATM public key, so it can be sent to the ATM, and (2) as
an RKX key-token that will be used in subsequent calls to the CSNDRKX verb to produce other keys.
v A key-encrypting key KEK1 that is encrypted under the TMK in a form that can be understood by the
ATM.
v A PIN-encrypting key PINKEY be used by the ATM to encrypt customer-entered PINs and by the host to
verify those PINs. The PINKEY is produced in two forms: (1) encrypted under KEK1 in a form that can
be understood by the ATM, and (2) as an internal CCA DES key-token with the proper PIN-key CV,
encrypted under the CCA DES master key and suitable for use with the coprocessor.
It takes seven steps to produce these keys using the CSNDRKX verb. These steps use a combination of
five rules contained in a single trusted block. The rules in this example are referred to as GENERAT1,
GENERAT2, EXPORT1, EXPORT2, and EXPORT3.
1. Use CSNDRKX with rule ID "GENERAT1" to generate a TMK for use with the ATM. The key will be
output in two forms:
a. ePu(TMK): Encrypted under the ATM public key, supplied in the certificate parameter, CERT
b. RKX(TMK): As an RKX key-token, suitable for subsequent input to the CSNDRKX verb
2. Use CSNDRKX with rule ID "GENERAT2" to generate a key-encrypting key (KEK1) as an RKX
key-token, RKX(KEK1)
3. Use CSNDRKX with rule ID "GENERAT2" to generate a PIN key (PINKEY) as an RKX key-token:
RKX(PINKEY).
4. Use CSNDRKX with rule ID "EXPORT1 " to export KEK1 encrypted under the TMK as a fixed-length
DES key-token using a variant of zeros applied to the TMK. This produces eTMK(KEK1).
5. Use CSNDRKX with rule ID "EXPORT2 " to export PINKEY encrypted under KEK1 as a key token
using a variant of zeros applied to KEK1. This produces eKEK1(PINKEY).
6. Use CSNDRKX with rule ID "EXPORT3 " to export PINKEY under KEK2, an existing CCA
key-encrypting key on the local server. This produces eKEK2(PINKEY), with the control vector for a PIN
key.
7. Use CSNBKIM to import the PINKEY produced in step 6 into the local system as an operational key.
This produces eMK(PINKEY), a copy of the key encrypted under the local DES master key (MK) and
ready for use by CCA PIN API functions.
Rule section samples

Samples of the GENERAT1, GENERAT2, EXPORT1, EXPORT2, and EXPORT3 rule sections are listed in
the following tables.
Note: The entire trusted block is not shown.
Following each rule section sample is a table that shows the most important inputs and outputs to the
CSNDRKX verb.

Table 25. Sample rule section GENERAT1
Offset Length
(bytes) (bytes) Value Description
000 001 X'12' Trusted block rule section identifier.
001 001 X'00' Section version number.
002 002 X'30' Section length in bytes.
004 008 "GENERAT1" Rule ID (in ASCII).
012 004 X'00000000' Flags (set to generate new key).
016 001 X'10' Generated key length in bytes.
017 001 X'00' Key check algorithm identifier (set to not compute a key check value).
018 001 X'00' Symmetric encrypted output key format flag (set to return an RKX
key-token encrypted under a variant of the MAC key).
019 001 X'01' Asymmetric encrypted output key format flag (set to output in PKCS-1.2
format).
020 028 Beginning of rule section subsections (TLV objects).
| Subsection X'0003'
000 002 X'0003' Common export key parameters TLV object subsection tag.
002 002 X'001C' Subsection length in bytes.
004 001 X'00' Subsection version number.
005 002 X'0000' Reserved.
007 001 X'00' Flags (reserved).
008 001 X'00' Export key minimum length in bytes. Not applicable for key generation.
009 001 X'00' Export key maximum length in bytes. Not applicable for key generation.
010 001 X'10' Output key variant length in bytes.
011 016 X'A5A5A5A5' Output key variant. Exclusive-OR this variant into the cleartext value of the
X'A5A5A5A5' output key.
X'5A5A5A5A'
X'5A5A5A5A'
27 001 X'00' CV length in bytes.
28 000 NULL CV. Not applicable for generate.
Table 26. Verb inputs and outputs for sample rule GENERAT1
CSNDRKX inputs CSNDRKX outputs
trusted_block_identifier (contains GENERAT1 rule) key_check_value (NONE)
certificate (CERT[Pu]) asym_encrypted_key [ePu(TMK)]
certificate_parms sym_encrypted_key_identifier [RKX(TMK)]
rule_id (ASCII "GENERAT1")
importer_key_identifier (NULL)
source_key_identifier (NULL)
extra_data
key_check_parameters

Table 27. Sample rule section GENERAT2
Offset Length
004 008 "GENERAT2" Rule ID (in ASCII).
012 004 X'00000000' Flags (set to generate new key).
018 001 X'00' Symmetric encrypted output key format flag (set to return an RKX
key-token encrypted under a variant of the MAC key).
019 001 X'00' Asymmetric encrypted output key format flag (set to not return an
asymmetric key).
020 028 Beginning of rule section subsections (TLV objects).
005 002 X'0000' Reserved.
008 001 X'00' Export key minimum length in bytes. Not applicable for key generation.
009 001 X'00' Export key maximum length in bytes. Not applicable for key generation.
011 016 X'FEDCBA98' Output key variant. Exclusive-OR this variant into the cleartext value of the
X'76543210' output key.
X'01234567'
X'89ABCDEF'
28 000 NULL CV. Not applicable for generate.
Table 28. Verb inputs and outputs for sample rule GENERAT2
trusted_block_identifier (contains GENERAT2 rule) First call:
certificate (NULL) key_check_value (NONE)
certificate_parms sym_encrypted_key_identifier [RKX(KEK1)]
rule_id (ASCII "GENERAT2") Second call
importer_key_identifier (NULL) key_check_value (NONE)
source_key_identifier (NULL) sym_encrypted_key_identifier [RKX(PINKEY)]
extra_data

Table 29. Sample rule section EXPORT1
Offset Length
004 008 "EXPORT1" Rule ID (in ASCII).
012 004 X'00000001' Flags (set to export existing key).
018 001 X'01' Symmetric encrypted output key format flag (set to return a fixed-length
DES key-token encrypted under a transport key).
asymmetric key).
020 024+ Beginning of rule section subsections (TLV objects).
014+
012+ 014
000 002 X'0001' Transport key variant TLV object subsection tag.
002 002 X'0018' Subsection length in bytes.
005 002 X'0000' Reserved.
007 001 X'10' Length of variant field in bytes.
008 016 X'00000000' Transport key variant.
X'00000000'
X'00000000'
X'00000000'
000 002 X'0002' Transport key rule reference TLV object subsection tag.
002 002 X'000E' Subsection length in bytes.
005 001 X'00' Reserved.
006 008 "GENERAT1" Rule ID for the rule that must have been used to create the transport key.
005 002 X'0000' Reserved.
008 001 X'08' Export key minimum length in bytes.
009 001 X'10' Export key maximum length in bytes.
012 000 NULL.

Table 29. Sample rule section EXPORT1 (continued)
Offset Length
000 002 X'0004' Source key rule reference TLV object subsection tag.
005 002 X'0000' Reserved.
006 008 "GENERAT2" Rule ID for the rule that must have been used to create the source key.
Table 30. Verb inputs and outputs for sample rule EXPORT1
trusted_block_identifier (contains EXPORT1 rule) key_check_value (NONE)
certificate (NULL) sym_encrypted_key_identifier [CCA(eTMK(KEK1))]
certificate_parms
rule_id (ASCII "EXPORT1")
source_key_identifier [RKX(KEK1)]
extra_data
transport_key_identifier [RKX(TMK)]

Offset Length
012 004 X'00000000' Flags (set to export new key).
asymmetric key).
020 024+ Beginning of rule section subsections (TLV objects).
014+
012+ 014
000 002 X'0001' Transport key variant TLV object subsection tag.
002 002 X'0018' Subsection length in bytes.
005 002 X'0000' Reserved.

Table 31. Sample rule section EXPORT2 (continued)
Offset Length
007 001 X'10' Length of variant field in bytes.
008 016 X'00000000' Transport key variant.
X'00000000'
X'00000000'
X'00000000'
000 002 X'0002' Transport key rule reference TLV object subsection tag.
005 001 X'00' Reserved.
006 001 "GENERAT2" Rule ID for the rule that must have been used to create the transport key.
005 002 X'0000' Reserved.
012 000 NULL.
005 001 X'00' Reserved.
certificate (NULL) sym_encrypted_key_identifier [CCA(eKEK1(PINKEY))]
certificate_parms
source_key_identifier [RKX(PINKEY)]
extra_data
transport_key_identifier [RKX(KEK1)]

Offset Length
002 002 X'3E' Section length in bytes.
012 004 X'00000001' Flags (set to export existing key).
asymmetric key).
020 028+ 014 Beginning of rule section subsections (TLV objects).
005 002 X'0000' Reserved.
012 016 X'00224200' CV (PINVER control vector). Exclusive-OR this CV with the cleartext
X'03410000' transport key.
X'00224200'
X'03210000'

certificate (NULL) sym_encrypted_key [CCA(eKEK2(PINKEY))]
certificate_parms
source_key_identifier [RKX(PINKEY)]
extra_data
transport_key_identifier [CCA(KEK2)]
Remote key distribution benefits

The CCA Support Program supports remote key-loading. This solves one new problem, and one
long-standing problem, and allows the distribution of initial keys to ATMs and other remote devices
securely using public-key techniques, in a flexible way that can support a wide variety of different
cryptographic architectures. This support also makes it far easier and far more secure to send keys to
non-CCA systems when those keys are encrypted with a Triple-DES key-encrypting key, thus making it
easier for customers to develop more secure systems.
Security precautions
Be sure to refer to Appendix H, Observations on secure operations, on page 725.
In order to maintain a secure cryptographic environment, each cryptographic node must be audited on a
regular basis. This audit should be aimed at preventing inadvertent and malicious breaches of security.
Some of the things that should be audited are listed below:
v The same transport key should not be used as both an EXPORTER key and IMPORTER key on any
given cryptographic node. This would destroy the asymmetrical properties of the transport key.
v Enablement of the Encipher Under Master Key command (offset X'00C3') should be avoided.
v The Key_Part_Import verb can be used to enter key-encrypting keys and DES data keys into the
system. This verb provides for split knowledge (dual control) of keys by ensuring that no one person
knows the true value of a key. Each person enters part of a key and the actual key is not assembled
until the last key part is used. Neither the key nor the partial results of the key assembly appear in the
clear outside of the secure hardware. Note, however, that the clear key parts have passed through the
general purpose computer. Consider accumulating the parts on different machines or using public-key
cryptography in the key-distribution scheme.
v Be careful that the public key used in the Symmetric_Key_Generate and Symmetric_Key_Export verbs
is associated with a legitimate receiver of the exported keys.
AES, DES, and HMAC key-management verbs

Clear_Key_Import (CSNBCKI)
Use the Clear_Key_Import verb to encipher a clear, single-length DES key under a DES master-key. The
resulting key is a DES DATA key because the service requires that the resulting internal key-token have a
DATA control-vector. You can use this verb to create an internal fixed-length key-token from a null
fixed-length DES key-token, or you can update an existing internal fixed-length DES DATA key-token with
the enciphered value of the clear key. (You can create other types of DES keys from clear-key information
using the Key_Part_Import verb.)
Note: If the clear-key value does not have odd parity in the low-order bit of each byte, the reason_code
parameter presents a warning.
See also the Multiple_Clear_Key_Import verb in Multiple_Clear_Key_Import (CSNBCKM) on page 301.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBCKI
clear_key Input String 8 bytes
target_key_identifier In/Output String 64 bytes
Parameters
clear_key
The clear_key parameter is a pointer to a string variable containing the clear value of the single-length
DES key being imported as a DATA key. The key is to be enciphered under the DES master-key.
Although not required, the low-order bit in each byte should provide odd parity for the other bits in the
byte.
The target_key_identifier parameter is a pointer to a string variable. If the input key-token in
application storage or DES key-storage is null, then a default internal fixed-length DES DATA

key-token containing the encrypted clear-key replaces the null token. Otherwise, the preexisting token
must be an internal fixed-length DES DATA key-token and the encrypted clear-key replaces the
existing key-value.
Required commands
The Clear_Key_Import verb requires the Encipher Under Master Key command (offset X'00C3') to be
Note: A role with offset X'00C3' enabled can also use the Multiple_Clear_Key_Import verb with the DES
algorithm

Control_Vector_Generate (CSNBCVG)
Use the Control_Vector_Generate verb to build a DES control vector from keywords specified by the
key_type and rule_array parameters. For descriptions of the keywords and for valid combinations of these
keywords, see Figure 10 on page 161, AES, DES, and HMAC key types on page 149, and DES key
usage restrictions on page 160. You might achieve added security by using optional keywords, or in some
cases required keywords, supplied in the rule_array variable.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBCVG
key_type Input String 8 bytes
reserved Input String null pointer or XL8'00' variable
control_vector Output String 16 bytes
Parameters
key_type
The key_type parameter is a pointer to a string variable containing a keyword for the DES key-type.
The keyword is 8 bytes in length, left-aligned, and padded on the right with space characters. Supply a
keyword from the following list:

CIPHER DATAM MAC
CVARDEC DATAMV MACVER
CVARENC DECIPHER OKEYXLAT
CVARPINE DKYGENKY OPINENC
CVARXCVL ENCIPHER PINGEN
CVARXCVR EXPORTER PINVER
DATA IKEYXLAT KEYGENKY1
DATAC IMPORTER SECMSG2
IPINENC
1. CLR8-ENC must be coded in the rule array when the KEYGENKY key-type is coded.
2. SMKEY or SMPIN must be coded in the rule array when the SECMSG key-type is coded.
For definitions of these keywords, see Control vectors, key types, key-usage, and key-management
restrictions on page 147.
rule_array_count
in the rule_array variable.
rule_array
characters. For the valid combinations of keywords for the key type and the rule array, see Figure 10
on page 161. The rule_array keywords are shown below:
| AMEX-CSC DKYL2 EXPORT NOOFFSET

| ANSIX9.92 DKYL3 GBP-PIN NOT31XPT
ANY2 DKYL4 GBP-PINO NOT-KEK2
ANY-MAC DKYL5 IBM-PIN OPEX
CLR8-ENC1 DKYL6 IBM-PINO OPIM
CPINENC DKYL7 IMEX PIN2
CPINGEN DMAC IMIM REFORMAT
CPINGENA DMKEY IMPORT SINGLE
| CVVKEY-A DMPIN INBK-PIN SMKEY
| CVVKEY-B DMV KEY-PART SMPIN
| DALL DOUBLE KEYLN8 T31XPTOK
DATA2 DPVR KEYLN16 TRANSLAT
DDATA ENH-ONLY LMTD-KEK2 UKPT
DEXP EPINGEN MIXED VISA-PVV
DIMP EPINGENA NO-SPEC XLATE
DKYL0 EPINVER NO-XPORT XPORT-OK
DKYL1 EXEX
1. CLR8-ENC must be coded when the KEYGENKY key-type is coded.

2. The meaning of this keyword has been discontinued. It is allowed for backward compatibility reasons only.
Notes:
1. Figure 37 on page 658 shows which control-vector bits are set for each of these keywords.
2. Most but not all key types have a default control vector. These default control vectors are shown in
Table 162 on page 657. With the exception of DATA keys, a default control vector is built whenever
no rule-array keywords are specified.
3. Figure 10 on page 161 shows the default keywords for each key type. For example, looking at
Figure 10 you can see the default rule-array keywords for a MAC or MACVER key are ANY-MAC,
SINGLE, and XPORT-OK.
4. The DATA key type has more than one default. The following describes how to build each default
DATA control vector (as shown in Table 162 on page 657):
v For internal single-length, specify no rule-array keywords, or specify SINGLE or KEYLN8.
v For internal double-length, specify DOUBLE, KEYLN16, or MIXED.
v For external single-length, use the Key_Token_Build verb and specify rule-array keywords of
EXTERNAL, DES, and either SINGLE, or KEYLN8.
v For external double-length, use the Key_Token_Build verb, specify rule-array keywords of
EXTERNAL, DES, and either DOUBLE, KEYLN16, or MIXED.
reserved
This reserved parameter is a pointer to a string variable. The parameter must either be a null pointer,
or a pointer to a variable of eight bytes of X'00'.
control_vector
The control_vector parameter is a pointer to a string variable containing the control vector returned by
the verb.
Required commands
None

Control_Vector_Translate (CSNBCVT)
Use the Control_Vector_Translate verb to change the control vector used to encipher a key contained in a
fixed-length DES key-token. See Changing control vectors with the Control_Vector_Translate verb on
page 667 for additional information about this verb.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v This verb does not support version X'10' external DES key tokens (RKX key tokens).
Format
CSNBCVT
KEK_key_identifier Input String 64 bytes
source_key_token Input String 64 bytes
array_key_left_identifier Input String 64 bytes
mask_array_left Input String 56 bytes
array_key_right_identifier Input String 64 bytes
mask_array_right Input String 56 bytes
target_key_token In/Output String 64 bytes
Parameters
KEK_key_identifier
The KEK_key_identifier parameter is a pointer to a string variable containing an operational
fixed-length DES key-token or the key label of an operational fixed-length DES key-token record
containing the key-encrypting key. The control vector in the key token must specify the key type
IMPORTER, EXPORTER, IKEYXLAT, or OKEYXLAT.

source_key_token
The source_key_token parameter is a pointer to a string variable containing the external fixed-length
DES key-token with the key and control vector to be processed.
array_key_left_identifier
The array_key_left_identifier parameter is a pointer to a string variable containing an operational
fixed-length DES key-token or a key label of an operational fixed-length DES key-token record that
deciphers the left mask-array. The key token must contain a control vector specifying a CVARXCVL
key-type. The CVARXCVL key must be single length.
mask_array_left
The mask_array_left parameter is a pointer to a string variable containing the mask array enciphered
under the left-array key.
array_key_right_identifier
The array_key_right_identifier parameter is a pointer to a string variable containing an operational
fixed-length DES key-token or the key label of an operational fixed-length DES key-token record that
deciphers the right mask-array. The key token must contain a control vector specifying a CVARXCVR
key-type. The CVARXCVR key must be single length.
mask_array_right
The mask_array_right parameter is a pointer to a string variable containing the mask array enciphered
under the right-array key.
rule_array_count
rule_array
Keyword Meaning
Parity adjustment (one, optional)
ADJUST Ensures that all target-key bytes have odd parity. This is the default.
NOADJUST Prevents the parity of the target key from being altered.
Key half processing mode (one, optional)
LEFT Causes an 8-byte source key, or the left half of a 16-byte source key, to be processed with the
result placed into both halves of the target key. This is the default.
RIGHT Causes the right half of a 16-byte source key to be processed with the result placed into only
the right half of the target key. The left half is copied unchanged (still encrypted) from the source
key into the left half of the target key.
BOTH Causes both halves of a 16-byte source key to be processed with the result placed into
corresponding halves of the target key. When you use the BOTH keyword, the mask array must
be able to validate the translation of both halves.
SINGLE Causes the left half of the source key to be processed with the result placed into only the left
half of the target. The right half of the target key is unchanged.
target_key_token
The target_key_token parameter is a pointer to a string variable containing an external fixed-length
DES key-token with the new control vector. This key token contains the key halves with the new
control vector.
Required commands
The Control_Vector_Translate verb requires the Translate Control Vector command (offset X'00D6') to be

Cryptographic_Variable_Encipher (CSNBCVE)
Use the Cryptographic_Variable_Encipher verb to encrypt plaintext using a CVARENC key to produce
ciphertext using the Cipher Block Chaining (CBC) method. The plaintext must be a multiple of 8 bytes in
length.
Specify the following to encrypt plaintext:

v An operational fixed-length DES key-token or a key label of an operational fixed-length DES key-token
record that contains the key to be used to encrypt the plaintext with the
c-variable_encrypting_key_identifier parameter. The control vector in the key token must specify the
CVARENC key-type.
v The length of the plaintext, which is the same as the length of the returned ciphertext, with the
text_length parameter. The plaintext must be a multiple of 8 bytes in length.
v The plaintext with the plaintext parameter.
v The initialization vector with the initialization_vector parameter.
v A variable for the returned ciphertext with the ciphertext parameter. The length of this field is the length
that you specified with the text_length variable.
The verb does the following:

v Uses the CVARENC key and the initialization value with the CBC method to encrypt the plaintext.
v Returns the encrypted plaintext in the variable pointed to by the ciphertext parameter.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The text length must be a multiple of eight bytes.
v The minimum length of text that the security server can process is 8 bytes and the maximum is 256
bytes.

Format
CSNBCVE
c-variable_encrypting_key_identifier Input String 64 bytes
text_length Input Integer
plaintext Input String text_length bytes
initialization_vector Input String 8 bytes
ciphertext Output String text_length bytes
Parameters
c-variable_encrypting_key_identifier
The c-variable_encrypting_key_identifier parameter is a pointer to a string variable containing an
operational fixed-length DES key-token or a key label of an operational fixed-length DES key-token
record. The key token must contain a control vector that specifies a CVARENC key-type.
text_length
The text_length parameter is a pointer to an integer variable containing the length of the plaintext
variable and the ciphertext variable.
plaintext
The plaintext parameter is a pointer to is a string variable containing the plaintext to be encrypted.
initialization_vector
The initialization_vector parameter is a pointer to a string variable containing the 8-byte initialization
vector the verb uses in encrypting the plaintext.
ciphertext
The ciphertext parameter is a pointer to a string variable containing the ciphertext returned by the
verb.
Required commands
The Cryptographic_Variable_Encipher verb requires the Encipher Cryptovariable command (offset X'00DA')
to be enabled in the active role.

Data_Key_Export (CSNBDKX)
Use the Data_Key_Export verb to export a single-length or double-length key contained in an internal
fixed-length DES DATA key-token. The verb can export the key from an internal fixed-length DES
key-token in DES key-storage or application storage. This verb, which is authorized with a different
access-control point than used with the Key_Export verb, allows you to limit the export operations to DATA
keys as compared to the capabilities of the more general Key_Export verb.
The verb overwrites the 64-byte target_key_token variable with an external fixed-length DES key-token
that contains the source key encrypted by the fixed-length DES EXPORTER key-encrypting key. Only a
DATA key can be exported. If the source key has a control vector valued to the default DATA control
vector, the target key is enciphered without any control vector (that is, an all-zero control vector), otherwise
the source-key control vector is also used with the target key.
A key with a default, double-length DATA control-vector is exported into a version X'01' external key-token.
Otherwise, keys are exported into a version X'00' external key token.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Unless you enable the Unrestrict Data Key Export command (offset X'0277'), having replicated
key-halves is not permitted to export a key having unequal key-halves. Key parity bits are ignored.
v This verb does not support version X'10' external DES key tokens (RKX key tokens).
v When bit 40 of a control vector is on, both halves of a double-length key are guaranteed to not be
identical. If bit 40 of the control vector in the key token identified by the source_key_identifier is on, it is
a control vector violation if bit 40 of the control vector contained in the key token identified by the
exporter_key_identifier is not also on.
Format
CSNBDKX
source_key_identifier Input String 64 bytes
exporter_key_identifier Input String 64 bytes
target_key_token Output String 64 bytes

Parameters
The source_key_identifier parameter is a pointer to a string variable containing the internal fixed-length
DES key-token or the key label of the internal fixed-length DES key-token record to be exported. Only
a key type of DATA can be exported.
exporter_key_identifier
The exporter_key_identifier parameter is a pointer to a string variable containing the operational
fixed-length transport key-token or the key label of the operational fixed-length transport key-token
record used to encipher the target key. The transport key-token must have a key type of EXPORTER.
target_key_token
The target_key_token parameter is a pointer to a string variable containing the external fixed-length
DES source-key token with the reencrypted key returned by the verb. Any existing information in this
variable is overwritten.
Required commands
The Data_Key_Export verb requires the Data Key Export command (offset X'010A') to be enabled in the
active role.
By also specifying the Unrestrict Data Key Export command (offset X'0277'), you can permit a less secure
mode of operation that enables an equal key-halves EXPORTER key-encrypting-key to export a key
having unequal key-halves (key parity bits are ignored).

Data_Key_Import (CSNBDKM)
Use the Data_Key_Import verb to import an encrypted, source single-length or double-length DATA key
contained in an external fixed-length DES key-token, and create or update a target internal fixed-length
DES key-token with the source key enciphered with the fixed-length DES IMPORTER key-encrypting key.
This verb, which is authorized with a different control point than used with the Key_Import verb, allows you
to limit the import operations to DATA keys as compared to the capabilities of the more general
Key_Import verb.
To use this verb, specify the following:

source_key_token:
An external fixed-length DES key-token containing the source key to be imported. The key token
must indicate that a control vector is present. However, the control vector is usually valued at zero.
A double-length key that should result in a default DATA control vector must be specified in a
version X'01' external key-token. Otherwise, both single-length and double-length keys are
presented in a version X'00' key token.
Alternatively, you can provide the encrypted DATA-key at offset 16 in an otherwise all X'00'
key-token. The verb processes this token format as a DATA key encrypted by the IMPORTER key
and a null (all zero) control vector.
importer_key_identifier:
A fixed-length DES IMPORTER key-encrypting key under which the source key is deciphered.
target_key_identifier:
An internal or null fixed-length DES key-token.
The verb builds the internal fixed-length DES key-token as follows:

v Creates a default control-vector for a DATA key-type in the internal fixed-length DES key-token,
provided that the control vector in the external key-token is zero. If the control vector is not zero, the
verb copies the control vector from the external fixed-length DES key-token into the internal fixed-length
DES key-token.
v Multiply-deciphers the key under the keys formed by the exclusive-OR of the key-encrypting key
(identified in the importer_key_identifier) and the control vector in the external key-token, then
multiply-enciphers the key under keys formed by the exclusive-OR of the DES master-key and the
control vector in the internal fixed-length DES key-token. The verb places the key in the internal
v Calculates a token-validation value and stores it in the internal fixed-length DES key-token.
This verb does not adjust the parity of the source key.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|

| v Unless you enable the Unrestrict Data Key Import command (offset X'027C'), an IMPORTER transport
key having replicated key-halves is not permitted to import a key having unequal key-halves. Key parity
bits are ignored.
Format
CSNBDKM
importer_key_identifier Input String 64 bytes
Parameters
source_key_token
The source_key_token parameter is a pointer to a string variable containing the external fixed-length
DES key-token to be imported. Only a DATA key can be imported.
importer_key_identifier
The importer_key_identifier parameter is a pointer to a string variable containing the fixed-length DES
(IMPORTER) transport key-token or the key label of the fixed-length DES (IMPORTER) transport
key-token used to decipher the source key.
The target_key_identifier parameter is a pointer to a string variable containing a null fixed-length DES
key-token, an internal fixed-length DES key-token, or the key label of an internal fixed-length DES
key-token record or null fixed-length DES key-token record. The key token receives the imported key.
Required commands
The Data_Key_Import verb requires the Data Key Import command (offset X'0109') to be enabled in the
active role.
By also specifying the Unrestrict Data Key Import command (offset X'027C'), you can permit a less secure
mode of operation that enables an equal key-halves IMPORTER key-encrypting key to import a key having
unequal key-halves (key parity bits are ignored).

Diversified_Key_Generate (CSNBDKG)
Use the Diversified_Key_Generate verb to generate a key based on a function of a key-generating key,
the process rule, and data that you supply. The key-generating-type enables restricting such keys from
being used in other verbs that might reveal the value of a diversified key.
This verb is especially useful for creating diversified keys for operating with finance industry smart cards.
See Diversifying DES keys on page 177.
To use the verb, specify the following:

v A rule-array keyword to select the diversification process.
v An optional rule-array keyword for specifying the key-wrapping method (Release 4.1 or later).
v An optional rule-array keyword for specifying the translation-control setting (Release 4.1 or later).
v The operational fixed-length DES key-generating key from which the diversified keys are generated. The
control vector of the key-generating key determines the type of target key that is generated and, except
for the SESS-XOR process, restricts the use of this key to the key-diversification process.
v The data and its length used in the diversification process.
v The operational fixed-length DES key-token used to recover the data or, for processes that employ clear
data, a null fixed-length DES key-token.
v The fixed-length DES generated-token with a suitable control vector for receiving the diversified key.
The specified process can restrict the type of generated key.
For the CLR8-ENC, TDESEMV2, TDESEMV4, and TDES-XOR processes, a null token might not be
specified
For the TDES-ENC or TDES-DEC processes, a null token might be specified
For the SESS-XOR process, a null token must be specified
The verb generates the diversified key and updates the generated-token with this value by the following
procedure:
v Determines that it can support the process as requested by the rule-array keyword
v Recovers the key-generating key and checks the control vector for the appropriate key-type and the
specified usage in this verb
v Determines that the length of the generating key is appropriate to the specified process
v Determines that the control vector in the generated-token is permissible for the specified process
v Recovers the data-encrypting key and determines that the control vector is appropriate for the specified
process
v Decrypts the data as can be required by the specified process
v Generates the key appropriate to the specified process
v Adjusts the parity of the derived key to odd
v Returns the diversified key, multiply-enciphered by the master key modified by the control vector

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
v The USECONFG, WRAP-ECB, WRAP-ENH, and ENH-ONLY rule-array keywords are not supported in
releases before Release 4.1.
Format
CSNBDKG
rule_array_count Input Integer 1, 2, 3
generating_key_identifier In/Output String 64 bytes
data_length Input Integer
data Input String data_length bytes
data_decrypting_key_identifier Input String 64 bytes
generated_key_identifier In/Output String 64 bytes
Parameters
rule_array_count
rule_array
characters. The rule_array keywords follow.

Keyword Meaning
Diversification process (required)
CLR8-ENC Specifies that eight bytes of clear (not encrypted) data shall be Triple-DES encrypted with
the generating key to create a generated key. The encryption process is like that shown in
Figure 41 on page 673 for a single-length key with a control vector valued to binary zero.
The key selected by the generating_key_identifier must specify a KEYGENKY key-type also
with control vector bit 19 set to B'1'.
The key identified by the data_decrypting_key_identifier must identify a null DES key-token.
The key token identified by the generated_key_identifier variable must contain a control
vector that specifies a single-length key of one of these types: DATA, CIPHER, ENCIPHER,
DECIPHER, MAC, or MACVER.
TDES-ENC Specifies that 8 bytes or 16 bytes of clear (not encrypted) data shall be Triple-DES
encrypted with the generating key to create the generated key. If the
generated_key_identifier variable specifies a single-length key, then 8 bytes of clear data are
Triple-DES encrypted. If the generated_key_identifier variable specifies a double-length key,
then 16 bytes of clear data are Triple-DES encrypted in ECB mode.
The key selected by the generating_key_identifier must specify a DKYGENKY key-type that
has the appropriate control vector usage bits (bits 19 22) set for the desired generated
key.
Control vector bits 12 14 binary encode the key-derivation sequence level (DKYL7 down to
DKYL0, see DKYGENKY in Figure 37 on page 658). The final key is derived when bits 12
14 are B'000'. The verb verifies the incremental relationship between the value in
generated_key_identifier control vector and the generating_key_identifier control vector. Or
in the case when the generated_key_identifier is a null DES token, the appropriate counter
value is placed into the output key-token.
The data_decrypting_key_identifier parameter must identify a null DES key-token.
A key token identified by the generated_key_identifier variable that is not a null key-token
must contain a control vector that specifies a single-length or double-length key having a key
type consistent with the specification in bits 19 22 of the generating key.
TDES-DEC Specifies that 8 or 16 bytes of clear (not encrypted) data shall be Triple-DES decrypted with
the generating key to create the generated key. If the generated_key_identifier variable
specifies a single-length key, then 8 bytes of clear data are Triple-DES decrypted. If the
generated_key_identifier variable specifies a double-length key, then 16 bytes of clear data
are Triple-DES decrypted in ECB mode.
The key selected by the generating_key_identifier must specify a DKYGENKY key-type that
has the appropriate control vector usage bits (bits 19 22) set for the desired generated
key.
Control vector bits 12 14 binary encode the key-derivation sequence level (DKYL7 down to
DKYL0, see DKYGENKY in Figure 37 on page 658). The final key is derived when bits 12
14 are B'000'. The verb verifies the incremental relationship between the value in the
generated_key_identifier variable control-vector and the generating_key_identifier variable
control-vector. Or in the case when the generated_key_identifier variable is a null DES
key-token, the appropriate counter value is placed into the output key-token.
A key token identified by the generated_key_identifier variable that is not a null DES
key-token must contain a control vector that specifies a single-length or double-length key
having a key type consistent with the specification in bits 19 22 of the generating key.

Keyword Meaning
TDESEMV2, Specifies that 10 bytes, 18 bytes, 26 bytes, or 34 bytes of clear data shall be processed to
TDESEMV4 form an EMV card-unique key and then a session key as specified in the EMV 2000
Integrated Circuit Card Specifications for Payment Systems Version 4.0 (EMV4.0), Annex
A1.3. See Visa and EMV-related smart card formats and processes on page 707 for
additional details. The supplied data variable must contain the concatenation of:
v 8 or 16 bytes of data to diversify the issuer-master-key.
v 2 bytes containing the Application Transaction Counter (ATC) received from the smart
card. Place the counter value in a string construct with the high-order counter bit first in
the string.
v Optionally, a 16-byte Initial Value used in obtaining the session key from the card-unique
key.
The key selected by the generating_key_identifier parameter must specify a DKYGENKY

key-type at level-0 (bits 12 - 14 B'000') and indicate permission to create one of several key
types in bits 19 - 22:
B'0001' DDATA, to generate a DATA key
B'0010' DMAC, to generate a MAC key
B'0011' DMV, to generate a MACVER key
B'1000' DMKEY, to generate a SECMSG SMKEY (used in secure messaging, key
encryption, see the Secure_Messaging_for_Keys verb)
B'1001' DMPIN, to generate a SECMSG SMPIN (used in secure messaging, PIN
encryption, see the Secure_Messaging_for_PINs verb).
A key token or key-token record identified by the generated_key_identifier parameter that is

not a null DES key-token must contain a control vector that specifies a key type conforming
to that specified in control-vector bits 19 22 for the key-generating key. The control vector
must specify a double-length key.
TDES-XOR Specifies that 10 bytes or 18 bytes of clear (not encrypted) data shall be processed as
described in Visa and EMV-related smart card formats and processes on page 707 to
create the generated key. The data variable contains either 8 bytes or 16 bytes of data to be
triple-encrypted to which you append a 2-byte Application Transaction Counter value
(previously received from the smart card). Place the counter value in a string construct with
the high-order counter bit first in the string.
The key selected by the generating_key_identifier parameter must specify a DKYGENKY

key-type at level-0 (bits 12 14 B'000') and indicate permission to create one of several key
types in bits 19 22:
B'0001'
DDATA, to generate a DATA key
B'0010'
DMAC, to generate a MAC key
B'0011' DMV, to generate a MACVER key
B'1000'
DMKEY, to generate a SECMSG SMKEY (used in secure messaging, key
encryption, see the Secure_Messaging_for_Keys verb)
B'1001'
DMPIN, to generate a SECMSG SMPIN (used in secure messaging, PIN
encryption, see the Secure_Messaging_for_PINs verb).
A key token or key-token record identified by the generated_key_identifier parameter that is

not a null DES key-token. The token must contain a control vector that specifies a key type
conforming to that specified in control-vector bits 19 22 for the key-generating key. The
control vector must specify a double-length key.

Keyword Meaning
SESS-XOR Specifies the Visa** method for session-key generation, namely that 8 bytes or 16 bytes of
data shall be exclusive-ORed with the clear value of the session key contained in the key
token identified by the generating_key_identifier parameter. If the generating_key_identifier
parameter identifies a single-length key, then 8 bytes of data are exclusive-ORed. If the
generating_key_identifier parameter identifies a double-length key, then 16 bytes of data are
exclusive-ORed.
The key token specified by the generating_key_identifier parameter must be of key type
DATA, DATAC, MAC, DATAM, MACVER, or DATAMV.
On input, the token identified by the generated_key_identifier parameter must identify a null
DES key-token. The control vector contained in the output key token identified by the
generated_key_identifier parameter is the same as the control vector contained in the key
token identified by the generating_key_identifier parameter.
USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method.
This is the default.
WRAP-ENH Specifies to wrap the key using the enhanced wrapping method.
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the
default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary
zeros. Release 4.1 or later.
wrapped with the enhanced method. Sets bit 56 (ENH-ONLY) of the control vector to B'1'.
generating_key_identifier
The generating_key_identifier parameter is a pointer to a string variable containing the
key-generating-key (DKYGENKY or KEYGENKY) key-token or key label of a key-token record.
data_length
The data_length parameter is a pointer to an integer variable containing the number of bytes of data in
the data variable.
data
The data parameter is a pointer to a string variable containing the information used in the
key-generation process. This can be clear or encrypted information based on the process rule
specified in the rule array. Currently this variable must contain clear data.
data_decrypting_key_identifier
The data_decrypting_key_identifier parameter is a pointer to a string variable containing the data
decrypting key-token or key label of a key-token record. The specified process dictates the class of
key. If the process rule does not support encrypted data, point to a null DES key-token. Currently this
variable must contain a 64-byte null key-token.
generated_key_identifier
The generated_key_identifier parameter is a pointer to a string variable containing the target internal
key-token or the key label of the target key-token record. Specify either an internal token or a skeleton
token containing the desired control vector of the generated key.
v For the CLR8-ENC, TDESEMV2, TDESEMV4, and TDES-XOR processes, a null token might not
be specified
v For the TDES-ENC or TDES-DEC processes, a null token might be specified
v For the SESS-XOR process, a null token must be specified.

The generated key is encrypted and returned in the specified token. The control vector in the specified
internal token must be suitable for the specified process rule.
Required commands
The Diversified_Key_Generate verb requires the following commands to be enabled in the active role
based on the keyword specified for the process rule:

CLR8-ENC X'0040' Generate Diversified Key (CLR8-ENC)
SESS-XOR X'0043' Generate Diversified Key (SESS-XOR)
TDES-DEC X'0042' Generate Diversified Key (TDES-DEC)
TDES-ENC X'0041' Generate Diversified Key (TDES-ENC)
TDES-XOR X'0045' Generate Diversified Key (TDES-XOR)
TDESEMV2 or TDESEMV4 X'0046' Generate Diversified Key (TDESEMVn)
WRAP-ECB or WRAP-ENH X'013D' Allow Configuration Override with Keyword in DKG
and default key-wrapping
method setting does not match
keyword (Release 4.1 or later)
When a key-generating key of key type DKYGENKY is specified with control vector bits (19 22) of
B'1111', the Generate Diversified Key (DALL with DKYGENKY Key Type) command (offset X'0290') must
also be enabled in the active role.
Note: A role with offset X'0290' enabled can also use the PIN_Change/Unblock verb with a DALL key.
When using the TDES-ENC or TDES-DEC modes, you can specifically enable generation of a
single-length key or a double-length key with equal key-halves (an effective single-length key) by enabling
the Enable DKG Single Length Keys and Equal Halves for TDES-ENC, TDES-DEC command (offset
X'0044').

| Use the EC_Diffie-Hellman verb to create symmetric key material from a pair of Elliptic Curve
| Cryptography (ECC) keys using the Elliptic Curve Diffie-Hellman (ECDH) protocol. ECDH is a
| key-agreement protocol that allows two parties, each having an elliptic curve public-private key pair, to
| establish a shared secret over an insecure channel. This shared secret is used to derive another
| symmetric key. The ECDH protocol is a variant of the Diffie-Hellman protocol using elliptic curve
| cryptography.
| ECDH derives a shared secret value from a secret key owned by an Entity A and a public key owned by
| an Entity B, when the keys share the same elliptic curve domain parameters. Entity A can be either the
| initiator of a key-agreement transaction, or the responder in a scheme. If two entities both correctly
| perform the same operations with corresponding keys as inputs, the same shared secret value is
| produced.
| Both parties must create an ECC public-private key pair. See PKA_Key_Token_Build (CSNDPKB) on
| page 95 and PKA_Key_Generate (CSNDPKG) on page 87. A key can be internal or external, as well as
| encrypted or in the clear. Both keys must have the same elliptic curve domain parameters (curve type and
| key size):
| v Brainpool (key size 160, 192, 224, 256, 320, 384, or 512)
| v Prime (key size 192, 224, 256, 384, or 521)
| In addition to having the same elliptic curve domain parameters, the keys must have their key-usage field
| set to permit key establishment (either KEY-MGMT or KM-ONLY). See Table 112 on page 597.
| To use this verb, specify the following:

| v One to five rule-array keywords:
| A required key-agreement keyword
| An optional transport key-type (required if output_KEK_key_identifier is a label) that identifies which
| key-storage dataset contains the output KEK key-token
| An optional output key-type (required if output_key_identifier is a label) that identifies which
| key-storage dataset contains the output key-token
| When the output is a DES key-token, an optional key-wrapping method and an optional translation
| control keyword
| v The internal or external ECC key-token containing the private key (public-private key pair).
| If the private key is in an external key-token and is not in the clear, specify the internal KEK that was
| used to wrap the private key. Otherwise, specify a private KEK key-length of 0.
| v An internal or external ECC key-token containing the public key (public key only or public-private key
| pair) of the other party.
| If the public key is in a key token that contains a public-private key pair, only the public-key portion is
| used. No attempt is made to decrypt the private key.
| v From 8 - 64 bytes of party information data of the initiator and the responder entities, according to NIST
| SP800-56A Section 5.8
| v The number of bits of key material, from 64 - 256, to derive and place in the provided output key-token
| v The length in bytes of the buffer for the output key-identifier
| v An internal or external skeleton key-token to be used as input for the output key-token
| The skeleton key-token must be an AES key or a DES key, as shown in the following table:

|| Algorithm Token version number Key type (see note)
| AES X'04' (legacy fixed-length DATA
| symmetric key-token)
| X'05' (variable-length symmetric v CIPHER
|| key-token) Both parties can provide any combination of encryption or
| decryption for key-usage field.
| v EXPORTER or IMPORTER
| Both parties can provide any combination of EXPORTER or
| IMPORTER.
| DES X'00', X'01', X'03' (legacy v CIPHER, DECIPHER, ENCIPHER
|| fixed-length symmetric Both parties can provide any combination of Encipher or
|| key-token) Decipher key-usage bits in the control vector.
| Both parties can provide any combination of EXPORT or
| IMPORT key-usage bits in the control vector.
| Note: Except as otherwise noted, both parties must provide identical skeleton key tokens for the output key in
| order to derive identical keys. For legacy skeletons, control vector parity bits are not used in the key derivation
| process.
|
| If the skeleton key-token is an external key-token, specify the internal KEK to be used to wrap the
| output key-token. Otherwise, specify an output KEK length of 0.
| If the output_key_identifier specifies a DES key-token, then the output_KEK_key_token must identify a
| legacy DES KEK. Otherwise it must identify a variable-length symmetric AES KEK key-token.
| Restrictions
| AIX
| IBM i
| SUSE Linux Enterprise Server X
| Windows
|
| v The NIST security strength requirements are enforced, with respect to ECC curve type (input) and
| derived key-length.

| Format
| Parameter name Direction Data type Data length or value
| CSNDEDH
| return_code Output Integer See Appendix A.
| reason_code Output Integer See Appendix A.
| exit_data_length In/Output Integer 0
| exit_data In/Output String exit_data_length bytes
| rule_array_count Input Integer 1-5
| rule_array Input String array rule_array_count * 8 bytes
| private_key_identifier_length Input Integer 64 - 800
| private_key_identifier Input String private_key_identifier_length bytes
| private_KEK_key_identifier_length Input Integer 0, 64 - 900
| private_KEK_key_identifier Input String private_KEK_key_identifier_length bytes
| public_key_identifier_length In/Output Integer 64 - 800
| public_key_identifier In/Output String public_key_identifier_length bytes
| chaining_vector_length In/Output Integer 0
| chaining_vector In/Output String chaining_vector_length bytes
| party_info_length In/Output Integer 8 - 64
| party_info In/Output String party_info_length bytes
| key_bit_length Input Integer 64, 128, 192, or 256
| reserved_1_length In/Output Integer 0
| reserved_1 In/Output String reserved_1_length bytes
| output_KEK_key_identifier_length Input Integer 0, 64 - 900
| output_KEK_key_identifier Input String output_KEK_key_identifier_length bytes
| output_key_identifier_length In/Output Integer 64 - 900
| output_key_identifier In/Output String output_key_identifier_length bytes
|
| See Appendix I, Java Native Interface, on page 743 for information about calling this verb using the JNI.
| Parameters
| For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see
| Parameters common to all verbs on page 9.
| rule_array_count
| in the rule_array variable. Valid values are 1 - 5.
| rule_array
| The rule_array parameter is a pointer to a string variable containing an array of keywords. The
| keywords are 8 bytes in length and must be left-aligned and padded on the right with space
| characters. The rule_array keywords for this verb are shown below:

|| Keyword Meaning
| Key agreement (one required)
| DERIV01 Use input skeleton key-token and derive one element of any key pair. Denotes ANS
| X9.63 protocol static unified model key-agreement scheme (see NIST SP800-56A).
| Initiator and responder must have a sufficient level of trust such that they each derive
| only one element of any key pair.
| Transport key-type (one, optional; one required if output_KEK_key_identifier is a label)
| OKEK-AES The output_KEK_key_identifier represents an AES key-token.
| OKEK-DES The output_KEK_key_identifier represents a DES key-token.
| Output key-type (one, optional; required if output_key_identifier is a label)
| KEY-AES The outbound key-encrypting key represents an AES skeleton key-token.
| KEY-DES The outbound key-encrypting key represents a DES skeleton key-token.
| Key-wrapping method (one, optional). DES only.
| USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method.
| This is the default.
| WRAP-ECB Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for
| AES keys.
| WRAP-ENH Specifies to wrap the key using the enhanced wrapping method. Valid only for DES keys.
| Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when
| the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to
| binary zeros.
| ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method after it
| has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the
| control vector to B'1'.
|
| private_key_identifier_length
| The private_key_identifier_length parameter is a pointer to an integer variable containing the number
| of bytes in the private_key_identifier variable.
| private_key_identifier
| The private_key_identifier parameter is a pointer to a string variable containing an internal or external
| ECC key-token, or a key label identifying a key-storage record for such a token. The ECC key-token
| will contain a public-private key pair. Clear keys are allowed.
| The ECC curve type and size must be the same as the type (Prime or Brainpool) and size of the ECC
| key-token specified by the public_key_identifier parameter. The key-usage flag of the ECC key-token
| identified by the private_key_identifier parameter must permit key establishment (either KEY-MGMT or
| KM-ONLY).
| private_KEK_key_identifier_length
| The private_KEK_key_identifier_length parameter is a pointer to an integer variable containing the
| number of bytes in the private_KEK_key_identifier variable. The length can be 0.
| private_KEK_key_identifier
| The private_KEK_key_identifier parameter is a pointer to a string variable containing an internal KEK
| key-token, or a key label identifying a key-storage record for such a key token. The KEK key-token
| must be present if the key token specified by the private_key_identifier contains an external encrypted
| ECC key-token.
| public_key_identifier_length
| The public_key_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes in the public_key_identifier variable. Note that even though this variable is not currently updated
| on output, it is reserved as an output field for future use.

| public_key_identifier
| The public_key_identifier parameter is a pointer to a string variable containing an ECC key-token, or a
| key label identifying a key-storage record for such a key token. The ECC curve type and size must be
| the same as the type and size of the ECC key-token specified by the private_key_identifier parameter.
| If the public_key_identifier parameter identifies a key token containing a public-private key pair, no
| attempt to decrypt the private part is made. Note that even though this variable is not currently
| updated on output, it is reserved as an output field for future use.
| chaining_vector_length
| The chaining_vector_length parameter is a pointer to an integer variable containing the number of
| bytes in the chaining_vector variable. This field is currently not used. The value must be 0.
| chaining_vector
| The chaining_vector parameter is a pointer to a string variable containing a buffer that is currently
| reserved.
| party_info_length
| The party_info_length parameter is a pointer to an integer variable containing the number of bytes in
| the party_info variable. The value must be 8 - 64.
| party_info
| The party_info parameter is a pointer to a string variable containing combined entity identifier
| information, including nonce. This information must contain data of both entities according to NIST
| SP800-56A Section 5.8.
| key_bit_length
| The key_bit_length parameter is a pointer to an integer variable containing the number of bits of key
| material to derive and place in the provided output key-token. The value must be 64 - 256.
| reserved_1_length
| The reserved_1_length parameter is a pointer to an integer variable containing the number of bytes in
| the reserved_1 variable. The value must be 0.
| reserved_1
| The reserved_1 parameter is a pointer to a string variable. It is currently not used.
| reserved_2_length
| reserved_2
| reserved_3_length
| reserved_3
| reserved_4_length
| reserved_4
| reserved_5_length
| reserved_5

| output_KEK_key_identifier_length
| The output_KEK_key_identifier_length parameter is a pointer to an integer variable containing the
| number of bytes in the output_KEK_key_identifier variable. The length can be 0.
| output_KEK_key_identifier
| The output_KEK_key_identifier parameter is a pointer to a string variable containing an internal KEK
| key-token, or a key label identifying a key-storage record for such a token. This parameter must
| identify a KEK key-token whenever the output_key_identifier specifies an external key-token. If the
| output_key_identifier specifies a DES key-token, then the output_KEK_key_identifier must identify a
| legacy DES KEK, otherwise it must identify a variable-length symmetric AES KEK key-token.
| If this variable contains a key label, specify a transport key-type rule-array keyword (OKEK-DES or
| OKEK-AES) to identify which key-storage dataset contains the key token. If a transport key-type
| keyword is specified, it must match the type of key identified by this parameter, whether the key is in
| key storage or not.
| If the output_KEK_key_identifier specifies a legacy DES KEK, then the key token must contain either
| an EXPORTER control vector with bit 21 on (EXPORT) or an IMPORTER control vector with bit 21 on
| (IMPORT). The XLATE bit (bit 22) is not checked. Similarly, if the output KEK_key_identifier identifies a
| variable-length symmetric AES KEK, then the KEK must be have a key type of EXPORTER or
| IMPORTER. Key-usage field 1 of the KEK must be set so that the key can be used for EXPORT or
| IMPORT. In addition, key-usage field 4 must be set so that the key can wrap DERIVATION class keys.
| output_key_identifier_length
| The output_key_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes in the output_key_identifier variable. On input, the output_key_identifier length variable must be
| set to the total size of the buffer pointed to by the output key identifier parameter. On output, this
| variable contains the number of bytes of data returned by the verb in the output_key_identifier
| variable.
| output_key_identifier
| The output_key_identifier parameter is a pointer to a string variable. On input, it must contain an
| internal or an external skeleton key-token, or a key label identifying a key-storage record for such a
| token. The skeleton key-token must be one of the following:
| DES (legacy DES key-token)
| v CIPHER, DECIPHER, or ENCIPHER
| AES
| v DATA (legacy AES key-token)
| v CIPHER (variable-length symmetric key-token) with key-usage field set so that the key can be
| used for decryption, encryption, or both)
| v EXPORTER or IMPORTER (variable-length symmetric key-token)
| On successful completion, this variable contains an updated key-token that contains the generated
| symmetric key material, or the key label of the key-token that has been updated in key storage.
| If this variable contains an external key-token on input, then the output_KEK_key_identifier is used to
| securely encrypt it for output. If this variable contains a key label, specify an output key-type rule-array
| keyword (KEY-DES or KEY-AES) to identify which key-storage dataset contains the key token. If an
| output key-type keyword is specified, it must match the type of key identified by this parameter,
| whether the key is in key storage or not.
| If this variable identifies an external DES key-token, then the output_KEK_key_identifier must identify
| a DES KEK key-token. If this variable is present and identifies an external key-token other than a DES
| key-token, then the output KEK key identifier must identify an AES KEK key-token.

| Required commands
| This table describes access control points that the EC_Diffie-Hellman verb must have enabled in the active
| role under certain circumstances.
|| Command Offset When required
| Elliptic Curve Diffie-Hellman X'0360' When using the EC_Diffie-Hellman verb
| Allow Configuration Override with X'0362' If the output_key_identifier parameter identifies a DES
| Keyword in EDH command key-token, and the wrapping method specified is not the
| default method
| Disallow Weak Key Wrap X'0328' To disable the wrapping of a stronger key with a weaker key
| This command affects multiple verbs.

| See Table 169 on page 715.
| Warn When Wrapping Weak Keys X'032C' To receive a warning against the wrapping of a stronger key
| with a weaker key
| The Disallow Weak Key Wrap
| command (offset X'0328') overrides
| this command.
| Prevent Weaker Keys from Being X'036F' To disable a weaker key from being used to generate a
| Used to Generate Stronger Keys stronger key
|
| Depending on curve type, each length of p in bits contained in the ECC private-key section and the ECC
| public-key section must have the following command enabled in the active role:
|| Curve type Length of prime p in bits Offset Command
| Brainpool 160 (X'00A0') X'0368' Allow Brainpool Curve 160
| 192 (X'00C0') X'0369' Allow Brainpool Curve 192
| 224 (X'00E0') X'036A' Allow Brainpool Curve 224
| 256 (X'0100') X'036B' Allow Brainpool Curve 256
| 320 (X'0140') X'036C' Allow Brainpool Curve 320
| 384 (X'0180') X'036D' Allow Brainpool Curve 384
| 512 (X'0200') X'036E' Allow Brainpool Curve 512
| Prime 192 (X'00C0') X'0363' Allow Prime Curve 192
| 224 (X'00E0') X'0364' Allow Prime Curve 224
| 256 (X'0100') X'0365' Allow Prime Curve 256
|
|

Key_Encryption_Translate (CSNBKET)
Use the Key_Encryption_Translate verb to change the method of key encryption. An input key can be a
double-length external DES CCA DATA key, or a double-length CBC-encrypted key. The return key is
encrypted using CBC encryption or CCA (ECB) encryption. The CCA DATA key must be double-length and
have an all-zero control vector. The CBC-encrypted key is treated as a 16-byte string encrypted with an
all-zero initialization vector.
Specify the following:

1. The translation re-encryption operation using a rule-array keyword:
v CBCTOECB changes a CBC key-encryption to a CCA (ECB) encryption.
v ECBTOCBC changes a CCA (ECB) key-encryption to CBC encryption.
2. The key-encrypting key:
v When performing CBCTOECB translation, specify an IMPORTER key.
v When performing ECBTOCBC translation, specify an EXPORTER key.
3. Using the key_in parameter, identify a 64-byte external CCA DATA key-token, or a 16-byte
CBC-encrypted key. Set the key_in_length variable to the length of the key_in variable.
4. Using the key_out parameter, identify a 64-bye external CCA DATA key-token with an all-zero control
vector, or a 16-byte string. Set the key_out_length variable to the length of the key_out variable.
The verb performs the following tasks:

v Recovers the key-encrypting key and ensures that the type is consistent with the requested
ECBTOCBC or CBCTOECB translation.
v Decrypts the supplied key_in key using the key-encrypting key, and then encrypts the result using the
key-encrypting key.
v For CBCTOECB translation, updates the key_out variable with the data key in an external token with an
all-zero control vector.
v For ECBTOCBC translation, returns the key in a 16-byte string.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|

| Format
CSNBKET
kek_key_identifier_length Input Integer 64
kek_key_identifier In/Output String kek_key_identifier_length bytes
key_in_length Input Integer 16 or 64
key_in Input String key_in_length bytes
key_out_length In/Output Integer 16 or 64
key_out Output String key_out_length bytes
Parameters
For the definitions of return_code, reason_code, exit_data_length, and exit_data, see Parameters
common to all verbs on page 9.
rule_array_count
rule_array
Keyword Meaning
Key translation method (one required)
CBCTOECB Specifies decryption of a 16-byte string and CCA encryption of the
resulting clear-key value as an external CCA DATA key.
ECBTOCBC Specifies decryption of a CCA DATA key and the CBC encryption
of the resulting clear key.
kek_key_identifier_length
The kek_key_identifier_length parameter is a pointer to an integer variable containing the length in
bytes of a fixed-length DES key-token. The value must be 64.
kek_key_identifier
The kek_key_identifier parameter is a pointer to a string variable containing the key-encrypting token,
or key label of a KEK key-token record.
key_in_length
The key_in_length parameter is a pointer to an integer variable containing the number of bytes of data
in the key_in variable. The value must be 16 for a CBCTOECD translation, or 64 for an ECBTOCBC
translation.

key_in
The key_in parameter is a pointer to a string variable containing a CCA external key-token, or a
16byte CBC-encrypted key.
key_out_length
The key_out_length parameter is a pointer to an integer variable containing the number of bytes of
data in the key_out variable. On input, set the variable to:
v At least 16 for the ECBTOCBC translation
v At least 64 for the CBCTOECB translation
Upon successful completion, the verb sets the variable to the length of the returned key_out variable.
key_out
The key_out parameter is a pointer to a string variable containing the returned translated key. The
verb returns the encrypted key in a 64-byte CCA external DATA key-token with an all-zero control
vector, or in a 16-byte string.
Required commands
The Key_Encryption_Translate verb requires the following commands to be enabled in the active role:

CBCTOECB X'030D' Translate Key from CBC to ECB
ECBTOCBC X'030E' Translate Key from ECB to CBC

Key_Export (CSNBKEX)
Use the Key_Export verb to export a source internal fixed-length DES key-token into a target external
fixed-length DES key-token. Existing information in the target key-token is overwritten. The target key is
enciphered by the EXPORTER key-encrypting key exclusive-ORed with the control vector of the target
key.

key_type
A keyword for the key type. Use of the TOKEN keyword is the preferred coding style. For
compatibility with older systems, however, you can explicitly name a key type, in which case the
key type must match the key in the control vector of the source key-identifier.
A source-key internal fixed-length DES key-token or the key label of an internal fixed-length
key-token record in DES key-storage containing the source key to be exported.
An EXPORTER key-encrypting key under which the target key is enciphered.
target_key_token
A 64-byte variable to hold the target external DES key-token.
The verb builds the external key-token:

v Copies the control vector from the internal key-token to the external key-token, except when the source
key has a control vector valued to the default DATA control-vector for single-length or double-length
keys, in which case the target control vector is set to 0.
v Multiply-deciphers the source key under keys formed by the exclusive-OR of the master key and the
control vector in the source key-token, multiply-enciphers the key under keys formed by the
exclusive-OR of the EXPORTER key-encrypting-key and target-key control vector, and places the result
in the target key-token.
v Calculates a token-validation value and stores it in the target key-token.
v Places the external key-token in the 64-byte variable identified by the target_key_token parameter,
ignoring any preexisting data.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Unless you enable the Unrestrict Reencipher from Master Key command (offset X'0276'), an
EXPORTER key-encrypting key having equal key-halves is not permitted to export a key having
unequal key-halves. Key parity bits are ignored.
v When bit 40 of a control vector is on, both halves of a double-length key are guaranteed to not be
identical. If bit 40 of the control vector in the key token identified by the source_key_identifier is on, it is
a control vector violation if bit 40 of the control vector contained in the key token identified by the
exporter_key_identifier is not also on.

Format
CSNBKEX
source_key_identifier Input String 64 bytes
exporter_key_identifier Input String 64 bytes
target_key_token Output String 64 bytes
Parameters
key_type
The key_type parameter is a pointer to a string variable containing a keyword that specifies the key
type of the source key-token. The keyword is 8 bytes in length, and must be left-aligned and padded
on the right with space characters. The key_type keywords are shown below:
CIPHER IMPORTER PINGEN

DATA IPINENC PINVER
DECIPHER MAC TOKEN
ENCIPHER MACVER DATAC (z/OS only)
EXPORTER OKEYXLAT DATAM (z/OS only)
IKEYXLAT OPINENC DATAMV (z/OS only)
The source_key_identifier parameter is a pointer to a string variable containing the internal DES
source key-token or key label of a key-token record.
The exporter_key_identifier parameter is a pointer to a string variable containing the EXPORTER
key-encrypting-key token or key label of a key-token record.
target_key_token
The target_key_token parameter is a pointer to a string variable containing the external DES target
key-token.
Required commands
The Key_Export verb requires the Reencipher from Master Key command (offset X'0013') to be enabled in
the active role.
By also specifying the Unrestrict Reencipher from Master Key command (offset X'0276'), you can permit a
less secure mode of operation that enables an equal key-halves EXPORTER key-encrypting-key to export
a key having unequal key-halves (key parity bits are ignored).

Key_Generate (CSNBKGN)
Use the Key_Generate verb to randomly generate an AES or DES key, and return one or two copies of
| the key in a fixed-length AES or DES key-token. Each copy is enciphered under a key-encrypting key
| (KEK). Also see Key_Generate2 (CSNBKGN2) on page 239 for generating keys for variable-length
| symmetric key tokens. For AES, the verb returns only one copy of the key, enciphered under the AES
master key. AES keys can be 16, 24, or 32 bytes (128, 192, or 256 bits) in length. For DES, the verb
selectively returns one copy of the key or two, with each copy enciphered under a user-specified DES
key-encrypting key. DES keys can be 8 bytes (single) or 16 bytes (double) in length. The verb returns
master-key enciphered keys in internal key tokens, and all others in external key tokens. These key tokens
and their enciphered keys are returned ready to use or distribute, either to application storage or DES
key-storage.
The verb needs to know the key length and the key type for each copy of the key it produces. Each of
these can be specified explicitly with a parameter value, or you can indicate that the verb should
determine the length and type itself.
v A parameter key_length is used to specify the key length using keywords. There are keywords for
specific explicit key lengths, but you can set key_length to space characters to have the verb determine
the key length based on the key type. If the key length in an AES token is valid, but different from a
length specified explicitly by parameter key_length, the length in the token is overwritten with the
specified length. In this case, the verb returns a return code of 0 and a reason code of 2040 (X'7F8') to
notify you that the length in the API parameter did not match the length in the key token that you
provided.
Note: Certain types of CCA DES keys must be double length, for example, IMPORTER or EXPORTER
keys. In some situations, you need these keys to act as single length keys. In order to
accomplish this, specify the SINGLE-R keyword. This causes the generated key to have equal
left and right (replicated) key halves. A double-length DES key with replicated key halves
operates identically as a single-length key with that same key value.
v A key-type parameter for each output key-token is used to specify the type of the generated key for that
token. Keywords can be used to explicitly specify the key type, but the preferred method is to use the
keyword TOKEN, which specifies that the verb is to determine the key types by examining the key
tokens provided. The TOKEN method allows the specification of any control vector, while the explicit key
type keywords allows only the generation of keys with the default control vectors for each key type. For
DES keys, the verb determines the key type from the control vector in the token. For AES keys, the only
key type available is AESDATA.
The parameter key_form indicates whether you want one or two copies of the generated random key, and
the form of each copy. For DES keys, each key can either be in internal form encrypted under the DES
master key, in external form encrypted under an IMPORTER key-encrypting key, or in external form
encrypted under an EXPORTER key-encrypting key.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|

v AES key tokens and keywords are not supported in releases before Release 3.30.
Format
CSNBKGN
key_form Input String 4 bytes
key_length Input String 8 bytes
key_type_1 Input String 8 bytes
KEK_key_identifier_1 Input String 64 bytes
KEK_key_identifier_2 Input String 64 bytes
generated_key_identifier_1 In/Output String 64 bytes
generated_key_identifier_2 In/Output String 64 bytes
Parameters
key_form
The key_form parameter is a pointer to a string variable containing a keyword. The keyword is 4 bytes
in length and must be left-aligned and padded on the right with space characters. The key_form
keywords and their usage are shown in Table 35 on page 231. One keyword is required.
A key_form keyword defines whether one or two copies of the key are generated, and what
key-encrypting key (KEK) is used to encipher each copy. It is comprised of one or two strings, two
characters each ("OP", "IM", or "EX"), where each two-character string indicates how each key should
be enciphered:
v The "OP" string requests an operational key. An operational key is enciphered under the master key
and returned in an internal key-token. It is immediately usable at the local node.
v The "IM" string requests an importable key. This key is enciphered with an IMPORTER KEK and
returned in an external key-token. It can be imported at the local node at a later time.
v The "EX" string requests an exportable key. This key is enciphered with an EXPORTER KEK and
returned in an external key-token. It is suitable for distribution to another cryptographic node.

Table 35. Key_form keywords and their usage
key_form KEK_key_ generated_key_ KEK_key_ generated_key_
keyword identifier_1 identifier_1 identifier_2 identifier_2 Description
OP Provide a null Provide a null Provide a null Provide a null Returns one
key-token. The key-token or an key-token. The key-token. The enciphered copy of
verb ignores this internal key token. verb ignores this verb ignores this the random key in
token. If null, a default token. token. operational form,
internal key-token ready for
is created. The immediate use at
verb updates the the local node. This
internal key-token keyword is valid for
with a copy of the both AES and
random key DES. See Table 37
enciphered under on page 236.
the master key.
IM Provide an Provide a null Provide a null Provide a null Returns one
IMPORTER KEK. key-token or an key-token. The key-token. The enciphered copy of
The verb uses this external key-token. verb ignores this verb ignores this the random key, to
KEK to encipher If null, a default token. token. be imported later to
the key returned in external key-token the local node. This
the key token is created. The keyword is valid
identified by the verb returns a copy only for DES. See
generated_key_ of the random key Table 37 on page
identifier_1 in an external 236.
parameter. key-token
enciphered under
KEK 1.
EX Provide an Provide a null Provide a null Provide a null Returns one
EXPORTER KEK. key-token or an key-token. The key-token. The enciphered copy of
The verb uses this external key-token. verb ignores this verb ignores this the random key for
KEK to encipher If null, a default token. token. distribution to a
the key returned in external key-token remote node. This
the key token is created. The keyword is valid
identified by the verb returns a copy only for DES. See
generated_key_ of the random key Table 37 on page
identifier_1 in an external 236.
parameter. key-token
enciphered under
KEK 1.
OPOP Provide a null Provide a null Provide a null Provide a null Returns two
key-token. The key-token or an key-token. The key-token or an enciphered copies*
verb ignores this internal key token. verb ignores this internal key token. of the random key,
token. If null, a default token. If null, a default both ready for
internal key-token internal key-token immediate use at
is created. The is created. The the local node. This
verb updates the verb updates the keyword is valid
internal key-token internal key-token only for DES. See
with a copy of the with a copy of the Table 38 on page
random key random key 236.
enciphered under enciphered under
the master key. the master key.

Table 35. Key_form keywords and their usage (continued)
OPIM Provide a null Provide a null Provide an Provide a null Returns two
key-token. The key-token or an IMPORTER KEK. key-token or an enciphered copies*
verb ignores this internal key token. The verb uses this external key-token. of the random key,
token. If null, a default KEK to encipher If null, a default one ready for
internal key-token the key returned in external key-token immediate use at
is created. The the key token is created. The the local node, and
verb updates the identified by the verb returns a copy the other to be
internal key-token generated_key_ of the random key imported later to
with a copy of the identifier_2 in an external the local node. This
random key parameter. key-token keyword is valid
enciphered under enciphered under only for DES. See
the master key. KEK 2. Table 38 on page
236.
OPEX Provide a null Provide a null Provide an Provide a null Returns two
key-token. The key-token or an EXPORTER KEK. key-token or an enciphered copies*
verb ignores this internal key token. The verb uses this external key-token. of the random key,
token. If null, a default KEK to encipher If null, a default one ready for
internal key-token the key returned in external key-token immediate use at
is created. The the key token is created. The the local node, and
verb updates the identified by the verb returns a copy the other for
internal key-token generated_key_ of the random key distribution to a
with a copy of the identifier_2 in an external remote node. This
random key parameter. key-token keyword is valid
the master key. KEK 2. Table 38 on page
236.
IMIM Provide an Provide a null Provide an Provide a null Returns two
IMPORTER KEK. key-token or an IMPORTER KEK. key-token or an enciphered copies*
The verb uses this external key-token. The verb uses this external key-token. of the random key,
KEK to encipher If null, a default KEK to encipher If null, a default both to be imported
the key returned in external key-token the key returned in external key-token later to the local
the key token is created. The the key token is created. The node. This keyword
identified by the verb returns a copy identified by the verb returns a copy is valid only for
generated_key_ of the random key generated_key_ of the random key DES. See Table 38
identifier_1 in an external identifier_2 in an external on page 236.
parameter. key-token parameter. key-token
KEK 1. KEK 2.
IMEX Provide an Provide a null Provide an Provide a null Returns two
IMPORTER KEK. key-token or an EXPORTER KEK. key-token or an enciphered copies*
KEK to encipher If null, a default KEK to encipher If null, a default one to be imported
the key returned in external key-token the key returned in external key-token later to the local
the key token is created. The the key token is created. The node, and the
identified by the verb returns a copy identified by the verb returns a copy other for
generated_key_ of the random key generated_key_ of the random key distribution to a
identifier_1 in an external identifier_2 in an external remote node. This
parameter. key-token parameter. key-token keyword is valid
KEK 1. KEK 2. Table 38 on page
236.

Table 35. Key_form keywords and their usage (continued)
EXEX Provide an Provide a null Provide an Provide a null Returns two
EXPORTER KEK. key-token or an EXPORTER KEK. key-token or an enciphered copies*
KEK to encipher If null, a default KEK to encipher If null, a default both for distribution
the key returned in external key-token the key returned in external key-token to a remote node.
the key token is created. The the key token is created. The This keyword is
identified by the verb returns a copy identified by the verb returns a copy valid only for DES.
generated_key_ of the random key generated_key_ of the random key See Table 38 on
identifier_1 in an external identifier_2 in an external page 236.
parameter. key-token parameter. key-token
KEK 1. KEK 2.
* Normally, each copy of the key is enciphered with a different control vector that enables different key usage.
key_length
The key_length parameter is a pointer to a string variable containing a keyword or space characters.
The variable is 8 bytes in length, and a keyword must be left-aligned and padded on the right with
space characters. The key_length parameter defines the length of the random AES or DES key for the
verb to generate and return encrypted under a KEK. The key_length values are shown in Table 36.
One value is required.
AES key lengths of 16, 24, and 32 bytes (128, 192, and 256 bits) are supported. DES key lengths of 8
bytes (single) and 16 bytes (double) are supported.
Table 36. Key_length values
key_length value Description
SINGLE Generates a single-length DES key (8 bytes). DES only.
KEYLN8 Synonym for SINGLE.
SINGLE-R Generates a double-length DES key (16 bytes) with replicated key halves, making an
effective single-length key. DES only.
DOUBLE Generates a double-length DES key (16 bytes). DES only
KEYLN16 For AES, generates a 16-byte (128-bit) key. For DES, synonym for DOUBLE.
KEYLN24 Generates a 24-byte (192-bit) key (AES only, Release 3.30 or later).
KEYLN32 Generates a 32-byte (256-bit) key (AES only, Release 3.30 or later).
8 space characters Determines the key length implicitly based on the key-token provided by the
generated_key_identifier_1 parameter. If a null key-token is provided, the length is the
default key length for the key_type keyword specified.
Key type AESDATA does not have a default key length. If the key token is not null, the
length of the key in the key token is used. Valid for AES and DES.

Table 36. Key_length values (continued)
Notes:
1. A fixed-length DES key-token contains a control vector with a key-form field that specifies the length of the
key. A fixed-length AES key-token contains an explicit field in the token for the length of the key.
2. For DES, if the key token provided by the generated_key_identifier_1 parameter is not null, it is an error if
the length in the key token does not match the length specified by the key_length keyword.
3. A double-length DES key consists of two single-length DES keys (a left half and a right half). If both halves
are equal (ignoring parity bits), the key operates identically as a single-length DES key. Some types of CCA
DES keys must be double length, such as KEKs. The SINGLE-R keyword is provided for those situations
where you need these types of keys to act as single-length keys.
4. The key-form bits of a DES control vector can be set to guarantee that the key halves of a double-length key
are unique. See Key-form bits, 'fff' and 'FFF' on page 660. Guaranteed unique halves prevents an effective
single-length key from masquerading as a double-length key. This CCA implementation does not support the
keyword DOUBLE-O to generate double-length DES keys with guaranteed unique halves as some
implementations might. To generate a double-length DES key with guaranteed unique halves, provide a key
token with a control vector that has the required key-form bits set. Not all CCA implementations support
control vectors set for guaranteed unique halves.
key_type_1 and key_type_2

These parameters are pointers to 8-byte string variables, each containing a keyword that specifies the
key type for each copy of the key being generated. If only a single copy of the key is being generated,
parameter key_type_2 should contain eight space characters.
Use the AESTOKEN keyword (Release 3.30 or later) for AES or the TOKEN keyword for DES keys to
indicate that the verb should determine the key type from the key token that you supply. For AES, all
keys are type AESDATA. For DES, the key type is determined from the control vector in the key
tokens. Alternatively, you can specify the key type using keywords shown in Table 37 on page 236 and
Table 38 on page 236. This is useful when you want to create a fixed-length AES or DES key-token
with a default control vector.
Table 37 on page 236 lists the keywords allowed when generating a single copy of the key (key_form
OP, IM, or EX). Table 38 on page 236 lists the keyword combinations that are allowed when
requesting two copies of the generated key.
For AES keys (Release 3.30 or later), the only keywords permitted for the key type are AESTOKEN
and AESDATA. These key-type keywords are not valid with DES. The remaining key-type keywords
are for DES only and are not valid with AES.
KEK_key_identifier_1 and KEK_key_identifier_2
These parameters are pointers to 64-byte string variables containing the key tokens or key labels for
the keys used to encipher IM or EX format generated keys. If an OP form DES key is requested or no
key is requested, the associated KEK identifier should point to a null key token. These parameters are
not used when generating AES keys, and both should point to null key-tokens.
generated_key_identifier_1 and generated_key_identifier_2
These parameters are pointers to 64-byte string variables containing the key tokens or key labels for
the tokens that are to receive the generated keys. If the parameter identifies an internal or external
key token, the verb attempts to use the information in the existing key token and simply replaces the
key value. If the parameter identifies a null DES key-token, the output key-token is wrapped using the
default key-wrapping method that is set in the configuration file.
Using the AESTOKEN (Release 3.30 or later) or TOKEN keyword in the key type parameters requires
that the key tokens already exist when the verb is called, so the information in those tokens can be
used to determine the key type. In general, unless you are using the AESTOKEN or TOKEN keyword,
you must identify a null key token in the generated key identifier parameters on input.
Note: The generated_key_identifier_2 parameter is not used when generating only a single key and
should point to a null key-token.

Required commands
Depending on your specification of key form, key type, and use of the SINGLE-R key length control,
different commands are required to enable operation of the Key_Generate verb.
v If you specify the key-form and key-type combinations shown with an 'X' in the Key_Form OP column in
Table 37 on page 236, the Key_Generate verb requires the Generate Key command (offset X'008E') to
be enabled in the active role.
v If you specify the key-form and key-type combinations shown with an 'X' in the Key_Form IM column in
Table 37 on page 236, the Key_Generate verb requires the Generate Key Set command (offset X'008C')
to be enabled in the active role. The verb applies the restrictive rules of the IMEX column in Table 38 on
page 236 to the generation of the IM form key.
v If you specify the key-form and key-type combinations shown with an 'X' in the Key_Form EX column in
Table 37 on page 236, the Key_Generate verb requires the Generate Key Set command (offset X'008C')
to be enabled in the active role. The verb applies the restrictive rules of the EXEX column in Table 38
on page 236 to the generation of the EX form key.
v If you specify the key-form and key-type combinations shown with an 'X' in Table 38 on page 236, the
Key_Generate verb requires the Generate Key Set command (offset X'008C') to be enabled in the
active role.
v If you specify the key-form and key-type combinations shown with an 'E' in Table 38 on page 236, the
Key_Generate verb requires the Generate Key Set Extended command (offset X'00D7') to be enabled
in the active role.
v If you specify the SINGLE-R key-length keyword, the Key_Generate verb also requires the Replicate
Key command (offset X'00DB') to be enabled in the active role.
Note: A role with offset X'00DB' enabled can also use the Remote_Key_Export verb.
Related information
This section provides additional information about the key_type and key_length parameters.
Key-type specifications: Generated DES keys are enciphered with a key encrypting key or the DES
master key, exclusive-ORed with the control vector associated with that copy of the generated key. (See
Understanding DES and RSA key encryption and decryption processes on page 671). Generated AES
keys are enciphered with the AES master key.
There are two methods for specifying the type of keys to be generated:
v Specify key-type keywords as described in Table 37 on page 236 and Table 38 on page 236.
v Use the AESTOKEN or TOKEN keyword and provide a key token with the necessary information, so
that the verb can determine the key type and key length. For DES keys, this information is obtained
from the control vector in the token. For AES keys, the key length is an explicit field within the token,
and the only key type is AESDATA.
Use of the key type keywords for DES keys generates default control-vector values. See Table 162 on
page 657. One or two keywords are examined depending on the value in the key_form variable. Table 37
on page 236 shows the key type keywords you can use to generate a single-key copy, which will use
default control vectors if you are generating a DES key. Table 38 on page 236 shows the key types you
can use to generate two copies of a key. An 'X' indicates a permissible key type for a given key form. An
'E' indicates that a special (Extended) command is required as those keys require special handling.
A single-length DES key with any permissible control vector value can be generated by specifying SINGLE
and OP. In this case, the verb uses the Generate Key command (offset X'008E').
If you use the TOKEN key-type keyword and encode a DES key-type in a control vector supplied in the
key token, remember that non-default control vector values for the key type can be employed. Certain key

type keywords have an asterisk (*) in the tables below indicating that these keywords are not recognized
by the verb as key type specifications. Nevertheless, those key types are supported when supplied as
control vector values.
Table 37. Key_type and key_form keywords for one key
key_type_1 key_form OP key_form IM key_form EX
AESDATA X
DATA X X X
MAC X X X
PINGEN X X X
DATAC * X X X
DATAM *
DATAMV *
KEYGENKY *
DKYGENKY *
SECMSG *
Notes:
1. AESDATA is for AES keys only. All other key types are for DES keys only.
2. AESDATA is for Release 3.30 or later.
3. The DES key types marked with an '*' must be requested through the specification of a proper control vector in a
key token and the use of the TOKEN keyword.
| 4. An 'X' indicates a permissible key type for a given key form.
Table 38. Key_type and key_form keywords for a DES key pair
key_form
OPOP, OPIM, key_form key_form key_form
key_type_1 key_type_2 IMIM OPEX EXEX IMEX
DATA DATA X X X X
MAC MAC
MAC MACVER
MACVER MAC
DATAC * DATAC *
DATAM * DATAM *
DATAM * DATAMV *
DATAMV * DATAM *
CIPHER CIPHER
CIPHER DECIPHER
CIPHER ENCIPHER
DECIPHER CIPHER
DECIPHER ENCIPHER
ENCIPHER CIPHER
ENCIPHER DECIPHER
KEYGENKY * KEYGENKY *
DKYGENKY * DKYGENKY *
EXPORTER IMPORTER X X X
IMPORTER EXPORTER
EXPORTER IMP-PKA *
IMP-PKA * EXPORTER
EXPORTER IKEYXLAT
IKEYXLAT EXPORTER
IKEYXLAT OKEYXLAT
IMPORTER OKEYXLAT
OKEYXLAT IMPORTER
OKEYXLAT IKEYXLAT
PINGEN PINVER
PINVER PINGEN

Table 38. Key_type and key_form keywords for a DES key pair (continued)
key_form
OPOP, OPIM, key_form key_form key_form
key_type_1 key_type_2 IMIM OPEX EXEX IMEX
OPINENC IPINENC E X X X
IPINENC OPINENC
OPINENC OPINENC X
CVARDEC * CVARENC * E E
CVARENC * CVARDEC *
CVARENC * CVARXCVL *
CVARENC * CVARXCVR *
CVARXCVL * CVARENC *
CVARXCVR * CVARENC *
CVARDEC * CVARPINE *
CVARPINE * CVARDEC *
Notes:
1. AES keys cannot be generated in pairs.
2. The key types marked with an '*' must be requested through the specification of a proper control-vector in a key token and the
use of the TOKEN keyword.
| 3. An 'X' indicates a permissible key type combination for a given key form. An 'E' indicates that a special (Extended) command is
| required as those keys require special handling.
Key-length specification: The key_length parameter is a pointer to a string variable that specifies the
length of the generated key. It contains either a keyword or eight space characters. The key length
specified must be consistent with the key length indicated by the token you supply. For DES keys, this
length is a field in the control vector. For AES keys, the length is an explicit field in the token.
Table 39 on page 238 shows the valid key lengths for each key type. An X indicates that a key length is
permitted for a key type and a D indicates the default key-length that the verb uses when you supply
eight space characters with the key_length parameter.

Table 39. Key lengths by AES and DES key-type
Key type SINGLE, KEYLN8 SINGLE-R DOUBLE, KEYLN16
DES key lengths
MAC X, D X X
MACVER X, D X X
DATA X, D X X
DATAC * X X X
DATAM * X X X
DATAMV * X X X
EXPORTER X X, D
IMPORTER X X, D
IKEYXLAT X X, D
OKEYXLAT X X, D
CIPHER X, D X X
DECIPHER X, D X X
ENCIPHER X, D X X
DKYGENKY X X, D
IPINENC X X, D
OPINENC X X, D
PINGEN X X, D
PINVER X X, D
CVARDEC * X X X
CVARENC * X X X
CVARPINE * X X X
CVARXCVL * X X X
CVARXCVR * X X X
KEYGENKY * X X X
AES key lengths
Key type KEYLN16 KEYLN24 KEYLN32
AESDATA X X X
| Notes:
| 1. The DES key types marked with an '*' must be requested through the specification of a proper control-vector in a key token and
| the use of the TOKEN keyword.
| 2. An 'X' indicates that a key length is permitted for a key type.
| 3. A 'D' indicates the default key-length that the verb uses when you supply eight space characters with the key_length parameter.

Key_Generate2 (CSNBKGN2)
| Use the Key_Generate2 verb to randomly generate a keyed hash message authentication code (HMAC)
| key or, beginning with Release 4.2, an AES key. Depending on the key form specified, the verb returns
| either one or two enciphered copies of the key, each in a variable-length symmetric key-token. Key tokens
| can be returned to either application storage or AES key storage. To generate keys that are returned in a
| fixed-length symmetric key-token, see Key_Generate (CSNBKGN) on page 229. In releases before
| Release 4.2, the Key_Generate2 verb is limited to selectively returning one or two copies of an HMAC key
| enciphered under the AES master-key. Beginning with Release 4.2, the verb is enhanced to selectively
| return one or two copies of an AES or an HMAC key enciphered under the AES master-key or an AES
| key-encrypting key. Keys enciphered under the master key are immediately usable at the local node.
| The verb can create default key tokens, update the key in existing key tokens, or complete skeleton key
| tokens. The Key_Token_Build2 verb can be used to build a skeleton key-token. See page 275.
| Beginning with Release 4.2, an access control point can be turned on to disallow the wrapping of a key
| with a weaker key-encrypting key. See Required commands on page 243.
| Note: Variable-length symmetric key tokens have an associated data section that contains clear data. This
| section is hashed and the hash value is cryptographically bound to its enciphered payload. See
| Variable-length symmetric key-token on page 614.

| v Two required rule array keywords
| A required token algorithm keyword that selects the type of algorithm that the key can be used for,
| either AES (Release 4.2 or later) or HMAC
| A required key form keyword that selects the number of keys to return, either one or two, and the
| token type for each key, either internal or external
| v The number of bits of clear-key data to randomly generate and return encrypted in the generated key or
| keys
| AES keys can be 128, 192, or 256 bits
| HMAC keys can be 80 - 2048 bits
| Any generated key will have the specified key length.
| v The key types of each key to be returned
| AES keys have key types of:
| CIPHER
| EXPORTER and IMPORTER
| HMAC keys have a key type of MAC
| A key type of TOKEN indicates that the generated key token provided as input is to be updated
| Notes:
| 1. When generating only one copy of the key, use eight space characters for the second key-type
| variable.
| 2. To update an existing key token with a copy of the randomly generated key, specify keyword
| TOKEN as the key type and identify the key token to be updated using the
| generated_key_identifier_n parameter.
| 3. If the key type is not TOKEN, the generated_key_identifier_n parameter must have a length of zero
| or point to a null key-token. This results in a key token with default key-usage and key-management
| fields.
| v The optional key name (label), up to 64 bytes, of one or both keys that is to be placed in the associated
| data of the key token; if provided, this data overrides any label in the input generated key token
| v The optional user-defined associated data, up to 255 bytes, of one or both keys that is to be placed in
| the associated data of the key token; if provided, this data overrides any user-defined associated data in
| the input generated key token

| Note: A user_associated_data_n variable that contains data overrides any user-defined associated data
| contained in a key token to be updated.
| v A key-encrypting key (KEK) identifier of key type EXPORTER (EX) or IMPORTER (IM) key, contained in
| an internal variable-length symmetric key-token, for wrapping each external key to be returned
| v The key identifier for each key to be generated
Restrictions
| AIX X
| IBM i X
| Windows
|
| v Token algorithm keyword AES and key form keywords EX, IM, OPEX, OPIM, IMIM, IMEX, and EXEX
| are not supported in releases before Release 4.2.
| v Support for external keys and key-encrypting keys is not available in releases before Release 4.2.
| v The Generate Key Set command (offset X'008C') and the Disallow Weak Key Wrap (offset X'0328')
| commands are not defined in releases before Release 4.2.
Format
CSNBKGN2
| clear_key_bit_length Input Integer 128, 192, 256 (AES), 80 - 2048 (HMAC)
| key_name_1_length Input Integer 0 or 64
key_name_1 Input String key_name_1_length bytes
| key_name_2_length Input Integer 0 or 64
key_name_2 Input String key_name_2_length bytes
user_associated_data_1_length Input Integer 0 - 255
user_associated_data_1 Input String user_associated_data_1_length bytes
user_associated_data_2_length Input Integer 0 - 255
user_associated_data_2 Input String user_associated_data_2_length bytes
| KEK_key_identifier_1_length Input Integer See Appendix B.
KEK_key_identifier_1 Input String KEK_key_identifier_1_length bytes
| KEK_key_identifier_2_length Input Integer See Appendix B.
KEK_key_identifier_2 Input String KEK_key_identifier_2_length bytes

| generated_key_identifier_1_length In/Output Integer See Appendix B.

generated_key_identifier_1 In/Output String generated_key_identifier_1_length bytes
| generated_key_identifier_2_length In/Output Integer See Appendix B.
generated_key_identifier_2 In/Output String generated_key_identifier_2_length bytes
Parameters
rule_array_count
rule_array
characters.
The rule-array keywords are:
|| Keyword Meaning
| Algorithm for which the key can be used (one required)
| AES (Rel. 4.2 or later) Generate an AES key token.
| HMAC Generate an HMAC key token.
| Key form (one required)
| EX (Rel. 4.2 or later) Return one copy of the key enciphered under an exporter KEK.
| IM (Rel. 4.2 or later) Return one copy of the key enciphered under an importer KEK.
| OP Return one copy of the key enciphered under the AES master key.
| OPEX (Rel. 4.2 or later) Return two copies of the key, the first enciphered key under the AES master key
| and the second under an exporter key-encrypting key.
| OPIM (Rel. 4.2 or later) Return two copies of the key, the first enciphered key under the AES master key
| and the second under an importer key-encrypting key.
| OPOP Return two copies of the key, both enciphered under the AES master key.
| EXEX (Rel. 4.2 or later) Return two copies of the key, both enciphered under exporter key-encrypting
| keys.
| IMEX (Rel. 4.2 or later) Return two copies of the key, the first enciphered under an importer
| key-encrypting key, and the second under an exporter key-encrypting key.
| IMIM (Rel. 4.2 or later) Return two copies of the key, both enciphered under importer key-encrypting
| keys.
|
clear_key_bit_length
| The clear_key_bit_length parameter is a pointer to an integer variable containing the number of
| clear-key bits to randomly generate and return encrypted in the generated key or keys. If a generated
| key token has a key type of TOKEN, this value overrides any key length contained in the key token.
| The value can be 128, 192, and 256 for AES keys (Release 4.2 or later), and 80 - 2048 for HMAC
| keys.
key_type_1 and key_type_2
These parameters are pointers to 8-byte string variables, each containing a keyword that is left aligned

and padded on the right with space characters. The keyword specifies the key type of the key being
generated. If a single copy of the key is being generated, parameter key_type_2 should contain eight
space characters.
| The verb can return each copy of the generated key in a default key token that it builds, or one that is
| provided. Keyword TOKEN indicates that the verb is to return an updated key token that contains the
| key-usage and key-management fields of the key token that is provided by the corresponding
| key_identifier_n parameter. A keyword other than TOKEN indicates that a null key-token is provided
| and that the verb is to build and return a default key-token for the key type specified.
| Table 40 on page 244 lists the keywords allowed when generating a single copy of the key (key_form
| EX, IM, or OP). Table 41 on page 244 lists the keyword combinations that are allowed when
| requesting two copies of the generated key.
key_name_1_length
| The key_name_1_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the key_name_1 variable. The value must be 0 or 64.
key_name_1
| The key_name_1 parameter is a pointer to a string variable containing the optional key label that is
| placed in the associated data of the key token identified by the generated_key_identifier_1 variable. If
| present, it must be a valid key label. This data is cryptographically bound to the first copy of the key.
key_name_2_length
| The key_name_2_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the key_name_2 variable. The value must be 0 or 64. For key form EX, IM, or OP, this
| value must be 0.
key_name_2
| The key_name_2 parameter is a pointer to a string variable containing the optional key label that is
| placed in the associated data of the key token identified by the generated_key_identifier_2 variable. If
| present, it must be a valid key label. This data is cryptographically bound to the second copy of the
| key.
user_associated_data_1_length
| The user_associated_data_1_length parameter is a pointer to an integer variable containing the
| number of bytes of data in the user_associated_data_1 variable. The value must be 0 - 255.
user_associated_data_1
The user_associated_data_1 parameter is a pointer to a string variable containing the optional
user-definable portion of the associated data to be included in the generated_key_identifier_1 token.
This data is cryptographically bound to the first copy of the generated key.
user_associated_data_2_length
| The user_associated_data_2_length parameter is a pointer to an integer variable containing the
| number of bytes of data in the user_associated_data_2 variable. The value must be 0 - 255. For key
| form EX, IM, or OP, the value must be 0.
user_associated_data_2
The user_associated_data_2 parameter is a pointer to a string variable containing the optional
user-definable portion of the associated data to be included in the generated_key_identifier_2 token.
This data is cryptographically bound to the second copy of the generated key.
KEK_key_identifier_1_length and KEK_key_identifier_2_length
| These are pointers to an integer variable containing the number of bytes of data in the
| KEK_key_identifier_1 or KEK_key_identifier_2 variable. For a key with a key form of OP, the value
| must be 0. For releases before Release 4.2, the value must be 0.
KEK_key_identifier_1 or KEK_key_identifier_2
| These parameters are pointers to string variables of AES internal key tokens or key labels of such key
| tokens that contain the key used to encipher generated keys that have a key form of IM or EX. If a
| KEK is not used, specify its length as 0.

generated_key_identifier_1_length
The generated_key_identifier_1_length parameter is a pointer to an integer variable containing the
number of bytes of data in the generated_key_identifier_1 variable. On input, this is the size of the
buffer. On output, the verb sets the variable to the length of the returned generated_key_identifier_1
variable.
generated_key_identifier_1
The generated_key_identifier_1 parameter is a pointer to a string variable containing the key token or
key label for the token that is to receive the first generated key. If the key_type_1 variable is a
keyword other than TOKEN, this parameter must be null or identify a null variable-length symmetric
key-token on input. If the key_type_1 variable specifies keyword TOKEN, the verb attempts to use the
information in the existing key token and updates the key value. If the key_type_1 variable specifies a
keyword other than TOKEN, the verb builds a default key token to receive the first copy of the
generated key. If the input_key_identifier_1 variable contains a key label, the verb updates AES
key-storage and does not return any data in this buffer.
generated_key_identifier_2_length
The generated_key_identifier_2_length parameter is a pointer to an integer variable containing the
number of bytes of data in the generated_key_identifier_2 variable. On input, this is the size of the
buffer. On output, the verb sets the variable to the length of the returned generated_key_identifier_2
variable.
generated_key_identifier_2
The generated_key_identifier_2 parameter is a pointer to a string variable containing the key token or
key label for the token that is to receive the second generated key. If the key form requests one copy
of the generated key, this parameter must be null or identify a null variable-length key token.
Otherwise, it is handled in the same manner as the generated_key_identifier_1 parameter.
Required commands
| The Key_Generate2 verb requires the Generate2 Key command (offset X'00EA') to be enabled in the
| active role when one key is returned (key form EX, IM, or OP). When two keys are returned (key form
| OPOP, OPIM, IMIM, OPEX, EXEX, or IMEX), the verb requires the Generate2 Key Set command (offset
| X'00EB') to be enabled in the active role.
| The following access control points are added beginning with Release 4.2:
| v To disallow the wrapping of a key with a weaker key-encrypting key, enable the Disallow Weak Key
| Wrap command (offset X'0328') in the active role. This command affects multiple verbs. See Table 169
| on page 715.
| v To receive a warning when wrapping a key with a weaker key-encrypting key, enable the Warn when
| Wrapping Weak Keys command (offset X'032C') in the active role. The Disallow Weak Key Wrap
| command overrides this command.
| Related information
| Key type specifications: Generated keys returned in an internal key-token are enciphered with the AES
| master key, while generated keys returned in an external key-token are enciphered under an AES
| key-encrypting key.
| There are two methods for specifying the type of keys to be generated:
| v Specify key-type keywords as described in Table 40 on page 244 and Table 41 on page 244.
| v Use the TOKEN keyword and provide a key token to be updated or a skeleton key-token to be
| completed.
| One or two key type keywords are examined depending on the value of the key form rule-array keyword.
| Table 40 on page 244 shows the permissible key type and key form keyword combinations to generate a
| single copy of a key. Table 41 on page 244 shows the permissible key type and key form keyword
| combinations to generate two copies of a key.

| Table 40. Key type and key form keywords for one AES or HMAC key
| key_type_1 Key form EX Key form IM Key form OP
| CIPHER X X X
| MAC
| Notes:
| 1. An "X" indicates a permissible key type for a given key form.
| 2. Key type CIPHER is not supported in releases before Release 4.2.
| 3. Key forms EX and IM are not supported in releases before Release 4.2.
|
| Table 41. Key type and key form keywords for a pair of AES or HMAC keys
| Key form
| OPOP,
| OPIM,
| key_type_1 (key usage) key_type_2 (key usage) IMIM OPEX EXEX IMEX
| CIPHER (DECRYPT and ENCRYPT) CIPHER (DECRYPT and ENCRYPT) X X X X
| CIPHER (DECRYPT and ENCRYPT) CIPHER (DECRYPT)
| CIPHER (DECRYPT and ENCRYPT) CIPHER (ENCRYPT)
| CIPHER (DECRYPT) CIPHER (DECRYPT and ENCRYPT)
| CIPHER (DECRYPT) CIPHER (ENCRYPT)
| CIPHER (ENCRYPT) CIPHER (DECRYPT and ENCRYPT)
| CIPHER (ENCRYPT) CIPHER (DECRYPT)
| MAC (GENERATE and VERIFY) MAC (GENERATE and VERIFY)
| MAC (GENERATE and VERIFY) MAC (VERIFY)
| MAC (VERIFY) MAC (GENERATE and VERIFY)
| IMPORTER EXPORTER X X X
| EXPORTER IMPORTER
| Notes:
| 1. An "X" indicates a permissible key type and key usage combination for a given key form.
| 2. The key usage attributes shown are those that are required. Key usage attributes that are not shown are optional.
| 3. Key types CIPHER, EXPORTER, and IMPORTER are not supported in releases before Release 4.2.
| 4. Key forms EXEX, IMIM, and OPIM are not supported in releases before Release 4.2.
|
|

Key_Import (CSNBKIM)
Use the Key_Import verb to import a source DES key, key-token, or key-token record enciphered by the
IMPORTER key-encrypting key into a target internal fixed-length DES key-token. The imported target-key
is returned enciphered using the DES symmetric master-key.

key_type
A keyword for the key type. Use of the TOKEN keyword is the preferred coding style. For
compatibility with older systems, however, you can explicitly name a key type, in which case the
key type must match the key type encoded in the control vector of the source key-token.
source_key_token
An external key-token or an encrypted external key to be imported. When you import an
enciphered key that is not in an external key-token, the key must be located at offset 16 (X'10') of
a null key-token. (The first byte of a null key-token is X'00'.)
An IMPORTER key-encrypting key under which the target key is deciphered.
An internal or null key-token, or the key label of an internal or null key-token record in DES
key-storage.
The verb builds or updates the target key-token as follows:

v If the source key is not in an external key-token:
You must specify an explicit key type (not TOKEN).
The default CV for the key type is used when decrypting the source key.
The default CV for the key type is used when encrypting the target key.
The target key-token must either be null or must contain valid, nonconflicting information.
The key token is returned to the application or DES key-storage with the imported key.
v If the source key is in an external key-token:
When an explicit key type keyword other than TOKEN is used, it must be consistent with the key
type encoded in the source-key control vector.
The control vector in the source key-token is used in decrypting the source key.
The control vector in the source key-token is used in encrypting the source key under the master
key. A source key having the default external DATA control vector (8 or 16 bytes of X'00') results in a
target key with the default internal DATA control vector.
The key token is returned to the application or DES key-storage with the imported key.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Unless you enable the Unrestrict Reencipher to Master Key command (offset X'027B'), an IMPORTER
key-encrypting key having equal key-halves is not permitted to import a key having unequal key-halves.
Key parity bits are ignored.

Format
CSNBKIM
importer_key_identifier Input String 64 bytes
Parameters
key_type
The key_type parameter is a pointer to a string variable containing an 8-byte keyword, left-aligned,
and padded on the right with space characters, that specifies the key type of the key to be imported.
In general, you should use the TOKEN keyword.
CIPHER IKEYXLAT OKEYXLAT

DATA IMPORTER OPINENC
DECIPHER IPINENC PINGEN
ENCIPHER MAC PINVER
EXPORTER MACVER TOKEN
source_key_token
The source_key_token parameter is a pointer to a string variable containing the external CCA source
DES key-token. Ordinarily the source key-token is an external fixed-length DES key-token (the first
byte of the key-token data structure contains X'02'). However, if the first byte of the token is X'00', then
the encrypted source-key is taken from the data at offset 16 (X'10') in the source key-token structure.
The importer_key_identifier parameter is a pointer to a string variable containing the key-token or key
label for the IMPORTER (transport) key-encrypting key.
The target_key_identifier parameter is a pointer to a string variable containing the internal target
fixed-length DES key-token or key label of a DES key-token record.
Required commands
The Key_Import verb requires the Reencipher to Master Key command (offset X'0012') to be enabled in
the active role.
By also enabling the Unrestrict Reencipher To Master Key command (offset X'027B'), you can permit a
less secure mode of operation that enables an equal key-halves IMPORTER key-encrypting key to import
a key having unequal key-halves (key parity bits are ignored).

Key_Part_Import (CSNBKPI)
Use the Key_Part_Import verb to accumulate parts of a DES key and store the result as an encrypted
partial key or as the final key in an internal fixed-length DES key-token. Individual key parts are
exclusive-ORed together to form the accumulated key.
On each call to Key_Part_Import (except COMPLETE, see below), specify 8 bytes or 16 bytes of clear-key
information based on the length of the key that you are accumulating. Align an 8-byte clear key in the
high-order (leftmost) bytes of a 16-byte field. Also specify an internal key-token in which the key
information is accumulated. The key token must include a control vector. The control vector defines the
length of the key, 8 or 16 bytes (single length or double length). The control vector must have the
KEY-PART bit set on. The verb returns the accumulated key information as a master-key-encrypted value
in the updated key-token.
Beginning with Release 4.1, an optional key-wrapping method and an optional translation-control setting
can be specified.
You can use the Key_Token_Build verb to create the internal key-token into which the first key-part is
imported.
On each call to Key_Part_Import, also specify a rule-array keyword to define the verb action: FIRST,
MIDDLE, LAST, ADD-PART, or COMPLETE.
v With the FIRST keyword, the verb requires that the input key-token be a skeleton. Each byte of the
8-byte or 16-byte key-part should have the low-order bit set such that the byte has an odd number of
one-bits, otherwise assuming no other problems, the verb returns reason code 2. Use of the FIRST
keyword requires that the Load First Key Part command be enabled in the access-control system.
v With the MIDDLE keyword, the verb exclusive-ORs the clear key-part with the (internally decrypted) key
value from the input key-token. Each byte of the 8-byte or 16-byte key-part should have the low-order
bit set such that the byte has an even number of one-bits. If any byte in the updated key has an even
number of one bits, and there are no other problems, the verb returns reason code 2. Use of the
MIDDLE keyword requires that the Combine Key Parts command be enabled in the access-control
system. The key-part bit remains on in the control vector of the updated key token returned from the
verb.
v With the LAST keyword, the verb exclusive-ORs the clear key-part with the (internally decrypted) key
value in the input key-token. Each byte of the 8-byte or 16-byte key-part should have the low-order bit
set such that the byte has an even number of one-bits. If any byte in the updated key has an even
number of one bits, and there are no other problems, the verb returns reason code 2. This use of the
LAST keyword requires that the Combine Key Parts command be enabled in the access-control system.
The key-part bit is set off in the control vector of the updated key token returned from the verb.
v With the ADD-PART keyword, the verb exclusive-ORs the clear key-part with the (internally decrypted)
key value in the input key-token. Each byte of the 8-byte or 16-byte key-part should have the low-order
bit set such that the byte has an even number of one-bits. If any byte in the updated key has an even
number of one bits, and there are no other problems, the verb returns reason code 2. Use of the
ADD-PART keyword requires that the Add Key Part command be enabled in the access-control system.
The key-part bit remains on in the control vector of the updated key token returned from the verb.
v With the COMPLETE keyword, the key-part bit is set off in the control vector of the updated key token
returned from the verb. Use of the COMPLETE keyword requires that the Complete Key Part command
be enabled in the access-control system. The 16-byte key_part variable must be declared but is
ignored.
Notes:
1. If your input creates a key value with one or more bytes with an even number of one bits, that is an
out-of-parity key, and the verb returns a reason-code value of 2. Many verbs check the parity of keys
and, if the key does not have odd parity in each key-byte, might return a warning or might terminate
without performing the requested operation. In general, out-of-parity DATA keys are tolerated.

2. You can enforce a dual-control security policy by employing the FIRST, ADD-PART, and COMPLETE
keywords. See Required commands on page 250. New applications should employ the ADD-PART
and COMPLETE keywords in lieu of the MIDDLE and LAST keywords in order to ensure a separation
of responsibilities between someone who can add key-part information and someone who can declare
that appropriate information has been accumulated in a key. Consider using the Key_Test verb to
ensure a correct key-value has been accumulated prior to using the COMPLETE option to mark the
key as fully operational.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v A typical double-length DES key has unequal left and right halves (ignoring parity bits). A replicated key
| is defined as a double-length DES key having equal left and right halves. Such a key performs as a
| single-length key. See DES replicated keys on page 731. Security is weakened if it is possible to
| convert an unreplicated key into a replicated key or the other way around. To prevent this security
| exposure, the Key_Part_Import verb restricts a key from being changed from replicated to unreplicated,
| or from unreplicated to replicated:
| If an input key has replicated key halves, and the key part being added results in an unreplicated
| key, an error is returned. An exception to this rule is if the input key is all binary zeros.
| If an input key has unreplicated key halves, and the key part being added results in a replicated key,
| an error is returned.
| The error returned by the verb is return code 8, reason code 2062 (X'80E'), "The active role does not
| permit you to change the characteristic of a double-length key in the Key_Part_Import parameter."
| An access-control point is available to allow any key part to be added. To disable the restriction on
| changing the characteristic of a double-length key, enable the Unrestrict Combine Key Parts command
| (offset X'027A') in the active role. Enabling this offset results in a less secure operation, and is not
| recommended.
v The USECONFG, WRAP-ECB, and WRAP-ENH rule-array keywords are not supported in releases
before Release 4.1.
Format
CSNBKPI
key_part Input String 16 bytes
key_identifier In/Output String 64 bytes

Parameters
rule_array_count
rule_array
characters.
The rule_array keywords are shown below:
Keyword Meaning
Key part (one required)
FIRST Specifies that an initial key-part is provided. The verb returns this key-part encrypted by the
master key in the key token which you supplied.
ADD-PART Specifies that additional key-part information is provided. The verb exclusive-ORs the key part
into the key information held encrypted in the key token.
COMPLETE Specifies that the key-part bit shall be turned off in the control vector of the key rendering the
key fully operational. No key_part information is added to the key with this keyword.
MIDDLE Specifies that an intermediate key-part, which is neither the first key-part nor the last key-part, is
provided. The verb exclusive-ORs the key part into the key information held encrypted in the key
token. The command control point for this keyword is the same as that for the LAST keyword
and different from that for the ADD-PART keyword.
LAST Specifies that the last key-part is provided. The verb exclusive-ORs the key part into the key
information held encrypted in the key token. The key-part bit is turned off in the control vector.
USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. This is
the default.
WRAP-ENH Specifies to wrap the key using the enhanced wrapping method.
key_part
The key_part parameter is a pointer to a string variable containing a clear DES key-part to be entered.
The key part might be either 8 or 16 bytes in length. For 8-byte keys, place the key part in the
high-order bytes of the 16-byte key-part field. The information in this variable must be defined but are
ignored by the coprocessor when you use the COMPLETE rule-array keyword.
key_identifier
The key_identifier parameter is a pointer to a string variable containing the internal fixed-length DES
key-token or a key label for an internal fixed-length DES key-token. The key token must not be null
and does supply the control vector for the partial key.

Required commands
The Key_Part_Import verb requires the following commands to be enabled in the active role:

FIRST X'001B' Load First Key Part
ADD-PART X'0278' Add Key Part
COMPLETE X'0279' Complete Key Part
MIDDLE or LAST X'001C' Combine Key Parts
WRAP-ECB or WRAP-ENH and X'0140' Allow Configuration Override with Keyword in KPI
default key-wrapping method setting
does not match keyword (Release 4.1
or later)
The Key_Part_Import verb enforces the key-halves restriction documented above when the Unrestrict
Combine Key Parts command (offset X'027A') is disabled in the active role. Enabling this command results
in less secure operation and is not recommended.

Key_Part_Import2 (CSNBKPI2)
| Use the Key_Part_Import2 verb to accumulate one or more parts of an HMAC key and, beginning with
| Release 4.2, an AES key, from clear key part data and any previously accumulated key parts recovered
from an internal variable-length symmetric key-token, and store the result as an encrypted partial key or as
the final key in an internal variable-length symmetric key-token. Individual key parts are exclusive-ORed
| together to form the accumulated key. The key is encrypted under the AES master key. See also
| Key_Part_Import.
| On each call to Key_Part_Import2, specify the number of bits to use for the clear key-part. For keyword
| COMPLETE this number must be 0. Place the clear key-part left-aligned in the clear_key_part variable,
| and specify the number of bits of clear_key_part data using the clear_key_part_bit_length variable. For
| any number not a multiple or eight, any extraneous bits of clear_key_part data will be ignored when the
| verb encrypts the key. Also specify an internal variable-length symmetric key-token in which the key
| information is accumulated. Use the Key_Token_Build2 verb to create the key-token skeleton into which
| the first key part is imported. After the FIRST key part, each accumulated clear key-part must have the
| same clear-key bit length and the key token must have the key-management field 2 set to indicate that the
| key is incomplete. For key-part keyword FIRST, key-management field 2 is ignored and overwritten with
| the value determined by the split-knowledge keyword. ADD-PART and COMPLETE cause the
| key-management field 2 to be updated.
Here is a summary of the three scenarios for importing key parts, based on rule-array keywords,
key-management field 2, and access-control command:
Key-management Key-mangement
field 2 input field 2 output
Rule-array keyword(s) (high-order byte) (high-order byte) Required access control command
Scenario 1: Minimum three required parts
FIRST, MIN3PART Ignored B'1100 0000' Import Minimum Three Parts
ADD-PART B'1100 0000' B'1000 0000' Import Second of Three or More Parts
ADD-PART B'1000 0000' B'0100 0000' Import Last Minimum Required Part
ADD-PART B'0100 0000' B'0100 0000' Import Optional Part
COMPLETE B'0100 0000' B'0000 0000' Complete Import of Key Parts
Scenario 2: Minimum two required parts
FIRST, MIN2PART Ignored B'1000 0000' Import Minimum Two Parts
ADD-PART B'1000 0000' B'0100 0000' Import Last Minimum Required Part
Scenario 3: Minimum one required part
FIRST, MIN1PART Ignored B'0100 0000' Import Minimum One Part
Notes:
1. Any number of optional key parts can be imported; there is no maximum.
2. The user who imports the first key part sets the minimum number of required key parts for that key.
| 3. For keyword FIRST, the key token identified by the key_identifier parameter must be a skeleton
| key-token.
4. For keyword COMPLETE, the clear_key_part_bit_length variable must be zero.

The verb returns the accumulated key information as an encrypted value in the updated key-token. After
all clear key-parts have been accumulated, use the COMPLETE keyword to make the key fully
operational.
On each call to Key_Part_Import2, also specify a rule-array keyword to define the verb action: FIRST,
ADD-PART, or COMPLETE.
v With the FIRST keyword, the verb requires that the input key-token be a skeleton. Use of the FIRST
keyword requires that one of the following access control commands be enabled in the access-control
system: Import Minimum Three Parts, Import Minimum Two Parts, or Import Minimum One Part.
v With the ADD-PART keyword, the verb exclusive-ORs the clear key-part with the (internally decrypted)
key value in the input key-token. The key token must have the key-management bit set to indicate that
the key is not complete. Use of the ADD-PART keyword requires that the Import Second of Three or
More Parts, Import Last Minimum Required Part, or Import Optional Part command be enabled in the
access-control system. The key remains incomplete in the updated key token returned from the verb.
v With the COMPLETE keyword, the key key-management bit is changed from not complete to complete,
and the key becomes complete and fully operational. Use of the COMPLETE keyword requires that the
Complete Import of Key Parts command be enabled in the access-control system. The
clear_key_part_bit_length variable must be set to zero.
Note: You can enforce a dual-control, split-knowledge security policy by employing the FIRST,
ADD-PART, and COMPLETE keywords. See Required commands on page 255. With the FIRST
keyword, one of the three split-knowledge keywords is required. The ADD-PART and COMPLETE
keywords ensure a separation of responsibilities between someone who can add key-part
information and someone who can declare that appropriate information has been accumulated in a
key. Consider using the Key_Test2 verb to ensure that a correct key-value has been accumulated
prior to using the COMPLETE option to mark the key as fully operational.
Restrictions

| AIX X
| IBM i X
| Windows
|
| v Rule-array keyword AES is not supported in releases before Release 4.2.
| v Key types CIPHER, EXPORTER, and IMPORTER are not supported in releases before Release 4.2.

Format
CSNBKPI2
| clear_key_part_bit_length Input Integer 0; 128, 192, or 256 (AES); 80 - 2048 (HMAC)
clear_key_part Input String (clear_key_part_bit_length + 7) / 8 bytes
| key_identifier_length In/Output Integer See Appendix B.
Parameters
rule_array_count
in the rule_array variable. The value must be 2 if it is not the FIRST key part, or 3 if it is the FIRST
key part.
rule_array

Keyword Meaning
Token algorithm (one required)
| AES (Rel. 4.2 or Specifies to import an AES key.
later)
HMAC Specifies to import an HMAC key.
Key part (one required)
| FIRST Specifies that an initial clear key-part is provided. The verb returns this key part, encrypted
| by the AES master key, in the key token supplied. The input key-token must be a skeleton.
ADD-PART Specifies that additional clear key-part information is provided. The verb exclusive-ORs the
key part into the key information held encrypted in the key token. Requires key
completeness value greater than zero. Subtracts one from key completeness if value is
greater than B'01'; if value is B'01', value does not get changed.
COMPLETE Specifies to change the key completeness value from not complete to complete. No key-part
information is added to the key with this keyword. Requires key completeness value of B'01'.
Value is changed to B'00', rendering the key fully operational.
Split knowledge (one required). Use only with keyword FIRST.
MIN3PART Specifies that the key must be entered in at least three parts. This enforces a
split-knowledge security policy. Sets key completeness bits to B'11'.
MIN2PART Specifies that the key must be entered in at least two parts. This enforces a split-knowledge
security policy. Sets key completeness bits to B'10'.
MIN1PART Specifies that the key must be entered in at least one part. This does not enforce a
split-knowledge security policy. Sets key completeness bits to B'01'.
| Note: Unlike the Key_Part_Import verb, which requires the first key to be incomplete (that is, for the
| KEY-PART bit to be on) for keyword FIRST, Key_Part_Import2 does not require the first key to
| be incomplete. It instead overwrites the key-completeness bits of key-management field 2
| based on the split-knowledge keyword
clear_key_part_bit_length
The clear_key_part_bit_length parameter is a pointer to an integer variable containing the number of
clear-key bits in the clear_key_part variable. For keywords FIRST and ADD-PART, this value must be
| 128, 192, or 256 for an AES key, and 80 - 2048 for an HMAC key. This value must be zero for
key-part keyword COMPLETE.
clear_key_part
| The clear_key_part parameter is a pointer to a string variable containing the key to be imported. When
| the clear_key_bit_length variable is not a multiple of 8, left align the clear_key_part value in the
| variable. Any extra bits are ignored when the key is encrypted.
The key_identifier_length parameter is a pointer to a string variable containing the number of bytes of
data in the key_identifier variable. If the key_identifier variable contains a key label, the length must be
64. Otherwise, the length must be large enough to hold the input key token and to receive the
expected output key token. On output, the value of this variable is updated to contain the actual length
of the key_identifier imported by the verb.
key_identifier
The key_identifier parameter is a pointer to a string variable containing an internal variable-length
| symmetric key-token or a key label identifying a key-storage record for such a token. If a key label
identifies a key record in AES key-storage, the returned key token replaces any key token associated
with that label. If the first byte of the identified string does not indicate a key label (that is, not in the
range X'20' - X'FE'), and the variable is of sufficient length to receive the result, then the key token is
returned in the identified variable.

Required commands
The Key_Part_Import2 verb requires the following commands to be enabled in the active role, based on
the rule-array key-part keyword and the key completeness setting of the key-management field 2:
Key-management field 2
Rule-array keyword (high-order byte) on input Offset Access control command
FIRST and MIN3PART Ignored X'0297' Import Minimum Three Parts
FIRST and MIN2PART Ignored X'0298' Import Minimum Two Parts
FIRST and MIN1PART Ignored X'0299' Import Minimum One Part
ADD-PART B'1100 0000' X'029A' Import Second of Three or More Parts
B'1000 0000' X'029B' Import Last Minimum Required Part
B'0100 0000' X'029C' Import Optional Part
COMPLETE B'0100 0000' X'029D' Complete Import of Key Parts

Key_Test (CSNBKYT)
| Use the Key_Test verb to generate or verify the value of either a master key, an internal AES key or
| key-part, or an internal DES key or key-part. The verb supports a GENERATE option in which it computes
and returns a key verification pattern (KVP) for the specified key, and a VERIFY option in which it verifies
that a passed KVP is correct for the specified key. The KVP and the verification process do not reveal any
information about the value of the tested key, other than equivalency of two key values. Several
verification algorithms are supported.
See also Key_Test_Extended (CSNBKYTX) on page 265 for operating on external AES and DES keys
and key parts.
The verb supports testing of AES, APKA, DES, and PKA master keys, AES or DES clear keys or key
parts, and enciphered AES or DES keys or key parts (see Restrictions on page 257). Rule array
keywords are used to specify information about the source key that is not implicit from other verb
parameters.
When testing a master key, you use two sets of rule array keywords to indicate what key to test:
1. The AES-MK, APKA-MK, ASYM-MK, and SYM-MK master-key selector keywords select whether to
test the AES, APKA, PKA (asymmetric), or DES (symmetric) master key. Not specifying a master-key
selector keyword indicates that the DES (symmetric) and PKA (asymmetric) master keys (SYM-MK
and ASYM-MK) have the same value, and that you want to test that value.
2. The KEY-KM, KEY-NKM, and KEY-OKM key or key-part rule keywords select among the
current-master-key register, the new-master-key register, and the old-master-key register.
Several key test algorithms are supported by the verb. See Cryptographic key-verification techniques on
page 677. Some are implicitly selected based on the type of key you are testing, while others are optional
and selected by specifying a verification process rule keyword. With the verification process rule, you can:
1. Specify the ENC-ZERO keyword to encrypt a block of binary zeros with the specified key. The verb
returns the leftmost 32 bits of the encryption result as the verification pattern. The block that is
encrypted consists of 16 bytes of binary zeros for AES keys, and 8 bytes for DES and Triple-DES
keys. For AES, this method is valid only with the CLR-A128, CLR-A192, CLR-A256, and TOKEN
keywords. For DES, this method is valid only with the KEY-CLR, KEY-CLRD, KEY-ENC, and
KEY-ENCD keywords.
2. Specify the MDC-4 keyword to compute a 16-byte verification pattern using the MDC-4 algorithm. This
keyword is valid only when computing the verification pattern for a DES (symmetric) or PKA
(asymmetric) master key.
3. Specify the SHA-1 keyword to compute the KVP using the SHA-1 hashing method. This keyword is
valid only when computing the KVP for the DES (symmetric) or PKA (asymmetric) master-key.
4. Specify the SHA-256 keyword to compute the KVP using the SHA-256 hashing method. This keyword
is valid only when computing the KVP for an AES key or an AES-MK and APKA-MK master-key.
| Note: For historical reasons, the verification information is passed in two 8-byte variables pointed to by
| the value_1 and value_2 parameters. The GENERATE option uses these variables for output, and
| the VERIFY option uses these variables as input. For VERIFY, the verb returns a warning of return
| code 4, reason code 1 if the information provided in these variables does not match the calculated
| values.
| Table 42 on page 257 describes the use of the value_1 and value_2 variables for each of the available
| verification-process rules.

| Table 42. Key_Test GENERATE outputs and VERIFY inputs
| GENERATE outputs and VERIFY inputs
| Verification-process rule
| value_1 variable value_2 variable
| ENC-ZERO Unused Contains the 4-byte KVP in the
| high-order 4 bytes of the variable,
| taken from the high-order 4 bytes of
| the encrypted result. The low-order 4
| bytes of the variable are unspecified.
| MDC-4 Contains the 8-byte KVP taken from Contains the low-order 8 bytes of the
| the high-order 8 bytes of the MDC-4 MDC-4 hash value.
| hash value.
| SHA-1 Contains the 8-byte KVP taken from Contains the low-order 8 bytes of the
| the high-order 8 bytes of the SHA-1 SHA-1 hash value.
| hash value.
| SHA-256 Unused Contains the 8-byte KVP taken from
| the high-order 8 bytes of the
| SHA-256 hash value.
| No keyword, and first and third parts Same as SHA-1 Same as SHA-1
| of the master key have different
| values
| No keyword, and first and third parts Contains the 8-byte KVP taken from Unused
| of the master key have the same the result of the z/OS-based
| value master-key verification method.
|
| DES and Triple-DES keys reserve the low-order bit of each byte for parity. If parity is used, the low-order
bit is set so that the total number of '1' bits in the byte is odd. Parity adjustment keywords ADJUST and
NOADJUST allow you to control how the Key_Test verb handles the parity bits. Keyword NOADJUST,
which is the default, specifies not to alter the parity bit values in any way. Keyword ADJUST specifies to
modify the low-order bit of each byte as necessary for odd parity. This is done on the cleartext value of the
key before the verification pattern is computed. The parity adjustment is performed only on a temporary
copy of the key within the card, and does not affect the key value in the key_identifier parameter.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The Key_Test verb does not process external key tokens.
v AES keys and the AES-MK master-key selector keyword are not supported in releases before Release
3.30.
v The APKA-MK master-key selector keyword is not supported in releases before Release 4.1.

Format
CSNBKYT
key_identifier Input String 64 bytes
| value_1 In/Output String 8 bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
Process rule (one required)
GENERATE Generate a verification pattern for the specified key or key part.
VERIFY Verify that a verification pattern matches the specified key or key part.
Key or key-part rule (one required)
CLR-A128 (Rel. 3.30 Process a 128-bit AES clear key or clear key-part
or later)
or later)
or later)
KEY-CLR Process a single-length DES clear key or clear key-part.
KEY-CLRD Process a double-length DES clear key or clear key-part.
KEY-ENC Process a single-length DES enciphered key or enciphered key-part supplied in a key
token.
KEY-ENCD Process a double-length DES enciphered key or enciphered key-part supplied in a key
token.
KEY-KM Process the master key in the current-master-key register.
KEY-NKM Process the master key in the new-master-key register, which can be an incomplete key
if all key parts have not been loaded.
KEY-OKM Process the master key in the old-master-key register.

Keyword Meaning
TOKEN Process an AES clear or encrypted key contained in an AES key-token (Release 3.30 or
later).
Master-key selector (one, optional). Use only with KEY-KM, KEY-NKM, or KEY-OKM keywords. The default is to
process the ASYM-MK and SYM-MK key registers, which must have the same key values for the default to be
valid.
AES-MK (Rel. 3.30 or Process one of the AES master-key registers
later)
APKA-MK (Rel. 4.1 Process one of the AES PKA master-key registers
or later)
ASYM-MK Process one of the asymmetric PKA (RSA) master-key registers.
SYM-MK Process one of the symmetric (DES) master-key registers.
Parity adjustment (one, optional). Not valid with AES-MK or APKA-MK master-key selector keywords.
ADJUST Adjust the low-order bit in each key byte used in the key-test computation so that the
byte contains an odd number of one bits.
NOADJUST Do not alter the key-byte values. This is the default.
| Verification-process rule (one, optional). See Cryptographic key-verification techniques on page 677.
ENC-ZERO Specifies use of the encrypt zeros method. Use only with the CLR-A128, CLR-A192,
CLR-A256, KEY-CLR, KEY-CLRD, KEY-ENC, KEY-ENCD, or TOKEN keywords.
MDC-4 Specifies use of the MDC-4 master-key-verification method. Use only with KEY-KM,
KEY-NKM, or KEY-OKM keywords. You must specify either the ASYM-MK or SYM-MK
master-key selector keyword to use this keyword.
SHA-1 Specifies use of the SHA-1 master-key-verification method. Use only with KEY-KM,
SHA-256 (Rel. 3.30 Specifies use of the SHA-256 master-key-verification method. This is valid only with AES
or later) keys and the AES and APKA master keys. This is the default for AES keys, and for
master-key selector keywords AES-MK and APKA-MK.
| No keyword, and first Defaults to the use of the SHA-1 master-key verification method when the ASYM-MK or
| and third parts of the SYM-MK master-key selector keyword is specified.
master key have
different values.
| No keyword, and first Defaults to the use of the IBM z/OS-based master-key verification method when the
| and third parts of the ASYM-MK or SYM-MK master-key selector keyword is specified.
master key have the
same value.
key_identifier
The key_identifier parameter is a pointer to a string variable containing an internal fixed-length AES or
DES key-token, a key label that identifies an internal fixed-length key-token record in AES or DES
key-storage, or a clear key. This parameter should point to a null DES key-token for rule-array
keywords KEY-KM, KEY-NKM, and KEY-OKM.
The key token contains the key or the key part used to generate or verify the KVP.
When you specify the KEY-CLR keyword, the clear key or clear key-part must be stored in bytes 0 - 7
of the key identifier. When you specify the KEY-CLRD keyword, the clear key or clear key-part must
be stored in bytes 0 - 15 of the key_identifier variable. When you specify the KEY-ENC or the
KEY-ENCD keyword, the enciphered key or enciphered key-part must be in a fixed-length DES
key-token.

Beginning with Release 3.30, when you specify the CLR-A128 keyword, the clear key or clear key-part
must be stored in bytes 0 - 15 of the key_identifier. For CLR-A192, it must be in bytes 0 - 23. For
CLR-A256, it must be in bytes 0 - 31.
| value_1
| The value_1 parameter is a pointer to a string variable. See Table 42 on page 257 for how this
| variable is used. For process rule GENERATE this parameter is output only, and for process rule
| VERIFY it is input only. This variable must be specified, even if it is not used.
| value_2
| VERIFY it is input only. This variable must be specified, even if it is not used.
Required commands
The Key_Test verb requires the Compute Verification Pattern command (offset X'001D') to be enabled in
the active role.

Key_Test2 (CSNBKYT2)
| Use the Key_Test2 verb to verify the value of an enciphered or clear key or key part. Before Release 4.2,
| the key must be in an HMAC internal variable-length symmetric key-token. Beginning with Release 4.2,
| key-encrypting keys are supported, along with support for the AES and DES algorithms. With this support,
| an HMAC key can be in an external variable-length symmetric key-token, provided that a suitable
| key-encrypting key is provided. Likewise, an AES key can either be in (1) an external or internal AES
| variable-length symmetric key-token (version X'05'), or (2) in an internal fixed-length symmetric key-token
| (version X'04'). A DES key can either be in (1) an external or internal fixed-length CCA key-token, or (2) an
| external TR-31 key block.
| The verb supports a GENERATE option in which it computes and returns a key verification pattern (KVP)
| for a specified key based on a KVP calculation algorithm keyword. The verb also supports a VERIFY
| option, based on the same KVP calculation algorithm keyword, in which it verifies that a passed KVP is
| correct for the specified key. Neither the KVP nor the verification process reveal any information about the
| value of the tested key, other than equivalency of two key values. Several KVP calculation algorithms are
| supported.
| Rule array keywords are used to specify information about the target key that is not implicit from other
| verb parameters.

| 1. Two required, two optional, and one optional or required keyword depending on the KEK identified by
| the KEK_key_identifier parameter:
| v A required token algorithm keyword for the type of algorithm for which the key can be used, either
| AES, DES, or HMAC
| v A required process rule keyword, depending on whether the verb is to generate or verify a KVP for
| the key or key part
| v An optional KVP calculation algorithm. Each token algorithm has its own default KVP calculation
| method. The AES algorithm is the only one that has a choice of KVP calculation algorithm, either
| ENC-ZERO or SHA-256. If ENC-ZERO is specified for AES, the Compute ENC-ZERO Verification
| Pattern for AES command (offset X'0021') must be enabled in the active role.
| v A token type rule keyword that is only used when the DES token algorithm is specified and the input
| key is a TR-31 key block, in which case the token type rule keyword TR-31 must be specified. This
| keyword is needed because a TR-31 key block is ASCII data and cannot always be distinguished
| from a DES key label.
| v A KEK identifier rule keyword that is required if the KEK_key_identifier parameter identifies an RSA
| key-encrypting key, otherwise the keyword is optional
| Do not specify a KEK identifier rule keyword if the key being tested is in an internal key-token. This
| keyword is only for when the input key is in an external key-token. It serves the purpose of
| identifying which key-storage dataset contains the key-encrypting key when a key label is passed in
| the KEK_key_identifier variable.
| 2. An internal or external key-token containing a key to be tested, or the label of such a key
| v For AES, the key must either be in an internal version X'04' fixed-length AES key-token, or in an
| external or internal version X'05' variable-length symmetric key-token.
| v For DES, the key must either be in an external or internal fixed-length CCA key-token, or it must be
| in a TR-31 key block. Do not use a label for a TR-31 key block.
| v For HMAC, the key must be in either be in an external or internal version X'05' variable-length
| symmetric key-token.
| 3. If the key being tested is in an external key-token, provide the key-encrypting key identifier of the key
| that was used to encipher the input key. If the KEK is in key storage, and the KEK is an RSA
| key-encrypting key, a KEK identifier rule keyword is required.

Restrictions
| AIX X
| IBM i X
| Windows
|
| v The following rule array keywords are not supported in releases before Release 4.2:
| Token algorithm keywords AES and DES
| KVP calculation keywords ENC-ZERO and SHA-256
| Token type rule keyword TR-31
| v The key_identifier parameter must not identify a key label when the input key is in a TR-31 key block.
Format
CSNBKYT2
| rule_array_count Input Integer 2, 3, 4, or 5
key_identifier_length Input Integer See Appendix B.
key_identifier Input String key_identifier_length bytes
KEK_key_identifier_length Input Integer 0
KEK_key_identifier Input String KEK_key_identifier_length bytes
| reserved_length In/Output Integer 0
| reserved In/Output String reserved_length bytes
| key_verification_pattern_length In/Output Integer 8
key_verification_pattern In/Output String key_verification_pattern_length bytes
Parameters
rule_array_count
| in the rule_array variable. The value must be 2, 3, 4, or 5.

rule_array
|| Keyword Meaning
| Token algorithm (one required)
| AES (Rel. 4.2 or later) Specifies to test an AES key in a version X'04' internal fixed-length AES key token or a
| version X'05' external or internal variable-length symmetric key-token.
| DES (Rel. 4.2 or later) Specifies to test a DES key in an external or internal fixed-length CCA key-token, or in
| an external TR-31 key block.
| HMAC Specifies to test an HMAC key in an internal variable-length symmetric key token or,
| beginning with Release 4.2, in an external variable-length symmetric key token.
| Process rule (one required)
| GENERATE Specifies to generate a key verification pattern (KVP) and an associated random
| number for the input key or key part.
| VERIFY Specifies to verify a KVP for the input key based on the random number and KVP
| provided as input. If the verb cannot verify the information provided, it returns a return
| code of 4 and a reason code of 1.
| KVP calculation algorithm (one, optional). See Cryptographic key-verification techniques on page 677.
| ENC-ZERO (Rel. 4.2 or Specifies to use the encrypt zeros method. Calculates the KVP by encrypting a data
| later) block filled with bytes valued to X'00'. Not valid with HMAC. This is the default for
| DES.
| SHA-256 (Rel. 4.2 or Specifies to use the SHA-256 based master-key verification method. Valid only with
| later) AES. This is the default for AES.
| Note: This method can be used to verify that the same key value present in a version
| X'04' AES key-token is the same as the key value in a version X'05' AES CIPHER
| key-token. It can also verify that the same key value is present in a version X'05' AES
| IMPORTER and EXPORTER key pair.
| SHA2VP1 Specifies to use the SHA-256 based master-key verification method. Valid only with
| HMAC. This is the default for HMAC.
| Token type rule (only valid with DES TR-31 key, required). Release 4.2 or later.
| TR-31 Specifies that the DES input key is contained in a TR-31 key block.
| KEK identifier rule (only valid if KEK_identifier_length variable is greater than 0; required if KEK identifier is a key
| label and the key in key storage is an RSA KEK, otherwise optional if KEK passed). Release 4.2 or later.
| IKEK-AES The transport key for the external key to test is an AES KEK. Not valid for DES. This is
| the default for AES and HMAC.
| IKEK-DES The transport key for the external key to test is a DES KEK. Valid only for DES. This is
| the default for DES.
| IKEK-PKA The transport key for the external key to test is an asymmetric key. Required if an RSA
| transport key is used (that is, the key to test is wrapped using the PKOAEP2 method).
| Not valid for DES.
|
in the key_identifier variable.
key_identifier
| The key_identifier parameter is a pointer to a string variable containing a key token that has a clear or
| encrypted key to be tested. Before Release 4.2, the key must be in an HMAC internal variable-length
| symmetric key-token. Beginning with Release 4.2, an HMAC key can be in an external variable-length
| symmetric key-token, provided that a suitable key-encrypting key is provided. Likewise, an AES key

| can either be in (1) an external or internal AES variable-length symmetric key-token (version X'05'), or
| (2) in an internal fixed-length symmetric key-token (version X'04'). A DES key can either be in (1) an
| external or internal fixed-length CCA key-token, or (2) it can be in an external TR-31 key block.
KEK_key_identifier_length
| The KEK_key_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the KEK_key_identifier. In releases before Release 4.2, the value must be zero. In
| Release 4.2 or later, set the value to zero if the input key is in an internal key-token, and set the value
| to greater than or equal to 64 if the input key is in an external key-token. If the variable contains a key
| label, set the value to 64.
KEK_key_identifier
| The KEK_key_identifier parameter is a pointer to a string variable containing the operational
| key-encrypting key used to decipher the external input key-token, or the key label of such a key. This
| parameter can identify an AES, DES, or RSA key-encrypting key.
| reserved_length
| The reserved_length parameter is a pointer to an integer variable containing the number of bytes in
| the reserved variable. Currently this value must be zero.
| reserved
| The reserved parameter is a pointer to a string variable that is currently reserved.
key_verification_pattern_length
| The key_verification_pattern_length parameter is a pointer to an integer variable containing the
| number of bytes in the key_verification_pattern variable.
| Note: Currently only one verification pattern method is supported. This method has a pattern length of
| 8 bytes. For VERIFY, this value must be 8 on input and is not updated on output. For
| GENERATE, this value must be at least 8 and is updated to 8 on output.
key_verification_pattern
| The key_verification_pattern parameter is a pointer to a string variable containing the binary
| verification pattern. For GENERATE, the verb returns the generated verification pattern in this variable.
| For VERIFY, the verb verifies the verification pattern in this variable.
Required commands
The Key_Test2 verb requires the Compute Verification Pattern command (offset X'001D') to be enabled in
the active role.
| For verification rule keyword ENC-ZERO together with algorithm keyword AES, the Compute ENC-ZERO
| Verification Pattern for AES command (offset X'0021') must be enabled in the active rule. This command is
| not required for DES.

Key_Test_Extended (CSNBKYTX)
| Use the Key_Test_Extended verb to generate or verify the value of either a master key, an internal AES
| key or key-part, or an internal DES key or key-part. In addition to operating on master keys and internal
| symmetric keys, this verb also operates on external DES keys and key parts. The verb supports a
| GENERATE option in which it computes and returns a key verification pattern (KVP) for the specified key,
| and a VERIFY option in which it verifies that a passed KVP is correct for the specified key. The KVP and
| the verification process do not reveal any information about the value of the tested key, other than
| equivalency of two key values. Several verification algorithms are supported.
The verb supports testing of AES, APKA, DES, and PKA master keys, AES clear keys or key parts, and
enciphered AES or DES keys or key parts (see Restrictions on page 257). Rule array keywords are used
to specify information about the source key that is not implicit from other verb parameters.
When testing a master key, you use two sets of rule array keywords to indicate what key to test:
1. The AES-MK, APKA-MK, ASYM-MK, and SYM-MK master-key selector keywords select whether to
test the AES, APKA, PKA (asymmetric), or DES (symmetric) master key. Not specifying a master-key
selector keyword indicates that the DES (symmetric) and PKA (asymmetric) master keys (SYM-MK
and ASYM-MK) have the same value, and that you want to test that value.
2. The KEY-KM, KEY-NKM, and KEY-OKM key or key-part rule keywords select among the
current-master-key register, the new-master-key register, and the old-master-key register.
Several key test algorithms are supported by the verb. See Cryptographic key-verification techniques on
page 677. Some are implicitly selected based on the type of key you are testing, while others are optional
and selected by specifying a verification process rule keyword. With the verification-process rule, you can:
| 1. Specify the ENC-ZERO keyword to encrypt a block of binary zeros with the specified key. The verb
| returns the leftmost 32 bits of the encryption result as the KVP. The block that is encrypted consists of
| 16 bytes of binary zeros for AES keys, and 8 bytes for DES and Triple-DES keys. For AES, this
| method is valid only with the TOKEN keyword. For DES, this method is valid only with the KEY-ENC
| and KEY-ENCD keywords.
| 2. Specify the MDC-4 keyword to compute a 16-byte KVP using the MDC-4 algorithm. This keyword is
| valid only when computing the KVP pattern for a DES (symmetric) or PKA (asymmetric) master key.
3. Specify the SHA-1 keyword to compute the KVP using the SHA-1 hashing method. This keyword is
valid only when computing the KVP for the DES (symmetric) or PKA (asymmetric) master-key.
4. Specify the SHA-256 keyword to compute the KVP using the SHA-256 hashing method. This keyword
is valid only when computing the KVP for an AES key or an AES-MK and APKA-MK master-key.
| Note: For historical reasons, the verification information is passed in two 8-byte variables pointed to by
| the value_1 and value_2 parameters. The GENERATE option uses these variables for output, and
| the VERIFY option uses these variables as input. For VERIFY, the verb returns a warning of return
| code 4, reason code 1 if the information provided in these variables does not match the calculated
| values.
| Table 43 on page 266 describes the use of the value_1 and value_2 variables for each of the available
| verification-process rules.

| Table 43. Key_Test_Extended GENERATE outputs and VERIFY inputs
| GENERATE outputs and VERIFY inputs
| Verification-process rule
| value_1 variable value_2 variable
| ENC-ZERO Unused Contains the 4-byte KVP in the
| high-order 4 bytes of the variable,
| taken from the high-order 4 bytes of
| the encrypted result. The low-order 4
| bytes of the variable are unspecified.
| MDC-4 Contains the 8-byte KVP taken from Contains the low-order 8 bytes of the
| the high-order 8 bytes of the MDC-4 MDC-4 hash value.
| hash value.
| SHA-1 Contains the 8-byte KVP taken from Contains the low-order 8 bytes of the
| the high-order 8 bytes of the SHA-1 SHA-1 hash value.
| hash value.
| SHA-256 Unused Contains the 8-byte KVP taken from
| the high-order 8 bytes of the
| SHA-256 hash value.
| No keyword, and first and third parts Same as SHA-1 Same as SHA-1
| of the master key have different
| values
| No keyword, and first and third parts Contains the 8-byte KVP taken from Unused
| of the master key have the same the result of the z/OS-based
| value master-key verification method.
|
| DES and Triple-DES keys reserve the low-order bit of each byte for parity. If parity is used, the low-order
| bit is set so that the total number of '1' bits in the byte is odd. Parity adjustment keywords ADJUST and
| NOADJUST allow you to control how the verb handles the parity bits. Keyword NOADJUST, which is the
| default, specifies not to alter the parity bit values in any way. Keyword ADJUST specifies to modify the
| low-order bit of each byte as necessary for odd parity. This is done on the cleartext value of the key before
| the verification pattern is computed. The parity adjustment is performed only on a temporary copy of the
| key within the card, and does not affect the key value in the key_identifier parameter.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v AES keys and the AES-MK master-key selector keyword are not supported in releases before Release
3.30.
v The APKA-MK master-key selector keyword is not supported in releases before Release 4.1.

Format
CSNBKYTX
kek_key_identifier Input String 64 bytes
Parameters
rule_array_count
rule_array

Keyword Meaning
Process rule (one required)
GENERATE Generate a verification pattern for the specified key or key part.
VERIFY Verify that a verification pattern matches the specified key or key part.
Key or key-part rule (one required)
KEY-ENC Process a single-length DES enciphered key or enciphered key-part supplied in a key
token.
KEY-ENCD Process a double-length DES enciphered key or enciphered key-part supplied in a key
token.
KEY-KM Process the master key in the current-master-key register.
KEY-NKM Process the master key in the new-master-key register, which can be an incomplete key
if all key parts have not been loaded.
KEY-OKM Process the master key in the old-master-key register.
TOKEN Process an AES clear or encrypted key contained in an AES key-token (Release 3.30 or
later).
Master-key selector (one, optional). Use only with KEY-KM, KEY-NKM, or KEY-OKM keywords. The default is to
process the ASYM-MK and SYM-MK key registers, which must have the same key values for the default to be
valid.
AES-MK (Rel. 3.30 or Process one of the AES master-key registers
later)
APKA-MK (Rel. 4.1 Process one of the AES PKA (ECC) master-key registers
or later)
ASYM-MK Process one of the asymmetric PKA (RSA) master-key registers.
SYM-MK Process one of the symmetric (DES) master-key registers.
Parity adjustment (one, optional). Not valid with AES-MK or APKA-MK master-key selector keywords.
ADJUST Adjust the low-order bit in each key byte used in the key-test computation so that the
byte contains an odd number of one bits.
NOADJUST Do not alter the key-byte values. This is the default.
| Verification-process rule (one, optional). See Cryptographic key-verification techniques on page 677.
| ENC-ZERO Specifies use of the encrypt zeros method. Calculates the KVP by encrypting a data
| block filled with bytes valued to X'00'. Use only with the KEY-ENC, KEY-ENCD, or
| TOKEN keywords.
MDC-4 Specifies use of the MDC-4 master-key-verification method. Use only with the KEY-KM,
SHA-1 Specifies use of the SHA-1 master-key-verification method. Use only with the KEY-KM,
SHA-256 (Rel. 3.30 Specifies use of the SHA-256 master-key-verification method. This is valid only with AES
or later) keys, and the AES and APKA master keys. This is the default for AES keys, and for
master-key selector keywords AES-MK and APKA-MK.
| No keyword, and first Defaults to the use of the SHA-1 master-key verification method when the ASYM-MK or
| and third parts of the SYM-MK master-key selector keyword is specified.
master key have
different values.
| No keyword, and first Defaults to the use of the IBM z/OS-based master-key verification method when the
| and third parts of the ASYM-MK or SYM-MK master-key selector keyword is specified.
master key have the
same value.

key_identifier
| The key_identifier parameter is a pointer to a string variable containing an internal or external
| fixed-length AES or DES key-token, or a key label that identifies an internal or external fixed-length
| key-token record in AES or DES key-storage. This parameter should point to a null DES key-token for
| rule-array keywords KEY-KM, KEY-NKM, and KEY-OKM.
| The key token contains the key or the key part used to generate or verify the KVP.
| When you specify the KEY-ENC or the KEY-ENCD keyword, the enciphered key or enciphered
| key-part must be in a fixed-length DES key-token.
| value_1
| VERIFY this parameter is input only. This variable must be specified, even if it is not used.
| value_2
| VERIFY this parameter is input only. This variable must be specified, even if it is not used.
kek_key_identifier
| The kek_key_identifier parameter is a pointer to a string variable containing an operational fixed-length
| DES key-token or the key label of such a key in DES key-storage. The key token must contain an
| IMPORTER or EXPORTER key-encrypting key for the external key identified by the key_identifier
| parameter. If the key_identifier parameter does not identify an external key-token, use the
| kek_key_identifier parameter to identify a null DES key-token.
Required commands
The Key_Test_Extended verb requires the Compute Verification Pattern command (offset X'001D') to be

Key_Token_Build (CSNBKTB)
Use the Key_Token_Build verb to assemble a fixed-length symmetric key-token in application storage from
information that you supply, either as an internal fixed-length AES or DES key-token, or as an external
| fixed-length DES key-token. CCA does not support fixed-length external AES key tokens. To assemble a
| variable-length symmetric key-token, see Key_Token_Build2 (CSNBKTB2) on page 275.
Internal fixed-length AES key tokens can contain either a clear key or an enciphered key, while
fixed-length DES key tokens can contain only an enciphered key. You either specify that the verb build a
completed key-token with a key value you provide, or build a skeleton key-token that does not have a key
value. A typical use of a skeleton key-token is so that it can be supplied to the Key_Generate verb, which
then updates the key token with an enciphered key that the verb randomly generates.
When building an AES skeleton-key token, Key_Token_Build sets the clear-key bit length value (offset 56)
in the token, even though it does not contain a key. This enables the Key_Generate verb to use this value
to determine what key size to generate. The verb also sets the AES key-token LRC checksum byte (offset
7) to binary zeros.
| A control vector includes data that defines the key type of a key. All fixed-length AES key tokens have a
| key type of DATA, and an AES control vector, if present, is always valued to binary zeros. Other than a
| key type, AES control vectors contain no other data such as key-usage, key-length, or key subtype. A DES
| control vector, in addition to a key type, includes data that defines key-usage values, a key-length
| specification, and in some cases a key subtype, a key subtype extension, or both. See Appendix C, CCA
| control-vector definitions and key encryption, on page 655.
Note: An external version X'01' DES key-token contains a double-length DATA key with a control vector of
binary zeros. In this case, the key length is located at offset 59 and not in the key-form bits of the
control vector.
The verb always includes a control vector as part of the output key-token. For AES keys, the verb sets the
control vector value in the key-token to binary zeros. For DES keys, the verb can include a control vector
you supply, or it can build the control vector based on the key type and keywords in the rule array related
to the control vector.
This verb does not perform cryptographic services on any key value. You cannot use this verb to change a
key or to change the control vector related to a key.
To use this verb:

| 1. Provide a 64-byte buffer to receive the returned fixed-length symmetric key-token.
2. Specify a keyword for the key type.
v For AES key tokens, specify keyword DATA when the key token is to contain an enciphered key, or
CLRAES when it is to contain a clear key. DATA or CLRAES are the only valid key-type keywords
for AES. Keyword CLRAES is only for AES, and implicitly specifies the token algorithm in the rule
array.
v For DES key tokens, specify a key-type keyword (not CLRAES). A fixed-length DES key-token
cannot contain a clear key, only an enciphered key. The USE-CV is a special keyword that specifies
the verb is to obtain the key type from the control vector pointed to by the control vector parameter.
The USE-CV keyword must be used together with the CV control-vector status keyword in the rule
array.
3. Specify the rule array keywords:
Token type
| Specify whether the verb is to build an external or an internal key-token. Do not specify external for
| an AES key.

Token algorithm
Optionally specify whether to build an AES key-token (Release 3.30 or later) or a DES key-token. If
the key-type keyword is CLRAES, then the implicit default is AES. Otherwise, the default is DES.
Key status
Optionally specify the keyword KEY if you want the key-token to be built using the key value
identified by the key_value parameter, or NO-KEY if the key-token is not to have a key. The default
is NO-KEY.
Key length
This keyword specifies the key length of AES or DES keys, and is required for AES. For enciphered
AES keys (DATA), use keyword KEYLN32. If the key-type keyword is CLRAES, use keyword
KEYLN16 for a clear AES key of 16 bytes, KEYLN24 for 24 bytes, and KEYLN32 for 32 bytes.
Control vector (CV) source
This optional keyword is for DES only. Optionally specify the keyword CV if you want the key-token
to be built using the control vector value identified by the control_vector parameter, or NO-CV if the
verb is to build the control vector based on the key type and any keywords related to the
control-vector in the rule array.
Control-vector keywords
These optional keywords are for DES only. Specify any keywords that can be specified for the
control vector of the specified DES key-type.
4. Specify a key value when the key status keyword in the rule array is KEY.
5. Specify the token_data_1 value. For encrypted AES keys only, this variable provides a one-character
string valued to the LRC calculated against the clear-key value. Otherwise, specify a null pointer or 8
bytes of binary zeros (XL8'0').
6. Specify a control vector value when the control vector keyword is CV.
7. Specify a master_key_verification_pattern value for the master-key encrypted key in the key token.
This value is needed when the key status keyword is KEY, the token type is INTERNAL, and the
key-type keyword is not CLRAES.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v AES key types and keywords are not supported in releases before Release 3.30.
v Version 1 software used a smaller master-key verification pattern, called the master-key version number.
Beginning with Version 2, the verb interface changed to accept an 8-byte verification pattern identified
by the master_key_verification_pattern parameter.
v The WRAP-ECB, WRAP-ENH, and ENH-ONLY rule-array keywords are not supported in releases
before Release 4.1.

Format
CSNBKTB
key_token Output String 64 bytes
rule_array_count Input Integer
key_value Input String 16, 24, or 32 bytes
reserved_1* Input void * integer valued to 0
reserved_2 Input Integer null pointer or 0
token_data_1 Input String null pointer (DES), or XL8'00' (DES), or 1 byte (AES)
control_vector Input String 16 bytes
reserved_4 Input String null pointer or XL8'00'
reserved_5 Input Integer null pointer or 0
reserved_6 Input String null pointer or 8-space variable
master_key_verification_pattern Input String 8 bytes
*
Previous implementations used the reserved_1 parameter to point to a four-byte integer or string that
represented the master-key version number. Beginning with Version 2, the CCA Support Program requires
this parameter to point to a four-byte value equal to binary zero.
Parameters
key_token
The key_token parameter is a pointer to a string variable containing the assembled key-token.
Note: This variable cannot contain a key label.

key_type
The key_type parameter is a pointer to a string variable containing a keyword that defines the key
type. The keyword is 8 bytes in length and must be left-aligned and padded on the right with space
characters.
These are valid key_type keywords for AES (Release 3.30 or later):
DATA CLRAES

These are valid key_type keywords for DES:
CIPHER DATAMV MAC

CVARDEC DECIPHER MACVER
CVARENC DKYGENKY OKEYXLAT
CVARPINE ENCIPHER OPINENC
CVARXCVL EXPORTER PINGEN
CVARXCVR IKEYXLAT PINVER
DATA IMPORTER SECMSG
DATAC IPINENC USE-CV
DATAM KEYGENKY
For information about key types, see Appendix C, CCA control-vector definitions and key encryption,
on page 655.
Specify the USE-CV keyword to indicate the key type should be obtained from the control_vector
variable.
rule_array_count
in the rule_array variable.
rule_array
Keyword Meaning
Token type (one required)
EXTERNAL Specifies to build an external key-token. Valid only for DES keys.
INTERNAL Specifies to build an internal key-token. Valid for both AES and DES keys.
Token algorithm (one, optional)
AES (Rel. 3.30 or Specifies to build an AES key-token. If the CLRAES key_type keyword is specified, this is
later) the default.
DES Specifies to build a DES key-token. If the CLRAES key_type keyword is not specified, this
is the default.
Key status (one, optional)
KEY Specifies to build the key token with the key variable identified by the key_value parameter.
NO-KEY Specifies to build the key token without a key value. This is the default.
Key length (one required for AES, one optional for DES)
SINGLE Specifies that the key length is single (valid only for DES keys).
KEYLN8 Same as SINGLE.
DOUBLE Specifies that the key is either a replicated single-length key (both key halves equal), or a
double-length key with two different 8-byte values (valid only for DES keys).
KEYLN16 AES keys: Specifies that the key length is 16 bytes (128 bits). DES keys: Same as
DOUBLE.
MIXED Same as DOUBLE.
KEYLN24 Specifies that the key length is 24 bytes (192 bits) - valid only for AES keys and only for
Release 3.30 or later.
KEYLN32 Specifies that the key length is 32 bytes (256 bits) - valid only for AES keys and only for
Release 3.30 or later.

Keyword Meaning
Control vector (CV) source (one, optional). Valid only for DES keys.
CV Specifies to build the key token using the control vector identified by the control_vector
parameter.
NO-CV Specifies to build the key token with a control vector that is based on the supplied
key_type keyword and control vector related keywords in the rule array. This is the default.
Key-wrapping method (one, optional). Not valid with AES. Release 4.1 or later.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method. Not valid if CV and bit 56
(ENH-ONLY) in control_vector variable is set to B'1'. This is the default.
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH. This option cannot be
used on a key with a control vector valued to binary zeros. Release 4.1 or later.
wrapped with the enhanced method. Sets bit 56 (ENH-ONLY) of the control vector to B'1'.
Control-vector related keywords (one or more, optional). Valid only for DES keys.
See Figure 10 on page 161 for the key-usage keywords that can be specified for a given key type.
key_value
This parameter is a pointer to a string variable containing the enciphered key or AES clear-key value
which is placed into the key field of the key token when you use the KEY rule-array keyword.
The length of this variable depends on the type of key that is provided. The length is 16 bytes for DES
keys. A single-length DES key must be left-aligned and padded on the right with eight bytes of X'00'.
For a clear AES key, the length is 16 bytes for KEYLN16, 24 bytes for KEYLN24, and 32 bytes for
KEYLN32. An enciphered AES key is 32 bytes.
token_data_1
This parameter is unused for DES keys and cleartext AES keys. In either of those cases it must either
be a null pointer or point to a string variable containing eight bytes of binary zeros.
For encrypted AES keys, this parameter is a pointer to a one-byte string variable containing the LRC
value for the key passed in the key_value parameter. See Internal fixed-length AES key tokens on
page 578 for an explanation of LRC values. The verb copies this LRC into the LRC field of the key
token. Note that the verb automatically computes the LRC for a cleartext AES key and stores it in the
key token.
control_vector
This parameter is a pointer to a string variable. If you specify the CV keyword in the rule array, the
contents of this variable are copied to the control vector field of the fixed-length DES key-token. The
contents of this variable are ignored for AES keys.
master_key_verification_pattern
This parameter is a pointer to a string variable containing the master-key verification pattern of the
master key used to encipher the key in the internal key-token. The contents of the variable are copied
into the MKVP field of the key token when keywords INTERNAL and KEY are specified, and key_type
keyword CLRAES is not specified.
Required commands
None

Key_Token_Build2 (CSNBKTB2)
| Use the Key_Token_Build2 verb to assemble an internal HMAC or, beginning with Release 4.2, an
| external or internal AES or HMAC variable-length symmetric key-token in application storage from
| information that you supply. If the verb assembles the information as a skeleton key-token, this skeleton
| can be supplied to the Key_Generate2 verb. In turn, the Key_Generate2 verb can use the skeleton to
| provide a completed key-token with the attributes of the skeleton along with a randomly generated key.
| These attributes become cryptographically bound to the key when it is enciphered. To assemble a
| fixed-length symmetric key-token, see Key_Token_Build (CSNBKTB) on page 270.
| The Key_Token_Build2 verb cannot assemble a usable key-token that contains an enciphered key. It can,
| however, assemble an internal AES or HMAC key-token that has a clear key, usable for a limited number
| of services.
This is a host-only verb and it does not use the cryptographic coprocessor. As such, it does not perform
cryptographic services on any key value.
Restrictions
| AIX X
| IBM i X
| Windows
|
| v Key types EXPORTER and IMPORTER do not allow clear keys.
| v External key tokens are not supported in releases before Release 4.2.
| v The following rule-array keywords are not supported in releases before Release 4.2:
| Token identifier EXTERNAL
| Algorithm AES
| Key types CIPHER, EXPORTER, or IMPORTER
| Encrypt key-usage control ENCRYPT and DECRYPT
| Generate key-usage control GENERATE and VERIFY
| EXPORTER key-usage control EXPORT, TRANSLAT, GEN-OPEX, GEN-IMEX, GEN-EXEX, and
| GEN-PUB
| IMPORTER key-usage control IMPORT, TRANSLAT, GEN-OPIM, GEN-IMEX, GEN-IMIM, and
| GEN-PUB
| User-defined extension control UDX-ONLY, UDX-001, UDX-010, and UDX-100
| Key-usage mode CBC, ECB, CFB, OFB, GCM, and XTS
| Key-usage wrap algorithm WR-DES, WR-AES, WR-HMAC, WR-RSA, and WR-ECC
| Key-usage wrap class WR-DATA, WR-KEK, WR-PIN, WRDERIVE, and WR-CARD
| DES-key export control NOEX-DES and XPRT-DES
| AES-key export control NOEX-AES and XPRT-AES
| RSA-key export control NOEX-RSA and XPRT-RSA

Format
CSNBKTB2
| clear_key_bit_length Input Integer 0; 128, 192, or 256 (CIPHER); 80 - 2048 (MAC)
clear_key_value Input String clear_key_bit_length / 8 bytes
| key_name_length Input Integer 0 or 64
key_name Input String key_name_length bytes
user_associated_data_length Input Integer 0 - 255
user_associated_data Input String user_associated_data_length bytes
token_data_length Input Integer 0
token_data Input String token_data_length bytes
reserved_length Input Integer 0
reserved Input String reserved_length bytes
| target_key_token_length In/Output Integer See Appendix B.
target_key_token Output String target_key_token_length bytes
Parameters
rule_array_count
in the rule_array variable. The minimum value is 4.
rule_array
| keywords are 8 bytes in length, and are left-aligned and padded on the right with space characters.
| The returned rule array keywords express the contents of the token.
|| Keyword Meaning
| Header section
| Token identifier (one required)
| INTERNAL Build an internal variable-length symmetric key-token.
| EXTERNAL (Rel. Build an external variable length key-token.
| 4.2 or later)
| Wrapping information section
| Key status (one, optional)
| NO-KEY Build the key token without a key value. This creates a skeleton key token that can later be
| supplied to the Key_Generate2 verb. This is the default.
| KEY-CLR Build the key token with a clear key, CIPHER and MAC key types only.

| Keyword Meaning
| Associated data section
| Type of algorithm for which key can be used (one required)
| AES (Rel. 4.2 or Build an AES key token.
| later)
| HMAC Build an HMAC key token.
| Key type (one required)
| CIPHER (Rel. 4.2 Build a CIPHER key for encryption and decryption operations (AES algorithm only). See
| or later) Figure 6 on page 154 and Table 23 on page 157.
| EXPORTER (Rel. Build an EXPORTER key-encrypting key (AES algorithm only). See Figure 7 on page 155.
| 4.2 or later)
| IMPORTER (Rel. Build an IMPORTER key-encrypting key (AES algorithm only). See Figure 8 on page 156.
| 4.2 or later)
| MAC Build a MAC key for message authentication code operations (HMAC algorithm only). See
| Figure 9 on page 157.
|
| clear_key_bit_length
| The clear_key_bit_length parameter is a pointer to an integer variable containing the number of bits of
| clear key data. For a skeleton key-token or a key type that does not support clear keys, use a value of
| zero. For a CIPHER clear key, use a value of 128, 192, or 256. For a MAC clear key, use a value from
| 80 - 2048.
clear_key_value
The clear_key_value parameter is a pointer to a string variable containing the clear key-value. The
clear_key_value parameter must be addressable up to the nearest byte boundary above the
clear_key_bit_length if the clear_key_bit_length is not a multiple of 8. The extra bits will not be used
when creating the output clear-key token.
key_name_length
| The key_name_length parameter is a pointer to an integer variable containing the number of bytes in
| the key_name variable. The value must be 0 or 64. This user-definable data is cryptographically bound
| to the key if it is encrypted.
key_name
| The key_name parameter is a pointer to a string variable containing the optional key label to be stored
| in the associated data structure of the key token. If present, the variable must contain a valid key
| label. This user-definable data is cryptographically bound to the key if it is encrypted.
user_associated_data_length
The user_associated_data_length parameter is a pointer to an integer variable containing the number
of bytes in the user_associated_data variable. The value must be 0 - 255.
user_associated_data
| The user_associated_data parameter is a pointer to a string variable containing the user-associated
| data to be stored in the key token. This user-definable data is cryptographically bound to the key if it is
| encrypted.
token_data_length
The token_data_length parameter is a pointer to an integer variable containing the number of bytes in
the token_data variable. The value must be 0.
token_data
The token_data parameter is a pointer to a string variable containing the token data to be stored in the
key token. This parameter is reserved for future use.

reserved_length
The reserved_length parameter is a pointer to an integer variable containing the number of bytes in
the reserved variable. The value must be 0.
reserved
The reserved parameter is a pointer to a string variable that is reserved for future use.
The target_key_token_length parameter is a pointer to an integer variable containing the number of
bytes in the target_key_token variable.
target_key_token
| The target_key_token parameter is a pointer to a string variable containing the target key-token. On
| output this buffer will contain the newly created token. Note that if a clear key-token is created and the
| clear_key_bit_length is not a multiple of 8, the clear key payload is padded with B'0' bits to the nearest
| byte boundary.
Required commands
None

Key_Token_Change (CSNBKTC)
Use the Key_Token_Change verb to reencipher the encrypted data of fixed-length AES or DES key tokens
from encryption under the old AES or DES master-key to encryption under the current AES or DES
master-key, and update keys in internal fixed-length AES or DES key tokens.
Beginning with Release 4.1, the verb can be used to reformat a key in an internal fixed-length AES or DES
key-token from its current key-wrapping method to the specified key-wrapping method. A reformat does not
change the master key used.
Note: Previous implementations of IBM CCA products had additional capabilities with this verb such as
deleting key records and key tokens in key storage. Also, use of a wildcard (*) was supported in
those implementations.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v AES is not supported in releases before Release 3.30.
v The REFORMAT reencipherment method is not supported in releases before Release 4.1.
Format
CSNBKTC
Parameters
rule_array_count

rule_array
Keyword Description
Algorithm (one, optional). These keywords are not supported in releases before Release 3.30.
AES Specifies that the key token is for an AES key.
DES Specifies that the key token is for a DES key. This is the default.
Reencipherment method (one required)
REFORMAT (Rel. Reenciphers a key from its current key-wrapping method to the specified key-wrapping
4.1 or later) method. The master key used to reencipher the key is the same master key used to wrap
the original key.
RTCMK Reenciphers a key that is now enciphered under the old master key to encipherment under
the current master key. If the key is already enciphered with the current master key, the verb
returns a positive response (return code 0, reason code 0) and does not change the key
token.
This keyword is ignored for AES keys. This is the default.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for
AES keys.
Translation control (optional). This is valid only with wrapping method WRAP-ENH or with USECONFG when the
default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to
binary zeros. Release 4.1 or later.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it
has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the
control vector to B'1'.
key_identifier
The key_identifier parameter is a pointer to a string variable containing the internal fixed-length AES or
DES key-token or the key label of an internal fixed-length AES or DES key-token record.
Required commands
The Key_Token_Change verb requires the following commands:

REFORMAT X'014C' Key Token Change (REFORMAT)
RTCMK X'0090' Reencipher to Current Master Key
WRAP-ECB or WRAP-ENH X'0146' Allow Configuration Override with Keyword in KTC
method setting does not
match keyword (Release 4.1
or later)
If the WRAP-ECB translation-control keyword is specified and the key in the input key token is wrapped by
the enhanced wrapping method (WRAP-ENH), the verb requires the Enable Translation from New to Old
Format in KTC and KTR2 command (offset X'0147') to be enabled. An active role with offest X'0147'
enabled can also use the Key_Translate2 verb to translate a key from the enhanced key-wrapping method
to the less-secure legacy method.

Key_Token_Change2 (CSNBKTC2)
Use the Key_Token_Change2 verb to reencipher the encrypted data of an internal variable-length
symmetric key-token from encryption under the old AES master-key to encryption under the current AES
master-key.
Restrictions
| AIX X
| IBM i X
| Windows
|
| v Rule-array keyword AES is not supported in releases before Release 4.2.
Format
CSNBKTC2
key_identifier_length In/Output Integer See Appendix B.
Parameters
rule_array_count
rule_array
characters.

Keyword Description
| AES (Rel. 4.2 or Specifies that the key token is for an AES key in a variable-length symmetric key token.
| later)
HMAC Specifies that the key token is for an HMAC key.
Reencipherment method (one required)
| RTCMK Reencipher a key that is enciphered under the old master-key to encipherment under the
| current master-key. If the key is already enciphered with the current master-key, the verb
| returns a positive response (return code 0, reason code 0) and does not change the key
| token.
| The key_identifier_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the key_identifier variable. On input, this variable contains the number of bytes for the
| key_identifier buffer, and must be large enough to hold the key token or key label. On output, this
| variable contains the number of bytes of data returned in the key_identifier variable.
key_identifier
| The key_identifier parameter is a pointer to a string variable containing an internal variable-length
| symmetric key-token, or a key label of such a key in AES key-storage. The enciphered data within the
| token is securely reenciphered under the current master-key.
Required commands
The Key_Token_Change2 verb requires the Reencipher to Current Master Key2 command (offset X'00F1')
to be enabled in the active role in order to use keyword RTCMK.

Key_Token_Parse (CSNBKTP)
Use the Key_Token_Parse verb to disassemble an internal or external fixed-length DES key-token into
separate pieces of information. The verb disassembles a key-token in application storage, and does not
perform any cryptographic services.
The key_token parameter specifies the key token to disassemble.
The verb returns some of the key-token information in a set of variables identified by individual parameters
and the remaining key-token information as keywords in the rule array.
Control-vector information is returned in keywords found in the rule array when the verb can fully parse the
control vector. Supported keywords are shown in Figure 10 on page 161. Otherwise, the verb returns
return code 4, reason code 2039 (X'7F7').
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v This verb does not support version X'10' external DES (RKX) key tokens.
Format
CSNBKTP
key_token Input String 64 bytes
key_type Output String 8 bytes
| rule_array_count In/Output Integer 3 - 50
rule_array Output String array rule_array_count * 8 bytes
key_value Output String 16 bytes
master_key_version_number Output Integer (version X'03' internal token only)
reserved_2 Output Integer Can be a null pointer.
reserved_3 Output String 8 bytes
control_vector Output String 16 bytes
reserved_5 Output Integer Can be a null pointer.
master_key_verification_pattern Output String 8 bytes (version X'00' internal token only)

Parameters
key_token
The key_token parameter is a pointer to a string variable in application storage containing an external
or internal key-token to be disassembled.
key_type
The key_type parameter is a pointer to a string variable containing a keyword defining the key type.
The keyword is 8 bytes in length and must be left-aligned and padded on the right with space
characters. Valid key_type keywords are shown below:
CIPHER DATAC EXPORTER MACVER

CVARDEC DATAM IKEYXLAT OKEYXLAT
CVARENC DATAMV KEYGENKY OPINENC
CVARPINE DECIPHER IMPORTER PINGEN
CVARXCVL DKYGENKY IPINENC PINVER
CVARXCVR ENCIPHER MAC SECMSG
DATA
rule_array_count
in the rule_array variable. This value must be a minimum of 3 and should be at least 20.
On input, specify the maximum number of usable array elements that are allocated. On output, the
verb sets the value to the number of keywords returned to the application.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords that
expresses the contents of the key token. The keywords are 8 bytes in length and are left-aligned and
padded on the right with space characters. The rule_array keywords are:
Keyword Meaning
Token type (one returned)
EXTERNAL Specifies an external fixed-length DES key-token.
INTERNAL Specifies an internal fixed-length DES key-token.
Key status (one returned)
KEY Indicates the key token contains a key. The key_value variable contains the key.
NO-KEY Indicates the key token does not contain a key.
Key-wrapping method (one returned). Release 4.1 or later.
WRAP-ECB The wrapping method for this key is legacy.
WRAP-ENH The wrapping method for this key is enhanced.
Control-vector (CV) status (one returned)
CV The key token specifies that a control vector is present. The verb sets the control_vector
variable with the value of the control vector found in the key token.
NO-CV The key token does not specify the presence of a control vector. The verb sets the
control_vector variable to space characters.
Control-vector keywords
See Figure 10 on page 161 for the key-usage keywords that can result with a given key type.

key_value
The key_value parameter is a pointer to a string variable. The verb copies the 16 bytes of data found
in the key token to the key_value variable. If the verb returns the KEY keyword in the rule array, the
key_value variable contains the 8-byte or 16-byte enciphered key.
master_key_version_number
The master_key_version_number parameter is a pointer to an integer variable. The verb writes binary
zero into the variable except when parsing a version X'03' internal key-token.
reserved_2/5
The reserved_2 and reserved_5 parameters are either null pointers or pointers to integer variables. If
the parameter is not a null pointer, the verb writes zero into the reserved variable.
reserved_3/4
The reserved_3 and reserved_4 parameters are either null pointers or pointers to string variables. If
the parameter is not a null pointer, the verb writes eight bytes of X'00' into the reserved variable.
reserved_6
The reserved_6 parameter is either a null pointer or a pointer to a string variable. If the parameter is
not a null pointer, the verb writes eight space characters into the reserved variable.
control_vector
The control_vector parameter is a pointer to a string variable. If the verb returns the NO-CV keyword
in the rule array, the key token did not contain a control-vector value and the control_vector variable is
filled with 16 space characters.
master_key_verification_pattern
The master_key_verification_pattern parameter is a pointer to a string variable. For version X'00'
internal key-tokens that contain a key, the 8-byte master-key verification pattern will be copied to the
variable. Otherwise, the 8-byte variable is filled with space characters.
Required commands
None

| Key_Token_Parse2 (CSNBKTP2)
| Use the Key_Token_Parse2 verb to disassemble a variable-length symmetric key-token into separate
| pieces of information. The verb can disassemble an external or internal variable-length symmetric
| key-token in application storage. To parse a fixed-length symmetric key-token, see Key_Token_Parse
| (CSNBKTP) on page 283.
| The key_token input parameter specifies the external or internal key token to disassemble. The verb
| returns some of the key-token information in a set of variables identified by individual parameters, and
| returns the remaining information as keywords in the rule array.
| The key-usage field and key-management field information is returned in keywords found in the rule array
| when the verb can fully parse the fields. See the rule_array parameter on page 288 for a table of
| supported keywords. If the token cannot be parsed successfully, the verb returns a warning using reason
| code 2039 X'7F7'). If a warning or error occurs during processing, the verb updates all of the count and
| length variables with a value of zero.
| The Key_Token_Parse2 verb performs no cryptographic services.

| v An external or internal variable-length symmetric key-token (version X'05') to be parsed
| This parameter does not accept a key label. The key token must be provided from application storage.
| If a key token located in key storage needs to be parsed, use the AES_Key_Record_Read verb to
| retrieve it into application storage before calling this verb.
| See Variable-length symmetric key-token on page 614 for the format of this key token. A review of this
| format information will greatly assist in understanding the output variables of this verb.
| v A rule-array-count value large enough for the verb to return keywords about the input key-token in the
| rule-array buffer
| To determine the exact count required, and also the required lengths of the other string variables,
| specify a value of zero. This causes the verb to return all count and length values without updating any
| string variables.
| v Adequate buffer sizes for all of the output variables using the length parameters
| Restrictions
| AIX
| IBM i
| Windows
|

| Format
| CSNBKTP2
| key_token_length Input Integer See Appendix A.
| key_token Input String key_token_length bytes
| key_type Output String 8 bytes
| rule_array_count In/Output Integer 3 - 50
| rule_array Output String array rule_array_count * 8 bytes
| key_material_state Output Integer 0, 1, 2, or 3
| payload_bit_length In/Output Integer See Appendix B.
| payload Output String payload_bit_length / 8 bytes
| key_verification_pattern_type Output Integer 0, 1, or 2
| key_verification_pattern_length In/Output Integer 16
| key_verification_pattern Output String key_verification_pattern_length bytes
| key_wrapping_method Output Integer 0, 2, or 3
| key_hash_algorithm Output Integer 0, 1, 2, 4, or 8
| key_name_length In/Output Integer 0 or 64
| key_name Output String key_name_length bytes
| TLV_data_length In/Output Integer 0
| TLV_data Output String TLV_data_length bytes
| user_associated_data_length In/Output Integer 255
| user_associated_data Output String user_associated_data_length bytes
| reserved_length In/Output Integer 0
| reserved Output String reserved_length bytes
|
| Parameters
| key_token_length
| The key_token_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the key_token variable.
| key_token
| The key_token parameter is a pointer to a string variable containing an external or internal
| variable-length symmetric key-token to be disassembled. This parameter must not point to a key label.
| key_type
| The key_type parameter is a pointer to a string variable containing a keyword for the key type of the
| input key. The keyword is 8 bytes in length and is left-aligned and padded on the right with space
| characters. Valid key_type keywords are shown below:
|| CIPHER EXPORTER
| IMPORTER MAC
|

| rule_array_count
| The rule_array_count is a pointer to an integer variable containing the number of 8-byte elements in
| the rule_array variable. The minimum returned value is 3, and the maximum returned value is
| approximately 50. To determine the exact count required, and also the required lengths of the other
| string variables, specify a value of zero. This causes the verb to return all count and length values
| without updating any string variables.
| On output, the variable is updated with the actual count of the rule-array keywords. An error is
| returned if a key token cannot be parsed or any of the output buffers are too small.
| rule_array
| keywords are 8 bytes in length, and are left-aligned and padded on the right with space characters.
| The returned rule array keywords express the contents of the token.
|| Keyword Meaning
| Header section
| Token identifier (one returned)
| EXTERNAL External key
| INTERNAL Internal key
| Wrapping information section
| Key status (one returned). See key_material_state variable for additional details.
| KEY Key token contains a partial or complete key. The payload variable contains the clear or
| encrypted key.
| NO-KEY Key token does not contain a key. The payload variable is empty.
| Key verification pattern (KVP) type
| Note: Not a keyword. Value returned in key_verification_pattern_type variable.
| KVP
| Note: Not a keyword. Value returned in key_verification_pattern variable.
| Encrypted section key-wrapping method
| Note: Not a keyword. Value returned in key_wrapping_method variable.
| Hash algorithm used for wrapping
| Note: Not a keyword. Value returned in key_hash_algorithm variable.
| Type of algorithm for which key can be used (one returned)
| AES AES (Release 4.2 or later)
| HMAC HMAC
| Key type
| Note: Keyword is returned in key_type variable
| Encrypt key-usage control (one or two returned, CIPHER key type only)
| ENCRYPT Key can be used for encryption. Used by Symmetric_Algorithm_Encipher.
| DECRYPT Key can be used for decryption. Used by Symmetric_Algorithm_Decipher.
| Generate key-usage control (one returned, MAC key type only)
| GENERATE Key can be used for generate and key can be used for verify. Used by HMAC_Generate.
| VERIFY Key cannot be used generate and key can be used for verify. Used by HMAC_Verify.

| Keyword Meaning
| EXPORTER key-usage control (one or more returned, EXPORTER key type only)
| EXPORT Key can be used for EXPORT. Used by Symmetric_Key_Export.
| GEN-OPEX Key can be used for GENERATE-OPEX. Used by Key_Generate2.
| GEN-EXEX Key can be used for GENERATE-EXEX. Used by Key_Generate2.
| IMPORTER key-usage control (one or more returned, IMPORTER key type only)
| IMPORT Key can be used for IMPORT. Used by Symmetric_Key_Import.
| TRANSLAT Key can be used for TRANSLAT. Used by Used by Key_Translate2..
| GEN-OPIM Key can be used for GENERATE-OPIM. Used by Key_Generate2.
| GEN-IMIM Key can be used for GENERATE-IMIM. Used by Key_Generate2.
| User-defined extension control (any number returned, all key types)
| UDX-ONLY Indicates that this key can only be used in UDXs.
| UDX-001 Indicates that the rightmost user-defined UDX bit is set on.
| UDX-010 Indicates that the middle user-defined UDX bit is set on.
| UDX-100 Indicates that the leftmost user-defined UDX bit is set on.
| Key-usage mode (one returned, CIPHER key type only)
| CBC Indicates that this key can be used for Cipher Block Chaining.
| ECB Indicates that this key can be used for Electronic Code Book.
| CFB Indicates that this key can be used for Cipher Feedback.
| OFB Indicates that this key can be used for Output Feedback.
| GCM Indicates that this key can be used for Galois/Counter Mode.
| XTS Indicates that this key can be used for Xor-Encrypt-Xor-based Tweaked Stealing.
| Hash method (one or more returned, MAC key type only)
| SHA-1 SHA-1 hash method is allowed for use by the key.
| Key-encrypting key control (zero or one returned, EXPORTER or IMPORTER key types only)
| WR-TR31 Indicates that this key-encrypting key can wrap or unwrap a TR-31 key block.

| Keyword Meaning
| Key-usage wrap algorithm (one or more returned, EXPORTER or IMPORTER key types only)
| WR-DES Key can wrap DES keys.
| WR-AES Key can wrap AES keys.
| WR-HMAC Key can wrap HMAC keys.
| WR-RSA Key can to wrap RSA keys.
| WR-ECC Key can wrap ECC keys.
| Reserved byte
| Key-usage wrap class (one or more returned, EXPORTER or IMPORTER key types only)
| WR-DATA Key can wrap DATA class keys.
| WR-KEK Key can wrap KEK class keys.
| WR-PIN Key can wrap PIN class keys.
| WRDERIVE Key can wrap DERIVATION class keys.
| WR-CARD Key can wrap CARD class keys.
| Reserved byte
| Key-management field 1, high order byte
| Symmetric-key export control (one returned, all key types)
| NOEX-SYM Prohibit export using symmetric key.
| XPRT-SYM Allow export using symmetric key.
| Unauthenticated asymmetric-key export control (one returned, all key types)
| NOEXUASY Prohibit export using an unauthenticated asymmetric key.
| XPRTUASY Allow export using unauthenticated asymmetric key.
| Authenticated asymmetric-key export control (one returned, all key types)
| NOEXAASY Prohibit export using authenticated asymmetric key.
| XPRTAASY Allow export using authenticated asymmetric key.
| DES-key export control (one returned, AES algorithm only)
| NOEX-DES Prohibit export using DES key
| XPRT-DES Allow export using DES key.
| AES-key export control (one returned, AES algorithm only)
| NOEX-AES Prohibit export using AES key.
| XPRT-AES Allow export using AES key.
| RSA-key export control (one returned, AES algorithm only)
| NOEX-RSA Prohibit export using RSA key
| XPRT-RSA Allow export using RSA key.

| Keyword Meaning
| Key completeness (one returned, all key types)
| MIN3PART Key if present is incomplete. Key requires at least 2 more parts.
| MIN2PART Key if present is incomplete. Key requires at least 1 more part.
| MIN1PART Key if present is incomplete. Key can be completed or have more parts added.
| KEYCMPLT Key if present is complete. No more parts can be added.
| Security history (one returned, all key types, Release 4.2 or later)
| UNTRUSTD Key was encrypted with an untrusted KEK.
| WOTUATTR Key was in a format without type/usage attributes.
| WWEAKKEY Key was encrypted with key weaker than itself.
| NOTCCAFM Key was in a non-CCA format.
| WECBMODE Key was encrypted in ECB mode.
| Pedigree original rules (one returned, all key types, Release 4.2 or later)
| POUNKNWN Unknown.
| POOTHER Other. Method other than those defined here, probably used in UDX.
| PORANDOM Randomly generated.
| POKEYAGR Established by key agreement such as Diffie-Hellman.
| POCLRKC Created from cleartext key components.
| POCLRKV Entered as a cleartext key value.
| PODERVD Derived from another key.
| POKPSEC Cleartext keys or key parts that were entered at TKE and secured from there to the target
| card.
| Pedigree current rule (one returned, all key types, Release 4.2 or later)
| PCUNKNWN Unknown.
| PCOTHER Other. Method other than those defined here, probably used in UDX.
| PCRANDOM Randomly generated.
| PCKEYAGR Established by key agreement such as Diffie-Hellman.
| PCCLCOMP Created from cleartext key components.
| PCCLVAL Entered as a cleartext key value.
| PCDERVD Derived from another key.
| PCMVARWP Imported from CCA version X'05' variable-length symmetric key-token with pedigree field.
| PCMVARNP Imported from CCA version X'05' variable-length symmetric key-token with no pedigree field.
| PCMWCV Imported from CCA key-token that contained a nonzero control vector.
| PCMNOCV Imported from CCA key-token that had no control vector or contained a zero control vector.
| PCMT31WC Imported from a TR-31 key block that contained a control vector (ATTR-CV option).
| PCMT31NC Imported from a TR-31 key block that did not contain a control vector.
| PCMPK1-2 Imported using PKCS 1.2 RSA encryption.
| PCMOAEP Imported using PKCS OAEP encryption.

| Keyword Meaning
| PCMPKA92 Imported using PKA92 RSA encryption.
| PCMZ-PAD Imported using RSA ZERO-PAD encryption.
| PCCNVTWC Converted from a CCA key-token that contained a nonzero control vector.
| PCCNVTNC Converted from a CCA key-token that had no control vector or contained a zero control
| vector.
| PCKPSEC Cleartext keys or key parts that were entered at TKE and secured from there to the target
| card.
| PCXVARWP Exported from CCA version X'05' variable-length symmetric key-token with pedigree field.
| PCXVARNP Exported from CCA version X'05' variable-length symmetric key-token with no pedigree field.
| PCXOAEP Exported using PKCS OAEP encryption.
| Optional clear key or encrypted AESKW payload section
| Payload
| Note: Not a keyword. Value returned in the payload variable.
|
| key_material_state
| The key_material_state parameter is a pointer to an integer variable containing the indicator for the
| current state of the key material. The valid values are:
| 0 No key present (internal or external)
| 1 Key is clear (internal), payload bit length is clear-key bit length
| 2 Key is encrypted under a KEK (external)
| 3 Key is encrypted under the master key (internal)
| payload_bit_length
| The payload_bit_length parameter is a pointer to an integer variable containing the number of bits in
| the token payload. If no key is present, the returned value is 0.
| If a clear key is present, the returned value is in the following range:
| AES 128, 192, or 256
| HMAC 80 - 2048
| payload
| The payload parameter is a pointer to a string variable containing the key material payload. The
| payload parameter must be addressable up to the nearest byte boundary above the
| payload_bit_length if the payload_bit_length is not a multiple of 8. This field will contain the clear key
| or the encrypted key material.
| key_verification_pattern_type
| The key_verification_pattern_type parameter is a pointer to an integer variable containing the indicator
| for the type of key verification pattern used. The valid values are:
| 0 No KVP
| 1 AESMK (8 left-most bytes of SHA-256 hash(X'01' || clear AES MK))
| 2 KEK VP (8 left-most bytes of SHA-256 hash(X'01' || clear KEK))
| key_verification_pattern_length
| The key_verification_pattern_length parameter is a pointer to an integer variable containing the
| number of bytes of data in the key_verification_pattern parameter. The valid values are 0, 8, or 16.
| The value 16 is for future use.
| key_verification_pattern
| The key_verification_pattern parameter is a pointer to a string variable containing the key verification
| pattern (KVP) of the key-encrypting key used to wrap this key. If the key_verification_pattern_type
| value indicates that a key verification pattern is present, the pattern will be copied from the token,
| otherwise this variable is empty.

| key_wrapping_method
| The key_wrapping_method parameter is a pointer to an integer variable containing the indicator for the
| encrypted section key-wrapping method used to protect the key payload. The valid values are:
| 0 NONE (for clear keys or no key)
| 2 AESKW (for external or internal key wrapped with an AES KEK)
| 3 PKOAEP2 (for external tokens wrapped with an RSA public key)
| key_hash_algorithm
| The key_hash_algorithm parameter is a pointer to an integer variable containing the indicator for the
| hash algorithm used for wrapping in the key token. The valid values are as follows:
|| Key-wrapping method
| Value Hash algorithm X'00' (clear key) X'02' (AESKW) X'03' (PKOAEP2)
| 0 No hash X
| 1 SHA-1 X
| 2 SHA-256 X X
| 4 SHA-384 X
| 8 SHA-512 X
|
| key_name_length
| The key_name_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the key_name variable. The returned value can be 0 or 64.
| key_name
| in the associated data structure of the key token. If there is no key name, then this variable is empty.
| TLV_data_length
| The TLV_data_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the TLV_data variable. The returned value is currently always zero.
| TLV_data
| The parameter is a pointer to a string variable containing the optional tag-length-value (TLV) section.
| This field is currently unused and will be empty.
| user_associated_data_length
| The user_associated_data_length parameter is a pointer to an integer variable containing the number
| of bytes of data in the user_associated_data variable. The returned value is 0 - 255.
| user_associated_data
| The user_associated_data parameter is a pointer to a string variable containing the user-associated
| data to be stored in the key token. This user-definable data is cryptographically bound to the key if it is
| encrypted. If there is no user-defined associated data, this variable is empty.
| reserved_length
| The reserved_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the reserved variable. The returned value is zero.
| reserved
| The parameter is a pointer to a string variable that is reserved for future use. This variable is empty.
| If an error occurs while processing the input token, all output lengths will be updated to zero and an error
| will be returned.
| Required commands
| None

Key_Translate (CSNBKTR)
| Use the Key_Translate verb to decipher an input key in an external fixed-length DES key-token, and then
| encipher this key using another key-encrypting key and return the reenciphered key in a different external
| fixed-length DES key-token.
| Note: This verb has been deprecated. New applications should use Key_Translate2 instead of this verb.
| See Key_Translate2 (CSNBKTR2) on page 296.
Specify the following key tokens to use this verb:

v The external (input) fixed-length DES key-token containing the key to be reenciphered.
v For key translation between key-encrypting keys:
The internal fixed-length DES key-token containing the IMPORTER or IKEYXLAT key-encrypting key.
The control vector for the IMPORTER key must have the XLATE bit set to B'1'.
The internal fixed-length DES key-token containing the EXPORTER or OKEYXLAT key-encrypting
key. The control vector for the EXPORTER key must have the XLATE bit set to B'1'.
v A 64-byte variable for the external (output) DES key-token.
The verb builds the output fixed-length DES key-token as follows:

v Copies the control vector from the input key-token.
v Verifies that the XLATE bit is set to B'1' if an IMPORTER or EXPORTER key-encrypting key is used.
v Multiply-deciphers the key under a key formed by the exclusive-OR of the key-encrypting key and the
control vector in the input key-token, multiply-enciphers the key under a key formed by the exclusive-OR
of the key-encrypting key and the control vector in the output key token; then places the key in the
output key-token.
v Copies other information from the input fixed-length DES key-token.
v Calculates a token-validation value and stores it in the output key-token.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v This verb does not support version X'10' external fixed-length DES (RKX) key tokens.

Format
CSNBKTR
input_key_token Input String 64 bytes
input_KEK_key_identifier Input String 64 bytes
output_KEK_key_identifier Input String 64 bytes
output_key_token Output String 64 bytes
Parameters
input_key_token
The input_key_token parameter is a pointer to a string variable containing an external fixed-length
DES key-token. The key token contains the key to be reenciphered (translated).
input_KEK_key_identifier
The input_KEK_key_identifier parameter is a pointer to a string variable containing the operational
fixed-length DES key-token or the key label of an operational fixed-length DES key-token record. The
key token contains the key-encrypting key used to decipher the key. It must contain a control vector
that specifies an IMPORTER or IKEYXLAT key type. The control vector for an IMPORTER key must
have the XLATE bit set to B'1'.
output_KEK_key_identifier
The output_KEK_key_identifier parameter is a pointer to a string variable containing the operational
key token contains the key-encrypting key used to encipher the key. It must contain a control vector
that specifies an EXPORTER or OKEYXLAT key type. The control vector for an EXPORTER key must
have the XLATE bit set to B'1'.
output_key_token
The output_key_token parameter is a pointer to a string variable containing an external fixed-length
DES key-token. The key token contains the reenciphered key.
Required commands
The Key_Translate verb requires the Translate Key command (offset X'001F') to be enabled in the active
role.

Key_Translate2 (CSNBKTR2)
| Use the Key_Translate2 verb to reformat or translate a symmetric key contained in one key-token into
| another key-token. This verb deprecates the Key_Translate verb, and should be used by all new
| applications.
| Reformat recovers a key from an input key-token, and places a copy of the key in a key token whose
| format differs in some way from the input key-token. An external output key is wrapped under the same
| key-encrypting key that was used to wrap the external input key.
| v Only DES keys can be reformatted in releases before Release 4.2. By specifying optional rule-array
| keywords for key-wrapping method and translation control, an external fixed-length DES key-token can
| be changed from one key-wrapping mode to another (that is, from legacy to enhanced, or from
| enhanced to legacy). The output key is returned in a different external fixed-length DES key-token. The
| same DES key-encrypting key used to unwrap the input key is used to wrap the output key.
| v Beginning with Release 4.2, an AES key can be reformatted. Specifically, an operational fixed-length
| AES key-token (older version X'04'), which always has a key type of DATA, can be reformatted into an
| operational variable-length AES key-token (newer, more secure version X'05') with a key type of
| CIPHER.
| Conversely, an operational variable-length AES key-token with a key type of CIPHER can be
| reformatted into a less secure operational fixed-length AES key-token.
| An internal version X'04' key-token is wrapped using the DES master key, while an internal X'05'
| key-token is wrapped using the more secure AES master key. Although the two AES keys are wrapped
| with different master keys, both remain operational within the same system.
| Translate recovers a key from an input key-token and places a copy of the key in a key token that does
| not differ from the input key-token. The copied key is translated by wrapping it under a different
| key-encrypting key than was used to wrap the input key.
| v Only DES keys can be translated in releases before Release 4.2. The input key must be in an external
| fixed-length DES key-token, and the output key is returned in a different external fixed-length DES
| key-token, wrapped under a different DES key-encrypting key.
| v Beginning with Release 4.2, AES keys and HMAC keys contained in external variable-length symmetric
| key tokens can be translated. A copy of the input key is returned in an identical key token, except that
| the copied key is wrapped using a different AES key-encrypting key.
| Table 44 on page 297 shows the input key tokens that are required and the output key tokens that are
| returned for a given combination of algorithm and reencipherment keywords.

| Table 44. Key_Translate2 key tokens based on algorithm and reencipherment keywords
| Algorithm Input key-token Input KEK key-token Output KEK key-token Output key-token
| REFORMAT
| AES Operational fixed-length Null or length of zero Null or length of zero On input, null or internal
| AES DATA (older (DES master-key is (stronger AES variable-length (newer
| version X'04' key-token) used to unwrap input master-key is used to version X'05' key-token)
| key) wrap output key) AES CIPHER with
| usage of CBC or ECB
| mode; on output,
| operational
| variable-length AES
| CIPHER with usage that
| allows encryption and
| decryption, mode as
| specified or CBC by
| default, and default key
| management export
| control settings
| Operational Null or length of zero Null or length of zero On input, null or internal
| variable-length AES (AES master-key is (less-secure DES fixed-length (older X'04'
| CIPHER (newer version used to unwrap input master-key is used to key-token) AES DATA;
| X'05' key-token), usage key) wrap output key; on output, operational
| allows encryption and enabling offset X'032A' fixed-length default AES
| decryption, CBC or ECB disallows this) DATA
| mode, user-defined
| extension control (UDX)
| bits must be zero, and
| key management export
| control settings must be
| default.
| DES External fixed-length Operational fixed-length Null or length of zero On input, null; on output,
| DES containing a key DES IMPORTER, (input KEK is used to external fixed-length
| IKEYXLAT, EXPORTER, wrap output key) DES with copy of CV
| or OKEYXLAT, XLATE and other information
| bit (CV bit 22) ignored taken from input
| key-token, modified as
| needed for ENH-ONLY
| (CV bit 56) and
| key-wrapping mode (flag
| byte 2)
| HMAC (Rel. Not applicable Not applicable Not applicable Not applicable
| 4.2 or later)
| TRANSLAT (Rel. 4.2 or later)
| AES (Rel. External variable-length Operational Operational On input, null; on output,
| 4.2 or later) AES containing a key variable-length AES variable-length AES external variable-length
| IMPORTER, key usage EXPORTER, key usage AES
| fields allow import fields allow export
| (IMPORT) and (EXPORT) and
| translation (TRANSLAT) translation (TRANSLAT)
| DES External fixed-length Operational fixed-length Operational fixed-length On input, null; on output,
| DES containing a key DES IMPORTER or DES EXPORTER or external fixed-length
| IKEYXLAT, CV allows OKEYXLAT, CV allows DES
| translation (CV XLATE translation (CV XLATE
| bit 22 = B'1') bit 22 = B'1')

| Table 44. Key_Translate2 key tokens based on algorithm and reencipherment keywords (continued)
| Algorithm Input key-token Input KEK key-token Output KEK key-token Output key-token
| HMAC (Rel. External variable-length Operational Operational On input, null; on output,
| 4.2 or later) HMAC containing a key variable-length AES variable-length AES external variable-length
| IMPORTER, key usage EXPORTER, key usage HMAC
| fields allow import fields allow export
| (IMPORT) and (EXPORT) and
| translation (TRANSLAT) translation (TRANSLAT)
| Notes:
| 1. The purpose of an AES REFORMAT is to convert internal AES keys between older version X'04' and newer
| version X'05' key-token formats. AES keys wrapped in version X'05' key tokens are more secure.
| 2. The purpose of a DES REFORMAT is to change the encipherment of an external DES key from one
| key-wrapping mode to another (that is, from legacy to enhanced, or from enhanced to legacy), without changing
| the encrypting key.
| 3. The purpose of a TRANSLAT is to change the encipherment of an external AES, DES, or HMAC key to a
| different key-encrypting key, without otherwise changing the key token.
|
| Restrictions
| AIX X
| IBM i X
| Windows
|
| v Clear keys are not supported.
| v Token algorithm keywords AES, DES, and HMAC are not supported in releases before Release 4.2.
| v Reencipherment keyword TRANSLAT is not supported in releases before Release 4.2.
| v AES key encrypting keys are not supported in releases before Release 4.2
Format
CSNBKTR2
| rule_array_count Input Integer 0, 1, 2, 3, or 4
| input_key_token_length Input Integer 64
input_key_token Input String input_key_token_length bytes
| input_KEK_key_identifier_length Input Integer 64
input_KEK_key_identifier Input String input_KEK_key_identifier_length bytes
| output_KEK_key_identifier_length Input Integer 64

output_KEK_key_identifier Input String output_KEK_key_identifier_length bytes

| output_key_token_length In/Output Integer See Appendix B.
output_key_token Output String output_key_token_length bytes
Parameters
rule_array_count
| The rule_array_count is a pointer to an integer variable containing the number of elements in the
| rule_array variable. The value must be 0, 1, 2, 3, or 4.
rule_array
keywords are a 8 bytes in length and must be left-aligned and padded on the right with space
characters.
|| Keyword Meaning
| Token algorithm (one, optional). Release 4.2 or later.
| AES Specifies that the input key is an AES key.
| DES Specifies that the input key is a DES key. This is the default.
| HMAC Specifies that the input key is an HMAC key.
| Reencipherment (one, optional)
| REFORMAT Specifies to change the key token in some way, without changing the encipherment of an
| external key to a different key-encrypting key. Not valid for HMAC.
| TRANSLAT (Rel. Specifies to change the encipherment of an external key to a different key-encrypting key,
| 4.2 or later) without otherwise changing the key token.
| Key-wrapping method (one, optional for DES; not allowed for any other token algorithm)
| USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method.
| WRAP-ECB Specifies to wrap the key using the legacy wrapping method.
| WRAP-ENH Specifies to wrap the key using the enhanced wrapping method.
| Translation control (optional). This is valid only with key wrapping method WRAP-ENH or with USECONFG when
| the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to
| binary zeros.
| ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it
| has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the
| control vector to B'1'.
|
input_key_token_length
| The input_key_token_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the input_key_token variable.
input_key_token
| The input_key_token parameter is a pointer to a string variable containing a symmetric key-token to be
| reformatted or translated. See Table 44 on page 297.

input_KEK_key_identifier_length
| The input_KEK_key_identifier_length parameter is a pointer to an integer variable containing the
| number of bytes of data in the input_KEK_key_identifier variable. This value can be zero if the input
| key is not external.
input_KEK_key_identifier
| The input_KEK_key_identifier parameter is a pointer to a string variable containing the operational
| AES or DES key-encrypting key when the input key-token is external, or the label of such a key in
| AES or DES key storage. If the input key is not external, identify a null key-token or set the length to
| zero. See Table 44 on page 297.
output_KEK_key_identifier_length
| The output_KEK_identifier_length parameter is a pointer to an integer variable containing the number
| of bytes of data in the output_KEK_identifier variable. For keyword REFORMAT, this value can be
| zero.
output_KEK_key_identifier
| The output_KEK_key_identifier parameter is a pointer to a string variable of the operational AES or
| DES key-encrypting key when the output key-token is external, or the label of such a key in AES or
| DES key storage. If the output key is not external, identify a null key-token or set the length to zero.
output_key_token_length
| The output_key_token_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the output_key_token variable. On output, and if the size is of sufficient length, the
| variable is updated with the actual length of the output_key_token variable.
output_key_token
| The output_key_token parameter is a pointer to a string variable containing a symmetric key-token
| containing the reformatted or translated key-token. See Table 44 on page 297.
| Required commands
| The Key_Translate2 verb requires the following commands to be enabled in the active role:
|| Rule-array keyword Offset Command
| REFORMAT X'014B' Translate Key2 (REFORMAT)
| REFORMAT X'032A' Disallow Translation from an AES X'05' to an AES X'04' Token
| (Rel. 4.2 or Note: Enable this command to prevent CIPHER keys, which are in
| later) variable-length AES key tokens (newer version X'05') and wrapped under
| the AES master-key, from being reformatted into DATA keys, which are in
| fixed-length AES key tokens (older version X'04') and wrapped under the
| less-secure DES master-key. This command overrides offset X'014B'.
| TRANSLAT (Rel. 4.2 or X'0149' Translate Key2
| later)
| WRAP-ECB or X'014A' Allow Configuration Override with Keyword in KTR2
| WRAP-ENH
| WRAP-ECB X'0147' Enable Translation from New to Old Format in KTC and KTR2
| Note: This command applies only when the input key is wrapped by the
| enhanced method, WRAP-ENH.
|
|

Multiple_Clear_Key_Import (CSNBCKM)
Use the Multiple_Clear_Key_Import verb to import a cleartext key into an internal fixed-length AES or DES
key-token. The verb creates an internal fixed-length AES or DES DATA key-token containing the specified
cleartext key, enciphered under the appropriate AES or DES master-key. You can import either:
v A 16-byte, 24-byte, or 32-byte cleartext AES key (see Restrictions on page 302)
v An 8-byte (single-length DES) or 16-byte (double-length Triple-DES) cleartext key
To use this verb, specify:

v The rule-array algorithm keyword:
Specify AES to import an AES key. Specify DES or no keyword to import a DES key.
v An optional rule-array keyword for specifying the key-wrapping method (Release 4.1 or later).
v An optional rule-array keyword for specifying the translation-control setting (Release 4.1 or later).
v The length, in bytes, of the clear key being imported:
1. For AES keys, specify 16, 24, or 32.
2. For DES keys, specify 8 or 16.
v The clear key:
1. AES keys do not have parity bits. Use any key value.
2. DES keys have parity bits. Use a key value with each byte having odd parity. If any byte of the clear
key does not have odd parity, the verb returns a warning of return code of 0, reason code of 2.
v A key identifier of a null key-token, an internal fixed-length AES or DES DATA key-token, or a key label
of a null key-token or internal fixed-length AES or DES DATA key-token:
Null key-token
The verb can create an internal fixed-length AES or DES key-token from a null key-token.
In the case of an AES key, the control vector in the output key-token is set to binary zeros.
In the case of a DES key and a clear-key length of 8, the control vector in the output key-token
is set to the value of a default single-length DATA key
In the case of a DES key and a clear-key length of 16, the control vector in the output
key-token is set to the value of a default double-length DATA key. See Table 162 on page 657.
Internal key-token
Provide an existing internal fixed-length AES or DES DATA key-token to be updated with the
enciphered value of the clear key.
For AES keys, the verb always updates the key token with the key length pointed to by the
clear_key_length parameter. If the verb modifies the key length in the AES key-token, the verb
returns a warning of return code 0, reason code 2040 (X'7F8') as notification that there might be
an unintentional key-length mismatch.
Key label
Used to identify a token in AES or DES key-storage for the verb to retrieve and update. For
AES, identify by name a fixed-length key-token in AES key-storage. For DES, identify by name
an internal fixed-length key-token in DES key-storage.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The AES algorithm is not supported in releases before Release 3.30.
Format
CSNBCKM
clear_key_length Input Integer 8, 16, 24, or 32
clear_key Input String clear_key_length bytes
Parameters
rule_array_count
rule_array

Keyword Meaning
Algorithm (optional)
AES (Rel. 3.30 or Specifies that the key is an AES key to be enciphered under the AES master key.
later)
DES Specifies that the key is a single-length DES key or a double-length (16-byte) Triple-DES
key to be enciphered under the DES master key. This is the default.
This keyword is ignored for AES keys. This is the default.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for
AES keys.
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when
the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it
has been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the
control vector to B'1'.
clear_key_length
The clear_key_length parameter is a pointer to an integer variable containing the number of bytes of
data in the clear_key variable.
If the algorithm is DES, the value must be:
v 8 for a single-length DES key
v 16 for a double-length Triple-DES key
If the algorithm is AES, the value must be:
v 16 for a 128-bit AES key
clear_key
The clear_key parameter is a pointer to a string variable containing the cleartext key to be imported.
key_identifier
On input, the key_identifier parameter is a pointer to a string variable containing a null key-token, an
internal fixed-length AES or DES DATA key-token, or a key label of a null key-token or internal
fixed-length AES or DES DATA key-token.
On output, the key token is updated with the specified cleartext key, enciphered under the appropriate
master key. A null key-token is updated with a default key-token for a DATA key.
Required commands
The Multiple_Clear_Key_Import verb requires the following commands to be enabled in the active role
based on the algorithm:

AES X'0129' Encipher Under AES Master Key
DES X'00C3' Encipher Under DES Master Key
WRAP-ECB or WRAP-ENH X'0141' Allow Configuration Override with Keyword in CKM
match keyword (Rel. 4.1 or
later)
Note: A role with offset X'00C3' can also use the Clear_Key_Import verb.

PKA_Decrypt (CSNDPKD)
Use the PKA_Decrypt verb to decrypt (unwrap) input data using an RSA private-key. For the PKCS-1.2
rule-array keyword, the decrypted data is examined to ensure that it meets RSA PKCS #1 block-type 02
(RSAES-PKCS1-v1_5) format specifications. See PKCS #1 hash formats on page 694.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v A key-usage flag bit (see offset 050 in the private-key section) must be on to permit use of the private
key in the decryption of a symmetric key.
v The RSA private-key modulus size (key size) is limited by the function control vector to accommodate
potential governmental export and import regulations. The verb enforces this restriction.
v The ZERO-PAD rule-array keyword is supported only for clear private keys contained in external RSA
tokens. This prevents the verb from being used to unwrap an object that is encrypted with a protected
key, such as a DES key wrapped by an encrypted RSA private-key.
Format
CSNDPKD
source_encrypted_key_length Input Integer 512
source_encrypted_key Input String source_encrypted_key_length bytes
data_structure_length Input Integer 0
data_structure In/Output String data_structure_length bytes
private_key_identifier_length Input Integer 3500
private_key_identifier Input String private_key_identifier_length bytes
clear_target_key_length In/Output Integer 512
clear_target_key Output String clear_target_key_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Recovery method (required)
| PKCS-1.2 Specifies that the key is formatted as defined in the RSA PKCS #1 v2.0 standard for the
| RSAES-PKCS1-v1_5 encryption/decryption scheme. Formerly known as the block-type 02
| method. See PKCS #1 hash formats on page 694.
| ZERO-PAD Decrypts the source_encrypted_key variable and places the result right-aligned in the
clear_target_key variable. The decrypted value is the same length as the modulus. As
required, high-order bits are set to zero.
Note: Supported only for clear RSA private keys.
source_encrypted_key_length
The source_encrypted_key_length parameter is a pointer to an integer variable containing the number
of bytes of data in the source_encrypted_key variable. The maximum length is 512.
source_encrypted_key
The source_encrypted_key parameter is a pointer to a string variable containing the input key to be
decrypted.
data_structure_length
The data_structure_length parameter is a pointer to an integer variable containing the number of bytes
of data in the data_structure variable. This value must be 0.
data_structure
The data_structure parameter is a pointer to a string variable. This variable is currently ignored.
private_key_identifier_length
The private_key_identifier_length parameter is a pointer to an integer variable containing the number
of bytes of data in the private_key_identifier variable. The maximum length is 3500 bytes.
private_key_identifier
The private_key_identifier parameter is a pointer to a string variable containing the RSA private-key in
a PKA key-token, or the label of an RSA private-key in a PKA key-token record, used to decrypt the
source key.
clear_target_key_length
The clear_target_key_length parameter is a pointer to an integer variable containing the number of
bytes of data in the clear_target_key variable. On input, this variable specifies the maximum
permissible length of the result. On output, this verb updates the variable to indicate the length of the
returned key. The maximum length is 512.
clear_target_key
The clear_target_key parameter is a pointer to a string variable containing the decrypted (clear) key
returned by this verb.
Required commands
The PKA_Decrypt verb requires the PKA Decipher Key Data command (offset X'011F') to be enabled in
the active role.

PKA_Encrypt (CSNDPKE)
Use the PKA_Encrypt verb to encrypt (wrap) input data using an RSA public-key. The data that you
encrypt might include:
v For keys, the encrypted data can be formatted according to RSA PKCS #1 block-type 02
(RSAES-PKCS1-v1_5) format specifications. See PKCS #1 hash formats on page 694.
v Other data, such as a digital signature, can be RSA-ciphered using the public key and the ZERO-PAD
option. The data that you provide is padded on the left with zero bits to the modulus length of the public
key. When validating a digital signature using the ZERO-PAD option, you are responsible for formatting
of the hash and any other required information. The ZERO-PAD option can be used to encipher
information, including a hash value to validate digital signatures such as ISO/IEC 9796-2.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The RSA public-key modulus size (key size) is limited by the function control vector to accommodate
governmental export and import regulations.
v A message can be encrypted provided that it is smaller than the public key modulus.
Format
CSNDPKE
clear_source_data_length Input Integer 512
clear_source_data Input String clear_source_data_length bytes
data_structure_length Input Integer 0
data_structure Input String data_structure_length bytes
public_key_identifier_length Input Integer 3500
public_key_identifier Input String public_key_identifier_length bytes
target_data_length In/Output Integer 512
target_data Output String target_data_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Format method (one required)
| PKCS-1.2 Specifies that the key is formatted as defined in the RSA PKCS #1 v2.0 standard for the
| RSAES-PKCS1-v1_5 encryption/decryption scheme. Formerly known as the block-type 02
ZERO-PAD Places clear_source_data variable in the low-order bit positions of a bit string of the same
length as the modulus. As required, high-order bits are set to zero. Encrypts the resulting
bit-string with the public key.
clear_source_data_length
| The clear_source_data_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the clear_source_data variable. When using the PKCS-1.2 keyword the maximum
| length is 501, and for ZERO-PAD, the maximum length is 512, with a 4096-bit RSA public-key.
clear_source_data
The clear_source_data parameter is a pointer to a string variable containing the input data to be
encrypted.
data_structure_length
The data_structure_length parameter is a pointer to an integer variable containing the number of bytes
of data in the data_structure variable. This value must be 0.
data_structure
The data_structure parameter is a pointer to a string variable. This variable is currently ignored.
public_key_identifier_length
The public_key_identifier_length parameter is a pointer to an integer variable containing the number of
bytes of data in the public_key_identifier variable. The maximum length is 3500 bytes.
public_key_identifier
| The public_key_identifier parameter is a pointer to a string variable containing the RSA public-key in a
| PKA key-token, or the label of such a key in PKA key-storage, used to encrypt the clear source data.
target_data_length
The target_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the target_data variable. On input, this variable specifies the maximum permissible length of
the result. On output, this verb updates the variable to indicate the length of the returned data. The
maximum output length is 512. The data length is the same as the size of the public-key modulus.
target_data
The target_data parameter is a pointer to a string variable containing the encrypted data returned by
the verb. The returned encrypted target_data variable is the same length as the public-key modulus.
Required commands
The PKA_Encrypt verb requires the PKA Encipher Clear Key command (offset X'011E') to be enabled in
the active role.

Prohibit_Export (CSNBPEX)
| Use the Prohibit_Export verb to modify an exportable internal fixed-length DES key-token so that its key
| can no longer be exported. See Prohibit_Export_Extended (CSNBPEXX) on page 311 for details on
| operating on an external fixed-length DES key-token, or Restrict_Key_Attribute (CSNBRKA) for details on
| operating on a fixed-length or variable-length external or internal symmetric key-token.
| Restrict_Key_Attribute can modify an internal DES key-token so that it can no longer be exported by the
| Key_Export_to_TR31 verb (CV bit 57). A new application program should use the Restrict_Key_Attribute
| verb because it has deprecated the Prohibit_Export verb.

v Multiply deciphers the key under a key formed by the exclusive-OR of the master key and the control
vector.
v Sets to off (zero) the XPORT-OK bit in the control vector (bit 17).
v Multiply enciphers the key under a key formed by the exclusive-OR of the master key and the modified
control vector. The encrypted key and the modified control vector are stored in the key token, and the
TVV is updated.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v This verb does not change the export control bit for TR-31 (CV bit 57).
Format
CSNBPEX
Parameters
key_identifier
The key_identifier parameter is a pointer to a string variable containing the internal fixed-length DES
key-token, or the key label of an internal fixed-length DES key-token record.

Required commands
The Prohibit_Export verb requires the Lower Export Authority command (offset X'00CD') to be enabled in
the active role.

Prohibit_Export_Extended (CSNBPEXX)
| Use the Prohibit_Export_Extended verb to modify an exportable external fixed-length DES key-token, so
| that its key can no longer be exported. See Prohibit_Export (CSNBPEX) on page 309 for details about
| operating on an internal fixed-length DES key-token, or Restrict_Key_Attribute (CSNBRKA) for details
| about operating on a fixed-length or variable-length external or internal symmetric key-token. A new
| application program should use the Restrict_Key_Attribute verb, because it has deprecated the
| Prohibit_Export_Extended verb.
The verb performs the following functions:

v Multiply deciphers the source key under a key formed by the exclusive-OR of the source key's control
vector and the specified key-encrypting key (KEK).
v Sets to off (zero) the XPORT-OK bit in the source key's control vector (bit 17).
v Multiply reenciphers the key under a key formed by the exclusive-OR of the KEK key and the source
key's modified control vector. The encrypted key and the modified control vector are stored in the
source-key key token, and the TVV is updated.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v This verb does not change the export control bit for TR-31 (CV bit 57).
Format
CSNBPEXX
source_key_token In/Output String 64 bytes
KEK_key_identifier Input String 64 bytes
Parameters
source_key_token
The source_key_token parameter is a pointer to a string variable containing an external fixed-length
DES key-token.

KEK_key_identifier
The KEK_key_identifier parameter is a pointer to a string variable containing an internal fixed-length
DES key-encrypting-key token, or the key label of an internal fixed-length DES key-encrypting-key
token record.
Required commands
The Prohibit_Export_Extended verb requires the Lower Export Authority, Extended command (offset

Random_Number_Generate (CSNBRNG)
Use the Random_Number_Generate verb to generate a random number for use as an initialization vector,
clear key, or clear key-part.
Note: To generate a random number of a specified length, use the Random_Number_Generate_Long

verb.
You specify whether the random number is 56 bits with the low-order bit in each of the 8 bytes adjusted
for even or for odd parity, or 64 bits without parity adjustment. The verb returns the random number in an
8-byte string variable.
Because the Random_Number_Generate verb uses cryptographic processes, the quality of the output is
better than that which higher-level language compilers typically supply.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBRNG
form Input String 8 bytes
random_number Output String 8 bytes
Parameters
form
The form parameter is a pointer to a string variable containing a keyword to select the characteristic of
the random number. The keyword is 8 bytes in length and must be left-aligned and padded on the
right with space characters. The form keywords are:

Keyword Meaning
Generation type (one required)
RANDOM Requests the generation of a 64-bit random number.
ODD Requests the generation of a 56-bit, odd parity, random number.
EVEN Requests the generation of a 56-bit, even parity, random number.
random_number
The random_number parameter is a pointer to a string variable containing the random number
returned by the verb.
Required commands
The Random_Number_Generate verb requires the Generate Key command (offset X'008E') to be enabled
in the active role.

Random_Number_Generate_Long (CSNBRNGL)
Use the Random_Number_Generate_Long verb to generate a random number ranging from 1 - 8192
bytes long. Choose the parity of each generated random byte as even, odd, or random. The verb returns
the random number in a string variable.
Because the Random_Number_Generate_Long verb uses cryptographic processes, the quality of the
output is better than that which higher-level language compilers typically supply.
Restrictions
| AIX X X X
| IBM i X X
| Windows X X
|
| Format
CSNBRNGL
seed_length Input Integer 0
seed Input String seed_length bytes
random_number_length In/Output Integer 1 - 8192 on input (also 0 on output)
random_number Output String random_number_length bytes
Parameters
rule_array_count
rule_array
keywords are 8 bytes in length, and must be left-aligned and padded on the right with space
characters.

Keyword Meaning
Parity adjust (one required)
EVEN Specifies that each generated random byte is adjusted for even parity.
ODD Specifies that each generated random byte is adjusted for odd parity.
RANDOM Specifies that each generated random byte is not adjusted for parity.
seed_length
The seed_length parameter is a pointer to an integer variable containing the number of bytes in the
seed variable. The value must be 0.
seed
The seed parameter is a pointer to a string variable containing a seed value. A seed can be supplied
so that the same value of the random number can be obtained in multiple instances. This can be
useful in testing situations. This variable is currently unused.
random_number_length
The random_number_length parameter is a pointer to an integer variable containing the number of
bytes in the random_number variable. On input, the minimum value is 1 and the maximum value is
8192.
Use this variable to specify the number of random bytes that the verb is to return. On output, this
variable contains the number of bytes returned by the verb in the random_number variable.
random_number
The random_number parameter is a pointer to a string variable containing the random number
generated.
Required commands
None

Remote_Key_Export (CSNDRKX)
Use the Remote_Key_Export verb as a method of secured transport of DES keys using asymmetric
techniques from a security module (for example, the 4764 PCI-X Cryptographic Coprocessor) to a remote
device such as an Automated Teller Machine (ATM). The DES keys to be transported are either key
encrypting keys that are generated within the coprocessor or, alternately, operational keys or replacement
KEKs enciphered under a KEK currently installed in a remote device.
Generating and exporting DES keys: This verb uses a trusted block to generate or export DES keys.
To create a trusted block, see Trusted_Block_Create (CSNDTBC) on page 353. It accepts as input
parameters a trusted block, a public-key certificate and certificate parameters, a transport key, a rule ID to
identify the appropriate rule section to be used within a trusted block, an importer key, a source key,
optional extra data that can be used as part of the OAEP key-wrapping process, and key-check
parameters used to calculate an optional key-check value.
The verb validates all input parameters for generate and export operations. After the verb performs the
input parameter validation, the remaining steps depend on whether the generate option or the export
option is specified in the selected rule of the trusted block.
The following is a high-level description of the remaining processing steps for generate and export.
Processing steps for generate operation: The verb performs these steps for the generate operation:
1. Generates a random value for the generated key, K. The generated key length specified by the
selected rule determines the key length.
2. Exclusive-ORs the output key variant with the randomly generated key K from the previous step if the
selected rule contains a common export key parameters subsection and the output key variant length
is greater than zero. Adjusts the result to have valid DES key parity.
3. Continues with Final processing steps common to generate and export operations on page 320.
Processing steps for export operation: The verb performs these steps for the export operation:
| 1. If the trusted block Common Export Key Parameters subsection is not present, return an error.
| 2. If the trusted block Source Key Rule Reference subsection is not present and the source_key input
| parameter is an RKX key-token, return an error.
| 3. If input source_key_length variable equals 0, return an error.
| 4. If the trusted block Transport Key Rule Reference subsection exists, return an error if either of these
| conditions is true:
| v The transport_key_identifier input parameter does not identify an RKX token.
| v The Rule ID in the RKX key-token identified by the transport_key_identifier parameter is not equal
| to the rule ID in the Transport Key Rule Reference subsection.
| 5. If the trusted block Transport Key Variant subsection exists, return an error if either of these
| conditions is true:
| v The length of the transport key obtained from the transport_key_identifier variable is greater than
| the length of Variant in the Transport Key Variant Reference subsection.
| v The Symmetric Encrypted Output Key Format Flag equals RKX key-token format.
| Note: Transport keys are not used for symmetric encrypted output keys that are RKX key-tokens.
| 6. Verify that the source key token length is:
| v 0 if the trusted block's selected Rule section Generate/Export flag equals B'0' (generate key).
| v 64 if the trusted block's selected Rule section Generate/Export flag equals B'1' (export key).
| 7. Obtain the length of the source key from the source key identifier. Verify that the length of the source
| key is greater than or equal to Export Key Minimum Length and is less than or equal to Export Key
| Maximum Length in the trusted block's selected rule section's Common Export Key Parameters
| subsection.
| 8. Verify that the length of the source key is less than or equal to the Output Key Variant Length in the
| Common Export Key Parameters subsection if the output key variant length is nonzero.
| 9. Recover the clear value of the source key in the input source key identifier key block:

| If the source_key_identifier parameter identifies an RKX key-token:
| v Verify that the Source Key Rule Reference TLV Object exists.
| v Verify that the Rule ID within the Source Key Rule Reference subsection matches the source key
| RKX key-token Rule ID.
| v Verify that the PKA master key MKVP matches the MKVP of the trusted block contained in the
| Protection Information subsection.
| v Recover the MAC key in the trusted block, then use that MAC key to compute the MAC over the
| source RKX key-token, then verify that the computed MAC equals the MAC value stored in the
| source RKX key-token.
| v Recover the source key in the RKX key-token using the recovered MAC key.
| If the source_key_identifier parameter identifies an external CCA key-token:
| v Verify that the importer key is a DES key token of type IMPORTER.
| v Verify that the importer key length is greater than or equal to the source key length. Verify that the
| importer key is an internal DES key-token.
| v Decrypt the source key under the IMPORTER importer key.
| v Verify the validity of the source key control vector (CV) as follows:
| If the Export Key CCA Token Parameters subsection's CV Limit Mask Length is nonzero, then the
| CV for the source key is first logically AND'ed with the CV Limit Mask. The result is then compared
| with the required CV bits located in the CV Limit Template. Both the mask and template are
| located in the Export Key CCA Token Parameters TLV Object. Return an error if a mismatch
| occurs.
| v If the length of the CV in the trusted block's selected rule section's Common Export Key Parameter
| subsection indicates a double-length key, and if the source key contained in the input key-block is
| a single-length key, and if the Symmetric Encrypted Output Key Format Flag indicates that the
| output is to be CCA format, and if the CV key form bits indicate "not guaranteed" unique halves
| and not single, then the single-length key is replicated to 16 bytes.
| subsection indicates a single-length key, and if the source key contained in the input key block is a
| double-length key, return an error.
| If the source_key_identifier parameter identifies an internal CCA key-token:
| v If the source_key_identifier parameter points to a label, then the label is replaced with an internal
| CCA key-token from key storage.
| v Recover the source key using the symmetric master key.
| v Verify the validity of the source key control vector (CV) as follows:
| If the Export Key CCA Token Parameters subsection's CV Limit Mask Length is nonzero, then the
| CV for the source key is first logically AND'ed with the CV Limit Mask. The result is then compared
| with the required CV bits located in the CV Limit Template. Both the mask and template are
| located in the Export Key CCA Token Parameters TLV Object. Return an error if a mismatch
| occurs.
| subsection indicates a double-length key, and if the source key contained in the input key-block is
| a single-length key, and if the Symmetric Encrypted Output Key Format Flag indicates that the
| output is to be CCA format, and if the CV key form bits indicate "not guaranteed" unique halves
| and not single, then the single-length key is replicated to 16 bytes.
| subsection indicates a single-length key, and if the source key contained in the input key block is a
| double-length key, return an error.
| 10. If the source_key_identifier parameter points to a label, verify the label and its length as follows:
| v If the length of the label pointed to by the source_key_identifier parameter is nonzero and the
| trusted block contains a Source Key Label Template Length of nonzero in the Export Key CCA
| Token Parameters subsection, verify that the Source Key Label Template matches against the
| host-supplied key label contained in the source_key_identifier variable. Wild cards (asterisks) may
| be used in the Export Key Label Template field so that the template can match a set of related key
| labels from the host.
| v Return an error if the Export Key Label Template Length is not 0 or 64.

| v Return an error if the Export Key Label Template in the Export Key CCA Token Parameters
| subsection does not match the label pointed to by the source_key_identifier parameter. The Export
| Key Label Template may contain wild cards to match a set of related key labels passed from the
| host.
| v If the length of the label pointed to by the source_key_identifier parameter equals 0, return an error
| if the Export Key Label Template Length in the Export Key CCA Token Parameters subsection is
| nonzero.
| 11. Recover the clear value of the transport_key in the transport_key_identifier:
| v If the trusted block's selected rule section's Symmetric Encrypted Output Key Format equals RKX
| key-token format, skip this step because transport keys are meaningless for RKX key-token output.
| Otherwise, continue.
| v Recover the clear value of the transport key received in the transport_key_identifier as follows:
| If the transport_key_identifier parameter identifies aan RKX key-token:
| Determine whether the trusted block's selected Rule section's Transport Key Rule Reference
| subsection exists. If so, return an error if the Rule ID in the Transport Key Rule Reference
| subsection does not equal the Rule ID value from the transport key RKX key-token.
| Verify that the PKA master key MKVP matches the trusted block's MKVP contained in the
| Protection Information subsection.
| Recover the MAC key in the trusted block, then using that MAC key, compute the MAC over the
| transport RKX key-token, then verify that the computed MAC equals the MAC value stored in
| the transport RKX key-token.
| Recover the source key in the RKX key-token using the recovered MAC key.
| If the Transport Key Variant Length is greater than the transport key length, the variant located
| in the trusted block's Rule section's Transport Key Variant subsection is truncated on the right to
| the length of the key before it is XORed into the cleartext transport key. If the Transport Key
| Variant Length equals the transport key length, the complete variant will be XORed into the
| cleartext transport key.
| If the Transport Key Variant Length is less than the transport key length, an error is returned.
| Verify that the transport key is at least 16 bytes in length.
| Return an error if the transport key has equal left and right halves and the source key has
| unique left and right halves.
| If the transport_key_identifier parameter identifies an internal CCA key-token:
| Recover the transport key under the symmetric master-key.
| If the control vector of the transport key indicates an EXPORTER key type and the source key
| is an external CCA key token containing a CV with the Export bit 17 set to B'0' (prohibit export),
| an error is returned. Note that the XPORT-OK bit in the CV of the source key is ignored if the
| transport key is an IMPORTER.
| If the Transport Key Variant Length is greater than the length of the transport key, the variant
| found in the trusted block's Rule section's Transport Key Variant subsection is truncated on the
| right to the length of the key before it is XORed into the cleartext transport key.
| If the Transport Key Variant Length equals the transport key length, the complete variant will be
| XORed into the cleartext transport key.
| If the Transport Key Variant Length is less than the transport key length, an error is returned.
| Verify that the transport key is at least 16 bytes in length.
| Return an error if the transport key has equal left and right halves and the source key has
| unique left and right halves.
| 12. Replicate source key if necessary.
| If the source key is an 8-byte key and if the CV contained in the trusted block's selected Rule
| section's Common Export Key Parameters subsection is 16 bytes, then the source key is replicated
| (equal halves) if the key-form bits (bits 40 - 42) in the CV do not specify B'000' (single-length key)
| and the CV bit 40 is not set to B'1'. Otherwise the RKX operation is not run and an error is returned.
| 13. Apply Output Key Variant to the source key if applicable:
| v If the trusted block's selected Rule section's Common Export Key Parameters subsection's Output
| Key Variant Length is not equal to 0, then XOR the Output Key Variant with the cleartext value of
| the source key.

| v The length of the Output Key Variant must be greater than or equal to the source key length. If the
| Output Key Variant is longer than the source key, the leftmost bytes of the variant up to the key
| length are used.
14. Continues with Final processing steps common to generate and export operations.
| Final processing steps common to generate and export operations: At this point, the source key is
| used from Step 2 in Processing steps for generate operation on page 317, or from Step 13 in
| Processing steps for export operation on page 317:
| 1. Based on the symmetric encrypted output key-format flag of the selected rule, returns the encrypted
| result in the token identified by the sym_encrypted_key_identifier parameter by completing the
| following steps:
| v The MKVP in the trusted block's Protection Information subsection of the Information section is
| compared with the PKA master keys' MKVP. If the comparison is successful,
| v The MAC key that resides within the trusted block is recovered. The recovered MAC key is then
| used to encrypt the source key.
| v An RKX key-token is constructed with the encrypted source key, and the rule ID from the trusted
| block's Rule section.
| v The recovered MAC key is used to compute the MAC over the newly constructed RKX key-token.
| The MAC is then appended to the RKX key-token.
| 2. Based on the asymmetric encrypted output key-format flag of the selected rule, returns the encrypted
| result in the token identified by the asym_encrypted_key_identifier parameter by completing the
| following steps. If the asymmetric encrypted output key format is NONE, no asymmetric encrypted
| output will be generated.
| v Verify certificate digital signature
| If input certificate_length variable is nonzero, use the public key identified by the
| trusted_block_identifier parameter to verify the digital signature embedded in the certificate as
| follows:
| Verify that the certificate length does not exceed the maximum allowed.
| Verify root public key exists, which is located in the Trusted RSA Public Key section of the key
| token identified by the trusted_block_identifier parameter. Return an error if the Trusted RSA
| Public Key section is not found.
| Create the certificates hash:
| - Verify root public key modulus length. Return an error if modulus length in the Trusted RSA
| Public Key section is greater than the maximum modulus length allowed by the FCV.
| - Verify root public key exponent. Return an error if the public exponent of the Trusted RSA
| Public Key section is an even number.
| - Generate an RSA key token.
| a. Copy the root public key exponent and length located in Trusted RSA Public Key section
| X'11' into an RsaKeyTokenPublic key.
| b. Copy the root public key modulus bit length located in Trusted RSA Public Key section
| X'11' into an RsaKeyTokenPublic key.
| c. Copy the root public key modulus and byte length located in Trusted RSA Public Key
| section X'11' into an RsaKeyTokenPublic key.
| Hash the data in the certificate:
| Create hash of the data pointed to by certificate base + certificate_parms offset 028 decimal, for
| a length of certificate_parms "length of data to be hashed" at offset 032 decimal, using hashing
| algorithm specified by the certificate_parms "hashing algorithm identifier" at offset 024 decimal.
| Only the SHA-1 algorithm will be supported initially. Create the BER encoded form of the hash.
| Generate comparative hash:
| Generate comparative hash using the certificate's digital signature pointed to by certificate base +
| certificate_parms offset 016 decimal for a length of certificate_parms offset 020 decimal, and the
| built RSA internal token. Create the PKCS 1.0 or 1.1 format (depending upon the

| certificate_parms encryption method at offset 25 decimal) of the BER encoded hash. Perform the
| RSA encryption of the certificate's digital signature with the public key in the RsaKeyTokenPublic
| key generated above.
| Compare hashes:
| Compare the "comparative hash" (above) with the "created hash" (above) for a length specified
| by the hashing algorithm at certificate_parms offset 024 decimal. Return an error if not equal.
| v If the asymmetric encrypted output key format is PKCS1.2, format the source key into a
| PKCS_encryption_block.
| v If the asymmetric encrypted output key format is RSAOAEP, format the source key into an
| OAEP_encryption_block.
| v Generate an RSA key token:
| Copy the public key exponent (from certificate) and length (from certificate parms) into the Rsa
| Key Token Public Key section.
| Copy the public key modulus bit length (from certificate parms) into the Rsa Key Token Public
| Key section.
| Copy the root public key modulus (from certificate) and byte length (from certificate parms) into
| the Rsa Key Token Public Key section.
| v Perform the RSA encryption of the encryption block (either the PKCS_encryption_block or the
| OAEP_encryption_block) from above with the RSA key token generated from the previous step and
| place the results in the asym_encrypted_key_identifier.
| 3. Returns the computed key-check value as determined by the trusted_block_identifier's key-check
| algorithm identifier, if the key-check algorithm identifier in the specified rule indicates to compute a
| key-check value. The value is returned in the key_check_value variable.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v AES keys are not supported by this verb.

Format
CSNDRKX
trusted_block_identifier_length Input Integer 0 - 3500
trusted_block_identifier Input String trusted_block_identifier_length bytes
certificate_length Input Integer 0 - 5000
certificate Input String certificate_length bytes
certificate_parms_length Input Integer 36
certificate_parms Input String certificate_parms_length bytes
transport_key_identifier_length Input Integer 0 or 64
transport_key_identifier Input String transport_key_identifier_length bytes
rule_id_length Input Integer 8
rule_id Input String rule_id_length bytes
importer_key_identifier_length Input Integer 0 or 64
importer_key_identifier Input String importer_key_identifier_length bytes
source_key_identifier_length Input Integer 0 or 64
asym_encrypted_key_length In/Output Integer 512
asym_encrypted_key Output String asym_encrypted_key_length bytes
sym_encrypted_key_identifier_length In/Output Integer 64
sym_encrypted_key_identifier Output String sym_encrypted_key_identifier_length bytes
extra_data_length Input Integer
extra_data Input String extra_data_length bytes
key_check_parameters_length Input Integer 0
key_check_parameters Input String key_check_parameters_length bytes
key_check_value_length In/Output Integer 0 - 16
key_check_value Output String key_check_value_length bytes
Parameters
rule_array_count
rule_array
The rule_array parameter is a pointer to a string variable. This variable is currently ignored.
trusted_block_identifier_length
The trusted_block_identifier_length parameter is a pointer to an integer variable containing the number
of bytes of data in the trusted_block_identifier variable. The maximum length is 3500 bytes.

trusted_block_identifier
The trusted_block_identifier parameter is a pointer to a string variable containing a trusted block
key-token of an internal trusted block, or the key label of a trusted block key-token record of an
internal trusted block. See Trusted blocks on page 600. It is used to validate the public-key certificate
and to define the rules for key generation and key export.
certificate_length
The certificate_length parameter is a pointer to an integer variable containing the number of bytes of
data in the certificate variable. The maximum length is 5000 bytes.
It is an error if the certificate_length variable is 0 and the trusted block's asymmetric encrypted output
key format in the rule section selected by the rule_id variable indicates PKCS-1.2 output format or
RSA-OAEP output format.
If the certificate_length variable is 0 or the trusted block's asymmetric encrypted output key format in
the rule section selected by the rule_id variable indicates no asymmetric key output, the certificate is
ignored.
certificate
The certificate parameter is a pointer to a string variable containing a public-key certificate. The
certificate must contain the public-key modulus and exponent in binary form, as well as a digital
certificate. The certificate must verify using the root public key that is in the trusted block pointed to by
the trusted_block_identifier parameter.
Note: After the hash is computed over the certificate data specified by offsets 28 and 32, the hash is
ASN.1 BER encoded by prepending these bytes:
X'30213009 06052B0E 03021A05 000414'
See PKCS #1 hash formats on page 694.

certificate_parms_length
| The certificate_parms_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the certificate_parms variable. The length must be 36 provided that (1) the selected
| rule's asymmetric output format is either PKCS1.2 or RSAOAEP, and (2) the certificate_length variable
| is nonzero.
| Note: If the select rule's asymmetric output format is NONE, the certificate_parms_length variable is
| ignored.
certificate_parms
The certificate_parms parameter is a pointer to a string variable containing a structure for identifying
the location and length of values within the public-key certificate pointed to by the certificate
parameter.
If the value of the certificate_length variable is 0, then the information in this variable is ignored but the
variable must be declared.
The format of the certificate_parms variable is defined in Table 45 on page 324.

Table 45. Parameters format for public-key certificate
Offset Length
(bytes) (bytes) Description (offsets and lengths are in bytes)
0 4 Offset of modulus
4 4 Length of modulus
8 4 Offset of public exponent
12 4 Length of public exponent
16 4 Offset of digital signature
20 4 Length of digital signature
24 1 Identifier for digital signature hash formatting method. The following value is defined:
Identifier Hash algorithm
X'01' SHA-1
25 1 Identifier for digital signature hash formatting method used. The following value is
defined:
Identifier Hash formatting method
X'01' PKCS-1.0
X'02' PKCS-1.1
26 2 Reserved, must be binary zeros
28 4 Offset of first byte of certificate data hashed to compute the digital signature
32 4 Length of certificate data hashed to compute the digital signature
Note: The modulus, exponent, and signature values can have bit lengths that are not multiples of 8;
each of these values is right-aligned and padded on the left with 0 bits to make it an even
number of bytes in length.
transport_key_identifier_length
The transport_key_identifier_length parameter is a pointer to an integer variable containing the number
of bytes of data in the transport_key_identifier variable. The length must be 0 or 64 bytes.
The transport_key_identifier parameter is a pointer to a string variable containing a KEK key-token, or
a key label of a KEK key-token record. The KEK is either an internal fixed-length DES key-token (key
type IMPORTER or EXPORTER), or an external version X'10' (RKX) DES key-token. It is used to
encrypt a key exported by the verb.
When the symmetric encrypted output key format flag of the selected rule indicates return an RKX
key-token, this parameter is ignored and should have a length of 0.
If this parameter points to a DES key-token:
v The token must be of key type IMPORTER or EXPORTER
v If the source_key_identifier parameter identifies an internal DES key-token, the token must be of
key type EXPORTER
rule_id_length
The rule_id_length parameter is a pointer to an integer variable containing the number of bytes of data
in the rule_id variable. The length must be 8 bytes.
rule_id
The rule_id parameter is a pointer to a string variable that identifies the rule in the trusted block to be
used to control key generation or export. The trusted block can contain multiple rules, each of which is
identified by a unique rule ID value.
importer_key_identifier_length
The importer_key_identifier_length parameter is a pointer to an integer variable containing the number
of bytes of data in the importer_key_identifier variable. The length must be 0 or 64 bytes.
The importer_key_identifier parameter is a pointer to a string variable containing an IMPORTER KEK
key-token or a label of an IMPORTER KEK key-token record. This KEK is used to decipher the key
pointed to by the source_key_identifier parameter.
The importer_key_identifier variable is ignored if the verb is used to generate a new key, or the
source_key_identifier variable contains either an RKX key token or an internal fixed-length DES
key-token.
of bytes of data in the source_key_identifier variable. The length must be 0 or 64 bytes.
The source_key_identifier parameter is a pointer to a string variable containing a fixed-length DES
key-token or a label of a fixed-length DES key-token record. The key token contains the key to be
exported, and must meet one of these criteria:
v It is a single-length or double-length external DES key-token
v It is a single-length or double-length internal DES key-token
v It is a single-length, double-length, or triple-length RKX key-token
Notes:
1. If the key token is a CCA DES key-token, its XPORT-OK control vector bit (bit 17) must be 1, or
the export will not be allowed.
2. If a DES key-token has three 8-byte key parts, the parts are considered unique if any two of the
three key parts differ.
asym_encrypted_key_length
The asym_encrypted_key_length parameter is a pointer to an integer variable containing the number
of bytes of data in the asym_encrypted_key variable. On output, the variable is updated with the actual
length of the asym_encrypted_key variable. The input length must be at least the length of the
modulus in bytes of the public-key in the certificate variable.
asym_encrypted_key
The asym_encrypted_key parameter is a pointer to a string variable containing a generated or
exported clear key returned by the verb. The clear key is encrypted by the public (asymmetric) key
provided by the certificate variable.
sym_encrypted_key_identifier_length
The sym_encrypted_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the sym_encrypted_key_identifier variable. On output, the variable is
updated with the actual length of the sym_encrypted_key_identifier variable. The input length must be
at least 64 bytes.
sym_encrypted_key_identifier
The sym_encrypted_key_identifier parameter is a pointer to a string variable. On input, the
sym_encrypted_key_identifier variable must either contain a key label of a fixed-length DES key-token
record or an RKX key-token record, or be filled with binary zeros. On output, the verb produces a
fixed-length DES key-token or an RKX key-token, depending on the value of the symmetric encrypted
output key format value of the rule section within the trusted_block_identifier variable. The key token
produced contains either a generated or exported key encrypted using the key-encrypting key provided
by the transport_key_identifier variable.
v If the output is an external fixed-length DES key-token:
1. If a common export key parameters subsection (X'0003') is present in the selected rule, the CV
is copied from the subsection into the output CCA DES key-token. Otherwise, the CV is copied
from source key-token.

2. If a transport key variant subsection (X'0001') is present in the selected rule, the key is multiply
enciphered under the transport key exclusive-ORed with the transport key variant from the
subsection. Otherwise, the key is multiply enciphered under the transport key exclusive-ORed
with binary zeros.
3. Exclusive-ORs the CV in the token with the encrypted result from the previous step.
4. Stores the previous result in the token and updates the TVV.
v If the output is an (external) RKX key-token:
1. Encrypts the key using a variant of the trusted block MAC key
2. Builds the token with the encrypted key and the rule_id variable
3. Calculates the MAC of the token contents and stores the result in the token
If the sym_encrypted_key_identifier variable is a key label on input, on output the key token produced
by the verb is stored in DES key-storage and the variable remains the same. Otherwise, on output the
variable is updated with the key token produced by the verb, provided the field is of sufficient length.
extra_data_length
The extra_data_length parameter is a pointer to an integer variable containing the number of bytes of
data in the extra_data variable. The length must be less than or equal to the byte length of the
certificate public key modulus minus the generated/exported key length minus 42 (X'2A'), which is the
OAEP overhead. For example, if the public key in the certificate has a modulus length of 1024 bits
(128 bytes), and the exported key is single length, then the extra data length must be less than or
equal to 128 minus 8 minus 42, which equals 78.
extra_data
The extra_data parameter is a pointer to a string variable containing extra data to be used as part of
the OAEP key-wrapping process. The extra_data variable is used when the output format for the
RSA-encrypted key that is returned in the asym_encrypted_key variable is RSA-OAEP; otherwise, it is
ignored.
Note: The RSA-OAEP format is specified as part of the rule in the trusted block.
key_check_parameters_length
The key_check_parameters_length parameter is a pointer to an integer variable containing the number
of bytes of data in the key_check_parameters variable. The length must be 0.
Reserved for future use.
key_check_value_length
The key_check_value_length parameter is a pointer to a string variable containing the number of bytes
of data in the key_check_value variable. On output, and if the field is of sufficient length, the variable
is updated with the actual length of the key_check_value variable.
key_check_value
The key_check_value parameter is a pointer to a string variable containing the result of the key-check
algorithm chosen in the rule section of the selected trusted block. See Encrypt zeros DES-key
verification algorithm on page 679 and Modification Detection Code calculation on page 679.
When the selected key-check algorithm is to encrypt an 8-byte block of binary zeros with the key, and
the generated or exported key is:
v Single length
1. A value 0, 1, or 2 is considered insufficient space to hold the output encrypted result and the
verb returns an error
2. A value of 3 returns the leftmost 3 bytes of the encrypted result if the key_check_value_length
variable is 3 or more, else an error is returned
3. A value of 4 - 8, inclusive, returns the leftmost 4 bytes of the encrypted result if the
key_check_value_length variable is 4 or more, else an error is returned

v Double length or triple length
The verb returns the entire 8-byte result of the encryption in the key_check_value variable if the
key_check_value_length variable is 8 or more, else an error is returned
When the selected key-check algorithm is to compute the MDC-2 hash of the key, and the generated
or exported key is single length, the 8-byte key is made into a double-length key by replicating the key
halves. This is because the MDC-2 calculation method does no padding, and requires that the data be
at least 16 bytes and a multiple of 8 bytes. If the generated or exported key is double length or triple
length, the key is processed as is. The verb returns the 16-byte hash result of the key in the
key_check_value variable if the key_check_value_length variable is large enough, else an error is
returned.
Required commands
The Remote_Key_Export verb requires the Generate or Export a Key for Use By a Non-CCA Node
command (offset X'0312') to be enabled in the active role.
The verb also requires the Replicate Key command (offset X'00DB') to be enabled to replicate a
single-length source key (either from a fixed-length DES key-token or an RKX key-token). If authorized,
key replication occurs if all of the following are true:
1. The key token returned using the sym_encrypted_key_identifier parameter is a fixed-length DES
key-token, as defined in the rule section identified by the rule_id parameter
2. The rule section identified by the rule_id parameter has a common export key parameters subsection
defined, and the control vector in the subsection is 16 bytes in length with key-form bits of B'010' for
the left half and B'001' for the right half (see Key-form bits, 'fff' and 'FFF' on page 660)
3. The token identified by the source_key_identifier parameter is single length, and is either a fixed-length
DES key-token or an RKX key-token.
Note: A role with X'00DB' enabled can also use the Key_Generate verb with the SINGLE-R key-length
keyword.

Restrict_Key_Attribute (CSNBRKA)
| Use the Restrict_Key_Attribute verb to lower the export authority of one or more export control attributes in
| a symmetric key-token. Before Release 4.2, the key must be in an HMAC internal variable-length
| symmetric key-token. Beginning with Release 4.2, support for key-encrypting keys is added, along with
| support for the AES and DES algorithms. With this support, an HMAC key can be also in an external
| variable-length symmetric key-token, provided that a suitable key-encrypting key is provided. Likewise, an
| AES key can be in an external or internal AES variable-length symmetric key-token (version X'05'); an AES
| key cannot be in an AES fixed-length symmetric key-token (version X'04'). A DES key can be in an
| external or internal fixed-length CCA key-token; it cannot be in an external TR-31 key block.
| This verb deprecates the Prohibit_Export and Prohibit_Export_Extended verbs, and should be used for all
| new applications.
| The use of this verb requires an awareness of the different export control attributes in the key
| management fields or control vector of each key token. The following table describes these attributes:
|| Attribute Parse keyword Meaning
| AES or HMAC variable-length symmetric key token
| B'1xxx xxxx' XPRT-SYM Allow export using symmetric key.
| B'0xxx xxxx' NOEX-SYM Prohibit export using symmetric key.
| B'x1xx xxxx' XPRTUASY Allow export using unauthenticated asymmetric key.
| B'x0xx xxxx' NOEXUASY Prohibit export using unauthenticated asymmetric key.
| B'xx1x xxxx' XPRTAASY Allow export using authenticated asymmetric key.
| B'xx0x xxxx' NOEXAASY Prohibit export using authenticated asymmetric key.
| Key-management field 1, low-order byte, symmetric:
| B'0xxx xxxx' XPRT-DES Allow export using DES key.
| B'1xxx xxxx' NOEX-DES Prohibit export using DES key.
| B'x0xx xxxx' XPRT-AES Allow export using AES key.
| B'x1xx xxxx' NOEX-AES Prohibit export using AES key.
| Key-management field 1, low-order byte, asymmetric
| B'xxxx 0xxx' XPRT-RSA Allow export using RSA key.
| B'xxxx 1xxx' NOEX-RSA Prohibit export using RSA key.
| DES fixed-length key-token
| Control vector bit 17
| B'1' XPORT-OK Allows the key to be exported by any export verb except for
| NOT31XPT restriction.
| B'0' NO-XPORT Prohibits the key from being exported by any export verb.
| Control vector bit 57
| B'0' T31XPTOK Allows the key to be exported by the Key_Export_to_TR31 verb,
| provided XPORT-OK attribute is set.
| B'1' NOT31XPT Prohibits the key from being exported by the Key_Export_to_TR31
| verb.
|

| v From 1 - 9 rule array keywords

A required token algorithm keyword for the type of algorithm for which the input key can be used,
either AES, DES, or HMAC
An optional export control keyword. Use this keyword, either explicitly or by default, to lower the
export authority of all available export control attributes. Otherwise, use one or more of the export
control keywords from the AES and HMAC group or the DES group, as applicable.
If the specified algorithm is AES or HMAC, and only a subset of export control attributes is to be
lowered, provide from 1 - 6 keywords from the export control for the AES or HMAC group. If the
NOEXPORT keyword is specified along with any of the keywords in this group, all of the export
control attributes in the group will have their export authority lowered.
If the specified algorithm is DES, and only one of the export control attributes is to be lowered,
specify one of the keywords from the export control for the DES group. Otherwise, do not specify
either keyword from this group and both keywords are the default.
A KEK identifier rule keyword that is required if the KEK_key_identifier parameter identifies an RSA
key-encrypting key, otherwise the keyword is optional. Do not specify a KEK identifier rule keyword if
the input key is in an internal key-token. Use one of these keywords only for when the input key is in
an external key-token. It serves the purpose of identifying which key-storage dataset contains the
key-encrypting key when a key label is passed in the KEK_key_identifier variable.
v The identifier of the input key, either in an external or internal key-token, or the label of such a key in
key storage. For AES or HMAC, the key must be in a variable-length symmetric key token. For DES,
the key must be in a fixed-length DES key-token. The key can be clear or encrypted.
v If the input key is in an external key-token, provide the identifier of the operational key-encrypting key
that was used to encipher the input key. If the KEK is in key storage, and the KEK is an RSA
key-encrypting key, a KEK identifier rule keyword is required.
Restrictions
| AIX X
| IBM i X
| Windows
|
| v The following rule array keywords are not supported in releases before Release 4.2:
| Token algorithm keywords AES and DES
| Export control for AES or HMAC keywords NOEX-AES, NOEX-DES, and NOEX-RSA
| Export control for DES keywords CCAXPORT and NOT31XPT
| KEK identifier rule keywords IKEK-AES, IKEK-DES, and IKEK-PKA
| v External key tokens are not supported in releases before Release 4.2. The KEK_key_identifier_length
| variable must be 0.

Format
CSNBRKA
| rule_array_count Input Integer 1-9
key_identifier_length In/Output Integer 64
| KEK_key_identifier_length Input Integer 0, 64
KEK_key_identifier Input String KEK_key_identifier_length bytes
| opt_parameter1_length Input Integer 0
| opt_parameter1 Input String opt_parameter1_length bytes
| opt_parameter2_length Input Integer 0
| opt_parameter2 Input String opt_parameter2_length bytes
Parameters
rule_array_count
| in the rule_array variable. The value must be 1 - 9.
rule_array
characters.
|| Keyword Meaning
| AES (Rel. 4.2 or Specifies to lower the export authority of an AES key. A key in a fixed-length AES key-token
| later) is not supported.
| DES (Rel. 4.2 or Specifies to lower the export authority of a DES key.
| later)
| HMAC Specifies to lower the export authority of an HMAC key.

| Keyword Meaning
| Export control (one, optional)
| NOEXPORT Prohibits the key from being exported by any verb. The use of this keyword always causes
| each available export control attribute to be lowered. If no export control keywords are used,
| this is the default.
| Variable-length symmetric key-token: This keyword is equivalent to providing all of the

| keywords listed under export control for AES or HMAC (NOEX-SYM, NOEXUASY, and so
| forth). This is the default if no export control for AES or HMAC keywords are used.
| DES key-token: Use this keyword to set CV bit 17 = B'0' (NO-XPORT) and CV bit 27 = B'1'
| (NOT31XPT). This is the default if no export control for DES keywords are used.
| Export control for AES or HMAC (one or more, optional). Not valid for DES.
| NOEX-SYM Prohibits the key from being exported using a symmetric key.
| NOEXUASY Prohibits the key from being exported using an unauthenticated asymmetric key.
| NOEXAASY Prohibits the key form being exported using an authenticated asymmetric key (for example,
| an RSA key in a trusted block token).
| NOEX-AES (Rel. Specifies to prohibit export using AES key.
| 4.2 or later)
| NOEX-DES (Rel. Specifies to prohibit export using DES key.
| 4.2 or later)
| NOEX-RSA (Rel. Specifies to prohibit export using RSA key.
| 4.2 or later)
| Export control for DES (one, optional). All keywords in this group are default if no keyword provided. Only valid
| for DES. Release 4.2 or later.
| CCAXPORT For DES internal tokens, set CV bit 17 = B'0' to prohibit any export of the key.
| NOT31XPT For DES internal tokens, set CV bit 57 = B'1' to prohibit TR-31 export of the key.
| KEK identifier rule (only valid if KEK_identifier_length variable is greater than 0; required if KEK identifier is a key
| label and the key in key storage is an RSA KEK, otherwise optional if KEK passed). Release 4.2 or later.
| IKEK-AES The inbound key-encrypting key for the external key is an AES KEK. Not valid for DES. This
| is the default for AES and HMAC.
| IKEK-DES The inbound key-encrypting key for the external key is a DES KEK. Valid only for DES. This
| is the default for DES.
| IKEK-PKA The inbound key-encrypting key for the external key is an asymmetric key. Required if an
| RSA transport key is used (that is, the key being changed is wrapped using the PKOAEP2
| method). Not valid for DES.
|
of data in the key_identifier variable on output.
key_identifier
| The key_identifier parameter is a pointer to a string variable containing an internal CCA variable-length
| symmetric key-token, or a label of such a key in key storage. Beginning with Release 4.2, this
| parameter can also point to a key token or a key label of an external CCA variable-length symmetric
| key-token, or a key token or key label of an external or internal fixed-length DES key token.
KEK_key_identifier_length
| The KEK_key_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the KEK_key_identifier variable. In releases before Release 4.2, the value must be
| zero. In Release 4.2 or later, set the value to zero if the input key is in an internal key-token, and set
| the value to greater than or equal to 64 if the input key is in an external key-token. If the variable
| contains a key label, set the value to 64.

KEK_key_identifier
| The KEK_key_identifier parameter is a pointer to a string variable containing the operational AES or
| DES EXPORTER or IMPORTER key-encrypting key, or the RSA private key needed to decipher the
| external input symmetric key-token, or the key label of such a key in AES, DES, or PKA key-storage.
opt_parameter1_length
| The opt_parameter1_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the opt_parameter1 variable. The value must be 0.
opt_parameter1
| The opt_parameter1 parameter is a pointer to a string variable that is reserved for future use.
opt_parameter2_length
| The opt_parameter2_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the opt_parameter2 variable. The value must be 0.
opt_parameter2
| The opt_parameter2 parameter is a pointer to a string variable that is reserved for future use.
Required commands
The Restrict_Key_Attribute verb requires the following commands to be enabled in the active role:

AES (Rel. 4.2 or later) X'00E9' Lower Export Authority2
HMAC
DES (Rel. 4.2 or later) X'0154' Restrict Key Attribute - Permit Setting the TR-31 Export Bit

Symmetric_Key_Export (CSNDSYX)
| Use the Symmetric_Key_Export verb to export an operational key that is contained in an internal
| symmetric key-token. The key being exported can be selectively returned either formatted and encrypted
| under an RSA public-key, or encrypted under an AES EXPORTER key-encrypting key, depending on the
| key-formatting method specified. The usage attributes of the EXPORTER key must allow EXPORT.
| For an RSA-enciphered output key, the key is returned as an opaque data buffer or in an external
| variable-length symmetric key-token. If the key is returned as an opaque data buffer, the
| Symmetric_Key_Import verb can be used along with the associated RSA private-key to import the key
| back into an operational symmetric key-token. If the key is returned in an external variable-length
| symmetric key-token, the Symmetric_Key_Import2 verb can be used along with the associated RSA
| private-key to import the key.
| For an AES-enciphered output key, the key is returned in an external variable-length symmetric key-token.
| The Symmetric_Key_Import2 verb can be used along with its associated AES IMPORTER key-encrypting
| key to import the key. The usage attributes of the IMPORTER key must allow IMPORT.
| The source key must be a complete symmetric key contained in a fixed-length or variable-length
| key-token, encrypted under an AES or DES master key. Fixed length keys are limited to a key type of
| DATA. Variable length keys have no key type limitations. Table 46 shows the source key tokens that are
| valid:
| Table 46. Symmetric_Key_Export source key tokens
| Internal fixed-length symmetric key-token key Internal variable-length symmetric key-token
| Algorithm type key type
| AES DATA (Release 3.30 or later) CIPHER, EXPORTER, or IMPORTER (Release
| 4.2 or later)
| DES DATA
| HMAC MAC (Release 4.1 or later)
|
| Different methods are supported for formatting the output key. Not all of these methods are available for
| each supported source key-token. The AESKW key-formatting method uses an AES EXPORTER
| key-encrypting key to wrap the output key before returning it in an external variable-length symmetric
| key-token. The other key formatting methods each use a different scheme to format the key before it is
| enciphered using an asymmetric RSA public-key. The formatted and enciphered key is returned as an
| opaque data buffer, and is not in a key token.
| Table 47 on page 334 shows which key-formatting methods can be used for each type of input key-token,
| along with a description of the enciphered key returned:

| Table 47. Symmetric_Key_Export key formatting methods by source key-token
| Key-formatting method keyword
| Source AESKW PKOAEP2
| key-token (Rel. 4.2 or later) PKCS-1.2 PKCSOAEP (Rel. 4.1 or later) ZERO-PAD
| AES Not supported. The output key is The output key is Not supported. The output key is
| operational returned as an returned as an returned as an
| fixed-length opaque data buffer opaque data buffer opaque data buffer
| DATA key after being after being after the key is
| type (Rel. formatted using formatted using right-aligned,
| 3.30 or later) the the RSAES-OAEP padded on the left
| RSAES-PKCS1- encryption / to the necessary
| v1_5 encryption / decryption scheme block length with
| decryption scheme of the RSA PKCS bits valued to zero,
| of the RSA PKCS #1 v2.0 standard and enciphered
| #1 v2.0 standard and enciphered using the RSA
| and enciphered using the RSA public-key
| using the RSA public-key provided as a
| public-key provided as a transport key.
| provided as a transport key.
| transport key.
| AES The output key is Not supported. Not supported. The output key is Not supported.
| operational returned in an returned in an
| variable- external external
| length (Rel. variable-length variable-length
| 4.1 or later) AES key-token AES key-token
| after being after being
| enciphered using formatted using
| the AES the RSAES-OAEP
| EXPORTER key encryption /
| provided as the decryption scheme
| transport key. of the RSA PKCS
| #1 v2.1 standard
| and enciphered
| using the RSA
| public-key
| provided as a
| transport key.
| Release 4.2 or
| later.
| DES Not supported. Same as Same as Not supported. Same as
| operational fixed-length AES fixed-length AES fixed-length AES
| fixed-length source key-token. source key-token. source key-token.
| DATA key
| type
| HMAC The output key is Not supported. Not supported. Same as Not supported.
| operational returned in an variable-length
| variable- external AES source
| length (Rel. variable-length key-token, except
| 4.1 or later) HMAC key-token that the output key
| after being is returned in an
| enciphered using external
| the AES variable-length
| EXPORTER key HMAC key-token.
| provided as the
| transport key.

| Table 47. Symmetric_Key_Export key formatting methods by source key-token (continued)
| Notes:
| 1. AESKW is not supported in releases before release 4.2, and PKOAEP2 is not supported in releases before 4.1.
| 2. For keywords PKCS-1.2, PKCSOAEP, and PKOAEP2, see PKCS #1 hash formats on page 694.
| 3. The RSA PKCS #1 v2.0 standard for the RSAES-PKCS1-v1_5 encryption/decryption scheme is formerly known
| as block-type 02 format.
| 4. PKCSOAEP and PKOAEP2 are the only key formatting methods that use a hash method. PKCSOAEP and
| PKOAEP2 can specify either SHA-1 or SHA-256. PKOAEP2 can also specify SHA-384 or SHA-512.
|

| v The rule array:
| 1. For Release 3.30 or later, an optional algorithm keyword. DES is the default. This keyword identifies
| which symmetric algorithm can be used by the source key being exported, and which key-storage
| file contains the key when it is identified by a key label. Note that an AES key must be in a
| fixed-length key-token in releases before Release 4.2.
| 2. A required key-formatting method keyword. This keyword selects which method to use to format the
| recovered clear symmetric key. See Table 47 on page 334 for a summary of which key formatting
| methods are available for a given source key-token.
| 3. A hash method keyword. This keyword is optional, required, or not allowed, depending on the
| key-formatting method specified. For PKCSOAEP, this is an optional keyword of SHA-1 or SHA-256
| (SHA-1 is the default). For PKOAEP2, this is a required keyword. Specify SHA-1, SHA-256,
| SHA-384, or SHA-512. The remaining key formatting methods do not use a hash method.
| For hash-formatting method PKOAEP2, the RSA key used must have a modulus bit length greater
| than or equal to the total PKOAEP2 message bit length, calculated as shown:
|| Hash method PKOAEP2 message bit length
| SHA-1 Bit size of symmetric key + 608 (minimum 688; maximum 2656)
|
| v An identifier for the source key-token. This must identify an internal symmetric key-token that contains
| the operational key to be exported. See Table 46 on page 333. If the identifier is a key label, the key
| must be in AES key-storage for an AES or HMAC key, and the key must be in DES key-storage for a
| DES key.
| v An identifier for the transport key token. The key token identified must contain an RSA public-key or an
| AES EXPORTER key-encrypting key, depending on the key-formatting method specified. See Table 47
| on page 334. A public-key can be in an external or internal PKA key-token. An EXPORTER key must be
| in an internal variable-length AES key-token. The EXPORTER key must have usage attributes that allow
| EXPORT.
| v A buffer large enough to receive the enciphered key.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The RSA public-key modulus size (key length) is limited by the Function Control Vector (FCV) to
accommodate potential government export and import regulations.
v AES is not supported in releases before Release 3.30.
v Rule-array keywords HMAC and PKOAEP2, and variable-length symmetric key tokens are not
supported in releases before Release 4.1
| v Retained keys are not supported.
| v Rule array keywords SHA-1 and SHA-256 are not supported with key-formatting method keyword
| PKCSOAEP in releases before Release 4.2.
| v Rule-array keyword AESKW is not supported in releases before Release 4.2.
| v The Export AES Key (AESKW) command (offset X'0327') and the Disallow Weak Key Wrap command
| (offset X'0328') are not supported in releases before Release 4.2
Format
CSNDSYX
| transport_key_identifier_length Input Integer 3500
| transport_key_identifier Input String transport_key_identifier_length bytes
| enciphered_key_length In/Output Integer 3500
| enciphered_key Output String enciphered_key_length bytes
Parameters

rule_array_count
rule_array
Keyword Meaning
| Algorithm (one, optional). Release 3.30 or later. See Table 46 on page 333.
| AES Specifies to export an AES key.
| DES Specifies to export a DES key.
| HMAC (Rel. 4.1 Specifies to export an HMAC key.
| or later)
| Key-formatting method (one required). See Table 47 on page 334.
| AESKW (Rel. 4.2 Specifies to return the key formatted using the AESKW method. The AESKW payload that
| or later) contains the key is encrypted by the AES EXPORTER key-encrypting key provided as the
| transport key, and returned in an external variable-length symmetric key-token. Valid only
| with the AES or HMAC algorithms.
| PKCS-1.2 Specifies to return the key formatted using the RSAES-PKCS1-v1_5 encryption/decryption
| scheme defined in the RSA PKCS #1 v2.0 standard. The formatted key is encrypted by the
| RSA public-key provided as the transport key and returned as an opaque data buffer, not in
| a key token. Valid only with the AES or DES algorithms, and only for a DATA key in a
| fixed-length symmetric key-token.
| PKCSOAEP Specifies to return the key formatted using the RSAES-OAEP encryption/decryption scheme
| defined in the RSA PKCS #1 v2.0 standard. The formatted key is encrypted by the RSA
| public-key provided as the transport key and returned as an opaque data buffer, not in a key
| token. Valid only with the AES or DES algorithms, and only for a DATA key in a fixed-length
| symmetric key-token. A hash method keyword is optional when this keyword is specified.
| PKOAEP2 (Rel. Specifies to return the key formatted using the RSAES-OAEP encryption/decryption scheme
| 4.1 or later) defined in the RSA PKCS #1 v2.1 standard. The PKOAEP2 payload containing the formatted
| key is encrypted by the RSA public-key provided as the transport key and returned in an
| external variable-length symmetric key-token. Valid only with the AES or HMAC algorithms.
| A hash method keyword is required when this keyword is specified.
| ZERO-PAD Specifies to return the key formatted by right-aligning the key and padding it on the left with
| bits valued to zero up to the modulus size of the RSA key. The formatted key is encrypted
| by the RSA public-key provided as the transport key and returned as an opaque data buffer,
| not in a key token. Valid only with the AES or DES algorithms, and only for a DATA key in a
| fixed-length symmetric key-token.
| Hash method (one optional for PKCSOAEP; one required for PKOAEP2; not allowed for any other
| key-formatting method).
| SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash. Only valid
| with key-formatting method PKCSOAEP or PKOAEP2. This is the default for key-formatting
| method PKCSOAEP.
| with key-formatting method PKCSOAEP or PKOAEP2.
| with key-formatting method PKOAEP2.
| with key-formatting method PKOAEP2.

of bytes of data in the source_key_identifier variable.
| The source_key_identifier parameter is a pointer to a string variable containing the operational
| symmetric key-token of the key to be exported, or the key label of such a key in AES or DES
| key-storage. See Table 46 on page 333.
| transport_key_identifier_length
| The transport_key_identifier_length parameter is a pointer to an integer variable containing the number
| of bytes of data in the transport_key_identifier variable. The maximum length is 3500 bytes.
| transport_key_identifier
| The transport_key_identifier parameter is a pointer to a string variable containing an RSA public-key in
| an external or internal PKA key-token or, beginning with Release 4.2, an AES EXPORTER
| key-encrypting key in an internal variable-length symmetric key-token, or the key label of such a key in
| PKA or AES key-storage. The key-formatting method specified determines whether a public-key or a
| key-encrypting key is required as the transport key. See Table 47 on page 334. An EXPORTER key
| must have usage attributes that allow EXPORT.
| enciphered_key_length
| The enciphered_key_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the enciphered_key variable. On output, the variable is updated with the actual length
| of the enciphered_key variable. The maximum length is 3500 bytes.
| enciphered_key
| The enciphered_key parameter is a pointer to a string variable containing the key after it has been
| formatted and enciphered by the transport key. The enciphered key is returned either as an opaque
| data buffer or in an external variable-length symmetric key-token. For key-formatting method
| PKOAEP2, the key token has no key verification pattern.
Required commands
The Symmetric_Key_Export verb requires the following commands to be enabled in the active role based
on the key-formatting method and the algorithm:
Key-formatting
method Algorithm Offset Command
| AESKW (Rel. AES X'0327' Export AES Key (AESKW)
4.2 or later)
PKCSOAEP or AES X'0130' Export AES Key (PKCSOAEP or PKCS-1.2)
PKCS-1.2
DES X'0105' Symmetric Key Export PKCS-1.2/OAEP
ZERO-PAD AES X'0131' Export AES Key (ZERO-PAD)
DES X'023E' ZERO-PAD Symmetric Key Export
PKOAEP2 HMAC X'00F5' Export HMAC key (PKOAEP2)
The following access control points are added beginning with Release 4.2:
| v To disallow the wrapping of a key with a weaker key-encrypting key, enable the Disallow Weak Key
| Wrap command (offset X'0328') in the active role. This command affects multiple verbs. See Table 169
| on page 715.
v To receive a warning when wrapping a key with a weaker key-encrypting key, enable the Warn when
Wrapping Weak Keys command (offset X'032C') in the active role. The Disallow Weak Key Wrap
command overrides this command.

Symmetric_Key_Generate (CSNDSYG)
Use the Symmetric_Key_Generate verb to generate a random AES (Release 3.30 or later) or DES data
key and return that key in two enciphered forms. The random key value is formatted and enciphered under
an RSA public-key for distribution to another node which has the corresponding private key. The key value
| is also enciphered under a symmetric key, and returned in a fixed-length AES or DES key-token for local
| use. For generation of AES keys, this symmetric key is the AES master-key. For generation of DES keys,
this symmetric key can be either the DES master-key or a fixed-length DES key-encrypting key. An
optional keyword specifies the algorithm for the key being imported. The default is DES.
Rule array keywords define the length of the generated key, how the RSA-enciphered key will be
enciphered, and the type of symmetric key used to encipher generated DES keys. Beginning with Release
4.1, they also specify the key-wrapping method and translation control.
There are six classes of rule-array keywords:

1. Optional algorithm keywords to select which type of key to generate (Release 3.30 or later).
2. Required keywords for specifying the key formatting method used when the key is encrypted with the
RSA public key. Three of the methods apply to DATA keys and are used when generating either AES
or DES keys. The other two methods apply only to key-encrypting keys and are used only when
generating DES keys.
3. Optional key-length keywords to control the length of the generated key.
4. When generating DATA keys, optional keywords for specifying the method in which the
symmetric-encrypted copy of the generated key is enciphered.
5. Optional keywords for specifying the method used to wrap the key (Release 4.1 or later).
6. An optional keyword used together with the WRAP-ENH key-wrapping method to restrict the wrapping
of the key to enhanced only (Release 4.1 or later).
DATA keys can be generated for both AES and DES. DES DATA keys can be single or double in length,
and are generated with the default DATA control vector as defined in Table 162 on page 657. AES DATA
keys can be 128, 192, or 256 bits in length. One copy of the key is returned in the variable identified by
the local_enciphered_key parameter.
| For AES keys, this copy is enciphered under the AES master key. For DES keys, this copy is enciphered
| under either the DES master key or under an IMPORTER or EXPORTER key-encrypting key. Also for DES
| keys, if you do not specify a null key-token, you must supply either the single-length or double-length
| default DATA control vector in a key token.
| The second copy of the key is formatted using the method specified and enciphered with an RSA public
| key. The enciphered formatted key is returned in the variable identified by the
| rsa_enciphered_key_identifier parameter. On input, you must specify a null key-token. Use one of these
| keywords to choose how the generated key is formatted prior to RSA encryption:
PKCSOAEP
| Formats the key as defined in the RSA PKCS #1 v2.0 standard for the RSAES-OAEP
| encryption/decryption scheme. See PKCS #1 hash formats on page 694.
PKCS-1.2
| Formats the key as defined in the RSA PKCS #1 v2.0 standard for the RSAES-PKCS1-v1_5
| encryption/decryption scheme. See PKCS #1 hash formats on page 694.
ZERO-PAD
| The generated key value is padded on the left with zero bits up to the modulus size of the RSA key
before it is encrypted.

DES key-encrypting keys can be generated. Key-encrypting keys are not supported for AES. DES
key-encrypting keys can be either true double-length or effective single-length (SINGLE-R). They are
generated with details that are dependent on the keyword you use to control the key formatting
technique.
PKA92
With this keyword, the verb generates a DES key-encrypting key and returns two copies of the key.
You must specify a pair of complementary control vectors that conform to the rules for an OPEX case
as defined for the Key_Generate verb. The control vector for one key copy must be from the
EXPORTER class while the control vector for the other copy must be from the IMPORTER class.
The verb enciphers one key copy using the public key from the RSA_key_identifier parameter and
the key encipherment technique defined in PKA92 key format and encryption process on page 674.
The control vector for this key is taken from an internal or external fixed-length DES key-token that
must be present on input in the RSA_enciphered_key_identifier variable.
The control vector for the local key is taken from a DES key-token that must be present on input in
the local_enciphered_key_identifier variable or in the key token identified by the key label in that
variable.
Note: A node environment identifier (EID) value must have been established prior to use of the
PKA92 keyword. Use the Cryptographic_Facility_Control verb to set the EID.
NL-EPP-5
With this keyword, the verb generates a DES key-encrypting key and returns two copies of the key.
The verb enciphers one key copy using the key encipherment techniques defined by certain OEM
equipment See Encrypting a key-encrypting key in the NL-EPP-5 format on page 675. On input, the
RSA_enciphered_key_token variable must contain an internal fixed-length DES key-token that
contains a control vector for an IMPORTER key-encrypting key.
The control vector for the local key is taken from a DES key-token that must be present on input in
the local_enciphered_key_identifier parameter or in the key token identified by the key label in that
parameter.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The permissible key length of the RSA public key is limited by the value specified in the function control
vector for RSA encipherment of keys.
v The USECONFG, WRAP-ECB, WRAP-ENH, and ENH-ONLY keywords are not supported in releases
before Release 4.1.
| v Rule-array keywords SHA-1 and SHA-256 are not supported in releases before Release 4.2.

Format
CSNDSYG
| rule_array_count Input Integer 1, 2, 3, 4, 5, 6, or 7
key_encrypting_key_identifier Input String 64
RSA_public_key_identifier_length Input Integer 3500
RSA_public_key_identifier Input String RSA_public_key_identifier_length bytes
local_enciphered_key_identifier_length In/Output Integer 64
local_enciphered_key_identifier In/Output String local_enciphered_key_identifier_length bytes
RSA_enciphered_key_identifier_length In/Output Integer 3500
RSA_enciphered_key_identifier In/Output String RSA_enciphered_key_identifier_length bytes
Parameters
rule_array_count
| in the rule_array variable. The value must be 1, 2, 3, 4, 5, 6, or 7.
rule_array

Keyword Meaning
AES Specifies to generate an AES key.
DES Specifies to generate a DES key. This is the default.
Key-formatting method (one required)
| PKCSOAEP Specifies that the AES or DES DATA key is formatted as defined in the RSA PKCS #1 v2.0 standard for
| the RSAES-OAEP encryption/decryption scheme. See PKCS #1 hash formats on page 694.
| PKCS-1.2 Specifies that the AES or DES DATA key is formatted as defined in the RSA PKCS #1 v2.0 standard for
| the RSAES-PKCS1-v1_5 encryption/decryption scheme. This was formerly known as the block-type 02
| ZERO-PAD Specifies to pad the key with binary zero bits to the left, up to the modulus size of the RSA key before
| enciphering it. This method applies to AES and DES DATA keys.
PKA92 Specifies to use the PKA92 method of encipherment for DES key-encrypting keys. This method is not
valid with AES keys.
NL-EPP-5 Specifies to use the NL-EPP-5 method of encipherment for DES key-encrypting keys. This method is
not valid with AES keys.
Key length (one, optional use with PKA92 or NL-EPP-5)
SINGLE-R For key-encrypting keys, this specifies that the left half and right half of the generated key will have
identical values. This makes the key operate identically to a single-length key with that same value.
Without this keyword, the left and right halves of the key-encrypting key will each be generated
randomly and independently.
Key length (one, optional use with PKCSOAEP, PKCS-1.2, or ZERO-PAD)
SINGLE, KEYLN8 Specifies to generate a key 8 bytes in length. Valid only for DES keys. This is the default for DES keys.
DOUBLE Specifies to generate a key that is 16 bytes in length. Valid only for DES keys.
KEYLN16 Specifies to generate a key that is 16 bytes in length. Valid for AES and DES keys. This is the default
for AES keys.
KEYLN24 Specifies to generate a key that is 24 bytes in length (Release 3.30 or later). Valid only for AES keys.
KEYLN32 Specifies to generate a key that is 32 bytes in length (Release 3.30 or later). Valid only for AES keys.
Encipherment method for the local enciphered copy of the key (one, optional for use with PKCSOAEP, PKCS-1.2, and ZERO-PAD)
OP Specifies to encipher the key with the master key. AES keys are enciphered with the AES master key,
while DES keys are enciphered with the DES master key.
| IM Specifies to encipher the key with the operational IMPORT-capable IMPORTER key-encrypting key
| identified by the key_encrypting_key_identifier parameter. Valid only for DES keys.
| EX Specifies to encipher the key with the operational EXPORT-capable EXPORTER key-encrypting key
| identified by the key_encrypting_key_identifier parameter. Valid only for DES keys.
| Hash method (when PKCSOAEP is specified, one optional).
| SHA-1 Specifies to use the SHA-1 method to calculate the OAEP message hash. This is the default.
| SHA-256 Specifies to use the SHA-256 method to calculate the OAEP message hash.
USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. This keyword
is ignored for AES keys. This is the default.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for AES keys.
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the default
wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary zeros. Release 4.1 or
later.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it has been
wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the control vector to B'1'.
key_encrypting_key_identifier
| The key_encrypting_key_identifier parameter is a pointer to a string variable containing the operational
| fixed-length DES key token or the key label of such a key in DES key-storage, with the key-encrypting

| key used to encipher the local enciphered key for DES-based key distribution. If IM or EX is not
| specified in the rule array, point to a null DES key-token.
RSA_public_key_identifier_length
The RSA_public_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the RSA_public_key_identifier variable. The maximum length is 3500 bytes.
RSA_public_key_identifier
| The RSA_public_key_identifier parameter is a pointer to a string variable containing an external or
| internal PKA96 RSA key-token with the RSA public-key of the remote node that imports the exported
| key.
local_enciphered_key_identifier_length
The local_enciphered_key_identifier_length parameter is a pointer to an integer variable containing the
| number of bytes of data in the local_enciphered_key_identifier variable. This value must be 64.
local_enciphered_key_identifier
The local_enciphered_key_identifier parameter is a pointer to a string variable containing either a key
label or a fixed-length AES or DES key-token. The control vector for the local key is taken from the
identified key token. On output, the generated key is inserted into the identified key token.
On input, you must specify a token type consistent with your choice of local-key encryption. If you
specify IM or EX, you must specify an external fixed-length DES key-token. Otherwise, specify an
internal fixed-length AES or DES key-token or a null fixed-length key-token.
| When PKCSOAEP, PKCS-1.2, or ZERO-PAD is specified, a null key-token can be specified. In this
| case, a default AES or DES DATA key is returned. For an internal key (OP), a default DATA
| control-vector is returned in the key token. For an external key (IM or EX), the control vector is set to
| binary zero.
| If you specify PKA92 or NL-EPP-5, on input specify a fixed-length DES key-token that contains the
| control vector to be used for this parameter's output, or a key label of such a key in DES key-storage.
RSA_enciphered_key_identifier_length
The RSA_enciphered_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the RSA_enciphered_key_identifier variable. On output, the variable is
updated with the actual length of the RSA_enciphered_key_identifier variable. The maximum length is
3500 bytes.
RSA_enciphered_key_identifier
| The RSA_enciphered_key_identifier parameter is a pointer to a string variable containing the
| generated RSA-enciphered key returned by the verb in a PKA key-token. If you specify PKCSOAEP,
| PKCS-1.2, or ZERO-PAD, on input specify a null PKA key-token or a key label of such a key in PKA
| key-storage. If you specify PKA92 or NL-EPP-5, on input specify a fixed-length DES key-token that
| contains the control vector to be used for this parameter's output, or a key label of such a key in DES
| key-storage.
Required commands
The Symmetric_Key_Generate verb requires the following commands to be enabled in the active role
based on the key-formatting method and possibly the algorithm:

Key-formatting
method Algorithm Offset Command
PKCSOAEP or AES X'012C' Generate AES DATA Key (PKCSOAEP or PKCS-1.2)
PKCS-1.2
DES X'023F' Symmetric Key Generate PKCS-1.2/OAEP
ZERO-PAD AES X'012D' Generate AES DATA Key (ZERO-PAD)
DES X'023C' ZERO-PAD Symmetric Key Generate
PKA92 DES X'010D' PKA92 Symmetric Key Generate
NL-EPP-5 DES X'010E' NL-EPP-5 Symmetric Key Generate
| In addition, use of the WRAP-ECB or WRAP-ENH key-wrapping method keywords requires the Allow
| Configuration Override with Keyword in SYG (offset X'013E') to be enabled in Release 4.1 or later.

Symmetric_Key_Import (CSNDSYI)
| Use the Symmetric_Key_Import verb to import an AES key (Release 3.30 or later) or DES data key that
| has been formatted and enciphered with an asymmetric public key into an opaque data buffer. The verb
| recovers the RSA-enciphered symmetric key using an asymmetric private key, and returns the deciphered
| key in a CCA internal fixed-length symmetric key-token enciphered under a symmetric master-key. The
| returned key-token always contains an encrypted copy of the imported key, with an AES key wrapped by
| the AES master key and a DES key wrapped by the DES master key.
Choose one of the following key-formatting methods for the verb to use, depending on how the
RSA-enciphered key is formatted:
v PKCSOAEP, PKCS-1.2, or ZERO-PAD to recover an AES or a DES default DATA key
v PKA92 to recover any DES keys of type DATA, MAC, MACVER, KEYGENKY, EXPORTER, OKEYXLAT,
PINGEN, PINVER, IPINENC, or OPINENC
Optionally choose an algorithm keyword for which type of key to import (Release 3.30 or later).
AES key lengths of 16, 24, and 32 bytes are supported (Release 3.30 or later). DES key lengths of 8
(single-length DES) and 16 (double-length Triple-DES) are supported.
| Note: Enciphered AES keys are always imported into enciphered key tokens. The verb never imports an
| enciphered AES key into a clear AES key token.

v The rule array:
1. An optional algorithm keyword (Release 3.30 or later). This keyword defines which symmetric key to
import. Choose either AES to import an AES key, or DES to import a DES key. DES is the default
when no algorithm keyword is specified.
2. A required RSA key-encipherment method. This keyword identifies the method used to format the
clear symmetric key before it was encrypted by a public key. This is the key identified by the
RSA_enciphered_key parameter. The verb uses this method to validate the recovered key. There is
no default.
For importing AES DATA keys or default DES single-length or double-length DATA keys, use one of
the following key-encipherment method keywords:
PKCSOAEP
| After recovering the formatted data contained in the RSA_enciphered_key variable, the verb
| checks the format for conformance to the encryption/decryption scheme defined in the RSA
| PKCS #1 v2.0 standard for RSAES-OAEP. See PKCS #1 hash formats on page 694.
PKCS-1.2
| checks the format for conformance to the encryption/decryption scheme defined in the RSA
| PKCS #1 standard for RSAES-PKCS1-v1_5 format. This was formerly known as the
| block-type 02 method. See PKCS #1 hash formats on page 694.
ZERO-PAD
| checks the format to verify that all the bits to the left of the key (the high-order bits) up to
| the modulus size of the RSA key have a value of zero.
For importing DES keys of type DATA, MAC, MACVER, KEYGENKY, EXPORTER, OKEYXLAT,
PINGEN, PINVER, IPINENC, or OPINENC with a default or non-default control vector, use the
following key-formatting method:
PKA92
DATA, MAC, MACVER, KEYGENKY, EXPORTER, OKEYXLAT, PINGEN, PINVER,
IPINENC, or OPINENC DES formatted keys and their control vectors are recovered using

the method employed in the TSS PKA92 implementation. See PKA92 key format and
encryption process on page 674. This method is not supported for AES keys.
Before using the PKA92 method, a node environment identifier (EID) value must be
established. Under the PKA92 scheme, the EID values at the exporting and importing nodes
must be different. Use the Cryptographic_Facility_Control verb to set the EID, and the
Cryptographic_Facility_Query verb to query the EID.
| Note: This implementation imports DES keys that are formatted according to the PKA92
| scheme, but does not provide a means for enciphering these key types other than
| DATA in the PKA92 format. This extension to CCA is considered nonstandard, and
| might not be present in other CCA implementations.
3. An optional keyword to select the method used to wrap the key (Release 4.1 or later).
4. An optional keyword, used together with the WRAP-ENH key-wrapping method, to restrict the
wrapping of the key to enhanced only (Release 4.1 or later).
| v The RSA-enciphered key, containing the formatted and enciphered symmetric AES or DES key to be
| imported.
v The RSA private-key to use to recover the AES or DES key to be imported, either as an internal PKA
key-token or as a key label that identifies an internal key-token in PKA key-storage.
v A target key identifier of either a null key-token, an internal fixed-length AES or DES key-token, or a key
label of a null key token or internal fixed-length AES or DES key-token. This key token is updated with
the imported key token.
| 1. Null key-token. The verb creates an internal fixed-length symmetric key-token from a null
key-token.
For AES keys, the control vector is set to binary zeros.
For RSA-enciphered DES keys enciphered under a key-formatting method of PKCSOAEP,
PKCS-1.2, or ZERO-PAD, the control vector in the null key-token is updated with the contents of
a default single-length or double-length DATA key-token, based on the length of the recovered
key. See Table 162 on page 657.
For RSA-enciphered DES keys enciphered under a key-formatting method of PKA92, the control
vector in the null key-token is updated with the contents of the control vector recovered from the
RSA_enciphered_key variable.
2. Internal key-token. Provide an existing internal fixed-length AES or DES key-token to be updated
with the enciphered value of the clear key.
| Fixed-length AES keys have a null or no control vector, hence no key-usage control information.
| All fixed-length AES keys are DATA keys. The length of the key found in the decrypted
| information must match the length of the clear-key bit length field of the key token.
For RSA-enciphered DES keys enciphered under a key-formatting method of PKCSOAEP,
PKCS-1.2, or ZERO-PAD, the control vector of the internal key-token must match the default
value for a single-length or double-length DATA key corresponding to the key length found in the
decrypted information. See Table 162 on page 657.
For RSA-enciphered DES keys enciphered under a key-formatting method of PKA92, the control
vector of the internal key-token must match the contents of the control vector recovered from the
RSA_enciphered_key variable.
3. Key label. Use a key label to identify either a null key-token or an internal key-token in AES or DES
key-storage for the verb to retrieve and update. For AES, identify by name a key token in AES
key-storage. For DES, identify a null or internal key-token in DES key-storage.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The RSA private-key modulus size (key length) is limited by the Function Control Vector (FCV) to
accommodate potential government export and import regulations.
v The usage limits in a PKA key-token for a private key can prevent the use of specific private keys in this
verb. See the description of usage limits for a private key in PKA_Key_Token_Build (CSNDPKB) on
page 95.
v Under PKA92, the EID of the node that exported a key cannot be the same as the EID of a node that
imports that key.
v Other IBM implementations of this verb might not support key types other than a default DATA control
vector, or the use of a key label as the variable pointed to by the target_key_identifier parameter.
v The USECONFG, WRAP-ECB, WRAP-ENH, and ENH-ONLY keywords are not supported in releases
before Release 4.1.
| v Rule-array keywords SHA-1 and SHA-256 are not supported in releases before Release 4.2.
Format
CSNDSYI
RSA_enciphered_key_length Input Integer 3500
RSA_enciphered_key Input String RSA_enciphered_key_length bytes
RSA_private_key_identifier_length Input Integer 3500
RSA_private_key_identifier Input String RSA_private_key_identifier_length bytes
target_key_identifier_length In/Output Integer 64
target_key_identifier In/Output String target_key_identifier_length bytes
Parameters

rule_array_count
rule_array
characters. The rule_array keywords are shown here:
Keyword Meaning
AES Specifies to import an AES key.
DES Specifies to import a DES key. This is the default.
Key-formatting method (one required)
| PKCSOAEP Specifies that the RSA-enciphered key is formatted as defined in the RSA PKCS #1 v2.0 standard
| for the RSAES-OAEP encryption/decryption scheme. See PKCS #1 hash formats on page 694.
| PKCS-1.2 Specifies that the RSA-enciphered key is formatted as defined in the RSA PKCS #1 v2.0 standard
| for the RSAES-PKCS1-v1_5 encryption/decryption scheme. See PKCS #1 hash formats on page
| 694.
| ZERO-PAD Specifies that the RSA-enciphered key is formatted by padding the key on the left with binary
| zeros to the modulus length of the RSA key before the key is encrypted.
PKA92 Specifies that the RSA-enciphered key is formatted with the PKA92 method. See PKA92 key
format and encryption process on page 674. Only used for DES keys of type DATA, MAC,
MACVER, KEYGENKY, EXPORTER, OKEYXLAT, PINGEN, PINVER, IPINENC, and OPINENC.
Note: This method is not supported for AES keys.
| Hash method (when PKCSOAEP is specified, one optional).
| SHA-1 Specifies to use the SHA-1 method to calculate the OAEP message hash. This is the default.
| SHA-256 Specifies to use the SHA-256 method to calculate the OAEP message hash.
USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. This
keyword is ignored for AES keys. This is the default.
WRAP-ECB Specifies to wrap the key using the legacy wrapping method. This keyword is ignored for AES
keys.
Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when
the default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method once it has
been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the control vector
to B'1'.
RSA_enciphered_key_length
The RSA_enciphered_key_length parameter is a pointer to an integer variable containing the number
of bytes of data in the RSA_enciphered_key variable. The maximum length is 3500 bytes.
RSA_enciphered_key
The RSA_enciphered_key parameter is a pointer to a string variable containing the symmetric key
being imported.
RSA_private_key_identifier_length
The RSA_private_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the RSA_private_key_identifier variable. The maximum length is 3500
bytes.

RSA_private_key_identifier
The RSA_private_key_identifier parameter is a pointer to a string variable containing a key label or a
PKA96 RSA key-token with the internal RSA private-key to be used to decipher the RSA-enciphered
key to be imported.
The target_key_identifier_length parameter is a pointer to an integer variable containing the number of
bytes of data in the target_key_identifier variable. On output, the value is updated with the actual
length of the target_key_identifier variable returned by the verb. The maximum length is 3500 bytes.
The target_key_identifier parameter is a pointer to a string variable containing either a null key-token,
an internal fixed-length AES or DES key-token, or a key label of a null key-token or internal
fixed-length AES or DES key-token. On input, this parameter identifies the symmetric key-token to be
updated. On output, this parameter identifies the key token that contains the imported key.
Required commands
The Symmetric_Key_Import verb requires the following commands to be enabled in the active role based
on the key-formatting method, the algorithm, and possibly the key type:
Key-formatting method Algorithm Offset Command

PKCSOAEP or PKCS-1.2 AES X'012E' Import AES Key (PKCSOAEP or PKCS-1.2)
DES X'0106' Symmetric Key Import PKCS-1.2/OAEP
ZERO-PAD AES X'012F' Import AES Key (ZERO-PAD)
DES X'023D' ZERO-PAD Symmetric Key Import
PKA92 and DATA, MAC, DES X'0235' PKA92 Symmetric Key Import
MACVER, KEYGENKY,
EXPORTER, or OKEYXLAT
key
NL-EPP-5 and PINGEN, DES X'0236' PKA92 Symmetric Key Import with PIN Keys
PINVER, IPINENC, or
OPINENC key
WRAP-ECB or WRAP-ENH DES X'0144' Allow Configuration Override with Keyword in SYI
match keyword (Rel. 4.1 or
later)

Symmetric_Key_Import2 (CSNDSYI2)
| Use the Symmetric_Key_Import2 verb to import a symmetric key that has been exported by the
| Symmetric_Key_Export verb into an external variable-length symmetric key-token. The verb imports the
| key into an internal variable-length symmetric key-token. Before Release 4.2, the input key must be an
| HMAC key that has been previously formatted using key-formatting method PKOAEP2. Beginning with
| Release 4.2, AES keys are supported, along with support for the AES algorithm. With this support, the
| input key can also be an HMAC key that has been previously formatted using key-formatting method
| AESKW, provided that the operational AES key-encrypting key used to encipher the key is provided.
| Likewise, an AES key can either be in an external AES variable-length symmetric key-token enciphered
| under an AES key-encrypting key (AESKW), or an RSA public-key (PKOAEP2).
Restrictions
| AIX X
| IBM i X
| Windows
|
| v The following rule-array keywords are not supported in releases before Release 4.2:
| Token algorithm AES
| Key-formatting method AESKW
Format
CSNDSYI2
| enciphered_key_length Input Integer 3500
| enciphered_key Input String enciphered_key_length bytes
| transport_key_identifier_length Input Integer 3500
| transport_key_identifier Input String transport_key_identifier_length bytes
| key_name_length Input Integer 0 or 64
| key_name Input String key_name_length bytes
| target_key_identifier_length In/Output Integer See Appendix B.
target_key_identifier Output String target_key_identifier_length bytes

Parameters
rule_array_count
rule_array
characters.
|| Keyword Meaning
| AES (Rel. 4.2 or later) Specifies to import an external AES key.
| HMAC Specifies to import an external HMAC key.
| Key-formatting method (one required)
| AESKW (Rel. 4.2 or later) Specifies that the enciphered input key is wrapped with the AESKW formatting
| method.
| PKOAEP2 Specifies that the enciphered input key is wrapped according to the method
| found in the RSA PKCS #1 v2.1 standard for the RSAES-OAEP
| encryption/decryption scheme.
| Note: There is no need for a hash method keyword, because the hash method is encoded in the external
| key-token carrying the encoded/encrypted payload.
|
| enciphered_key_length
| The enciphered_key_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the enciphered_key variable.
| enciphered_key
| The enciphered_key parameter is a pointer to a string variable containing an external variable-length
| symmetric key-token. This parameter cannot identify a key label. Before Release 4.2, the input key
| must be an HMAC key with an RSA-enciphered payload. Beginning with Release 4.2, an AES and
| HMAC key can be in an AESKW-wrapped payload, and an AES key can be in an RSA-enciphered
| payload.
| transport_key_identifier_length
| The transport_key_identifier_length parameter is a pointer to an integer variable containing the number
| of bytes of data in the transport_key_identifier variable.
| transport_key_identifier
| The transport_key_identifier parameter is a pointer to a string variable containing the operational key
| that was used to encrypt the external input enciphered key. For key-formatting method AESKW, this is
| an AES IMPORTER key-encrypting key in a variable-length symmetric key-token that has key usage
| that allows the key to be used for IMPORT, or the label of such a key in AES key-storage. For
| key-formatting method PKOAEP2, this is an internal key with the RSA private-key to be used to
| decrypt the OAEP-formatted message in the enciphered_key variable, or the label of such a key in
| PKA key-storage.
| key_name_length
| The key_name_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the key_name variable on output. The value must be 0 or 64.
| key_name

| in the associated data structure of the imported variable-length symmetric key-token. If this variable
| contains data, it must be a valid key label. If this variable has a length of zero, any key name in the
| input key-token is placed in the output key-token.
| The target_key_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the target_key_identifier variable on output. The value must be large enough to
| receive the target key. On output, it is updated to the length of the returned target_key_identifier
| variable.
| The target_key_identifier parameter is a pointer to a string variable containing a null variable-length
| symmetric key-token, or a key label of such a key in AES key-storage. On input, this parameter
| identifies the key token to be updated. On output, this parameter identifies the key token containing
| the imported key.
| Required commands
| The Symmetric_Key_Import2 verb requires the following commands to be enabled in the active role:
|| Key-formatting method Token algorithm keyword Offset Command
| keyword
| AESKW (Rel. 4.2 or later) AES X'0329' Import AES Key (AESKW)
| HMAC
| PKOAEP2 AES (Rel. 4.2 or later) X'00FD' Import AES Key (PKOAEP2
| HMAC X'00F4' Import HMAC Key (PKOAEP2)
|
| The following access-control points are added beginning with Release 4.2:
| v To disallow the wrapping of a stronger key with a weaker key, the Disallow Weak Import command
| (offset X'032B') must be enabled in the active role (Release 4.2 or later). This command affects multiple
| verbs. See Table 169 on page 715.
| v To receive a warning against the wrapping of a stronger key with a weaker key, the Warn When
| Wrapping Weak Keys command (offset X'032C') must be enabled in the active role. The Disallow Weak
| Import command overrides this command.

Trusted_Block_Create (CSNDTBC)
Use the Trusted_Block_Create verb to create an external trusted block under dual control. A trusted block
is an extension of CCA PKA key tokens using new section identifiers.
Trusted blocks are an integral part of a remote key-loading process. They contain various items, some of
which are optional, and some of which can be present in different forms. Tokens are composed of
concatenated sections. For a detailed description of a trusted block, including its format and field values,
see Trusted blocks on page 600.
Creating an external trusted block: Create an active external trusted block in two steps:
1. Create an inactive external trusted block using the INACTIVE rule-array keyword. This step requires
the Create a Trusted Block in Inactive Form command (offset X'030F') to be enabled in the active role.
2. Complete the creation process by activating (promoting) an inactive external trusted block using the
ACTIVE rule-array keyword. This step requires the Activate an Inactive Trusted Block command (offset
X'0310') to be enabled in the active role. Changing an external trusted block from inactive to active
effectively approves the trusted block for further use
Note: Authorize each command in a different role to enforce a dual-control policy.
The creation of an external trusted block typically takes place in a highly secure environment. Use the
PKA_Key_Import verb to import an active external trusted block into the desired node. The imported
internal trusted block can then be used as input to the Remote_Key_Export verb to generate or export
DES keys.
Create an inactive external trusted block: To create an inactive external trusted block, use a
rule_array_count of 1 and a rule_array keyword of INACTIVE. Identify the input trusted block using the
input_block_identifier parameter, and set the input_block_identifier_length variable to the length of the key
label or the key token of the input block. The input block can be any one of these forms:
v An uninitialized trusted block. The trusted block is complete except that it does not have MAC
protection.
v An inactive trusted block. The trusted block is external, and it is in inactive form. MAC protection is
present due to recycling of an existing inactive trusted block.
v An active trusted block. The trusted block is internal or external, and it is in active form. MAC protection
is present due to recycling of an existing active trusted block.
Note: The MAC key is replaced with a new MAC key, and any RKX key-token created with the input
trusted block cannot be used with the output trusted block.
The verb randomly generates a confounder and triple-length MAC key, and uses a variant of the MAC key
to calculate an ISO 16609 CBC-mode Triple-DES MAC of the trusted block contents. To protect the MAC
key, the verb encrypts the confounder and MAC key using a variant of an IMP-PKA key (see Table 162 on
page 657). The calculated MAC and the encrypted confounder and MAC key are embedded in the output
trusted block. Use the transport_key_identifier parameter to identify the key token that contains the
IMP-PKA key.
On input, set the trusted_block_identifier_length variable to the length of the key label or at least the size
of the output trusted block. The output trusted block is returned in the key-token identified by the
trusted_block_identifier parameter, and the verb updates the trusted_block_identifier_length variable to the
size of the key token if a key label is not specified.
Create an active external trusted block: To create an active external trusted block, use a rule_array_count
of 1 and a rule_array keyword of ACTIVE. Identify the input trusted block using the input_block_identifier

parameter, and set the input_block_identifier_length variable to the length of the key label or the key token
of the input block. The input block must be an inactive external trusted block that was created using the
INACTIVE rule_array keyword.
Use the transport_key_identifier parameter to identify the key token that contains the IMP-PKA key.
On input, set the trusted_block_identifier_length variable to the length of the key label or at least the size
of the output trusted block. The verb returns an error if the input trusted block is not valid. Otherwise, it
changes the flag in the trusted block information section from the inactive state to the active state,
recalculates the MAC, and embeds the updated MAC value in the output trusted block.
The output trusted block is returned in the key-token identified by the trusted_block_identifier parameter,
and the verb updates the trusted_block_identifier_length variable to the size of the key token if a key label
is not specified.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v AES keys are not supported by this verb.
Format
CSNDTBC
input_block_identifier_length Input Integer 3500
input_block_identifier Input String input_block_identifier_length bytes
transport_key_identifier Input String 64 bytes
trusted_block_identifier_length In/Output Integer 3500
trusted_block_identifier Output String trusted_block_identifier_length bytes
Parameters

rule_array_count
rule_array
characters. The rule_array keywords are shown in the following table:
Keyword Meaning
Operation (one required)
INACTIVE Create an external trusted block, based on the input_block_identifier variable, and set the
active flag to B'0'. This makes the trusted block unusable in any other CCA services.
ACTIVATE Create an external trusted block, based on the token identified by the input_block_identifier
parameter, and change the active flag from B'0' to B'1'. This makes the trusted block usable
in other CCA services.
input_block_identifier_length
The input_block_identifier_length parameter is a pointer to an integer variable containing the number
of bytes in the input_block_identifier variable. The maximum length is 3500 bytes.
input_block_identifier
The input_block_identifier parameter is a pointer to a string variable containing a trusted block
key-token or the key label of a trusted block key-token that has been built according to the format
specified in Trusted blocks on page 600. The trusted block key-token will be updated by the verb and
returned in the trusted_block_identifier variable.
When the operation is INACTIVE, the trusted block can have MAC protection (for example, due to
recycling of an existing trusted block), but typically it does not.
The transport_key_identifier parameter is a pointer to a string variable containing an operational
key token must be of type IMP-PKA.
An IMP-PKA key type is an IMPORTER key-encrypting key with only its IMPORT key-usage bit (bit 21)
on; its other key-usage bits (IMEX, OPIM, IMIM, and XLATE) must be off. See Table 162 on page 657.
Note: An IMP-PKA control vector can be built using the Control_Vector_Generate verb with a key type
of "IMPORTER" and a rule_array keyword of IMPORT.
trusted_block_identifier_length
The trusted_block_identifier_length parameter is a pointer to an integer variable containing the number
of bytes of data in the trusted_block_identifier variable. The maximum length is 3500 bytes.
The output trusted block token can be up to seven bytes longer than the input trusted block token due
to padding.
trusted_block_identifier
The trusted_block_identifier parameter is a pointer to a string variable containing a trusted block token
or a label of a trusted block token returned by the verb.
Required commands
The Trusted_Block_Create verb requires the following commands to be enabled in the active role based
on the keyword specified for the operation rule:

INACTIVE X'030F' Create a Trusted Block in Inactive Form
ACTIVATE X'0310' Activate an Inactive Trusted Block

Chapter 6. Data confidentiality and data integrity
This section describes the verbs that use the Advanced Encryption Standard (AES) and Data Encryption
Standard (DES) algorithms to encrypt and decrypt data, and the DES verbs to generate and verify a
message authentication code (MAC). It contains sections on:
v Encryption and message authentication codes
v Data confidentiality and data integrity verbs
The following table lists the data confidentiality and data integrity verbs. See Data confidentiality and data
integrity verbs on page 359 for a description of these verbs.
Table 48. Data confidentiality and data integrity verbs
Service
Decipher 360 Deciphers data using a DES key. CSNBDEC E
Encipher 363 Enciphers data using a DES key. CSNBENC E
HMAC_Generate (Rel. 4.1 or 366 Generate a keyed hash message CSNBHMG E
later) authentication (HMAC) code.
HMAC_Verify (Rel. 4.1 or later) 369 Verifies an HMAC. CSNBHMV E
MAC_Generate 372 Generates a message authentication code CSNBMGN E
(MAC).
MAC_Verify 375 Verifies a MAC. CSNBMVR E
| Symmetric_Algorithm_Decipher 378 Deciphers data using an AES key in cleartext CSNBSAD E
| form (no key token), or in cleartext or
| enciphered form contained within a
| fixed-length or variable-length AES key-token.
| Symmetric_Algorithm_Encipher 383 Enciphers data using an AES key in cleartext CSNBSAE E
| form (no key token), or in cleartext or
| enciphered form contained within a
| fixed-length or variable-length AES key-token.
E=cryptographic engine
Encryption and message authentication codes

This section explains how to use the services that are described to ensure the confidentiality of data
through encryption, and to ensure the integrity of data using MACs.
Note: See Chapter 4, Hashing and digital signatures, on page 115 for information about other ways to
ensure data integrity.
Ensuring data confidentiality

You can use the AES Symmetric_Algorithm_Encipher verb and the DES Encipher verb to convert plaintext
to ciphertext. To convert ciphertext back to plaintext, you can use the AES Symmetric_Algorithm_Decipher
verb or the DES Decipher verb. The Encipher and Decipher verbs use the DES data encryption algorithm.
DES operates on blocks of 64 bits (8 bytes). Based on the length of the DES key that you specify, the
Encipher and Decipher verbs perform either basic, single DES or Triple-DES 1. See Single-DES and
Triple-DES encryption algorithms for general data on page 682 for more information.
1. CCA implementations always encipher DES keys and PIN blocks with Triple-DES.
357
| If you know that your data is always in multiples of 8 bytes, you can request the use of the DES Cipher
Block Chaining (CBC) mode of encryption. In this mode, the enciphered result of encrypting one block of
plaintext is exclusive-ORed with the subsequent block of plaintext prior to enciphering the second block.
This process is repeated through the processing of your plaintext. The process is reversed in decryption.
See Ciphering methods on page 681.
If some portion of the ciphertext is altered, the CBC decryption of that block and the subsequent block
does not recover the original plaintext. Other blocks of plaintext are correctly recovered. CBC encryption is
used to disguise patterns in your data that could be seen if each data block was encrypted by itself.
In general, data to be ciphered is not a multiple of 8 bytes. In this case, a strategy for the last block of
data must be adopted. The Encipher and Decipher verbs can also be used with the ANS X9.23 mode of
encryption. In X9.23 encryption, at least 1 byte of data and up to 8 bytes of data are always added to the
end of your plaintext. The last of the added bytes is a binary value equal to the number of added bytes.
The ANS X9.23 process ensures that the enciphered data is always a multiple of 8 bytes as required for
CBC encryption. In X9.23 decryption, the padding is removed from the decrypted plaintext.
Whenever the first block of plaintext has a predictable value, it is important to modify the first block of data
prior to encryption to deny an adversary a known plaintext-ciphertext pair. There are two common
approaches:
v Use an initialization vector
v Prepend your data with 8 bytes of random data, called an initial text sequence
An initialization vector is exclusive-ORed with the first block of plaintext prior to encrypting the result. The
initialization vector is exclusive-ORed with the decryption of the first block of ciphertext to correctly recover
the original plaintext. You must have a means of passing the value of the initialization vector from the
encryption process to the decryption process. A common solution to the problem is to pass the initialization
vector as an encrypted quantity during key agreement between the encrypting and decrypting processes.
You specify the value of an initialization vector when you invoke the Encipher and Decipher verbs.
If the procedure for agreeing on a key does not readily result in passing of an encrypted quantity that can
serve as the initialization vector, then you can add 8 bytes of random data to the start of your plaintext. Of
course, the decrypting process must remove this initial text sequence as it recovers your plaintext. An
initialization vector valued to binary 0 is used in this case.
The key used to encrypt or decrypt your data is specified in a key token. The control vector for the key
must be of the general class DATA or CIPHER-class (control vector bits 8 to 15 equal to X'00' or X'03',
respectively). In addition to the class of key defined in CV bits 8 to 14, CV bit 18 must also be on to
encipher data while CV bit 19 must also be on to decipher data. See Appendix C, CCA control-vector
definitions and key encryption. DATA keys can participate in both enciphering and using MAC, while
CIPHER-class keys only perform in ciphering operations.
If an invocation of the Encipher of the Decipher verb includes an initialization vector value, use the
keyword INITIAL. If there is more data that is a logical extension of preceding data, you can use the
keyword CONTINUE. In this case, the initialization vector value is not used, but the enciphered value of
the last block of data from a prior ciphering verb is taken from the chaining_vector save area that you
must provide with each use of the ciphering verbs. Each portion of the data must be a multiple of 8 bytes
and you must use the CBC encryption mode. You can use X9.23 keyword with the final invocation of the
ciphering verbs if your processes use this method to accommodate data that can be other than a multiple
of 8 bytes.
Ensuring data integrity

CCA offers three classes of services for ensuring data integrity:
| v MAC techniques based on the DES or HMAC algorithm
v Hashing techniques

v Digital signature techniques
This section includes the MAC verbs. For information on using hashing or digital signatures to ensure the
integrity of data, see Chapter 4, Hashing and digital signatures.
The MAC_Generate and MAC_Verify verbs support four variations of DES-based message authentication
(see MAC calculation methods on page 689). These methods are:
1. ANS X9.9 Option 1, binary data (same as ANS X9.19 Basic Procedure and ISO/IEC 9797-1, MAC
Algorithm 1). This method requires a single-length key. This is the default method used for a
single-length key.
2. ANS X9.19 Optional Procedure (same as ISO/IEC 9797-1, MAC Algorithm 3). This method requires a
double-length key. This is the default method used for a double-length key.
3. ISO 16609 Triple-DES (same as ISO/IEC 9797-1, MAC Algorithm 1 using Triple-DES/ANS X9.52). This
method requires a double-length key.
4. EMVMAC (single-length key) or EMVMACD (double-length key). These methods are the same as ANS
X9.9 Option 1 and ANS X9-19 Optional Procedure, respectively, except with a message padding
technique employed with EMV smart card messages.
Both the DATA class and the MAC or MACVER key types can be used. Control vector bit 20 (MAC
generate) must be on for keys used in the MAC_Generate verb. Control vector bit 21 (MAC verify) must
be on for keys used in the MAC_Verify verb.
You can employ MAC values with 4-byte, 6-byte, or 8-byte lengths (32, 48, or 64 bits) by using the
MACLEN4, MACLEN6, or MACLEN8 keywords in the rule array. MACLEN4 is the default.
When generating or verifying a 32-bit MAC, exchange the MAC in one of these ways:
v Binary, in 4 bytes (the default method)
v 8 hexadecimal characters, invoked using the HEX-8 keyword
v 8 hexadecimal characters with a space character between the fourth and fifth hex characters, invoked
using the HEX-9 keyword
For details about MAC services, see MAC_Generate (CSNBMGN) on page 372 and MAC_Verify
(CSNBMVR) on page 375.
MAC and segmented data

Using MAC services procedure, you can divide a string of data into parts, and generate or verify a MAC in
a series of procedure calls to the appropriate verb. This can be useful when it is no possible to bring the
entire string into memory. For example, you might want to use MAC for the entire contents of a dataset
which is tens or hundreds of megabytes in length. The length of the data in each procedure-call is
restricted only by the operating environment and the particular verb.
In each procedure call, a segmenting-control keyword indicates whether the call contains the first, middle,
or last unit of segmented data; the chaining_vector parameter specifies the work area that the verb uses.
The default segmenting-control keyword ONLY specifies that segmenting is not used.
Data confidentiality and data integrity verbs
Chapter 6. Data confidentiality and data integrity 359

Decipher (CSNBDEC)
| The Decipher verb uses the Data Encryption Standard (DES) algorithm and a cipher key to decipher data
| called ciphertext. This verb returns data called plaintext. Also see Symmetric_Algorithm_Decipher
| (CSNBSAD) on page 378.
Performance can be enhanced by aligning the start of the plaintext and ciphertext variables on 4-byte
boundaries.
DATA, DATAC, CIPHER, and DECIPHER key types can be used. Both DES and Triple-DES are performed
based on the length of the key. For additional information about the ciphering verbs, see Ensuring data
confidentiality on page 357.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The starting address of plaintext cannot begin within the ciphertext variable.
v The text_length variable is restricted to a maximum length of 32 MB 8 bytes, and to 64 MB 8 bytes
in the IBM i environment.
| v The installed function control vector regulates the maximum data ciphering capability to DES or
| Triple-DES.
Format
CSNBDEC
text_length In/Output Integer
ciphertext Input String text_length bytes
plaintext Output String text_length bytes

Parameters
key_identifier
The key_identifier parameter is a pointer to a string variable containing an internal key-token or a key
label of an internal key-token record. Use a key type of DATA (CV bit 19 on), DATAC, CIPHER, or
DECIPHER.
text_length
The text_length parameter is a pointer to an integer variable. On input, the text_length variable
contains the number of bytes of data in the ciphertext variable. On output, the text_length variable
contains the number of bytes of data in the plaintext variable.
ciphertext
The ciphertext parameter is a pointer to a string variable containing the text to be deciphered.
The initialization_vector parameter is a pointer to a string variable containing the initialization vector
that the verb uses with the input data.
rule_array_count
in the rule_array variable. This value must be 0, 1, 2, or 3.
rule_array
characters.
Keyword Meaning
Deciphering method (one, optional)
CBC Specifies Cipher Block Chaining. The data must be a multiple of 8 bytes. This is the default.
X9.23 Specifies Cipher Block Chaining with 1 - 8 bytes of padding. This is compatible with the
requirements in ANS Standard X9.23.
ICV (one, optional)
| INITIAL Specifies that this is either the first request of a sequence of chained requests, or the only
| request. The value identified by the initialization_vector parameter is used as input to decipher
| the first block of data. This must be the same value that was previously used to produce the
| ciphertext. The value identified by the chaining_vector parameter is ignored on input, and is
| updated with data required for the next subsequent chained request, if any. This is the default.
| CONTINUE Specifies that the request is part of a sequence of chained requests and is not the first (initial)
| request in the sequence. The value identified by the chaining_vector parameter is used as
| input to decipher the next block of ciphertext data, and is updated with data required for the
| next subsequent chained request, if any. The value identified by the initialization_vector
| parameter is ignored.
| This keyword is not valid with the X9.23 deciphering method keyword.
Decryption process (one, optional)
| DES Specifies use of the DES ciphering algorithm. If an adapter cannot use DES general
| data-decipherment, the verb is rejected. This is the default.
| CDMF Specifies use of the CDMF ciphering algorithm. This keyword is no longer implemented.

chaining_vector
The chaining_vector parameter is a pointer to a string variable containing the segmented data
between calls by the security server. The output chaining vector is contained in bytes 0 - 7.
Important: Application programs must not alter the contents of this variable between related INITIAL
and CONTINUE calls.
plaintext
The plaintext parameter is a pointer to a string variable containing the plaintext returned by the verb.
The starting address of plaintext variable cannot begin within the ciphertext variable. The verb
updates the text_length variable to the length of the plaintext when it returns. The length is different
when padding is removed.
Required commands
The Decipher verb requires the Decipher command (offset X'000F') to be enabled in the active role.

Encipher (CSNBENC)
| The Encipher verb uses the DES algorithm and a cipher key to encipher data called plaintext. This verb
| returns data called ciphertext. Also see Symmetric_Algorithm_Encipher (CSNBSAE) on page 383.
The returned ciphertext can be as many as 8 bytes longer than the plaintext due to padding. Ensure the
ciphertext variable is large enough to receive the returned data.
Performance can be enhanced by aligning the start of the plaintext and ciphertext variables on 4-byte
boundaries.
DATA, DATAC, CIPHER, and ENCIPHER key types can be used. Both DES and Triple-DES are performed
based on the length of the key. For additional information about the ciphering verbs, see Ensuring data
confidentiality on page 357.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The text_length variable is restricted to a maximum length of 32 MB - 8 bytes and to 64 MB 8 bytes in
the IBM i environment.
| v The installed function control vector regulates the maximum data ciphering capability to DES or
| Triple-DES.
Format
CSNBENC
text_length In/Output Integer
plaintext Input String text_length bytes
pad_character Input Integer 0 - 255
ciphertext Output String updated text_length bytes

Parameters
key_identifier
The key_identifier parameter is a pointer to a string variable containing an internal key-token or the
key label of an internal key-token record. Use a key type of DATA (CV bit 18 on), DATAC, CIPHER, or
ENCIPHER.
text_length
The text_length parameter is a pointer to an integer variable. On input, the text_length variable
contains the number of bytes of data in the cleartext variable. On output, the text_length variable
contains the number of bytes of data in the ciphertext variable.
plaintext
The plaintext parameter is a pointer to a string variable containing the text to be enciphered.
that the verb uses with the input data.
rule_array_count
rule_array
Keyword Meaning
Enciphering method (one, optional)
CBC Specifies Cipher Block Chaining. The data must be a multiple of 8 bytes. This is the default.
X9.23 Specifies Cipher Block Chaining with 1 - 8 bytes of padding. This is compatible with the
requirements in ANS Standard X9.23.
ICV (one, optional)
| INITIAL Specifies that this is either the first request of a sequence of chained requests, or the only
| request. The value identified by the initialization_vector parameter is used as input to encipher
| the first block of data. This must be the same value that is later used to recover the plaintext.
| The value identified by the chaining_vector parameter is ignored on input, and is updated with
| data required for the next subsequent chained request, if any. This is the default.
| CONTINUE Specifies that the request is part of a sequence of chained requests and is not the first (initial)
| request in the sequence. The value identified by the chaining_vector parameter is used as
| input to encipher the next block of plaintext data, and is updated with data required for the next
| subsequent chained request, if any. The value identified by the initialization_vector parameter is
| ignored.
| This keyword is not valid with the X9.23 enciphering method keyword.
Encryption process (one, optional)
| DES Specifies use of the DES ciphering algorithm. If an adapter does not support DES general data
| encipherment, the verb is rejected. This is the default.
| CDMF Specifies use of the CDMF ciphering algorithm. This keyword is no longer implemented.
pad_character
The pad_character parameter is a pointer to an integer variable containing a value used as a padding
character. The value must be 0 255. When you use the X9.23 count byte and padding bytes as
required.

chaining_vector
The chaining_vector parameter is a pointer to a string variable containing a work area that the security
server uses to carry segmented data between procedure calls.
Important: Application programs must not alter the contents of this variable between related INITIAL
and CONTINUE calls.
ciphertext
The ciphertext parameter is a pointer to a string variable containing the enciphered text returned by
the verb. The starting address of the ciphertext variable cannot begin within the plaintext variable. The
returned ciphertext might be up to 8 bytes longer than the plaintext because of padding. The verb
updates the text_length variable to the length of the ciphertext when it returns. The length is different
when padding is added.
Required commands
The Encipher verb requires the Encipher command (offset X'000E') to be enabled in the active role.

HMAC_Generate (CSNBHMG)
| Use the HMAC_Generate verb to generate a keyed hash message authentication code (HMAC) for the
| message string provided as input. A MAC key with key usage that can be used for generate is required to
| calculate the MAC. The key must be in a variable-length HMAC key-token. Also see MAC_Generate
| (CSNBMGN) on page 372.
Restrictions
| AIX X
| IBM i X
| Windows
|
| v The message_length variable must be less than 32 MB minus 8 bytes. The maximum length on IBM i
systems is 64 MB minus 64 bytes.
Format
CSNBHMG
key_identifier_length Input Integer 800
message_text_length Input Integer Minimum is 8. For the maximum, see Restrictions.
message_text Input String message_text_length bytes
MAC_length In/Output Integer 64
MAC Output String MAC_length bytes
Parameters
rule_array_count

rule_array
characters.
Keyword Meaning
HMAC Specifies to use the HMAC algorithm to generate a MAC.
SHA-1 Specifies to use the SHA-1 hash method.
ONLY Specifies that this is the only data from the application program. The application program does
not use segmenting. This is the default.
FIRST Specifies that this is the first segment of data from the application program.
MIDDLE Specifies that this is an intermediate segment of data from the application program.
LAST Specifies that this is the last segment of data from the application program.
of data in the key_identifier variable.
key_identifier
| The key_identifier parameter is a pointer to a string variable containing an operational HMAC key in a
| variable-length symmetric key-token or a key label identifying such a key in key-storage. The key is
| used to generate the keyed-hash message authentication code. A MAC key type that can be used for
| generate is required.
message_text_length
The message_text_length parameter is a pointer to an integer variable containing the number of bytes
of data in the message_text variable.
message_text
The message_text parameter is a pointer to a string variable containing the text of the message that
the hardware uses to calculate the MAC.
chaining_vector
The chaining_vector parameter is a pointer to a string variable containing a work area the security
Important: Application programs must not alter the contents of this variable between related FIRST,
MAC_length
The MAC_length parameter is a pointer to an integer variable containing the number of bytes of data

in the MAC variable. On input, the length must be sufficient to receive the output MAC. On output, the
value of the variable is updated to contain the actual length of the MAC value generated by the verb.
MAC
The MAC parameter is a pointer to a string variable containing the resulting MAC returned by the verb.
The value is left-aligned in the variable.
Required commands
The HMAC_Generate verb requires the following commands to be enabled in the active role:

SHA-1 X'00E4' Generate SHA-1 HMAC

HMAC_Verify (CSNBHMV)
| Use the HMAC_Verify verb to verify a keyed hash message authentication code (HMAC) for the message
| text provided as input. A MAC key with key usage that can be used for verify is required to calculate the
| MAC. The key must be in a variable-length HMAC key-token and have the same value as the key used to
| generate the HMAC. Also see MAC_Verify (CSNBMVR) on page 375.
Restrictions
| AIX X
| IBM i X
| Windows
|
| v The message_length variable must be less than 32 MB minus 8 bytes. The maximum length on IBM i
systems is 64 MB minus 64 bytes.
Format
CSNBHMV
key_identifier_length Input Integer 800
message_text_length Input Integer Minimum is 8. For maximum, see Restrictions
message_text Input String message_text_length bytes
MAC_length Input Integer 64
MAC Input String MAC_length bytes
Parameters
rule_array_count

rule_array
characters.
Keyword Meaning
HMAC Specifies to use the HMAC algorithm to verify a MAC.
ONLY Specifies that this is the only data from the application program. The application program does
not use segmenting. This is the default.
of data in the key_identifier variable.
key_identifier
| The key_identifier parameter is a pointer to a string variable containing an operational variable-length
| HMAC key-token, or a key label identifying such a key in AES key storage. The key is used to verify
| the keyed-hash message authentication code. A MAC key type is required. The key must have usage
| that can be used for verify.
message_text_length
The message_text_length parameter is a pointer to an integer variable containing the number of bytes
of data in the message_text variable.
message_text
The message_text parameter is a pointer to a string variable containing the text of the message that
the hardware uses to calculate the MAC.
chaining_vector
MAC_length
The MAC_length parameter is a pointer to an integer variable containing the number of bytes of data
in the MAC variable.

MAC
The MAC parameter is a pointer to a string variable containing the trial MAC. The value must be
left-aligned in the variable. The verb verifies the MAC if segmenting control is ONLY or LAST.
Required commands
The HMAC_Verify verb requires the following commands to be enabled in the active role:

SHA-1 X'00F7' Verify SHA-1 HMAC
SHA-384 X'00FA' Verify SHA-384 HMAC
SHA-512 X'00FB' Verify SHA-512 HMAC

MAC_Generate (CSNBMGN)
Use the MAC_Generate verb to generate a message authentication code (MAC) for the text string
provided as input. For additional information about using the MAC generation and verification verbs, see
| Ensuring data integrity on page 358. Also see HMAC_Generate (CSNBHMG) on page 366.
Performance can be enhanced by aligning the start of the text variable on a 4-byte boundary.
Specify the MAC ciphering method through the choice of a rule-array keyword. There are defaults based
on the use of a single-length or double-length key.
EMVMAC and EMVMACD
EMV message authentication processes. See the EMV 4.0 Book 2, Annex A1.2 for information
about this form of MAC generation. The verb extends the text provided with X'80' and the
minimum number (0...7) bytes of X'00' for the extended message to be a multiple of 8 bytes in
length. The MAC is computed based on ISO/IEC 9797-1, MAC Algorithm 1 or MAC Algorithm 3,
depending on key length. When specifying a single-length key, use EMVMAC. When specifying a
double-length key, use EMVMACD.
Note: The EMV specification permits the MAC to be 4 - 8 bytes in length. The MAC_Verify verb
only uses MAC lengths of 4, 6, and 8 bytes.
TDES-MAC
ANS X9.9 Option 1 (binary data) procedure using ISO 16609 CBC-mode Triple-DES (TDES)
encryption of the data. See Triple-DES ciphering algorithms on page 685. Uses a double-length
key.
X9.9-1 ANS X9.9 Option 1 (binary data) procedure, by default when a single-length key is provided. This
is the same as ANS X9.19 Basic Procedure and ISO/IEC 9797-1, MAC Algorithm 1.
X9.19OPT
ANS X9.19 Optional Procedure, by default when a double-length key is provided. This is the same
as ISO/IEC 9797-1, MAC Algorithm 3.
Any of these DES key types can be used: DATA, DATAM, or MAC.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The text_length variable must be at least 8 bytes. The maximum length on IBM i systems is 64 MB
minus 8 bytes, and on other systems the maximum length is 32 MB minus 8 bytes.

Format
CSNBMGN
text_length Input Integer 8
MAC Output String 4, 6, 8, or 9 bytes
Parameters
key_identifier
The key_identifier parameter is a pointer to a string variable containing an operational key-token or the
key label of an operational key-token record. Use a key type of DATA (CV bit 21 on), DATAM,
DATAMV, MAC, or MACVER. The DATA, MAC, and MACVER keys can be either single length or
double length.
text_length
the text variable.
text
The text parameter is a pointer to a string variable containing the text that the hardware uses to
calculate the MAC.
rule_array_count
rule_array

Keyword Meaning
MAC ciphering-method (one, optional)
EMVMAC Specifies the EMV-related message-padding and calculation method. A single-length key is
required.
EMVMACD Specifies the EMV-related message-padding and calculation method. A double-length key is
required.
TDES-MAC Specifies the ANS X9.9 Option 1 (binary data) procedure and a CBC Triple-DES encryption of
the data. See Triple-DES ciphering algorithms on page 685. A double-length key is required.
X9.9-1 Specifies the ANS X9.9 Option 1 (binary data) procedure. A single-length key is required. This
is the default for a single-length key.
X9.19OPT Specifies the ANS X9.19 Optional Procedure. A double-length key is required. This is the
default for a double-length key.
ONLY Specifies that the application program does not use segmenting. This is the default.
MAC length and presentation (one, optional)
MACLEN4 Specifies a 4-byte MAC. This is the default.
MACLEN6 Specifies a 6-byte MAC.
MACLEN8 Specifies an 8-byte MAC.
HEX-8 Specifies a 4-byte MAC and presents it as 8 hexadecimal characters.
HEX-9 Specifies a 4-byte MAC and presents it as two groups of 4 hexadecimal characters separated
by a space character.
chaining_vector
MAC
The MAC parameter is a pointer to a string variable containing the resulting MAC returned by the verb.
The value is left-aligned in the variable. Allocate a variable large enough to receive the resulting MAC
value.
Required commands
The MAC_Generate verb requires the Generate MAC command (offset X'0010') to be enabled in the
active role.

MAC_Verify (CSNBMVR)
Use the MAC_Verify verb to verify a message authentication code (MAC) for the text string provided as
input. For additional information about using the MAC generation and verification verbs, see Ensuring
| data integrity on page 358. Also see HMAC_Verify (CSNBHMV) on page 369.
Performance can be enhanced by aligning the start of the text variable on a 4-byte boundary.
Specify the MAC process through the choice of a rule-array keyword. There are defaults based on the use
of a single-length or double-length key.
EMVMAC and EMVMACD
EMV message authentication procedure. See the EMV 4.0 Book 2, Annex A1.2, for information
about this form of MAC verification. The verb extends the text provided with X'80' and the
minimum number (0...7) bytes of X'00' for the extended message to become a multiple of 8 bytes
in length. The MAC is computed based on ISO/IEC 9797-1, MAC Algorithm 1 or MAC Algorithm 3,
depending on key length. When specifying a single-length key, use EMVMAC. When specifying a
double-length key, use EMVMACD.
Note: The EMV specification permits the MAC to be 4 - 8 bytes in length. This verb only supports
MAC lengths of 4, 6, and 8 bytes.
TDES-MAC
ANS X9.9 Option 1 (binary data) procedure using ISO 16609 CBC-mode Triple-DES (TDES)
encryption of the data. See Triple-DES ciphering algorithms on page 685. Uses a double-length
key.
X9.9-1 ANS X9.9 Option 1 (binary data) procedure, by default when a single-length key is provided. This
is the same as ANS X9.19 Basic Procedure and ISO/IEC 9797-1, MAC Algorithm 1.
X9.19OPT
ANS X9.19 Optional Procedure, by default when a double-length key is provided. This is the same
as ISO/IEC 9797-1, MAC Algorithm 3.
Any of these DES key types can be used: DATA (CV bit 21 on), DATAM, DATAMV, MAC, or MACVER.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The text_length variable must be at least 8 bytes. The maximum length on IBM i systems is 64 MB
minus 8 bytes, and on other systems the maximum length is 32 MB minus 8 bytes.

Format
CSNBMVR
text_length Input Integer 8
MAC Input String 9 bytes
Parameters
key_identifier
The key_identifier parameter is a pointer to a string variable containing an operational key token or the
key label of an operational key-token record. Use a key type of DATA (CV bit 21 on), DATAM,
DATAMV, MAC, or MACVER. The DATA, MAC, and MACVER keys can be either single length or
double length.
text_length
the text variable.
text
The text parameter is a pointer to a string variable containing the text the hardware uses to calculate
the MAC.
rule_array_count
rule_array

Keyword Meaning
MAC ciphering-method (one, optional)
EMVMAC Specifies the EMV-related message-padding and calculation method. A single-length key is
required.
EMVMACD Specifies the EMV-related message-padding and calculation method. A double-length key is
required.
TDES-MAC Specifies the ANS X9.9 Option 1 (binary data) procedure using ISO 16609 CBC-mode
Triple-DES encryption of the data. See Triple-DES ciphering algorithms on page 685. A
double-length key is required.
X9.9-1 Specifies the ANS X9.9 Option 1 (binary data) procedure. A single-length key is required. This
is the default for a single-length key.
X9.19OPT Specifies the ANS X9.19 Optional Procedure. A double-length key is required. This is the
default for a double-length key.
ONLY Specifies that the application program does not use segmenting. This is the default.
MAC length and presentation (one, optional)
MACLEN4 Specifies a 4-byte MAC. This is the default.
MACLEN6 Specifies a 6-byte MAC.
MACLEN8 Specifies an 8-byte MAC.
HEX-8 Specifies a 4-byte MAC and accepts it as 8 hexadecimal characters.
HEX-9 Specifies a 4-byte MAC and accepts it as two groups of 4 hexadecimal characters separated
by a space character.
chaining_vector
MAC
The MAC parameter is a pointer to a string variable containing the trial MAC. Ensure that this
parameter is a pointer to a 9-byte string variable, because 9 bytes are always sent to the security
server. The MAC value must be left-aligned in the variable. The verb verifies the MAC if you specify
the ONLY or LAST keyword for the segmenting control.
Required commands
The MAC_Verify verb requires the Verify MAC command (offset X'0011') to be enabled in the active role.

Symmetric_Algorithm_Decipher (CSNBSAD)
Use the Symmetric_Algorithm_Decipher verb to decipher data with the AES (Advanced Encryption
Standard) algorithm. Data can be deciphered in either Cipher Block Chaining (CBC) mode with or without
| padding, or in Electronic Code Book (ECB) mode. Also see Decipher (CSNBDEC) on page 360.
The AES key used to decipher the data can either be 16, 24, or 32 bytes (128, 192, or 256 bits) in length.
The key can be supplied to the verb in any of three forms:
1. A cleartext key consisting of only the key bytes, not contained in a key token
| 2. A cleartext key contained in an internal fixed-length or, beginning with Release 4.2, a variable-length
| AES key-token
| 3. An encrypted key contained in an internal fixed-length or, beginning with Release 4.2, a variable-length
| AES key-token, where the key is wrapped (encrypted) with the AES master key

v The rule array:
1. The algorithm identifier keyword AES, which is the only symmetric algorithm currently supported
2. An optional processing rule using keyword CBC (the default), ECB, or PKCS-PAD, which selects
the decryption mode
| 3. An optional key rule using the keyword KEY-CLR (the default) or KEYIDENT, which selects whether
| the key_identifier parameter points to a 16-byte, 24-byte, or 32-byte clear key, or a key contained in
| a fixed-length or variable-length AES key-token, in application storage or a key label of such a key
| in AES key-storage.
4. An optional ICV (initial chaining value) selection using the keyword INITIAL (the default) or
CONTINUE, which indicates whether it is the first or a subsequent request, and which parameter
points to the initialization vector
| v For a key rule of KEY-CLR, a key identifier containing a 16-byte, 24-byte, or 32-byte clear key. For a
| key rule of KEYIDENT, a fixed-length or variable-length internal AES key-token or the key label of such
| a key in AES key-storage. The key token can contain either a clear or enciphered key.
| A variable-length AES key-token must have a key that can be used for decryption (key-usage field 1
| high-order byte = B'x1xx xxxx'). Also, for processing rule CBC or PKCS-PAD, key usage must allow the
| key to be used for Cipher Block Chaining (KUF2 high-order byte = X'00'). For processing rule ECB, key
| usage must allow the key to be used for Electronic Code Book (KUF2 high-order byte = X'01').
v A block size of 16 for the cryptographic algorithm.
v For cipher block chaining, either one of these:
1. For an ICV selection of INITIAL, a 16-byte initialization vector of your choosing and a 32-byte chain
data buffer
2. For an ICV selection of CONTINUE, no initialization vector and the 32-byte chain data buffer from
the output of the previous chained call. The electronic code book algorithm does not use an
initialization vector or a chain data buffer
v The ciphertext to be deciphered.
v A cleartext buffer large enough to receive the deciphered output.
This verb does the following when it deciphers the data:

v Verifies the AES key-token for keyword KEYIDENT.
v Verifies that the ciphertext length is a multiple of the block size.
v Deciphers the input AES key if the key is encrypted (MKVP was present in token).
v Deciphers the ciphertext with the AES clear key according to the encryption mode specified.
v Removes from 1 - 16 pad characters from the right of the clear data for keyword PKCS-PAD.
v Returns the cleartext data and its length.
v Returns the chain data and its length if keyword ECB is not specified.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Variable-length symmetric key tokens are not supported in releases before Release 4.2.
Format
CSNBSAD
| key_identifier_length Input Integer 16, 24, 32, or 64
key_parms_length Input Integer 0
key_parms Input String key_parms_length bytes
block_size Input Integer 16
initialization_vector_length Input Integer 0 or 16
initialization_vector Input String initialization_vector_length bytes
chain_data_length In/Output Integer 32
chain_data In/Output String chain_data_length bytes
ciphertext_length Input Integer multiple of block_size
ciphertext Input String ciphertext_length bytes
cleartext_length In/Output Integer ciphertext_length minus pad byte count
cleartext In/Output String cleartext_length bytes
optional_data_length Input Integer 0
optional_data Input String optional_data_length bytes
Parameters
rule_array_count

rule_array
characters.
Keyword Meaning
Algorithm identifier (one required)
AES Specifies use of the Advanced Encryption Standard (AES) as the encryption algorithm.
The block size for AES is 16 bytes, and the key length is 16, 24, or 32 bytes. AES is the
only algorithm currently supported by this verb.
Processing rule (one, optional)
CBC Specifies encryption in Cipher Block Chaining mode. The cleartext length must be a
multiple of the block size. This is the default value.
ECB Specifies encryption in Electronic Code Book mode. The cleartext length must be a
multiple of the block size.
PKCS-PAD Specifies that the cleartext was padded on the right with 1 - 16 bytes of pad characters,
| making the padded text a multiple of the block size, before the data was enciphered in
| Cipher Block Chaining mode. Each pad character is valued to the number of pad
characters added.
The output cleartext is stripped of any pad characters and the cleartext length is 1 - 16
bytes less than the ciphertext length.
Key rule (one, optional)
KEY-CLR Specifies that the key_identifier parameter points to a cleartext AES key. Only the key
value is permitted; the key is not contained in a key token. This is the default value.
KEYIDENT Specifies that the key_identifier parameter points to an internal AES key-token or the
label of an internal key-token in AES key-storage.
ICV selection (one, optional)
INITIAL Specifies that this is either the first request of a sequence of chained requests, or the
only request. The initialization vector is used as input to decipher the first block of data,
and must be the same value used to encipher the ciphertext. The chain data buffer is
updated with output that is used as input to subsequent chained requests. This is the
default.
CONTINUE Specifies that the request is part of a sequence of chained requests and is not the first
(initial) request in the sequence. The chain data is used as input to decipher the next
block of data. The chain data buffer is updated with output that is used as input to
subsequent chained requests.
This keyword is not valid with the ECB processing rule keyword.
| of data in the key_identifier variable. This value must be 16, 24, 32, or greater than or equal to 64.
key_identifier
The key_identifier parameter is a pointer to a string variable containing either a cleartext AES key or
the internal key-token or a label for an internal key-token record in AES key-storage. This is the key
used to decipher the data pointed to by the ciphertext parameter.
| For rule-array keyword KEY-CLR, a 16-byte, 24-byte, or 32-byte clear AES key is required. For
| rule-array keyword KEYIDENT, a fixed-length or, beginning with Release 4.2, a variable-length internal
| AES key-token or key label for such a key in AES key-storage is required.

key_parms_length
The key_parms_length parameter is a pointer to an integer variable containing the number of bytes of
data in the key_parms parameter. This value must be 0.
key_parms
The key_parms parameter is a pointer to a string variable for key-related parameters. It is currently
unused.
block_size
The block_size parameter is a pointer to an integer variable containing the block size used by the
cryptographic algorithm. This value must be 16.
initialization_vector_length
| The initialization_vector_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the initialization_vector variable. For Cipher Block Chaining (CBC or PKCS-PAD) with
| an ICV selection of INITIAL, this value must be 16. Otherwise, set this value to 0.
| The initialization_vector parameter is a pointer to a string variable containing the initialization vector for
| the INITIAL call to CBC mode encryption. It is not used if the processing rule is ECB or the ICV
| selection is CONTINUE. The same initialization vector must have been used to encipher the data.
chain_data_length
The chain_data_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the chain_data variable. On input, set this variable to a value of 32 or greater for CBC mode
| encryption, or 0 for ECB mode encryption.
On output, the variable is updated with the length of the data returned in the chain_data variable. The
chain_data_length parameter must not be changed by the calling application until chained operations
are complete.
chain_data
The chain_data parameter is a pointer to a string variable used as a work area for CBC encipher
requests. This work area is not used for ECB mode encryption. When the verb performs a CBC
decipher operation and the ICV selection is INITIAL, the chain_data variable is an output-only buffer
that receives data used as input for deciphering the next part of the input data, if any. When the ICV
selection is CONTINUE, the chain_data variable is both an input and output buffer. The application
must not change any intermediate data in this string.
ciphertext_length
The ciphertext_length parameter is a pointer to an integer variable containing the number of bytes of
data in the ciphertext variable. The ciphertext_length value must be a multiple of the block size. The
value must not be 0. If PKCS-PAD is specified, the output cleartext_length variable will be from 1 - 16
bytes less than the ciphertext_length value.
ciphertext
The ciphertext parameter is a pointer to a string variable containing the data to be deciphered,
including any pad bytes.
cleartext_length
On input, the cleartext_length parameter is a pointer to an integer variable containing the number of
bytes of data in the cleartext variable. On output, the cleartext_length variable is updated to contain
the actual length of text output in the cleartext variable. If PKCS-PAD is specified, the cleartext value
is updated with 1 - 16 bytes of data less than the ciphertext_length value.
cleartext
The cleartext parameter is a pointer to a string variable used to contain the data to be enciphered,
excluding any pad bytes.
optional_data_length
| The optional_data_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the optional_data variable. Set this value to 0.

optional_data
The optional_data parameter is a pointer to a string variable containing optional data for the
decryption. It is currently not used.
Required commands
The Symmetric_Algorithm_Decipher verb requires the Decipher Data Using AES command (offset X'012B')

Symmetric_Algorithm_Encipher (CSNBSAE)
Use the Symmetric_Algorithm_Encipher verb to encipher data with the AES (Advanced Encryption
Standard) algorithm. Data can be enciphered in either Cipher Block Chaining (CBC) mode with or without
| padding, or in Electronic Code Book (ECB) mode. Also see Encipher (CSNBENC) on page 363.
The AES key used to encipher the data can either be 16, 24, or 32 bytes (128, 192, or 256 bits) in length.
The key can be supplied to the verb in any of three forms:
1. A cleartext key consisting of only the key bytes, not contained in a key token
| 2. A cleartext key contained in an internal fixed-length or, beginning with Release 4.2, a variable-length
| AES key-token
| 3. An encrypted key contained in an internal fixed-length or, beginning with Release 4.2, a variable-length
| AES key-token, where the key is wrapped (encrypted) with the AES master key

v The rule array:
1. The algorithm identifier keyword AES, which is the only symmetric algorithm currently supported
2. An optional processing rule using keyword CBC (the default), ECB, or PKCS-PAD, which selects
the decryption mode
| 3. An optional key rule using the keyword KEY-CLR (the default) or KEYIDENT, which selects whether
| the key_identifier parameter points to a 16-byte, 24-byte, or 32-byte clear key, or a key contained in
| a fixed-length or variable-length AES key-token, in application storage or a key label of such a key
| in AES key-storage
4. An optional ICV (initial chaining value) selection using the keyword INITIAL (the default) or
CONTINUE, which indicates whether it is the first or a subsequent request, and which parameter
points to the initialization vector
| v For a key rule of KEY-CLR, a key identifier containing a 16-byte, 24-byte, or 32-byte clear key. For a
| key rule of KEYIDENT, a fixed-length or variable-length internal AES key-token or the key label of such
| a key in AES key-storage. The key token can contain either a clear or enciphered key.
| A variable-length AES key-token must have a key that can be used for decryption (key-usage field 1
| high-order byte = B'x1xx xxxx'). Also, for processing rule CBC or PKCS-PAD, key usage must allow the
| key to be used for Cipher Block Chaining (KUF2 high-order byte = X'00'). For processing rule ECB, key
| usage must allow the key to be used for Electronic Code Book (KUF2 high-order byte = X'01').
v A block size of 16 for the cryptographic algorithm.
v For cipher block chaining, either one of these:
1. For an ICV selection of INITIAL, a 16-byte initialization vector of your choosing and a 32-byte chain
data buffer
2. For an ICV selection of CONTINUE, no initialization vector and the 32-byte chain data buffer from
the output of the previous chained call (the electronic code book algorithm does not use an
initialization vector or a chain data buffer)
v The cleartext to be enciphered.
v A ciphertext buffer large enough to receive the enciphered output.
This verb does the following when it enciphers the data:

v Verifies the AES key token for keyword KEYIDENT.
v Deciphers the input AES key if the key is encrypted (MKVP was present in token).
| v Pads the cleartext data with 1 - 16 bytes on the right for keyword PKCS-PAD, otherwise verifies that the
| cleartext length is a multiple of the block size and greater than zero.
v Enciphers the cleartext, including any pad characters, with the AES clear key according to the
encryption mode specified.
v Returns the enciphered data and its length.

v Returns the chain data and its length if keyword ECB is not specified.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNBSAE
| key_identifier_length Input Integer 16, 24, 32, or 64
key_parms_length Input Integer 0
key_parms Input String key_parms_length bytes
block_size Input Integer 16
initialization_vector_length Input Integer 0 or 16
initialization_vector Input String initialization_vector_length bytes
chain_data_length In/Output Integer 32
chain_data In/Output String chain_data_length bytes
cleartext_length Input Integer multiple of block_size
cleartext Input String cleartext_length bytes
ciphertext_length In/Output Integer cleartext_length plus pad bytes
ciphertext In/Output String ciphertext_length bytes
optional_data_length Input Integer 0
optional_data Input String optional_data_length bytes
Parameters

rule_array_count
rule_array
characters.
Keyword Meaning
Algorithm identifier (one required)
AES Specifies use of the Advanced Encryption Standard (AES) as the encryption algorithm.
The block size for AES is 16 bytes, and the key length is 16, 24, or 32 bytes. AES is the
only algorithm currently supported by this verb.
Processing rule (one, optional)
CBC Specifies encryption in Cipher Block Chaining mode. The cleartext length must be a
multiple of the block size. This is the default value.
ECB Specifies encryption in Electronic Code Book mode. The cleartext length must be a
multiple of the block size.
PKCS-PAD Specifies padding of the cleartext on the right with 1 to 16 bytes of pad characters,
making the padded text a multiple of the block size. Each pad character is valued to the
number of pad characters added. The ciphertext length must be large enough to include
| the added pad characters. The padded cleartext is enciphered in Cipher Block Chaining
| mode.
Key rule (one, optional)
KEY-CLR Specifies that the key_identifier parameter points to a cleartext AES key. Only the key
value is permitted; the key is not contained in a key token. This is the default value.
KEYIDENT Specifies that the key_identifier parameter points to an internal AES key-token or the
label of an internal key-token in AES key-storage.
ICV selection (one, optional)
INITIAL Specifies that this is either the first request of a sequence of chained requests, or the
only request. The initialization vector is used as input to encipher the first block of data.
The chain data buffer is updated with output that is used as input to subsequent chained
requests. This is the default.
CONTINUE Specifies that the request is part of a sequence of chained requests and is not the first
(initial) request in the sequence. The chain data is used as input to encipher the next
block of data. The chain data buffer is updated with output that is used as input to
subsequent chained requests.
This keyword is not valid with the ECB processing rule keyword.
| of data in the key_identifier variable. This value must be 16, 24, 32, or greater than or equal to 64.
key_identifier
The key_identifier parameter is a pointer to a string variable containing either a cleartext AES key or
the internal key-token or a label for an internal key-token record in AES key-storage. This is the key
used to encipher the data pointed to by the cleartext parameter. For rule-array keyword KEY-CLR, a
16-byte, 24-byte, or 32-byte clear AES key is required. For rule-array keyword KEYIDENT, a
| fixed-length or, beginning with Release 4.2, a variable-length internal AES key-token or key label for
| such a key in AES key-storage is required.

key_parms_length
The key_parms_length parameter is a pointer to an integer variable containing the number of bytes of
data in the key_parms parameter. This value must be 0.
key_parms
The key_parms parameter is a pointer to a string variable for key-related parameters. It is currently
unused.
block_size
The block_size parameter is a pointer to an integer variable containing the block size used by the
cryptographic algorithm. This value must be 16.
initialization_vector_length
| The initialization_vector_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the initialization_vector variable. For Cipher Block Chaining (CBC or PKCS-PAD) with
| an ICV selection of INITIAL, this value must be 16. Otherwise, set this value to 0.
The initialization_vector parameter is a pointer to a string variable containing the initialization vector for
| the INITIAL call to CBC mode encryption. It is not used if the processing rule is ECB or the ICV
| selection is CONTINUE. The same initialization vector must have been used when deciphering the
data.
chain_data_length
The chain_data_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the chain_data variable. On input, set this variable to a value of 32 or greater for CBC mode
| encryption, or 0 for ECB mode encryption.
On output, the variable is updated with the length of the data returned in the chain_data variable. The
chain_data_length parameter must not be changed by the calling application until chained operations
are complete.
chain_data
The chain_data parameter is a pointer to a string variable used as a work area for CBC encipher
requests. This work area is not used for ECB mode encryption.
When the verb performs a CBC encipher operation and the ICV selection is INITIAL, the chain_data
variable is an output-only buffer that receives data used as input for enciphering the next part of the
input data, if any.
When the ICV selection is CONTINUE, the chain_data variable is both an input and output buffer. The
application must not change any intermediate data in this string.
cleartext_length
The cleartext_length parameter is a pointer to an integer variable containing the number of bytes of
data in the cleartext variable. This length must be a multiple of the block_size variable unless
processing rule PKCS-PAD is specified. A value of zero is not permitted.
cleartext
The cleartext parameter is a pointer to a string variable used to contain the data to be enciphered,
excluding any pad bytes.
ciphertext_length
On input, the ciphertext_length parameter is a pointer to an integer variable containing the number of
bytes of data in the ciphertext variable. On output, the ciphertext_length variable is updated to contain
the actual length of text output in the ciphertext variable. If PKCS-PAD is specified, the
ciphertext_length value must be greater than or equal to the next higher multiple of 16 as the
cleartext_length value (from 1 - 16 bytes longer). Otherwise, the ciphertext_length value must be
greater than or equal to the cleartext_length variable.
ciphertext
The ciphertext parameter is a pointer to a string variable used as an output buffer where the verb

returns the enciphered data. If PKCS-PAD is specified, on output the ciphertext buffer contains 1 - 16
bytes of data more than the cleartext input buffer contains.
optional_data_length
| The optional_data_length parameter is a pointer to an integer variable containing the number of bytes
| of data in the optional_data variable. Set this value to 0.
optional_data
The optional_data parameter is a pointer to a string variable containing optional data for the
encryption. It is currently not used.
Required commands
The Symmetric_Algorithm_Encipher verb requires the Encipher Data Using AES command (offset X'012A')

Chapter 7. Key-storage mechanisms
This section describes how you can use key-storage mechanisms and the associated verbs for creating,
writing, reading, listing, and deleting key tokens and key records in AES, DES, and PKA key-storage, or
listing and deleting RSA keys retained within the cryptographic engine. A key-token record consists of a
key-token name (key label) and a null, internal, or external key token. The following table lists the verbs in
this section. See Key-storage verbs on page 391 for detailed information on each verb.
Table 49. Key-storage-record services
Service
AES_Key_Record_Create 392 Creates a null or internal AES key-token CSNBAKRC S
record in AES key-storage.
AES_Key_Record_Delete 394 Deletes an entire record or deletes the key CSNBAKRD S
token from a record in AES key-storage.
AES_Key_Record_List 396 Creates a key-record-list dataset containing CSNBAKRL S
information about specified key records in
AES key-storage.
AES_Key_Record_Read 398 Reads a key token from AES key-storage. CSNBAKRR S
AES_Key_Record_Write 400 Writes an internal AES key-token into AES CSNBAKRW S
key-storage.
DES_Key_Record_Create 402 Creates a null DES key-token record in DES CSNBKRC S
key-storage.
DES_Key_Record_Delete 404 Deletes an entire record or deletes the key CSNBKRD S
token from a record in DES key-storage.
DES_Key_Record_List 406 Creates a key-record-list dataset containing CSNBKRL S
DES key-storage.
DES_Key_Record_Read 408 Reads a key token from DES key-storage. CSNBKRR S
DES_Key_Record_Write 409 Writes an external or internal DES key-token CSNBKRW S
into DES key-storage.
PKA_Key_Record_Create 410 Creates a null, internal, or external PKA (RSA CSNDKRC S
or ECC) key-token record in the PKA
key-storage.
PKA_Key_Record_Delete 412 Deletes an entire record or deletes the key CSNDKRD S
token from a record in PKA key-storage.
PKA_Key_Record_List 414 Creates a key-record-list dataset containing CSNDKRL S
PKA key-storage.
PKA_Key_Record_Read 416 Reads a key token from PKA key-storage. CSNDKRR S
PKA_Key_Record_Write 418 Writes an external (RSA) or internal (PKA or CSNDKRW S
ECC) key-token into PKA key-storage.
Retained_Key_Delete 420 Deletes an RSA key-record retained within the CSNDRKD E
Retained_Key_List 422 Lists the public and private RSA keys retained CSNDRKL E
within the cryptographic engine.
389
Key labels and key-storage management
Use the verbs described in this section to manage AES, DES, and PKA key-storage. The CCA software
manages key storage as an indexed repository of key records. Access key storage using a key label with
verbs that have a key-label or key-identifier parameter.
There are several independent key-storage systems that can be used to manage records for AES key
records, DES key records, and PKA key records:
AES key-storage Holds null and internal AES key tokens
DES key-storage Holds null, internal, and external DES key tokens
PKA key-storage Holds null PKA key tokens, and both internal and external public and
private RSA key tokens. Beginning with Release 4.1, also holds internal
ECC key tokens.
Also, public and private RSA keys can be retained within the coprocessor. Public RSA keys are loaded into
the coprocessor through use of the PKA_Public_Key_Hash_Register and PKA_Public_Key_Register verbs.
Private RSA keys are generated and optionally retained within the coprocessor using the
PKA_Key_Generate verb. Depending on the other uses for coprocessor storage, between 75 and 150
keys can normally be retained within the coprocessor.
A key-storage file must be initialized before any records are created. Prior to storing a key token in key
storage, a key-storage record must be created using the AES_Key_Record_Create,
DES_Key_Record_Create, or PKA_Key_Record_Create verb.
Use the AES_Key_Record_Delete, DES_Key_Record_Delete, or PKA_Key_Record_Delete verb to delete

a key token from a key record, or to entirely delete the key record from key storage.
Use the AES_Key_Record_List, DES_Key_Record_List, or PKA_Key_Record_List verb to determine the

existence of key records in key storage. These list verbs create a key-record-list dataset with information
about select key records. The wildcard character, represented by an asterisk (*), is used to obtain
information about multiple key records. The dataset can be read using conventional workstation-data-
management services.
Individual key tokens can be read using the AES_Key_Record_Read, DES_Key_Record_Read, and
PKA_Key_Record_Read verbs or written using the AES_Key_Record_Write, DES_Key_Record_Write, and
PKA_Key_Record_Write verbs.
Key-label content
Use a key label to identify a record in key storage managed by a CCA implementation. The key label must
be left-aligned in the 64-byte string variable used as input to the verb. Some verbs use a key label while
others use a key identifier. Calls that use a key identifier accept either a key token or a key label.
A key-label character string has the following properties:

v It contains 64 bytes of data.
v The first character is within the range X'20' - X'FE'. If the first character is within this range, the input is
treated as a key label, even if it is otherwise not valid. Inputs beginning with a byte valued in the range
X'00' - X'1F' are considered to be some form of key token. A first byte valued to X'FF' is not valid.
v The first character of the key label cannot be numeric (0 - 9).
v The label is ended by a space character on the right (in ASCII it is X'20', and in EBCDIC it is X'40'). The
remainder of the 64-byte field is padded with space characters.
v Construct a label with 1 - 7 name tokens, each separated by a period (.). The key label must not end
with a period.

v A name token consists of 1 - 8 characters in the character set A - Z, 0 - 9, and 3 additional characters
relating to different character symbols in the various national language character sets as listed below:
ASCII systems EBCDIC systems USA graphic (for reference)

X'23' X'7B' #
X'24' X'5B' $
X'40' X'7C' @
The alphabetic and numeric characters and the period should be encoded in the normal character set
for the computing platform that is in use, either ASCII or EBCDIC.
Notes:
1. Some CCA implementations accept the characters a - z and fold these to their uppercase
equivalents, A - Z. For compatibility reasons, only use the uppercase alphabetic characters.
2. Some implementations internally transform the EBCDIC encoding of a key label to an ASCII string.
Also, the label might be put in tokenized form by dropping the periods and formatting each name
token into 8-byte groups, padded on the right with space characters.
Some verbs accept a key label containing a wildcard represented by an asterisk (*). (X'2A' in ASCII; X'5C'
in EBCDIC). When a verb permits the use of a wildcard, the wildcard can appear as the first character, as
the last character, or as the only character in a name token. Any of the name tokens can contain a
wildcard.
Examples of valid key labels include the following:

A
ABCD.2.3.4.5555
ABCDEFGH
BANKSYS.XXXXX.43*.PDQ
Examples of key labels that are not valid include the following:
Key label not valid Problem with key label

A/.B A slash is an unacceptable character
ABCDEFGH9 Name token is greater than 8 characters
1111111.2.3.4.55555 First character cannot be numeric
A1111111.2.3.4.55555.6.7.8 Number of name tokens exceeds 7
BANKSYS.XXXXX.*43*.D Number of wildcards exceeds 1
A.B. Last character cannot be a period
Key-storage verbs
Chapter 7. Key-storage mechanisms 391

AES_Key_Record_Create (CSNBAKRC)
Use the AES_Key_Record_Create verb to create a key-token record in AES key-storage. The new key
record can be a null AES key-token, or an internal AES key-token. It is identified by the key label specified
with the key_label parameter. Beginning with Release 4,1, the new key record can be a null or internal
variable-length symmetric key-token.
Use any of the following verbs to add or update an existing key token in the record:
v AES_Key_Record_Delete
v AES_Key_Record_Write
v Key_Generate
v Key_Generate2 (Release 4.1 or later)
v Key_Part_Import2 (Release 4.1 or later)
v Key_Token_Change
v Key_Token_Change2 (Release 4.1 or later)
v Key_Translate2 (Release 4.1 or later)
v Restrict_Key_Attribute (Release 4.1 or later)
v Symmetric_Key_Import2 (Release 4.1 or later)
Notes:
1. To delete a key record from AES key-storage, use the AES_Key_Record_Delete verb.
2. AES key-storage records are stored in the external key-storage dataset defined by the CSUAESDS
environment variable.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|

Format
CSNBAKRC
key_label Input String 64 bytes
key_token_length Input Integer 0 or 64
key_token Input String key_token_length bytes
Parameters
rule_array_count
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. This verb
does not use keywords.
key_label
The key_label parameter is a pointer to a string variable containing the key label of the AES
key-record to be created.
key_token_length
The key_token_length parameter is a pointer to an integer variable containing the number of bytes of
data in the key_token variable. If the value of the key_token_length variable is zero, a record with a
null AES key-token is created.
key_token
The key_token parameter is a pointer to a string variable containing the key token being written to
AES key-storage.
Required commands
The AES_Key_Record_Create verb requires the Compute Verification Pattern command (offset X'001D') to

AES_Key_Record_Delete (CSNBAKRD)
Use the AES_Key_Record_Delete verb to do either of the following tasks:
v Overwrite (delete) a key token or key tokens in AES key-storage, replacing the key token of each
selected record with a null AES key-token
v Delete an entire key record or key records, including the key label and the key token of each selected
record, from AES key-storage.
Identify a task with the rule_array keyword, and the key record or records with the key_label parameter. To
identify multiple records, use a wildcard (*) in the key label.
Note: AES key-storage records are stored in the external key-storage dataset defined by the CSUAESDS
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNBAKRD
Parameters
rule_array_count

rule_array
Keyword Meaning
Task (one, optional)
TOKEN-DL Deletes a key token from a key record in AES key-storage, overwriting it with a null AES or
variable-length symmetric key-token. This is the default.
LABEL-DL Deletes an entire key record, including the key label, from AES key-storage.
key_label
The key_label parameter is a pointer to a string variable containing the key label of a key-token record
or records in AES key-storage. Use a wildcard (*) in the key_label variable to identify multiple records
in key storage.
Required commands
The AES_Key_Record_Delete verb requires the Compute Verification Pattern command (offset X'001D') to

AES_Key_Record_List (CSNBAKRL)
Use the AES_Key_Record_List verb to create a key-record-list dataset containing information about
specified key records in AES key-storage. Information listed includes whether record validation is correct,
the type of key, and the date and time each record was created and last updated. Specify the key records
to be listed using the key_label variable. To identify multiple key records, use the wildcard (*) in a key
label.
Notes:
1. To list all the labels in key storage, specify the key_label parameter with *, *.*, *.*.*, and so forth, up
to a maximum of seven name tokens (*.*.*.*.*.*.*).
The verb creates the AES key-record-list dataset and returns the name of the dataset and the length of the
dataset name to the calling application. The verb also returns the name of the security server where the
dataset is stored. This dataset has a header record, followed by 0 to n detail records, where n is the
number of key records with matching key labels. For information about the header and detail records, see
Key-record-list datasets and records on page 637.
AIX and Linux users should refer to the IBM 4764 PCI-X Cryptographic Coprocessor CCA Support
Program Installation Manual for information concerning the location of the AES key-record-list directory.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNBAKRL
dataset_name_length Output Integer 64
dataset_name Output String dataset_name_length bytes
security_server_name Output String 8 bytes

Parameters
rule_array_count
rule_array
currently does not use keywords.
key_label
The key_label parameter is a pointer to a string variable containing a key record or key records in AES
key-storage. Use a wildcard (*) to identify multiple records in key storage.
dataset_name_length
The dataset_name_length parameter is a pointer to an integer variable containing the number of bytes
of data returned by the verb in the dataset_name variable. The maximum returned length is 64 bytes.
dataset_name
The dataset_name parameter is a pointer to a string variable containing the name of the dataset
returned by the verb. The dataset contains the AES key-record information.
Note: The dataset name returned by this verb is defined by the CSUAESLD environment variable.
The verb returns the dataset name as a fully qualified file specification (for example, C:\Program
Files\IBM\4764\KEYS\AESLIST\KYRLTnnn.LST on a Windows system), where nnn is the numeric
portion of the name. This value increases by one every time you use this verb. When this value
reaches 999, it resets to 001.
Note: When the verb stores a key-record-list dataset, it overlays any older dataset with the same
name.
security_server_name
The security_server_name parameter is a pointer to a string variable. The information in this variable
is not currently used, but the variable must be declared.
Required commands
The AES_Key_Record_List verb requires the Compute Verification Pattern command (offset X'001D') to be

AES_Key_Record_Read (CSNBAKRR)
Use the AES_Key_Record_Read verb to read a key-token record from AES key-storage and return a copy
of the key token to application storage. The returned key token can be null. In this event, the key_length
variable contains a value of 64 and the key-token variable contains 64 bytes of X'00' beginning at offset 0.
See Null key tokens on page 578.
Note: AES key-storage records are stored in the external key-storage dataset defined by the CSUAESDS
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNBAKRR
key_token_length In/Output Integer 0 (output) or 64
key_token Output String key_token_length bytes
Parameters
rule_array_count
rule_array

key_label
The key_label parameter is a pointer to a string variable containing the key label of the record to be
read from AES key-storage.
key_token_length
data in the key_token variable. The maximum length is 64.
key_token
The key_token parameter is a pointer to a string variable containing the key token read from AES
key-storage. This variable must be large enough to hold the AES key token being read. On
completion, the key_token_length variable contains the actual length of the token being returned.
Required commands
The AES_Key_Record_Read verb requires the Compute Verification Pattern command (offset X'001D') to

AES_Key_Record_Write (CSNBAKRW)
Use the AES_Key_Record_Write verb to write a copy of an AES key-token from application storage into
AES key-storage. Beginning with Release 4.1, the verb can also write a copy of a variable-length
symmetric key-token from application storage into AES key-storage. The verb can perform the following
processing options:
v Write the new key-token only if the old token was null.
v Write the new key-token regardless of content of the old token.
Notes:
1. Before using the AES_Key_Record_Write verb, use the AES_Key_Record_Create verb to create a
key-token record in AES key-storage.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNBAKRW
key_token_length Input Integer 64
Parameters
rule_array_count

rule_array
characters.
Keyword Meaning
Processing option (one, optional)
CHECK Specifies that the record is written only if a record of the same label in AES key-storage
contains a null key-token. This is the default.
OVERLAY Specifies that the record is overwritten regardless of the current content of the record in AES
key-storage.
key_label
The key_label parameter is a pointer to a string variable containing the key label that identifies the
record in AES key-storage where the key token is to be written.
key_token_length
data in the key_token variable. This value must be 64.
key_token
The key_token parameter is a pointer to a string variable containing the AES or variable-length
symmetric key-token to be written into AES key-storage.
Required commands
The AES_Key_Record_Write verb requires the Compute Verification Pattern command (offset X'001D') to

DES_Key_Record_Create (CSNBKRC)
Use the DES_Key_Record_Create verb to create a key-token record with a null DES key-token to DES
key-storage. It is identified by the key label specified with the key_label parameter.
Note: DES key-storage records are stored in the external key-storage dataset defined by the CSUDESDS
After creating a DES key-record, any of the following verbs update a key token in the record:
v Clear_Key_Import
v DES_Key_Record_Delete
v DES_Key_Record_Write
v Data_Key_Import
v Diversified_Key_Generate
v Key_Generate
v Key_Import
v Key_Part_Import
v Key_Token_Change
v Remote_Key_Export
To delete a key record from DES key-storage, use the DES_Key_Record_Delete verb.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBKRC
Parameters

key_label
The key_label parameter is a pointer to a string variable containing the key label of the key record to
be created in DES key-storage.
Required commands
The DES_Key_Record_Create verb requires the Compute Verification Pattern command (offset X'001D') to

DES_Key_Record_Delete (CSNBKRD)
Use the DES_Key_Record_Delete verb to do either of the following tasks:
v Overwrite (delete) a key token or key tokens in DES key-storage, replacing the key token of each
selected record with a null key-token.
record, from DES key-storage.
Identify a task with the rule_array keyword, and the key record or records with the key_label parameter. To
identify multiple records, use a wildcard (*) in the key label.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBKRD
Parameters
rule_array_count
rule_array
keywords are eight bytes in length and must be left-aligned and padded on the right with space

Keyword Meaning
Task (one required)
TOKEN-DL Deletes a key token from a key record in DES key-storage, overwriting it with a null DES
key-token.
LABEL-DL Deletes an entire key record, including the key label, from DES key-storage.
key_label
or records in DES key-storage. Use a wildcard (*) in the key_label variable to identify multiple records
in key storage.
Required commands
The DES_Key_Record_Delete verb requires the Compute Verification Pattern command (offset X'001D') to

DES_Key_Record_List (CSNBKRL)
Use the DES_Key_Record_List verb to create a key-record-list dataset containing information about
specified key records in DES key-storage. Information listed includes whether record validation is correct,
the type of key, and the date and time each record was created and last updated.
Specify the key records to be listed using the key_label variable. To identify multiple key records, use the
wildcard (*) in the key label.
Notes:
2. DES key-storage records are stored in the external key-storage dataset defined by the CSUDESDS
The verb creates the DES key-record-list dataset and returns the name of the dataset and the length of
the dataset name to the calling application. This dataset has a header record, followed by 0 to n detail
records, where n is the number of key records with matching key labels. For information about the header
and detail records, see Key-record-list datasets and records on page 637.
Program Installation Manual for information concerning the location of the DES key-record-list directory.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBKRL

Parameters
key_label
in DES key-storage. In a key label, you can use a wildcard (*) to identify multiple records in key
storage.
dataset_name_length
of data returned by the verb in the dataset_name variable. The maximum returned length is 64 bytes.
dataset_name
The dataset_name parameter is a pointer to a 64-byte string variable containing the name of the
dataset returned by the verb. The dataset contains the DES key-record information.
Note: The dataset name returned by this verb is defined by the CSUDESLD environment variable.
Files\IBM\4764\KEYS\DESLIST\KYRLTnnn.LST on a Windows system), where nnn is the numeric
portion of the name. This value increases by one every time you use this verb. When this value
reaches 999, it resets to 001.
name.
Required commands
The DES_Key_Record_List verb requires the Compute Verification Pattern command (offset X'001D') to be

DES_Key_Record_Read (CSNBKRR)
Use the DES_Key_Record_Read verb to read a key-token record from DES key-storage and return a copy
of the key token to application storage. The returned key token can be null (64 bytes of X'00').
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBKRR
key_token Output String 64 bytes
Parameters
key_label
The key_label parameter is a pointer to a string variable containing the key label of the key-token
record to be read from DES key-storage.
key_token
The key_token parameter is a pointer to a string variable containing a copy of the key-token record to
be read from DES key-storage.
Required commands
The DES_Key_Record_Read verb requires the Compute Verification Pattern command (offset X'001D') to

DES_Key_Record_Write (CSNBKRW)
Use the DES_Key_Record_Write verb to write a copy of an internal or external DES key-token from
application storage into DES key-storage.
Notes:
1. Before using the DES_Key_Record_Write verb, use the DES_Key_Record_Create verb to create a null
key-token record in DES key-storage.
2. DES key-storage records are stored in the external key-storage dataset defined by the CSUDESDS
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNBKRW
key_token Input String 64 bytes
Parameters
key_token
The key_token parameter is a pointer to a string variable containing the internal key-token to be
written into DES key storage.
key_label
The key_label parameter is a pointer to a string variable containing the key label that identifies the
record in DES key storage where the key token is to be written.
Required commands
The DES_Key_Record_Write verb requires the Compute Verification Pattern command (offset X'001D') to

PKA_Key_Record_Create (CSNDKRC)
Use the PKA_Key_Record_Create verb to create a key-token record in PKA key-storage. The new key
record can be a null PKA key-token or an internal or external PKA key-token. Beginning with Release 4,1,
the new key record can also be an internal ECC key-token. It is identified by the key label specified with
the key_label parameter.
After creating a PKA key-record, use any of the following verbs to add or update a key token in the record:
v PKA_Key_Import
v PKA_Key_Generate
v PKA_Key_Record_Delete
v PKA_Key_Record_Write
v PKA_Key_Token_Change
Notes:
1. To delete a key record from PKA key-storage, use the PKA_Key_Record_Delete verb.
2. PKA key-storage records are stored in the external key-storage dataset defined by the CSUPKADS
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v ECC key tokens are not supported in releases before Release 4.1.
Format
CSNDKRC
Parameters

rule_array_count
rule_array
does not use keywords.
key_label
The key_label parameter is a pointer to a string variable containing the key label of the PKA
key-record to be created.
key_token_length
data in the key_token variable. If the value of the key_token_length variable is zero, a record with a
null PKA key-token is created.
key_token
The key_token parameter is a pointer to a string variable containing the key token being written to
PKA key-storage.
Required commands
The PKA_Key_Record_Create verb requires the Compute Verification Pattern command (offset X'001D') to

PKA_Key_Record_Delete (CSNDKRD)
Use the PKA_Key_Record_Delete verb to do either of the following tasks:
v Overwrite (delete) a key token or key tokens in PKA key-storage, replacing the key token of each
selected record with a null PKA key-token.
record, from PKA key-storage.
Identify the task with the rule_array keyword, and the key record or key records with the key_label
parameter. To identify multiple records, use a wildcard (*) in the key label.
Note: PKA key-storage records are stored in the external key-storage dataset defined by the CSUPKADS
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNDKRD
Parameters
rule_array_count

rule_array
Keyword Meaning
Task (one, optional)
TOKEN-DL Deletes a key token from a key record in PKA key-storage, overwriting it with a null PKA
key-token. This is the default.
LABEL-DL Deletes an entire key record, including the key label, from PKA key-storage.
key_label
or records in PKA key-storage. Use a wildcard (*) in the key_label variable to identify multiple records
in key storage.
Required commands
The PKA_Key_Record_Delete verb requires the Compute Verification Pattern command (offset X'001D') to

PKA_Key_Record_List (CSNDKRL)
Use the PKA_Key_Record_List verb to create a key-record-list dataset containing information about
specified key records in PKA key-storage. Information listed includes whether record validation is correct,
the type of key, and the date and time each record was created and last updated.
Specify the key records to be listed using the key_label variable. To identify multiple key records, use the
wildcard (*) in a key label.
Notes:
The verb creates the PKA key-record-list dataset and returns the name of the dataset and the length of the
dataset name to the calling application. The verb also returns the name of the security server where the
dataset is stored. This dataset has a header record, followed by 0 to n detail records, where n is the
number of key records with matching key labels. For information about the header and detail records, see
Key-record-list datasets and records on page 637.
Program Installation Manual for information concerning the location of the PKA key-record-list directory.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNDKRL

Parameters
rule_array_count
rule_array
key_label
The key_label parameter is a pointer to a string variable containing a key record or key records in
PKA key-storage. Use a wildcard (*) to identify multiple records in key storage.
dataset_name_length
of data returned in the dataset_name variable. The maximum returned length is 64 bytes.
dataset_name
The dataset_name parameter is a pointer to a string variable containing the name of the dataset
returned by the verb. The dataset contains the PKA key-record information.
Note: The dataset name returned by this verb is defined by the CSUPKALD environment variable.
Files\IBM\4764\KEYS\PKALIST\KYRLTnnn.LST on a Windows system), where nnn is the numeric
portion of the name. This value increases by one every time you use this verb. When it reaches 999,
the value is reset to 001.
name.
Required commands
The PKA_Key_Record_List verb requires the Compute Verification Pattern command (offset X'001D') to be

PKA_Key_Record_Read (CSNDKRR)
Use the PKA_Key_Record_Read verb to read a key-token record from PKA key-storage and return a copy
of the key token to application storage.
The returned key token can be null. In this event, the key_length variable contains a value of 8 and the
key-token variable contains 8 bytes of X'00' beginning at offset 0 (see Null key tokens on page 578).
Note: PKA key-storage records are stored in the external key-storage dataset defined by the CSUPKADS
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNDKRR
key_token_length In/Output Integer 3500
key_token Output String key_token_length bytes
Parameters
rule_array_count
rule_array

key_label
The key_label parameter is a pointer to a string variable containing the key label of the record to be
read from PKA key-storage.
key_token_length
data in the key_token variable. The maximum length is 3500 bytes.
key_token
The key_token parameter is a pointer to a string variable containing the key token read from PKA
key-storage. This variable must be large enough to hold the PKA key token being read. On successful
completion, the key_token_length variable contains the actual length of the token being returned.
Required commands
The PKA_Key_Record_Read verb requires the Compute Verification Pattern command (offset X'001D') to

PKA_Key_Record_Write (CSNDKRW)
Use the PKA_Key_Record_Write verb to write a copy of an RSA key-token or, beginning with Release 4,1,
an ECC key-token, from application storage into PKA key-storage.
The verb can perform the following processing options:

v Write the new key-token only if the old token was null
v Write the new key-token regardless of content of the old token
Notes:
1. Before using the PKA_Key_Record_Write verb, use the PKA_Key_Record_Create verb to create a
key-token record in PKA key-storage.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNDKRW
Parameters
rule_array_count

rule_array
Keyword Meaning
Processing option (one, optional)
CHECK Specifies that the record is written only if a record of the same label in PKA key-storage
contains a null key-token. This is the default.
OVERLAY Specifies that the record is overwritten regardless of the current content of the record in PKA
key-storage.
key_label
The key_label parameter is a pointer to a string variable containing the key label that identifies the key
record in PKA key-storage where the key token is to be written.
key_token_length
data in the key_token variable. The maximum length is 3500 bytes.
key_token
The key_token parameter is a pointer to a string variable containing the RSA or ECC key-token to be
written into PKA key-storage.
Required commands
The PKA_Key_Record_Write verb requires the Compute Verification Pattern command (offset X'001D') to

Retained_Key_Delete (CSNDRKD)
Use the Retained_Key_Delete verb to delete a PKA key-record currently retained within the cryptographic
engine.
Both public and private keys can be retained within the cryptographic engine using verbs such as
PKA_Key_Generate and PKA_Public_Key_Register. A list of retained keys can be obtained using the
Retained_Key_List verb.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNDRKD
rule_array Input String array rule_array_count * 8 bytes or null pointer
Parameters
rule_array_count
rule_array
The rule_array parameter should be a null address pointer.
key_label
The key_label parameter is a pointer to a string variable containing the key label of a PKA key-record
that has been retained within the cryptographic engine. The use of a wildcard in the key_label variable
is not permitted.

Required commands
The Retained_Key_Delete verb requires the Delete Retained Key command (offset X'0203') to be enabled
in the active role.

Retained_Key_List (CSNDRKL)
Use the Retained_Key_List verb to list the key labels of selected PKA key records that have been retained
within the cryptographic engine.
Specify the keys to be listed using the key_label_mask variable. To identify multiple keys, use a wildcard
(*) in the mask. Only labels with matching characters to those in the mask up to the first * is returned. To
list all retained key labels, specify a mask of an *, followed by 63 space characters. For example, if the
cryptographic engine has retained key labels a.a, a.a1, a.b.c.d, and z.a, and you specify the mask a.*, the
verb returns a.a, a.a1 and a.b.c.d. If you specify a mask of a.a*, the verb returns a.a and a.a1.
To retain PKA keys within the coprocessor, use the PKA_Key_Generate and the
PKA_Public_Key_Register verbs. To delete retained keys from the coprocessor, use the
Retained_Key_Delete verb.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| Format
CSNDRKL
key_label_mask Input String 64 bytes or null pointer
retained_keys_count In/Output Integer
key_labels_count In/Output Integer
key_labels Output String array key_labels_count * 64 bytes
Parameters
rule_array_count
in the rule_array variable. The value currently must be 0.

rule_array
The rule_array parameter should be a null address pointer.
key_label_mask
The key_label_mask parameter is a pointer to a string variable containing a key-label mask that is
used to filter the list of key names returned by the verb. Use a wildcard (*) to identify multiple key
records retained within the coprocessor.
retained_keys_count
The retained_keys_count parameter is a pointer to an integer variable to receive the total number of
retained-key records stored within the coprocessor.
key_labels_count
The key_labels_count parameter is a pointer to an integer variable which on input defines the
maximum number of key labels to be returned, and which on output defines the number of key labels
returned by the coprocessor.
key_labels
The key_labels parameter is a pointer to a string array variable containing the returned key labels. The
coprocessor returns zero or more 64-byte array elements, each of which contains the key label of a
PKA key-record retained within the coprocessor.
Required commands
The Retained_Key_List verb requires the List Retained Key command (offset X'0230') to be enabled in the
active role.

Chapter 8. Financial services support
Several classes of verbs are described in this section:
v Verbs that process finance industry PINs.
v Verbs that can change the acceptable PIN on a smart card based on Visa and EMV design concepts.
v SET-related verbs that support cryptographic operations as defined in the Secure Electronic Transaction
(SET) protocol as defined by Visa International and MasterCard**; see their Web pages for a reference
to the SET protocol.
v Transaction validation verbs that compute and validate codes for MasterCard, Visa, and American
Express.
Table 50 lists the verbs described in this section. See Financial services support verbs on page 437 for a
detailed description of each verb.
Table 50. Financial services support verbs
Service
Clear_PIN_Encrypt 438 Formats a PIN into a PIN block and produces CSNBCPE E
the PIN block as an encrypted quantity.
The keyword RANDOM represents an

extension to the support available with other
CCA implementations to generate random
PINs that are produced in encrypted PIN
blocks.
Clear_PIN_Generate 441 Generates a clear PIN, or a PIN offset. CSNBPGN E
Clear_PIN_Generate_Alternate 444 Extracts a customer-selected PIN or CSNBCPA E
institution-assigned PIN from an encrypted
PIN-block and generates a PIN offset.
CVV_Generate 449 Generates a card-verification value according CSNBCSG E
to the Visa CVV and MasterCard CVC rules
for track 2.
| CVV_Key_Combine 452 Combines two operational single-length CSNBCKC E
| MAC-capable DES keys (key-A and key-B)
| into one operational double-length TDES key
| with key attribute CVVKEY-A.
CVV_Verify 456 Verifies a card-verification value according to CSNBCSV E
the Visa CVV and MasterCard CVC rules for
track 2.
Encrypted_PIN_Generate 459 Generates a PIN from an account number CSNBEPG E
and other information and returns the result
in an encrypted PIN-block.
Encrypted_PIN_Translate 463 Operates in two modes: CSNBPTR E
v Translate mode reencrypts a PIN block
under a different key.
v Reformat mode can do the following:
Reformats a PIN from one PIN-block
format into another PIN-block format
Changes selected non-PIN digits in a
PIN block
Reencrypts a PIN block
Encrypted_PIN_Verify 469 Extracts and verifies a PIN by using the CSNBPVR E
specified PIN-calculation method.
PIN_Change/Unblock 475 Calculates a PIN for a smart card based on CSNBPCU E
keys and data you supply according to Visa
and EMV specifications.
425
Table 50. Financial services support verbs (continued)
Service
Secure_Messaging_for_Keys 481 Securely incorporates a key into a text block CSNBSKY E
that is then encrypted (for use with EMV
smart cards).
Secure_Messaging_for_PINs 484 Securely incorporates a PIN block into a text CSNBSPN E
block that is then encrypted (for use with
EMV smart cards).
SET_Block_Compose 489 Creates a SET-protocol RSA-OAEP block CSNDSBC E
that DES encrypts.
SET_Block_Decompose 492 Decomposes the RSA-OAEP block that DES CSNDSBD E
decrypts.
Transaction_Validation 496 Generates and verifies American Express CSNBTRV E
Card Security Codes (CSC).
E=cryptographic engine
Processing financial PINs

This section describes how the financial personal identification number (PIN) verbs are used to process
financial PINs.
Note: In this section, automated teller machine (ATM) can also mean a point-of-sale device, an enhanced
teller terminal, or a programmable workstation.
A financial PIN is used to authorize personal financial transactions for a customer who uses an automated
teller machine or point-of-sale device. A financial PIN is similar to a password except that a financial PIN
consists of decimal digits and is normally a cryptographic function of an associated account number. With
the financial PIN verbs you can specify PINs that range from 4 16 digits in length. (A financial PIN is
usually 4 digits in length.)
The financial PIN verbs form a complete set of verbs that you can use in various combinations to process
financial PINs. The verb relationships and primary inputs and outputs are depicted in Figure 23 on page
428. You use these verbs for the following tasks:
v Provide security for the PINs by using encrypted PIN-blocks with these capabilities:
Encryption of a clear PIN in various PIN-block formats
Generation of random PIN values and encryption of these in various PIN-block formats
Verification of a PIN. The PIN block is decrypted as part of the verification service.
Reencrypting a PIN-block under another key with optional, integral changing of the PIN-block format
v Use multiple PIN calculation methods
v Use multiple PIN block formats and PIN extraction methods
v Use ANS X9.24 derived unique-key-per-transaction (UKPT) PIN-block encryption
v Provide the following services:
Create encrypted PIN blocks for transmission
Generate institution-assigned PINs
Generate an offset or a Visa PIN-validation value (PVV)
Create encrypted PIN blocks for a PIN-verification database
Change the PIN-block encrypting key or the PIN-block format
Verify PINs
Normally, a customer inserts a magnetic-stripe card and enters a trial PIN into an ATM to identify himself.
The ATM does the following:
1. Obtains account information and other information from the magnetic stripe on the card.

2. Formats the trial PIN into a PIN block and encrypts the PIN block.
3. Sends the information from the card, the encrypted PIN block, and other data in a message to a host
program for verification. In some applications, a program in the machine can use a verb to verify a
clear PIN locally.
To verify a PIN, a program normally uses one of the following two methods:
v PIN-calculation method. In this method, the program calls the PIN verification verb that decrypts the trial
PIN block, extracts the trial PIN from the PIN block, recalculates the account-number-based PIN,
adjusts this value with any offset, compares the resulting value to the trial PIN, and returns the result of
the comparison.
v PIN-database method. In this method, the encrypted PIN-block that contains the correct customer-PIN is
stored in a PIN-verification database. Upon receipt of an encrypted trial-PIN block, the program calls a
verb to translate (decipher, then encipher) the trial PIN block to the format and key used for the
encrypted PIN-block in the PIN-verification database. The two encrypted PIN-blocks can then be
compared for equality.
In general, a PIN can be assigned by an institution or selected by a customer. Some PIN calculation
methods use the institution-assigned or customer-selected PIN to calculate another value that is stored on
the magnetic stripe of the account-holder's card or in a database and that is used in the PIN-verification
process.
Chapter 8. Financial services support 427

Account CustomerEntered PIN CustomerSelected PIN
Number
TPIN
Clear
CPIN
PINGEN
Clear_PIN_Generate
Account
Number
CSNBPGN

PINGEN
Clear_PIN_Generate
APIN (Offsetgeneration Mode)

CSNBPGN
Account
Number Clear PIN
OPIN

PINGEN
Encrypted_PIN_Generate OPINENC
Clear_PIN_Encrypt

(Also RANDOM PIN
OPINENC
CSNBEPG generate option) CSNBCPE

APIN

Encrypted Encrypted
PIN_Block PIN_Block
(Typically CPIN)

Account
Number

IPINENC
or
Encrypted_PIN_Translate IPINENC
Clear_PIN_Generate
KEYGENKY _Alternate
w/CKSN

OPINENC
or
CSNBPTR PINGEN
CSNBCPA
KEYGENKY
w/CKSN
Encrypted OPIN
PIN_Block

Account
Number TPIN

IPINENC
or
Encrypted_PIN_Verify
KEYGENKY
w/CKSN

PINVER
CSNBPVR

Y/N
Note: See PIN-verb summary on page 429.
Figure 23. Financial PIN verbs

PIN-verb summary
The following terms are used for the various PIN values:
A-PIN The quantity derived from a function of the account number and PIN-generating key, and other
inputs such as a decimalization table.
C-PIN The quantity that a customer should use to identify himself. In general, this can be a
customer-selected or institution-assigned quantity.
O-PIN A quantity, sometimes called an offset, that relates the A-PIN to the C-PIN as permitted by certain
PIN calculation methods.
T-PIN The trial PIN presented for verification.
The Clear_PIN_Generate verb uses a PIN-generating key and an account number to create an A-PIN
according to the PIN-calculation method selected through a rule-array keyword. See PIN calculation
methods on page 697. Certain calculation methods also accept a C-PIN value and return an O-PIN
calculated from the coprocessor-generated A-PIN value.
The Encrypted_PIN_Generate verb uses a PIN-generating key and an account number to create an A-PIN
according to the PIN-calculation method selected through a rule-array keyword. The verb formats the
A-PIN value into a PIN block as specified in the input control information. The PIN block is returned
encrypted by the supplied OPINENC-type key.
The Clear_PIN_Encrypt verb accepts a clear PIN value and formats the input into a PIN block. The result
is encrypted and returned. This verb can also randomly generate PIN values and return these as
encrypted PIN blocks. This function is useful when an institution wants to distribute initial PIN values to
customers.
The Clear_PIN_Generate_Alternate verb accepts an encrypted PIN block that contains a

customer-selected C-PIN value. The verb calculates the A-PIN from the account number and
PIN-generating key and then derives the O-PIN as a function of the A-PIN and the C-PIN. The O-PIN is
returned in the clear.
The Encrypted_PIN_Verify verb accepts an account number and PIN-verifying or PIN-generating key to
internally produce an A-PIN. For certain methods, the verb also accepts an O-PIN so that it can produce
the correct value that a customer must enter to access his account. The final input, an encrypted T-PIN
block, is decrypted, the customer-entered trial PIN is extracted from the block and compared to the
calculated value; equality is indicated by the return code (and reason code) values. Return code 0
indicates the PIN is validated while return code 4 indicates that the trial PIN failed validation.
The Encrypted_PIN_Translate verb is used to change the key used later to decrypt or compare the PIN
block. The verb can also extract the PIN from one PIN-block format and insert the PIN into another
PIN-block format before reencryption. This service is useful when transferring PIN blocks from one domain
to another.

PIN-calculation method and PIN-block format summary
As described in the following sections, you can use a variety of PIN calculation methods (UKPT, IBM-PIN,
IBM-PINO, GBP-PIN, INBK-PIN, NL-PIN-1, VISA-PVV) and a variety of PIN-block formats (3624, ISO-0,
ISO-1, ISO-2, ISO-3, VISAPCU1, VISAPCU2) with the various PIN-processing verbs. Table 51 provides a
summary of the supported combinations.
Table 51. PIN verb, PIN-calculation method, and PIN-block format support summary
Verb / PIN-calculation Entry IBM- IBM- GBP- INBK- NL- VISA- ISO-0 VISA- VISA-
method, PIN block point UKPT PIN PINO PIN PIN PIN-1 PVV 3624 ISO-1 ISO-2 ISO-3 PCU1 PCU2
Clear_PIN_Encrypt CSNBCPE X X X X
Clear_PIN_Generate CSNBPGN X X
Clear_PIN_Generate_Alternate CSNBCPA X X X X X X
Encrypted_PIN_Generate CSNBEPG X X X X X X X
Encrypted_PIN_Translate CSNBPTR X X X X X
| Encrypted_PIN_Verify CSNBPVR X X X X X X X X X X X
PIN_Change/Unblock CSNBPCU X X X X X X
Secure_Messaging_for_PINs CSNBSPN X
Note: The ISO-3 PIN-block format is not supported in releases before Release 3.30.
Providing security for PINs

It is important to maintain the security of PINs. Unauthorized knowledge of a PIN and its associated
account number can result in fraudulent transactions. One method of maintaining the security of a PIN is
to store the PIN in a PIN block, encrypt the PIN block, and only send or store a PIN in this form. A PIN
block is 64 bits in length, which is the length of data on which the DES algorithm operates. A PIN block
consists of both PIN digits and non-PIN digits. The non-PIN digits pad the PIN digits to a length of 64 bits.
When discussing PINs, the term digit refers to a 4-bit quantity that can be valued to the decimal values 0 -
9 and in some cases also to the hexadecimal values A - F. Several different PIN-block formats are
supported. See PIN-block formats on page 700.
The non-PIN digits can also add variability to a PIN block. Varying the value of the non-PIN digits in a PIN
block is a security measure used to create a large number of different encrypted PIN-blocks, even though
there are typically only 10 000 PIN values in use. To enhance the security of a clear PIN during PIN
processing, the verbs generally operate with encrypted PIN-blocks. The PIN verbs provide high-level
services that typically insert or extract PIN values to or from a PIN block.
The following verbs receive clear PINs from your application program or return clear PINs to your program.
None of the other PIN verbs reveals a clear PIN.
v Clear_PIN_Generate
v Clear_PIN_Encrypt
When your application program supplies a clear PIN to a verb or receives a clear PIN from a verb, ensure
that adequate access controls and auditing are provided to protect this sensitive data. Also recognize that
exhaustive use of certain verbs such as Encrypted_PIN_Verify and Clear_PIN_Generate_Alternate can
reveal the value of a PIN. Therefore, if production level keys are available in a system, be sure that you
have usage controls and auditing in effect to detect inappropriate usage of these verbs.
Using specific key types and key-usage bits to help ensure PIN security
The control vectors that are associated with obtaining and verifying PINs enable you to minimize certain
security exposures. The class of keys designated PINGEN operates in the verbs that create and validate
PIN values, whereas the PINVER class operates only in those verbs that validate a PIN. Reduce your
exposure to fraud by limiting the availability of the PINGEN keys to those applications and times when it is
legitimate to create new PIN values. Use the PINVER key class to validate PINs. You can also further

restrict those verbs in which a PINGEN key performs by selectively turning off bits in the default PINGEN
control vector. See Appendix C, CCA control-vector definitions and key encryption, on page 655.
Those verbs that encrypt a PIN block require the encrypting key to be of the class OPINENC, output
PIN-block encrypting key. Those verbs that decrypt a PIN block require the encrypting key to be of the
class IPINENC, input PIN-block encrypting key. The actual input and output key values are the same, but
the use of two different types of control vectors aids in defeating certain insider attacks that might enable
redirection of encrypted PIN values to an unintended service to the attacker's benefit. You can also turn off
selected bits in the default OPINENC and IPINENC control vectors to limit those verbs in which a given
key can operate to further reduce exposure to insider fraud.
Point-of-sale terminals that accept a customer's PIN often use the UKPT mechanism specified in ANS
X9.24 to ensure that tampering with the device does not reveal keys used to encrypt previous PIN
encryptions. With the Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs, you can process PIN
blocks encrypted according to ANS X9.24. In these cases you supply the base key and a current-key
serial number (CKSN). The verb derives the appropriate key to decrypt or encrypt the PIN block when a
Single-DES method is specified. If a Triple-DES method is specified, it employs the algorithm specified in
ANS X9.52.
The PIN verbs use these key types:

PINGEN (PIN-generating) key type
The PIN verbs that generate and verify a PIN require the PIN-generating key to have a control
vector that specifies a PINGEN key-type.
The Encrypted_PIN_Verify verb can use a key with a PINGEN key type if control-vector bit 22 is
set to B'1' to specify that the key can be used to verify a PIN.
PINVER (PIN-verifying) key type
The Encrypted_PIN_Verify verb, which verifies an encrypted PIN by using the PIN-calculation
method, requires the PIN-generating key to have a control vector that specifies the PINVER key
type, or a control vector that specifies the PINGEN key type and has bit 22 set to B'1'. The
PINVER key-type cannot be used to create a PIN value, and therefore is the preferred key type in
a system that only needs to validate PINs.
IPINENC (inbound PIN-block encrypting) key type
The PIN verbs that decrypt a PIN block require the decrypting key to have a control vector that
specifies an IPINENC key type.
OPINENC (outbound PIN-block encrypting) key type
The PIN verbs that encrypt a PIN block require the encrypting key to have a control vector that
specifies an OPINENC key type.
KEYGENKY (UKPT base key-generating key) key type
The Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs can derive a unique key from the
KEYGENKY derivation key and CKSN to decrypt or encrypt a PIN block.
Supporting multiple PIN calculation methods

With the PIN verbs you can use multiple PIN calculation methods. Use the data_array variable to supply
information that a PIN-calculation method requires.
PIN calculation methods

A PIN calculation method determines the value of an A-PIN in relation to an account number. The methods
are described in PIN calculation methods on page 697. The PIN verbs can use the following PIN
calculation methods, which you specify with a keyword in the rule_array variable for a verb:

Table 52. PIN calculation methods and keywords
PIN calculation method Keyword
IBM German Bank Pool PIN GBP-PIN
IBM 3624 PIN IBM-PIN
IBM 3624 PIN offset IBM-PINO
InterBank PIN INBK-PIN
Netherlands PIN-1 NL-PIN-1
Visa PIN-validation value (PVV) VISA-PVV
Note: The Clear_PIN_Generate_Alternate (CSNBCPA) verb always outputs four digits rather than padding
the output with binary zeros to the length of the PIN when the Visa PVV PIN-calculation method is
used.
PIN verb data_array variable

To obtain the information that a PIN-calculation method requires, the PIN verbs use a data_array variable.
Depending on the PIN-calculation method and the verb, the elements in the data_array variable can
include a decimalization table, account validation data, an offset or clear PIN, or transaction security data.
The data array is a 48-byte string made up of three consecutive 16-byte character strings. Each element
must be 16 bytes in length, uppercase, left-aligned, and padded on the right with space characters. Some
PIN calculation methods and verbs do not use all three elements. However, all three elements must be
declared.
Data array with IBM-PIN, IBM-PINO, NL-PIN-1, and GBP-PIN: When using the IBM-PIN, the IBM-PINO,
the NL-PIN-1, and GBP-PIN methods, the data array contains elements for a decimalization table and
validation data. For some verbs, it also includes a clear PIN or an offset to a clear PIN.
v decimalization_table
The first element in the data array for a PIN-calculation method provides the decimalization table, which
is 16 characters. The characters are used to map the hexadecimal digits (X'0' to X'F') of the encrypted
validation data to decimal digits (X'0' - X'9').
Notes:
1. To avoid errors when using the IBM 3624 PIN-block format, do not include a decimal digit that is
also used as a pad digit in the decimalization table. For information about using a pad digit, see
PIN profile on page 433.
| 2. Use a decimalization table of 0123456789012345 for NL-PIN-1.
v validation_data
The second element in the data array for a PIN-calculation method provides from 1 - 16 characters of
account data, which can be the customers account number or other identifying number. If necessary,
the application program must left-align the validation data and pad on the right with space characters to
a length of 16 bytes. While normally the validation data consists of numeric-decimal characters, the
Clear_PIN_Generate_Alternate, Encrypted_PIN_Generate, and Encrypted_PIN_Verify verbs have been
updated to accept any hexadecimal character (0 - 9, A - F).
v clear_PIN, offset_data, or reserved
The third element in the data array provides an O-PIN value. If an O-PIN is not used in the verb or
method, then this should be 16 space characters.
Data array with the Visa PVV PIN-calculation method: When using the Visa PVV PIN-calculation
method, the data array consists of the transaction_security_parameter, the PVV, and one reserved
element.
v transaction_security_parameter

The first element in the data array for the Visa PVV PIN-calculation method provides transaction
security data. Specify 16 characters that include the following:
Eleven (rightmost) digits of personal account number (PAN) data, excluding the check digit. For
information about a PAN, see Personal account number on page 436.
A one-digit key index selector value from 1 - 6.
Four space characters.
v referenced PVV
When using the Encrypted_PIN_Verify verb, the second element in the data array for the Visa PVV
PIN-calculation method contains 4 numeric characters, which are the PVV value for the account and
derived from a customer-selected PIN value. This value is followed by 12 space characters.
v reserved
The second element (when not using the Encrypted_PIN_Verify verb) or the third element in the data
array for the Visa PVV PIN-calculation method is reserved. This element is a 16-byte variable in
application storage. The information in this element is ignored, but must be declared.
Data array for the InterBank PIN-calculation method: When using the InterBank PIN-calculation
method with certain verbs, the data array consists of one element, the transaction_security_parameter, for
transaction security data. The other two elements are reserved.
v transaction_security_parameter
The first element in the data array for the InterBank PIN-calculation method provides
transaction-security data. Specify 16 numeric characters that include the following:
Eleven (rightmost) digits of PAN data, excluding the check digit. For information about a PAN, see
Personal account number on page 436.
A constant, 6.
A one-digit key index selector value from 1 6.
Three numeric characters of validation data.
v reserved
The second and third elements in the data array for the InterBank PIN-calculation method are reserved.
These two elements each point to a 16-byte variable in application storage. The information in these
elements is ignored, but the elements must be declared.
Supporting multiple PIN-block formats and PIN-extraction methods

The PIN verbs use multiple PIN-block formats, which you specify in a PIN_profile variable. The PIN-block
formats are described in PIN-block formats on page 700. Multiple methods for extracting the PIN value
from the PIN block exist for certain PIN-block formats. Depending on the PIN-block format, the verbs also
require a pad digit, a personal account number (PAN), or a sequence number.
When deriving the unique key according to the ANS X9.24 UKPT process, the verbs also require you to
supply the CKSN. The CKSN is supplied as an extension of the PIN profile.
PIN profile
A PIN_profile variable normally consists of three basic elements. It sometimes includes a fourth 24-byte
CKSN extension. The three basic elements identify the PIN-block format, the level of format control, and
any pad digit. Generally, you can code the basic PIN_profile variable as a constant in your application.
Each element is an 8-byte character string in an array, which is the equivalent of a single 24-byte string
that is organized as three 8-byte fields. The elements must be 8 bytes in length, uppercase, and,
depending on the element, either left-aligned or right-aligned and padded with space characters.
Depending on the verb and the PIN-block format, all three elements might not be used. However, all three
elements (that is, all 24 bytes) must be declared.
PIN-block format: The PIN-block format is the first element in a PIN_profile variable. Specify the format
using one of these keywords, left-aligned and padded on the right with space characters:

Table 53. PIN-block format
PIN-block format Keyword
IBM 3624 3624
ISO-0 (same as ANS X9.8, VISA-1, and ECI-1) ISO-0
ISO-1 (same as ECI-4) ISO-1
ISO-2 ISO-2
ISO-3 ISO-3
EMV-PIN-change VISAPCU1
VISAPCU2
Format control enforcement: The format-control level is the second element in a PIN profile. For the
IBM 4765 and IBM 4764, this element must be set to NONE followed by four space characters.
Pad digit: The pad digit is the third element in a PIN profile. Certain PIN-block formats require a pad
digit when a PIN is either formatted, extracted, or both, as discussed in Table 54 on page 434. The pad
digit for PIN formatting column indicates the values that the verb uses when it creates a PIN block. The
pad digit for PIN extraction column indicates the values that the verb uses when it extracts a PIN from a
PIN block.
When required, specify the pad digit as a character from the character set 0 - 9 and A - F. The pad digit
must be uppercase, right-aligned in the 8-byte element, with 7 preceding space characters. When a pad
digit is not required, specify 8 space characters.
Note: For the IBM 3621 PIN-block format, the pad digit should be a non-decimal character (from C'A' -
C'F'). The 3624 PIN-block format depends on the fact that the pad digit is not the same as a PIN
digit. If they are the same, unpredictable results can occur. For this reason, do not use a decimal
digit for the pad digit. If you use a decimal digit for the pad digit, you also limit the range of possible
PINs.
If you use a decimal digit for the pad digit, ensure that you do not include the decimal digit in the
decimalization table. For information about the decimalization table, see PIN verb data_array variable on
page 432.
Table 54. Pad-digit specification by PIN-block format
PIN-block format Pad digit for PIN formatting Pad digit for PIN extraction
3624 X'0' - X'F' X'0' - X'F'
ISO-0 X'F' The pad-digit specification is ignored.
ISO-1 The pad-digit specification is ignored. The pad-digit specification is ignored.
ISO-2 The pad-digit specification is ignored. The pad-digit specification is ignored.
ISO-3 Random X'A' - X'F' The pad-digit specification is ignored.
EMV-PIN-change The pad-digit specification is ignored. The pad-digit specification is ignored.
Current key serial number: When a PIN block is encrypted with a derived, unique key, the 24-byte
PIN_profile variable is extended from 24 bytes to 48 bytes to include the CKSN extension. The CKSN is
left-aligned within the extension and padded with 4 bytes of X'00'.

The CKSN is the concatenation of a terminal identifier and a sequence number which, together, define a
unique terminal (within the set of terminals associated with a given base key) and the sequence number of
the transaction originated by that terminal. Each time the terminal completes a transaction, it increments
the sequence number and modifies the transaction-encryption key retained within the terminal. The
key-modification process is a one-way function so that tampering with the terminal does not reveal
previously used keys. For details of this process, see Derived unique-key-per-transaction calculation
method on page 704.
PIN-extraction methods
Before a verb can process a formatted and encrypted PIN, the verb must decrypt the PIN block and
extract the PIN from the PIN block. The PIN verbs can use multiple PIN-extraction methods. The valid
PIN-extraction method depends on the PIN-block format.
You can specify a PIN-extraction method or use the default method for the PIN-block format. To specify a
PIN-extraction method, use a keyword in the rule_array variable for the verb.
Table 55 shows the keywords for the PIN-extraction methods that are valid for each PIN-block format.
When only one PIN-extraction method is valid, the keyword is the default value. When more than one
method is valid, the first keyword is the default value.
Table 55. PIN-extraction method keywords by PIN-block format
PIN-block format PIN-extraction method keywords (used in the rule array)
3624 HEXDIGIT
PADDIGIT
PADEXIST
PINLEN04 PINLEN16
ISO-0 PINBLOCK
ISO-1 PINBLOCK
ISO-2 PINBLOCK
ISO-3 PINBLOCK
The PIN-extraction method keywords operate in the following way:

PINBLOCK
Depending on the contents of the PIN block, this keyword specifies that the verb use one of the
following items to identify the PIN:
v The PIN length, if the PIN block contains a PIN-length field.
v The PIN-delimiter character, if the PIN block contains a PIN-delimiter character.
PADDIGIT
This keyword specifies that the verb is to use the pad value in the PIN profile to identify the end of
the PIN.
HEXDIGIT
This keyword specifies that the verb is to use the first occurrence of a digit in the range from X'A'
to X'F' as the pad value to determine the PIN length.
PINLENxx
This keyword specifies that the verb is to use the length specified in the keyword, where xx can
range from 4 16 digits, to identify the PIN.
PADEXIST
This keyword specifies that the verb is to use the character in the sixth position of the PIN block
as the value of the pad value.

Enhanced PIN security mode
An enhanced PIN security mode is available. This optional mode is selected by enabling the Enhanced
PIN Security Mode command (offset X'0313') in the active role. When active, this command affects all PIN
verbs that extract or format a PIN using a PIN-block format of 3621 or 3624 with a PIN-extraction method
of PADDIGIT.
Table 56 summarizes the verbs affected by the Enhanced PIN Security Mode command and describes the
effect that the command has when the command is enabled.
Table 56. Verbs affected by enhanced PIN security mode
PIN-block format PIN processing changes (when Enhanced PIN
and PIN-extraction Security Mode command, offset X'0313', is
method Verbs affected enabled)
3621 or 3624 Clear_PIN_Generate_Alternate PIN extraction determines the PIN length by scanning
format and Encrypted_PIN_Translate from right to left until a digit, not equal to the pad
PADDIGIT Encrypted_PIN_Verify digit, is found. The minimum PIN length is set at four
PIN_Change/Unblock digits, so scanning ceases one digit after the position
of the 4th PIN digit in the block. (No changes are
made for any PIN-extraction method other than
PADDIGIT.)
3621 or 3624 Clear_PIN_Encrypt PIN formatting does not examine the PIN, in the
format and Encrypted_PIN_Generate output PIN block, to see if it contains the pad digit.
PADDIGIT Encrypted_PIN_Translate (No changes are made for any PIN-extraction method
other than PADDIGIT.)
Personal account number

A personal account number (PAN) identifies an individual and associates that individual to an account at
the financial institution. The PAN consists of the following data:
v Issuer identification number
v Customer account number
v One check digit
For the ISO-0 and ISO-3 (Release 3.30 or later) PIN-block formats, the PIN verbs use a PAN to format
and extract a PIN. You specify the PAN with a PAN_data parameter for the verb. You must specify the
PAN in character format in a 12-byte field. Each digit in the PAN must be from 0 - 9. The actual PAN might
be more than 12 digits, but the PIN verbs use only 12 digits for the PAN. Depending on the PIN-block
format, the verbs use the rightmost 12 digits or the leftmost 12 digits.
Note: When using the ISO-0 or ISO-3 PIN-block format, use the rightmost 12 digits of the PAN, excluding
the check digit.
Generating and verifying card security codes

A card security code is a security feature for credit card or debit card transactions. Card companies such
as American Express, MasterCard, and Visa use these codes to help protect against fraud.
Both Visa and MasterCard employ the same process for creating a card security code. Visa calls their
card security code a card-verification value (CVV). MasterCard calls theirs a card validation code (CVC).
CCA uses the term CVV generically.
The CVV value can be encoded in track 2 (CVV1 or CVC1) or might be printed, but not embossed, on a
credit card (CVV2 or CVC2). Look for a 3, 4, or 5 character code that might be indent-printed in the card's
signature panel following the card number on the back of a credit card. This code is sometimes requested
in a card-not-present transaction.

CCA can generate and verify a CVV using the CVV_Generate (CSNBCSG) and CVV_Verify (CSNBCSV)
verbs.
The process used to generate a CVV is described in CVV and CVC card-verification method on page
706.
American Express employs its own proprietary process for creating a card security code. American
Express calls their card security code a card identification number (CID).
CCA can generate and verify a CID using the Transaction_Validation (CSNBTRV) verb.
Working with EMV smart cards

There are several verbs and verb capabilities you can use in secure communications with EMV smart
cards. The processing capabilities are consistent with the specifications provided in these documents:
v EMV 2000 Integrated Circuit Card Specifications for Payment Systems Version 4.0 (EMV4.0)
v Visa Integrated Circuit Card Specification Manual, Version 1.4.0
v Integrated Circuit Card Specification (VIS) 1.4.0 Corrections
EMV smart cards include the following processing capabilities:

v The Diversified_Key_Generate verb (see Diversified_Key_Generate (CSNBDKG) on page 211) with
rule-array options TDES-XOR, TDESEMV2, and TDESEMV4 enable you to derive a key used to cipher
and authenticate messages, and more particularly message parts, for exchange with an EMV smart
card. You use the derived key with verbs such as Encipher, Decipher, MAC_Generate, MAC_Verify,
Secure_Messaging_for_Keys, and Secure_Messaging_for_PINs. These message parts can be
combined with message parts created using the Secure_Messaging_for_Keys and
Secure_Messaging_for_PINs verbs.
v The Secure_Messaging_for_Keys verb (see Secure_Messaging_for_Keys (CSNBSKY) on page 481)
enables you to securely incorporate a key into a message part (generally the value portion of a TLV
component of a secure message for a card). Similarly, the Secure_Messaging_for_PINs verb (see
Secure_Messaging_for_PINs (CSNBSPN) on page 484) enables secure incorporation of a PIN block
into a message part.
v The PIN_Change/Unblock verb (see PIN_Change/Unblock (CSNBPCU) on page 475) enables you to
encrypt a new PIN to send to a new EMV smart card, or to update the PIN value on an initialized EMV
card. This verb generates both the required session key (from the master encryption key) and the
required authentication code (from the master authentication key).
v The ZERO-PAD option of the PKA_Encrypt verb (see PKA_Encrypt (CSNDPKE) on page 307)
enables you to validate a digital signature created according to ISO/IEC 9796-2 standard by encrypting
information you format, including a hash value of the message to be validated. You compare the
resulting enciphered data to the digital signature accompanying the message to be validated.
v The MAC_Generate and MAC_Verify verbs post-pad a X'80'...X'00' string to a message as required for
authenticating messages exchanged with EMV smart cards.
Financial services support verbs

Clear_PIN_Encrypt (CSNBCPE)
The Clear_PIN_Encrypt verb formats a PIN into one of the following PIN-block formats and encrypts the
results (see PIN-block formats on page 700):
v IBM 3624 format
v ISO-0 format (same as ANS X9.8, VISA-1, and ECI-1)
v ISO-1 format (same as ECI-4)
v ISO-2 format
v ISO-3 format (Release 3.30 or later)
You can use the Clear_PIN_Encrypt verb to create an encrypted PIN-block for transmission. With the
RANDOM keyword, you can also have the verb generate random PIN numbers. This can be useful when
you supply PIN numbers to a bank-card manufacturer.
Note: A clear PIN is a sensitive piece of information. Ensure that your application program and system
design provide adequate protection for any clear-PIN value.
To use this verb, specify the following data:

v A key used to encrypt the PIN block.
v A clear PIN. When you generate random PINs, the clear_PIN variable specifies the length of the
generated-PIN value by the number of left-aligned numeral zero characters. The remainder of the
variable must be padded on the right with space characters.
v A PIN profile that specifies the format of the PIN block to be created, and any pad digit; see PIN
profile on page 433.
v When using the ISO-0 or ISO-3 PIN-block format, the PAN_data variable provides the account number
that is exclusive-ORed with the PIN information.
v The sequence number. Specify a value of 99999 in the integer variable.

v Formats the PIN into the specified PIN-block format.
v Checks the control vector for the OPINENC key by verifying that the CPINENC bit is 1.
v Encrypts the PIN block in ECB mode.
v Returns the encrypted PIN-block in the encrypted_PIN_block variable.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The ISO-3 PIN-block format is not supported in releases before Release 3.30.

Format
CSNBCPE
PIN_encrypting_key_identifier Input String 64 bytes
clear_PIN Input String 16 bytes
PIN_profile Input String array 3 * 8 bytes
PAN_data Input String 12 bytes
sequence_number Input Integer 99999
encrypted_PIN_block Output String 8 bytes
Parameters
PIN_encrypting_key_identifier
The PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an operational
key-token or a key label of an operational key-token. The key token contains the key that encrypts the
PIN block. The control vector in the internal key token must specify an OPINENC key type and have
the CPINENC bit (CV bit 18) set to B'1'.
rule_array_count
rule_array
Keyword Meaning
PIN source (one, optional)
ENCRYPT Causes the verb to use the PIN value contained in the clear_PIN variable. This is the
default.
RANDOM Causes the verb to use a randomly generated PIN value. The length of the PIN is based on
the value in the clear_PIN variable. Value the clear PIN to 0 and use as many digits as the
desired random PIN. Pad the remainder of the clear_PIN variable on the right with space
characters.
clear_PIN
The clear_PIN parameter is a pointer to a string variable containing the clear PIN. The PIN value must
be left-aligned and padded on the right with space characters.

PIN_profile
The PIN_profile parameter is a pointer to a string variable containing three 8-byte elements with: a
PIN-block format keyword, a format-control keyword (NONE), and a pad digit as required by certain
formats. See PIN profile on page 433.
PAN_data
The PAN_data parameter is a pointer to a personal account number (PAN) in character format. The
verb uses this parameter if the PIN profile specifies the ISO-0 or ISO-3 keyword for the PIN-block
format. Otherwise, ensure that this parameter points to a 12-byte area in application storage. The
information in this variable is ignored, but the variable must be declared.
sequence_number
The sequence_number parameter is a pointer to an integer variable. Specify a value of 99999.
encrypted_PIN_block
The encrypted_PIN_block parameter is a pointer to a string variable containing the encrypted
PIN-block returned by the verb.
Required commands
The Clear_PIN_Encrypt verb requires the Format and Encrypt PIN command (offset X'00AF') to be
An enhanced PIN security mode is available for formatting an encrypted PIN-block into IBM 3621 or 3624
format using the PADDIGIT PIN-extraction method. This mode limits checking of the PIN to decimal digits;
no other PIN-block consistency checking will occur. To activate this mode, enable the Enhanced PIN
Security Mode command (offset X'0313') in the active role.

Clear_PIN_Generate (CSNBPGN)
The Clear_PIN_Generate verb generates an A-PIN or an O-PIN using one of the following PIN calculation
methods that you specify with a rule-array keyword (see PIN calculation methods on page 697):
v IBM 3624 PIN (IBM-PIN)
v IBM 3624 PIN Offset (IBM-PINO)
You can use this verb to perform the following tasks:

v Generate a clear PIN for immediate use; for example, generate a clear A-PIN as part of PIN mailer
processing
v Generate an offset (O-PIN) for use on a customer account magnetic-stripe card
Notes:
1. A clear PIN is a sensitive piece of information. Ensure that your application program and system
design provide adequate protection for the clear PIN.
2. To format and encrypt a PIN, use the Clear_PIN_Encrypt verb.
To use this verb, specify this data:

v A PIN-generating key
v The number of rule-array elements
v The PIN-calculation method
v The length of the PIN
v For certain PIN calculation methods, an additional PIN-length value with the PIN_check_length variable
to determine the length of the O-PIN value
v A decimalization table, validation data (for example, account-number information) and, based on the
PIN-calculation method, the C-PIN value, in a character array
v A 16-byte variable to receive the clear PIN

1. Verifies that the CPINGEN bit (CV bit 18) is set to B'1' in the control vector for the PINGEN key.
2. Calculates the A-PIN, and optionally uses the C-PIN and the A-PIN to compute the O-PIN value. See
PIN calculation methods on page 697.
3. Uses the specified PIN length to determine the length of the PIN.
4. Returns the clear A-PIN or O-PIN in the variable identified by the returned_result parameter.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
|

Format
CSNBPGN
PIN_generating_key_identifier Input String 64 bytes
PIN_length Input Integer 4 - 16
PIN_check_length Input Integer 4 - 16
data_array Input String array 3 * 16 bytes
returned_result Output String 16 bytes
Parameters
PIN_generating_key_identifier
The PIN_generating_key_identifier parameter is a pointer to a string variable containing an operational
key-token or a key label of an operational key-token record. The key token contains the
PIN-generation key and must contain a control vector that specifies the PINGEN key type and has the
CPINGEN bit (CV bit 18) set to B'1'.
rule_array_count
in the rule_array variable. This value must be 1.
rule_array
Keyword Meaning
PIN-calculation method (one required)
IBM-PIN Specifies that the IBM 3624 PIN-calculation method is to be used to generate a PIN.
IBM-PINO Specifies that the IBM 3624 PIN-offset calculation method is to be used to generate a PIN
offset.
PIN_length
The PIN_length parameter is a pointer to an integer variable containing the number of digits of the
PIN. It is a value from 4 - 16.
PIN_check_length
The PIN_check_length parameter is a pointer to an integer variable from 4 16 containing the length
of the PIN offset. The verb uses the PIN-check length if you specify the IBM-PINO keyword for the
PIN-calculation method. Otherwise, ensure that this parameter is a pointer to a 4-byte variable in
application storage. This variable must be declared.
Note: The PIN_check_length variable must be less than or equal to the PIN length.

data_array
The data_array parameter is a pointer to a string variable containing three 16-byte numeric character
strings, which are equivalent to a single 48-byte string. The values in the data array depend on the
keyword for the PIN-calculation method. Each element is not always used, but you must always
declare a complete data array.
The numeric characters in each 16-byte string must be 1 16 bytes in length, left-aligned, and padded
on the right with space characters. The verb converts the space characters to zeros.
When using the IBM-PIN and IBM-PINO keywords, identify the following elements in the data array:
Element Description
decimalization_table This element contains the decimalization table of 16 characters (0 9) that are used
to convert the hexadecimal digits (X'0' X'F') of the encrypted validation data to
decimal digits (X'0' X'9').
validation_data This 16-byte element contains 1 16 characters of account data. The data must be
left-aligned and padded on the right with spaces.
clear_PIN When using the IBM-PINO keyword, this 16-byte element contains the clear
customer-selected PIN. This value must be left-aligned and padded on the right with
spaces.
returned_result
The returned_result parameter is a pointer to a string variable containing the result returned by the
verb. The result is left-aligned and padded on the right with space characters.
Required commands
The Clear_PIN_Generate verb requires the Generate Clear 3624 PIN command (offset X'00A0') to be
| Beginning with Release 4.2, whenever the Use Only Valid Decimalization Tables command (offset X'0356')
| is enabled in the active role, the decimalization_table element of the data_array value must match one of
| the PIN decimalization tables that are in the active state on the coprocessor. Use of this command
| provides improved security and control for PIN decimalization tables. See the
| Cryptographic_Facility_Control verb for information on managing PIN decimalization tables on the
| coprocessor.

Clear_PIN_Generate_Alternate (CSNBCPA)
The Clear_PIN_Generate_Alternate verb obtains a value, the O-PIN (either as an offset or Visa PVV
PIN-validation value) that relates the institution-assigned PIN to the customer-known PIN. The verb uses
these PIN calculation methods:
v IBM 3624 PIN offset (IBM-PINO)
v Netherlands PIN-1 (NL-PIN-1)
v Visa PIN-validation value (VISA-PVV)
You supply the customer PIN, known as a C-PIN, as an encrypted PIN-block. The verb performs the
following functions:
v Decrypts a PIN block.
v Extracts a customer-selected or institution-assigned PIN.
v Generates an A-PIN from the input account number, PIN-generating key, and so forth.
v Computes an O-PIN from the C-PIN and the A-PIN; the O-PIN is returned in the clear.
Note: To generate an O-PIN from a clear C-PIN, see the Clear_PIN_Generate verb.
To use this verb, specify the following data:

v An input PIN-block encrypting key used to decrypt the PIN block
v A PIN-generating key used to calculate the A-PIN
v A PIN profile that describes the PIN block that contains the C-PIN
v When using the ISO-0 or ISO-3 (Release 3.30 or later) PIN-block format, personal account number data
to be used in extracting the PIN
v The encrypted PIN-block that contains the C-PIN
v A PIN-calculation method and optionally a PIN-extraction method
v The length of the O-PIN offset
v A decimalization table and account validation data
v A 16-byte variable for the O-PIN
The verb performs the following processing:

1. Checks the control vector of the IPINENC key to ensure that the CPINGENA bit (CV bit 20) is 1.
2. Decrypts the PIN block in ECB mode.
3. Extracts the PIN. The verb uses the PIN-extraction method specified with the rule_array parameter or
the default extraction method for the PIN-block format. The verb also uses the PIN_check_length
variable. Depending on the PIN-block format specified in the PIN profile, the verb also uses the pad
digit specified in the input_PIN_profile variable or the PAN specified in the PAN_data variable.
4. Verifies that the CPINGENA bit (CV bit 21) is 1 in the control vector for the PINGEN key.
5. Calculates the A-PIN. The verb uses the specified PIN-calculation method, the data_array variable, and
the PIN_check_length variable to calculate the PIN.
6. Calculates the O-PIN.
7. Returns the clear O-PIN in the variable identified by the returned_result parameter.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Use of the Visa PVV PIN-calculation method will always output four digits rather than padding the
output with binary zeros to the length of the PIN.
v The ISO-3 PIN-block format is not supported in releases before Release 3.30.
v Enabling the Enforce ANS X9.8 PIN Rules command (offset X'0350') in the active role has not effect on
access control in releases before Release 4.1.
Format
CSNBCPA
exit_data In/Output Integer exit_data_length bytes
inbound_PIN_encrypting_key_identifier Input String 64 bytes
input_PIN_profile Input String array 3 * 8 bytes
encrypted_PIN_block Input String 8 bytes
returned_result Output String 16 bytes
Parameters
inbound_PIN_encrypting_key_identifier
The inbound_PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an
operational key-token or a key label of an operational key-token record. The key token contains the
key that decrypts the PIN-block C-PIN. The control vector in the key token must specify the IPINENC
key type and have the CPINGENA bit (CV bit 20) set to B'1'1.

PIN-generation key and must contain a control vector that specifies the PINGEN key type and has the
CPINGENA bit (CV bit 21) set to B'1'.
input_PIN_profile
The input_PIN_profile parameter is a pointer to a string variable containing a character array with
three 8-byte elements: the PIN-block format keyword, the format control (NONE), a pad digit, if
needed. See PIN profile on page 433 for more information.
PAN_data
The PAN_data parameter is a pointer to a string variable containing personal account number (PAN)
data. If the PIN profile specifies the ISO-0 or ISO-3 keyword, the verb uses the PAN data to recover
the C-PIN from the PIN block.
Note: When using the ISO-0 or ISO-3 PIN-block format, use the 12 rightmost PAN digits, excluding
the check digit.
encrypted_PIN_block
PIN-block of the customer-selected C-PIN value.
rule_array_count
rule_array
characters.
Element Number Function of Keyword

1 PIN-calculation method
2 PIN-extraction method
The first element in the rule array must specify one of the keywords that indicates the PIN-calculation
method, as shown in Table 57.
Table 57. Clear_PIN_Generate_Alternate rule_array keywords (first element)
PIN-calculation method Meaning
IBM-PINO Specifies that the IBM 3624 PIN-offset calculation method is to be
used. PINGEN NOOFFSET bit (CV bit 37) must not be set.
NL-PIN-1 Specifies that the Netherlands PIN-1 calculation method is to be
used.
VISA-PVV Specifies that the Visa PVV PIN-calculation method is to be used.
The second element in the rule array must specify one of the keywords that indicates a PIN-extraction
method, as shown in Table 58 on page 447. For more information about extraction methods, see
PIN-extraction methods on page 435.
Notes:
1. In the table, the PIN-block format keyword is the keyword that you specify in the input_PIN_profile
variable.
2. If the PIN-block format enables you to choose the PIN-extraction method. If you specify a
rule_array_count of 1, the PIN-extraction method keyword that is listed first in the following table is
the default.

Table 58. Clear_PIN_Generate_Alternate rule_array keywords (second element)
PIN-block format
keyword PIN-extraction method keyword Meaning
3624 PADDIGIT Specifies a PIN-extraction method for an IBM
HEXDIGIT 3624 PIN-block format. The first keyword,
PINLEN04 PINLEN16 PADDIGIT, is the default PIN-extraction
PADEXIST method for the PIN-block format.
ISO-0 PINBLOCK Specifies the default PIN-extraction method for
an ISO-0 PIN-block format.
an ISO-3 PIN-block format (Release 3.30 or
later).
PIN_check_length
The PIN_check_length parameter is a pointer to an integer variable from 4 - 16 containing the number
of digits of PIN information that the verb should check. The verb uses the PIN_check_length
parameter if you specify the IBM-PINO keyword for the PIN-calculation method. Otherwise, ensure
that this parameter points to a 4-byte variable in application storage. The information in this variable is
ignored, but this variable must be declared.
Note: The PIN_check_length variables should be less than or equal to the PIN length. If the
PIN_check_length variable is greater than the PIN length, the PIN_check_length variable will be
set to the PIN length.
The length of the PIN offset in the returned result is determined by the value that the
PIN_check_length parameter identifies. The security server shortens the PIN offset.
data_array
The data_array parameter is a pointer to a string variable containing three 16-byte character strings,
which are equivalent to a single 48-byte string. The values in the data array depend on the
PIN-calculation method. Each element is not always used, but you must always declare a complete
48-byte data array.
| When using the IBM-PINO or NL-PIN-1 keyword, identify the following elements in the data array as:
Element Description
to convert the hexadecimal digits (X'0' X'F') of the enciphered validation data to
decimal digits (X'0' X'9').
validation_data This 16-byte element contains 1 16 characters of account data. The data must be
left-aligned and padded on the right with space characters.
reserved_3 The information in this element is ignored, but the 16-byte element must be declared.
When using the VISA-PVV keyword, identify the following elements in the data array. For more
information about transaction security data for the Visa PVV PIN-calculation method, see Visa
PIN-validation value PIN-calculation method on page 700.

Element Description
transaction_security_parameter This element contains 16 numeric characters that include the following:
v Eleven (rightmost) digits of PAN data
v One digit of key index from 1 6
v Four space characters for padding
reserved_2 The information in this element is ignored, but the 16-byte element
must be declared.
must be declared.
returned_result
The returned_result parameter is a pointer to a string variable containing the clear O-PIN returned by
the verb. The 16-byte result is left-aligned and padded on the right with space characters.
The length of the PIN offset in the returned result is determined by the value that the
PIN_check_length variable specifies.
Required commands
The Clear_PIN_Generate_Alternate verb requires the commands shown in the following table to be
enabled in the active role based on the keyword specified for the PIN calculation methods.

IBM-PINO X'00A4' Generate Clear 3624 PIN Offset
NL-PIN-1 X'0231' Generate Clear NL-PIN-1 Offset
VISA-PVV X'00BB' Generate Clear Visa PVV Alternate
An enhanced PIN security mode is available for extracting PINs from a 3621 or 3624 encrypted PIN-block
using the PADDIGIT PIN-extraction method. This mode limits checking of the PIN to decimal digits, and a
minimum PIN length of 4 is enforced; no other PIN-block consistency checking will occur. To activate this
mode, enable the Enhanced PIN Security Mode command (offset X'0313') in the active role.
Beginning with Release 4.1, enable the Enforce ANS X9.8 PIN Rules command (offset X'0350') in the
active role to accept only an input_PIN_profile variable that contains a PIN-block format of ISO-0 or ISO-3.
Note: A role with offset X'0350' enabled also affects access control of the Encrypted_PIN_Translate and
the Secure_Messaging_for_PINs verbs.
| coprocessor. The VISA-PVV PIN-calculation method does not have a decimalization_table element and is
| therefore not affected by this command.

CVV_Generate (CSNBCSG)
The CVV_Generate verb generates card security codes as defined by the Visa card-verification value
(CVV) and the MasterCard card-verification code (CVC). This document uses the generic term CVV. The
CVV can be found on the magnetic stripe on track 2 (CVV1 or CVC1), or indent-printed but not embossed
on a card (CVV2 or CVC2).
The verb generates a CVV that is based on the information you specify with the PAN_data, the
expiration_date, and the service_code parameters. The verb uses the key-A and key-B keys to
cryptographically process this information. For details about the CVV process, see CVV and CVC
card-verification method on page 706.
You specify the following information:

v The length of the personal account number (PAN) through a rule-array keyword.
v The PAN data in a 16-byte variable for a 13-character or 16-character PAN, or in a 19-byte variable for
a 19-character PAN.
| v Two single-length MAC-capable operational DES keys, key-A and key-B or, beginning with Release 4.2,
| one double-length operational DES key with key type MAC that has the CVVKEY-A attribute (CV bits 0 -
| 3 = B'0010'), that is, contains key-A in the left half and key-B in the right half. Specify either a
MAC-class key type or a DATA-class key type. The subtype extension bit field (bits 0 3) in the control
vectors can be B'0000'. Alternatively, you can ensure that the keys are used only in the CVV_Generate
and CVV_Verify verbs by specifying a MAC-class key with subtype extension bits (CV bits 0 - 3) for
key-A as B'0010' (CVVKEY-A) and for key-B as B'0011' (CVVKEY-B). The control vectors for these keys
| must also indicate MAC generation capability by having CV bit 20 set to B'1'. For more information
about control vectors, see Appendix C, CCA control-vector definitions and key encryption.
The verb returns the five-byte variable specified by the CVV_value parameter. If the requested CVV is
shorter than five characters, the CVV is left-aligned and padded on the right with space characters.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v A double-length key is not supported in releases before Release 4.2.

Format
CSNBCSG
PAN_data Input String 16 or 19 bytes
expiration_date Input String 4 bytes
service_code Input String 3 bytes
CVV_key-A_identifier Input String 64 bytes
CVV_key-B_identifier Input String 64 bytes
CVV_value Output String 5 bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
PAN-data length (one, optional)
PAN-13 Specifies that the length of the PAN data is 13 bytes. This is the default.
PAN-16 Specifies that the length of the PAN data is 16 bytes.
CVV length (one, optional)
CVV-1 Specifies the length of the CVV to be returned is 1 character. This is the default.
CVV-2 Specifies the length of the CVV to be returned is 2 characters.
PAN_data
The PAN_data parameter is a pointer to a string variable containing PAN data in character format. The
PAN is the account number as defined for the track-2 magnetic-stripe standards. If you specify either
the PAN-13 or PAN-16 keyword, 16 bytes are sent to the coprocessor. A 13-character PAN must be
left aligned in the 16-byte variable. If you specify the PAN-19 keyword, 19 bytes are sent to the
coprocessor.

expiration_date
The expiration_date parameter is a pointer to a string variable containing the card expiration date. The
date is in numeric character format. You must determine whether the CVV is calculated as YYMM or
MMYY.
service_code
The service_code parameter is a pointer to a string variable containing the service code in character
format. The service code is the number that the track-2 magnetic-stripe standards define.
CVV_key-A_identifier
| The CVV_key-A_identifier parameter is a pointer to a string variable containing an operational DES
| key-token or a key label of such a key. Before Release 4.2, the key token contains the single-length
| MAC-capable key-A key that encrypts information in the CVV process. Beginning with Release 4.2, the
| key token can contain either the single-length key-A key, or the double-length CVVKEY-A key. The
| double-length key meets recent standard changes governing users of this function. It contains key-A in
| the left half, and key-B in the right half. If the key is double length, the CVV_key-B_identifier parameter
| must identify a null key-token. See CVV_Key_Combine (CSNBCKC) for information on combining two
| single-length MAC-capable keys into one double-length key. Use a key type of DATA or MAC with its
| MAC generate bit on (CV bit 20 = B'1').
CVV_key-B_identifier
| The CVV_key-B_identifier parameter is a pointer a string variable containing an operational key-token
| or a key label of such a key. The key token contains the single-length key-B key that decrypts
| information in the CVV process. Use a key type of DATA or MAC with its MAC generate bit on (CV bit
| 20 = B'1').
| Beginning with Release 4.2, if the CVV_key-A_identifier identifies a double-length key, this parameter
| must identify a null parameter.
CVV_value
The CVV_value parameter is a pointer to a string variable containing the CVV value in character
format returned by the verb.
Required commands
The CVV_Generate verb requires the Generate CVV command (offset X'00DF') to be enabled in the active
role.

| CVV_Key_Combine (CSNBCKC)
| Use the CVV_Key_Combine verb to combine two operational DES keys into one operational TDES key.
| The verb accepts as input two single-length keys that are suitable for use with the CVV (card-verification
| value) algorithm. The resulting double-length key meets a more recent industry standard of using TDES to
| support PIN-based transactions. In addition, the double-length key is in a format that can be wrapped
| using the Key_Export_to_TR31 verb.
| The CVV_Generate and CVV_Verify verbs use the CVV algorithm to generate and verify card security
| codes required by Visa (CVV) and MasterCard (CVC). Previously, these verbs only accepted as input two
| single-length MAC-capable keys. Beginning with Release 4.2, these verbs will additionally accept as input
| a double-length MAC or MAC-capable DATA key that contains key-A as the left half of the key, and key-B
| as the right half of the key. The double-length key must be usable with either the CVV_Generate verb, the
| CVV_Verify verb, or both.
| The CVV_Key_Combine verb allows combining most pairs of single-length DES keys that formerly
| functioned as a separate key-A and key-B into one double-length CVVKEY-A key. The CVVKEY-A attribute
| in the control vector is now changed to mean single-length CVV key containing key-A or double-length
| CVV key containing key-A and key-B.

| v Up to two optional rule-array keywords:
| 1. A key wrapping method keyword that specifies whether to use the new enhanced wrapping method,
| the original wrapping method, or the wrapping method defined as the default according to a
| configuration setting.
| 2. A translation control keyword that restricts the translation method to the enhanced method.
| v A single-length operational DES key for key-A
| Identify a single-length operational DES key that has a key type of MAC or DATA. The key identifier
| length must be 64, which is the length of a DES key-token or a key label. This parameter identifies the
| key-A key used with the CVV algorithm. It is placed in the left half of the double-length output key.
| When a MAC key is identified, it must have as its subtype extension ANY-MAC (CV bits 0 - 3 = B'0000')
| or CVVKEY-A (CV bits 0 - 3 = B'0010'). If a DATA key is identified, it must have its MAC generate bit on
| (CV bit 20), its MAC verify bit on (CV bit 21), or both bits on.
| v A single-length operational DES key for key-B
| Identify a single-length operational DES key that has a key type of MAC or DATA. The key identifier
| length must be 64, which is the length of a DES key-token or a key label. This parameter identifies the
| key-B key used with the CVV algorithm. It is placed in the right half of the double-length output key.
| When a MAC key is identified, it must have as its subtype extension ANY-MAC (CV bits 0 - 3 = B'0000')
| or CVVKEY-B (CV bits 0 - 3 = B'0011'). If a DATA key is identified, it must have its MAC generate bit on
| (CV bit 20), its MAC verify bit on (CV bit 21), or both bits on.
| v An output key identifier
| Identify a null key-token in a 64-byte buffer, or the key label of a DES null key-token. If the input
| parameter identifies a key label, the output key is placed in DES key-storage. otherwise, the output is
| returned in the buffer provided.
| The following table shows the various output combinations that are returned for the MAC generate and
| MAC verify attributes. These results are based on the three possible MAC generate and MAC verify
| control-vector-bit combinations (bits 20 - 21) that the pair of input keys can have.

|| CV bits 20 - 21 of input key key-B, single length
| CV bits 20 - 21 of
| input key key-A, MAC generate and MAC generate only,
| single length MAC verify single length MAC verify only
| MAC generate and MAC generate and MAC verify MAC generate only MAC verify only
| MAC verify double-length key-A double-length key-A double-length key-A
| MAC generate only MAC generate only MAC generate only Invalid combination, control
| double-length key-A double-length key-A vector conflict
| MAC verify only MAC verify only Invalid combination, control MAC verify only
| double-length key-A vector conflict double-length key-A
|
| Restrictions
| AIX
| IBM i
| Windows
|
| v Input key-A and input key-B cannot have different export control bits (CV bit 17 and 57); these bits must
| match. Use the Prohibit_Export verb to change XPORT-OK to NO-XPORT (CV bit 17), or the
| Restrict_Key_Attribute verb to change T31XPTOK to NOT31XPT (CV bit 57, newly defined in Release
| 4.2). These two bits get propagated to the output key-token.
| Format
| CSNBCKC
| rule_array_count Input Integer 0, 1, or 2
| key_a_identifier_length Input Integer 64
| key_a_identifier Input String key_a_identifier_length bytes
| key_b_identifier_length Input Integer 64
| key_b_identifier Input String key_b_identifier_length bytes
| output_key_identifier_length Input Integer 64
|
| Parameters

| rule_array_count
| in the rule_array variable. The value must be 0, 1, or 2.
| rule_array
| characters. The rule_array keywords are:
|| Keyword Meaning
| Key wrapping method (one, optional)
| USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. This
| keyword is ignored for AES keys. This is the default.
| Translation control (optional). This is valid only with wrapping method WRAP-ENH or with USECONFG when the
| default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to
| binary zeros. Release 4.1 or later.
| ENH-ONLY Specifies to restrict the key from being wrapped with the legacy wrapping method after it has
| been wrapped with the enhanced wrapping method. Sets bit 56 (ENH-ONLY) of the control
| vector to B'1'.
|
| There are restrictions on the available wrapping methods for the output key derived from the wrapping
| methods employed and control vector restrictions of the input keys. These are detailed in Table 59.
| Table 59. Key-wrapping matrix for CVV_Key_Combine
| key-A or key-B key-A or key-B has WRAP-ENH (by
| wrapped using ENH-ONLY bit on (CV keyword or by ENH-ONLY Resulting form of
| WRAP-ENH method bit 56 = B'1') default) keyword output key or error
| No No No to both No ECB wrapped
| Yes No No to both No Wrap type conflict,
| 8/2161 (X'871')
| No No Yes to either No WRAP-ENH, CV bit 56
| = B'0' (NOT set)
| Yes No Yes to either No
| No No Yes to either Yes WRAP-ENH, CV bit 56
| = B'1' (IS set)
| Yes No Yes to either Yes
| Yes Yes Yes to either No
| Yes Yes Yes to either Yes
| No No No to both Yes CV bit 56 conflict, 8/2111
| (X'83F')
| Yes No No to both Yes
| Yes Yes No to both No
| Yes Yes No to both Yes
|
| key_a_identifier_length
| The key_a_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes in the key_a_identifier variable. This value must be 64.
| key_a_identifier
| The key_a_identifier parameter is a pointer to a string variable containing either the operational
| single-length DES key-token of the key-A key, or the label of such a key token. This key must be a
| MAC key or a DATA key that can perform MAC operations.

| key_b_identifier_length
| The key_b_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes in the key_b_identifier variable. This value must be 64.
| key_b_identifier
| The key_b_identifier parameter is a pointer to a string variable containing either the operational
| single-length DES key-token of the key-B key, or the label of such a key token. This key must be a
| MAC key or a DATA key that can perform MAC operations.
| The output_key_identifier_length parameter is a pointer to an integer variable containing the number of
| bytes in the output_key_identifier variable. This value must be 64.
| The output_key_identifier parameter is a pointer to a string variable containing a NULL key token, or
| the key label of a null DES key-token.
| Required commands
| The CVV_Key_Combine verb requires the CVV Key Combine command (offset X'0155') to be enabled in
| the active role.
| In addition, these commands are required to be enabled in the active role, depending on the key-wrapping
| method keyword:
|| Keyword Offset Command
| WRAP-ECB X'0156' CVV Key Combine - Allow Wrapping Override Keywords
| WRAP-ENH
|
| One additional restriction is related to combining the key-A and key-B pair of keys when there are mixed
| types. To permit the combination of mixed key types into a single set of types (ANY-MAC, CVVKEY-A,
| CVVKEY-B, and DATA), enable the CVV Key Combine - Permit Mixed Key Types command (offset
| X'0157') in the active role. See the table below for when this command is required:
|| Input key-B
| Input key-A ANY-MAC CVVKEY-A CVVKEY-B DATA
| ANY-MAC Always returns Invalid combination, Only returns Only returns
| double-length control vector conflict double-length double-length
| CVVKEY-A key CVVKEY-A key if CVVKEY-A key if
| X'0157' enabled X'0157' enabled
| CVVKEY-A Only returns Invalid combination, Always returns Only returns
| CVVKEY-A key if CVVKEY-A key CVVKEY-A key if
| X'0157' enabled, else X'0157' enabled
| access error
| CVVKEY-B Invalid combination Invalid combination Invalid combination Invalid combination
| DATA Only returns Invalid combination, Only returns Always returns
| CVVKEY-A key if CVVKEY-A key if CVVKEY-A key
| X'0157' enabled, else X'0157' enabled, else
| access error access error
|
|

CVV_Verify (CSNBCSV)
The CVV_Verify verb verifies credit-card verification codes as defined by the Visa card-verification value
(CVV) and the MasterCard card-verification code (CVC). This data can be found on the magnetic stripe on
track 2, and indent-printed but not embossed on a card. This document uses the generic term CVV.
The verb generates a CVV value internal to the coprocessor based on the information you specify with the
PAN_data, the expiration_date, and the service_code parameters. The verb uses the key-A and key-B
keys to cryptographically process this information. The internal value is compared to that which you
provide and the result is returned to you in a return-code value. For details about the CVV process, see
CVV and CVC card-verification method on page 706.

v The length of the personal account number (PAN) through a rule-array keyword.
v The PAN data in a 16-byte variable for a 13-character or 16-character PAN, or in a 19-byte variable for
a 19-character PAN.
| v Two single-length MAC-capable operational DES keys, key-A and key-B or, beginning with Release 4.2,
| one double-length operational DES key with key type MAC that has the CVVKEY-A attribute (CV bits 0 -
| 3 = B'0010'), that is, contains key-A in the left half and key-B in the right half. Specify either a
| MAC-class key type or a DATA-class key type. The subtype extension bit field (bits 0 - 3) in the control
vectors can be B'0000'. Alternatively, you can ensure that the keys are used only in the CVV_Generate
and CVV_Verify verbs by specifying a MAC-class key with subtype extension bits (CV bits 0 - 3) for
key-A as B'0010' (CVVKEY-A) and for key-B as B'0011' (CVVKEY-B). The control vectors for these keys
must also indicate verification capability by having CV bit 21 set to B'1'. For more information about
control vectors, see Appendix C, CCA control-vector definitions and key encryption.
v The expected CVV value in a 5-byte variable, left aligned and padded with space characters.
Based on your use of the CVV_n rule-array keywords, the internal CVV value is truncated to fewer
characters and padded on the right with space characters. The internal CVV value is then compared to the
five-character value that you specify with the CVV_value parameter. The result of this comparison is
indicated in the return code.
The verb returns the results of the comparison in the return_code variable. If the return code is 0, the
values correctly compared. If the CVV values do not match, the return code is set to 4 (and the reason
code is set to B'1').
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v A double-length key is not supported in releases before Release 4.2.

Format
CSNBCSV
PAN_data Input String 16 or 19 bytes
expiration_date Input String 4 bytes
service_code Input String 3 bytes
CVV_key-A_identifier Input String 64 bytes
CVV_key-B_identifier Input String 64 bytes
CVV_value Input String 5 bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
PAN-data length (one, optional)
PAN-13 Specifies that the length of the PAN data is 13 bytes. This is the default.
CVV length (one, optional)
CVV-1 Specifies that the length of the CVV to be verified is 1 character. This is the default.
CVV-2 Specifies that the length of the CVV to be verified is 2 characters.
PAN_data
The PAN_data parameter is a pointer to a string variable containing the PAN data in character format.
The PAN is the account number as defined for the track-2 magnetic-stripe standards. If you specify
either the PAN-13 or PAN-16 keyword, 16 bytes are sent to the coprocessor. A 13-character PAN must
be left aligned in the 16-byte variable. If you specify the PAN-19 keyword, 19 bytes are sent to the
coprocessor.

expiration_date
The expiration_date parameter is a pointer to a string variable containing the card expiration date. The
date is in numeric character format. You must determine whether the CVV is calculated as YYMM or
MMYY.
service_code
The service_code parameter is a pointer to a string variable containing the service code in character
format. The service code is the number that the track-2, magnetic-stripe standards define.
CVV_key-A_identifier
| The CVV_key-A_identifier parameter is a pointer to a string variable containing an operational
| MAC-capable DES key-token or a key label of such a key. Before Release 4.2, the key token contains
| the single-length key-A key that encrypts information in the CVV process. Beginning with Release 4.2,
| the key token can contain either the single-length key-A key, or the double-length CVVKEY-A key. The
| double-length key meets recent standard changes governing users of this function. It contains key-A in
| the left half, and key-B in the right half. If the key is double length, the CVV_key-B_identifier parameter
| must identify a null key-token. See CVV_Key_Combine (CSNBCKC) for information on combining two
| single-length MAC-capable keys into one double-length key. Use a key type of DATA or MAC with its
| MAC verify bit on (CV bit 21 = B'1').
CVV_key-B_identifier
| The CVV_key-B_identifier parameter is a pointer a string variable containing an operational key-token
| or a key label of such a key. The key token contains the single-length key-B key that decrypts
| information in the CVV process. Use a key type of DATA or MAC with its MAC verify bit on (CV bit 21
| = B'1').
| Beginning with Release 4.2, if the CVV_key-A_identifier identifies a double-length key, this parameter
| must identify a null parameter.
CVV_value
The CVV_value parameter is a pointer to a string variable containing the CVV value in character
format.
Required commands
The CVV_Verify verb requires the Verify CVV command (offset X'00E0') to be enabled in the active role.

Encrypted_PIN_Generate (CSNBEPG)
The Encrypted_PIN_Generate verb generates and formats a PIN and encrypts the PIN block. To generate
the PIN, the verb uses one of the following PIN calculation methods:
v IBM 3624 PIN
v IBM German Bank Pool Institution PIN
v InterBank PIN
To format the PIN, the verb uses one of the following PIN-block formats:
v IBM 3624
v ISO-0 (same as ANS X9.8, VISA-1, and ECI-1)
v ISO-1 (same as ECI-4)
v ISO-2
v ISO-3 (Release 3.30 or later)
You can use the Encrypted_PIN_Generate verb to generate a PIN and create an encrypted PIN-block for
transmission or for later use in a PIN verification database.
Note: To generate a clear PIN, use the Clear_PIN_Generate verb.
To generate and format a PIN and encrypt the PIN block, specify the following information:
v An internal key-token or a key label of an internal key-token record that contains the PIN-generating key
with the PIN_generating_key_identifier parameter. The control vector in the key token must specify the
PINGEN key-type and have the EPINGEN bit (CV bit 20) set to B'1'.
v An internal key-token or a key label of an internal key-token record that contains the key to be used to
encrypt the PIN block with the outbound_PIN_encrypting_key_identifier parameter. The control vector in
the key token must specify the OPINENC key-type and have the EPINGEN bit (CV bit 19) set to B'1'.
v One for the number of rule_array elements with the rule_array_count variable.
v The PIN-calculation method with a keyword in the rule_array variable.
v The length of the PIN for those PIN calculation methods with variable-length PINs in the PIN_length
variable. Otherwise, the variable should be 0.
v A decimalization table and account validation data with the data_array parameter. For information about
a decimalization table and PIN calculation methods, see PIN calculation methods on page 697. For
information about the data-array variable, see PIN verb data_array variable on page 432.
v A PIN profile that specifies the format of the PIN block to be created, the level of format control, and
any pad digit with the output_PIN_profile parameter. For more information about the PIN profile, see
PIN-block formats on page 700.
v One of the following with the PAN_data parameter:
When using the ISO-0 or ISO-3 PIN-block format, specify a PAN. For information about a PAN, see
When using another PIN-block format, specify a 12-byte area in application storage. The information
in the variable is not used, but the variable must be declared.
v With the sequence_number variable, specify a positive integer value.
v An 8-byte variable for the encrypted PIN with the encrypted_PIN_block parameter.

v Verifies that the EPINGEN bit is 1 in the control vector for the PIN-generating key.
v Uses the specified PIN-calculation method and account validation data to calculate the PIN.
v Optionally, uses the specified PIN length to determine the length of the PIN.
v Formats the PIN into the specified PIN-block format. The verb includes the clear PIN and, depending on
the PIN-block format, the pad digit, the PAN, and the sequence number. For a description of the
formats, see PIN-block formats on page 700.

v Checks the control vector for the OPINENC key by verifying that the EPINGEN bit is 1.
v Encrypts the PIN block in ECB mode according to the format-control keyword specified in the PIN
profile.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
Format
CSNBEPG
outbound_PIN_encrypting_key_identifier Input String 64 bytes
PIN_length Input Integer
data_array Input String 16 bytes * 3
PIN_profile Input String array 3 * 8 bytes
sequence_number Input Integer
encrypted_PIN_block Output String 8 bytes
Parameters
PIN-generating key and must contain a control vector that specifies a PINGEN key type and has the
EPINGEN bit (CV bit 20) set to B'1'.
outbound_PIN_encrypting_key_identifier
The outbound_PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an

key to be used to encrypt the formatted PIN and must contain a control vector that specifies the
OPINENC key type and has the EPINGEN bit (CV bit 19) set to B'1'.
rule_array_count
in the rule_array variable. This value must be 1.
rule_array
Keyword Meaning
| PIN-calculation method (one required)
IBM-PIN Specifies that the IBM 3624 PIN-calculation method is to be used to generate a PIN.
GBP-PIN Specifies that the IBM German Bank Pool Institution PIN-calculation method is to be used to
generate a PIN.
INBK-PIN Specifies that the InterBank PIN-calculation method is to be used to generate a PIN.
PIN_length
The PIN_length parameter is a pointer to an integer variable containing the PIN length for those
PIN-calculation methods with variable-length PINs. Otherwise, the variable should be valued to 0.
data_array
which are equivalent to a single 48-byte string. The values in the data array depend on the keyword
for the PIN-calculation method. Each element is not always used, but you must always declare a
complete data array, see PIN verb data_array variable on page 432.
The numeric characters in each 16-byte string must be from 1 - 16 bytes in length, uppercase,
left-aligned, and padded on the right with space characters. The verb converts the space characters to
zeros.
PIN_profile
The PIN_profile parameter is a pointer to a string variable containing the PIN profile including the
PIN-block format. See PIN profile on page 433.
PAN_data
The PAN_data parameter is a pointer to a string variable containing 12 digits of PAN data. The verb
uses this parameter if the PIN profile specifies ISO-0 or ISO-3 for the PIN-block format. Otherwise,
ensure that this parameter is a pointer to a 4-byte area in application storage. The information in this
variable is ignored, but this variable must be declared.
Note: When using the ISO-0 or ISO-3 keywords, use the 12 rightmost digits of the PAN data,
excluding the check digit.
sequence_number
The sequence_number parameter is a pointer to an integer variable containing a value greater than or
equal to zero.
encrypted_PIN_block
PIN-block returned by the verb.

Required commands
The Encrypted_PIN_Generate verb requires the commands, as shown in the following table, to be enabled
in the active role based on the keyword specified for the PIN-calculation methods.

IBM-PIN X'00B0' Generate Formatted and Encrypted
3624 PIN
GBP-PIN X'00B1' Generate Formatted and Encrypted
German Bank Pool PIN
INBK-PIN X'00B2' Generate Formatted and Encrypted
InterBank PIN
An enhanced PIN security mode is available for formatting an encrypted PIN block into IBM 3621 or 3624
format using the PADDIGIT PIN-extraction method. This mode limits checking of the PIN to decimal digits,
and a minimum PIN length of 4 is enforced; no other PIN-block consistency checking will occur. To
activate this mode, enable the Enhanced PIN Security Mode command (offset X'0313') in the active role.
| coprocessor. The INBK-PIN PIN-calculation method does not have a decimalization_table element and is
| therefore not affected by this command.

Encrypted_PIN_Translate (CSNBPTR)
The Encrypted_PIN_Translate verb changes (translates) PIN-block encryption and, optionally, formats a
PIN into a different PIN-block format (reformats). You can use this verb in an interchange-network
application, or to change the PIN block to conform to the format and encryption key used in a
PIN-verification database. With this verb you can also use derived unique-key-per-transaction (UKPT)
PIN-block encryption (ANS X9.24) for both input and output PIN blocks.
You can specify these PIN-block formats:

v IBM 3624
v ISO-2
The verb operates in one of two modes:

v In translate mode the verb decrypts a PIN block using an input key that you supply, or that is derived
from other information that you supply. The cleartext information is then encrypted using an output key
that you supply, or that is derived from other information that you supply. The cleartext is not examined.
v In reformat mode the verb performs the translate-mode functions and, in addition, processes the
cleartext information. Following rules that you specify, the PIN is recovered from the input cleartext
PIN-block and formatted into an output PIN-block for encryption.
To use this verb, specify the following information:

v The mode of operation with a keyword in the rule array: TRANSLAT or REFORMAT.
v Optionally, the method of PIN extraction with a rule-array keyword.
v Optionally, UKPT option on input or output with rule-array keywords: UKPTIPIN, UKPTOPIN, or
UKPTBOTH for Single-DES method, or DUKPT-IP, DUKPT-OP, or DUKPT-BH for Triple-DES method.
v Input and output PIN-block encrypting keys, or the base keys used to derive the PIN-block enciphering
keys.
v Input and output PIN profiles, which for UKPT processing are extended to 48 bytes with a 24-byte
current-key serial number (CKSN) extension. See PIN profile on page 433 and Derived
unique-key-per-transaction calculation method on page 704.
v Input and output PAN data as required by the selected PIN-block formats.
v An output PIN-block sequence number. Specify a value of 99999.

v Decrypts the input PIN-block by using the supplied IPINENC key in ECB mode, or derives the
decryption key using the specified KEYGENKY key and CKSN, and then uses ANS X9.24-specified
special decryption or Triple-DES method.
v Checks the control vector to ensure that for an IPINENC key that the TRANSLAT bit (CV bit 21) is set
to B'1' for translate mode and the REFORMAT bit (CV bit 22) is set to B'1' for reformat mode, or for a
KEYGENKY key that the UKPT bit (CV bit 18) is . Likewise the OPINENC key must have one or both of
the TRANSLAT and REFORMAT bits set according to the requested mode.
v In reformat mode, the verb performs these additional steps:
Extracts the PIN from the specified PIN-block format using the method specified by default or by a
rule-array keyword. If required by the PIN-block format, PAN data is used in the extraction process.
Formats the extracted-PIN into the format declared for the output PIN-block. As required by the
PIN-block format, the verb incorporates PAN data, sequence number, and pad character information
in formatting the output.
v Encrypts the output PIN-block by using the supplied OPINENC key in ECB mode, or derives the
decryption key using the specified KEYGENKY key and output CKSN and uses ANS X9.24-specified

special encryption or Triple-DES method. The TRANSLAT bit must be set to B'1' in the OPINENC
control vector, or the UKPT bit must be set to B'1' in the KEYGENKY control vector.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Some CCA implementations might enforce a specific order of the rule array keywords with this verb.
See the product-specific literature for more information.
v Enabling the Enforce ANS X9.8 PIN Rules command (offset X'0350'), Enforce ANS X9.8 PIN Rules and
Disallow Use of Non-ISO PINS command (offset X'0352'), or the Allow Change or PAN with ANS X9.8
PIN Rules command (offset X'0351') in the active role has no effect on access control in releases
before Release 4.1.
Format
CSNBPTR
input_PIN_encrypting_key_identifier Input String 64 bytes
output_PIN_encrypting_key_identifier Input String 64 bytes
input_PIN_profile Input String array 24 or 48 bytes
input_PAN_data Input String 12 bytes
input_PIN_block Input String 8 bytes
output_PIN_profile Input String array 24 or 48 bytes
output_PAN_data Input String 12 bytes
sequence_number Input Integer 99999
output_PIN_block Output String 8 bytes
Parameters

input_PIN_encrypting_key_identifier
The input_PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an
operational fixed-length DES key-token or a key label of an operational fixed-length DES key-token
record.
If you do not use the UKPT process or you specify the UKPTOPIN or DUKPT-OP rule-array keyword,
the key token must contain the input PIN-block encrypting key to be used to decrypt the input
PIN-block. The control vector in the key token must specify the IPINENC key-type and have one or
both of the TRANSLAT and REFORMAT bits set to B'1' as appropriate for the requested mode.
If you use the UKPT process for the input PIN-block by specifying the UKPTIPIN, UKPTBOTH,
DUKPT-IP, or DUKPT-BH rule-array keyword, specify the base derivation key as a KEYGENKY
key-type with the UKPT bit set to B'1'.
output_PIN_encrypting_key_identifier
The output_PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an
operational key-token or a key label of an operational key-token record.
If you do not use the UKPT process or you specify the UKPTOPIN or DUKPT-OP rule-array keyword,
the key token must contain the output PIN-block encrypting key to be used to encrypt the output PIN
block. The control vector in the key token must specify the OPINENC key type and have one or both
of the TRANSLAT and REFORMAT bits set to B'1' as appropriate for the requested mode.
If you use the UKPT process for the output PIN-block by specifying the UKPTIPIN, UKPTBOTH,
DUKPT-IP, or DUKPT-BH rule-array keyword, specify the base derivation key as a KEYGENKY
key-type with the UKPT bit set to B'1'.
input_PIN_profile
The input_PIN_profile parameter is a pointer to a string variable containing three 8-byte character
strings with information defining the PIN-block format and, optionally, an additional 24 bytes containing
the input CKSN extension. The strings are equivalent to 24-byte or 48-byte strings.
input_PAN_data
The input_PAN_data parameter is a pointer to a string variable containing the PAN data. The verb
uses this data to recover the PIN from the PIN block if you specify the REFORMAT keyword and the
input PIN profile specifies the ISO-0 or ISO-3 keyword for the PIN-block format.
Note: When using the ISO-0 or ISO-3 PIN-block format, use the 12 rightmost digits of PAN, excluding
the check digit.
input_PIN_block
The input_PIN_block parameter is a pointer to a string variable containing the encrypted PIN-block.
rule_array_count
in the rule_array variable. This value must be 1, 2, or 3.
rule_array

Keyword Meaning
Mode (one required)
TRANSLAT Specifies that only PIN-block encryption is changed.
REFORMAT Specifies that either or both the PIN-block format and the PIN-block encryption are to be
changed.
If the PIN-extraction method is not chosen by default, another element in the rule array must
specify one of the keywords that indicates a PIN-extraction method as listed in Table 60. For
more information about extraction methods, see PIN-extraction methods on page 435.
Unique key per transaction (one, optional)
UKPTIPIN Specifies the use of UKPT input-key derivation and PIN-block decryption, Single-DES
method.
UKPTOPIN Specifies the use of UKPT output-key derivation and PIN-block encryption, Single-DES
method.
UKPTBOTH Specifies the use of UKPT key-derivation and PIN-block ciphering for both input and output
processing, Single-DES method.
DUKPT-IP Specifies the use of UKPT input-key derivation and PIN-block decryption, Triple-DES
method.
DUKPT-OP Specifies the use of UKPT output-key derivation and PIN-block encryption, Triple-DES
method.
DUKPT-BH Specifies the use of UKPT key-derivation and PIN-block ciphering for both input and output
processing, Triple-DES method.
PIN-extraction method (one, optional)
See Table 60.
Table 60. Encrypted_PIN_Translate PIN-extraction method rule_array keywords

PIN-block format PIN-extraction method Meaning
Note: You specify the PIN-block format keyword in the PIN_profile variable.
3624 HEXDIGIT Specifies a PIN-extraction method for an IBM
PADDIGIT 3624 PIN-block format. PADDIGIT is the default
PADEXIST PIN-extraction method for the 3624 PIN-block
PINLEN04 PINLEN16 format.
an ISO-3 PIN-block format. (Release 3.30 or
later)
output_PIN_profile
The output_PIN_profile parameter is a pointer to a string variable containing three 8-byte character
strings with information defining the PIN-block format, and, optionally, an additional 24 bytes containing
the output CKSN extension. The strings are equivalent to 24-byte or 48-byte strings.
output_PAN_data
The output_PAN_data parameter is a pointer to a string variable containing the personal account

number (PAN) data. If you specify the REFORMAT keyword, and if the output PIN-profile specifies the
ISO-0 or ISO-3 PIN-block format, the verb uses this data to format the output PIN-block. Otherwise,
ensure that this parameter points to a 12-byte area in application storage.
Note: When using the ISO-0 or ISO-3 PIN-block format, use the 12 rightmost digits of PAN, excluding
the check digit.
sequence_number
The sequence_number parameter is a pointer to an integer variable containing the sequence number.
Ensure that this parameter is a pointer to an integer variable valued to 99999.
output_PIN_block
The output_PIN_block parameter is a pointer to a string variable containing the reenciphered and,
optionally, reformatted PIN-block returned by the verb.
Required commands
The Encrypted_PIN_Translate verb requires the commands shown below to be enabled in the active role
based on the keyword specified for translation or reformatting and the format control in the PIN profile. You
should enable only those commands that are required.
Rule-array keyword Input profile format Output profile Offset Command

control keyword format control
keyword
TRANSLAT NONE NONE X'00B3' Translate PIN with No
Format-Control to No
Format-Control
REFORMAT NONE NONE X'00B7' Reformat PIN with No
Format-Control to No
Format-Control
The Encrypted_PIN_Translate verb also requires the Unique Key Per Transaction, ANS X9.24 command
(offset X'00E1') to be enabled if you employ UKPT processing.
Note: A role with offset X'00E1' enabled can also use the Encrypted_PIN_Verify verb with UKPT
processing.
and formatting an encrypted PIN block into IBM 3621 or 3624 format using the PADDIGIT PIN-extraction
method. This mode limits checking of the PIN to decimal digits, and a minimum PIN length of 4 is
enforced; no other PIN-block consistency checking will occur. To activate this mode, enable the Enhanced
PIN Security Mode command (offset X'0313') in the active role.
The verb returns an error indicating that the PAD digit is not valid if all of these conditions are met:
1. The Enhanced Security Mode command is enabled in the active role
2. The output PIN profile specifies 3621 or 3624 as the PIN-block format
3. The output PIN profile specifies a decimal digit (0 - 9) as the PAD digit
Beginning with Release 4.1, three new commands are added (offsets X'0350', X'0351', and X'0352').
These three commands affect how PIN processing is performed as described below:
1. Enable the Enforce ANS X9.8 PIN Rules command (offset X'0350') in the active role to apply additional
restrictions to PIN processing as follows:
v Do not translate or reformat a non-ISO PIN block into an ISO PIN block. Specifically, do not allow
an IBM 3624 PIN-block format in the output_PIN_profile variable when the PIN-block format in the
input_PIN_profile variable is not IBM 3624.
v Constrain use of ISO-2 PIN blocks to offline PIN verification and PIN change operations in
integrated circuit card environments only. Specifically, do not allow ISO-2 input or output PIN blocks.

v Do not translate or reformat a PIN-block format that includes a PAN into a PIN-block format that
does not include a PAN. Specifically, do not allow an ISO-1 PIN-block format in the
output_PIN_profile variable when the PIN-block format in the input_PIN_profile variable is ISO-0, or
ISO-3.
v Do not allow a change of PAN data. Specifically, when performing translations between PIN block
formats that both include PAN data, do not allow the input_PAN_data and output_PAN_data
variables to be different from the PAN data enciphered in the input PIN block.
Note: A role with offset X'0350' enabled also affects access control of the
Clear_PIN_Generate_Alternate and Secure_Messaging_for_PINs verbs.
2. Enable the Allow Change of PAN with ANS X9.8 PIN Rules command (offset X'0351') in the active role
to override the restriction to not allow a change of PAN data. This override is applicable only when
either the Enforce ANS X9.8 PIN Rules command (offset X'0350') or the Enforce ANS X9.8 PIN Rules
and Disallow use of Non-ISO PINs command (offset X'0352') or both are enabled in the active role.
This override is to support account number changes in issuing environments. Offset X'0351' has no
effect if neither offset X'0350' nor offset X'0352' is enabled in the active role.
Secure_Messaging_for_PINs verb.
3. Enable the Enforce ANS X9.8 PIN Rules and Disallow use of Non-ISO PINs command (offset X'0352')
in the active role to apply a more restrictive variation of the Enforce ANS X9.8 PIN Rules command
(offset X'0350'). In addition to the previously described restrictions of offset X'0350', this command also
restricts the input_PIN_profile and the output_PIN_profile to contain only ISO-0, ISO-1, and ISO-3 PIN
block formats. Specifically, the IBM 3624 PIN-block format is not allowed with this command. Offset
X'0352' overrides offset X'0350'.
Secure_Messaging_for_PINs verb.

Encrypted_PIN_Verify (CSNBPVR)
The Encrypted_PIN_Verify verb extracts a trial PIN (T-PIN) from an encrypted PIN-block and verifies this
value by comparing it to an account PIN (A-PIN) calculated by using the specified PIN-calculation method.
Certain PIN calculation methods modify the value of the A-PIN with the clear offset (O-PIN) value prior to
the comparison. The verb also supports derived unique key per transaction (UKPT) PIN-block encryption
(ANS X9.24) for decrypting the input PIN block.
You can specify the PIN-block formats:

v IBM 3624
v ISO-2

v Processing choices using rule-array keywords:
A PIN-calculation method.
Optionally, a PIN-extraction method.
Optionally, unique-key-per-transaction (UKPT) processing with the UKPTIPIN keyword for
Single-DES method or DUKPT-IP keyword for Triple-DES method.
v An input PIN-block decrypting key, or the base key used to derive the PIN-block enciphering key.
v A PIN-verifying key to be used to calculate the PIN.
v A PIN profile for the input PIN-block, which for UKPT processing must be extended from 24 bytes to 48
bytes with the current-key serial number (CKSN) extension. See PIN profile on page 433.
v When using the ISO-0 or ISO-3 PIN-block format, a PAN to be used in extracting the PIN. See
v The PIN block that contains the PIN to be verified.
v The length of the PIN to be checked if you specify the IBM-PIN or the IBM-PINO PIN calculation
methods in the rule array.
v In the data array: a decimalization table, account validation data, and for certain PIN calculation
methods, an offset value.

v Decrypts the input PIN-block by using the supplied IPINENC key in ECB mode, or derives the
decryption key using the specified KEYGENKY key and CKSN and uses ANS X9.24-specified special
decryption or Triple-DES method. The EPINVER bit must be valued to B'1' in the IPINENC control
vector, or the UKPT bit must be valued to B'1' in the KEYGENKY control vector. See PIN profile on
page 433 and Derived unique-key-per-transaction calculation method on page 704.
v Extracts the trial PIN (T-PIN) from the specified PIN-block format using the method specified by default
or by a rule array keyword. If required by the PIN-block format, PAN data or the pad digit is used in the
extraction process.
v Verifies use of a PINVER or PINGEN key type having the EPINVER bit valued to B'1' in the control
vector of the PIN-verifying key
v Calculates the account-number-based PIN (A-PIN).
v For methods that employ an offset, modifies the A-PIN value with the offset (O-PIN) value entered in the
third element of the data_array variable. The NOOFFSET bit must be valued to zero in the control
vector of the PIN-verifying key when employing the IBM 3624 PIN-offset calculation method.
v Compares the extracted trial (T-PIN) with the possibly modified account PIN (A-PIN) and reports the
results in the return_code variable. Return code 4 indicates a verification failure, while return code 0
indicates success.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v Some CCA implementations might enforce a specific order of the rule array keywords with this verb.
See the product-specific literature for more information.
Format
CSNBPVR
PIN_verifying_key_identifier Input String 64 bytes
PIN_profile Input String array 24 or 48 bytes
encrypted_PIN_block Input String 8 bytes
Parameters
key-token or a key label of an operational key-token record.
If you do not use the UKPT process, the key token must contain the input PIN-block encrypting key to
be used to decrypt the input PIN-block. The control vector in the key token must specify the IPINENC
key-type with EPINVER bit (CV bit 19) set to B'1'.
If you use the UKPT process for the input PIN-block, specify the base derivation key as a KEYGENKY
key-type with the UKPT bit (CV bit 18) set to B'1'.

PIN_verifying_key_identifier
The PIN_verifying_key_identifier parameter is a pointer to a string variable containing an operational
key-token or a key label of an operational key-token record. The key token contains the key used to
generate the account-number-based PIN (A-PIN). The control vector in the internal key-token must
specify a PINVER or PINGEN key-type with the EPINVER bit (CV bit 22) set to B'1'. If the IBM-PINO
rule-array keyword is specified, NOOFFSET (CV bit 37) must not be specified.
PIN_profile
The PIN_profile parameter is a pointer to a string variable containing three 8-byte character strings
with information defining the PIN-block format, and optionally an additional 24 bytes containing the
input CKSN extension. The strings are equivalent to 24-byte or 48-byte strings. For more information
about a PIN profile, see PIN profile on page 433.
PAN_data
The PAN_data parameter is a pointer to a string variable containing the personal account number
(PAN) data. The verb uses the PAN data to recover the PIN from the PIN block if the PIN profile
specifies the ISO-0 or ISO-3 keyword for the PIN-block format. Otherwise, ensure that this parameter
is a pointer to a 12-byte variable in application storage.
Note: When using the ISO-0 or ISO-3 PIN-block format, use the 12 rightmost PAN digits, excluding
the check digit.
encrypted_PIN_block
PIN-block.
rule_array_count
rule_array
Keyword Meaning
| PIN-calculation method (one required)
IBM-PIN Specifies to use the IBM 3624 PIN-calculation method.
IBM-PINO Specifies to use the IBM 3624 PIN-offset PIN calculation method.
| NL-PIN-1 Specifies to use the Netherlands PIN-1 calculation method.
GBP-PIN Specifies to use the IBM German Bank Pool Institution PIN-calculation method.
VISA-PVV Specifies to use the Visa PVV PIN-calculation method.
VISAPVV4 Specifies to use the Visa PVV PIN-calculation method. Acceptable PINs must be exactly four
digits in length.
INBK-PIN Specifies to use the InterBank PIN-calculation method.
Unique key per transaction (one, optional)
UKPTIPIN Specifies the use of UKPT input-key derivation and PIN-block decryption, Single-DES method.
DUKPT-IP Specifies the use of UKPT input-key derivation and PIN-block decryption, Triple-DES method.
See Table 61 on page 472.

Table 61. Encrypted_PIN_Verify PIN-extraction method rule_array keywords
PIN-block format PIN-extraction method Meaning
3624 HEXDIGIT The PIN-extraction method keywords specify a
PADDIGIT PIN-extraction method for an IBM 3624
PADEXIST PIN-block format. PADDIGIT is the default
PINLEN04 PINLEN16 PIN-extraction method for the 3624 PIN-block
format.
ISO-0 PINBLOCK Specifies to use the default PIN-extraction
method for an ISO-0 PIN-block format.
method for an ISO-3 PIN-block format (Release
3.30 or later).
PIN_check_length
The PIN_check_length parameter is a pointer to an integer variable containing the number of digits of
PIN information that the verb should verify. The verb uses the value in the variable if you specify the
IBM-PIN or IBM-PINO keyword for the PIN-calculation method. The specified number of digits is
selected from the low order (right side) of the PIN. Ensure that this parameter always points to an
integer variable in application storage.
Note: The PIN check length must be less than or equal to the PIN length and in the range from 4 -
16.
data_array
which are equivalent to a single 48-byte string. The values you specify in the data array depend on the
PIN-calculation method. Each element is not always used, but you must always declare a complete
48-byte data array.
| When using the IBM-PIN, IBM-PINO, GBP-PIN, or NL-PIN-1 keyword, identify the following elements
in the data array.
Element Description
to convert the hexadecimal digits (X'0' - X'F') of the encrypted validation data to
decimal digits (X'0' - X'9').
validation_data This 16-byte element contains 1 - 16 characters of account data. The data must be
left-aligned and padded on the right with space characters. (To conform with industry
practice, any hexadecimal character can be specified.)
| offset data When using the IBM-PINO or NL-PIN-1 keyword, this 16-byte element contains the
offset data that must be left-aligned and padded on the right with space characters.
The PIN length specifies the number of digits that are processed for the IBM-PINO or
| NL-PIN-1 PIN-calculation method. When using the IBM-PIN or GBP-PIN keyword, this
element is ignored, but must be declared.
When using the VISA-PVV or VISAPVV4 keywords, identify the following elements in the data array.
For more information about these elements, and transaction security data for the Visa PVV
PIN-calculation method, see Visa PIN-validation value PIN-calculation method on page 700.

Element Description
transaction_security_parameter This element contains 16 characters that include the following:
v One digit of key index from 1 6
v Four space characters
PVV (O-PIN) This 16-byte element contains four numeric characters, which are the
referenced PVV value. This value is followed by 12 space characters.
must be declared.
When using the INBK-PIN keyword, identify the following elements in the data array. For more
information about these elements and transaction security data for the InterBank PIN-calculation
method, see InterBank PIN-calculation method on page 700.
Element Description
transaction_security_parameter This element contains 16 numeric characters that include the following:
v A constant of 6
v A one-digit key index selector from 1 6
v Three numeric characters of validation data
must be declared.
must be declared.
Required commands
The Encrypted_PIN_Verify verb requires the following commands to be enabled in the active role, based
on the keyword specified for the PIN calculation methods.

IBM-PIN, IBM-PINO X'00AB' Verify Encrypted 3624 PIN
GBP-PIN X'00AC' Verify Encrypted German Bank Pool PIN
VISA-PVV, VISAPVV4 X'00AD' Verify Encrypted Visa PVV
INBK-PIN X'00AE' Verify Encrypted InterBank PIN
NL-PIN-1 X'0232' Verify Encrypted NL-PIN-1
The Encrypted_PIN_Verify verb also requires the Unique Key Per Transaction, ANS X9.24 command
(offset X'00E1') to be enabled in the active role if you employ UKPT processing.
Note: A role with offset X'00E1' enabled can also use the Encrypted_PIN_Translate verb with UKPT
processing.

| coprocessor. The VISA-PVV, VISAPVV4, and INBK-PIN PIN calculation methods do not have a
| decimalization_table element and are therefore not affected by this command.

PIN_Change/Unblock (CSNBPCU)
The PIN_Change/Unblock verb prepares an encrypted message-portion for communicating an original or
replacement PIN for an EMV smart card. The verb embeds the PINs in an encrypted PIN-block from
information that you supply. You incorporate the information created with the verb in a message sent to the
smart card.
The processing is consistent with the specifications provided in these documents:


v Through the optional choice of one rule-array keyword, the key-diversification process to employ in
deriving the session key used to encrypt the PIN block. See Visa and EMV-related smart card formats
and processes on page 707 for processing details.
TDES-XOR An exclusive-OR process described in Appendix G, Access-control-point codes. It is
the default.
TDESEMV2 The tree-based-diversification process with a branch factor of 2.
TDESEMV4 The tree-based-diversification process with a branch factor of 4.
v Through the required choice of one rule-array keyword, if you are providing a PIN for a smart card:
VISAPCU1 For a card without a PIN, provide the new PIN in an encrypted PIN-block in the
new_reference_PIN_block variable. The contents of the five current_reference_PIN_x
variables are ignored.
VISAPCU2 For a card with a current PIN, provide the existing PIN in an encrypted PIN-block in the
current_reference_PIN_block variable, and supply the new PIN-value in an encrypted
PIN-block in the new_reference_PIN_block variable.
v Issuer-provided master-derivation keys (MDK). The card-issuer provides two keys for diversifying the
same data:
The MAC-MDK key that you incorporate in the variable specified by the authentication_key_identifier
parameter. The verb uses this key to derive an authentication value incorporated in the PIN block.
The control vector for the MAC-MDK key must specify a DKYGENKY key type with DKYL0 (level-0),
and DMAC or DALL permissions. See Figure 37 on page 658.
The ENC-MDK key that you incorporate in the variable specified by the encryption_key_identifier
parameter. The verb uses this key to derive the PIN-block encryption key. The control vector for the
ENC-MDK key must specify a DKYGENKY key type with DKYL0 (level-0), and DMPIN or DALL
permissions.
See Visa and EMV-related smart card formats and processes on page 707, which explains the
derivation processes and PIN-block formation.
v The diversification_data_length to indicate the sum of the lengths of:
Data, 8 or 16 bytes, encrypted by the verb using the MDK keys to generate the ENC-UDK and
Unique DES Key.
The 2-byte application transfer counter (ATC). You receive the ATC value from the EMV smart card.
The optional 16-byte initial value used in the TDESEMVn processes.
Valid lengths are 10, 18, 26, and 34 bytes.
v The diversification_data variable. Concatenate the 8-byte or 16-byte data, the ATC, and optionally the
Initial Value.
The 16-bit ATC counter is processed as a two-byte string, not as an integer value.
v The new-reference PIN in an encrypted PIN block. You provide:
The key to decrypt the PIN block

The PIN block
The format information that defines how to parse the PIN block
When using an ISO-0 or ISO-3 (Release 3.30 or later) PIN-block format, personal account number
(PAN) information to enable PIN recovery from the ISO-0 or ISO-3 PIN-block format
v If you specified VISAPCU2 (because the target smart card already has a PIN), the
current_reference_PIN in an encrypted PIN block with the associated decrypting key, PIN-block format,
and PAN data. In any case, you must declare the five current_reference_PIN_x variables.
v The output_PIN_message variable to receive the encrypted PIN block for the smart card, and the length
in bytes of the PIN block (16). The PIN-block format you specify (VISAPCU1 or VISAPCU2)
corresponds to the one or two PIN values to be communicated to the smart card.
v Two variables which are reserved for future use: output_PIN_data_length (valued to zero), and an
output_PIN_data string variable (or set the associated parameter to a null pointer).
The PIN_Change/Unblock verb:

v Decrypts the MDK keys and verifies the required control vector permissions.
v Diversifies the left-most eight bytes of data using the MAC-MDK key to obtain the authentication value
for placement into the PIN block.
v Recovers the supplied PIN values provided that PIN-block encrypting keys are one of IPINENC or
OPINENC type, and the use of the specific type is authorized with the appropriate access-control
command.
v Constructs and pads the output PIN block to a 16-byte string. See Constructing the PIN-block for
transporting an EMV smart-card PIN on page 708.
v Generates the session key used to encrypt the output-PIN block using the ENC-MDK, the
key_generation_data, the ATC counter value, and the optional Initial Value.
v Triple encrypts the 16-byte padded PIN-block in ECB mode.
v Returns the encrypted, padded PIN-block in the output_PIN_message variable.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|

Format
CSNBPCU

authentication_key_identifier_length Input Integer 64
authentication_key_identifier Input String authentication_key_identifier_length bytes
encryption_key_identifier_length Input Integer 64
encryption_key_identifier Input String encryption_key_identifier_length bytes
diversification_data_length Input Integer 10, 18, 26, or 34
diversification_data Input String diversification_data_length bytes
new_reference_PIN_key_identifier_length Input Integer 64
new_reference_PIN_key_identifier Input String new_reference_PIN_key_ identifier_length bytes
new_reference_PIN_block Input String 8 bytes
new_reference_PIN_profile Input String 3*8 bytes
new_reference_PIN_PAN_data Input String 12 bytes
current_reference_PIN_key_identifier_length Input Integer 64
current_reference_PIN_key_identifier Input String current_reference_PIN_key_ identifier_length bytes
current_reference_PIN_block Input String 8 bytes
current_reference_PIN_profile Input String 3*8 bytes
current_reference_PIN_PAN_data Input String 12 bytes
output_PIN_data_length Input Integer 0
output_PIN_data Input String Can be null pointer
output_PIN_profile Input String 3*8 bytes
output_PIN_message_length In/Output Integer 16
output_PIN_message Output String output_PIN_message_length bytes
Parameters
rule_array_count
rule_array

Keyword Meaning
Diversification process (one, optional)
TDES-XOR Diversify the issuer-master-key using Triple-DES and an exclusive-OR process. This is the
default.
TDESEMV2 Diversify the issuer-master-key using the EMV tree-based function, branch factor 2. See
EMV 4.0 Book 2, Annex A1.3.1, and Visa and EMV-related smart card formats and
processes on page 707.
TDESEMV4 Diversify the issuer-master-key using the EMV tree-based function, branch factor 4.
Output PIN creation process (one required)
VISAPCU1 Create the output PIN from the new-reference PIN and the smart-card-unique, intermediate
key.
VISAPCU2 Create the output PIN from the new-reference PIN and the smart-card-unique, intermediate
key, and the current-reference PIN.
authentication_key_identifier_length
The authentication_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the authentication_key_identifier variable. The value must be 64.
authentication_key_identifier
The authentication_key_identifier parameter is a pointer to a string variable containing an operational
key-token or a key label of an operational key-token record. The key token contains the MAC-MDK
key used to diversify the data to form the authentication value. The control vector for this key must
specify a DKYGENKY key type with DKYL0 (level-0), and DMAC or DALL permissions. Both halves of
this double-length key must be unique. See Figure 37 on page 658.
encryption_key_identifier_length
The encryption_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the authentication_key_identifier variable. The value must be 64.
encryption_key_identifier
The encryption_key_identifier parameter is a pointer to a string variable containing an operational
key-token or a key label of an operational key-token record. The key token contains the ENC-MDK key
used to diversify the data to form the output PIN-block encryption key. The control vector for this key
must specify a DKYGENKY key type with DKYL0 (level-0), and DMPIN or DALL permissions. Both
halves of this double-length key must be unique.
diversification_data_length
The diversification_data_length parameter is a pointer to an integer variable containing the number of
bytes of data in the diversification_data variable. With the TDES-XOR keyword, use a length of 10 or
18. With the TDESEMV2 and TDESEMV4 keywords, use a length of 10, 18, 26, or 34.
diversification_data
The diversification_data parameter is a pointer to a string variable. This data is used in the generation
of the authentication value and the PIN-block encryption key. Form the variable by concatenating two
or three values:
v The first 8 or 16 bytes of data contains the value used to form the smart-card-specific authentication
value and the PIN-block encryption key.
v The next two bytes of data contain the 16-bit ATC counter used to further diversify the ENC-MDK
key to form the session key used to encrypt the output PIN block. The high-order counter bit is in
the left-most counter byte.
v When using the TDESEMV2 or TDESEMV4 tree-based diversification process, you can concatenate
an optional 16-byte Initial Value. (Otherwise the verb substitutes 16 bytes of X'00'.)
new_reference_PIN_key_identifier_length
The new_reference_PIN_key_identifier_length parameter is a pointer to an integer variable containing
the number of bytes of data in the new_reference_PIN_key_identifier variable. The value must be 64.

new_reference_PIN_key_identifier
The new_reference_PIN_key_identifier parameter is a pointer to a string variable containing an
key used to decrypt the new_reference_PIN_block. The control vector for this key must specify either
an IPINENC or an OPINENC key type.
new_reference_PIN_block
The new_reference_PIN_block parameter is a pointer to a string variable containing an encrypted PIN
block which in turn contains the new_reference_PIN.
new_reference_PIN_profile
The new_reference_PIN_profile parameter is a pointer to an array of three, 8-byte string variables
which define the new_reference_PIN_block format. For more information about a PIN profile, see PIN
profile on page 433.
new_reference_PIN_PAN_data
The new_reference_PIN_PAN_data parameter is a pointer to a string variable containing the PAN
data. PAN data is used to recover a PIN from an ISO-0 or ISO-3 PIN block. If the PIN block is not in
ISO-0 or ISO-3 format, this value is ignored, but a 12-byte variable must be declared.
current_reference_PIN_key_identifier_length
The current_reference_PIN_key_identifier_length parameter is a pointer to an integer variable
containing the number of bytes of data in the current_reference_PIN_key_identifier variable. If the
VISAPCU2 rule-array keyword is used, a key must be specified and the value must be 64, else the
value must be 0.
current_reference_PIN_key_identifier
The current_reference_PIN_key_identifier parameter is a pointer to a string variable. If the VISAPCU2
rule_array keyword is present, the variable contains an operational key-token or a key label of an
operational key-token record. The key token contains the key used to decrypt the
current_reference_PIN_block. The control vector for this key must specify either an IPINENC or an
OPINENC key type.
current_reference_PIN_block
The current_reference_PIN_block parameter is a pointer to a string variable. If the VISAPCU2
rule_array keyword is present, the variable contains an encrypted PIN-block which in turn contains the
current-reference PIN.
current_reference_PIN_profile
The current_reference_PIN_profile parameter is a pointer to an array of three, 8-byte string variables.
If the VISAPCU2 rule_array keyword is present, the variables define which PIN-block format is
processed.
current_reference_PIN_PAN_data
The current_reference_PIN_PAN_data parameter is a pointer to a string variable. If the VISAPCU2
rule_array keyword is present and the PIN-profile specifies an ISO-0 or ISO-3 PIN-block format, the
variable contains the PAN data. PAN data is used to recover a PIN from an ISO-0 or ISO-3 PIN block.
output_PIN_data_length
The output_PIN_data_length parameter is a pointer to an integer variable containing the number of
bytes of data in the output_PIN_data variable. The value must be 0.
output_PIN_data
The output_PIN_data parameter is a pointer to a string variable. It should be a null pointer.
output_PIN_profile
The output_PIN_profile parameter is a pointer to a string variable containing an array of three, 8-byte
string elements. The elements define which PIN-block format is processed. Set the three 8-byte array
elements to these values:
v As per the rule array selection, the string VISAPCU1 or VISAPCU2
v Format control set to NONE (left aligned and padded on the right with space characters)

v Eight space characters
For more information about a PIN profile, see PIN profile on page 433.
output_PIN_message_length
The output_PIN_message_length parameter is a pointer to an integer variable containing the number
of bytes of data in the output_PIN_message variable. Set this variable to a value of 16 on input. On a
successful response, the verb returns the length of the output_PIN_message variable
output_PIN_message
The output_PIN_message parameter is a pointer to a string variable to receive the output encrypted,
padded PIN-block.
Required commands
The PIN_Change/Unblock verb requires the following commands to be enabled in the active role based on
the permissible key-type, IPINENC or OPINENC, used in the decryption of the input PIN blocks.
PIN-block Offset Command Comment

encrypting
key-type
OPINENC X'00BC' Generate PIN Change Required if either the new_reference_PIN_key or the
Using OPINENC current_reference_PIN_key are permitted to be an
OPINENC key type.
IPINENC X'00BD' Generate PIN Change Required if either the new_reference_PIN_key or the
Using IPINENC current_reference_PIN_key are permitted to be an
IPINENC key type.
When a MAC-MDK or an ENC-MDK of key type DKYGENKY is specified with control vector bits (19 22)
of B'1111', the Generate Diversified Key (DALL with DKYGENKY Key Type) command (offset X'0290')
must also be enabled in the active role.
Note: A role with offset X'0290' enabled can also use the Diversified_Key_Generate verb with a DALL
key.

Secure_Messaging_for_Keys (CSNBSKY)
Use the Secure_Messaging_for_Keys verb to decrypt a DES key that you supply, for incorporation into a
text block that you also supply. The text block is then encrypted within the verb to preserve the security of
the key value. The encrypted text block, normally the value field in a TLV item, can be incorporated into a
message sent to an EMV smart card.

v Visa Integrated Circuit Card Specification Manual, Version 1.4.0.
Specify the following information:

v Whether the text block is to be CBC or ECB encrypted.
v The input DES key to be included within the encrypted text block. The input key can be an operational
key (encrypted under the DES master key), or an external key, in which case you also provide the
operational IMPORTER or EXPORTER DES key required to decipher the input key. You also specify the
length of this key using the key_field_length variable.
v The DES SECMSG key to encipher the secure message text block, the secmsg_key_identifier.
v The cleartext variable to be encrypted along with its length and the offset within the block for placement
of the decrypted input_key_identifier key. The text you supply must be a multiple of eight bytes.
You also supply the encryption initialization_vector and the variable for receiving the initialization vector
for encrypting additional message text. The supplied text is a portion of a larger message you are
preparing for an EMV smart card. The encrypted text must be on an 8-byte boundary within the
complete message. The initialization_vector is the encrypted eight bytes just before the text prepared
within this verb.
v The enciphered_text variable to receive the enciphered text.
The Secure_Messaging_for_Keys verb performs the following tasks:

v Recovers the input key.
v Places the deciphered input-key value within the supplied text at the specified offset.
v Encrypts the supplied text. In CBC mode, uses the supplied initialization_vector and also returns the
value to be supplied as the initialization vector when enciphering subsequent data for the EMV smart
card message using the output_chaining_vector.
v Returns the enciphered text.
Restrictions

| AIX X X X X
| IBM i X X X
| Windows X X
|
|

Format
CSNBSKY
input_key_identifier Input String 64 bytes
key_encrypting_key_identifier Input String 64 bytes
secmsg_key_identifier Input String 64 bytes
cleartext_length Input Integer Multiple of 8, 4096
key_offset Input Integer (0 is at the start of the cleartext)
key_field_length Input Integer key length, such as 8 or 16
enciphered_text Output String cleartext_length bytes
output_chaining_vector Output String 8 bytes
Parameters
rule_array_count
rule_array
Keyword Meaning
Enciphering mode (one, optional)
TDES-CBC Use CBC mode to encipher the cleartext. This is the default.
TDES-ECB Use ECB mode to encipher the cleartext.
input_key_identifier
The input_key_identifier parameter is a pointer to a string variable containing the encrypted-token or
the label of an encrypted-token record. You can identify any type of key, provided the XPORT-OK
control-vector bit is on (bit 17). You can also specify an external DATA key with an all-zero control
vector.
key_encrypting_key_identifier
The key_encrypting_key_identifier parameter is a pointer to a string variable containing the operational
IMPORTER or EXPORTER key-token or the label of an operational IMPORTER or EXPORTER
key-token record to decipher an external input_key_identifier. You can also specify a key label of a
DES key-storage record for such a key. For an internal-form input key, specify a null key-token.

secmsg_key_identifier
The secmsg_key_identifier parameter is a pointer to a string variable containing an operational
key-token or the key label of a DES operational key-token record. The control vector must specify a
SECMSG type key with the SMKEY control-vector bit (CV bit 18) set to B'1'.
cleartext_length
The cleartext_length parameter is a pointer to an integer variable containing the number of bytes in
the cleartext variable. This must be a multiple of 8 and less than or equal to 4096.
cleartext
The cleartext parameter is a pointer to a text string variable containing the cleartext to be updated and
encrypted.
The initialization_vector parameter is a pointer to a string variable containing the CBC-encryption
initialization vector. The data is to be exclusive-ORed with the first eight bytes of the message. This
can be a null pointer when ECB mode is specified in the rule array.
key_offset
The key_offset parameter is a pointer to an integer variable containing the offset of the location for the
decrypted input key. The start of the text is an offset of 0. The offset plus the key-offset value must be
less than or equal to the value of the cleartext_length variable.
key_field_length
The key_field_length parameter is a pointer to an integer variable containing the length of key
information to be inserted into the text message. Use a length of 8 for a single-length key and a length
of 16 for a double-length key.
enciphered_text
The enciphered_text parameter is a pointer to a string variable to receive the enciphered-text
message.
output_chaining_vector
The output_chaining_vector parameter is a pointer to a string variable to receive the CBC chaining
value. This is the same as the last eight bytes of returned text and is used as an initialization_vector
when encrypting subsequent data for a message. This can be a null pointer when ECB mode is
specified in the rule array.
Required commands
The Secure_Messaging_for_Keys verb requires the Secure Messaging for Keys command (offset X'0273')

Secure_Messaging_for_PINs (CSNBSPN)
Use the Secure_Messaging_for_PINs verb to decrypt an encrypted PIN block, reformat the PIN-block, and
incorporate the reformatted PIN-block into a text block that you supply. The text block is then encrypted
within the verb to preserve the security of the PIN value. The encrypted text block, normally the value field
in a Tag, Length, Value (TLV) item, can be incorporated into a message sent to an EMV smart card. TLV is
defined in ISO 7816-4.

v Visa Integrated Circuit Card Specification Manual, Version 1.4.0.
Specify the following information:

v Whether the text block is to be CBC or ECB encrypted.
v Whether the PIN block is to be self-encrypted.
v The encrypted input_PIN_block.
v The key to decipher the input_PIN_block.
v The PIN profile for the input_PIN_block.
v When the PIN profile specifies an ISO-0 or ISO-3 (Release 3.30 or later) PIN-block format, the PAN
data to recover the PIN.
v The key to encipher the secure message text block.
v The PIN profile for the PIN-block included within the output message.
v When the PIN profile specifies an ISO-0 or ISO-3 (Release 3.30 or later) PIN-block format, the PAN
data to obscure the PIN.
v The cleartext to be encrypted along with its length and the offset within the block for placement of the
PIN block. The text you supply must be a multiple of 8 bytes, with a maximum of 4096 bytes.
v You also supply the encryption initialization_vector and the variable for receiving the initialization vector
for encrypting additional message text. The supplied text is a portion of a larger message you are
preparing for an EMV smart card. The encrypted text must be on an 8-byte boundary within the
complete message. The initialization_vector is the encrypted 8 bytes just before the text prepared within
this verb.
v The variable to receive the enciphered text.
v The variable to receive a copy of the last 8 bytes of enciphered text. This can be used as an
initialization vector for enciphering subsequent message text.
The Secure_Messaging_for_PINs verb performs the following tasks:

v Deciphers the input PIN block.
v Reformats the PIN block when the input and output PIN-block formats differ.
v Self-encrypts the output PIN block as specified.
v Places the PIN block within the supplied text at the specified offset.
v Encrypts the updated text. In CBC mode, uses the supplied initialization_vector and also returns the
value to be supplied as the initialization vector when enciphering subsequent data for the EMV smart
card message (the output_chaining_vector).
v Returns the enciphered text.

Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
v Enabling the Enforce ANS X9.8 PIN Rules command (offset X'0350'), Enforce ANS X9.8 PIN Rules and
Disallow Use of Non-ISO PINS command (offset X'0352'), or the Allow Change or PAN with ANS X9.8
PIN Rules command (offset X'0351') in the active role has no effect on access control in releases
before Release 4.1.
Format
CSNBSPN
input_PIN_block Input String 8 bytes
input_PIN_profile Input String 3 * 8 bytes
input_PAN_data Input String 12 bytes
secmsg_key_identifier Input String 64 bytes
output_PIN_profile Input String 3 * 8 bytes
output_PAN_data Input String 12 bytes
cleartext_length Input Integer multiple of 8, 4096
PIN_offset Input Integer (0 is at the start of the cleartext)
PIN_offset_field_length Input Integer 8
enciphered_text Output String cleartext_length bytes
output_chaining_vector Output String 8 bytes
Parameters

rule_array_count
rule_array
Keyword Meaning
Enciphering mode (one, optional)
TDES-CBC Use CBC mode to encipher the cleartext. This is the default.
TDES-ECB Use ECB mode to encipher the cleartext.
PIN encryption (one, optional)
CLEARPIN Do not encrypt the PIN block prior to encrypting the complete text message. This is the default.
SELFENC Copy the PIN-block self-encrypted to the clear PIN block within the unencrypted output
message. See PIN-block self-encryption on page 709.
input_PIN_block
The input_PIN_block parameter is a pointer to a string variable containing the encrypted input
PIN-block.
key is used to decipher the input PIN-block and must be an IPINENC key-type.
input_PIN_profile
The input_PIN_profile parameter is a pointer to a string variable containing three 8-byte character
strings with information defining the input PIN-block format. Valid PIN-block formats are ISO-0, ISO-1,
ISO-2, and ISO-3 with this verb.
input_PAN_data
The input_PAN_data parameter is a pointer to a string variable containing the input PAN data. The
verb uses the PAN data when it must output the PIN in a different PIN-block format and the input
format is ISO-0 or ISO-3. You supply the 12 rightmost PAN digits, excluding the check digit.
secmsg_key_identifier
The secmsg_key_identifier parameter is a pointer to a string variable containing an operational
fixed-length DES key-token, or the key label of an operational fixed-length DES key-token record. The
control vector must specify a SECMSG type key with the SMPIN control-vector bit (CV bit 19) set to
B'1'.
output_PIN_profile
The output_PIN_profile parameter is a pointer to a string variable containing three 8-byte character
strings with information defining the output PIN-block format. You can use PIN-block formats ISO-0,
ISO-1, ISO-2, and ISO-3 with this verb.
output_PAN_data
The output_PAN_data parameter is a pointer to a string variable containing the PAN data. The verb
uses the PAN data when it must output the PIN in a different PIN-block format and the output format is
ISO-0 or ISO-3. You supply the 12 rightmost PAN digits, excluding the check digit.
cleartext_length
The cleartext_length parameter is a pointer to an integer variable containing the number of bytes in
the cleartext variable. The value must be a multiple of 8, and less than or equal to 4096.

cleartext
The cleartext parameter is a pointer to a string variable containing the cleartext string to be updated
with a PIN block and encrypted.
The initialization_vector parameter is a pointer to a string variable containing the CBC-encryption
initialization vector. The data is to be exclusive-ORed with the first eight bytes of the text. This can be
a null pointer when ECB mode is specified in the rule array.
PIN_offset
The PIN_offset parameter is a pointer to an integer variable containing the offset to the location for the
PIN block. Specify the start of the text as offset 0. The offset plus PIN_offset_field_length must be less
than or equal to the cleartext_length variable.
PIN_offset_field_length
The PIN_offset_field_length parameter is a pointer to an integer variable. This must be a value of 8.
enciphered_text
The enciphered_text parameter is a pointer to a string variable to receive the enciphered text
message.
output_chaining_vector
The output_chaining_vector parameter is a pointer to a string variable to receive the CBC chaining
value. This is the same as the last eight bytes of returned enciphered text and can be used as an
initialization_vector when encrypting subsequent data for a message. This can be a null pointer when
ECB mode is specified.
Required commands
The Secure_Messaging_for_PINs verb requires the Secure Messaging for PINs command (offset X'0274')
Beginning with Release 4.1, three new commands are added (offsets X'0350', X'0351', and X'0352').
These three commands affect how PIN processing is performed as described below:
1. Enable the Enforce ANS X9.8 PIN Rules command (offset X'0350') in the active role to apply additional
restrictions to PIN processing as follows:
v Constrain use of ISO-2 PIN blocks to offline PIN verification and PIN change operations in
integrated circuit card environments only. Specifically, do not allow ISO-2 input or output PIN blocks.
v Do not reformat a PIN-block format that includes a PAN into a PIN-block format that does not
include a PAN.
v Do not allow a change of PAN data. Specifically, when performing translations between PIN block
formats that both include PAN data, do not allow the input_PAN_data and output_PAN_data
variables to be different from the PAN data enciphered in the input PIN block.
Clear_PIN_Generate_Alternate and Encrypted_PIN_Translate verbs.
2. Enable the Allow Change of PAN with ANS X9.8 PIN Rules command (offset X'0351') in the active role
to override the restriction to not allow a change of PAN data. This override is applicable only when
either the Enforce ANS X9.8 PIN Rules command (offset X'0350') or the Enforce ANS X9.8 PIN Rules
and Disallow use of Non-ISO PINs command (offset X'0352') or both are enabled in the active role.
This override is to support account number changes in issuing environments. Offset X'0351' has no
effect if neither offset X'0350' nor offset X'0352' is enabled in the active role.
Note: A role with offset X'0351' enabled also affects access control of the Encrypted_PIN_Translate
verb.
3. Enable the Enforce ANS X9.8 PIN Rules and Disallow use of Non-ISO PINs command (offset X'0352')
in the active role to apply a more restrictive variation of the Enforce ANS X9.8 PIN Rules command
(offset X'0350'). In addition to the previously described restrictions of offset X'0350', this command also

restricts the input_PIN_profile and the output_PIN_profile to contain only ISO-0, ISO-1, and ISO-3 PIN
block formats. Specifically, the IBM 3624 PIN-block format is not allowed with this command. Offset
X'0352' overrides offset X'0350'.
Note: A role with offset X'0352' enabled also affects access control of the Encrypted_PIN_Translate
verb.

SET_Block_Compose (CSNDSBC)
The SET_Block_Compose verb creates a SET-protocol RSA-OAEP block and DES encrypts the data
block using the SET protocols. Optionally, the verb computes the SHA-1 hash of the supplied data block
and includes this in the OAEP block. The DES_encrypted_block variable can be as many as eight bytes
longer than the data_to_encrypt variable due to padding. Ensure the DES_encrypted_block buffer is large
enough.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The maximum data block that can be supplied for DES encryption is the limit as expressed by the
Encipher verb. See Encipher (CSNBENC) on page 363.
Format
CSNDSBC
block_contents_identifier Input String 1 byte
XData_string_length Input Integer 94
XData_string Input String XData_string_length bytes
data_to_encrypt_length In/Output Integer
data_to_encrypt Input String data_to_encrypt_length bytes
data_to_hash_length Input Integer
data_to_hash Input String data_to_hash_length bytes
RSA_public_key_identifier_length Input Integer 3500
RSA_public_key_identifier Input String RSA_public_key_identifier_length bytes
DES_key_block_length In/Output Integer 0
DES_key_block In/Output String DES_key_block_length bytes
RSA-OAEP_block_length In/Output Integer 128
RSA-OAEP_block In/Output String RSA-OAEP_block_length bytes
DES_encrypted_block Output String updated data_to_encrypt_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Block type (required)
SET1.00 Specifies that the structure of the RSA-OAEP encrypted block is
defined by the SET protocol.
block_contents_identifier
The block_contents_identifier parameter is a pointer to a string variable containing a binary value that
is copied into the block contents (BC) field of the SET DB data block. The BC field indicates what data
is carried in the actual data block (ADB) and the format of any extra data in the XData_string variable.
XData_string_length
The XData_string_length parameter is a pointer to an integer variable containing the number of bytes
of data in the XData_string variable. The maximum length is 94 bytes.
XData_string
The XData_string parameter is a pointer to a string variable containing extra encrypted data within the
OAEP-processed and RSA-encrypted block. If the Xdata_string_length variable is 0, this parameter is
ignored but must still be declared.
data_to_encrypt_length
The data_to_encrypt_length parameter is a pointer to an integer variable containing the number of
bytes of data in the data_to_encrypt parameter. The maximum length is the same limit as for the
Encipher verb. On output, and if the field is of sufficient length, the variable is updated with the actual
length of the DES-encrypted data block.
data_to_encrypt
The data_to_encrypt parameter is a pointer to a string variable containing the data to be
DES-encrypted with a single-use 64-bit DES key generated by this service. The data is first padded by
this service.
data_to_hash_length
The data_to_hash_length parameter is a pointer to an integer variable containing the number of bytes
of data in the data_to_hash variable.
The hash value is an optional part of the OAEP block. No hash value is computed or inserted into the
OAEP block if the data_to_hash_length variable is 0.
data_to_hash
The data_to_hash parameter is a pointer to a string variable containing the data that is to be hashed
and included in the OAEP block.
If the data_to_hash_length variable is not zero, a SHA-1 hash value of the data_to_hash variable is
included in the OAEP block.

the verb uses with the input data.
RSA_public_key_identifier_length
The RSA_public_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the RSA_public_key_identifier variable. The maximum length is 3500 bytes.
RSA_public_key_identifier
The RSA_public_key_identifier parameter is a pointer to a string variable containing the PKA96 RSA
key-token or a key label of the PKA96 RSA key-token record with the RSA public-key used to perform
the RSA encryption of the OAEP block.
DES_key_block_length
The DES_key_block_length parameter is a pointer to an integer variable containing the number of
bytes of data in the DES_key_block variable. The value must be 0.
DES_key_block
The DES_key_block parameter is a pointer to a string variable containing the DES key-block. This
parameter must be a null pointer, or a pointer to 64 bytes of unused application storage.
RSA-OAEP_block_length
The RSA-OAEP_block_length parameter is a pointer to an integer variable containing the number of
bytes of data in the RSA-OAEP_block variable. The value must be at least 128 bytes. On output, and
if the field is of sufficient length, the variable is updated with the actual length of the RSA-OAEP_block
variable.
RSA-OAEP_block
The RSA-OAEP_block parameter is a pointer to a string variable containing the RSA-OAEP block.
chaining_vector
The chaining_vector parameter is a pointer to a string variable containing a work area that the security
server uses to carry segmented data between calls. The parameter must contain a null pointer or a
pointer to 18 bytes of unused application storage.
DES_encrypted_block
The DES_encrypted_block parameter is a pointer to a string variable containing the DES-encrypted
data block returned by the verb (cleartext was identified with the data_to_encrypt variable). The
starting address must not fall inside the data_to_encrypt area.
Required commands
The SET_Block_Compose verb requires the Compose SET Block command (offset X'010B') to be enabled
in the active role.

SET_Block_Decompose (CSNDSBD)
The SET_Block_Decompose verb decomposes the RSA-OAEP block and DES decrypts the data block in
support of the SET protocols.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The maximum data block that can be supplied for DES decryption is the limit as expressed by the
Decipher verb. See Decipher (CSNBDEC) on page 360.
Format
CSNDSBD
RSA-OAEP_block_length Input Integer 128
RSA-OAEP_block Input String RSA-OAEP_block_length bytes
DES_encrypted_data_block_length In/Output Integer
DES_encrypted_data_block Input String DES_encrypted_data_block_length bytes
RSA_private_key_identifier_length Input Integer 3500
RSA_private_key_identifier Input String RSA_private_key_identifier_length bytes
DES_key_block_length In/Output Integer 0, 64, or 128
DES_key_block In/Output String DES_key_block_length bytes
block_contents_identifier Output String 1 byte
XData_string_length In/Output Integer 94
XData_string Output String XData_string_length bytes
data_block Output String DES_encrypted_data_block_length bytes
hash_block_length In/Output Integer 20
hash_block Output String hash_block_length bytes

Parameters
rule_array_count
rule_array
Keyword Meaning
Block type (required)
SET1.00 Specifies that the structure of the RSA-OAEP encrypted block is defined by the SET 1.00
protocol.
PIN-block encryption (optional)
PINBLOCK Specifies that the OAEP block contains PIN information in the XDATA field, including an ISO-0
or ISO-3 format PIN-block.
The PIN block is encrypted using an IPINENC or OPINENC key that is contained in the
DES_key_block variable. The PIN information and the encrypted PIN-block are returned in the
XData_string variable.
RSA-OAEP_block_length
The RSA-OAEP_block_length parameter is a pointer to an integer variable containing the number of
bytes of data in the RSA-OAEP_block variable. This value must be 128 bytes.
RSA-OAEP_block
The RSA-OAEP_block parameter is a pointer to a string variable containing the RSA-OAEP block.
DES_encrypted_data_block_length
The DES_encrypted_data_block_length parameter is a pointer to an integer variable containing the
number of bytes of data in the DES_encrypted_data_block variable. The maximum length is the same
limit as for the Decipher verb. On output, the variable is updated with the actual length of the
decrypted data with padding removed.
DES_encrypted_data_block
The DES_encrypted_data_block parameter is a pointer to a string variable containing the
DES-encrypted data block.
the verb uses with the input data.
RSA_private_key_identifier_length
The RSA_private_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the RSA_private_key_identifier variable. The maximum length is 3500
bytes.
RSA_private_key_identifier
The RSA_private_key_identifier parameter is a pointer to a string variable containing the PKA96 RSA
key-token or the key label of the PKA96 RSA key-token with the RSA private-key used to perform the
RSA decryption of the OAEP block.

DES_key_block_length
The DES_key_block_length parameter is a pointer to an integer variable containing the number of
bytes of data in the DES_key_block variable. The value can be 0, 64, or 128. These three values are
used in the following way:
0 This is the normal value when the PINBLOCK keyword is not present. In this case, no DES
key data is passed as input or output.
64 This value is permitted when the PINBLOCK keyword is not present, in order to improve
compatibility with the SET_Block_Decompose verb defined for the z/OS ICSF. The
coprocessor treats this in the same way as a value of zero.
128 This is the length when the PINBLOCK keyword is present.
DES_key_block
The DES_key_block parameter is a pointer to a string variable containing the PIN encrypting key used
when the PINBLOCK keyword is present. For compatibility with the z/OS ICSF implementation of this
verb, the parameter is also allowed to point to an unused 64-byte variable in application storage when
the PINBLOCK keyword is not present.
The PIN encrypting-key token must be an internal token, and must be of type IPINENC or OPINENC.
The key token must be in the last (rightmost) 64 bytes of a 128-byte buffer. The first 64 bytes of the
buffer are reserved for future use, and should be set to X'00'.
block_contents_identifier
The block_contents_identifier parameter is a pointer to a string variable containing the block contents
(BC) field of the SET DB data block. The BC field indicates what data is carried in the actual data
block (ADB), and the format of any extra data, an XData string.
XData_string_length
The XData_string_length parameter is a pointer to an integer variable containing the number of bytes
of data in the XData_string variable. The minimum value is 94 bytes. On output, and if the field is of
sufficient length, the variable is updated with the actual length of the XData_string variable returned by
the verb.
XData_string
The XData_string parameter is a pointer to the string variable containing the extra-encrypted data
within the OAEP-processed and RSA-decrypted block.
When the XData field contains PIN information, 8 bytes of that information are an ISO-0 or ISO-3
format PIN-block in cleartext. This PIN block is enciphered using the PIN encryption-key received in
the DES_key_block variable. The enciphered PIN-block replaces the cleartext PIN-block in the
XData_string variable returned by the verb.
chaining_vector
server uses to carry segmented data between calls. The parameter must contain a null pointer or a
pointer to 18 bytes of unused application storage.
data_block
The data_block parameter is a pointer to a string variable containing the decrypted DES-encrypted
data block. The starting address must not fall inside the DES_encrypted_data_block area. Padding
characters are removed.
hash_block_length
The hash_block_length parameter is a pointer to an integer variable containing the number of bytes of
data in the hash_block variable. An error is returned if the hash_block variable is not large enough to
hold the 20-byte SHA-1 hash.
On output, this field is updated to reflect the number of bytes of hash data returned in the hash_block
variable, either 0 or 20 bytes.

hash_block
The hash_block parameter is a pointer to a string variable containing the SHA-1 hash extracted from
the OAEP block returned by the verb.
Required commands
The SET_Block_Decompose verb requires the Decompose SET Block command (offset X'010C') to be
Two additional commands must be enabled in the active role when encrypting PIN data with this verb:
v When using an IPINENC type key, SET PIN Encrypt with IPINENC (offset X'0121').
v When using an OPINENC type key, SET PIN Encrypt with OPINENC (offset X'0122').

Transaction_Validation (CSNBTRV)
With the Transaction_Validation verb you can generate and verify American Express card security codes
| (CSCs). American Express calls their codes card identification numbers, or CIDs. This verb requires an
| operational fixed-length DES key this is capable of performing a MAC operation.
The Transaction_Validation verb generates and verifies transaction values based on information from the
transaction and a cryptographic key. You select the validation method, and a mode, either the generate or
verify mode, through rule-array keywords.
| For the American Express process, the control vector supplied with the cryptographic key must indicate a
| single-length or double-length MAC or MACVER class. The control vector bits 0 - 3 can be B'0000'
| (ANY-MAC). Alternatively, you can ensure that a key is used only for the American Express CSC process
| by specifying a MAC or a MACVER-class key with control vector bits 0 - 3 valued to B'0100' (AMEX-CSC).
| The MAC generate bit must be on (CV bit 20 = B'1') if you request CSC generation and the MAC verify bit
| (CV bit 21 = B'1') must be on if you request verification. For more information about control vectors, see
| Appendix C, CCA control-vector definitions and key encryption, on page 655.
The verb returns the validation within the return code. A return code of 0 indicates the transaction has
been validated, and return code 4 indicates the transaction has not been validated.
Restrictions
| AIX X X X X
| IBM i X X X
| Windows X X
|
| v The transaction_info and validation_values variables cannot exceed 256 bytes in length. CSC codes
must be 19 bytes in length.
Format
CSNBTRV
transaction_key_identifier_length Input Integer 64
transaction_key_identifier Input String transaction_key_identifier_length bytes
transaction_info_length Input Integer 19
transaction_info Input String transaction_info_length bytes
validation_values_length In/Output Integer 3, 4, 5, or 12
validation_values In/Output String validation_values_length bytes

Parameters
rule_array_count
The rule_array_count parameter is a pointer to an integer variable containing the number of the
rule-array elements in the rule_array variable. The value must be 1 or 2.
rule_array
keywords are 8 bytes in length, left-aligned, and padded on the right with space characters, as shown
in the following table:
Keyword Meaning
Mode (one, optional)
VERIFY Specifies verification of the value presented in the validation_values variable. (This is the
default when the CSC-3, CSC-4, or CSC-5 keywords are used.)
GENERATE Specifies generation of transaction_validation values. (This is the default when the CSC-345
keyword is used.)
American Express card security codes (one required with VERIFY)
CSC-3 3-digit card security code (CSC) located on the signature panel (the default), VERIFY implied.
CSC-4 4-digit CSC located on the front of the card, VERIFY implied.
CSC-5 5-digit CSC located on the magnetic stripe, VERIFY implied.
American Express card security codes (required with GENERATE)
CSC-345 Generates 3-byte, 4-byte, 5-byte values when given an account number and an expiration date,
GENERATE implied.
transaction_key_identifier_length
The transaction_key_identifier_length parameter is a pointer to an integer variable containing the
number of bytes of data in the transaction_key_identifier variable. The value must be 64.
transaction_key_identifier
| The transaction_key_identifier parameter is a pointer to a string variable containing a key token of a
| single-length or double-length MAC or MACVER class key or a key label of a key-token record of such
| a key.
transaction_info_length
The transaction_info_length parameter is a pointer to an integer variable containing the length of the
transaction_info variable. For American Express CSC codes, this length must be 19.
transaction_info
The transaction_info parameter is a pointer to a string variable containing the concatenation of the
4-byte expiration date (in the format of YYMM) and the 15-byte American Express account number.
Provide the information in character format.
validation_values_length
The validation_values_length parameter is a pointer to an integer variable containing the length of the
validation_values variable.
validation_values
The validation_values parameter is a pointer to a string variable containing American Express CSC
values. The data is output for GENERATE and input for VERIFY.

Operation Element description Validation-values length
GENERATE and CSC-345 555554444333, where: 12
v 55555 = CSC 5 value
v 4444 = CSC 4 value
v 333 = CSC 3 value
VERIFY and CSC-3 333 = CSC 3 value 3
Required commands
The Transaction_Validation verb requires the listed commands to be enabled in the active role, depending
on the operation and card security code specified:
Operation keyword Card security code Offset Command

keyword
GENERATE CSC-345 X'0291' Generate CSC 3, 4, and 5 Values
VERIFY CSC-3 X'0292' Verify CSC 3 Values
CSC-4 X'0293' Verify CSC 4 Values
CSC-5 X'0294' Verify CSC 5 Values

|
| Chapter 9. TR-31 symmetric-key management
| This chapter is dedicated to X9 TR-31, which is defined in X9 TR-31 2010: Interoperable Secure Key
| Exchange Block Specification for Symmetric Algorithms. This chapter should be considered an extension
| of Chapter 5, AES, DES, and HMAC symmetric-key management. For additional information on
| symmetric keys, including DES control vectors, see Chapter 5, AES, DES, and HMAC symmetric-key
| management, on page 137.
| The TR-31 key block is a format defined by the ANS Standards Committee to support interchange of
| symmetric keys in a secure manner and with key attributes included in the exchanged data. Currently, this
| format supports only DES keys. AES keys are not supported.
| TR-31 is a Technical Report. This is different from a standard, which is a mandatory set of rules that must
| be followed. A Technical Report is not mandatory, but provides guidance to those who are using the
| standards. In this case, TR-31 is a companion to the standard X9.24-1, which defines requirements for key
| management performed using symmetric key techniques. TR-31 shows a method that complies with the
| various requirements that are defined in X9.24-1, and because no other specific method has been defined
| by the standards committee, the TR-31 method is becoming the apparent standard through which financial
| organizations will exchange keys.
| Prior to TR-31, there were problems with the interchange of symmetric keys. In the banking environment, it
| is very important that each symmetric key have a specific set of attributes attached to it, specifying such
| things as the cryptographic operations for which that key can be used. CCA implements these attributes in
| the form of the control vector (CV), but other vendors implement attributes in their own proprietary ways.
| Thus, if you are exchanging keys between CCA systems, you can securely pass the attributes using CCA
| functions and data structures. If, however, that same key were sent to a non-CCA system, there would be
| no secure way to do that. This is because the two cryptographic architectures have no common key format
| that could be used to pass both the key and its attributes. As a result, the normal approach has been to
| strip the attributes and send just the encrypted key, then attach attributes again at the receiving end.
| The above scenario has major security problems because it allows an insider to obtain the key without its
| designated attributes. The insider can then attach other attributes to it, thereby compromising the security
| of the system. For example, assume the exchanged key is a key-encrypting key (KEK). The attributes of a
| KEK should restrict its use to key management functions that are designed to prevent exposure of the
| keys that the KEK is used to encrypt. If that KEK is transmitted without any attributes, an attacker on the
| inside can turn the key into a type used for data decryption. Such a key can then be used to decipher all
| of the keys that were previously protected using the KEK. It is clearly very desirable to have a way of
| exchanging keys that prevents this modification of the attributes. TR-31 provides such a method.
| The TR-31 key block has a set of defined key attributes. These attributes are securely bound to the key so
| that they can be transported together between any two systems that both understand the TR-31 format.
| This is much of the reason for its gain in popularity. There are two supported cryptographic methods for
| protecting the key block. The original version of TR-31 defined a method that encrypted the key field in
| CBC mode and computed a TDES MAC over the header and key field. The encryption and MAC
| operations used different keys, created by applying predefined variants to the input key block protection
| key. This method is identified by a Key Block Version ID value of "A" (X'41'). An update to TR-31 adds a
| more modern method, identified by a Key Block Version ID value of "B" (X'42') or "C" (X'43'). The "B"
| method uses an authenticated encryption scheme and uses cryptographic key derivation methods to
| produce the encryption and MAC keys. The "C" method is exactly the same as the "A" method in terms of
| wrapping keys. However, the field values are expected to conform to the updated standard.
| Not surprisingly, TR-31 uses some key attributes that are different from those in the CCA control vector. In
| some cases, there is a one-to-one correspondence between CCA and TR-31 attributes. For these cases,
| conversion is simple and straightforward. In other cases, the correspondence is one-to-many or
| many-to-one and the application program must provide information to help the CCA verbs decide how to
499
| perform the translation between CCA and TR-31 attributes. There are also CCA attributes that simply
| cannot be represented using TR-31. CCA keys with those attributes are not eligible for conversion to
| TR-31 format.
| The TR-31 key block has these two important features:

| 1. The key is protected in such a way that it meets the "key bundling" requirements of various standards.
| These standards state that the individual 8-byte blocks of a double-length or triple-length TDES key
| must be bound in such a way that they cannot be individually manipulated. TR-31 accomplishes this
| mainly by computation of a MAC across the entire structure, excluding the MAC value itself.
| 2. Key usage attributes, defined to control how the key can be used, are securely bound to the key itself.
| This makes it possible for a key and its attributes to be securely transferred from one party to another
| while assuring that the attributes of the key cannot be modified to suit the needs of an attacker.
| Beginning with Release 4.2, CCA adds support for the management of DES keys using TR-31. Table 62
| lists the verbs described in this section. See TR-31 symmetric key management verbs for a detailed
| description of the verbs.
| Table 62. TR-31 symmetric key management verbs
| Service
| Verb Page Service Entry point location
| Key_Export_to_TR31 501 Exports a CCA external or internal fixed-length symmetric CSNBT31X E
| key-token, converting it into an external X9 TR-31 key block
| format.
| TR31_Key_Import 528 Imports an external X9 TR-31 key block, converting it into a CSNBT31I E
| CCA external or internal fixed-length symmetric key-token.
| TR31_Key_Token_Parse 551 Parses the information from the standard predefined fields of CSNBT31P S
| the TR-31 key block header without importing the key.
| TR31_Optional_Data_Build 555 Constructs the optional blocks of a TR-31 key block, one CSNBT31O S
| block at a time.
| TR31_Optional_Data_Read 558 Obtains the contents of any optional fields of a TR-31 key CSNBT31R S
| block header.
| E=cryptographic engine, S=security API host software
|
|
| TR-31 symmetric key management verbs
|

| Key_Export_to_TR31 (CSNBT31X)
| Use the Key_Export_to_TR31 verb to convert a proprietary CCA external or internal symmetric key-token
| and its attributes into a non-proprietary key block that is formatted under the rules of TR-31. After being
| exported into a TR-31 key block, the key and its attributes are ready to be interchanged with any outside
| third party who uses TR-31. The verb takes as input either an external or internal fixed-length DES
| key-token that contains a DES or Triple-DES (TDES) key, along with an internal DES EXPORTER or
| OKEYXLAT key-encrypting key used to wrap the external TR-31 key block.
| The Key_Export_to_TR31 verb is analogous to the Key_Export verb, except that Key_Export_to_TR31
| accepts an external or internal fixed-length DES key-token as input instead of only an internal fixed-length
| DES key-token, and it translates the key to an external non-CCA format instead of an external fixed-length
| DES key-token. The purpose of both verbs is to export a DES key to another party.
| An external-to-external translation would not normally be called an export or import operation. Instead, it
| would be called a key translation, and would be handled by a verb such as Key_Translate2. For practical
| reasons, the export of an external CCA DES key-token to external TR-31 format is supported by the
| Key_Export_to_TR31 verb, and the import of an external TR-31 key block to an external CCA DES
| key-token is supported by the TR31_Key_Import verb.
| Note that the Key_Export_to_TR31 verb does not support the translation of an external key from
| encipherment under one key-encrypting key to encipherment under a different key-encrypting key. When
| converting an external DES key to an external TR-31 format, the key-encrypting key used to wrap the
| external source key must be the same as the one used to wrap the TR-31 key block. If a translation of an
| external DES key from encipherment under one key-encrypting to a different key-encrypting key is desired,
| use the Key_Translate or Key_Translate2 verbs.
| Both CCA and TR-31 define key attributes that control key usage. In both cases, the usage information is
| securely bound to the key so that the attributes cannot be changed in unintended or uncontrolled ways.
| CCA maintains its DES key attributes in a control vector (CV), while a TR-31 key block uses fields: key
| usage, algorithm, mode of use, and exportability.
| Each attribute in a CCA control vector falls under one of these categories:
| 1. There is a one-to-one correspondence between the CV attribute and the TR-31 attribute. For these
| attributes, conversion is straightforward.
| 2. There is not a one-to-one correspondence between the CV attribute and the TR-31 attribute, but the
| attribute can be automatically translated when performing this export operation.
| 3. There is not a one-to-one correspondence between the CV attribute and the TR-31 attribute, in which
| case a rule-array keyword has been defined to specify which attribute is to be used in the TR-31 key
| block.
| 4. Item (1), (2), or (3) applies, but there are some attributes that are lost completely on translation (for
| example, key-generating bits in key-encrypting keys).
| 5. None of the above applies, because the key type, its attributes, or both simply cannot be reasonably
| translated into a TR-31 key block.
| The control vector is always checked for compatibility with the TR-31 attributes. It is an error if the
| specified TR-31 attributes are in any way incompatible with the control vector of the input key. In addition,
| access control points are defined that can be used to restrict the permitted attribute conversions.
| The TR-31 key block has a header that can contain optional blocks. Optional blocks become securely
| bound to the key by virtue of the MAC on the TR-31 key block. The opt_blocks parameter is provided to
| allow a complete and properly formatted optional block structure to be included as part of the TR-31 key
| block that is returned by the verb. The TR31_Optional_Data_Build (CSNBT31O) verb can be used to
| construct an optional block structure, one optional block at a time.
Chapter 9. TR-31 symmetric-key management 501

| An optional block has a two-byte ASCII block ID value that determines the use of the block. The use of a
| particular optional block is either defined by TR-31, or it has a proprietary use. An optional block that has a
| block ID with a numeric value is a proprietary block. IBM has defined its own proprietary optional block for
| the purpose of containing a CCA control vector. See TR-31 optional block data on page 629 for a
| description of the IBM-defined data.
| To include a copy of the control vector from the DES source key in an optional block of the TR-31 key
| block, specify the ATTR-CV or INCL-CV control vector transport control keyword in the rule array. If either
| optional keyword is specified, the verb copies the single-length or double-length control vector field from
| the source key into the optional data field of the TR-31 header. The TR31_Key_Import verb can later
| extract this data and use it as the control vector for the CCA key that it creates when importing the TR-31
| key block. This provides a way to use TR-31 for transport of CCA keys and to make the CCA key have
| identical control vectors on the sending and receiving nodes.
| The ATTR-CV and INCL-CV keywords both cause the control vector to be included in a TR-31 optional
| block, but each has a different purpose:
| ATTR-CV
| Causes a copy of the control vector to be included, but both the TR-31 usage and mode of use fields
| in the non-optional part of the TR-31 key block header are set to IBM proprietary values. These
| values, described in TR-31 optional block data on page 629, indicate that the usage and mode
| information are specified in the control vector of the optional block and not in the TR-31 header. The
| restrictions imposed by the setting of the relevant access control points are bypassed, and any CCA
| key can be exported as long as the export control fields in the control vector allow it.
| INCL-CV
| Causes a copy of the control vector to be included as additional detail. The resulting attributes set in
| the non-optional part of the TR-31 key block header are identical to not using either keyword except
| that the value for the number of optional blocks is increased by one. The export operation is still
| subject to the restrictions imposed by the settings of the relevant access control points.
| Restrictions
| AIX
| IBM i
| Windows
|
| v The only proprietary values for the TR-31 header fields supported by this verb are those defined and
| used by IBM CCA when carrying a control vector in an optional block in the header.
| v AES is not currently supported for TR-31 key blocks.
| v The export will be prohibited if the CCA key does not have attributes XPORT-OK (CV bit 17 = B'1') and
| T31XPTOK (CV bit 57 = B'1').

| Format
| CSNBT31X
| rule_array Input String array 8 * rule_array_count bytes
| key_version_number Input String 2 bytes
| key_field_length Input Integer
| source_key_identifier_length Input Integer 64
| source_key_identifier Input String source_key_identifier_length bytes
| unwrap_kek_identifier_length Input Integer 0
| unwrap_kek_identifier Input String unwrap_kek_identifier_length bytes
| wrap_kek_identifier_length Input Integer 64
| wrap_kek_identifier Input String wrap_kek_identifier_length bytes
| opt_blocks_length Input Integer
| opt_blocks Input String opt_blocks_length bytes
| tr31_key_block_length In/Output Integer
| tr31_key_block Output String tr31_key_block_length bytes
|
| Parameters
| rule_array_count
| in the rule_array variable. The value must be 2, 3, 4 or 5.
| rule_array
|| Keyword Meaning
| Key block protection method (one required). Specifies which version of the TR-31 key block to use for exporting the
| CCA DES key. The version defines the method by which the key block is cryptographically protected and the content
| and layout of the block.
| VARXOR-A Specifies to use the Key Variant Binding Method 2005 Edition. Corresponds to TR-31 Key
| Block Version ID of "A" (X'41').
| VARDRV-B Specifies to use the Key Derivation Binding Method 2010 Edition. Corresponds to TR-31 Key
| Block Version ID of "B" (X'42').
| VARXOR-C Specifies to use the Key Variant Binding Method 2010 Edition. Corresponds to TR-31 Key
| Block Version ID of "C" (X'43').

| Control vector transport control (one, optional). If no keyword from this group is provided, or keyword INCL-CV is
| specified, the control vector in the CCA key token identified by the source_key_identifier parameter is verified to
| agree with the TR-31 key usage and mode of key use keywords specified from the groups below.
| INCL-CV Specifies to copy the control vector from the CCA key-token into an optional proprietary block
| that is included in the TR-31 key block header. See Table 138 on page 630. The TR-31 key
| usage and mode of use fields indicate the key attributes. Those attributes, as derived from
| the keywords specified, must be compatible with the ones in the included CV. In addition, the
| export of the key must meet the translation and ACP authorizations indicated in the export
| translation table for the specified keywords. A key usage keyword and a mode of use
| keyword are required when this keyword is specified.
| ATTR-CV Same as keyword INCL-CV, except that the key usage field of the TR-31 key block (byte
| number 5 - 6) is set to the proprietary value "10" (X'3130'), and the mode of use field (byte
| number 8) is set to the proprietary value "1" (X'31'). These proprietary values indicate that
| the key usage and mode of use attributes are specified by the CV in the optional block. For
| this option, only the general ACPs regarding export are checked, not the ones relating to
| specific CCA to TR-31 translations. No key usage or mode of use keywords are allowed
| when this keyword is specified.
| TR-31 key usage value for output key (one required). Not valid if ATTR-CV keyword is specified. Only those TR-31
| usages shown are supported.
| TR-31 key
| Keyword usage CCA key types Meaning
| BDK "B0" KEYGENKY Specifies to export to a TR-31 base derivation key
| (BDK).
| You must select one mode of use keyword from

| Table 63 on page 508 with this usage keyword. The
| table shows all of the supported translations for key
| usage keyword BDK. It also shows the access control
| commands that must be enabled in the active role in
| order to use the combination of inputs shown.
| CVK "C0" MAC or DATA Specifies to export to a TR-31 CVK card verification key.

| usage keyword CVK. It also shows the access control
| ENC "D0" ENCIPHER, Specifies to export to a TR-31 data encryption key.
| DECIPHER ,
| CIPHER, or DATA You must select one mode of use keyword from
| usage keyword ENC. It also shows the access control
| KEK "K0" EXPORTER or Specifies to export to a TR-31 key-encryption or
| OKEYXLAT wrapping key.

| usage keyword KEK. It also shows the access control

| KEK-WRAP "K1" IMPORTER or Specifies to export to a TR-31 key block protection key.
| IKEXLAT
| usage keyword KEK-WRAP. It also shows the access
| control commands that must be enabled in the active
| role in order to use the combination of inputs shown.
| ISOMAC0 "M0" MAC, MACVER, Specifies to export to a TR-31 ISO 16609 MAC
| DATA, DATAM, or algorithm 1 (using TDEA) key.
| DATAMV
| usage keyword ISOMAC0. It also shows the access
| ISOMAC1 "M1" Specifies to export to a TR-31 ISO 9797-1 MAC
| algorithm 1 key.

| ISOMAC3 "M3" Specifies to export to a TR-31 ISO 9797-1 MAC
| algorithm 3 key.

| PINENC "P0" OPINENC or Specifies to export to a TR-31 PIN encryption key.
| IPINENC
| usage keyword PINENC. It also shows the access

| PINVO "V0" PINGEN or PINVER Specifies to export to a TR-31 PIN verification key or
| other algorithm.

| usage keyword PINVO. It also shows the access control
| PINV3624 "V1" Specifies to export to a TR-31 PIN verification, IBM
| 3624 key.

| usage keyword PINV3624. It also shows the access
| VISAPVV "V2" Specifies to export to a TR-31 PIN verification, VISA
| PVV key.

| usage keyword VISAPVV. It also shows the access
| EMVACMK "E0" DKYGENKY Specifies to export to a TR-31 EMV/chip issuer master
| key: application cryptograms key.

| usage keyword EMVACMK. It also shows the access
| EMVSCMK "E1" Specifies to export to a TR-31 EMV/chip issuer master
| key: secure messaging for confidentiality key.

| usage keyword EMVSCMK. It also shows the access
| EMVSIMK "E2" Specifies to export to a TR-31 EMV/chip issuer master
| key: secure messaging for integrity key.

| usage keyword EMVSIMK. It also shows the access

| EMVDAMK "E3" DATA, MAC, CIPHER, Specifies to export to a TR-31 EMV/chip issuer master
| or ENCIPHER key: data authentication code key.

| usage keyword EMVDAMK. It also shows the access
| EMVDNMK "E4" DKYGENKY Specifies to export to a TR-31 EMV/chip issuer master
| key: dynamic numbers key.

| usage keyword EMVDNMK. It also shows the access
| EMVCPMK "E5" Specifies to export to a TR-31 EMV/chip issuer master
| key: card personalization key.

| usage keyword EMVCPMK. It also shows the access
| TR-31 mode of key use (one required). Not valid if ATTR-CV keyword is specified. Only those TR-31 modes shown
| are supported.
| TR-31
| Keyword mode Usage keyword Meaning
| ENCDEC "B" ENC, KEK, Specifies both encrypt and decrypt, wrap and unwrap.
| KEK-WRAP
| DEC-ONLY "D" ENC, KEK, Specifies to decrypt and unwrap only.
| KEK-WRAP, PINENC
| ENC-ONLY "E" ENC, PINENC Specifies to encrypt and wrap only.
| GENVER "C" CVK, ISOMAC0, Specifies to both generate and verify.
| ISOMAC1, ISOMAC3,
| PINVO, PINV3624,
| VISAPVV
| GEN-ONLY "G" CVK, ISOMAC0, Specifies to generate only.
| ISOMAC1, ISOMAC3,
| PINVO, PINV3624,
| VISAPVV
| VER-ONLY "V" CVK, ISOMAC0, Specifies to verify only.
| ISOMAC1, ISOMAC3,
| PINVO, PINV3624,
| VISAPVV
| DERIVE "X" BDK, EMVACMK, Specifies that key is used to derive other keys.
| EMVSCMK,
| EMVSIMK,
| EMVDAMK,
| EMVDNMK,
| EMVCPMK

| ANY "N" BDK, PINVO, Specifies no special restrictions (other than restrictions
| PINV3624, VISAPVV, implied by the key usage).
| EMVACMK,
| EMVSCMK,
| EMVSIMK,
| EMVDAMK,
| EMVDNMK,
| EMVCPMK
| TR-31 exportability (one, optional). Use to set exportability field in TR-31 key block. Defines whether the key may be
| transferred outside the cryptographic domain in which the key is found.
| TR-31
| Keyword byte Meaning
| EXP-ANY "E" Specifies that the key in the TR-31 key block is exportable under a
| key-encrypting key in a form that meets the requirements of X9.24 Parts 1 or 2.
| Note: A TR-31 key block with a key block version ID of "B" or "C" and an
| exportability field value of "E" cannot be wrapped by a key-encrypting key that is
| wrapped in ECB mode (legacy wrap mode). This is because ECB mode does
| not comply with ANS X9.24 Part 1.
| EXP-TRST "S" Specifies that the key in the TR-31 key block is sensitive, exportable under a
| key-encrypting key in a form not necessarily meeting the requirements of X9.24
| parts 1 or 2.
| EXP-NONE "N" Specifies that the key in the TR-31 key block is non-exportable.
|
| Table 63. Export translation table for a TR-31 BDK base derivation key (BDK)
| Key block
| protection Mode of
| Key usage method CCA key type and required use
| keyword keyword control vector attributes keyword Offset Command
| BDK ("B0") VARXOR-A KEYGENKY, double length, UKPT ANY ("N") X'0180' TR31 Export - Permit
| (CV bit 18 = B'1') KEYGENKY:UKPT to B0
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| Notes:
| 1. These are the base keys from which derived unique key per transaction (DUKPT) initial keys are derived for
| individual devices such as PIN pads.
| 2. This table defines the only supported translations for this TR-31 usage. Usage must be the following:
| "B0" BDK base derivation key.
| 3. KEYGENKY keys are double length only.
|

| Table 64. Export translation table for a TR-31 CVK card verification key (CVK)
| Key block
| CVK ("C0") VARXOR-A, MAC, single or MAC generate GEN-ONLY X'0181' TR31 Export - Permit
| VARDRV-B, double length, on, MAC verify ("G") MAC/MACVER:AMEX-
| VARXOR-C AMEX-CSC (CV off (CV bits 20 - CSC to C0:G/C/V
| bits 0 - 3 = 21 = B'10')
| B'0100')
| MAC generate VER-ONLY
| off, MAC verify ("V")
| on (CV bits 20 -
| 21 = B'01')
| MAC generate GENVER
| on, MAC verify ("C")
| on (CV bits 20 -
| 21 = B'11')
| MAC, double MAC generate GEN-ONLY X'0182' TR31 Export - Permit
| length, on, MAC verify ("G") MAC/MACVER:CVV-
| CVVKEY-A (CV off (CV bits 20 - KEYA to C0:G/C/V
| bits 0 - 3 = 21 = B'10')
| B'0010')
| on (CV bits 20 -
| 21 = B'01')
| on (CV bits 20 -
| 21 = B'11')
| MAC, double MAC generate GEN-ONLY X'0183' TR31 Export - Permit
| length, ANY-MAC on, MAC verify ("G") MAC/MACVER:ANY-MAC
| (CV bits 0 - 3 = off (CV bits 20 - to C0:G/C/V
| B'0000') 21 = B'10')
| on (CV bits 20 -
| 21 = B'01')
| on (CV bits 20 -
| 21 = B'11')
| DATA, double MAC generate GEN-ONLY X'0184' TR31 Export - Permit
| length on, MAC verify ("G") DATA to C0:G/C
| off (CV bits 20 -
| 21 = B'10')
| on (CV bits 20 -
| 21 = B'11')

| Table 64. Export translation table for a TR-31 CVK card verification key (CVK) (continued)
| Security considerations:
| 1. There is asymmetry in the translation from a CCA DATA key to a TR-31 key. The asymmetry results from CCA
| DATA keys having attributes of both data encryption keys and MAC keys, while TR-31 separates data encryption
| keys from MAC keys. A CCA DATA key can be exported to a TR-31 "C0" key, provided that one or both
| applicable MAC generate and MAC verify control vector bits are on. However, a TR-31 "C0" key cannot be
| imported to the lower-security CCA DATA key, it can only be imported to a CCA key type of MAC or MACVER.
| This restriction eliminates the ability to export a CCA MAC or MACVER key to a TR-31 key and re-importing it
| back as a CCA DATA key with the capability to Encipher, Decipher, or both.
| 2. Since the translation from TR-31 usage "C0" is controlled by rule array keywords when using the
| TR31_Key_Import verb, it is possible to convert an exported CCA CVVKEY-A or CVVKEY-B key into an
| AMEX-CSC key or the other way around. This can be restricted by not enabling offsets X'015A' (TR31 Import -
| Permit C0 to MAC/MACVER:CVVKEY-A) and X'015B' (TR31 Import - Permit C0 to MAC/MACVER:AMEXCSC) at
| the same time. However, if both CVVKEY-x and AMEX-CSC translation types are required, then offsets X'015A'
| and X'015B' must be enabled. In this case, control is up to the development, deployment, and execution of the
| applications themselves.
| Notes:
| 1. Card verification keys are used for computing or verifying (against supplied value) a card verification code with
| the CVV, CVC, CVC2, and CVV2 algorithms. In CCA, this corresponds to keys used with two algorithms:
| v Visa CVV and MasterCard CVC codes are generated and verified using the CVV_Generate and CVV_Verify
| verbs. These verbs require a key type of DATA or MAC/MACVER with a subtype extension (CV bits 0 - 3) of
| ANY-MAC, single-length CVVKEY-A and single-length CVVKEY-B, and beginning with Release 4.2 a
| double-length CVVKEY-A (see CVV_Key_Combine verb). The MAC generate and the MAC verify (CV bits 20 -
| 21) key usage values must be set appropriately.
| v American Express CSC codes are generated and verified using the Transaction_Validation verb. This verb
| requires a key type of MAC or MACVER with a subtype extension of ANY-MAC or AMEX-CSC.
| "C0" CVK card verification key.
| 3. CCA and TR-31 represent CVV keys differently. This makes representations between the two incompatible. CCA
| represents the key-A and key-B keys as two 8-byte (single length) keys, while TR-31 represents these keys as
| one 16-byte (double length) key. Current Visa standards now require one 16-byte key. Beginning with Release
| 4.2, the the CVV_Generate and CVV_Verify verbs have support added to accept one 16-byte CVV key, using left
| and right key parts as key-A and key-B. See CVV_Key_Combine (CSNBCKC) on page 452. This new verb
| provides a way to combine two single-length MAC-capable keys into one double-length CVV key.
| 4. Import and export of 8-byte CVVKEY-A and CVVKEY-B MAC/MACVER keys will only be allowed using the IBM
| proprietary TR-31 usage and mode values ("10" and "1", respectively) to indicate encapsulation of the IBM control
| vector in an optional block, since the 8-byte CVVKEY-A is meaningless and useless as a TR-31 "C0" usage key
| of any mode.
|

| Table 65. Export translation table for a TR-31 data encryption key (ENC)
| Key block
| ENC ("D0") VARXOR-A, ENCIPHER, single or double ENC-ONLY X'0185' TR31 Export - Permit
| VARDRV-B, length ("E") ENCIPHER/DECIPHER/
| VARXOR-C CIPHER to D0:E/D/B
| DECIPHER, single or double DEC-ONLY
| length ("D")
| CIPHER, single or double length ENCDEC
| ("B")
| DATA, single or double length, ENCDEC X'0186' TR31 Export - Permit
| Encipher on, Decipher on (CV bits ("B") DATA to D0:B
| 18 - 19 = B'11')
| Security consideration: There is asymmetry in the translation from a CCA DATA key to a TR-31 key. The
| asymmetry results from CCA DATA keys having attributes of both data encryption keys and MAC keys, while TR-31
| separates data encryption keys from MAC keys. A CCA DATA key can be exported to a TR-31 "D0" key, provided
| that one or both applicable Encipher or Decipher control vector bits are on. However, a TR-31 "D0" key cannot be
| imported to the lower-security CCA DATA key, it can only be imported to a CCA key type of ENCIPHER,
| DECIPHER, or CIPHER. This restriction eliminates the ability to export a CCA DATA key to a TR-31 key and
| re-importing it back as a CCA DATA key with the capability to MAC generate and MAC verify.
| Notes:
| 1. Data encryption keys are used for the encryption and decryption of data.
| "D0" Data encryption
|
|

| Table 66. Export translation table for a TR-31 key encryption or wrapping, or key block protection key (KEK or
| KEK-WRAP)
| Key block
| KEK ("K0") VARXOR-A, EXPORTER, double length, ENC-ONLY X'0187' TR31 Export - Permit
| VARDRV-B, EXPORT on (CV bit 21 = B'1') ("E") EXPORTER/OKEYXLAT
| VARXOR-C to K0:E
| OKEYXLAT, double length
| IMPORTER, double length, DEC-ONLY X'0188' TR31 Export - Permit
| IMPORT on (CV bit 21 = B'1') ("D") IMPORTER/IKEYXLAT to
| K0:D
| IKEYXLAT, double length
| KEK-WRAP VARDRV-B, EXPORTER, double length, ENC-ONLY X'0189' TR31 Export - Permit
| ("K1") VARXOR-C EXPORT on (CV bit 21 = B'1') ("E") EXPORTER/OKEYXLAT
| to K1:E
| OKEYXLAT, double length
| IMPORTER, double length, DEC-ONLY X'018A' TR31 Export - Permit
| IMPORT on (CV bit 21 = B'1') ("D") IMPORTER/IKEYXLAT to
| K1:D
| IKEYXLAT, double length
| Security consideration: The CCA OKEYXLAT, EXPORTER, IKEYXLAT, or IMPORTER KEK translation to a TR-31
| "K0" key with mode "B" (both wrap and unwrap) is not allowed for security reasons. Even with access-control point
| control, this capability would give an immediate path to turn a CCA EXPORTER key into a CCA IMPORTER key, and
| the other way around.
| Notes:
| 1. Key encryption or wrapping keys are used only to encrypt or decrypt other keys, or as a key used to derive keys
| that are used for that purpose.
| 2. This table defines the only supported translations for this TR-31 usage. Usage must be one of the following:
| "K0" Key encryption or wrapping
| "K1" TR-31 key block protection key
| 3. CCA mode support is the same for version IDs "B" and "C". That is because the distinction between TR-31 "K0"
| and "K1" does not exist in CCA keys. CCA does not distinguish between targeted protocols, and so there is no
| good way to represent the difference. Also note that most wrapping mechanisms now involve derivation or key
| variation steps.
|

| Table 67. Export translation table for a TR-31 ISO MAC algorithm key (ISOMACn)
| Key block
| ISOMAC0 VARXOR-A, MAC, double length, MAC GEN-ONLY X'018B' TR31 Export - Permit
| ("M0") VARDRV-B, generate on (CV bit 20 = B'1') ("G") MAC/DATA/DATAM to
| VARXOR-C M0:G/C
| DATA, double length, MAC
| generate on (CV bit 20 = B'1')
| MAC, double length, MAC GENVER
| generate on, MAC verify on (CV ("C")
| bits 20 - 21 = B'11')
| DATAM, double length, MAC
| generate on, MAC verify on (CV
| bits 20 - 21 = B'11')
| DATA, double length, MAC
| generate on, MAC verify on (CV
| bits 20 - 21 = B'11')
| MACVER, double length, MAC VER-ONLY X'018C' TR31 Export - Permit
| generate off, MAC verify on (CV ("V") MACVER/DATAMV to
| bits 20 - 21 = B'01') M0:V
| DATAMV, double length, MAC
| generate off, MAC verify on (CV
| bits 20 - 21 = B'01')
| ISOMAC1 VARXOR-A, MAC, single or double length, GEN-ONLY X'018D' TR31 Export - Permit
| ("M1") VARDRV-B, MAC generate on (CV bit 20 = ("G") MAC/DATA/DATAM to
| VARXOR-C B'1') M1:G/C
| DATA, single or double length,
| MAC generate on (CV bit 20 =
| B'1')
| MAC, single or double length, GENVER
| MAC generate on, MAC verify on ("C")
| (CV bits 20 - 21 = B'11')
| DATAM, single or double length,
| MAC generate on, MAC verify on
| (CV bits 20 - 21 = B'11')
| (CV bits 20 - 21 = B'11')
| MACVER, single or double length, VER-ONLY X'018E' TR31 Export - Permit
| MAC generate off, MAC verify on ("V") MACVER/DATAMV to
| (CV bits 20 - 21 = B'01') M1:V
| DATAMV, single or double length,
| MAC generate off, MAC verify on
| (CV bits 20 - 21 = B'01')

| Table 67. Export translation table for a TR-31 ISO MAC algorithm key (ISOMACn) (continued)
| Key block
| ISOMAC3 VARXOR-A, MAC, single or double length, GEN-ONLY X'018F' TR31 Export - Permit
| ("M3") VARDRV-B, MAC generate on (CV bit 20 = ("G") MAC/DATA/DATAM to
| VARXOR-C B'1') M3:G/C
| MAC generate on (CV bit 20 =
| B'1')
| MAC, single or double length, GENVER
| MAC generate on, MAC verify on ("C")
| (CV bits 20 - 21 = B'11')
| DATAM, single or double length,
| (CV bits 20 - 21 = B'11')
| (CV bits 20 - 21 = B'11')
| MACVER, single or double length, VER-ONLY X'0190' TR31 Export - Permit
| MAC generate off, MAC verify on ("V") MACVER/DATAMV to
| (CV bits 20 - 21 = B'01') M3:V
| DATAMV, single or double length,
| MAC generate off, MAC verify on
| (CV bits 20 - 21 = B'01')
| separates data encryption keys from MAC keys. A CCA DATA key can be exported to a TR-31 "M0", "M1", or "M3"
| key, provided that one or both applicable MAC generate and MAC verify control vector bits are on. However, a TR-31
| "M0", "M1", or "M3" key cannot be imported to the lower-security CCA DATA key, it can only be imported to a CCA
| key type of MAC or MACVER. This restriction eliminates the ability to export a CCA MAC or MACVER key to a
| TR-31 key and re-importing it back as a CCA DATA key with the capability to Encipher, Decipher, or both.
| Notes:
| 1. MAC keys are used to compute or verify a code for message authentication.
| "M0" ISO 16609 MAC algorithm 1, TDEA
| The ISO 16609 MAC algorithm 1 is based on ISO 9797. It is identical to "M1", except that it does not
| support 8-byte DES keys.
| "M1" ISO 9797 MAC algorithm 1
| The ISO 9797 MAC algorithm 1 is identical to "M0", except that it also supports 8-byte DES keys.
| This is the X9.19 style of Triple-DES MAC.
| 3. A CCA control vector has no bits defined to limit key usage by algorithm, such as CBC MAC (TR-31 usage "M0"
| and "M1") or X9.19 (TR-31 usage "M3"). When importing a TR-31 key block, the resulting CCA key token
| deviates from the restrictions of usages "M0", "M1", and "M3". Importing a TR-31 key block which allows MAC
| generation ("G" or "C") results in a control vector with the ANY-MAC attribute rather than for the restricted
| algorithm that is set in the TR-31 key block. The ANY-MAC attribute provides the same restrictions as what CCA
| currently uses for generating and verifying MACs.
|

| Table 68. Export translation table for a TR-31 PIN encryption or PIN verification key (PINENC, PINVO, PINV3624,
| VISAPVV)
| Key block
| PINENC VARXOR-A, OPINENC, double length ENC-ONLY X'0191' TR31 Export - Permit
| ("P0") VARDRV-B, ("E") OPINENC to P0:E
| VARXOR-C
| IPINENC, double length DEC-ONLY X'0192' TR31 Export - Permit
| ("D") IPINENC to P0:D
| PINVO VARXOR-A PINVER, double length, NO-SPEC ANY ("N") X'0193' TR31 Export - Permit
| ("V0") (CV bits 0 - 4 = B'0000') (requires PINVER:NO-SPEC to V0
| both
| X'01B0' TR31 Export - Permit
| commands)
| PINGEN/PINVER to
| V0/V1/V2:N
| VARXOR-A, PINVER, double length, NO-SPEC VER-ONLY X'0193' TR31 Export - Permit
| VARDRV-B, (CV bits 0 - 4 = B'0000'), ("V") PINVER:NO-SPEC to V0
| VARXOR-C CPINGEN off, EPINGENA off,
| EPINGEN off, CPINGENA off (CV
| bits 18 - 21 = B'0000')
| VARXOR-A PINGEN, double length, NO-SPEC ANY ("N") X'0194' TR31 Export - Permit
| (CV bits 0 - 4 = B'0000') (requires PINGEN:NO-SPEC to V0
| both
| commands)
| PINGEN/PINVER to
| V0/V1/V2:N
| VARXOR-A, PINGEN, double length, NO-SPEC GEN-ONLY X'0194' TR31 Export - Permit
| VARDRV-B, (CV bits 0 - 4 = B'0000'), ("G") PINGEN:NO-SPEC to V0
| VARXOR-C EPINVER off (CV bit 22 = B'0')
| PINGEN, double length, NO-SPEC GENVER
| (CV bits 0 - 4 = B'0000'), ("C")
| EPINVER on (CV bit 22 = B'1')

| VISAPVV) (continued)
| Key block
| PINV3624 VARXOR-A PINVER, double length, NO-SPEC ANY ("N") X'0195' TR31 Export - Permit
| ("V1") or IBM-PIN/IBM-PINO (CV bits 0 - (requires PINVER:NO-SPEC/IBM-
| 4 = B'0000' or B'0001') both PIN/IBM-PINO to V1
| commands)
| PINGEN/PINVER to
| V0/V1/V2:N
| VARDRV-B, or IBM-PIN/IBM-PINO (CV bits 0 - ("V") PINVER:NO-SPEC/IBM-
| VARXOR-C 4 = B'0000' or B'0001'), CPINGEN PIN/IBM-PINO to V1
| off, EPINGENA off, EPINGEN off,
| CPINGENA off (CV bits 18 - 21 =
| B'0000')
| or IBM-PIN/IBM-PINO (CV bits 0 - (requires PINGEN:NO-SPEC/IBM-
| 4 = B'0000' or B'0001') both PIN/IBM-PINO to V1
| commands)
| PINGEN/PINVER to
| V0/V1/V2:N
| VARDRV-B, or IBM-PIN/IBM-PINO (CV bits 0 - ("G") PINGEN:NO-SPEC/IBM-
| VARXOR-C 4 = B'0000' or B'0001'), EPINVER PIN/IBM-PINO to V1
| off (CV bit 22 = B'0')
| or IBM-PIN/IBM-PINO (CV bits 0 - ("C")
| 4 = B'0000' or B'0001'), EPINVER
| on (CV bit 22 = B'1')

| Key block
| VISAPVV VARXOR-A PINVER, double length, NO-SPEC ANY ("N") X'0197' TR31 Export - Permit
| ("V2") or VISA-PVV (CV bits 0 - 4 = (requires PINVER:NO-SPEC/VISA-
| B'0000' or B'0010') both PVV to V2
| commands)
| PINGEN/PINVER to
| V0/V1/V2:N
| VARDRV-B, or VISA-PVV (CV bits 0 - 4 = ("V") PINVER:NO-SPEC/VISA-
| VARXOR-C B'0000' or B'0010'), CPINGEN off, PVV to V2
| EPINGENA off, EPINGEN off,
| CPINGENA off (CV bits 18 - 21 =
| B'0000')
| or VISA-PVV (CV bits 0 - 4 = (requires PINGEN:NO-SPEC/VISA-
| B'0000' or B'0010') both PVV to V2
| commands)
| PINGEN/PINVER to
| V0/V1/V2:N
| VARDRV-B, or VISA-PVV (CV bits 0 - 4 = ("G") PINGEN:NO-SPEC/VISA-
| VARXOR-C B'0000' or B'0010'), EPINVER off PVV to V2
| (CV bit 22 = B'0')
| or VISA-PVV (CV bits 0 - 4 = ("C")
| B'0000' or B'0010'), EPINVER on
| (CV bit 22 = B'1')

| Security notes:
| 1. It is highly recommended that the INCL-CV keyword be used when exporting PINGEN, PINVER, IPINENC or
| OPINENC keys. Using this keyword ensures that importing the TR-31 key block back into CCA will have the
| desired attributes.
| 2. TR-31 key blocks that are protected under legacy version ID "A" (keyword VARXOR-A, using the Key Variant
| Binding Method 2005 Edition) use the same mode of use "N" (keyword ANY) for PINGEN and PINVER keys. For
| version ID "A" keys only, for a given PIN key usage, enabling both the PINGEN and PINVER access-control
| points at the same time while enabling offset X'01B0' (for mode "N") is NOT recommended. In other words, for a
| particular PIN verification usage, you should not simultaneously enable the four commands shown below for that
| usage:
| Key type, mode,
| or version Offset Command
| "V0" For usage "V0", a user with the following four commands enabled in the active role can change a
| PINVER key into a PINGEN key and the other way around. Avoid simultaneously enabling these four
| commands.
| Key type PINVER X'0193' TR31 Export - Permit PINVER:NO-SPEC to V0
| Key type PINGEN X'0194' TR31 Export - Permit PINGEN:NO-SPEC to V0
| Mode ANY X'01B0' TR31 Export - Permit PINGEN/PINVER to V0/V1/V2:N
| Version VARXOR-A X'014D' TR31 Export - Permit Version A TR-31 Key Blocks
| commands.
| Key type PINVER X'0195' TR31 Export - Permit PINVER:NO-SPEC/IBM-PIN/IBM-PINO to V1
| Key type PINGEN X'0196' TR31 Export - Permit PINGEN:NO-SPEC/IBM-PIN/IBM-PINO to V1
| commands.
| Key type PINVER X'0197' TR31 Export - Permit PINVER:NO-SPEC/VISA-PVV to V2
| Key type PINGEN X'0198' TR31 Export - Permit PINGEN:NO-SPEC/VISA-PVV to V2
|
| Failure to comply with this recommendation allows changing PINVER keys into PINGEN and the other way
| around.

| Notes:
| 1. PIN encryption keys are used to protect PIN blocks. PIN verification keys are used to generate or verify a PIN
| using a particular PIN-calculation method for that key type.
| "P0" PIN encryption
| "V0" PIN verification, KPV, other algorithm
| Usage "V0" is intended to be a PIN-calculation method "other" than those defined for "V1" or "V2".
| Because CCA does not have a PIN-calculation method of "other" defined, it maps usage "V0" to the
| subtype extension of NO-SPEC (CV bits 0 - 3 = B'0000'). Be aware that NO-SPEC allows any method,
| including "V1" and "V2", and that this mapping is suboptimal.
| "V1" PIN verification, IBM 3624
| "V2" PIN verification, Visa PVV
| 3. Mode must be one of the following:
| "E" Encrypt/wrap only
| This restricts PIN encryption keys to encrypting a PIN block. May be used to create or reencipher an
| encrypted PIN block (for key-to-key translation).
| "D" Decrypt/unwrap only
| This restricts PIN encryption keys to decrypting a PIN block. Generally used in a PIN translation to
| decrypt the incoming PIN block.
| "N" No special restrictions (other than restrictions implied by the key usage)
| This is used by several vendors for a PIN generate or PIN verification key when the key block version ID
| is "A".
| "G" Generate only
| This is used for a PINGEN key that may not perform a PIN verification. This is the only mode available
| when the control vector in the CCA key-token (applicable when INCL-CV keyword is not provided) does
| NOT have the EPINVER control vector bit on.
| "V" Verify only
| This is used for PIN verification only. This is the only mode available when the control vector in the CCA
| key-token (applicable when INCL-CV is not provided) ONLY has the EPINVER control vector usage bit
| on (CV bits 18 - 22 = B'00001').
| "C" Both generate and verify (combined)
| This is the only output mode available for TR-31 when any of the CCA key-token PIN generating bits are
| on in the control vector (CPINGENA, EPINGENA, EPINGEN, or CPINGENA) in addition to the EPINVER
| bit.
|
|

| Table 69. Export translation table for a TR-31 EMV/chip issuer master-key key (DKYGENKY, DATA)
| Key block
| EMVACMK VARXOR-A DKYGENKY, double length, ANY ("N") X'0199' TR31 Export - Permit
| ("E0") DKYL0 (CV bits 12 - 14 = B'000'), DKYGENKY:DKYL0
| VARDRV-B, DERIVE
| DMAC (CV bits 19 - 22 = B'0010') +DMAC to E0
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'019A' TR31 Export - Permit
| DKYL0 (CV bits 12 - 14 = B'000'), DKYGENKY:DKYL0
| VARDRV-B, DERIVE
| DMV (CV bits 19 - 22 = B'0011') +DMV to E0
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'019B' TR31 Export - Permit
| VARDRV-B, DERIVE
| DALL (CV bits 19 - 22 = B'1111') +DALL to E0
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'019C' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'019D' TR31 Export - Permit
| VARDRV-B, DERIVE
| DMV (CV bits 19 - 22 = B'0011') +DMV to E0
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'019E' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| EMVSCMK VARXOR-A DKYGENKY, double length, ANY ("N") X'019F' TR31 Export - Permit
| VARDRV-B, DERIVE
| DDATA (CV bits 19 - 22 = B'0001') +DDATA to E1
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'01A0' TR31 Export - Permit
| VARDRV-B, DERIVE
| DMPIN (CV bits 19 - 22 = B'1001') +DMPIN to E1
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| DMPIN (CV bits 19 - 22 = B'1001') +DMPIN to E1
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| VARXOR-C ("X")

| Table 69. Export translation table for a TR-31 EMV/chip issuer master-key key (DKYGENKY, DATA) (continued)
| Key block
| EMVSIMK VARXOR-A DKYGENKY, double length, ANY ("N") X'01A5' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| EMVDAMK VARXOR-A DATA, double length ANY ("N") X'01A9' TR31 Export - Permit
| ("E3") DATA/MAC/CIPHER/
| VARDRV-B, DERIVE
| ENCIPHER to E3
| VARXOR-C ("X")
| VARXOR-A MAC (not MACVER), double ANY ("N")
| length
| VARXOR-A GEN-ONLY
| ("G")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARXOR-A CIPHER, double length ANY ("N")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARXOR-A ENCIPHER, double length ANY ("N")
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| EMVDNMK VARXOR-A DKYGENKY, double length, ANY ("N") X'01AA' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'01AB' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")

| Table 69. Export translation table for a TR-31 EMV/chip issuer master-key key (DKYGENKY, DATA) (continued)
| Key block
| EMVCPMK VARXOR-A DKYGENKY, double length, ANY ("N") X'01AC' TR31 Export - Permit
| VARDRV-B, DERIVE
| DEXP (CV bits 19 - 22 = B'0101') +DEXP to E5
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'01AD' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'01AE' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| VARXOR-A DKYGENKY, double length, ANY ("N") X'01AF' TR31 Export - Permit
| VARDRV-B, DERIVE
| VARXOR-C ("X")
| Notes:
| 1. EMV/chip issuer master-key keys are used by the chip cards to perform cryptographic operations or, in some
| cases, to derive keys used to perform operations. In CCA, these are (a) diversified key-generating keys (key type
| DKYGENKY), allowing derivation of operational keys, or (b) operational keys. Note that in this context, "master
| key" has a different meaning than for CCA. These master keys, also called KMCs, are described by EMV as DES
| master keys for personalization session keys. They are used to derive the corresponding chip card master keys,
| and not typically used directly for cryptographic operations other than key derivation. In CCA, these are usually
| key generating keys with derivation level DKYL1 (CV bits 12 - 14 = B'001'), used to derive other key generating
| keys (the chip card master keys). For some cases, or for older EMV key derivation methods, the issuer master
| keys could be level DKYL0 (CV bits 12 - 14 = B'000').
| "E0" Application cryptograms
| "E1" Secure messaging for confidentiality
| "E2" Secure messaging for integrity
| "E3" Data authentication code
| "E4" Dynamic numbers
| "E5" Card personalization
| 3. EMV support in CCA is quite different than TR-31 support, and CCA key types do not match TR-31 types.
| 4. DKYGENKY keys are double length only.
|
| key_version_number
| The key_version_number parameter is a pointer to a string variable containing two numeric ASCII
| bytes that are copied into the key version number field of the output TR-31 key block. Use a value of
| "00" (X'3030') if no key version number is needed.
| This value is ignored If the key identified by the source_key_identifier parameter contains a partial key,
| that is, the KEY-PART bit (CV bit 44) is on in the control vector. When a partial key is passed, the verb
| sets the key version number field in the TR-31 key block to "c0" (X'6330'). According to TR-31, this
| value indicates that the TR-31 key block contains a component of a key (key part).
| key_field_length
| The key_field_length parameter is a pointer to an integer variable containing the length of the key field
| that is encrypted in the TR-31 block. The length must be a multiple the DES cipher block size, which is
| eight. It must also be greater than or equal to the length of the cleartext key passed using the
| source_key_identifier parameter plus the length of the key length field (two bytes) that precedes this
| key in the TR-31 block. For example, if the source key is a double-length TDES key (its length is 16
| bytes), then the key field length must be greater than or equal to (16 + 2) bytes, and must also be a
| multiple of 8. This means that the minimum key_field_length in this case would be 24.

| TR-31 allows a variable number of padding bytes to follow the cleartext key, and the application
| designer can choose to pad with more than the minimum number of bytes needed to form a block that
| is a multiple of 8. This is generally done to hide the length of the cleartext key from those who cannot
| decipher that key. Most often, all keys (single, double, or triple length) are padded to the same length
| so that it is not possible to determine which length is carried in the TR-31 block by examining the
| encrypted block.
| Note: This parameter is not expected to allow for ASCII encoding of the encrypted data stored in the
| key field according to the TR-31 specification. For example, when a value of 24 is passed here,
| following the minimum example above, the length of the final ASCII-encoded encrypted data in
| the key field in the output TR-31 key block is 48 bytes.
| source_key_identifier_length
| The source_key_identifier_length parameter is a pointer to an integer variable containing the length in
| bytes of the source_key_identifier variable. The value must be 64.
| source_key_identifier
| The source_key_identifier parameter is a pointer to a string variable containing either the key label for
| the source key or the key token containing the source key. The source key is the key that is to be
| exported. The key must be a CCA fixed-length DES internal or external key-token. If the source key is
| an external token, an identifier for the KEK that wraps the source key must be identified by the
| unwrap_kek_identifier parameter. TR-31 currently only supports DES and TDES keys. AES is not
| supported.
| unwrap_kek_identifier_length
| The unwrap_kek_identifier_length parameter is a pointer to an integer variable containing the length in
| bytes of the unwrap_kek_identifier variable. The value must be greater than or equal to 0. A null
| key-token can have a length of 1. Set this value to 64 for a key label or a KEK.
| unwrap_kek_identifier
| The unwrap_kek_identifier parameter is a pointer to a string variable containing either the key label for
| the source key KEK or the key token containing the source key KEK when the source key is an
| external CCA key token, and a NULL key token otherwise. The source key KEK can also be the
| wrapping key for the key that is to be exported if the wrap_kek_identifier is not specified. The source
| key KEK must be a CCA internal DES KEK token of type EXPORTER or OKEYXLAT.
| Note: ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap or unwrap
| TR-31 "B" or "C" key blocks that have or will have "E" exportability, because ECB-mode does
| wrap_kek_identifier_length
| The wrap_kek_identifier_length parameter is a pointer to an integer variable containing the length in
| bytes of the wrap_kek_identifier variable. Set this value to 64.
| wrap_kek_identifier
| The wrap_kek_identifier parameter is a pointer to a string variable containing an operational
| fixed-length DES key-token with a key type of EXPORTER or OKEYXLAT to use for wrapping the
| output TR-31 key block, a null key token, or a key label of such a key in DES key-storage. If the
| identified key token is not null, the key token must have the same key that is in the key-token
| identified by the unwrap_kek_identifier parameter. If it is null, then the key identified by the
| unwrap_kek_identifier parameter is also used for wrapping the output TR-31 key block.
| Note: ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap or unwrap
| not comply with ANS X9.24 Part 1. This parameter exists to allow for KEK separation. It is
| possible that KEKs are restricted as to what they can wrap, such that a KEK for wrapping CCA
| external keys might not be usable for wrapping TR-31 external keys, or the other way around.

| opt_blocks_length
| The opt_blocks_length is a pointer to an integer variable that specifies the length in bytes of the
| opt_blocks variable. If no optional data is to be included in the TR-31 key block, set this value to zero.
| opt_blocks
| The opt_blocks parameter is a pointer to a string variable containing optional blocks data that is to be
| included in the output TR-31 key block. The optional blocks data can be constructed using the
| TR31_Optional_Data_Build verb.
| Note: The Padding Block, ID "PB" cannot be added by the user, and therefore is not accepted in the
| opt_blocks parameter. CCA adds a Padding Block of the appropriate size as needed when
| building the TR-31 key block in Key_Export_to_TR31. The Padding Block for optional blocks
| serves no security purpose, unlike the padding in the encrypted key portion of the payload.
| tr31_key_block_length
| The tr31_key_block_length parameter is a pointer to an integer variable containing the length in bytes
| of the tr31_key_block variable. On input, specify the size of the application program buffer available for
| the output key-token. On return from the verb, this variable is updated to contain the actual length of
| that returned token. TR-31 key blocks are variable in length.
| tr31_key_block
| The tr31_key_block parameter is a pointer to a string variable containing the output key block
| produced by the verb. The output key block contains the external form of the key created by the verb,
| wrapped according to the method specified.
| Note: The padding optional block in the output TR-31 key block can be present with zero data bytes.
| This is because sometimes the optional block portion of the header needs exactly four bytes of
| padding, the size of an optional block header without the data portion. The data portion is
| defined as optional by TR-31, which allows this.
| Required commands
| The Key_Export_to_TR31 verb requires the following commands to be enabled in the active role:
|| Rule-array Offset Command

| keyword
| TR-31 key block protection method
| VARXOR-A X'014D' TR31 Export - Permit Version A TR-31 Key Blocks
| VARDRV-B X'014E' TR31 Export - Permit Version B TR-31 Key Blocks
| VARXOR-C X'014F' TR31 Export - Permit Version C TR-31 Key Blocks
| INCL-CV X'0158' TR31 Export - Permit Any CCA Key if INCL-CV Is Specified
| When providing the INCL-CV keyword:

| v If this command is enabled in the active role, the key-type specific commands are
| not checked.
| v If this command is not enabled in the active role, the key-type specific commands
| are required.
| ATTR-CV N/A Note: No commands relating to specific CCA to TR-31 transitions are checked
| when this keyword is specified. Only the general access control commands
| regarding export are checked.
|
| Be aware of the interaction of access-control point X'0158' (TR31 Export - Permit Any CCA Key if INCL-CV
| Is Specified) with the INCL-CV keyword. Without the INCL-CV keyword, most export translations are
| guarded by key-type-specific access control points, to guard the source CCA system against attacks
| involving reimport of the exported key under ambiguous circumstances. When the control vector is
| exported along with the key as an optional block securely bound to the encrypted key, the source system
| is somewhat protected because the key on import is allowed to have only the form of the included control

| vector. No expansion of capability is allowed. If access-control point X'0158' is enabled in the active role,
| the key-type-specific access control points are not checked when INCL-CV is provided. If ACP X'0158' is
| not enabled, the type-specific access control points are still required. The following figure illustrates this
| concept:
|
|
| ACP X'0158'
|
is enabled
Any CCA key specified
| in active role is allowed
|
|
INCL-CV
|
| ACP X'0158'
|
is not enabled
Check key-type-specific
| in active role access control points
|
|
| Be aware of access-control point X'01B0' (TR31 Export - Permit PINGEN/PINVER to V0/V1/V2:N) for
| export of PINGEN or PINVER keys to wrapping method "A" , usage "V0", "V1", or "V2", and mode "N".
| TR-31 key blocks with legacy key usage "A" (key block protected using the Key Variant Binding Method
| 2005 Edition) use the same mode "N" for PINGEN as well as PINVER keys. For usage "A" keys only,
| enabling a PINGEN and PINVER access-control point while enabling offset X'01B0' (for keyword ANY,
| mode "N") is NOT recommended. Failure to comply with this recommendation allows changing PINVER
| keys into PINGEN and the other way around.
| In addition to the above commands, the verb requires these additional commands to be enabled in the
| active role depending on the TR-31 key usage rule-array keyword provided and additional information as
| shown in the table referenced in the rightmost column:
|| TR-31 key usage Specific key type and control
| keyword Offset Command vector attributes
| "B0": TR-31 BDK base derivation keys
| BDK X'0180' TR31 Export - Permit KEYGENKY:UKPT to B0 See Table 63 on page 508.
| "C0": TR-31 CVK card verification keys
| CVK X'0181' TR31 Export - Permit MAC/MACVER:AMEX- See Table 64 on page 509.
| CSC to C0:G/C/V
| X'0182' TR31 Export - Permit MAC/MACVER:CVV-
| KEYA to C0:G/C/V
| X'0183' TR31 Export - Permit MAC/MACVER:ANY-
| MAC to C0:G/C/V
| X'0184' TR31 Export - Permit
| "D0": TR-31 data encryption keys
| ENC X'0185' TR31 Export - Permit ENCIPHER/DECIPHER/ See Table 65 on page 511.
| CIPHER to D0:E/D/B
| X'0186' TR31 Export - Permit DATA to D0:B
| "E0", "E1", "E2", "E3", "E4", and "E5": TR-31 EMC/chip issuer master-key keys

| TR-31 key usage Specific key type and control
| EMVACMK X'0199' TR31 Export - Permit See Table 66 on page 512.
| DKYGENKY:DKYL0+DMAC to E0
| X'019A' TR31 Export - Permit
| DKYGENKY:DKYL0+DMV to E0
| X'019B' TR31 Export - Permit
| DKYGENKY:DKYL0+DALL to E0
| X'019C' TR31 Export - Permit
| X'019D' TR31 Export - Permit
| DKYGENKY:DKYL1+DMV to E0
| X'019E' TR31 Export - Permit
| EMVSCMK X'019F' TR31 Export - Permit See Table 66 on page 512.
| DKYGENKY:DKYL0+DDATA to E1
| X'01A0' TR31 Export - Permit
| DKYGENKY:DKYL0+DMPIN to E1
| DKYGENKY:DKYL1+DMPIN to E1
| EMVSIMK X'01A5' TR31 Export - Permit See Table 66 on page 512.
| EMVDAMK X'01A9' TR31 Export - Permit DATA/MAC/CIPHER/ See Table 66 on page 512.
| ENCIPHER to E3
| EMVDNMK X'01AA' TR31 Export - Permit See Table 66 on page 512.
| X'01AB' TR31 Export - Permit
| EMVCPMK X'01AC' TR31 Export - Permit See Table 66 on page 512.
| DKYGENKY:DKYL0+DEXP to E5
| X'01AD' TR31 Export - Permit
| X'01AE' TR31 Export - Permit
| X'01AF' TR31 Export - Permit
| "K0" and "K1": TR-31 key encryption or wrapping, or key block protection keys

| TR-31 key usage Specific key type and control
| KEK X'0187' TR31 Export - Permit EXPORTER/OKEYXLAT See Table 67 on page 513.
| to K0:E
| X'0188' TR31 Export - Permit IMPORTER/IKEYXLAT to
| K0:D
| KEK-WRAP X'0189' TR31 Export - Permit EXPORTER/OKEYXLAT
| to K1:E
| X'018A' TR31 Export - Permit IMPORTER/IKEYXLAT to
| K1:D
| "M0", "M1", and "M3": TR-31 ISO MAC algorithm keys
| ISOMAC0 X'018B' TR31 Export - Permit MAC/DATA/DATAM to See Table 68 on page 515.
| M0:G/C
| X'018C' TR31 Export - Permit MACVER/DATAMV to
| M0:V
| ISOMAC1 X'018D' TR31 Export - Permit MAC/DATA/DATAM to
| M1:G/C
| X'018E' TR31 Export - Permit MACVER/DATAMV to
| M1:V
| ISOMAC3 X'018F' TR31 Export - Permit MAC/DATA/DATAM to
| M3:G/C
| X'0190' TR31 Export - Permit MACVER/DATAMV to
| M3:V
| "P0", "V0", "V1": TR-31 PIN encryption or PIN verification keys
| PINENC X'0191' TR31 Export - Permit OPINENC to P0:E See Table 69 on page 520.
| X'0192' TR31 Export - Permit IPINENC to P0:D
| PINVO X'0193' TR31 Export - Permit PINVER:NO-SPEC to V0
| X'0194' TR31 Export - Permit PINGEN:NO-SPEC to V0
| X'01B0' TR31 Export - Permit PINGEN/PINVER to
| V0/V1/V2:N
| PINV3624 X'0195' TR31 Export - Permit PINVER:NO-SPEC/IBM-
| PIN/IBM-PINO to V1
| X'0196' TR31 Export - Permit PINGEN:NO-SPEC/IBM-
| PIN/IBM-PINO to V1
| V0/V1/V2:N
| VISAPVV X'0197' TR31 Export - Permit PINVER:NO-SPEC/VISA-
| PVV to V2
| X'0198' TR31 Export - Permit PINGEN:NO-SPEC/
| VISA-PVV to V2
| V0/V1/V2:N
|
|

| TR31_Key_Import (CSNBT31I)
| Use the TR31_Key_Import verb to convert a non-proprietary external key-block that is formatted under the
| rules of TR-31 into a proprietary CCA external or internal fixed-length DES key-token with its attributes in a
| control vector. After being imported into a CCA key-token, the key and its attributes are ready to be used
| in a CCA system. The verb takes as input an external TR-31 key block and the internal DES IMPORTER
| or IKEYXLAT key-encrypting key of the key that was used to wrap the TR-31 key block.
| The TR31_Key_Import verb is analogous to the existing Key_Import verb, except that TR31_Key_Import
| accepts an external non-CCA DES key-token instead of an external CCA fixed-length DES key-token, and
| it translates the key to either an external or internal fixed-length DES key-token instead of only an internal
| fixed-length DES key-token. An import by TR31_Key_Import to an external key-token requires a suitable
| internal fixed-length DES key-encrypting key. The purpose of both verbs is to import a DES key from
| another party.
| An external-to-external translation would not normally be called an export or import operation. Instead, it
| would be called a key translation and would be handled by a verb such as Key_Translate or
| Key_Translate2. For practical reasons, the export of an external CCA DES key-token to an external TR-31
| format is supported by the Key_Export_to_TR31 verb, and the import of an external TR-31 key block to an
| external CCA DES key-token format is supported by the TR31_Key_Import verb.
| Note that the TR31_Key_Import verb does not support the translation of an external key from
| encipherment under one key-encrypting key to encipherment under a different key-encrypting key. When
| converting an external TR-31 key block to an external fixed-length DES key-token, the key-encrypting key
| used to wrap the external TR-31 key block must be the same as the one used to wrap the external
| fixed-length DES key-token. Use the Key_Translate or Key_Translate2 verbs for switching external key
| wrapping keys: the normal function of those verbs.
| Both CCA and TR-31 define key attributes that control key usage. In both cases, the usage information is
| securely bound to the key so that the attributes cannot be changed in unintended or uncontrolled ways.
| CCA maintains its DES key attributes in a control vector (CV), while a TR-31 key block uses fields: key
| usage, algorithm, mode of use, and exportability.
| Each attribute in a CCA control vector falls under one of these categories:
| 1. There is a one-to-one correspondence between the CV attribute and the TR-31 attribute. For these
| attributes, conversion is straightforward.
| 2. There is not a one-to-one correspondence between the CV attribute and the TR-31 attribute, but the
| attribute can be automatically translated when performing this export operation.
| 3. There is not a one-to-one correspondence between the CV attribute and the TR-31 attribute, in which
| case a rule-array keyword has been defined to specify which attribute is to be used in the TR-31 key
| block.
| 4. Item (1), (2), or (3) applies, but there are some attributes that are lost completely on translation (for
| example, key-generating bits in key-encrypting keys).
| 5. None of the above applies, because the key type, its attributes, or both simply cannot be reasonably
| translated into a TR-31 key block.
| The control vector is always checked for compatibility with the TR-31 attributes. It is an error if the
| specified control vector attributes are in any way incompatible with the attributes of the input key. In
| addition, access control points are defined that can be used to restrict the permitted attribute conversions.
| The import operation produces the CCA external or internal fixed-length DES key-token as its output. It
| does not return any field values or optional block data from the TR-31 key block header. To obtain the
| header field values, use the TR31_Key_Token_Parse verb. To obtain optional block data from the header,
| use the TR31_Optional_Data_Read verb.

| An optional control vector transport control rule-array keyword can be passed to the Key_Export_to_TR31
| verb. Such a keyword specifies that the verb is to copy the control vector from the CCA DES key into the
| TR-31 key block. A copy of the control vector is passed in an IBM-proprietary optional block. See TR-31
| optional block data on page 629.
| If the TR-31 key block contains an IBM-proprietary block, the TR31_Key_Import verb verifies that the
| control vector is compatible with the attributes in the TR-31 key block. If any incompatibility is found, the
| verb rejects the import. If the control vector is valid for the key, the verb uses it for the control vector of the
| CCA DES key-token. Note that the import operation is always subject to the restrictions imposed by the
| relevant access control points, even if a control vector is received.
| A control vector, if present, can be in the TR-31 key block in one of two ways, depending on the control
| vector transport control keyword specified in the rule array of the Key_Export_to_TR31 verb when the key
| was exported. One keyword option is ATTR-CV, and the other is INCL-CV:
| ATTR-CV
| Causes a copy of the control vector to be included in the TR-31 key block. The TR-31 key usage and
| mode of use fields are set to IBM proprietary. See TR-31 optional block data on page 629. These
| proprietary values indicate that the usage and mode information is contained in the included control
| vector. In this case, if the TR31_Key_Import verb successfully verifies that the included control vector
| does not conflict with the rule-array keywords specified, it uses it as the control vector for the
| imported CCA DES key-token.
| INCL-CV
| Causes a copy of the control vector to be include din the TR-31 key block, and the TR-31 key usage
| and mode of use fields contain attributes from the set defined in the TR-31 standard. In this case, the
| TR31_Key_Import verb verifies that the usage and mode information in those fields are compatible
| with the included control vector. The verb also verifies that no rule array keywords conflict with the
| control vector.
| Note that the included CV could have more capability from a CCA perspective than the TR-31 usage
| and mode fields indicate. This is not an error, because the key block binding methods give the
| importer assurance that the key block optional blocks are as secure as any other attribute.
| Special notes:
| 1. Several import situations might require keywords. Keywords are ignored for INCL-CV scenarios unless
| they directly conflict with the included CV. For example, the verb returns an error if the control vector
| indicates that a DKYGENKY key has a subtype of DKYL0 and the user specifies the DKYL1 keyword.
| 2. Be aware of the interaction of ACP X'0158' (TR31 Export - Permit Any CCA Key if INCL-CV Is
| Specified) with the INCL-CV keyword for the Key_Export_to_TR31 verb. Without the INCL-CV keyword
| specified, most export translations are guarded by key type specific ACPs. This is to guard the source
| CCA system against attacks involving reimport of the exported key under ambiguous circumstances.
| When the control vector is exported in an optional block along with the key, it is securely bound to the
| encrypted key. This somewhat protects the source system because the key on import is only allowed
| to have the form of the included control vector. Expansion of capability is blocked. If ACP X'0158' is not
| enabled in the active role, the type-specific ACPs are still required. However, if ACP X'0158' is
| enabled, the key-type specific ACPs are not checked when INCL-CV is specified.
| 3. Be aware of ACP X'017C' (TR31 Import - Permit V0/V1/V2:N to PINGEN/PINVER) for import of
| PINGEN or PINVER keys to wrapping mode A, usage V0, V1, V2, and mode N.
| Examples:
| 1. A full MAC key that is exported as TR-31 "C0" key block with an included control vector will be
| re-imported as a full MAC key.
| 2. A DKYGENKY key with key usage DALL key exported as a TR-31 "E0", "E1", or "E2" key block with
| an included control vector will be re-imported as a DKYGENKY key with key usage DALL, even though
| the "E0", "E1", and "E2 types are more restricted.

| The extra translation-specific ACPs are intended to enable control of situations where the CCA imported
| key type is ambiguous based on the TR-31 key attributes. This is never the case when INCL-CV has been
| specified with the Key_Export_to_TR31 verb, which ensures that the imported TR-31 key block has a valid
| CV to precisely control the resultant CCA key. Therefore, there are no translation-specific ACPs governing
| INCL-CV import translations.
| Restrictions
| AIX
| IBM i
| Windows
|
| Format
| CSNBT31I
| tr31_key_block_length Input Integer See CSNBT31P.
| tr31_key_block Input String tr31_key_block_length bytes
| unwrap_kek_identifier_length Input Integer 64
| unwrap_kek_identifier Input String unwrap_kek_identifier_length bytes
| wrap_kek_identifier_length Input Integer 0
| wrap_kek_identifier Input String wrap_kek_identifier_length bytes
| output_key_identifier_length In/Output Integer 64
| num_opt_blocks Output Integer 0
| cv_source Output Integer See Table 77 on page 546.
| protection_method Output Integer See Table 78 on page 546.
|
| Parameters
| rule_array_count
| in the rule_array variable. The value must be 1, 2, 3, or 4.

| rule_array
| characters. The rule_array keywords are shown in the following table:
|| Keyword Meaning
| Token identifier (one required)
| INTERNAL Specifies to return the output key in an internal CCA key-token.
| EXTERNAL Specifies to return the output key in an external CCA key-token, wrapped by the transport key
| identified by the wrap_kek_identifier parameter.
| CCA output key usage subgroups (One from one subgroup required based on TR-31 input key usage. Keywords for
| the subgroup are valid only for given TR-31 key usage.)
| Note: None of the following keywords are allowed if the TR-31 key block provided as input has an optional block
| that contains a CCA control vector. See Table 138 on page 630. If the TR-31 key block header contains an optional
| block with a control vector in it, the control vector is used in place of keywords to produce the output CCA key-token.
| If the key usage and mode of use fields of the key block are not IBM-defined (see Table 138 on page 630), the
| control vector must not conflict with any TR-31 header fields.
| CV subtype extension for "C0" key usage (one required). Only valid for TR-31 key block with key usage "C0" and no
| control vector in optional block.
| CVK-CVV Convert a TR-31 card verification key (CVK) to a double-length CCA DES MAC key that has a
| subtype extension of CVVKEY-A. This restricts the key to generating or verifying a Visa CVV or
| MasterCard CVC.
| CVK-CSC Convert a TR-31 CVK to a CCA DES MAC key that has a subtype extension of AMEX-CSC.
| This restricts the key to generating or verifying an American Express card security code, also
| known as a card identification number (CID).
| CV key type for "K0" key usage (one required). Only valid for TR-31 key block with key usage "K0" and no control
| vector in optional block.
| EXPORTER For TR-31 key usage "K0" and mode of use "E" or "B", convert a TR-31 key encryption or
| wrapping key to a CCA EXPORTER key.
| OKEYXLAT For TR-31 key usage "K0" and mode of use "E" or "B", convert a TR-31 key encryption or
| wrapping key to a CCA OKEYXLAT key.
| IMPORTER For TR-31 key usage "K0" and mode of use "D" or "B", convert a TR-31 key encryption or
| wrapping key to a CCA IMPORTER key.
| IKEYXLAT For TR-31 key usage "K0" and mode of use "D" or "B", convert a TR-31 key encryption or
| wrapping key to a CCA IKEYXLAT key.
| CV key type for "V0", "V1", or "V2" key usage (one required). Only valid for TR-31 key block with key usage "V0",
| "V1", or "V2" and no control vector in optional block. When this keyword is specified, an optional CV key type
| modifier can be specified for key usage "V0" or "V1".
| PINGEN Convert a TR-31 PIN verification key to a CCA PINGEN key.
| PINVER Convert a TR-31 PIN verification key to a CCA PINVER key.
| CV key usage for "E0" or "E2" key usage (one required) Only valid for TR-31 key block with key usage "E0" or "E2"
| and no control vector in optional block.
| DMAC Convert TR-31 EMV/chip issuer master key: application cryptograms or secure messaging for
| integrity to CCA DKYGENKY with key usage DMAC.
| DMV Convert TR-31 EMV/chip issuer master key: application cryptograms or secure messaging for
| integrity to CCA DKYGENKY with key usage DMV.

| Keyword Meaning
| CV key usage for "E1" key usage (one required) Only valid for TR-31 key block with key usage "E1" and no control
| DMPIN Convert TR-31 EMV/chip issuer master key: secure messaging for confidentiality to CCA
| DKYGENKY with key usage DMPIN
| DDATA Convert TR-31 EMV/chip issuer master key: secure messaging for confidentiality to CCA
| DKYGENKY with key usage DDATA.
| CV key usage for "E5" key usage (one required) Only valid for TR-31 key block with key usage "E5" and no control
| DMAC Convert TR-31 EMV/chip issuer master key: card personalization to CCA DKYGENKY with key
| usage DMAC.
| DMV Convert TR-31 EMV/chip issuer master key: card personalization to CCA DKYGENKY with key
| usage DMV.
| DEXP Convert TR-31 EMV/chip issuer master key: card personalization to CCA DKYGENKY with key
| usage DEXP.
| CV subtype for "E0", "E1", or "E2" key usage (one required). Only valid for TR-31 key block with key usage "E0",
| "E1", or "E2" and no control vector in optional block.
| DKYL0 Convert TR-31 EMV/chip issuer master key: application cryptograms, secure message for
| confidentiality, or secure message for integrity to CCA DKYGENKY with subtype DKYL0.
| DKYL1 Convert TR-31 EMV/chip issuer master key: application cryptograms, secure message for
| confidentiality, or secure message for integrity to CCA DKYGENKY with subtype DKYL1.
| CV key type modifier for "V0" or "V1" key usage (one required). Only valid for TR-31 key block with key usage "V0"
| or "V1" and no control vector in optional block.
| NOOFFSET Convert a TR-31 PIN verification key to a CCA PINGEN or PINVER key with the key type
| modifier NOOFFSET, so that the key cannot participate in a PIN offset process or PVV process.
| Key-wrapping method (one, optional)
| USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. This is
| the default.
| Note: Do not use this keyword if the default wrapping method is WRAP-ECB and a control
| vector is present in an optional block of the TR-31 key block with CV bit 56 = B'1' (ENH-ONLY).
| Use the WRAP-ENH keyword instead.
| Note: Do not use this keyword if a control vector is present in an optional block of the TR-31
| key block with CV bit 56 = B'1' (ENH-ONLY).
| Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the
| default wrapping method is WRAP-ENH. This option cannot be used on a key with a control vector valued to binary
| zeros.
| ENH-ONLY Specifies to restrict the key from being wrapped with the legacy method once it has been
| wrapped with the enhanced method. Sets CV bit 56 = B'1' (ENH-ONLY).
| Note: If a control vector is present in an optional block of the TR-31 key block with CV bit 56 =
| B'0', this keyword overrides that value in the CCA key-token. This keyword has no effect if the
| control vector in an optional block is all zeros.
|
| Table 70 on page 533 shows all valid translations for import of a TR-31 BDK base derivation key
| (usage "B0") to a CCA KEYGENKY key, along with any access control commands that must be
| enabled in the active role for that key type and control vector attributes. These keys are for translating
| derived unique key per transaction (DUKPT) base derivation keys.

| Table 70. Import translation table for a TR-31 BDK base derivation key (usage "B0")
| Key block
| protection
| method
| Key keyword Mode of Rule-array CCA key type and control vector
| usage (version ID) use keywords attributes Offset Command
| "B0" "A" "N" N/A KEYGENKY, double length, UKPT N/A N/A
| (CV bit 18 = B'1')
| "B" or "C" "X"
| Notes:
| 1. These are the base keys from which derived unique key per transaction (DUKPT) initial keys are derived for
| individual devices such as PIN pads.
| "B0" BDK base derivation key.
| 3. There are no specific access-control commands for this translation because it is not ambiguous or in need of
| interpretation.
|
| Table 71 shows all valid translations for import of a TR-31 CVK card verification key (usage "C0") to a
| CCA MAC or DATA key, along with any access control commands that must be enabled in the active
| role for that key type and control vector attributes. These keys are for computing or verifying (against
| supplied value) a card verification code with the CVV, CVC, CVC2, and CVV2 algorithm.
| Table 71. Import translation table for a TR-31 CVK card verification key (usage "C0")
| Key block
| protection
| method
| keyword
| Key (version Mode Rule-array CCA key type and control
| usage ID) of use keywords vector attributes Offset Command
| "C0" "A", "B", or "G" or CVK-CSC MAC, single or double length, X'015B' TR31 Import - Permit C0 to
| "C" "C" AMEX-CSC (CV bits 0 - 3 = MAC/MACVER:AMEXCSC
| B'0100')
| CVK-CVV MAC, double length, X'015A' TR31 Import - Permit C0 to
| CVVKEY-A (CV bits 0 - 3 = MAC/MACVER:CVVKEY-A
| B'0010')
| "V" CVK-CSC MACVER, single or double X'015B' TR31 Import - Permit C0 to
| length, AMEX-CSC (CV bits 0 MAC/MACVER:AMEXCSC
| - 3 = B'0100')
| CVK-CVV MACVER, double length, X'015A' TR31 Import - Permit C0 to
| CVVKEY-A (CV bits 0 - 3 = MAC/MACVER:CVVKEY-A
| B'0010')
| 1. There is asymmetry in the translation from a CCA DATA key to a TR-31 key. The asymmetry results from CCA
| DATA keys having attributes of both data encryption keys and MAC keys, while TR-31 separates data encryption
| keys from MAC keys. A CCA DATA key can be exported to a TR-31 "C0" key, provided that one or both
| applicable MAC generate and MAC verify control vector bits are on. However, a TR-31 "C0" key cannot be
| imported to the lower-security CCA DATA key, it can only be imported to a CCA key type of MAC or MACVER.
| This restriction eliminates the ability to export a CCA MAC or MACVER key to a TR-31 key and re-importing it
| back as a CCA DATA key with the capability to Encipher, Decipher, or both.
| 2. The translation from TR-31 usage "C0" is controlled by rule array keywords when using the TR31_Key_Import
| verb. This makes it possible to convert an exported CCA CVVKEY-A key into an AMEX-CSC key or the other way
| around. To prevent such a conversion, do not enable offsets X'015A' (TR31 Import - Permit C0 to
| MAC/MACVER:CVVKEY-A) and X'015B' (TR31 Import - Permit C0 to MAC/MACVER:AMEXCSC) at the same
| time. However, if both CVVKEY-A and AMEX-CSC translation types are required, then offsets X'015A' and
| X'015B' must be enabled. In this case, control is up to the development, deployment, and execution of the
| applications themselves.

| Table 71. Import translation table for a TR-31 CVK card verification key (usage "C0") (continued)
| Notes:
| 1. Card verification keys are used for computing or verifying (against supplied value) a card verification code with
| the CVV, CVC, CVC2, and CVV2 algorithms. In CCA, this corresponds to keys used with two algorithms:
| v Visa CVV and MasterCard CVC codes are generated and verified using the CVV_Generate and CVV_Verify
| verbs. These verbs require a key type of DATA or MAC/MACVER with a subtype extension (CV bits 0 - 3) of
| ANY-MAC, single-length CVVKEY-A and single-length CVVKEY-B, and beginning with Release 4.2 a
| double-length CVVKEY-A (see CVV_Key_Combine verb). The MAC generate and the MAC verify (CV bits 20 -
| 21) key usage values must be set appropriately.
| v American Express CSC codes are generated and verified using the Transaction_Validation verb. This verb
| requires a key type of MAC or MACVER with a subtype extension of ANY-MAC or AMEX-CSC.
| 2. The translation from TR-31 usage "C0" to a CCA MAC/MACVER key with a subtype extension of ANY-MAC (CV
| bits 0 - 3 = B'0000') is not allowed.
| "C0" CVK card verification key
| 4. CCA does not have an equivalent to the TR-31 "generate only" mode of use, so a translation from TR-31 mode
| "G" will result in a CCA MAC key with both MAC generate and MAC verify attributes (CV bits 20 - 21 = B'11').
| Note that any key that can perform a generate can readily verify a MAC as well.
| 5. The CCA representation and the TR-31 representation of CVV keys are incompatible. CCA represents the
| CVVKEY-A and CVVKEY-B keys as two 8-byte (single length) keys, while TR-31 represents these keys as one
| 16-byte key. Beginning with Release 4.2, the CVV_Generate and CVV_Verify verbs have support added to accept
| one 16-byte CVV key, using left and right key parts as A and B. Current Visa standards require this.
| 6. Import and export of 8-byte CVVKEY-A and CVVKEY-B MAC/MACVER keys will only be allowed using the
| proprietary TR-31 usage+mode values ("10" and "1", respectively) to indicate encapsulation of the IBM control
| vector in an optional block, because the 8-byte CVVKEY-A is meaningless and useless as a TR-31 "C0" usage
| key of any mode.
|
| Table 72 shows all valid translations for import of a TR-31 data encryption key (usage "D0") to a CCA
| ENCIPHER, DECIPHER, CIPHER, or DATA key, along with any access control commands that must
| be enabled in the active role for that key type and control vector attributes. These keys are used for
| the encryption and/or decryption of data.
| Table 72. Import translation table for a TR-31 data encryption key (usage "D0")
| Key block
| protection
| method
| Key keyword Mode of Rule-array CCA key type and control vector
| usage (version ID) use keywords attributes Offset Command
| "D0" "A", "B", or "E" N/A ENCIPHER, single or double length N/A N/A
| "C"
| "D" N/A DECIPHER, single or double length
| "B" N/A CIPHER, single or double length
| separates data encryption keys from MAC keys. A CCA DATA key can be exported to a TR-31 "D0" key, provided
| that one or both applicable Encipher or Decipher control vector bits are on. However, a TR-31 "D0" key cannot be
| imported to the lower-security CCA DATA key, it can only be imported to a CCA key type of ENCIPHER,
| DECIPHER, or CIPHER. This restriction eliminates the ability to export a CCA DATA key to a TR-31 key, and
| re-importing it back as a CCA DATA key with the capability to MAC generate and MAC verify.
| Notes:
| 1. Data encryption keys are used for the encryption and decryption of data.
| "D0" Data encryption
| 3. There are no specific access-control commands for this translation since it is not ambiguous or in need of
| interpretation.
|

| Table 73 shows all valid translations for import of a TR-31 key encryption or wrapping, or key block
| protection key (usages "K0", "K1") to a CCA EXPORT, OKEYXLAT, IMPORTER, or IKEYXLAT key,
| along with any access control commands that must be enabled in the active role for that key type and
| control vector attributes. These keys are used only to encrypt or decrypt other keys, or as a key used
| to derive keys that are used for that purpose.
| Table 73. Import translation table for a TR-31 key encryption or wrapping, or key block protection key (usages "K0",
| "K1")
| Key block
| protection
| method
| keyword
| "K0" "A", "B", or "E" OKEYXLAT OKEYXLAT, double length X'015C' TR31 Import - Permit K0:E to
| "C" EXPORTER/OKEYXLAT
| EXPORTER EXPORTER, double length,
| EXPORT on (CV bit 21 =
| B'1')
| "D" IKEYXLAT IKEYXLAT, double length X'015D' TR31 Import - Permit K0:D to
| IMPORTER/IKEYXLAT
| IMPORTER IMPORTER, double length,
| IMPORT on (CV bit 21 = B'1')
| "B" OKEYXLAT OKEYXLAT, double length X'015E' TR31 Import - Permit K0:B to
| EXPORTER/OKEYXLAT
| B'1')
| IKEYXLAT IKEYXLAT, double length X'015F' TR31 Import - Permit K0:B to
| IMPORTER/IKEYXLAT
| "K1" "B" or "C" "E" OKEYXLAT OKEYXLAT, double length X'0160' TR31 Import - Permit K1:E to
| EXPORTER/OKEYXLAT
| B'1')
| "D" IKEYXLAT IKEYXLAT, double length X'0161' TR31 Import - Permit K1:D to
| IMPORTER/IKEYXLAT
| "B" OKEYXLAT OKEYXLAT, double length X'0162' TR31 Import - Permit K1:B to
| EXPORTER/OKEYXLAT
| B'1')
| IKEYXLAT IKEYXLAT, double length X'0163' TR31 Import - Permit K1:B to
| IMPORTER/IKEYXLAT

| Table 73. Import translation table for a TR-31 key encryption or wrapping, or key block protection key (usages "K0",
| "K1") (continued)
| 1. The CCA OKEYXLAT, EXPORTER, IKEYXLAT, or IMPORTER KEK translation to a TR-31 "K0" key with mode
| "B" (both wrap and unwrap) is not allowed for security reasons. Even with access-control point control, this
| capability would give an immediate path to turn a CCA EXPORTER key into a CCA IMPORTER, and the other
| way around.
| 2. When a TR-31 key block does not have an included control vector as an optional block, the default control vector
| will be used to construct the output key-token. Default CCA EXPORTER or IMPORTER keys have CV bits 18 -
| 20 on, which are used for key generation.
| Notes:
| 1. Key encryption or wrapping keys are used only to encrypt or decrypt other keys, or as a key used to derive keys
| that are used for that purpose.
| "K0" Key encryption or wrapping
| "K1" TR-31 key block protection key
| 3. Any attempt to import a TR-31 "K0" or "K1" key that has algorithm "D" (DEA) will result in an error because CCA
| does not support single-length KEKs.
| 4. CCA mode support is the same for version IDs "A", "B", and "C". That is because the distinction between TR-31
| "K0" and "K1" does not exist in CCA keys. CCA does not distinguish between targeted protocols currently, and so
| there is no good way to represent the difference. Also note that most wrapping mechanisms now involve
| derivation or key variation steps.
|

| Table 74 shows all valid translations for import of a TR-31 ISO MAC algorithm key (usages "M0", "M1",
| "M3") to a CCA MAC, MACVER, DATA, DATAM, or DATAMV key, along with any access control
| commands that must be enabled in the active role for that key type and control vector attributes.
| These keys are use to compute or verify a code for message authentication.
| Table 74. Import translation table for a TR-31 ISO MAC algorithm key (usages "M0", "M1", "M3")
| Key block
| protection
| method
| keyword
| "M0" "A", "B", or "G" or N/A MAC, double length, X'0164' TR31 Import - Permit
| "C" "C" ANY-MAC (CV bits 0 - 3 = M0/M1/M3 to
| B'0000') MAC/MACVER:ANY-MAC
| "V" MACVER, double length,
| ANY-MAC (CV bits 0 - 3 =
| B'0000')
| "M1" "G" or MAC, single or double length,
| "C" ANY-MAC (CV bits 0 - 3 =
| B'0000')
| "V" MACVER, single or double
| length, ANY-MAC (CV bits 0 -
| 3 = B'0000')
| "M3" "G" or MAC, single or double length,
| "C" ANY-MAC (CV bits 0 - 3 =
| B'0000')
| "V" MACVER, single or double
| length, ANY-MAC (CV bits 0 -
| 3 = B'0000')
| separates data encryption keys from MAC keys. A CCA DATA key can be exported to a TR-31 "M0", "M1", or "M3"
| key, provided that one or both applicable MAC generate and MAC verify control vector bits are on. However, a TR-31
| "M0", "M1", or "M3" key cannot be imported to the lower-security CCA DATA key, it can only be imported to a CCA
| key type of MAC or MACVER. This restriction eliminates the ability to export a CCA MAC or MACVER key to a
| TR-31 key, and re-importing it back as a CCA DATA key with the capability to Encipher, Decipher, or both.
| Notes:
| 1. MAC keys are used to compute or verify a code for message authentication.
| "M0" SO 16609 MAC algorithm 1, TDEA
| The ISO 16609 MAC algorithm 1 is based on ISO 9797. It is identical to "M1" except that it does not
| support 8-byte DES keys.
| "M1" SO 9797 MAC algorithm 1
| The ISO 9797 MAC algorithm 1 is identical to "M0" except that it also supports 8-byte DES keys.
| This is the X9.19 style of Triple-DES MAC.
| 3. A CCA control vector has no bits defined to limit key usage by algorithm, such as CBC MAC (TR-31 usage "M0"
| and "M1") or X9.19 (TR-31 usage "M3"). When importing a TR-31 key block, the resulting CCA key token
| deviates from the restrictions of usages "M0", "M1", and "M3". Importing a TR-31 key block which allows MAC
| generation ("G" or "C") results in a control vector with the ANY-MAC attribute rather than for the restricted
| algorithm that is set in the TR-31 key block. The ANY-MAC attribute provides the same restrictions as what CCA
| currently uses for generating and verifying MACs.
|

| Table 75 shows all valid translations for import of a TR-31 PIN encryption or PIN verification key
| (usages "P0", "V0", "V1", "V2") to a CCA OPINENC, IPINENC, PINGEN, or PINVER key, along with
| any access control commands that must be enabled in the active role for that key type and control
| vector attributes. These keys are used to protect PIN blocks and to generate or verify a PIN using a
| particular PIN-calculation method for that key type.
| Table 75. Import translation table for a TR-31 PIN encryption or PIN verification key (usages "P0", "V0", "V1", "V2")
| Key block
| protection
| method
| keyword
| Key (version Rule-array CCA key type and control
| usage ID) Mode of use keywords vector attributes Offset Command
| "P0" "A", "B", "E" N/A OPINENC, double length X'0165' TR31 Import - Permit
| or "C" P0:E to OPINENC
| "D" IPINENC, double length X'0166' TR31 Import - Permit
| P0:D to IPINENC
| "V0" "A" "N" (requires PINGEN PINGEN, NOOFFSET off X'0167' TR31 Import - Permit
| both double length, (CV bit 37 = V0 to
| commands) NO-SPEC (CV B'0') PINGEN:NO-SPEC
| bits 0 - 3 =
| X'017C' TR31 Import - Permit
| B'0000')
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "G" or "C" NOOFFSET off X'0167' TR31 Import - Permit
| or "C" (CV bit 37 = V0 to
| B'0') PINGEN:NO-SPEC
| "A" "N" (requires PINGEN, NOOFFSET on X'0167' TR31 Import - Permit
| both NOOFFSET (CV bit 37 = V0 to
| commands) B'1') PINGEN:NO-SPEC
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "G" or "C" NOOFFSET on X'0167' TR31 Import - Permit
| B'1') PINGEN:NO-SPEC
| "A" "N" (requires PINVER PINVER, NOOFFSET off X'0168' TR31 Import - Permit
| commands) NO-SPEC (CV B'0') PINVER:NO-SPEC
| bits 0 - 3 =
| B'0000')
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "V" NOOFFSET off X'0168' TR31 Import - Permit
| B'0') PINVER:NO-SPEC
| "A" "N" (requires PINVER, NOOFFSET on X'0168' TR31 Import - Permit
| commands) B'1') PINVER:NO-SPEC
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "V" NOOFFSET on X'0168' TR31 Import - Permit
| B'1') PINVER:NO-SPEC

| Table 75. Import translation table for a TR-31 PIN encryption or PIN verification key (usages "P0", "V0", "V1",
| "V2") (continued)
| Key block
| protection
| method
| keyword
| "V1" "A" "N" (requires PINGEN PINGEN, NOOFFSET off X'0169' TR31 Import - Permit
| commands) IBM B'0') PINGEN:IBM-PIN/
| PIN/IBM-PINO IBMPINO
| (CV bits 0 - 3 =
| B'0001')
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "G" or "C" NOOFFSET off X'0169' TR31 Import - Permit
| B'0') PINGEN:IBM-PIN/
| IBMPINO
| "A" "N" (requires PINGEN, NOOFFSET on X'0169' TR31 Import - Permit
| commands) B'1') PINGEN:IBM-PIN/
| IBMPINO
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "G" or "C" NOOFFSET on X'0169' TR31 Import - Permit
| B'1') PINGEN:IBM-PIN/
| IBMPINO
| "A" "N" (requires PINVER PINVER, NOOFFSET off X'016A' TR31 Import - Permit
| commands) IBM B'0') PINVER:IBM-PIN/
| PIN/IBM-PINO IBMPINO
| (CV bits 0 - 3 =
| B'0001')
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "V" NOOFFSET off X'016A' TR31 Import - Permit
| B'0') PINVER:IBM-PIN/
| IBMPINOEC
| "A" "N" (requires PINVER, NOOFFSET on X'016A' TR31 Import - Permit
| commands) B'1') PINVER:IBM-PIN/
| IBMPINOC
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "V" NOOFFSET on X'016A' TR31 Import - Permit
| B'1') PINVER:IBM-PIN/
| IBMPINO

| "V2") (continued)
| Key block
| protection
| method
| keyword
| "V2" "A" "N" (requires PINGEN PINGEN, double length, X'016B' TR31 Import - Permit
| both VISA-PVV (CV bits 0 - 3 = V2 to
| commands) B'0010') PINGEN:VISA-PVV
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "G" or "C" PINGEN, double length, X'016B' TR31 Import - Permit
| or "C" VISA-PVV (CV bits 0 - 3 = V2 to
| B'0010') PINGEN:VISA-PVV
| "A" "N" (requires PINVER PINVER, double length, X'016C' TR31 Import - Permit
| both VISA-PVV (CV bits 0 - 3 = V2 to
| commands) B'0010') PINVER:VISA-PVV
| V0/V1/V2:N to
| PINGEN/PINVER
| "A", "B", "V" PINVER, double length, X'016C' TR31 Import - Permit
| or "C" VISA-PVV (CV bits 0 - 3 = V2 to
| B'0010') PINVER:VISA-PVV
| Security note: TR-31 key blocks that are protected under legacy version ID "A" (using the Key Variant Binding
| Method 2005 Edition) use the same mode of use "N" for PINGEN and PINVER keys. For version ID "A" keys only,
| for a given PIN key usage, enabling both the PINGEN and PINVER access-control points at the same time while
| enabling offset X'017C' (for mode "N", no special restrictions) is NOT recommended. In other words, for a particular
| PIN verification key usage, you should not simultaneously enable the four commands shown below for that usage:
| Key type, mode,
| or version Offset Command
| "V0" For usage "V0", a user with the following four commands enabled in the active role can change a PINVER
| key into a PINGEN key and the other way around. Avoid simultaneously enabling these four
| commands.
| Key type PINGEN X'0167' TR31 Import - Permit V0 to PINGEN:NO-SPEC
| Key type PINVER X'0168' TR31 Import - Permit V0 to PINVER:NO-SPEC
| Mode "N" X'017C' TR31 Import - Permit V0/V1/V2:N to PINGEN/PINVER
| Version "A" X'0150' TR31 Import - Permit Version A TR-31 Key Blocks
| commands.
| Key type PINGEN X'0169' TR31 Import - Permit V1 to PINGEN:IBM-PIN/IBMPINO
| Key type PINVER X'016A' TR31 Import - Permit V1 to PINVER:IBM-PIN/IBMPINO
| commands.
| Key type PINGEN X'016B' TR31 Import - Permit V2 to PINGEN:VISA-PVV
| Key type PINVER X'016C' TR31 Import - Permit V2 to PINVER:VISA-PVV
| Failure to comply with this recommendation allows changing PINVER keys into PINGEN and the other way around.

| "V2") (continued)
| Notes:
| 1. PIN encryption keys are used to protect PIN blocks. PIN verification keys are used to generate or verify a PIN
| using a particular PIN-calculation method for that key type.
| "P0" PIN encryption
| "V0" PIN verification, KPV, other algorithm
| Usage "V0" does not have its own PIN-calculation method defined. The mapping to NO-SPEC is
| sub-optimal. Exporting to "N" mode restricts keys from being imported with the IBM-PIN/IBM-PINO or
| VISA-PVV attribute, while CCA NO-SPEC allows any method.
| "V1" PIN verification, IBM 3624
| "V2" PIN verification, Visa PVV
| The NOOFFSET keyword is not allowed for the Visa PVV algorithm because it does not support this
| attribute.
| 3. Mode must be one of the following:
| "E" Encrypt/wrap only
| This restricts PIN encryption keys to encrypting a PIN block. May be used to create or reencipher an
| encrypted PIN block (for key-to-key translation).
| "D" Decrypt/unwrap only
| This restricts PIN encryption keys to decrypting a PIN block. Generally used in a PIN translation to
| decrypt the incoming PIN block.
| "N" No special restrictions (other than restrictions implied by the key usage)
| This is used by several vendors for a PIN generate or PIN verification key when the key block version ID
| is "A".
| "G" Generate only
| This is used for a PINGEN key that may not perform a PIN verification. The control vector will not have
| its EPINVER attribute on (CV bit 22 = B'0').
| "V" Verify only
| This is used for PIN verification only. If the TR-31 key block does not have a control vector included, the
| only usage bits set on in the control vector will be the EPINVER bit (CV bits 18 - 22 = B'00001').
| "C" Both generate and verify (combined)
| The control vector will have the default PINGEN bits on (CV bits 18 -22 = B'11111').
| 4. Any attempt to import a TR-31 "P0" key that has mode "B" (both encrypt and decrypt) will result in an error
| because CCA does not support this combination of attributes.
| 5. If the TR-31 key block contains a control vector, and the control vector has NOOFFSET on, the NOOFFSET
| keyword is not necessary because the verb will automatically set NOOFFSET on in this case.
|
| Table 76 on page 542 shows all valid translations for import of a TR-31 EMV/chip issuer master-key
| key (usages "E0", "E1", "E2", "E3", "E4", "E5") to a CCA DKYGENKY, DATA, MAC, CIPHER, or
| ENCIPHER key, along with any access control commands that must be enabled in the active role for
| that key type and control vector attributes. These keys are used by the chip cards to perform
| cryptographic operations or, in some cases, to derive keys used to perform operations.

| Table 76. Import translation table for a TR-31 EMV/chip issuer master-key key (usages "E0", "E1", "E2", "E3", E4",
| "E5")
| Key block
| protection
| method
| keyword
| "E0" "A" "N" DKYL0, DKYGENKY, double length, X'016D' TR31 Import - Permit E0 to
| DMAC DKYL0 (CV bits 12 - 14 = DKYGENKY:DKYL0+DMAC
|| "B" or "C" "X" B'000'), DMAC (CV bits 19 -
| 22 = B'0010')
| "A" "N" DKYL0, DKYGENKY, double length, X'016E' TR31 Import - Permit E0 to
| DMV DKYL0 (CV bits 12 - 14 = DKYGENKY:DKYL0+DMV
|| "B" or "C" "X" B'000'), DMV (CV bits 19 - 22
| = B'0011')
| "A" "N" DKYL1, DKYGENKY, double length, X'016F' TR31 Import - Permit E0 to
| 22 = B'0010')
| "A" "N" DKYL1, DKYGENKY, double length, X'0170' TR31 Import - Permit E0 to
| DMV DKYL1 (CV bits 12 - 14 = DKYGENKY:DKYL1+DMV
|| "B" or "C" "X" B'001'), DMV (CV bits 19 - 22
| = B'0011')
| "E1" "A" "N" DKYL0, DKYGENKY, double length, X'0171' TR31 Import - Permit E1 to
| DMPIN DKYL0 (CV bits 12 - 14 = DKYGENKY:DKYL0+DMPIN
| "E"
| B'000'), DMPIN (CV bits 19 -
| "D" 22 = B'1001')
| "B"
| "B" or "C" "X"
| DDATA DKYL0 (CV bits 12 - 14 = DKYGENKY:DKYL0+DDATA
| "E"
| B'000'), DDATA (CV bits 19 -
| "D" 22 = B'0001')
| "B"
| "B" or "C" "X"
| DMPIN DKYL1 (CV bits 12 - 14 = DKYGENKY:DKYL1+DMPIN
| "E"
| B'001'), DMPIN (CV bits 19 -
| "D" 22 = B'1001')
| "B"
| "B" or "C" "X"
| "E"
| "D" 22 = B'0001')
| "B"
| "B" or "C" "X"

| "E5") (continued)
| Key block
| protection
| method
| keyword
| "E2" "A" "N" DKYL0, DKYGENKY, double length, X'0175' TR31 Import - Permit E2 to
| 22 = B'0010')
| 22 = B'0010')
| "E3" "A" "N" N/A ENCIPHER X'0177' TR31 Import - Permit E3 to
| ENCIPHER
| "E"
| "D"
| "B"
| "G"
| "B" or "C" "X"
| "E4" "A" "N" N/A DKYGENKY, double length, X'0178' TR31 Import - Permit E4 to
| DKYL0 (CV bits 12 - 14 = DKYGENKY:DKYL0+DDATA
| "B"
| "B" or "C" "X" 22 = B'0001')

| "E5") (continued)
| Key block
| protection
| method
| keyword
| "E5" "A" "G" DKYL0, DKYGENKY, double length, X'0179' TR31 Import - Permit E5 to
| "C"
| B'000'), DMAC (CV bits 19 -
| "V" 22 = B'0010')
| "E"
| "D"
| "B"
| "N"
| "B" or "C" "X"
| "A" "G" DKYL0, DKYGENKY, double length, X'017A' TR31 Import - Permit E5 to
| "C"
| "V" 22 = B'0001')
| "E"
| "D"
| "B"
| "N"
| "B" or "C" "X"
| "A" "G" DKYL0, DKYGENKY, double length, X'017B' TR31 Import - Permit E5 to
| DEXP DKYL0 (CV bits 12 - 14 = DKYGENKY:DKYL0+DEXP
| "C"
| B'000'), DEXP (CV bits 19 - 22
| "V" = B'0101')
| "E"
| "D"
| "B"
| "N"
| "B" or "C" "X"

| "E5") (continued)
| Notes:
| 1. EMV/chip issuer master-key keys are used by the chip cards to perform cryptographic operations or, in some
| cases, to derive keys used to perform operations. In CCA, these are (a) diversified key-generating keys (key type
| DKYGENKY), allowing derivation of operational keys, or (b) operational keys. Note that in this context, "master
| key" has a different meaning than for CCA. These master keys, also called a KMCs, are described by EMV as
| DES master keys for personalization session keys. They are used to derive the corresponding chip card master
| keys, and not typically used directly for cryptographic operations other than key derivation. In CCA, these are
| usually key generating keys with derivation level DKYL1 (CV bits 12 - 14 = B'001'), used to derive other key
| generating keys (the chip card master keys). For some cases, or for older EMV key derivation methods, the
| issuer master keys could be level DKYL0 (CV bits 12 - 14 = B'000').
| "E0" Application cryptograms
| "E1" Secure messaging for confidentiality
| "E2" Secure messaging for integrity
| "E3" Data authentication code
| "E4" Dynamic numbers
| "E5" Card personalization
| 3. EMV support in CCA is quite different than TR-31 support, and CCA key types do not match TR-31 types.
| 4. DKYGENKY keys are double length only.
| 5. In CCA, a MAC key that can perform a MAC generate operation also can perform a MAC verify. For TR-31 mode
| "G" (generate only), the translation to a CCA key results in a key that can perform MAC generate and MAC verify.
|
| tr31_key_block_length
| The tr31_key_block_length parameter is a pointer to an integer variable containing the number of
| bytes of data in the tr31_key_block variable. The length field in the TR-31 block is a 4-digit decimal
| number, so the maximum acceptable length is 9992 bytes.
| tr31_key_block
| The tr31_key_block parameter is a pointer to a string variable containing the TR-31 key block that is to
| be imported. The key block is protected with the key identified by the unwrap_kek_identifier parameter.
| unwrap_kek_identifier_length
| The unwrap_kek_identifier_length parameter is a pointer to an integer variable containing the number
| of bytes of data in the unwrap_kek_identifier variable. Set this value to 64.
| unwrap_kek_identifier
| The unwrap_kek_identifier parameter is a pointer to a string variable containing the operational
| fixed-length DES key-token used to unwrap the key identified by the tr31_key_block parameter, or a
| key label of such a key in DES key-storage. The key must have a key type of IMPORTER or
| IKEYXLAT, and be authorized for import.
| Note: DES keys wrapped in ECB mode (CCA legacy wrap mode) cannot be used to wrap or unwrap
| wrap_kek_identifier_length
| The wrap_kek_identifier_length parameter is a pointer to an integer variable containing the length in
| bytes of the wrap_kek_identifier variable. The value must be greater than or equal to 0. A null
| key-token can have a length of 1. Set this value to 64 for a key label or a KEK.
| wrap_kek_identifier
| The wrap_kek_identifier parameter is a pointer to a string variable containing the operational
| fixed-length DES key-token used to wrap the key identified by the output_key_identifier parameter, a
| null key-token, or a key label of such a key in DES key-storage. If the key token identified by the
| parameter is not null, it must have a key type of IMPORTER or IKEYXLAT, be authorized for import,

| and have the same clear key as the key identified by the unwrap_kek_identifier parameter. If the
| parameter identifies a null key-token, then the unwrap_kek_identifier parameter is also used for
| wrapping the CCA output key token.
| The output_key_identifier_length parameter is a pointer to an integer specifying the length in bytes of
| the output_key_identifier variable. This is an input/output parameter.
| The output_key_identifier parameter is a pointer to a string variable containing the key token or the
| key label for the token that is to receive the imported key. The output key-token is a CCA internal or
| external key token containing the key received in the TR-31 token. If a key token is provided, it must
| be a null token (64 bytes of X'00'). If a key label is provided, the imported token is stored in the key
| storage file and identified by that label.
| num_opt_blocks
| The num_opt_blocks parameter is a pointer to an integer variable where the verb stores the number of
| optional blocks that are present in the TR-31 key token.
| cv_source
| The cv_source parameter is a pointer to an integer variable where the verb stores a value indicating
| how the control vector in the output key token was created. It can be one of the values in Table 77.
| Table 77. CSNBT31I CV sources
| CSNBT31I CV
| source Meaning
| 0 No CV was present in an optional block, and the output CV was created by the verb based on
| input parameters and on the attributes in the TR-31 key block header.
| 1 A CV was obtained from an optional block in the TR-31 key block, and the key usage and mode
| of use were also specified in the TR-31 header. The verb verified compatibility of the header
| values with the CV and then used that CV in the output key token.
| 2 A CV was obtained from an optional block in the TR-31 key block, and the key usage and mode
| of use in the TR-31 header held the proprietary values indicating that key use and mode should
| be obtained from the included CV. The CV from the TR-31 token was used as the CV for the
| output key token.
|
| Any values other than these three are reserved and are currently invalid.
| protection_method
| The protection_method parameter is a pointer to an integer variable where the verb stores a value
| indicating what method was used to protect the input TR-31 key block. The TR-31 standard allows two
| methods, and the application program might want to know which was used for security purposes. The
| variable can have one of the values in Table 78.
| Table 78. CSNBT31I protection methods
| CSNBT31I
| protection
| method Meaning
| 0 The TR-31 key block was protected using the variant method as identified by a Key Block
| Version ID value of "A" (X'41').
| 1 The TR-31 key block was protected using the derived key method as identified by a Key Block
| Version ID value of "B" (X'42').
| 2 The TR-31 key block was protected using the variant method as identified by a Key Block
| Version ID value of "C" (X'43'). Functionally this method is the same as "A", but to maintain
| consistency a different value is returned here for "C".
|
| Any values other than these three are reserved and are currently invalid.

| Required commands
| The TR31_Key_Import verb requires the following commands to be enabled in the active role:
|| Rule-array
| keyword Offset Command
| WRAP-ENH or X'0153' TR31 Import - Permit Override of Default Wrapping Method
| WRAP-ECB
|
|| TR-31 key
| block version
| ID Offset Command
| "A" (X'41') X'0150' TR-31 Import - Permit Version A TR-31 Key Blocks
| "B" (X'42') X'0151' TR-31 Import - Permit Version B TR-31 Key Blocks
| "C" (X'43') X'0152' TR-31 Import - Permit Version C TR-31 Key Blocks
|
| Be aware of access-control point X'017C' (TR31 Import - Permit V0/V1/V2:N to PINGEN/PINVER) for
| import of PINGEN or PINVER keys to wrapping method "A", usage "V0", "V1", or "V2", and mode "N".
| TR-31 key blocks with legacy key usage "A" (key block protected using the Key Variant Binding Method
| 2005 Edition) use the same mode "N" for PINGEN as well as PINVER keys. For usage "A" keys only,
| enabling a PINGEN and PINVER access-control point while enabling offset X'017C' (for mode "N") is NOT
| recommended. Failure to comply with this recommendation allows changing PINVER keys into PINGEN,
| and the other way around.
| In addition to the above commands, the verb requires these additional commands to be enabled in the
| active role depending on the rule-array keyword provided:
|| Specific key usage, version ID,
| Rule-array keyword Offset Command and mode values
| "C0": TR-31 CVK card verification keys
| CVK-CSC X'015B' TR31 Import - Permit C0 to See Table 71 on page 533.
| MAC/MACVER:AMEXCSC
| CVK-CVV X'015A' TR31 Import - Permit C0 to
| MAC/MACVER:CVKEY-A

| Specific key usage, version ID,
| "K0" and "K1": TR-31 key encryption or wrapping, or key block protection keys
| OKEYXLAT or X'015C' TR31 Import - Permit K0:E to EXPORTER/ See Table 73 on page 535.
| EXPORTER OKEYXLAT
| X'015E' TR31 Import - Permit K0:B to
| EXPORTER/OKEYXLAT
| X'0160' TR31 Import - Permit K1:E to
| EXPORTER/OKEYXLAT
| X'0162' TR31 Import - Permit K1:B to
| EXPORTER/OKEYXLAT
| IKEYXLAT or X'015D' TR31 Import - Permit K0:D to
| IMPORTER IMPORTER/IKEYXLAT
| X'015F' TR31 Import - Permit K0:B to
| IMPORTER/IKEYXLAT
| X'0161' TR31 Import - Permit K1:D to
| IMPORTER/IKEYXLAT
| X'0163' TR31 Import - Permit K1:B to
| IMPORTER/IKEYXLAT
| "M0", "M1", and "M3": TR-31 ISO MAC algorithm keys
| N/A X'0164' TR31 Import - Permit M0/M1/M3 to See Table 74 on page 537.
| MAC/MACVER:ANY-MAC
| X'018C' TR31 Export - Permit MACVER/DATAMV to
| M0:V
| "P0", "V0", "V1": TR-31 PIN encryption or PIN verification keys
| N/A X'0165' TR31 Import - Permit P0:E to OPINENC See Table 75 on page 538.
| X'0166' TR31 Import - Permit P0:D to IPINENC
| PINGEN X'0167' TR31 Import - Permit V0 to
| PINGEN:NO-SPEC
| X'0169' TR31 Import - Permit V1 to
| PINGEN:IBM-PIN/IBMPINO
| X'016B' TR31 Import - Permit V2 to
| PINGEN:VISA-PVV
| X'017C' TR31 Import - Permit V0/V1/V2:N to
| PINGEN/PINVER
| PINVER X'0168' TR31 Import - Permit V0 to
| PINVER:NO-SPEC
| X'016A' TR31 Import - Permit V1 to
| PINVER:IBM-PIN/IBMPINO
| X'016C' TR31 Import - Permit V2 to
| PINVER:VISA-PVV
| X'017C' TR31 Import - Permit V0/V1/V2:N to
| PINGEN/PINVER

| "E0", "E1", "E2", "E3", "E4", and "E5": TR-31 EMC/chip issuer master-key keys
| DKYL0 X'016D' TR31 Import - Permit E0 to See Table 76 on page 542.
| DKYGENKY:DKYL0+DMAC
| X'016E' TR31 Import - Permit E0 to
| DKYGENKY:DKYL0+DMV
| X'0171' TR31 Import - Permit E1 to
| DKYGENKY:DKYL0+DMPIN
| DKYGENKY:DKYL0+DDATA
| X'0179' TR31 Export - Permit
| X'017A' TR31 Import - Permit E5 to
| X'017B' TR31 Import - Permit E5 to
| DKYGENKY:DKYL0+DEXP
| DKYL1 X'016F' TR31 Import - Permit E0 to See Table 76 on page 542.
| DMAC X'016D' TR31 Import - Permit E0 to See Table 76 on page 542.
| X'016F' TR31 Import - Permit E0 to
| DMV X'016E' TR31 Import - Permit E0 to See Table 76 on page 542. See
| DKYGENKY:DKYL0+DMV Table 76 on page 542.
| DMPIN X'0171' TR31 Import - Permit E1 to

| DDATA X'0172' TR31 Import - Permit E1 to See Table 76 on page 542.
| X'017A' TR31 Import - Permit E5 to
| DEXP X'017B' TR31 Import - Permit E5 to See Table 76 on page 542. See
| DKYGENKY:DKYL0+DEXP Table 76 on page 542.
| N/A X'0177' TR31 Import - Permit E3 to ENCIPHER
|
|

| TR31_Key_Token_Parse (CSNBT31P)
| Use the TR31_Key_Token_Parse verb to disassemble the unencrypted header of an external TR-31 key
| block into separate pieces of information. The part of the header that is optional, called optional blocks, is
| not disassembled. To obtain the contents of optional blocks, use the TR31_Optional_Data_Read verb.
| Neither verb performs any cryptographic services, and both disassemble a key block in application
| storage. The validity of the key block is verified as much as can be done without performing any
| cryptographic services.
| The TR-31 header fields that are disassembled into separate pieces of information include a key block
| version ID, key block length, key usage, algorithm, mode of use, key version number, exportability, and
| number of optional blocks. Except for the two length values, which are returned as integers, the verb
| returns the field values as ASCII strings. This is the format used in the TR-31 key block itself. For
| additional information, see X9 TR-31 2010: Interoperable Secure Key Exchange Block Specification for
| Symmetric Algorithms.
| The following table summarizes the key blocks fields returned by this verb:
|| Field or
| buffer
| string
| length in
| TR-31 field name Verb parameter bytes Description of TR-31 field
| Key block version ID key_block_version 1 Identifies the method by which the key block is
| cryptographically protected and the content layout of the
| block.
| Key block length key_block_length 4 Entire key block length after encoding (header, encrypted
| (integer) confidential data, and MAC).
| Key usage key_usage 2 Provides information about the intended function of the
| protected key/sensitive data, such as data encryption, PIN
| encryption, or key wrapping. Numeric values are reserved
| for proprietary use (that is, not defined by TR-31).
| Algorithm algorithm 1 The approved symmetric algorithm for which the protected
| key may be used. Numeric values are reserved for
| proprietary use.
| Mode of use mode 1 Defines the operation for which the protected key can
| perform. Numeric values are reserved for proprietary use.
| Key version number key_version_number 2 Version number to optionally indicate that the contents of
| the key block is a component (key part), or to prevent
| re-injection of an old key. This field is a tool for
| enforcement of local key change rules.
| Exportability exportability 1 Defines whether the protected key may be exported.
| Number of optional num_opt_blocks 4 Defines the number of optional blocks included in the key
| blocks (integer) block. If this value is greater than zero, use the
| TR31_Optional_Data_Read verb to obtain the contents of
| the optional blocks.
|
| This verb does not perform cryptographic services on any key value. You cannot use this verb to change a
| key or to change the control vector related to a key.

| Restrictions
| AIX
| IBM i
| Windows
|
| Format
| CSNBT31P
| tr31_key_length Input Integer
| tr31_key Input String tr31_key_length bytes
| key_block_version Output String 1 byte
| key_block_length Output Integer
| key_usage Output String 2 bytes
| algorithm Output String 1 byte
| mode Output String 1 byte
| key_version_number Output String 2 bytes
| exportability Output String 1 byte
| num_opt_blocks Output Integer
|
| Parameters
| rule_array_count
| rule_array
| characters. No rule array keywords are currently defined for this verb.
| tr31_key_length
| The tr31_key_length parameter is a pointer to an integer variable containing the number of bytes of

| data in the tr31_key variable. Specify a length that is greater than or equal to the size of the key block.
| The verb determines the actual length of the key by parsing its contents.
| tr31_key
| The tr31_key parameter is a pointer to a string variable containing the TR-31 key block to be
| disassembled.
| key_block_version
| The key_block_version parameter is a pointer to a string variable. The verb copies the one byte found
| in the key block version ID field of the input key block to this variable.
| Note that if the verb finds a proprietary key block version ID, it treats it as an invalid value. This is
| because the verb is not capable of disassembling a key block that has a proprietary ID. This variable
| is not updated if a processing error occurs.
| key_block_length
| The key_block_length parameter is a pointer to an integer variable. The verb parses the two-byte
| numeric ASCII key block length field from the input key block, converts the string value into an integer,
| and returns the integer in this variable. This value must be less than or equal to the tr31_key_length
| input variable.
| key_usage
| The key_usage parameter is a pointer to a string variable. The verb copies the two bytes found in the
| key usage field of the input key block to this variable.
| algorithm
| The algorithm parameter is a pointer to a string variable. The verb copies the one byte found in the
| algorithm field of the input key block to this variable. The verb does not treat a proprietary
| algorithm value as an error.
| mode
| The mode parameter is a pointer to a one-byte string variable containing the TR-31 mode of use for
| the key contained in the block. The value is obtained from the TR-31 header. The mode of use
| describes what operations the key can perform, within the limitations specified with the key usage
| value. For example, a key with usage for data encryption can have a mode to indicate that it can be
| used only for encryption, decryption, or both.
| This pointer must be non-NULL and point to application storage with at least the size given by the byte
| count noted. The storage will be updated with the noted value on a successful return from this verb,
| and unchanged otherwise.
| key_version_number
| The key_version_number parameter is a pointer to a two-byte string variable obtained from the TR-31
| header, which can be used for one of three purposes, or can be unused.
| v If the both bytes are X'30' ("0"), then key versioning is unused for this key. In this case, the second
| byte is not examined and can contain any value.
| v If the first byte is X'63' ("c"), then the block contains a component of a key which must be combined
| with other components in order to form the complete key. TR-31 does not define the method
| through which the components are combined. TR-31 specifies that local rules are used for that
| purpose.
| In this case, the second byte is not examined and can contain any value.
| v If the first byte is anything other than the two values above, then the two-byte key version value is
| an identifier of the version of the key that is carried in the block. This can be used by an application,
| for example, to ensure that an old version of a key is not reentered into the system.

| exportability
| The exportability parameter is a pointer to a one-byte string variable containing the key exportability
| value from the TR-31 header. This value indicates whether the key can be exported from this system,
| and if so specifies conditions under which export is permitted. The following three values are possible:
| v If the value is X'4E' ("N"), then the key is not exportable.
| v If the value is X'53' ("S"), then the key is exportable under any key-encrypting key.
| v If the value is X'45' ("E"), then the key is exportable only under a trusted key-encrypting key. TR 31
| defines such a trusted key as either one that is encrypted under the HSM master key or one that is
| itself contained in a TR-31 key block. CCA does not support KEKs that are wrapped in TR-31 key
| blocks.
| num_opt_block
| The num_opt_block parameter is a pointer to an integer value containing the number of optional
| blocks that are part of the TR-31 key block. Information on each optional block can be obtained using
| the TR31_Optional_Data_Read verb. In this verb, use the number of optional blocks acquired with this
| verb to obtain a list of the IDs and lengths for each optional block. Then, use those lists to read the
| data from each desired block.
| Required commands
| None.

| TR31_Optional_Data_Build (CSNBT31O)
| Use the TR31_Optional_Data_Build verb to build a properly formatted TR-31 optional block from the data
| provided. The newly constructed optional block can optionally be appended to an existing structure of
| optional blocks, or it can be returned as a new optional blocks structure. After the last optional block has
| been constructed, the completed structure containing the optional blocks can be included in a TR-31 key
| block during an export operation by the Key_Export_to_TR31 verb by using its opt_blocks parameter. For
| information on TR-31, including the format of a TR-31 optional block, see X9 TR-31 2010: Interoperable
| Secure Key Exchange Block Specification for Symmetric Algorithms.
| The TR-31 key block has an unencrypted header that can contain optional blocks. The header is securely
| bound to the key block using the integrated MAC. An optional block has a two-byte ASCII block ID value
| that determines the use of the block. The ID of each block in an optional blocks structure must be unique.
| The verb builds a structure of optional blocks by adding one optional block with each call. This process is
| repeated until the entire set of optional blocks has been added. For each call, provide the components for
| a single optional block. This includes the optional block ID, the optional block length in bytes, and the
| optional block data. In addition, provide an optional blocks buffer large enough to add the optional block
| being built.
| There are two valid scenarios for the optional blocks buffer provided on input, as determined by the value
| of the opt_blocks_length variable:
| 1. The optional blocks buffer is empty. In this case, the newly constructed optional block is copied into the
| buffer.
| 2. The optional blocks buffer contains one or more existing optional blocks. In this case, the newly
| constructed optional block is appended to the existing optional blocks. No duplicate IDs are allowed.
| Upon successful completion, the opt_blocks_length variable is updated to the length of the returned
| optional blocks structure.
| Restrictions
| AIX
| IBM i
| Windows
|
| v An optional block with an ID of "PB" (padding block) cannot be added by the user. The
| Key_Export_to_TR31 verb adds a padding block of the appropriate size as needed when building the
| TR-31 key block. Unlike the padding within the encrypted key portion of the key block, the padding
| block for optional blocks serves no security purpose.
|

| Format
| CSNBT31O
| opt_blocks_bfr_length Input Integer 0
| opt_blocks_length In/Output Integer opt_blocks_bfr_length
| opt_blocks In/Output String opt_blocks_length bytes
| num_opt_blocks Output Integer 0
| opt_block_id Input String 2 bytes
| opt_block_data_length Input Integer 0
| opt_block_data Input String opt_block_data_length bytes
|
| Parameters
| rule_array_count
| in the rule_array variable. The value must be 0, because no keywords are currently defined for this
| verb.
| rule_array
| characters. No rule_array keywords are currently defined for this verb.
| opt_blocks_bfr_length
| The opt_blocks_bfr_length parameter is a pointer to an integer variable containing the length in bytes
| of the buffer allocated for the opt_blocks variable. Set this length to at least the size of any optional
| blocks structure in the buffer plus the optional block being added.
| opt_blocks_length
| The opt_blocks_length parameter is a pointer to an integer variable containing the length in bytes of
| the data in the opt_blocks variable. This length must be less than or equal to the value of the
| opt_blocks_bfr_length variable. On input, set this variable to the length of the optional blocks structure
| being updated. Set this value to zero if this is the first optional block in the structure. On successful
| completion, this variable is updated with the length of the updated variable.
| opt_blocks
| The opt_blocks parameter is a string variable containing a buffer for the optional blocks structure that
| the verb updates. In the first call to the verb, the buffer will generally be empty. The verb appends one
| optional block to the buffer with each call.
| num_opt_blocks
| The num_opt_blocks parameter is a pointer to an integer variable containing the number of optional
| blocks contained in the opt_blocks variable that is returned by the verb.

| opt_block_id
| The opt_block_id parameter is a pointer to a string variable containing a two-byte value that identifies
| the use of the optional block. Each ID must be unique, that is, no duplicates are allowed.
| Note that a value of "PB" is not allowed. The Key_Export_to_TR31 verb adds a padding block of the
| appropriate size as needed. Unlike the padding in the encryption key portion of the TR-31 key block,
| the padding block for optional blocks serves no security purpose.
| opt_block_data_length
| The opt_block_data_length parameter is a pointer to an integer variable containing the length in bytes
| of the data passed in the opt_block_data variable. Note that it is valid for this length to be zero, since
| an optional block can have an ID and a length, but no data.
| opt_block_data
| The opt_block_data parameter is a pointer to a string variable containing the data for the optional
| block that is to be constructed.
| Required commands
| None.

| TR31_Optional_Data_Read (CSNBT31R)
| Use the TR31_Optional_Data_Read verb to either obtain information about all of the optional blocks in the
| header of an external TR-31 key block, or obtain the length and data of the specified optional block. To
| disassemble the part of the header that is not optional, use the TR31_Key_Token_Parse verb. Neither
| verb performs any cryptographic services, and both disassemble a key block in application storage. The
| validity of the key block is verified as much as can be done without performing any cryptographic services.
| A TR-31 key block contains an unencrypted header that can include one or more optional blocks. All parts
| of the header are securely bound to the key block using the integrated MAC.
| Optional blocks in a key block must each be identified by a unique two-byte ID. The value of an ID must
| either be defined by TR-31 or be a numeric value, otherwise the key block is invalid. Numeric IDs are
| reserved for proprietary use. For additional information, see X9 TR-31 2010: Interoperable Secure Key
| Exchange Block Specification for Symmetric Algorithms.
| In order to obtain the data of a particular optional block from the header of an external TR-31 key block,
| perform the following steps:
| 1. Use the tr31_key parameter to identify the TR-31 key block that this verb is to process.
| 2. Call the TR31_Key_Token_Parse verb to parse the TR-31 key block. See TR31_Key_Token_Parse
| (CSNBT31P) on page 551. Upon successful completion:
| v Set the value of the tr31_key_length variable to the value returned in the tr31_key_length variable.
| v Set the value of the num_opt_blocks variable to the value returned in the num_opt_blocks variable.
| v Allocate a string buffer in bytes for the opt_blocks_id and an integer buffer in bytes for the
| opt_blocks_length variables. These buffers must be at least two times the value of the
| num_opt_blocks variable.
| 3. Specify a rule-array keyword of INFO to obtain information about the optional blocks in the key block.
| The opt_block_id, opt_block_data_length, and opt_block_data parameters are ignored.
| 4. Call the TR31_Optional_Data_Read verb to read data from the TR-31 key block. Upon successful
| completion, the verb returns an array of optional block IDs in the opt_blocks_id variable, and an array
| of lengths for the optional block IDs in the opt_blocks_length variable. The IDs and lengths are
| returned in same order as the optional blocks appear in the header of the TR-31 key block.
| 5. Determine which ID of the unique IDs contained in the opt_blocks_id variable is to be obtained from
| the TR-31 key block. Set the opt_block_id variable to this two-byte value. Set the value of the
| opt_block_data_length variable to the corresponding length from the opt_blocks_length variable.
| Note: The offset used to locate the ID in the opt_blocks_id variable has the same value as the offset
| for the corresponding length in the opt_blocks_length variable.
| 6. Allocate a buffer in bytes for the opt_block_data variable that is at least the value of the
| opt_block_data_length variable.
| 7. Specify a rule-array keyword of DATA to obtain the length and data of the specified optional block. The
| num_opt_blocks and the opt_blocks_id parameters are ignored.
| 8. Call the TR31_Optional_Data_Read verb. Upon successful completion, the verb returns the data of the
| specified optional block in the opt_block_data variable. The verb updates the opt_block_data_length
| variable to the number of bytes returned in the opt_block_data variable.

| Restrictions
| AIX
| IBM i
| Windows
|
| Format
| CSNBT31R
| tr31_key_length Input Integer
| tr31_key Input String tr31_key_length bytes
| opt_block_id Input String 2 bytes
| num_opt_blocks Input Integer
| opt_block_ids Output String array 2 * num_opt_blocks bytes
| opt_block_lengths Output String array 2 * num_opt_blocks bytes
| opt_block_data_length In/Output Integer
| opt_block_data Output String opt_block_data_length bytes
|
| Parameters
| rule_array_count
| rule_array
|| Keyword Meaning
| Operation (one required)
| INFO Return information about the optional blocks in the TR-31 key block.
| DATA Return the data contained in a specified optional block in the TR-31 key block.

|
| tr31_key_length
| The tr31_key_length parameter is a pointer to an integer variable containing the number of bytes of
| data in the tr31_key variable. Specify a length that is greater than or equal to the size of the key block.
| The verb determines the actual length of the key by parsing its contents.
| tr31_key
| The tr31_key parameter is a pointer to a string variable containing the TR-31 key block to be
| disassembled.
| opt_block_id
| The opt_block_id parameter is used when operation keyword DATA is specified, otherwise it is
| ignored. For keyword DATA, this parameter is a pointer to a string variable that identifies the two-byte
| ID of the optional block to obtain from the TR-31 key block.
| num_opt_blocks
| The num_opt_blocks parameter is used when operation keyword INFO is specified, otherwise it is
| ignored. For keyword INFO, this parameter is a pointer to an integer variable that specifies the number
| of two-byte optional block IDs that are allocated for (1) the opt_block_ids variable and (2) the number
| of two-byte integers that are allocated for the opt_block_lengths variable. This the value must specify
| the exact number of optional blocks that are in the header of the TR-31 key block. Use the
| TR31_Key_Token_Parse verb to determine the number of optional blocks IDs in a TR-31 key block
| before calling this verb.
| opt_block_ids
| The opt_block_ids parameter is used when operation keyword INFO is specified, otherwise it is
| ignored. For keyword INFO, this parameter is a pointer to a string array of two-byte values that lists
| the identifiers of each optional block contained in the header of the TR-31 key block. Each ID must be
| unique, that is, no duplicates are allowed. The IDs, along with the associated lengths listed in the
| opt_block_lengths variable, are returned in the order that the optional blocks appear in the header of
| the TR-31 key block. The size of the variable must be at least two times the value of the
| num_opts_blocks variable.
| opt_block_lengths
| The opt_block_lengths parameter is used when operation keyword INFO is specified, otherwise it is
| ignored. For keyword INFO, this parameter is a pointer to an integer array of two-byte values that are
| 16-bit unsigned integers corresponding to the associated length of the optional block identified in the
| opt_block_ids variable. The lengths, along with the associated IDs listed in the opt_block_ids variable,
| are returned in the order that the optional blocks appear in the header of the TR-31 key block. The
| size of the variable must be at least two times the value of the num_opts_blocks variable.
| opt_block_data_length
| The opt_block_data_length parameter is used when operation keyword DATA is specified, otherwise it
| is ignored. For keyword DATA, this parameter is a pointer to an integer variable containing the length
| of the opt_block_data parameter. On input, this variable specifies the maximum permissible length of
| the result. On output, the verb updates the value to length of the returned optional block data.
| opt_block_data
| The opt_block_data parameter is used when operation keyword DATA is specified, otherwise it is
| ignored. For keyword DATA, this parameter is a pointer to a string variable. If the TR-31 key block is
| found to be valid and the TR-31 key block contains an optional block specified by the
| optional_block_ID variable, the optional block is copied into this variable if it is large enough. The
| opt_block_data_length variable is updated with the length of the data returned in the variable.
| Required commands
| None.

|
Appendix A. Return codes and reason codes
This section describes the return codes and reason codes reported at the conclusion of verb processing.
Reason code numbers narrow down the meaning of a return code. All reason code numbers are unique
and associated with a single return code. Generally, you can base your application program design on the
return codes.
Each verb supplies a return code and a reason code in the variables identified by the return_code and
reason_code parameters. See Parameters common to all verbs on page 9.
Return codes
A return code provides a general indication of the results of verb processing. A return code can have the
values shown in Table 79.
Table 79. Return code values
Hex value Decimal value Meaning
00 00 This return code indicates a normal completion of verb processing.
To provide additional information, there are also nonzero reason
codes associated with this return code.
04 04 This return code is a warning that indicates that the verb
completed processing; however, an unusual event occurred. The
event is most likely related to a problem created by the user, or it
is a normal occurrence based on the data supplied to the verb.
08 08 This return code indicates that the verb prematurely stopped
processing. Generally, the application programmer needs to
investigate the significance of the associated reason code to
determine the origin of the problem. In some cases, due to
transient conditions, retrying the verb might produce different
results.
0C 12 This return code indicates that the verb prematurely stopped
processing. Either a coprocessor is not available or a processing
error occurred. The reason is most likely related to a problem in
the set up of the hardware or in the configuration of the software.
10 16 This return code indicates that the verb prematurely stopped
processing. A processing error occurred. If these errors persist, a
repair of the coprocessor hardware or a correction to the
coprocessor software might be required.
Note: If an application receives a return code greater than 4, an error occurred. In the case of an error,
assume that any output variables other than the return code and reason code are not valid.
Reason codes
A reason code details the results of verb processing. Every reason code is associated with a single return
code. A nonzero reason code can be associated with a zero return code.
User Defined Extensions (UDX) return reason codes in the range of 20480 (X'5000') through 24575
(X'5FFF').
561
The remainder of this appendix lists the reason codes that accompany each of the return codes. The
return codes are shown in decimal form, and the reason codes are shown in decimal and in hexadecimal
(hex) form.
Reason codes that accompany return code 0

Table 80. Reason codes for return code 0
Return code Reason code

in decimal decimal (hex) Meaning
0 000 (000) The verb completed processing successfully.
0 002 (002) One or more bytes of a key do not have odd parity.
0 151 (097) The key token supplies the MAC length or MACLEN4 is the default for
key tokens that contain MAC or MACVER keys.
0 701 (2BD) A new master-key value has duplicate thirds.
0 702 (2BE) A provided master-key part does not have odd parity.
| 0 2146 (862) A weaker key was used to wrap a stronger key and the Warn When
| Wrapping Weak Keys command (offset X'032C') was enabled in the
| active role.
0 10 001 (2711) A key encrypted under the old master key was used.
| 0 10 002 (2712) A fully qualified dataset name is longer than 64 bytes and the
| environment variable CSUxxxLD is not defined (where xxx is either AES,
| DES, or PKA). The current directory has been abbreviated as a single
| dot (period).
| 0 10 003 (2713) A fully qualified dataset name is longer than 64 bytes and the
| environment variable CSUxxxLD is defined (where xxx is either AES,
| DES, or PKA). Only the dataset name is returned. Use the CSUxxxLD
| environment variable to determine the fully qualified dataset name.


4 001 (001) The verification test failed.
4 013 (00D) The key token has an initialization vector, and the initialization_vector
variable is nonzero. The verb uses the value in the key token.
4 016 (010) The rule array and the rule-array count are too small to contain the
complete result.
4 017 (011) The requested ID is not present in any profile in the specified
cryptographic hardware component.
4 019 (013) The financial PIN in a PIN block is not verified.
4 158 (09E) The verb did not process any key records.
4 166 (0A6) The control-vector is not valid because of parity bits, anti-variant bits, or
inconsistent KEK bits, or because bits 59 to 62 are not zero.
4 179 (0B3) The control-vector keywords that are in the rule array are ignored.
4 283 (11B) The coprocessor battery is low.
4 287 (11F) The PIN-block format is not consistent.

Table 81. Reason codes for return code 4 (continued)

4 429 (1AD) The digital signature is not verified. The verb completed its processing
normally.
4 1024 (400) Sufficient shares have been processed to create a new master key.
4 2039 (7F7) At least one control vector bit, key usage field, or key management field
cannot be parsed.
4 2042 (7FA) The supplied passphrase is not valid.
| 4 2133 (855) The verb_data value identifies one or more PIN decimalization tables to
| be deleted that are not stored on the coprocessor. All PIN tables that
| were requested to be deleted are removed.


8 012 (00C) The token-validation value in an external key token is not valid.
8 022 (016) The ID number in the request field is not valid.
8 023 (017) An access to the data area is outside the data-area boundary.
8 024 (018) The master-key verification pattern is not valid.
8 025 (019) The value that the text_length parameter specifies is not valid.
8 026 (01A) The value of the PIN is not valid.
8 029 (01D) The token-validation value in an internal key token is not valid.
8 030 (01E) No record with a matching key label is in key storage.
8 031 (01F) The control vector does not specify a DATA key.
8 032 (020) A key label format is not valid.
8 033 (021) A rule array or other parameter specifies a keyword that is not valid.
8 034 (022) A rule-array keyword combination is not valid.
8 035 (023) A rule-array count is not valid.
8 036 (024) The action command must be specified in the rule array.
8 037 (025) The object type must be specified in the rule array.
8 039 (027) A control vector violation occurred. Check all control vectors employed
with the verb. For security reasons, no detail is provided.
8 040 (028) The service code does not contain numerical character data.
8 041 (029) The keyword specified by the key_form parameter is not valid.
8 042 (02A) The expiration date is not valid.
8 043 (02B) The length specified by the key_token_length parameter or the keyword
specified by the key_length parameter is not valid.
8 044 (02C) A record with a matching key label already exists in key storage.
8 045 (02D) The input character string cannot be found in the code table.
8 046 (02E) The card-validation value (CVV) is not valid.
Appendix A. Return codes and reason codes 563


8 047 (02F) A source key token is unusable because it contains data that is not valid
or is undefined.
8 048 (030) One or more keys has a master-key verification pattern that is not valid.
8 049 (031) A key-token version number found in a key token is not supported.
8 050 (032) The key-serial-number specified in the rule array is not valid.
8 051 (033) The value that the text_length parameter identifies is not a multiple of the
cryptographic algorithm block length.
8 054 (036) The value that the pad_character parameter specifies is not valid.
8 055 (037) The initialization vector in the key token is enciphered.
8 056 (038) The master-key verification pattern in the OCV is not valid.
8 058 (03A) The parity of the operating key is not valid.
8 059 (03B) Control information (for example, the processing method or the pad
character) in the key token conflicts with that in the rule array.
8 060 (03C) A cryptographic request with the FIRST or MIDDLE keywords and a text
length less than 8 bytes is not valid.
8 061 (03D) The keyword specified by the key_type parameter is not valid.
8 062 (03E) The source key is not present.
8 063 (03F) A key token has an invalid token header (for example, not an internal
token).
8 064 (040) The key is not permitted to perform the requested operation. A likely
cause is that key distribution usage is not enabled for the key.
8 065 (041) The key token failed consistency checking.
8 066 (042) The recovered encryption block failed validation checking.
8 067 (043) RSA encryption failed.
8 068 (044) RSA decryption failed.
| 8 070 (46) An invalid block identifier (identifier tag) was found. Either a block ID
| (identifier tag) that was proprietary was found, a reserved block ID was
| used, a duplicate block ID was found, or the specified optional block in
| the TR-31 key block could not be found.
8 072 (048) The value that the size parameter specifies is not valid (too small, too
large, negative, or zero).
8 081 (051) The modulus length (key size) exceeds the allowable maximum.
8 085 (055) The date or the time value is not valid.
8 090 (05A) Access control checking failed. See the Required commands section for
the failing verb.
8 091 (05B) The time that was sent in your logon request was more than five minutes
different from the clock in the secure module.
8 092 (05C) The user profile is expired.
8 093 (05D) The user profile has not yet reached its activation date.
8 094 (05E) The authentication data (for example, passphrase) is expired.
8 095 (05F) Access to the data is not authorized.
8 096 (060) An error occurred reading or writing the secure clock.


8 100 (064) The PIN length is not valid.
8 101 (065) The PIN check length is not valid. It must be in the range from 4 to the
PIN length inclusive.
8 102 (066) The value of the decimalization table is not valid.
8 103 (067) The value of the validation data is not valid.
8 104 (068) The value of the customer-selected PIN is not valid, or the PIN length
does not match the value specified by the PIN_length parameter or
defined by the PIN-block format specified in the PIN profile.
8 105 (069) The value of the transaction_security_parameter is not valid.
8 106 (06A) The PIN-block format keyword is not valid.
8 107 (06B) The format control keyword is not valid.
8 108 (06C) The value or the placement of the padding data is not valid.
8 109 (06D) The extraction method keyword is not valid.
8 110 (06E) The value of the PAN data is not numeric character data.
8 111 (06F) The sequence number is not valid.
8 112 (070) The PIN offset is not valid.
8 114 (072) The PVV value is not valid.
8 116 (074) The clear PIN value is not valid. For example, digits other than 0 - 9 were
found.
8 120 (078) An origin or destination identifier is not valid.
8 121 (079) The value specified by the inbound_key or source_key parameter is not
valid.
8 122 (07A) The value specified by the inbound_KEK_count or outbound_count
parameter is not valid.
8 125 (07D) A PKA92-encrypted key having the same EID as the local node cannot
be imported.
8 129 (081) Required rule-array keyword not found.
8 153 (099) The text length exceeds the system limits.
8 154 (09A) The key token that the key_identifier parameter specifies is not an
internal key-token or a key label.
8 155 (09B) The value that the generated_key_identifier parameter specifies is not
valid, or it is not consistent with the value that the key_form parameter
specifies.
8 156 (09C) A keyword is not valid with the specified parameters.
8 157 (09D) The key-token type is not specified in the rule array.
8 159 (09F) The keyword supplied with the option parameter is not valid.
8 160 (0A0) The key type and the key length are not consistent.
8 161 (0A1) The value that the dataset_name_length parameter specifies is not valid.
8 162 (0A2) The offset value is not valid.
8 163 (0A3) The value that the dataset_name parameter specifies is not valid.
8 164 (0A4) The starting address of the output area falls inside the input area.


8 165 (0A5) The carryover_character_count that is specified in the chaining vector is
not valid.
8 168 (0A8) A hexadecimal MAC value contains characters that are not valid, or the
MAC on a request or reply failed because the user session key in the
host and the adapter card do not match.
8 169 (0A9) The MDC_Generate text length is in error.
8 170 (0AA) The value of the mechanism strength in the passphrase authentication
data structure of the user profile is less than the minimum authorization
level required.
8 171 (0AB) The control_array_count value is not valid.
8 175 (0AF) The key token cannot be parsed because no control vector is present.
8 180 (0B4) A key token presented for parsing is null.
8 181 (0B5) The key token is not valid. The first byte is not valid, or an incorrect token
type was presented.
8 183 (0B7) The key type is not consistent with the key type of the control vector.
8 184 (0B8) A required pointer is null.
8 185 (0B9) A disk I/O error occurred: perhaps the file is in-use, does not exist, and
so forth.
8 186 (0BA) The key-type field in the control vector is not valid.
8 187 (0BB) The requested MAC length (MACLEN4, MACLEN6, MACLEN8) is not
consistent with the control vector (key-A, key-B).
8 191 (0BF) The requested MAC length (MACLEN6, MACLEN8) is not consistent with
the control vector (MAC-LN-4).
8 192 (0C0) A key-storage record contains a record validation value that is not valid.
8 204 (0CC) A memory allocation failed. This can occur in the host and in the
coprocessor. Try closing other host tasks. If the problem persists, contact
the IBM support center.
8 205 (0CD) The X9.23 ciphering method is not consistent with the use of the
CONTINUE keyword.
8 323 (143) The ciphering method that the Decipher verb used does not match the
ciphering method that the Encipher verb used.
8 335 (14F) Either the specified cryptographic hardware component or the
environment cannot implement this function.
8 340 (154) One of the input control vectors has odd parity.
8 343 (157) Either the data block or the buffer for the block is too small, or a variable
has caused an attempt to create an internal data structure that is too
large.
| 8 345 (159) Insufficient storage space exists for the data in the data block buffer.
8 374 (176) Less data was supplied than expected or less data exists than was
requested.
8 377 (179) A key-storage error occurred.
8 382 (17E) A time-limit violation occurred.
8 385 (181) The cryptographic hardware component reported that the data passed as
part of a command is not valid for that command.


8 387 (183) The cryptographic hardware component reported that the user ID or role
ID is not valid.
8 393 (189) The command was not processed because the profile cannot be used.
8 394 (18A) The command was not processed because the expiration date was
exceeded.
8 397 (18D) The command was not processed because the active profile requires the
user to be verified first.
8 398 (18E) The command was not processed because the maximum PIN or
password failure limit is exceeded.
8 407 (197) There is a PIN-block consistency-check-error.
8 439 (1B7) Key cannot be completed because all required key parts have not yet
been accumulated, or key is already complete.
| 8 441 (1B9) Key part cannot be added because key is complete. The key to be
| processed should be partial, but the key is not partial according to the
| control vector or other control bits of the key.
8 442 (1BA) DES keys with replicated halves are not allowed.
8 605 (25D) The number of output bytes is greater than the number that is permitted.
8 703 (2BF) A new master-key value is one of the weak DES keys.
8 704 (2C0) A new master key cannot have the same master-key version number or
master-key verification pattern as the current master-key.
8 705 (2C1) Both exporter keys specify the same key-encrypting key.
8 706 (2C2) Pad count in deciphered data is not valid.
8 707 (2C3) The master-key registers are not in the state required for the requested
function.
8 714 (2CA) A reserved parameter must be a null pointer or an expected value.
8 715 (2CB) A parameter that must have a value of zero is not valid.
8 718 (2CE) The hash value of the data block in the decrypted RSA-OAEP block does
not match the hash of the decrypted data block.
8 719 (2CF) The block format (BT) field in the decrypted RSA-OAEP block does not
have the correct value.
8 720 (2D0) The initial byte (I) in the decrypted RSA-OAEP block does not have a
valid value.
8 721 (2D1) The V field in the decrypted RSA-OAEP does not have the correct value.
8 752 (2F0) The key-storage file path is not usable.
8 753 (2F1) Opening the key-storage file failed.
8 754 (2F2) An internal call to the key_test command failed.
8 756 (2F4) Creation of the key-storage file failed.
8 760 (2F8) An RSA key-modulus length in bits or in bytes is not valid.
8 761 (2F9) An RSA-key exponent length is not valid.
8 762 (2FA) A length in the key value structure is not valid.
8 763 (2FB) The section identification number within a key token is not valid.
8 770 (302) The PKA key-token has a field that is not valid.


8 771 (303) The user is not logged on.
8 772 (304) The requested role does not exist.
8 773 (305) The requested profile does not exist.
8 774 (306) The profile already exists.
8 775 (307) The supplied data is not replaceable.
8 776 (308) The requested ID is already logged on.
8 777 (309) The authentication data is not valid.
8 778 (30A) The checksum for the role is in error.
8 779 (30B) The checksum for the profile is in error.
8 780 (30C) There is an error in the profile data.
8 781 (30D) There is an error in the role data.
8 782 (30E) The function-control-vector header is not valid.
8 783 (30F) The command is not permitted by the function-control-vector value.
8 784 (310) The operation you requested cannot be performed because the user
profile is in use.
8 785 (311) The operation you requested cannot be performed because the role is in
use.
8 1025 (401) The registered public key or retained private key name already exists.
8 1026 (402) The key name (registered public key or retained private key) does not
exist.
8 1027 (403) Environment identifier data is already set.
8 1028 (404) Master key share data is already set.
8 1029 (405) There is an error in the EID data.
8 1030 (406) There is an error in using the master key share data.
8 1031 (407) There is an error in using registered public key or retained private key
data.
8 1032 (408) There is an error in using registered public key hash data.
8 1033 (409) The public key hash was not registered.
8 1034 (40A) The public key was not registered.
8 1035 (40B) The public key certificate signature was not verified.
8 1037 (40D) There is a master key shares distribution error.
8 1038 (40E) The public key hash is not marked for cloning.
8 1039 (40F) The registered public key hash does not match the registered hash.
8 1040 (410) The master key share enciphering key could not be enciphered.
8 1041 (411) The master key share enciphering key could not be deciphered.
8 1042 (412) The master key share digital signature generate failed.
8 1043 (413) The master key share digital signature verify failed.
8 1044 (414) There is an error in reading VPD data from the adapter.
8 1045 (415) Encrypting the cloning information failed.
8 1046 (416) Decrypting the cloning information failed.


8 1047 (417) There is an error loading new master key from master key shares.
8 1048 (418) The clone information has one or more sections that are not valid.
8 1049 (419) The master key share index is not valid.
8 1050 (41A) The public-key encrypted-key is rejected because the EID with the key is
the same as the EID for this node.
8 1051 (41B) The private key is rejected because the key is not flagged for use in
master-key cloning.
8 1052 (41C) Token identifier of the header section is in the range X'20' - X'FF'.
8 1053 (41D) The Active flag in section X'14' of the trusted block is not disabled.
8 1054 (41E) Token identifier of the header section is not external X'1E'.
8 1055 (41F) The Active flag in section X'14' of the trusted block is not enabled.
8 1056 (420) Token identifier of the header section is not internal X'1F'.
8 1057 (421) Trusted block rule section X'12' rule ID does not match input parameter
rule ID.
8 1058 (422) Trusted block contains a value that is too small or too large.
8 1059 (423) A trusted block parameter that must have a value of zero (or a grouping
of bits set to zero} is not valid.
8 1060 (424) Trusted block public-key section failed consistency checking.
8 1061 (425) Trusted block contains at least one extraneous section or subsection
(TLV).
8 1062 (426) Trusted block has at least one missing section or subsection (TLV).
8 1063 (427) Trusted block contains at least one duplicate section or subsection (TLV).
8 1064 (428) The expiration date of the trusted block is expired (compared to the
cryptographic coprocessor clock).
8 1065 (429) The expiration date of the trusted block precedes the activation date.
8 1066 (42A) Trusted block public key modulus bit length is not consistent with the byte
length. The bit length must be less than or equal to 8 * byte length, and
greater than 8 * (byte length - 1).
8 1067 (42B) Trusted block public key modulus length in bits exceeds maximum
allowed bit length as defined by the function control vector (FCV).
8 1068 (42C) One or more trusted block sections or TLV objects contains data that is
not valid (for example, invalid label data in label section X'13').
8 1069 (42D) Trusted block verification attempted by function other than CSNDDSV,
CSNDKTC, CSNBKPI, CSNDRKX, or CSNDTBC.
8 1070 (42E) Trusted block rule ID contained within the rule section contains one or
more invalid characters.
8 1071 (42F) The key length or control vector of the source key does not match the
rule section in the trusted block that was selected by the rule ID input
parameter.
8 1072 (430) The activation date is not valid.
8 1073 (431) The source-key label does not match the template in the export key DES
token parameters TLV object of the selected trusted block rule section.


8 1074 (432) The control-vector value specified in the common export key parameters
TLV object in the selected rule section of the trusted block contains a
control vector that is not valid.
8 1075 (433) The source-key label template in the export key DES token parameters
TLV object in the selected rule section of the trusted block contains a
label template that is not valid.
8 1077 (435) Key wrapping option input error.
8 1078 (436) Key wrapping Security Relevant Data Item (SRDI) error.
8 1100 (44C) There is a general hardware device driver execution error.
8 1101 (44D) There is a hardware device driver parameter that is not valid.
8 1102 (44E) There is a hardware device driver non-valid buffer length.
8 1103 (44F) The hardware device driver has too many opens. The device cannot
open now.
8 1104 (450) The hardware device driver is denied access.
8 1105 (451) The hardware device driver device is busy and cannot perform the
request now.
8 1106 (452) The hardware device driver buffer is too small and the received data is
truncated.
8 1107 (453) The hardware device driver request is interrupted and the request is
aborted.
8 1108 (454) The hardware device driver detected a security tamper event.
| 8 1114 (45A) The communications manager detected that the host-supplied buffer for
| the reply control block is too small.
| 8 1115 (45B) The communications manager detected that the host-supplied buffer for
| the reply data block is too small.
8 2034 (7F2) The environment variable that was used to set the default coprocessor is
not valid, or does not exist for a coprocessor in the system.
8 2036 (7F4) The contents of a chaining vector are not valid. Ensure that the chaining
vector was not modified by your application program.
8 2038 (7F6) No RSA private key information is provided.
8 2041 (7F9) A default coprocessor environment variable is not valid.
8 2050 (802) The current-key serial number (CKSN) field in the PIN_profile variable is
not valid (not hexadecimal or too many 1 bits).
8 2051 (803) There is a non-valid message length in the OAEP-decoded information.
8 2053 (805) No message found in the OAEP-decoded data.
8 2054 (806) There is a non-valid RSA Enciphered Key cryptogram: OAEP optional
encoding parameters failed validation.
| 8 2055 (807) Based on the hash method and size of the symmetric key specified, the
| RSA public key size is too small to format the symmetric key into a
| PKOAEP2 message.
8 2062 (80E) The active role does not permit you to change the characteristic of a
double-length key in the Key_Part_Import parameter.
8 2065 (811) The specified key token is not null.
| 8 2080 (820) The group profile was not found.


| 8 2081 (821) The group has duplicate elements.
| 8 2082 (822) The group profile is not in the group.
| 8 2083 (823) The group has the wrong user ID count.
| 8 2084 (824) The group user ID failed.
| 8 2085 (826) The profile is not in the specified group.
| 8 2086 (826) The group role was not found.
| 8 2087 (827) The group profile has not been activated.
| 8 2088 (828) The expiration date of the group profile has been reached or exceeded.
8 2089 (829) There is an inconsistency in the specification of a cryptographic
algorithm. The verb contains multiple keywords or parameters that
indicate the algorithm to be used, and at least one of these specifies or
implies a different algorithm from the others.
| 8 2090 (82A) A required SRDI was not found.
| 8 2091 (82B) A required CA SRDI was not found.
8 2095 (82F) The key_type value is not compatible with the key_form value.
8 2097 (831) The key_length value is not compatible with the key_type value.
8 2098 (832) Either an AES key-token contains an invalid clear-key bit length (not 128,
192, or 256), or an external DES key-token with a token version number
of X'01' has an invalid key-length flag.
8 2099 (833) Byte length of encrypted key in AES key-token is invalid.
8 2106 (83A) An input/output error occurred while accessing the logged on users table.
8 2110 (83E) Invalid wrapping type.
8 2111 (83F) Control vector enhanced bit (bit 56) conflicts with key wrapping keyword.
8 2113 (841) A key token contains invalid payload.
8 2114 (842) Clear-key bit length is out of range.
8 2115 (843) Input key token cannot have a key present when importing the first key
part; skeleton key token is required.
| 8 2118 (846) One or more invalid values in the TR-31 key block header.
| 8 2119 (847) The "mode" value in the TR-31 header is invalid or is not acceptable in
| the chosen operation.
| 8 2121 (849) The "algorithm" value in the TR-31 header is invalid or is not acceptable
| in the chosen operation.
| 8 2122 (84A) For import, the exportability byte in the TR-31 header contains a value
| that does not support import of the key into CCA. For export, the
| requested exportability does not match circumstances (for example, a 'B'
| Key Block Version ID key can be wrapped only by a KEK that is wrapped
| in CBC mode, the ECB mode KEK violates ANS X9.24).
| 8 2123 (84B) The length of the cleartext key in the TR-31 block is invalid (for example,
| the algorithm is 'D' for single-length DES, but the key length is not 64
| bits).
| 8 2125 (84D) The Key Block Version ID in the TR-31 header contains an invalid value.
| 8 2126 (84E) The key-usage field in the TR-31 header contains a value that is not
| supported for import of the key into CCA.


| 8 2127 (84F) The key-usage field in the TR-31 header contains a value that is not valid
| with the other parameters in the header.
| 8 2129 (851) Either a parameter for building a TR-31 key block (a TR-31 key block or
| a component, such as a tag for an optional block) contains one or more
| ASCII characters that are not printable as described in TR-31, or a field
| contains ASCII characters that are not allowed for that field.
| 8 2130 (852) The control vector carried in the optional blocks of the TR-31 key block is
| inconsistent with other attributes of the key.
| 8 2131 (853) The TR-31 key-token failed the MAC validate step of the Key Block
| unwrap and verify steps (for either Key Block Version ID method). MAC
| validation failed for a parameter in a key block, such as a trusted block or
| a TR-31 key block. This might be the result of tampering, corruption, or
| using a validation key that is different from the one use to generate the
| MAC.
| 8 2134 (856) No valid PIN decimalization tables are present.
| 8 2135 (857) The PIN decimalization table provided as input is not allowed to be used
| because it does not match any of the active tables stored on the
| coprocessor.
| 8 2137 (859) There is an error involving the PIN decimalization table input data. No
| PIN tables have been changed.
| 8 2138 (85A) At least one of the PIN decimalization tables requested to be activated is
| empty or already in the active state (not in the loaded state). No PIN
| tables have been activated.
| 8 2139 (85B) At least one PIN decimalization table provided as input to be activated
| does not match the corresponding table that is loaded on the
| coprocessor. No PIN tables have been changed from the loaded state to
| the active state.
| 8 2141 (84D) The key verification pattern for the key-encrypting key is not valid.
| 8 2142 (85E) A key-usage field setting prevents operation.
| 8 2143 (85F) A key-management field setting prevents operation.
| 8 2145 (861) An attempt to wrap a stronger key with a weaker key was disallowed.
| 8 2147 (863) The key type to be generated is not valid.
| 8 2149 (865) The key to be generated is stronger than the input material.
| 8 2151 (867) At least one PIN decimalization table identifier provided as input is out of
| range or is a duplicate. No PIN tables have been changed.
| 8 2153 (869) The input token is incompatible with the service (that is, clear key when
| encrypted key was expected).
| 8 2154 (86A) At least one key token does not have the required key type for the
| specified function.
| 8 2158 (86E) There is a mismatch between ECC key tokens of curve types, key
| lengths, or both. Curve types and key lengths must match.
| 8 2159 (86F) A key-encrypting key is invalid.
| 8 2161 (871) A wrap type, either requested or default, is in conflict with one or more
| input tokens.
8 3001 (BB9) The RSA-OAEP block contains a PIN block and the verb did not request
PINBLOCK processing.


8 3013 (BC5) The LRC checksum in the AES key-token does not match the LRC
checksum of the clear key.
| 8 3047 (BE7) Use of clear key provided is not allowed. A secure key is required.
8 6000 (1770) The specified device is already allocated.
8 6001 (1771) No device is allocated.
8 6002 (1772) The specified device does not exist.
8 6003 (1773) The specified device is an improper type.
8 6004 (1774) Use of the specified device is not authorized for this user.
8 6005 (1775) The specified device is not varied online.
8 6006 (1776) The specified device is in a damaged state.
8 6007 (1777) The key-storage file is not designated.
8 6008 (1778) The key-storage file is not found.
8 6009 (1779) The specified key-storage file is either the wrong type or the wrong
format.
8 6010 (177A) The user is not authorized to use the key-storage file.
8 6011 (177B) The specified CCA verb request is not permitted from a secondary
thread.
8 6012 (177C) A cryptographic resource is already allocated.
8 6013 (177D) The length of the cryptographic resource name is not valid.
8 6014 (177E) The cryptographic resource name is not valid, or does not refer to a
coprocessor that is available in the system.
| 8 6015 (177F) An ECC curve type is invalid or its usage is inconsistent.
| 8 6017 (1781) Curve size p is invalid or its usage is inconsistent.
| 8 6018 (1782) Error returned from CLiC module.


12 097 (061) File space in key storage is insufficient to complete the operation.
12 196 (0C4) The device driver, the security server, or the directory server is not
installed, or is not active. In AIX or Linux, file permissions are not valid for
your application.
12 197 (0C5) There is a key-storage file I/O error, or the file is not found.
12 206 (0CE) The key-storage file is not valid, or the master-key verification failed.
There is an unlikely, but possible, synchronization problem with the
Master_Key_Process verb.
12 207 (0CF) The verification method flags in the profile are not valid.
12 319 (13F) The host software is out-of-date.


12 324 (144) There is insufficient memory available to process your request, either
memory in the host computer, or memory inside the coprocessor including
the flash EPROM used to store keys, profiles, and other application data.
12 338 (152) This cryptographic hardware device driver is not installed or is not
responding, or the CCA code is not loaded in the coprocessor.
12 764 (2FC) The master keys are not loaded and, therefore, a key cannot be
recovered or enciphered.
12 768 (300) One or more paths for key-storage directory operations are improperly
specified.
12 769 (301) A cryptographic internal device driver component detected data contained
in a cryptographic request that is not valid.
12 2045 (7FD) The CCA software is unable to claim a semaphore. The system might be
short of resources.
12 2046 (7FE) The CCA software is unable to list all of the keys. The limit of 500 000
keys might have been reached.
| 12 2049 (801) An error occurred while unlocking a semaphore in order to release the
| exclusive control of that semaphore.
| 12 2074 (81A) Invalid version found in Connectivity Programming Request/Reply Block
| (CPRB).
12 2101 (835) Invalid AES flags in the function control vector (FCV).
| 12 2117 (845) Thread specific CLiC objects are not in proper state.
| 12 2155 (86B) The length of the fully qualified dataset name exceeds the maximum size
| that the verb can process.


16 099 (063) An unrecoverable error occurred in the security server. Contact IBM
support.
16 336 (150) An error occurred in a cryptographic hardware or software component.
16 337 (151) A device software error occurred.
16 339 (153) An unrecoverable error occurred in the cryptographic command
processor. Contact IBM support.
16 444 (1BC) The verb-unique-data has an invalid length.
16 556 (22C) The request parameter block failed consistency checking.
16 708 (2C4) The cryptographic engine is returning inconsistent data.
16 709 (2C5) Cryptographic engine internal error, could not access the master-key
data.
16 710 (2C6) An unrecoverable error occurred while attempting to update master-key
data items.
16 712 (2C8) An unexpected error occurred in the master-key manager.


16 800 (320) One_Way_Hash failed with an internal error.
16 2047 (7FF) Unable to transfer Request Data from host to coprocessor.
16 2057 (809) Internal error: memory allocation failure.
16 2058 (80A) Internal error: unexpected return code from OAEP routines.
16 2059 (80B) Internal error: OAEP SHA-1 request failure.
16 2061 (80D) Internal error in CSNDSYI, OAEP-decode: enciphered message too
long.
| 16 2063 (80F) Reply message too long.
16 2107 (83B) Internal error: Security Relevant Data Item (SRDI) verification failure.
| 16 2150 (866) An error occurred while attempting to open or save the DECTABLE
| SRDI that is stored on the coprocessor.

Appendix B. Data structures
This section describes the following data structures:
v Key tokens and trusted blocks
| v TR-31 optional block data on page 629
| v ACI smart card formats on page 630
v Chaining-vector work areas on page 633
v Key-storage datasets and records on page 633
v Key-record-list datasets and records on page 637
v Access-control data structures on page 638
v Master-key shares data formats on page 649
v Distributed function control vector on page 650
Key tokens and trusted blocks

This section describes the AES, DES and PKA (RSA and ECC) key tokens used with the product. This
section also describes trusted blocks. A key token is a data structure that contains information about a key
and usually contains a key or keys. A trusted block is an extension of CCA RSA key tokens, and is an
integral part of a remote key-loading process.
In general, a key that is available to an application program or held in key storage is multiply-enciphered
by some other key. When a key is enciphered by the CCA node's master key, the key is designated an
internal key and is held in an internal key-token structure. Therefore, an internal key-token or internal
trusted block is used to hold a key and its related information for use at a specific CCA node.
An external key-token or external trusted block is used to communicate a key between nodes, or to hold a
key in a form not enciphered by a CCA master key. DES keys and PKA private-keys contained in an
external key-token or external trusted block are multiply-enciphered by a transport key. In a CCA-node, a
transport key is a double-length DES key-encrypting key (KEK).
The remainder of this section describes the structures used with the IBM 4765 and IBM 4764:
v Master-key verification pattern
v Token-validation value and record-validation value on page 578
v Null key tokens on page 578
v Internal fixed-length AES key tokens on page 578 (Release 3.30 or later)
v Fixed-length DES key tokens on page 580
v External RKX DES key tokens on page 583
v PKA key tokens on page 585
v Trusted blocks on page 600
v Variable-length symmetric key-token on page 614
Master-key verification pattern

A master-key verification pattern (MKVP) exists within an internal AES or DES key-token that has an
encrypted key present. An MKVP also exists within an internal PKA key-token that has an encrypted RSA
or ECC private-key present or within an active internal CCA trusted block. See Internal fixed-length AES
key-token flag byte on page 580 and Fixed-length DES key-token flag bytes (internal and external) on
page 583. An MKVP permits the cryptographic engine to detect whether the key within the token is
enciphered by an available master key. Different internal key-verification-pattern approaches are employed
depending on the version of the key token and, for DES key tokens, the value of the symmetric master
key. See Master-key verification algorithms on page 677.
577
An IBM 4765 or IBM 4764 does not permit the introduction of a new master-key value that has the same
verification value as either the current master-key or as the old master-key.
Token-validation value and record-validation value

The token-validation value (TVV) is a checksum that helps ensure that an application-program provided
fixed-length AES or DES key-token is valid. A TVV is the sum (twos complement ADD), ignoring carries
and overflow, of the key token by operating on 4 bytes at a time, starting with bytes 0 - 3 and ending with
bytes 56 - 59. The 4-byte strings are treated as big-endian binary numbers with the high-order byte stored
in the lower address. Fixed-length AES and DES key-token bytes 60 - 63 contain the TVV.
When an application program supplies a fixed-length AES or DES key-token, the CCA node checks the
TVV. When a CCA verb builds a fixed-length AES or DES key-token, it calculates and stores a TVV in the
key token.
The record-validation value (RVV) used in AES, DES, and PKA key-storage records is calculated in the
same manner as the AES or DES TVV, except that for PKA the last bytes added are always treated as a
4-byte integer. The RVV is the sum of each sequential 4-byte value in the record, except for the four bytes
where the RVV itself is stored.
Null key tokens

With some CCA verbs, a null key-token can be used instead of an internal or an external key-token. A verb
generally accepts a null key token as a signal to use a key token with default values. A null key token
always has a value of X'00' as its first byte.
Null AES key-token

A null AES key-token consists of 64 bytes of X'00'.
Note: AES key tokens are not supported in releases before Release 3.30.
Null DES key-token

A null DES key-token is indicated by the value X'00' at offset zero in a key token, a key-token record in
key storage, a key-token variable, or a key-identifier variable.
The (DES) Key_Import verb accepts input with offset zero valued to X'00'. In this special case, the verb
treats information starting at offset 16 as an enciphered, single-length key. In a very limited sense, this
special case can be considered a null DES key-token.
Null PKA key-token

PKA key-storage uses an 8-byte structure, shown in Table 95 on page 587, to represent a null PKA key
token. The PKA_Key_Record_Read verb returns this structure if a key record with a null PKA key-token is
read. When examining PKA key-storage, expect key records without a key token containing specific key
values to be represented by a null PKA key-token. In the case of key-storage records, the record length
(offset 2 and 3) can be greater than 8.
Internal fixed-length AES key tokens

Fixed-length AES key-token data structures are 64 bytes in length, and are made up of an internal
key-token identifier and a token version number, reserved fields, a flag byte containing various flag bits,
and a token-validation value.
Note: Fixed-length AES key tokens are not supported in releases before Release 3.30.
Depending on the flag byte, the key token either contains an encrypted key, a clear key, or the key is
absent. An encrypted key is encrypted under an AES master key identified by a master-key verification
pattern (MKVP) in the key token. The key token contains a two-byte integer that specifies the length of the

clear-key value in bits, valued to 0, 128, 192, or 256, and a two-byte integer that specifies the length of the
encrypted-key value in bytes, valued to 0 or 32. An LRC checksum byte of the clear-key value is also in
the key token.
All keys in fixed-length AES key tokens are DATA keys. If the flag byte indicates that a control vector (CV)
is present, it must be all binary zeros. An all-zero CV represents the CV value of an AES DATA key. If a
key is present without a control vector in a key token, that is accepted and the key is interpreted as an
AES DATA key.
The AES internal key-token is the structure used to hold AES keys that are either encrypted with the AES
master-key, or in cleartext format.
Table 85. Internal fixed-length AES key-token format, version X'04'
0 1 X'01' (a token identifier flag that indicates an internal key-token)
1 3 Implementation-dependent bytes, must be X'000000'
4 1 Token version number (X'04')
5 1 Reserved, binary zero
6 1 Flag byte; for more information, see Table 86 on page 580
7 1 LRC
Longitudinal redundancy check checksum of clear-key value (LRC is the

exclusive-OR of each byte in the clear-key value).
8 8 MKVP
Contains the master-key verification pattern of the AES master-key used to encrypt
the key contained in the token, or binary zeros if the token does not contain a key
or the key is in the clear. The MKVP is calculated as the leftmost 8 bytes of the
SHA-256 hash of the string formed by pre-pending the byte X'01' to the cleartext
master-key value.
16 32 Key value, if present. Contains either:
v A 256-bit encrypted-key value.
The clear key value is padded on the right with binary zeros, and the entire
256-bit value is encrypted under the AES master-key using AES CBC mode with
an initialization vector of binary zeros.
v A 128-bit, 192-bit, or 256-bit clear-key value left-aligned and padded on the right
with binary zeros for the entire 256-bit field.
48 8 Control vector
This value must be binary zeros for all AES key tokens that have a control vector
present.
56 2 Clear-key bit length
Integer specifying the length in bits of the clear-key value. If no key is present in a
completed token, this length is zero. In a skeleton token, this is the length of the
key to be created in the token when used as input to the Key_Generate verb.
58 2 Encrypted-key byte length
Integer specifying the length in bytes of the encrypted-key value. This value is zero
if the token does not contain a key or the key is in the clear.
60 4 The token-validation value (TVV)
Appendix B. Data structures 579

Internal fixed-length AES key-token flag byte
Table 86. Internal fixed-length AES key-token flag byte
Bits (MSB...LSB)1 Description
1xxx xxxx Key is encrypted under the AES master-key (ignored if no key present).
0xxx xxxx Key is in the clear (ignored if no key present).
x1xx xxxx Control vector (CV) is present.
x0xx xxxx CV is not present.
xx1x xxxx No key and no MKVP present.
xx0x xxxx Encrypted or clear key present, MKVP present if key is encrypted.
Note: All undefined bits are reserved and must be 0.
Fixed-length DES key tokens

Fixed-length DES key-token data structures are 64 bytes in length, and are made up of a DES-enciphered
key, a control vector, various flag bits, a token identifier and version number, reserved fields, and
token-validation value. An internal key-token also includes a master-key verification pattern or master-key
version number, depending on the key-token version number.
If an internal fixed-length DES key-token has a key present, it contains a key multiply-enciphered by a
DES master key. If an external fixed-length DES key-token has a key present, it contains a key
multiply-enciphered by a key-encrypting key.
2. MSB is the most significant bit; LSB is the least significant bit.

Internal fixed-length DES key tokens
The CCA Support Program accepts and outputs a version X'00' internal fixed-length DES key-token. This
software also accepts the version X'03' internal fixed-length DES key-token.
Table 87. Internal fixed-length DES key-token format, version X'00' (version 2 and later software)
06 1 Flag byte 1. For more information, see Table 91 on page 583.
08 8 Master-key verification pattern
16 8 Single-length operational (master-key encrypted) key or the left half of a
double-length operational key
24 8 Null, or the right half of a double-length operational key
32 8 Control-vector base
40 8 Null, or the control vector base for the right half of a double-length key
60 4 Token-validation value
Table 88. Internal fixed-length DES key-token format, version X'03'

Note: Created and processed by Version 1 Software. Version 2 and later software only accepts as input.
02 2 Master-key version number
16 8 Single-length operational (master-key encrypted) key or the left half of a
double-length operational key
24 8 Null, or the right half of a double-length operational key
External fixed-length DES key tokens

CCA has defined more than one version of external fixed-length DES key tokens. CCA generally uses a
version X'00' external fixed-length DES key-token as shown in Table 89 on page 582. The CCA Support
Program also uses a version X'01' external DES key-token to hold a double-length DATA key that is
associated with a null control vector as shown in Table 90 on page 582. A version X'10' external key-token

is used exclusively by the Remote_Key_ExportRemote_Key_Export and DES key-storage verbs, and is
described as an RKX key-token. See Remote key-loading on page 178.
Table 89. External fixed-length DES key-token format, version X'00'
00 1 X'02' (a token identifier flag that indicates an external key-token)
06 1 Flag byte 1. For more information, see Table 91 on page 583
16 8 Single-length key or the left half of a double-length key
24 8 Null, or the right half of a double-length key
Table 90. External fixed-length DES key-token format, version X'01'

00 1 X'02' (a flag that indicates an external key-token)
06 1 Flag byte 1. For more information, see Table 91 on page 583
16 8 Left half of a double-length key
24 8 Right half of a double-length key
32 16 Null control vector, binary zero
59 1 Key length flag, double, X'10'

Fixed-length DES key-token flag bytes (internal and external)
Table 91 describes the settings for flag byte 1 of fixed-length DES key tokens.
Table 91. Internal and external fixed-length DES key-token flag byte 1
0xxx xxxx An encrypted key is not present.
1xxx xxxx The encrypted key value and, if an internal fixed-length DES key-token, the master-key verification pattern
(version 0) or master-key version number (version 3) are present.
x0xx xxxx The control vector value is not present.
x1xx xxxx The control vector value is present.
Note: All other bit combinations are reserved; undefined bits should be zero.
Table 92 describes the settings for flag byte 2 of fixed-length DES key tokens. Flag byte 2 was added in
Release 4.1.
Table 92. Internal and external fixed-length DES key-token flag byte 2 (Release 4.1 or later)
000x xxxx The encrypted key is wrapped using the legacy (WRAP-ECB) method.
001x xxxx The encrypted key is wrapped using the enhanced (WRAP-ENH) method.
Notes:
1. All other bit combinations are reserved; undefined bits should be zero.
2. Before Release 4.1, this byte is reserved, and should be binary zero.
External RKX DES key tokens

Table 93 on page 584 defines an external fixed-length DES key-token called an RKX key-token. An RKX
key-token is a special token used exclusively by the Remote_Key_Export (CSNDRKX) and DES
key-storage verbs (for example, DES_Key_Record_Write). No other verbs use or reference an RKX
key-token or key-token record. For additional information about the usage of RKX key tokens, see
Remote key-loading on page 178.
Note: Verbs other than CSNDRKX and the DES key-storage do not support RKX key tokens or RKX key
token records.
As can be seen in the table, RKX key tokens are 64 bytes in length, have a token identifier flag (X'02'), a
token version number (X'10'), and room for encrypted keys like normal fixed-length DES key tokens.
Unlike normal fixed-length DES key tokens, RKX key tokens do not have a control vector, flag bits, and a
token-validation value. In addition, RKX key tokens have a confounder value, a MAC value, and room for a
third encrypted key.

Table 93. External RKX DES key-token format, version X'10'
Offset Length Description
00 1 X'02' (a token identifier flag that indicates an external key-token)
07 1 Key length in bytes, including confounder
08 8 Confounder
16 8 Key left
24 8 Key middle (binary zero if not used)
32 8 Key right (binary zero if not used)
40 8 Rule ID
The trusted block rule identifier used to create this key token. A subsequent call to
Remote_Key_Export (CSNDRKX) can use this token with a trusted block rule that
references the rule ID that must have been used to create this token. The trusted
block rule can be compared with this rule ID for verification purposes.
The Rule ID is an 8-byte string of ASCII characters, left-aligned and padded on the
right with space characters. Acceptable characters are A...Z, a...z, 0...9, - (X'2D'),
and _ (X'5F'). All other characters are reserved for future use.
56 8 MAC value
ISO 16609 CBC-mode Triple-DES MAC, computed over the 56 bytes starting at
offset 0 and including the encrypted key value and the rule ID using the same MAC
key that is used to protect the trusted block itself.
This MAC value guarantees that the key and the rule ID cannot be modified without
detection, providing integrity and binding the rule ID to the key itself. This MAC
value must verify with the same trusted block used to create the key, thus binding
the key structure to that specific trusted block.
Notes:
v A fixed, randomly derived variant is exclusive-ORed with the MAC key before it is used to encipher the
generated or exported key and confounder.
v The MAC key is located within a trusted block (internal format) and can be recovered by decipherment
under a variant of the PKA master key.
v The trusted block is originally created in external form by the CSNDTBC verb and then converted to
internal form by the CSNDPKI verb prior to the CSNDRKX call.

PKA key tokens
PKA key tokens (which hold RSA, or beginning with Release 4.1, ECC keys) contain various items, some
of which are optional, and some of which can be present in different forms. The token is composed of
concatenated sections that must occur in the prescribed order.
As with other CCA key tokens, both internal and external forms are defined.
v An internal PKA key-token contains a private key that is protected by encrypting the private key
information using the CCA-node asymmetric master key, or by an object protection key (OPK) that is
| itself encrypted by the APKA or PKA asymmetric master key. The internal key-token also contains the
modulus and the public-key exponent. A master-key verification pattern is also included to enable
determination that the proper master key is available to process the protected private key.
Note: The format and content of an internal key-token is local to a specific node and product
implementation, and does not represent an interchange format.
v An external RSA key-token contains the modulus and the public-key exponent. Also, the external
key-token optionally contains the private key. If the private key is present, it is either in the clear or it
might be protected by encryption using a double-length DES transport key. An external key-token is an
inter-product interchange data structure.
An RSA private key can be represented in one of several forms:

v By a modulus and the private-key exponent
v By a set of numbers used in the Chinese-Remainder Theorem (CRT). The coprocessor always
generates a CRT key with p > q. If you import a CRT key from another RSA implementation with q > p
the key is usable within the coprocessor, but your application encounters a performance penalty with
each use of the key.
The RSA private key can be protected by encrypting a confounder (a random number) and the private key
information exclusive of the modulus. An encrypted RSA private key in an external key-token is protected
by a double-length DES transport key and the EDE2 algorithm. See RSA private-key encryption and
decryption process on page 671. The private key and the blinding values in an internal RSA key-token are
protected by the triple-length asymmetric (PKA) master key and encryption algorithms as specified with
each private key data structure.

PKA key token sections
A PKA key-token is the concatenation of an ordered set of sections. These key-token-section data
structures are described in the sections referenced in the following table:
Section Reference Usage

Header Table 94 on page 587 RSA key-token header.
X'02' Table 96 on page 588 RSA private key, 1024-bit Modulus-Exponent format.
Generated for external format for clear keys or for keys
encrypted by a key-encrypting key.
X'04' Table 101 on page 593 RSA public-key.
X'05' Table 97 on page 589 RSA private key, 2048-bit Chinese-Remainder Theorem
format. Internal and external format. Accepted only as an
input and not generated in Version 2 and later; replaced
by section X'08'.
X'06' Table 98 on page 590 RSA private key, 1024-bit Modulus-Exponent format with
OPK. Only used as a master-key encrypted, internal
format.
X'08' Table 100 on page 592 RSA private key, Chinese-Remainder Theorem format
with OPK. Internal and external format; replaces section
X'05'.
| X'09' Table 99 on page 591 RSA private key, 4096-bit Modulus-Exponent format.
| Generated for external format for clear keys or for keys
| encrypted by a key-encrypting key.
X'10' Table 102 on page 594 RSA private-key name.
X'20' Table 112 on page 597 ECC private key (Release 4.1 or later) internal and
external format with OPK.
X'21' Table 113 on page 599 ECC public-key certificate (Release 4.1 or later).
X'40' Table 103 on page 595 through RSA public-key certificates.
Table 109 on page 596
X'FF' Table 114 on page 600 RSA private-key blinding information.
Note: You cannot use a Modulus-Exponent format for RSA keys with a modulus (key size) greater than
1024 bits.
PKA key tokens can be built with the PKA_Key_Token_Build verb.
An RSA key-token is a concatenation of these sections:

v A token header:
An external header (first byte X'1E')
An internal header (first byte X'1F')
v An optional private-key section in one of these formats:
Section identifier X'02' for a clear or key-encrypting key enciphered, Modulus-Exponent format key
up to 1024 bits
Section identifier X'06' for a master-key enciphered, Modulus-Exponent format key up to 1024 bits
Section identifier X'08' for a CRT-format key up to 4096 bits
| Section identifier X'09' for a clear or key-encrypting key enciphered, for a Modulus-Exponent format
| key up to 4096 bits
Note: Keys with a modulus greater than 2048 bits are not supported in releases before Release 3.30.
Section identifier X'05' for a CRT-format key up to 1024 bits is accepted as input
v A public-key section (section identifier X'04')

v An optional private-key name section (section identifier X'10')
v For internal key-tokens with private keys in X'02' or X'05' sections, a private-key blinding section
(section identifier X'FF')
v An optional certificate section (section identifier X'40' with subsidiary sections)
An ECC key-token is a concatenation of these sections:

v A token header:
An external header (first byte X'1E')
An internal header (first byte X'1F')
v An optional private-key section (section identifier X'20')
v A public-key section (section identifier X'21')
RSA key-token integrity

If the RSA key-token contains private-key information, then the integrity of the information within the token
can be verified by computing and comparing the SHA-1 hash values that are found in the private-key
sections. The SHA-1 hash value at offset 4 within the private-key section requires access to the cleartext
values of the private-key components. The cryptographic engine verifies this hash quantity whenever it
retrieves the secret key for productive use.
A second SHA-1 hash value is located at offset 30 within the private-key section. This hash value is
computed on optional, designated key-token information following the public-key section. The value of this
SHA-1 hash is included in the computation of the hash value at offset 4. As with the offset 4 hash value,
the hash at offset 30 is validated whenever a private key is recovered from the token for productive use.
In addition to the hash checks, various token-format and content checks are performed to validate the key
values.
The optional private-key name section can be used by access-monitor systems (for example, RACF) to
ensure that the application program is entitled to employ the particular private key.
Number representation in PKA key tokens

v All length fields are in binary.
v All binary fields (exponents, lengths, and so forth) are stored with the high-order byte first (left,
low-address, z/OS format); thus the least significant bits are to the right and preceded with zero-bits to
the width of a field.
v In variable-length binary fields that have an associated field-length value, leading bytes that would
otherwise contain X'00' can be dropped and the field shortened to contain only the significant bits.
Table 94. PKA key-token header
000 001 Token identifier (a flag that indicates token type)
X'00' Null token
X'1E' External token; the optional private-key is either in cleartext or enciphered by a
transport key-encrypting key
X'1F' Internal token; the private key is enciphered by the master key
001 001 Token version number (X'00').
002 002 Length in bytes of the token structure (big endian).
Note: See Number representation in PKA key tokens.
Table 95. Null PKA key-token format

00 01 X'00' Indicates that this is a null key-token.

Table 95. Null PKA key-token format (continued)
01 01 X'00' Token version number.
02 02 X'0008' Length indicates a null PKA key-token.
Note: See Number representation in PKA key tokens on page 587.
Table 96. Private key, 1024-bit Modulus-Exponent format section (X'02')

000 001 Section identifier:
X'02' RSA private key, 1024-bit maximum Modulus-Exponent format (RSA-PRIV)
This section type is created by selected IBM Cryptographic Adapters and the IBM CCA Support
Program. Version 2 and later software uses this format for a clear or an encrypted RSA private
key in an external key token.
001 001 Section version number (X'00').
002 002 Section length in bytes (X'016C').
004 020 SHA-1 hash value of the private-key subsection cleartext, offset 28 to and including the
modulus that ends at offset 363.
026 002 Master-key verification pattern in an internal key-token, else X'0000'.
028 001 Key format and security flag:
X'00' Unencrypted RSA private-key subsection identifier
X'82' Encrypted RSA private-key subsection identifier
030 020 SHA-1 hash of the optional key-name section; if there is no name section, then 20 bytes of
X'00'.
| 050 001 Key-usage flag:
| B'11xx xxxx' Only key unwrapping (KM-ONLY)
| B'10xx xxxx' Both signature generation and key unwrapping (KEY-MGMT)
| B'01xx xxxx' Undefined
| B'00xx xxxx' Only signature generation (SIG-ONLY)
| All other bits are reserved and must be zero.

084 Start of the optionally encrypted subsection. Private key encryption:
v External token: EDE2 process using the double-length transport key
v Internal token: EDE3 process using the asymmetric master key
See Triple-DES ciphering algorithms on page 685.

084 024 Random number (confounder).
108 128 Private-key exponent, d. d = e-1mod((p - 1)(q - 1)), 1 < d < n, and where e is the public
exponent.
End of the optionally encrypted subsection. All of the fields starting with the confounder field and ending with the private-key
exponent are enciphered for key confidentiality when the key format and security flags (offset 28) indicate that the private key is
enciphered.
236 128 Modulus, n. n = pq, where p and q are prime and 2512 n < 21024.
See Number representation in PKA key tokens on page 587.

Table 97. RSA private key, 2048-bit Chinese-Remainder Theorem format section (X'05')
X'05' RSA private key, 2048-bit maximum CRT (RSA-OPT) format
This section type is only created by the IBM Version 1 CCA Support Program.
002 002 Section length in bytes (76 + ppp + qqq + rrr + sss + ttt + uuu + xxx + nnn).
004 020 SHA-1 hash value of the private-key subsection cleartext, offset 28 to the end of the
modulus.
024 002 Length in bytes of the optionally encrypted secure subsection, or X'0000' if the subsection is
not encrypted.
026 002 Master-key verification pattern in an internal key-token, else X'0000'.
X'40' Unencrypted RSA private-key subsection identifier, Chinese-Remainder Theorem
format
X'42' Encrypted RSA private-key subsection identifier, Chinese-Remainder Theorem
format
030 020 SHA-1 hash of the optional key-name section; if there is no name section, then 20 bytes of
X'00'.

052 Start of the optionally encrypted subsection.
Private key encryption:

v External token: EDE2 process using the double-length transport key
v Internal token: EDE3 process using the asymmetric master key.

052 008 Random number, confounder.
060 002 Length of prime number, p, in bytes: ppp.
062 002 Length of prime number, q, in bytes: qqq.
064 002 Length of dp, in bytes: rrr.
066 002 Length of dq, in bytes: sss.
068 002 Length of Ap, in bytes: ttt.
070 002 Length of Aq, in bytes: uuu.
072 002 Length of modulus, n, in bytes: nnn.
074 002 Length of padding field, in bytes: xxx.
076 ppp Prime number, p.
076+ppp qqq Prime number, q.
076+ppp+qqq rrr dp = d mod(p - 1).
076+ppp+qqq +rrr sss dq = d mod(q - 1).
076+ppp+qqq ttt Ap = qp-1 mod(n).
+rrr+sss
076+ppp+qqq uuu Aq = (n + 1 - Ap).
+rrr+sss+ttt
076+ppp+qqq xxx X'00' padding of length xxx bytes such that the length from the start of the random number
+rrr+sss+ttt +uuu above to the end of the padding field is a multiple of 8 bytes.

Table 97. RSA private key, 2048-bit Chinese-Remainder Theorem format section (X'05') (continued)
End of the optionally encrypted subsection; all of the fields starting with the confounder field and ending with the variable-length pad
field are enciphered for key confidentiality when the key-format-and-security flags (offset 28) indicate that the private key is
enciphered.
076+ppp+qqq nnn Modulus, n. n = pq, where p and q are prime and 2512 n < 22048.
+rrr+sss+ttt
+uuu+xxx
Table 98. RSA private key, 1024-bit Modulus-Exponent format with OPK section (X'06')
X'06' RSA private key, 1024-bit maximum Modulus-Exponent format (RSA-PRIV)
This section type is created by the IBM Version 2 and later CCA Support Program. This
section type provides compatibility and interchangeability with the CCF hardware in z/OS
processors.
002 002 Section length (X'0198').
004 020 SHA-1 hash value of the private-key subsection cleartext, offset 28 up to and including the
modulus that ends at offset 363.
X'02' Encrypted RSA private key with OPK
029 001 Private key source flag:
X'21' Imported from cleartext
X'22' Imported from ciphertext
X'23' Generated using regeneration data
X'24' Randomly generated
030 020 SHA-1 hash of all optional sections that follow the public-key section, if any, else 20 bytes
of X'00'.

060 048 Object Protection Key (OPK); six 8-byte values: confounder, three key values, and two
initialization vector values.
The asymmetric master key encrypts the OPK using the EDE3 algorithm. See Triple-DES
ciphering algorithms on page 685.
108 128 Private-key exponent, d. d = e-1mod((p-1)(q-1)), 1 < d < n, and where e is the public
exponent.
The OPK encrypts the private key exponent using the EDE5 algorithm. See Triple-DES
ciphering algorithms on page 685 and Figure 49 on page 688.
236 128 Modulus, n. n = pq, where p and q are prime and 2512 n < 21024.
364 016 Asymmetric-keys master-key verification pattern.
380 020 SHA-1 hash value of the subsection cleartext, offset 400 to the section end. This hash
value is checked after an enciphered private key is deciphered for use.

Table 98. RSA private key, 1024-bit Modulus-Exponent format with OPK section (X'06') (continued)
| Table 99. Private key, 4096-bit Modulus-Exponent format section (X'09')

| Offset (bytes) Length (bytes) Description
| 000 001 Section identifier:
| X'09' RSA private key, 4096-bit maximum Modulus-Exponent format (RSAMEVAR).
| This format is used for a clear or an encrypted RSA private-key in an external key-token up
| to a modulus size of 4096 bits. This section type is not created in releases before Release
| 4.1.
| 001 001 Section version number (X'00').
| 002 002 Section length (132 + ddd + nnn + xxx).
| 004 020 SHA-1 hash value of the private-key subsection cleartext, offset 28 to the end of the
| modulus.
| 024 002 Length in bytes of the optionally encrypted secure subsection, or X'0000' if the subsection
| is not encrypted.
| 026 002 Reserved (X'0000').
| 028 001 Key format and security flags:
| External token:
| X'00' Unencrypted RSA private-key subsection identifier
| X'82' Encrypted RSA private-key subsection identifier
| 029 001 Private key source flag:
| X'00' Generation method unknown
| 030 020 SHA-1 hash of all optional sections that follow the public-key section, if any, else 20 bytes
| of X'00'.

| 051 065 Reserved, binary zeros.
| 116 002 Private-key exponent field length, in bytes: ddd.
| 118 002 Private-key modulus field length, in bytes: nnn.
| 120 002 Length of padding field, in bytes: xxx.
| Padding of X'00' bytes for a length of xxx bytes such that the length from the start of the
| confounder at offset 124 to the end of the padding field is a multiple of 8 bytes.
| 122 002 Reserved, binary zeros.
| Start of the (optionally) encrypted subsection; all of the fields starting with the confounder field and ending with the variable-length
| pad field are enciphered for key confidentiality when the key format and security flags (offset 28) indicate that the private key is
| enciphered.
| 124 008 Confounder.
| This is an eight-byte random number.
| Data encrypted with two-part key-encrypting key.

| Table 99. Private key, 4096-bit Modulus-Exponent format section (X'09') (continued)
| 132 ddd Private-key exponent, d:
| d = e-1 mod((p - 1)(q - 1))
| where 1 < d < n, and e is the public exponent.
| The transport key encrypts the private key exponent using the EDE2 algorithm. See
| Triple-DES ciphering algorithms on page 685 and Figure 49 on page 688.
| 132 + ddd xxx Pad of X'00' bytes.
| End of the optionally encrypted subsection.
| 132 + ddd + xxx nnn Private-key modulus.
|
Table 100. RSA private key, Chinese-Remainder Theorem format with OPK section (X'08')
X'08' RSA private key, CRT format (RSA-CRT) with OPK
This section type is created by the IBM Version 2 and later CCA Support Program.
002 002 Section length (132+ppp+qqq+rrr+sss+uuu+xxx+nnn).
004 020 SHA-1 hash value of the private-key subsection cleartext, offset 28 to the end of the
modulus.
External token:
X'40' Unencrypted RSA private-key subsection identifier
Internal token:
029 001 Key source flag:
External tokens, reserved, binary zero.
Internal tokens:
X'21' Imported from cleartext
X'22' Imported from ciphertext
X'23' Generated using regeneration data
X'24' Randomly generated
030 020 SHA-1 hash of all optional sections that follow the public key section, if any; else 20 bytes
of X'00'.

054 002 Length of the prime number, p, in bytes: ppp.
056 002 Length of the prime number, q, in bytes: qqq.
058 002 Length of dp, in bytes: rrr.
060 002 Length of dq, in bytes: sss.
062 002 Length of the U value, in bytes: uuu.

Table 100. RSA private key, Chinese-Remainder Theorem format with OPK section (X'08') (continued)
064 002 Length of the modulus, n, in bytes: nnn.
070 002 Length of the pad field, in bytes: xxx.
076 016 External token, reserved, binary zero.
Internal token, asymmetric master-key verification pattern.

092 032 External token: reserved, binary zero.
Internal token: Object Protection Key (OPK), 8-byte confounder and three 8-byte keys used
in the Triple-DES CBC process to encrypt the private key and blinding information. These
32 bytes are Triple-DES CBC encrypted by the asymmetric master key. See TDES at
Triple-DES ciphering algorithms on page 685.
124 Start of the (optionally) encrypted subsection.
v External token:
When offset 028 is X'40', the subsection is not encrypted.
When offset 028 is X'42', the subsection is encrypted by the double-length transport
key using the Triple-DES CBC process.
v Internal token:
When offset 028 is X'08', the subsection is encrypted by the triple-length OPK using the
Triple-DES CBC process.

124 008 Random number, confounder.
132 ppp Prime number, p.
132+ppp qqq Prime number, q.
132+ppp +qqq rrr dp = d mod(p-1).
132+ppp +qqq+rrr sss dq = d mod(q-1).
132+ppp uuu U = q-1mod(p).
+qqq+rrr+sss
132+ppp xxx X'00' padding of length xxx bytes such that the length from the start of the confounder at
+qqq+rrr+sss +uuu offset 124 to the end of the padding field is a multiple of 8 bytes.
End of the optionally encrypted subsection; all of the fields starting with the confounder field and ending with the variable-length pad
field are enciphered for key confidentiality when the key-format-and-security flags (offset 28) indicate that the private key is
enciphered.
132+ppp nnn Modulus, n. n=pq, where p and q are prime and 2512 n < 24096
+qqq+rrr+sss
+uuu+xxx Keys with a modulus greater than 2048 bits are not supported in releases before Release
3.30.
Table 101. Public-key section (X'04') of RSA key token

X'04' RSA public-key
002 002 Section length (12+xxx+yyy).
006 002 RSA public-key exponent field length in bytes, xxx.
008 002 Public-key modulus length in bits.

Table 101. Public-key section (X'04') of RSA key token (continued)
010 002 RSA public-key modulus field length in bytes, yyy.
Note: If the token contains an RSA private-key section, this field length, yyy, should be 0.
The RSA private-key section contains the modulus.
012 xxx Public-key exponent, e (this field length is typically 1, 3, or 64 - 512 bytes). e must be odd
and 1 e < n. (e is frequently valued to 3 or 216 + 1 (=65537), otherwise e is of the same
order of magnitude as the modulus).
Note: A Rabin key, which is an RSA public key with its public exponent valued to two, can be
used to correctly validate an ISO/IEC 9796-1 digital signature. The current product
implementation can import such keys, but it cannot generate them.
012+xxx yyy Modulus, n. n=pq, where p and q are prime and 2512 n < 24096. This field is absent when the
modulus is contained in the private-key section. If present, the field length is 64 - 512 bytes.
Note: Keys with a modulus greater than 2048 bits are not supported in releases before
Release 3.30.
Table 102. Private-key name section (X'10') of RSA key token

X'10' RSA private-key name
002 002 Section length (X'0044').
004 064 Private-key name, left-aligned, padded on the right with space characters (X'20'). The
private-key name can be used by an access-control system to validate the calling
application's entitlement to employ the key. When generating a retained private key, the name
supplied in this part of the skeleton key-token is subsequently used in the coprocessor to
locate the retained key.
RSA public-key certificate section: An optional public-key certificate section can be included in an RSA
key-token. The section consists of:
v The section header (identifier X'40')
v A public-key subsection (identifier X'41')
v An optional certificate information subsection (identifier X'42') with any or all of these TLV objects:
User data (tag identifier X'50')
EID (tag identifier X'51')
Serial number (tag identifier X'52')
v One or more signature subsections (tag identifier X'45')
The section is composed of a series of subsections and tag-length-variable (TLV) objects to form a
self-defining data structure. One or more TLV objects can be included in the variable portion of a
higher-level TLV object.
The section header is described followed by descriptions of the subsections and TLV objects that can be
included in the section.

Table 103. Public-key certificate section (X'40') of RSA key token
X'40' RSA public-key certificate
002 002 Section length; includes:
v Section header
v Public key subsection
v Information subsection (optional)
v Signature subsections
Table 104. Public-key subsection (X'41') of RSA public-key certificate

000 001 Subsection identifier:
X'41' Public key
001 001 Subsection version number (X'00').
002 002 Subsection length (12 + xxx + yyy).
008 002 Public-key modulus length in bits.
012 xxx Public-key exponent, e (this field length is typically 1, 3, or 64 - 512 bytes). e must be odd,
and 1 e < n.
012+xxx yyy Modulus, n. n = pq, where p and q are prime and 2512 n < 24096. This field is absent when
the modulus is contained in the private-key section. If present, the field length is 64 - 512
bytes.
Release 3.30.
Table 105. Optional-information subsection (X'42') of RSA public-key certificate

X'42' Information
002 002 Subsection length (4+iii, where iii =
length of TLV object X'50' +

length of TLV object X'51' +
length of TLV object X'52').
004 iii The information field that contains any of the optional TLV objects:
Tag Description
X'50' User data
X'51' EID
X'52' Serial number

Table 106. User-data TLV object (X'50') of RSA public-key certificate
000 001 Tag identifier:
X'50' User data TLV object
001 001 TLV object version number (X'00').
002 002 TLV object length (4+uuu; 0uuu64).
004 uuu User-provided data.
Table 107. TLV object (X'51') of private-key environment identifier of RSA public-key certificate
X'51' Private key EID TLV object
002 002 TLV object length (X'0014').
004 016 EID string of the CCA node that generated the public and private key. This TLV must be
provided in a skeleton key-token with usage of the PKA_Key_Generate verb. The verb fills in
the EID string prior to certifying the public key. The EID value is encoded using the ASCII
character set.
Table 108. Serial-number TLV object (X'52') of RSA public-key certificate

X'52' Serial number TLV object
002 002 TLV object length (X'000C').
004 008 Serial number of the coprocessor that generated the public and private key. This TLV must be
provided in a skeleton key-token with usage of the PKA_Key_Generate verb. The verb fills in
the serial number prior to certifying the public key.
Table 109. Signature subsection (X'45') of RSA public-key certificate

X'45' Signature
002 002 Subsection length (70+sss).
004 001 Hash algorithm identifier:
X'01' SHA-1
005 001 Signature formatting identifier:
X'01' ISO/IEC 9796-1 process
006 064 Signature-key identifier; the key label of the key used to generate the signature.
070 sss The signature field:
The signature is calculated on data that begins with the signature section identifier (X'40')
through the byte immediately preceding this signature field.
Note: More than one signature subsection can be included in a signature section. This accommodates the possibility of a
self-signature as well as a device-key signature.

| CCA allows a choice between two types of elliptic curves when generating an ECC key. One is Brainpool,
| and the other is Prime. Table 110 and Table 111 show the size and name of each supported elliptic curve,
| along with its object identifier (OID) in dot notation.
| Table 110. Supported Prime elliptic curves by size, name, and object identifier
| SEC 2 recommended
| Size of prime p in bits ANS X9.62 ECDSA NIST-recommended elliptic curve domain
| (key length) OID in dot notation prime curve ID elliptic curve ID parameter
| 192 1.2.840.10045.3.1.1 prime192v1 P-192 secp192r1
| 224 1.3.132.0.33 N/A P-224 secp224r1
| 256 1.2.840.10045.3.1.7 prime256v1 P-256 secp256r1
| 384 1.3.132.0.34 N/A P-384 secp384r1
| 521 1.3.132.0.35 N/A P-521 secp521r1
|
| Table 111. Supported Brainpool elliptic curves by size, name, and object identifier
| Size of prime p in bits (key length) OID in dot notation Brainpool elliptic curve ID
| 160 1.3.36.3.3.2.8.1.1.1 brainpoolP160r1
| 192 1.3.36.3.3.2.8.1.1.3 brainpoolP192r1
| 224 1.3.36.3.3.2.8.1.1.5 brainpoolP224r1
| 256 1.3.36.3.3.2.8.1.1.7 brainpoolP256r1
| 320 1.3.36.3.3.2.8.1.1.9 brainpoolP320r1
| 384 1.3.36.3.3.2.8.1.1.11 brainpoolP384r1
| 512 1.3.36.3.3.2.8.1.1.13 brainpoolP512r1
|
| Table 112. ECC private-key section
| 000 001 Section identifier:
| X'20' ECC private key
| 001 001 Section version number (X'00').
| 002 002 Length of section in bytes.
| 004 001 Wrapping method:
| X'00' Section is unencrypted (clear)
| X'01' AESKW
| X'02' CBC
| 005 001 Hash method used for wrapping:
| X'00' None (clear key)
| X'01' SHA-224
| X'02' SHA-256
| 006 002 Reserved, binary zero.
| 008 001 Key-usage flag.
| Management of symmetric keys and generation of digital signatures:

| B'11xx xxxx' Only key establishment (KM-ONLY)
| B'10xx xxxx' Both signature generation and key establishment (KEY-MGMT)
| Translation control:
| B'xxxx xx1x' Private key translation is allowed (XLATE-OK)
| B'xxxx xx0x' Private key translation is not allowed (NO-XLATE)
| 009 001 Curve type:
| X'00' Prime
| X'01' Brainpool

| Table 112. ECC private-key section (continued)
| 010 001 Key format and security flag:
| X'08' Encrypted internal ECC private key
| X'40' Unencrypted external ECC private key
| X'42' Encrypted external ECC private key
| 011 001 Reserved, binary zero
| 012 002 Length of prime p in bits. See Table 110 on page 597 and Table 111 on page 597.
| X'00A0' 160 (Brainpool)
| X'00C0' 192 (Brainpool, Prime)
| X'00E0' 224 (Brainpool, Prime)
| X'0209' 521 (Prime)
| 014 002 Length in bytes of IBM associated data.
| 016 008 Key verification pattern.
| External key-token
| v For an encrypted private key, KEK verification pattern (KVP)
| v For a clear private key, binary zeros
| v For a skeleton, binary zeros
| Internal key-token
| v For encrypted private key, master-key verification pattern (MKVP)
| v For a skeleton, binary zeros
| 024 048 Object Protection Key (OPK).
| For an internal key token: OPK, integrity check value (ICV), 8-byte confounder, and a 256-bit
| AES key used with the AESKW algorithm to encrypt the ECC private key, otherwise binary
| zeros.
| Note: The OPK is encrypted by the APKA master key using AESKW.
| 072 002 Length in bytes of associated data.
| 074 002 Length in bytes of formatted section, bb.
| Start of IBM
| associated data
| 076 001 Associated data section version (X'00').
| Includes IBM associated data and user-definable associated data.

| 077 001 Length in bytes of the key label: kl (0 - 64).
| 078 002 Length in bytes of the IBM associated data, including key label and IBM extended associated
| data ( 16).
| 080 002 Length in bytes of the IBM extended associated data (0).
| 082 001 Length in bytes of the user-definable associated data: uad (0 - 100).
| 083 001 Curve type (see offset 009).
| 084 002 Length of p in bits (see offset 012).
| 086 001 Key-usage flag (see offset 008).
| 087 001 Key format and security flag (see 010).
| 092 kl Optional key label.
| 092 + kl iead Optional IBM extended associated data.
| End of IBM
| associated data
| 092 + kl + iead uad Optional user-definable associated data.

| Table 112. ECC private-key section (continued)
| End of associated data section
| 092 + kl + iead bb Formatted section (payload), which includes private key d:
| + uad v Clear-key section contains d.
| v Encrypted-key section contains d within the AESKW-wrapped payload.
| Note: See Number representation in PKA key tokens on page 587.
|
| Table 113. ECC public-key section
X'21' ECC public key
002 002 Section length.
008 001 Curve type:
X'00' Prime
X'01' Brainpool
010 002 Length of prime p in bits. See Table 110 on page 597 and Table 111 on page 597.
X'00A0' 160 (Brainpool)
X'00C0' 192 (Brainpool, Prime)
X'00E0' 224 (Brainpool, Prime)
X'0100' 256 (Brainpool, Prime)
X'0140' 320 (Brainpool)
X'0180' 384 (Brainpool, Prime)
X'0200' 512 (Brainpool)
X'0209' 521 (Prime)
012 002 Length of public key q in bytes. Value includes key material length plus a one-byte flag to
indicate if the key material is compressed.
014 cc Public key q.
RSA private-key blinding information:

Table 114. Blinding information of RSA private-key
X'FF' Private-key blinding information
Used with internal key-tokens created by the CCA Support Program, Version 1 (having
section identifiers X'02' or X'05').
002 002 Section length (34+rrr+iii).
004 020 SHA-1 hash value of the internal information subsection cleartext, offset 28 to the section end.
This hash value is checked after an enciphered private key is deciphered for use.
024 002 Length in bytes of the encrypted secure subsection.
028 Start of the encrypted secure subsection. An internal token with section identifiers X'02' or X'05' uses the
asymmetric master key and the EDE3 algorithm. See Triple-DES ciphering algorithms on page 685.
028 002 Length of the random number r, in bytes: rrr.
030 002 Length of the random number multiplicative inverse r-1, in bytes: iii.
032 002 Length of the padding field, in bytes xxx.
034 rrr Random number r (used in blinding).
034+rrr iii Random number r-1 (used in blinding).
034+rrr+iii xxx X'00' padding of length xxx bytes such that the length from the start of the encrypted
subsection to the end of the padding field is a multiple of 8 bytes.
End of the encrypted subsection.
Trusted blocks
A trusted block is an extension of CCA PKA key tokens using new section identifiers. Trusted blocks are
an integral part of a remote key-loading process. For more information on their usage, see Improved
remote key distribution on page 178.
Trusted blocks contain various items, some of which are optional, and some of which can be present in
different forms. Tokens are composed of concatenated sections that, unlike CCA PKA key tokens, occur in
no prescribed order.
As with other CCA key-tokens, both internal and external forms are defined:
v An external trusted block contains a randomly generated confounder and a triple-length MAC key
enciphered under a DES IMP-PKA transport key. The MAC key is used to calculate an ISO 16609
CBC-mode Triple-DES MAC of the trusted block contents. An external trusted block is created by the
Trusted_Block_Create verb. This verb can:
1. Create an inactive external trusted block
2. Change an external trusted block from inactive to active
v An internal trusted block contains a confounder and triple-length MAC key enciphered under a variant of
the PKA master key. The MAC key is used to calculate a TDES MAC of the trusted block contents. A
PKA master-key verification pattern is also included to enable determination that the proper master key
is available to process the key. The Remote_Key_Export verb only operates on trusted blocks that are
internal. An internal trusted block must be imported from an external trusted block that is active using
the PKA_Key_Import verb.
Note: Trusted blocks do not contain a private key section.

Trusted block sections
A trusted block is a concatenation of a header followed by an unordered set of sections. The data
structures of these sections are summarized in the following table:
Section Reference Usage

Header Table 115 on page 602 Trusted block token header
X'11' Table 116 on page 603 Trusted block public key
X'12' Table 117 on page 604 Trusted block rule
X'13' Table 124 on page 610 Trusted block name (key label)
X'14' Table 125 on page 611 Trusted block information
X'15' Table 129 on page 613 Trusted block application-defined data
Every trusted block starts with a token header. The first byte of the token header determines the key form:
v An external header (first byte X'1E'), created by the Trusted_Block_Create verb
v An internal header (first byte X'1F'), imported from an active external trusted block by the
PKA_Key_Import verb
Following the token header of a trusted block is an unordered set of sections. A trusted block is formed by
concatenating these sections to a trusted block header:
v An optional public-key section (trusted block section identifier X'11')
The trusted block trusted RSA public-key section includes the key itself in addition to a key-usage flag.
No multiple sections are allowed.
v An optional rule section (trusted block section identifier X'12')
A trusted block can have zero or more rule sections.
1. A trusted block with no rule sections can be used by the PKA_Key_Token_Change and
PKA_Key_Import verbs. A trusted block with no rule sections can also be used by the
Digital_Signature_Verify verb, provided there is an RSA public-key section that has its key-usage
flag bits set to allow digital signature operations.
2. At least one rule section is required when the Remote_Key_Export verb is used to:
Generate an RKX key-token
Export an RKX key-token
Export a CCA DES key-token
Encrypt the clear generated or exported key using the provided vendor certificate
3. If a trusted block has multiple rule sections, each rule section must have a unique 8-character Rule
ID.
v An optional name (key label) section (trusted block section identifier X'13')
The trusted block name section provides a 64-byte variable to identify the trusted block, just as key
labels are used to identify other CCA keys. This name, or label, enables a host access-control system
such as RACF to use the name to verify that the application has authority to use the trusted block. No
multiple sections are allowed.
v A required information section (trusted block section identifier X'14')
The trusted block information section contains control and security information related to the trusted
block. The information section is required while the others are optional. This section contains the
cryptographic information that guarantees its integrity and binds it to the local system. No multiple
sections are allowed.
v An optional application-defined data section (trusted block section identifier X'15')

The trusted block application-defined data section can be used to include application-defined data in the
trusted block. The purpose of the data in this section is defined by the application. CCA does not
examine or use this data in any way. No multiple sections are allowed.
Trusted block integrity

An enciphered confounder and triple-length MAC key contained within the required information section of
the trusted block is used to protect the integrity of the trusted block. The randomly generated MAC key is
used to calculate an ISO 16609 CBC-mode Triple-DES MAC of the trusted block contents. Together, the
MAC key and MAC value provide a way to verify that the trusted block originated from an authorized
source, and binds it to the local system.
An external trusted block has its MAC key enciphered under an IMP-PKA key-encrypting key. An internal
trusted block has its MAC key enciphered under a variant of the PKA master key, and the master-key
verification pattern is stored in the information section.
Number representation in trusted blocks

v All length fields are in binary.
v All binary fields (exponents, lengths, and so forth) are stored with the high-order byte first (left,
low-address, z/OS format); thus the least significant bits are to the right and preceded with zero-bits to
the width of a field.
v In variable-length binary fields that have an associated field-length value, leading bytes that would
otherwise contain X'00' can be dropped and the field shortened to contain only the significant bits.
Format of trusted block sections

At the beginning of every trusted block is a trusted block header. The header contains the following
information:
v A token identifier, which specifies if the token contains an external or internal key-token
v A token version number to allow for future changes
v A length in bytes of the trusted block, including the length of the header
The trusted block header is defined in the following table:
Table 115. Trusted block header
000 001 Token identifier (a flag that indicates token type)
X'1E' External trusted block token
X'1F' Internal trusted block token
002 002 Length of the key-token structure in bytes.
Note: See Number representation in trusted blocks.
Following the header, in no particular order, are trusted block sections. There are five different sections
defined, each identified by a one-byte section identifier (X'11' - X'15'). Two of the five sections have
subsections defined. A subsection is a tag-length-value (TLV) object, identified by a two-byte subsection
tag.
Only sections X'12' and X'14' have subsections defined; the other sections do not. A section and its
subsections, if any, are one contiguous unit of data. The subsections are concatenated to the related
section, but are otherwise in no particular order. Section X'12' has five subsections defined (X'0001' -
X'0005'), and section X'14' has two (X'0001' and X'0002'). Of all the subsections, only subsection X'0001'
of section X'14' is required. Section X'14' is also required.
The trusted block sections and subsections are described in detail in the following sections.

Trusted block section X'11'
Trusted block section X'11' contains the trusted RSA public key in addition to a key-usage flag indicating
whether the public key is usable in key-management operations, digital signature operations, or both.
Section X'11' is optional. No multiple sections are allowed. It has no subsections defined.
This section is defined in the following table:

Table 116. Trusted block trusted RSA public-key section (X'11')
X'11' Trusted block trusted RSA public key
002 002 Section length (16 + xxx + yyy).
004 002 Reserved, must be binary zero.
008 002 RSA public-key modulus length in bits.
012 xxx Public-key exponent, e (this field length is typically 1, 3, or 64 - 512 bytes). e must be odd
and 1 e < n. (e is frequently valued to 3 or 216 + 1 (=65537), otherwise e is of the same
order of magnitude as the modulus).
Note: A Rabin key, which is an RSA public key with its public exponent valued to two, can
be used to correctly validate an ISO/IEC 9796-1 digital signature. The current product
implementation can import such keys, but it cannot generate them.
012+xxx yyy RSA public-key modulus, n. n = pq, where p and q are prime and 2512 n < 24096. The field
length is 64 - 512 bytes.
Release 3.30.
012+xxx+yyy 004 Flags:
X'00000000' Trusted block public key can be used in digital signature operations only
X'80000000' Trusted block public key can be used in both digital signature and key
management operations
X'C0000000' Trusted block public key can be used in key management operations
only
Note: See Number representation in trusted blocks on page 602.
Trusted block section X'12' contains information that defines a rule. A trusted block can have zero or more
rule sections.
1. A trusted block with no rule sections can be used by the PKA_Key_Token_Change and
PKA_Key_Import verbs. A trusted block with no rule sections can be used by the
Digital_Signature_Verify verb, provided there is an RSA public-key section that has its key-usage flag
set to allow digital signature operations.
2. At least one rule section is required when the Remote_Key_Export verb is used to:
v Generate an RKX key-token
v Export an RKX key-token
v Export a CCA DES key-token
v Generate or export a key encrypted by a public key. The public key is contained in a vendor
certificate and is the root certification key for the ATM vendor. It is used to verify the digital signature
on public-key certificates for specific individual ATMs.
3. If a trusted block has multiple rule sections, each rule section must have a unique 8-character Rule ID.

Section X'12' is the only section allowed to have multiple sections. Section X'12' is optional. Multiple
sections are allowed.
Note: The overall length of the trusted block cannot exceed its maximum size of 3500 bytes.
Five subsections (TLV objects) are defined.
This section is defined in the following table:

Table 117. Trusted block rule section (X'12')
X'12' Trusted block rule
002 002 Section length in bytes (20+yyy).
004 008 Rule ID (in ASCII).
An 8-byte character string that uniquely identifies the rule within the trusted block.
Valid ASCII characters are: A...Z, a...z, 0...9, - (hyphen), and _ (underscore), left-aligned and
padded on the right with space characters.
012 004 Flags (undefined flag bits are reserved and must be zero).
B'00000000' Generate new key
B'00000001' Export existing key
016 001 Generated key length.
Length in bytes of key to be generated when flags value (offset 012) is set to generate a
new key; otherwise ignore this value. Valid values are 8, 16, or 24; return an error if not
valid.
017 001 Key-check algorithm identifier (all others are reserved and must not be used):
Value Meaning
X'00' Do not compute key-check value. Set the key_check_value_length variable to
zero.
X'01' Encrypt an 8-byte block of binary zeros with the key. See Encrypt zeros DES-key
verification algorithm on page 679.
X'02' Compute the MDC-2 hash of the key. See Modification Detection Code
calculation on page 679.
018 001 Symmetric encrypted output key format flag (all other values are reserved and must not be
used).
Return the indicated symmetric key-token using the sym_encrypted_key_identifier

parameter.
Value Meaning
X'00' Return an RKX key-token encrypted under a variant of the MAC key.
Note: This key format is permitted when the flags value (offset 012) is set to
either:
1. Generate a new key
2. Export an existing key
X'01' Return a CCA DES key-token encrypted under a transport key.
Note: This key format is not permitted if the flags value (offset 012) is set to
generate a new key; it is only permitted when exporting an existing key.
019 001 Asymmetric encrypted output key format flag (all other values are reserved and must not be
used).
Return the indicated asymmetric key-token in the asym_encrypted_key variable.

Value Meaning
X'00' Do not return an asymmetric key. Set the asym_encrypted_key_length variable to
zero.
X'01' Output in PKCS-1.2 format.
X'02' Output in RSA-OAEP format (RSA PKCS #1 v2.0).
020 yyy Rule section subsections (tag-length-value objects). A series of 0 - 5 objects in TLV format.

Table 117. Trusted block rule section (X'12') (continued)
Trusted block section X'12' subsections
Section X'12' has five rule subsections (tag-length-value objects) defined. These subsections are
summarized in the following table:
Table 118. Summary of trusted block rule subsection
Rule
subsection
tag TLV object Optional or required Comments
X'0001' Transport key Optional Contains variant to be exclusive-ORed into the cleartext transport
variant key.
X'0002' Transport key Optional; required to use Contains the rule ID for the rule that must have been used to create
rule reference an RKX key-token as a the transport key.
transport key
X'0003' Common Optional for key Contains the export key and source key minimum and maximum
export key generation; required for lengths, an output key variant length and variant, a CV length, and a
parameters key export of an existing CV to be exclusive-ORed with the cleartext transport key to control
key usage of the key.
X'0004' Source key Optional; required if the Contains the rule ID for the rule used to create the source key.
reference source key is an RKX Note: Include all rules that will ever be needed when a trusted block
key-token is created. A rule cannot be added to a trusted block after it has been
created.
X'0005' Export key Optional; used for export Contains mask length, mask, and CV template to limit the usage of
CCA token of CCA DES key tokens the exported key. Also contains the template length and template that
parameters only defines which source key labels are allowed.
The key type of a source key input parameter can be "filtered" by

using the export key CV limit mask (offset 005) and limit template
(offset 005+yyy) in this subsection.
Trusted block section X'12' subsection X'0001'
Subsection X'0001' of the trusted block rule section (X'12') is the transport key variant TLV object. This
subsection is optional. It contains a variant to be exclusive-ORed into the cleartext transport key.
This subsection is defined in the following table:

Table 119. Transport key variant subsection (X'0001') of trusted block rule section (X'12')
000 002 Subsection tag:
X'0001' Transport key variant TLV object
002 002 Subsection length in bytes (8+nnn).
007 001 Length of variant field in bytes (nnn).
This length must be greater than or equal to the length of the transport key that is identified by
the transport_key_identifier parameter. If the variant is longer than the key, truncate it on the
right to the length of the key prior to use.
008 nnn Transport key variant.
Exclusive-OR this variant into the cleartext transport key, provided: (1) the length of the variant
field value (offset 007) is not zero, and (2) the symmetric encrypted output key format flag
(offset 018 in section X'12') is X'01'.
Note: A transport key is not used when the symmetric encrypted output key is in RKX
key-token format.

Subsection X'0002' of the trusted block rule section (X'12') is the transport key rule reference TLV object.
This subsection is optional. It contains the rule ID for the rule that must have been used to create the
transport key. This subsection must be present to use an RKX key-token as a transport key.

Table 120. Transport key rule reference subsection (X'0002') of trusted block rule section (X'12')
X'0002' Transport key rule reference TLV object
002 002 Subsection length in bytes (14).
006 008 Rule ID.
Contains the rule identifier for the rule that must have been used to create the RKX key-token
used as the transport key.
The Rule ID is an 8-byte string of ASCII characters, left-aligned and padded on the right with
space characters. Acceptable characters are A...Z, a...z, 0...9, - (X'2D'), and _ (X'5F'). All other
characters are reserved for future use.
Subsection X'0003' of the trusted block rule section X'12') is the common export key parameters TLV
object. This subsection is optional, but is required for the key export of an existing source key (identified
by the source_key_identifier parameter) in either RKX key-token format or CCA DES key-token format. For
new key generation, this subsection applies the output key variant to the cleartext generated key, if such
an option is desired. It contains the input source key and output export key minimum and maximum
lengths, an output key variant length and variant, a CV length, and a CV to be exclusive-ORed with the
cleartext transport key.

Table 121. Common export key parameters subsection (X'0003') of trusted block rule section (X'12')
X'0003' Common export key parameters TLV object
002 002 Subsection length in bytes (12+xxx+yyy).
007 001 Flags (must be set to binary zero).
008 001 Export key minimum length in bytes. Length must be 0, 8, 16, or 24.
Also applies to the source key. Not applicable for key generation.
009 001 Export key maximum length in bytes (yyy). Length must be 0, 8, 16, or 24.
Also applies to the source key. Not applicable for key generation.

Table 121. Common export key parameters subsection (X'0003') of trusted block rule section (X'12') (continued)
010 001 Output key variant length in bytes (xxx).
Valid values are 0 or 8 - 255. If greater than 0, the length must be at least as long as the
longest key ever to be exported using this rule. If the variant is longer than the key, truncate it
on the right to the length of the key prior to use.
Note: The output key variant (offset 011) is not used if this length is zero.
011 xxx Output key variant.
The variant can be any value. Exclusive-OR this variant into the cleartext value of the output
key.
011+xxx 001 CV length in bytes (yyy).
v If the length is not 0, 8, or 16, return an error.
v If the length is 0, and if the source key is a CCA DES key-token, preserve the CV in the
symmetric encrypted output if the output is to be in the form of a CCA DES key-token.
v If a nonzero length is less than the length of the key identified by the source_key_identifier
parameter, return an error.
v If the length is 16, and if the CV (offset 012 + xxx) is valued to 16 bytes of X'00' (ignoring
the key-part bit), then:
1. Ignore all CV bit definitions
2. If CCA DES key-token format, set the flag byte of the symmetric encrypted output key to
indicate a CV value is present (see Fixed-length DES key-token flag bytes (internal and
external) on page 583)
3. If the source key is 8 bytes in length, do not replicate the key to 16 bytes
012+xxx yyy CV. (See Appendix C, CCA control-vector definitions and key encryption, on page 655.)
Place this CV into the output exported key-token, provided that the symmetric encrypted
output key format selected (offset 018 in rule section) is CCA DES key-token.
v If the symmetric encrypted output key format flag (offset 018 in section X'12') indicates
return an RKX key-token (X'00'), then ignore this CV. Otherwise, exclusive-OR this CV into
the cleartext transport key.
v Exclusive-OR the CV of the source key into the cleartext transport key if the CV length
(offset 011 + xxx) is set to 0. If a transport key to encrypt a source key has equal left and
right key halves, return an error. Replicate the key halves of the key identified by the
source_key_identifier parameter whenever all of these conditions are met:
1. The Replicate Key command (offset X'00DB') is enabled in the active role
2. The CV length (offset 011 + xxx) is 16, and both CV halves are nonzero
3. The source_key_identifier parameter (contained in either a CCA DES key-token or RKX
key-token) identifies an 8-byte key
4. The key-form bits (40 - 42) of this CV do not indicate a single-length key (are not set to
zero)
5. Key-form bit 40 of this CV does not indicate the key is to have guaranteed unique
halves (is not set to B'1'; see Key-form bits, 'fff' and 'FFF' on page 660).
Note: A transport key is not used when the symmetric encrypted output key is in RKX
key-token format.
Subsection X'0004' of the trusted block rule section (X'12') is the source key rule reference TLV object.
This subsection is optional, but is required if using an RKX key-token as a source key (identified by
source_key_identifier parameter). It contains the rule ID for the rule used to create the export key. If this
subsection is not present, an RKX key-token format source key will not be accepted for use.

Table 122. Source key rule reference subsection (X'0004') of trusted block rule section (X'12')
X'0004' Source key rule reference TLV object
006 008 Rule ID.
Rule identifier for the rule that must have been used to create the source key.
The Rule ID is an 8-byte string of ASCII characters, left-aligned and padded on the right with
space characters. Acceptable characters are A...Z, a...z, 0...9, - (X'2D'), and _ (X'5F'). All other
characters are reserved for future use.
Subsection X'0005' of the trusted block rule section (X'12') is the export key CCA token parameters TLV
object. This subsection is optional. It contains a mask length, mask, and template for the export key CV
limit. It also contains the template length and template for the source key label. When using a CCA DES
key-token as a source key input parameter, its key type can be "filtered" by using the export key CV limit
mask (offset 005) and limit template (offset 005+yyy) in this subsection.

Table 123. Export key CCA token parameters subsection (X'0005') of trusted block rule section (X'12')
X'0005' Export key CCA token parameters TLV object
002 002 Subsection length in bytes (8+yyy+yyy+zzz).
007 001 Flags (must be set to binary zero).
008 001 Export key CV limit mask length in bytes (yyy).
Do not use CV limits if this CV limit mask length (yyy ) is zero. Use CV limits if yyy is
nonzero, in which case yyy:
v Must be 8 or 16
v Must not be less than the export key minimum length (offset 008 in subsection X'0003')
v Must be equal in length to the actual source key length of the key
Example: An export key minimum length of 16 and an export key CV limit mask length of 8
returns an error.
009 yyy Export key CV limit mask (does not exist if yyy=0).
See Figure 37 on page 658
Indicates which CV bits to check against the source key CV limit template (offset 009+yyy).
Examples: A mask of X'FF' means check all bits in a byte. A mask of X'FE' ignores the
parity bit in a byte.

Table 123. Export key CCA token parameters subsection (X'0005') of trusted block rule section (X'12') (continued)
009+yyy yyy Export key CV limit template (does not exist if yyy=0).
Specifies the required values for those CV bits that are checked based on the export key
CV limit mask (offset 009). (See Figure 37 on page 658.)
The export key CV limit mask and template have the same length, yyy. This is because
these two variables work together to restrict the acceptable CVs for CCA DES key tokens to
be exported. The checks work as follows:
1. If the length of the key to be exported is less than yyy, return an error
2. Logical AND the CV for the key to be exported with the export key CV limit mask
3. Compare the result to the export key CV limit template
4. Return an error if the comparison is not equal
Examples: An export key CV limit mask of X'FF' for CV byte 1 (key type) along with an
export key CV limit template of X'3F' (key type CVARENC) for byte 1 filters out all key types
except CVARENC keys.
Note: Using the mask and template to permit multiple key types is possible, but cannot
consistently be achieved with one rule section. For example, setting bit 10 to 1 in the mask
and the template permits PIN processing keys and cryptographic variable encrypting keys,
and only those keys. However, a mask to permit PIN-processing keys and key-encrypting
keys, and only those keys, is not possible. In this case, multiple rule sections are required,
one to permit PIN-processing keys and the other to permit key-encrypting keys.
009+yyy+yyy 001 Source key label template length in bytes (zzz).
Valid values are 0 and 64. Return an error if the length is 64 and a source key label is not
provided.
010+yyy+yyy zzz Source key label template (does not exist if zzz = 0).
If a key label is identified by the source_key_identifier parameter, verify that the key label
name matches this template. If the comparison fails, return an error. The source key label
template must conform to the following rules:
v The key label template must be 64 bytes in length
v The first character cannot be in the range X'00' - X'1F', nor can it be X'FF'
v The first character cannot be numeric (X'30' - X'39')
v A key label name is terminated by a space character (X'20') on the right and must be
padded on the right with space characters
v The only special characters permitted are #, $, @, and * (X'23', X'24', X'40', and X'2A')
v The wildcard X'2A' (*) is only permitted as the first character, the last character, or the
only character in the template
v Only alphanumeric characters (a...z, A...Z, 0...9), the four special characters (X'23', X'24',
X'40', and X'2A'), and the space character (X'20') are allowed
Trusted block section X'13' contains the name (key label). The trusted block name section provides a
64-byte variable to identify the trusted block, just as key labels are used to identify other CCA keys. This
name, or label, enables a host access-control system such as RACF to use the name to verify that the
application has authority to use the trusted block.
Section X'13' is optional. No multiple sections are allowed. It has no subsections defined. This section is
defined in the following table:
Table 124. Trusted block key label (name) section (X'13')
X'13' Trusted block name (key label)

Table 124. Trusted block key label (name) section (X'13') (continued)
002 002 Section length in bytes (68).
004 064 Name (key label).
Trusted block section X'14' contains control and security information related to the trusted block. This
information section is separate from the public key and other sections because this section is required
while the others are optional. This section contains the cryptographic information that guarantees its
integrity and binds it to the local system.
Section X'14' is required. No multiple sections are allowed. Two subsections are defined. This section is
Table 125. Trusted block information section (X'14')
X'14' Trusted block information
002 002 Section length in bytes (10+xxx).
006 004 Flags:
B'00000000' Trusted block is in the inactive state
B'00000001' Trusted block is in the active state
010 xxx Information section subsections (tag-length-value objects).
One or two objects in TLV format.

Trusted block section X'14' subsections
Section X'14' has two information subsections (tag-length-value objects) defined. These subsections are
summarized in the following table:
Table 126. Summary of trusted block information subsections
Rule Optional or
subsection tag TLV object required Comments
X'0001' Protection Required Contains the encrypted 8-byte confounder and triple-length (24-byte) MAC
information key, the ISO 16609 CBC-mode Triple-DES MAC value, and the MKVP of the
PKA master key (computed using MDC4).
X'0002' Activation and Optional Contains flags indicating whether or not the coprocessor is to validate dates,
expiration dates and contains the activation and expiration dates that are considered valid for
the trusted block.
Subsection X'0001' of the trusted block information section (X'14') is the protection information TLV object.
This subsection is required. It contains the encrypted 8-byte confounder and triple-length (24-byte) MAC
key, the ISO 16609 CBC-mode Triple-DES MAC value, and the MKVP of the PKA master key (computed
using MDC4).

Table 127. Protection information subsection (X'0001') of trusted block information section (X'14')
X'0001' Trusted block information TLV object
004 001 Subsection version number (X'00'.
006 032 Encrypted MAC key.
Contains the encrypted 8-byte confounder and triple-length (24-byte) MAC key in the following
format:
Offset Description
00 - 07 Confounder
08 - 15 Left key
16 - 23 Middle key
24 - 31 Right key
038 008 MAC.
Contains the ISO 16609 CBC-mode Triple-DES MAC value.

046 016 MKVP.
Contains the PKA master-key verification pattern, computed using MDC4, when the trusted
block is in internal form, otherwise contains binary zero.
Subsection X'0002' of the trusted block information section (X'14') is the activation and expiration dates
TLV object. This subsection is optional. It contains flags indicating whether or not the coprocessor is to
validate dates, and contains the activation and expiration dates that are considered valid for the trusted
block.

Table 128. Activation and expiration dates subsection (X'0002') of trusted block information section (X'14')
X'0002' Activation and expiration dates TLV object
006 002 Flags:
X'0000' The coprocessor does not check dates.
X'0001' The coprocessor checks dates.
Compare the activation date (offset 008) and the expiration date (offset 012) to the
coprocessor's internal real-time clock. Return an error if the coprocessor date is
before the activation date or after the expiration date.
008 004 Activation date.
Contains the first date that the trusted block can be used for generating or exporting keys.
Format of the date is YYMD, where:
YY Big-endian year (return an error if greater than 9999)
M Month (return an error if any value other than X'01' - X'0C')
D Day of month (return an error if any value other than X'01' - X'1F'; day must be valid
for given month and year, including leap years)
Return an error if the activation date is after the expiration date or is not valid.
012 004 Expiration date.
Contains the last date that the trusted block can be used. Same format as activation date
(offset 008). Return an error if date is not valid.
Trusted block section X'15' contains application-defined data. The trusted block application-defined data
section can be used to include application-defined data in the trusted block. The purpose of the data in
this section is defined by the application; it is neither examined nor used by CCA in any way.
Section X'15' is optional. No multiple sections are allowed. It has no subsections defined. This section is
Table 129. Trusted block application-defined data section (X'15')
X'15' Application-defined data
002 002 Section length (6+xxx)
004 002 Application data length
The value of xxx can be between 0 - N, where N does not cause the overall length of the
trusted block to exceed its maximum size of 3500 bytes.
006 xxx Application-defined data
Might be used to hold a public-key certificate for the trusted public key.

Variable-length symmetric key-token
| Beginning with Release 4.1, CCA supports a variable-length symmetric key-token. This key token has a
| version number of X'05' (offset 4). Use the Key_Token_Build2 (CSNBKTB2) verb to build skeleton
| variable-length symmetric key tokens used as input by the Key_Generate2 (CSNBKGN2) or
| Key_Part_Import2 (CSNBKPI2) verbs, which return these key tokens with encrypted keys in the key-token
| payload.
| Table 131 on page 617 shows the format of the CIPHER variable-length symmetric key-token that,
| beginning with Release 4.2, can be used with the AES algorithm. An AES CIPHER key-token is used by
| the Symmetric_Algorithm_Decipher (CSNBSAD) and Symmetric_Algorithm_Encipher (CSNBSAE) verbs to
| decipher or encipher data with the AES algorithm.
| Table 132 on page 620 shows the format of the MAC variable-length symmetric key-token that, beginning
| with Release 4.1, can be used with the HMAC algorithm. An HMAC MAC key-token is used by the
| HMAC_Generate (CSNBHMG) and HMAC_Verify (CSNBHMV) verbs to generate or verify keyed hash
| message authentication codes.
| Table 133 on page 623 shows the format of the EXPORTER and IMPORTER variable-length symmetric
| key tokens that can be used with the AES algorithm. An EXPORTER operational key-token is used by the
| Symmetric_Key_Export (CSNDSYX) verb to export an internal AES or HMAC variable-length symmetric
| key-token into an external variable-length symmetric key-token, either into an AESKW or PKOAEP2
| wrapped payload. An IMPORTER operational key-token is used by the Symmetric_Key_Import2
| (CSNDSYI2) verb to import an external AES or HMAC variable-length symmetric key-token, containing
| either an AESKW or PKOAEP2 wrapped payload, into an internal variable-length symmetric key-token.
The general format of the token version number X'05' key token is shown in Table 130.
Table 130. Variable-length symmetric key-token, version X'05' general format (Release 4.1 or later)
Length
Offset (bytes) (bytes) Description
Header
000 01 Token identifier:
X'00' Null key-token
X'01' Internal key-token
X'02' External key-token
All other values are reserved and undefined.

002 02 Length in bytes of the overall token structure. For a null token the value is 8,
otherwise:
46 + (2 * kuf) + (2 * kmf) + kl + iead + uad + TLV lengths + ((pl + 7) / 8)

End of header
Wrapping information section (all data related to wrapping the token)
008 01 Key material state:
X'00' No key present (internal or external)
X'01' Key is clear (internal)
X'02' Key is encrypted under a KEK (external)
X'03' Key is encrypted under the master key (internal)

Table 130. Variable-length symmetric key-token, version X'05' general format (Release 4.1 or later) (continued)
Length
009 01 Key verification pattern (KVP) type:
X'00' No KVP
X'01' AESMK (8 leftmost bytes of SHA-256 hash (X'01' || clear AES MK))
| X'02' KEK (8 leftmost bytes of SHA-256 hash (X'01' || clear KEK))

| 010 16 KVP.
| Value is left-aligned in the field and padded on the right with binary zeros.
| Note: For key-wrapping method X'03' (PKOAEP2), this value is filled with binary
| zeros.
026 01 Encrypted section key-wrapping method:
X'00' Clear key
X'01' CBC enhanced (not used in this token)
| X'02' AESKW (internal tokens and external keys with AES KEK)
| X'03' PKOAEP2 (for external tokens only)

027 01 Hash algorithm used for wrapping.
For clear key wrapping method (X'00' at offset 26):

X'00' Clear key (no hash)
For AESKW wrapping method (X'02' at offset 26):

X'01' SHA-224 (not used)
X'02' SHA-256
X'04' SHA-384 (reserved for future use)
X'08' SHA-512 (reserved for future use)
For PKOAEP2 wrapping method (X'03' at offset 26):

X'01' SHA-1
X'02' SHA-256
X'04' SHA-384
X'08' SHA-512

End of wrapping information section
AESKW components: (1) associated data and (2) optional clear key or encrypted AESKW payload
Associated data section
030 01 Associated data section version (X'01').
032 02 Length in bytes of the associated data (16 - 1610).
034 01 Length in bytes of the key label: kl (0 - 64).
035 01 Length in bytes of the IBM extended associated data: iead (0 - 255).
036 01 Length in bytes of the user-definable associated data: uad (0 - 255).
038 02 Length in bits of the encrypted or clear payload: pl.

Length
041 01 Type of algorithm for which the key can be used.
| X'02' AES (Rel. 4.2 or later)
X'03' HMAC

042 02 Key type:
| X'0001' CIPHER (Rel. 4.2 or later)
X'0002' MAC
| X'0003' EXPORTER (Rel. 4.2 or later)
| X'0004' IMPORTER (Rel. 4.2 or later)

044 01 Key-usage fields count: kuf (0 - 255).
02 Optional key-usage field 1.
02 Optional key-usage field 2.
.
.
.
02 Optional key-usage field kuf.

045 + (2 * kuf) 01 Key-management fields count: kmf (0 - 255).
02 Optional key-management field 1.
02 Optional key-management field 2.
.
.
.
02 Optional key-management field kmf.

046 + (2 * kuf) + kl Optional key label.
(2 * kmf)
046 + (2 * kuf) + iead IBM extended associated data.
(2 * kmf) + kl
046 + (2 * kuf) + uad User-definable associated data.
(2 * kmf) + kl +
iead
046 + (2 * kuf) + 01 Optional tag-length-value (TLV) tag 1.
(2 * kmf) + kl +
iead + uad
02 Optional TLV length 1: tlv1.
tlv1 - 3 Optional TLV value 1
01 Optional TLV tag 2
02 Optional TLV length 2: tlv2
tlv2 - 3 Optional TLV value 2.
.
.
.
01 Optional TLV tag n.

01 Optional TLV length n: tlvn.

Length
tlvn - 3 Optional TLV value n.
End of associated data section
Optional clear key or encrypted AESKW payload
046 + (2 * kuf) + (pl + 7) / Clear key or encrypted wrapped/encoded payload.
(2 * kmf) + kl + 8
iead + uad + TLV
lengths
End of optional clear key or encrypted AESKW payload
End of AESKW components
Note: All numbers are in big endian format.
| Table 131 shows the format of the CIPHER variable-length symmetric key-token that, beginning with
| Release 4.2, can be used with the AES algorithm. An AES CIPHER key-token is used by the
| Symmetric_Algorithm_Decipher (CSNBSAD) and Symmetric_Algorithm_Encipher (CSNBSAE) verbs to
| decipher or encipher data with the AES algorithm.
| Table 131. Variable-length symmetric key-token, key type CIPHER (Release 4.2 or later)
| Length
| Offset (bytes) (bytes) Description
| Header
| 000 01 Token identifier:
| X'01' Internal key-token
| X'02' External key-token
| All other values are reserved and undefined.

| 002 02 Length in bytes of the overall token structure:
| 56 + kl + iead + uad + ((pl + 7) / 8)

| 004 01 Token version number (X'05').
| End of header
| Wrapping information section (all data related to wrapping the token)
| 008 01 Key material state:
| X'00' No key present (internal or external)
| X'01' Key is clear (internal)
| X'02' Key is encrypted under a KEK (external)
| X'03' Key is encrypted under the master key (internal)
| All other values are reserved and undefined or not used.

| 009 01 Key verification pattern (KVP) type:
| X'00' No KVP
| X'01' AESMK (8 leftmost bytes of SHA-256 hash (X'01' || clear AES MK))
| X'02' KEK (8 leftmost bytes of SHA-256 hash (X'01' || clear KEK))
| Note: Key-wrapping method X'03' (PKOAEP2) has no KVP.

| Table 131. Variable-length symmetric key-token, key type CIPHER (Release 4.2 or later) (continued)
| Length
| 010 16 KVP.
| zeros.
| 026 01 Encrypted section key-wrapping method:

| 027 01 Hash algorithm used.
| For key-wrapping method X'02' (AESKW):

| X'02' SHA-256
| For key-wrapping method X'03' (PKOAEP2):

| X'01' SHA-1
| X'02' SHA-256
| X'04' SHA-384
| X'08' SHA-512

| End of wrapping information section
| Components: (1) associated data and (2) encrypted wrapped/encoded payload
| 032 02 Length in bytes of the associated data (26 + kl + iead + uad).
| 035 01 Length in bytes of the IBM extended associated data: iead (0 - 255).
| 038 02 Length in bits of the encrypted payload: pl.
| 041 01 Type of algorithm for which the key can be used:
| X'02' AES
| 042 02 Key type:
| X'0001' CIPHER
| 044 01 Key-usage fields count: 2. Each key-usage field is two bytes in length.

| Table 131. Variable-length symmetric key-token, key type CIPHER (Release 4.2 or later) (continued)
| Length
| 045 02 Key-usage field 1.
| High-order byte:
| B'1xxx xxxx' Key can be used for encryption.
| B'0xxx xxxx' Key cannot be used for encryption.
| B'x1xx xxxx' Key can be used for decryption.
| B'x0xx xxxx' Key cannot be used for decryption.
| All unused bits are reserved and must be zero.
| Low-order byte. See Table 134 on page 627.

| High-order byte:
| X'00' Key can be used for Cipher Block Chaining (CBC).
| X'01' Key can be used for Electronic Code Book (ECB).
| X'02' Key can be used for Cipher Feedback (CFB).
| X'03' Key can be used for Output Feedback (OFB).
| X'04' Key can be used for Galois/Counter Mode (GCM).
| X'05' Key can be used for Xor-Encrypt-Xor-based Tweaked Stealing (XTS).
| Low-order byte:
| B'xxxx xxxx' Reserved
| All bits are reserved and must be zero.

| 049 01 Key management fields count: 3. Each key-management field is two bytes in length.
| 050 02 Key-management field 1.



| 056 + kl iead IBM extended associated data.
| 056 + kl + iead uad User-definable associated data.
| Encrypted wrapped/encoded payload (length pl is in bits)
| 056 + kl + iead + (pl + 7) / Internal encrypted AESKW payload, or external encrypted PKOAEP2 payload.
| uad 8
| End of optional clear key or encrypted AESKW payload
| End of components
| Note: All numbers are in big endian format.
|

| Table 132 shows the format of the MAC variable-length symmetric key-token that, beginning with Release
| 4.1, can be used with the HMAC algorithm. An HMAC MAC key-token is used by the HMAC_Generate
| (CSNBHMG) and HMAC_Verify (CSNBHMV) verbs to generate or verify keyed hash message
| authentication codes.
Table 132. Variable-length symmetric key-token, key type MAC (Release 4.1 or later)
Length
Header
000 01 Token identifier:
X'00' Internal key-token
X'01' External key-token
002 02 Length in bytes of the overall token structure.
| 56 + kl + iead + uad + ((pl + 7) / 8) (Release 4.2 or later)
| 54 + kl + iead + uad + ((pl + 7) / 8) (Release 4.1)

End of header
Wrapping information section (all data related to wrapping the token)
008 01 Key material state:
X'00' No key present (internal or external)
X'01' Key is clear (internal)
X'02' Key is encrypted under a KEK (external)
X'03' Key is encrypted under the master key (internal)
009 01 Key verification pattern (KVP) type:
X'00' No KVP
X'01' AESMK (8 leftmost bytes of SHA-256 hash (X'01' || clear AES MK))
X'02' KEK verification pattern
Note: Key-wrapping method X'03' (PKOAEP2) has no KVP.

010 16 KVP.
Value is left-aligned in the field and padded on the right with binary zeros.
Note: For key-wrapping method X'03' (PKOAEP2), this value is filled with binary
zeros.
026 01 Encrypted section key-wrapping method:
X'00' Clear key
X'02' AESKW
X'03' PKOAEP2
027 01 Hash algorithm used for wrapping.
For clear key wrapping method (X'00' at offset 26):

X'00' Clear key (no hash)
For AESKW wrapping method (X'02' at offset 26):

X'02' SHA-256
For PKOAEP2 wrapping method (X'03' at offset 26):

X'01' SHA-1
X'02' SHA-256
X'04' SHA-384
X'08' SHA-512

Table 132. Variable-length symmetric key-token, key type MAC (Release 4.1 or later) (continued)
Length
End of wrapping information section
AESKW components: (1) associated data and (2) optional clear key or encrypted AESKW payload.
Associated data section
030 01 Associated data section version (X'01').
032 02 Length in bytes of the associated data.
| 24 + kl + iead + uad
034 01 Length in bytes of the key label: kl (0 or 64).
035 01 Length in bytes of the IBM extended associated data: iead (0).
036 01 Length in bytes of the user-definable associated data: uad (0 - 255).
038 02 Length in bits of the payload: pl.
Valid values are 0 when no key is present, 80 - 2048 when key is clear, and 464 -
2432 when key is encrypted.
041 01 Type of algorithm for which the key can be used.
X'03' HMAC
042 02 Key type:
X'0002' MAC
044 01 Key-usage fields count: kuf (2).
045 02 Key-usage field 1.
High-order byte:
B'1xxx xxxx' Key can be used for generate.
B'0xxx xxxx' Key cannot be used for generate.
B'x1xx xxxx' Key can be used for verify.
B'x0xx xxxx' Key cannot be used for verify.
All unused bits are reserved and must be zero.

Table 132. Variable-length symmetric key-token, key type MAC (Release 4.1 or later) (continued)
Length
047 02 Key-usage field 2.
High-order byte:
B'1xxx xxxx' SHA-1 hash method is allowed for the key.
B'0xxx xxxx' SHA-1 hash method is not allowed for the key.
B'x1xx xxxx' SHA-224 hash method is allowed for the key.
B'x0xx xxxx' SHA-224 hash method is not allowed for the key.
B'xx1x xxxx' SHA-256 hash method is allowed for the key.
B'xx0x xxxx' SHA-256 hash method is not allowed for the key.
B'xxx1 xxxx' SHA-384 hash method is allowed for the key.
B'xxx0 xxxx' SHA-384 hash method is not allowed for the key.
B'xxxx 1xxx' SHA-512 hash method is allowed for the key.
B'xxxx 0xxx' SHA-512 hash method is not allowed for the key.
All unused bits are reserved and must be zero.
| Low-order byte:
| xxxx xxxx Reserved

049 01 Key-management fields count: kmf
2 Release 4.1
3 Release 4.2 or later
050 02 Key-management field 1.

052 02 Key-management field 2.

| 054 02 Key-management field 3 (Release 4.2 or later).

End of associated data section
Optional clear key or encrypted AESKW payload
| 056 + kl + iead + (pl + 7)/8 Clear key or encrypted wrapped/encoded payload.
| uad
End of optional clear key or encrypted AES KW payload
End of AESKW components
Note: All numbers are in big endian format.
Table 133 on page 623 shows the format of the EXPORTER and IMPORTER variable-length symmetric
key tokens that can be used with the AES algorithm. An EXPORTER operational key-token is used by the
Symmetric_Key_Export (CSNDSYX) verb to export an internal AES or HMAC variable-length symmetric
key-token into an external variable-length symmetric key-token, either into an AESKW or PKOAEP2
wrapped payload. An IMPORTER operational key-token is used by the Symmetric_Key_Import2
(CSNDSYI2) verb to import an external AES or HMAC variable-length symmetric key-token, containing
either an AESWK or PKOAEP2 wrapped payload, into an internal variable-length symmetric key-token.

| Table 133. Variable-length symmetric key-token, key types EXPORTER and IMPORTER (Release 4.2 or later)
| Length
| Header
| 000 01 Token identifier:
| X'01' Internal key-token
| X'02' External key-token

| 002 02 Length in bytes of the overall token structure:
| 60 + kl + iead + uad + ((pl + 7) / 8)

| 004 01 Token version number (X'05').
| End of header
| Wrapping information section (all data related to wrapping the token)
| 008 01 Key material state:
| X'00' No key present (internal or external)
| X'02' Key is encrypted under a KEK (external)
| X'03' Key is encrypted under the master key (internal)

| 009 01 Key verification pattern (KVP) type:
| X'00' No KVP
| X'01' AESMK (8 leftmost bytes of SHA-256 hash (X'01' || clear AES MK))
| X'02' KEK verification pattern (8 leftmost bytes of SHA-256 hash (X'01' || clear
| KEK))
| Note: Key-wrapping method X'03' (PKOAEP2) has no KVP.

| 010 16 KVP.
| zeros.
| 026 01 Encrypted section key-wrapping method:

| Table 133. Variable-length symmetric key-token, key types EXPORTER and IMPORTER (Release 4.2 or
| later) (continued)
| Length
| 027 01 Hash algorithm used for wrapping.
| For key-wrapping method X'02' (AESKW):

| X'02' SHA-256
| For key-wrapping method X'03' (PKOAEP2):

| X'01' SHA-1
| X'02' SHA-256
| X'04' SHA-384
| X'08' SHA-512

| End of wrapping information section
| Components: (1) associated data and (2) encrypted wrapped/encoded payload
| 032 02 Length in bytes of the associated data (26 + kl + iead + uad).
| 035 01 Length in bytes of the IBM extended associated data: iead (0 - 255).
| 038 02 Length in bits of the encrypted payload: pl.
| 041 01 Type of algorithm for which the key can be used.
| X'02' AES
| 042 02 Key type:
| X'0003' EXPORTER
| X'0004' IMPORTER
| 044 01 Key-usage fields count: 4. Each key-usage field is two bytes in length.

| Length
| High-order byte for EXPORTER:

| B'1xxx xxxx' Key can be used for EXPORT.
| B'0xxx xxxx' Key cannot be used for EXPORT.
| B'x1xx xxxx' Key can be used for TRANSLAT.
| B'x0xx xxxx' Key cannot be used for TRANSLAT.
| B'xx1x xxxx' Key can be used for GENERATE-OPEX.
| B'xx0x xxxx' Key cannot be used for GENERATE-OPEX.
| B'xxx1 xxxx' Key can be used for GENERATE-IMEX.
| B'xxx0 xxxx' Key cannot be used for GENERATE-IMEX.
| B'xxxx 1xxx' Key can be used for GENERATE-EXEX.
| B'xxxx 0xxx' Key cannot be used for GENERATE-EXEX.
| B'xxxx x1xx' Key can be used for GENERATE-PUB.
| B'xxxx x0xx' Key cannot be used for GENERATE-PUB.
| High-order byte for IMPORTER:

| B'1xxx xxxx' Key can be used for IMPORT.
| B'0xxx xxxx' Key cannot be used for IMPORT.
| B'x1xx xxxx' Key can be used for TRANSLAT.
| B'x0xx xxxx' Key cannot be used for TRANSLAT.
| B'xx1x xxxx' Key can be used for GENERATE-OPIM.
| B'xx0x xxxx' Key cannot be used for GENERATE-OPIM.
| B'xxx1 xxxx' Key can be used for GENERATE-IMEX.
| B'xxx0 xxxx' Key cannot be used for GENERATE-IMEX.
| B'xxxx 1xxx' Key can be used for GENERATE-IMIM.
| B'xxxx 0xxx' Key cannot be used for GENERATE-IMIM.
| B'xxxx x1xx' Key can be used for GENERATE-PUB.
| B'xxxx x0xx' Key cannot be used for GENERATE-PUB.

| High-order byte:
| Low-order byte:

| Length
| 049 Key-usage field 3.
| High-order byte:
| B'1xxx xxxx' Key can wrap DES keys.
| B'0xxx xxxx' Key cannot wrap DES keys.
| B'x1xx xxxx' Key can wrap AES keys.
| B'x0xx xxxx' Key cannot wrap AES keys.
| B'xx1x xxxx' Key can wrap HMAC keys.
| B'xx0x xxxx' Key cannot wrap HMAC keys.
| B'xxx1 xxxx' Key can wrap RSA keys.
| B'xxx0 xxxx' Key cannot wrap RSA keys.
| B'xxxx 1xxx' Key can wrap ECC keys.
| B'xxxx 0xxx' Key cannot wrap ECC keys.
| Low-order byte:

| High-order byte:
| B'1xxx xxxx' Key can wrap DATA class keys.
| B'0xxx xxxx' Key cannot wrap DATA class keys.
| B'x1xx xxxx' Key can wrap KEK class keys.
| B'x0xx xxxx' Key cannot wrap KEK class keys.
| B'xx1x xxxx' Key can wrap PIN class keys.
| B'xx0x xxxx' Key cannot wrap PIN class keys.
| B'xxx1 xxxx' Key can wrap DERIVATION class keys.
| B'xxx0 xxxx' Key cannot wrap DERIVATION class keys.
| B'xxxx 1xxx' Key can wrap CARD class keys.
| B'xxxx 0xxx' Key cannot wrap CARD class keys.
| Low-order byte:

| 053 01 Key management fields count: 3. Each key-management field is two bytes in length.




| Length
| Encrypted wrapped/encoded payload (length pl is in bits)
| 060 + kl + iead + (pl + 7)/8 Internal encrypted AESKW payload, or external encrypted PKOAEP2 payload.
| uad
| End of optional clear key or encrypted AESKW payload
| End of components
| Note: All numbers are in big endian format.
|
| Table 134. Common key-usage field 1, low-order byte
| Length
| (bytes) Description
| 02 Key-usage field 1, low-order byte.
| B'xxxx 1xxx' The key can be used only in UDXs.
| B'xxxx 0xxx' The key can be used in UDXs and CCA.
| B'xxxx xuuu' Reserved for UDXs, where uuu are UDX-defined bits.

|
| Table 135. Common key-management field 1
| Length
| 02 Key-management field 1.
| High-order byte:
| B'1xxx xxxx' Allow export using symmetric key.
| B'0xxx xxxx' Prohibit export using symmetric key.
| B'x1xx xxxx' Allow export using unauthenticated asymmetric key.
| B'x0xx xxxx' Prohibit export using unauthenticated asymmetric key.
| B'xx1x xxxx' Allow export using authenticated asymmetric key.
| B'xx0x xxxx' Prohibit export using authenticated asymmetric key.
| Low-order byte, symmetric:

| B'0xxx xxxx' Allow export using DES key.
| B'1xxx xxxx' Prohibit export using DES key.
| B'x0xx xxxx' Allow export using AES key.
| B'x1xx xxxx' Prohibit export using AES key.
| Low-order byte, asymmetric:

| B'xxxx 0xxx' Allow export using RSA key.
| B'xxxx 1xxx' Prohibit export using RSA key.

|

| Length
| High-order byte:
| B'11xx xxxx' Key is incomplete. Key requires at least 2 more parts.
| B'10xx xxxx' Key is incomplete. Key requires at least 1 more part.
| B'01xx xxxx' Key is incomplete. Key can be completed or have more parts added.
| B'00xx xxxx' Key is complete. No more parts can be added.
| Low-order byte (Release 4.2 or later):

| B'xxx1 xxxx' Key was encrypted with an untrusted KEK.
| B'xxxx 1xxx' Key was in a format without type/usage attributes.
| B'xxxx x1xx' Key was encrypted with key weaker than itself.
| B'xxxx xx1x' Key was in a non-CCA format.
| B'xxxx xxx1' Key was encrypted in ECB mode.

|

| Length
| Pedigree indicates how key was originally created and how it got into the current system.
| High-order byte, pedigree original:

| X'00' Unknown.
| X'01' Other. Method other than those defined here, probably used in UDX.
| X'02' Randomly generated.
| X'03' Established by key agreement such as Diffie-Hellman.
| X'04' Created from cleartext key components.
| X'05' Entered as a cleartext key value.
| X'06' Derived from another key.
| X'07' Cleartext keys or key parts that were entered at TKE and secured from there to the target
| card.
| All unused values are reserved and undefined.
| Low-order byte, pedigree current:

| X'00' Unknown.
| X'01' Other. Method other than those defined here, probably used in UDX.
| X'02' Randomly generated.
| X'03' Established by key agreement such as Diffie-Hellman.
| X'04' Created from cleartext key components.
| X'05' Entered as a cleartext key value.
| X'06' Derived from another key.
| X'07' Imported from CCA version X'05' variable-length symmetric key-token with pedigree field.
| X'08' Imported from CCA version X'05' variable-length symmetric key-token with no pedigree field.
| X'09' Imported from CCA key-token that contained a nonzero control vector.
| X'0A' Imported from CCA key-token that either had no control vector or contained a zero control
| vector.
| X'0B' Imported from a TR-31 key block that contained a control vector (ATTR-CV option).
| X'0C' Imported from a TR-31 key block that did not contain a control vector.
| X'0D' Imported using PKCS 1.2 RSA encryption.
| X'0E' Imported using PKCS OAEP encryption.
| X'0F' Imported using PKA92 RSA encryption.
| X'10' Imported using RSA ZERO-PAD encryption.
| X'11' Converted from a CCA key-token that contained a nonzero control vector.
| X'12' Converted from a CCA key-token that either had no control vector or contained a zero
| control vector.
| X'13' Cleartext keys or key parts that were entered at TKE and secured from there to the target
| card.
| X'14' Exported from CCA version X'05' variable-length symmetric key-token with pedigree field.
| X'15' Exported from CCA version X'05' variable-length symmetric key-token with no pedigree field.
| X'16' Exported using PKCS OAEP encryption.
| All unused values are reserved and undefined.

|
|
| TR-31 optional block data
| This section describes the IBM-defined data for a TR-31 optional block that can be contained in a TR-31
| key block. See X9 TR-31 2010: Interoperable Secure Key Exchange Block Specification for Symmetric
| Algorithms for the definition of a TR-31 key block. As defined by X9 TR-31, a TR-31 key block can contain
| one or more optional blocks. A TR-31 key block contains at least one optional block when byte number 12
| - 13 is a value other than ASCII string "00".

| The data of an IBM-defined optional block contains ASCII string "00" (X'3130') in the first two bytes, and
| contains ASCII string "IBMC" (X'49424D43') beginning at offset 4 of the data. CCA treats an optional block
| with these characteristics as a proprietary container for a CCA control vector. See Table 138. An optional
| block with different characteristics is ignored by CCA.
| If a TR-31 key block contains an optional block as defined by Table 138, the data contains a copy of the
| 8-byte or 16-byte DES control vector that was in the CCA key-token of the key being exported. The copied
| control vector is in hex-ASCII format.
| The control vector is only copied from the CCA key-token when the user of the Key_Export_to_TR31 verb
| specifies a control vector transport control keyword (INCL-CV or ATTR-CV):
| 1. If the optional block contains a control vector as the result of specifying the INCL-CV keyword during
| export, the key usage and mode of use fields indicate the key attributes, and these attributes are
| verified during export to be compatible with the ones in the included control vector.
| 2. If the optional block contains a control vector as the result of specifying the ATTR-CV keyword during
| export, the key usage field (byte number 5 - 6 of the TR-31 key block) is set to the proprietary value
| "10" (X'3130'), and the mode of use field (byte number 8) is set to the proprietary value "1" (X'31').
| These proprietary values indicate that the key attributes are specified in the included control vector.
| See Chapter 9, TR-31 symmetric-key management, on page 499 for additional information on how CCA
| uses an IBM-defined optional block in a TR-31 key block.
| Table 138. IBM optional block data in a TR-31 key block
| Offset Length
| (bytes) (bytes) Description
| 00 02 Proprietary ID of TR-31 optional block (alphanumeric-ASCII):
| X'3130' IBM proprietary optional block (ASCII string "10")
| 02 02 Length of optional block (hex-ASCII):
| For TLV valued to "01":

| X'3143' "1C" for 8-byte (single-length) control vector
| X'3243' "2C" for 16-byte (double-length) control vector
| Beginning of optional block data
| 04 04 "Magic" value (alphanumeric-ASCII):
| X'49424D43'
| A constant value ("IBMC") used to reduce ambiguity and the chance for false
| interpretation of the proprietary optional blocks of non-IBM vendors.
| An optional block that uses the same proprietary ID but does not include this magic
| value will be ignored.
| 08 02 Tag-length-value (TLV) ID (numeric-ASCII):
| X'3031' IBM CCA control vector ("01")
| 10 02 Length of TLV (hex-ASCII)
| For TLV valued to "01":

| X'3134' "14" (decimal 20) TLV of 8-byte control vector
| X'3234' "24" (decimal 36) TLV of 16-byte control vector
| 12 16 or 32 Control vector (hex-ASCII)
|
|
ACI smart card formats
This information was taken directly from ACI Smart Chip Manager Product Suite, System Design
Specification, RSA Private Key Formats 2008-2009 by ACI Worldwide B.V. All rights reserved. Author: V.
Kessels

The size of an RSA key pair is the size of the modulus component (m) and is measured in bits. Common
sizes are 768, 1024 and 1152 bits.
The Modulus-Exponent format consists of the following components:

Table 139. Modulus-Exponent components
Component Size
Modulus m
Private Exponent m
The CRT format consists of the following components:

Table 140. CRT components
Component Size Alternate names
Prime 1 m/2 p CP
Prime 2 m/2 q CQ
Exponent 1 m/2 d mod (p 1) CD1
Exponent 2 m/2 d mod (q 1) CD2
Coefficient m/2 (q 1) mod p CA
| This section describes the following ACI smart card formats:

| v Format 1 Visa proprietary format
| v Format 2 Common personalization for ModulusExponent format on page 632
| v Format 3 Common personalization for CRT format on page 632
Format 1 Visa proprietary format

This format supports only the ModulusExponent format.
The formatting of each component is as follow:

Table 141. Visa proprietary format data fields
Field Length (bytes) Description
KEYDATA Length 1 Length of component without padding, in bytes.
Component m Modulus or Private Exponent.
Padding 3 or 7 Padding with X'00' to make KEYDATA a multiple of 8
bytes.
The whole KEYDATA field should be encrypted with Triple-DES in ECB mode. There is no chaining
between the two KEYDATA fields.
The whole private key should be formatted as:

Table 142. Visa proprietary format private key format
Private Encrypted KEYDATA m + 4 or The encrypted KEYDATA using 3DES ECB.
Exponent m + 8
Modulus Encrypted KEYDATA m + 4 or The encrypted KEYDATA using 3DES ECB.
m + 8

Format 2 Common personalization for ModulusExponent format
This format supports only the Modulus-Exponent format.

Table 143. Common personalization ModulusExponent data fields
KEYDATA Component m Modulus or Private Exponent.
Padding 4 or 8 Padding with X'80000000' or X'80000000 00000000' to make
KEYDATA a multiple of 8 bytes.

Table 144. Common Personalization ModulusExponent private key format
Private Encrypted KEYDATA m + 4 or The encrypted KEYDATA using 3DES ECB.
Exponent m + 8
Modulus Encrypted KEYDATA m + 4 or The encrypted KEYDATA using 3DES ECB.
m + 8
Format 3 Common personalization for CRT format

This format supports only the CRT format.

Table 145. Common personalization CRT data fields
KEYDATA Component m/2 Prime 1, Prime 2, Exponent 1, Exponent 2 or Coefficient component
Padding 4 or 8 Padding with X'80000000' or X'80000000 00000000' to make
KEYDATA a multiple of 8 bytes.
Note: According to the EMV Card Personalization Specification, only ECB is used to encrypt the RSA
Private Key components.

Table 146. Common personalization CRT private key format
Prime 1 Encrypted KEYDATA m / 2 + 4 or The encrypted KEYDATA using 3DES ECB.
m / 2 + 8
Prime 2 Encrypted KEYDATA m / 2 + 4 or The encrypted KEYDATA using 3DES ECB.
m / 2 + 8
Exponent 1 Encrypted KEYDATA m / 2 + 4 or The encrypted KEYDATA using 3DES ECB.
m / 2 + 8

Table 146. Common personalization CRT private key format (continued)
Exponent 2 Encrypted KEYDATA m / 2 + 4 or The encrypted KEYDATA using 3DES ECB.
m / 2 + 8
Coefficient Encrypted KEYDATA m / 2 + 4 or The encrypted KEYDATA using 3DES ECB.
m / 2 + 8
Chaining-vector work areas

The chaining_vector parameter is a pointer to a string variable containing an 18-byte work area that is
required with the Encipher, Decipher, MAC_Generate, MAC_Verify, and MDC_Generate verbs. Ensure that
the application program does not change the chaining_vector variable between related verb calls. The verb
uses the chaining vector to carry information between procedure calls.
Table 147. Encipher, Decipher, MAC_Generate, MAC_Verify, and MDC_Generate chaining-vector format
Offset Length (bytes) Description (bytes)
00 8 The cryptographic output chaining-vector (OCV) of the service. When used with the
MAC_Generate and MAC_Verify verbs, the OCV is enciphered as a cryptographic variable.
08 1 The count of the bytes that are carried over and not processed (from 0 - 7).
09 7 The bytes that are carried over and left-aligned.
16 2 The token master-key verification pattern.
Key-storage datasets and records

Key storage exists as an online, resident dataset on the hard disk drive. Key storage contains key records.
Key records contain a key label, space for a key token, and control information. The stored key tokens are
accessed using the key label. AES, DES, and PKA key tokens are held in independent key-storage
datasets.
For platforms other than IBM i, the first two records in key storage contain key-storage control information
that includes the key verification information for the master key that is used to multiply-encipher the keys
that are held in key storage.
v Table 148 on page 634 shows the format of the first record in the file header of the key-storage file. This
record contains the default master-key verification pattern, and part of the file description.
v Table 149 on page 635 shows the format of the second record in the file header of the key-storage file.
This record contains the rest of the file description for key storage.
For platforms other than IBM i, Table 150 on page 636 shows the format of the AES, DES, and PKA
records that contain key tokens. For the IBM i platform, the AES, DES, and PKA key tokens are held in
distinct record formats.
v Table 151 on page 636 shows the format of the records in IBM i DES key-storage that contain key
tokens.
v Table 152 on page 636 shows the format of the records in IBM i AES and PKA key-storage that contain
key tokens.

Table 148. Key-storage file, header record 1 (not IBM i)
000 04 For AES or PKA, the total length of this key record, which is 192, in little endian format.
Otherwise, reserved.
004 04 The record validation value, in little endian format.
008 64 The header record 1 key label without separators. The key label is
$$FORTRESS$REL01$MASTER$KEY$VERIFY$PATTERN
072 15 The date and time when this record was created. The date string consists of an 8-digit date
and a 6-digit time (yyyymmddhhttssz) where:
yyyy Year
mm Month
dd Day
hh Hour in 24 hour format (00-24)
tt Minutes
ss Seconds
z String terminator (X'00')
087 15 The date and time when this record was last updated. This field has the same format as the
created date (offset 072).
102 26 Reserved.
128 01 Key-token identifier:
X'01' AES or DES
X'1F' PKA
129 01 Key-storage file version. The version is X'01'.
130 02 Token length which is a value of 64, in big endian format.
132 02 Reserved.
134 02 First two bytes of the SHA-1 DES or PKA MKVP. See SHA-1 based master-key verification
method on page 677.
136 16 The master-key verification pattern of the associated current master-key in the cryptographic
facility when this file was initialized, or when the master key changes. For AES, see SHA-256
based master-key verification method on page 678.
152 24 The first 24 bytes of the file description identified by the key_storage_description parameter of
the Key_Storage_Initialization verb. The remaining 40 bytes are stored in the second record
at offset 136.
176 12 Reserved.
188 04 The token-validation value. Bytes 128 through 191 are considered to be the 64-byte token.

Table 149. Key-storage file, header record 2 (not IBM i)
000 04 For AES or PKA, the total length of this key record, which is 192, in little endian format.
Otherwise, reserved.
008 64 The header record 2 key label without separators.
For the AES key-storage file, the key label is

$$FORTRESS$AES$REL01$KEY$STORAGE$FILE$HEADER.
For the DES key-storage file, the key label is

$$FORTRESS$DES$REL01$KEY$STORAGE$FILE$HEADER.
For the PKA key-storage file, the key label is

$$FORTRESS$PKA$REL01$KEY$STORAGE$FILE$HEADER.
072 15 The date and time of when this record was created. The date string consists of an 8-digit date
yyyy Year
mm Month
dd Day
tt Minutes
ss Seconds
102 26 Reserved.
128 01 Key-token identifier:
X'01' AES or DES
X'1F' PKA
129 01 Reserved.
130 02 Token length, which is a value of 64, in big endian format.
132 04 Reserved.
136 40 The last 40 bytes of the key-storage file description (the first 24 bytes were stored in the first
record beginning at offset 152).
176 12 Reserved.
188 04 The token validation value. Bytes 128 through 191 are considered to be the 64-byte token.

Table 150. Key-record format in key storage (not IBM i)
000 04 For AES or PKA, the total length of this key record. This is 192 for AES and DES and variable
for PKA, in little endian format. Otherwise, reserved.
008 64 The key label without separators.
072 15 The date and time when this record was created. The date string consists of an 8-digit date
yyyy Year
mm Month
dd Day
tt Minutes
ss Seconds
102 26 Reserved.
128 ??
AES A 64-byte key token, either null (all bytes X'00'), or internal (first byte X'01')
DES A 64-byte key token, either null (all bytes X'00'), internal (first byte X'01'), or external
(first byte X'02')
PKA A variable-length token containing at least 8 bytes, either null (X'00000008
00000000'), internal (first byte X'1F'), or external (first byte X'1E')
Table 151. DES key-record format, IBM i key storage

056 002 Reserved.
058 064 The CCA DES key-token.
122 004 The date and time of when this record was created.
126 004 The date and time of when this record was last updated.
130 002 Reserved.
132 004 The record validation value.
136 120 Reserved.
Table 152. AES and PKA key-record format, IBM i key storage
064 24 Reserved.
088 04 The date and time of when this record was created.
092 04 The date and time of when this record was last updated.
096 04 The record validation value.
100 02 The key token length.
102 ?? The PKA key token.

Key-record-list datasets and records
There are three key-record-list verbs:
v For the AES key-store, verb AES_Key_Record_List
v For the DES key-store, verb DES_Key_Record_List
v For the PKA key-store, verb PKA_Key_Record_List
Each verb creates an internal dataset that contains information about specified key records in key storage.
Each dataset is named:
KYRLTnnn.LST
where nnn is the numeric portion of the name and nnn starts at 001 and increments to 999 and then
wraps back to 001. Locate the dataset using the fully-qualified dataset name returned by the verb.
Each list dataset has a header record, followed by zero to n detail records, where n is the number of key
records with matching key labels.
Table 153. Key-record-list dataset format (other than IBM i)
Header record (part 1)
000 24 This field contains the installation-configured listing header. The default values are:
v For the AES key-store, AES KEY-RECORD-LIST
v For the DES key-store, DES KEY-RECORD-LIST
v For the PKA key-store, PKA KEY-RECORD-LIST
024 02 This field contains spaces for separation.
026 19 This field contains the date and the time when the list was generated. The format is
yyyy-mm-dd hh:tt:ss, where:
yyyy Year
mm Month
dd Day
hh Hour
tt Minute
ss Second
A space character separates the day and the hour.

050 06 This field contains the number of detail records.
058 04 This field contains the length of each detail record, in character form, and left-aligned. The
length is 154.
062 04 This field contains the offset to the first detail record, in character form, and left-aligned. The
offset is 154.
066 09 This field is reserved filled with space characters.
075 02 This field contains carriage return/line feed (CR/LF).
Header record (part 2)
077 64 This field contains the key-label pattern that you used to request the list.
141 11 This field is reserved filled with space characters.
152 02 This field contains a carriage return or line feeds (CR/LF).
Detail record (part 1)
00 01 This field contains an asterisk (*) if the key-storage record did not have a correct record
validation value; this record should be considered to be a potential error.
03 64 This field contains the key label.

Table 153. Key-record-list dataset format (other than IBM i) (continued)
67 08 This field contains the key type. If a null key token exists in the record or if the key token
does not contain the key value, this field is set to NO-KEY. For the DES key-storage, if the
key token does not contain a control vector, this field is set to NO-CV. If the control vector
cannot be decoded to a recognized key type, this field is set to ERROR, and an asterisk (*) is
set into the record at offset 0. For PKA key-storage, the possible key types are: RSA-PRIV,
RSA-PUBL, RSA-CRT, or RSA-OPT.
75 02 This field contains a carriage return or line feeds (CR/LF).
Detail record (part 2)
77/0 04 For an internal token, this field contains (the first) two bytes of the master-key verification
pattern expressed in hexadecimal.
81/4 01 This field contains spaces for separation.
82/5 08 Reserved, filled with space characters.
92/15 19 This field contains the date and time when the record was created. The format is yyyy-mm-dd
hh:tt:ss, where:
yyyy Year
mm Month
dd Day
hh Hour
tt Minute
ss Second

113/36 19 This field contains the last time and date when the record was updated. The format is
yyyy-mm-dd hh:tt:ss, where:
yyyy Year
mm Month
dd Day
hh Hour
tt Minute
ss Second

132/55 01 This field contains a space character for separation.
133/56 08 This field contains type of token, INTERNAL, EXTERNAL or NO-KEY (null token). Anything
else, this field is set of ERROR and an asterisk (*) is set into the record offset 0 field.
141/64 11 Reserved, filled with space characters.
152/75 02 This field contains a carriage return (CR) or line feeds (LF).
Access-control data structures

| This section describes the data structures that are used in the access-control system:
| v Role structures
| v Profile structures on page 642
| v Examples of the access-control data structures on page 646
Unless otherwise noted, all 2-byte and 4-byte integers are in big-endian format; the high-order byte of the
value is in the lowest-numbered address in memory.
Role structures
This section describes the data structures of a role, which control what permitted operations a user can
perform, and when those operations can be performed.

Basic structure of a role
The following figure describes how the role data is structured. This is the format used when role data is
transferred to or from the coprocessor, using verbs CSUAACI or CSUAACM.
Bytes Field

2 Role structure version (X01, X00)

2 Role structure length (bytes)

20 Comment

2 Checksum

2 Reserved

8 Role ID

2 Required authentication strength

2 Lower time limit

2 Upper time limit

1 Valid DOW

1 Reserved

variable Permitted operations

Figure 24. Access-control system role structure
Note: The checksum value is not used in the current role structure. It can be verified by the IBM 4764
Cryptographic Coprocessor with a future version of the role structure.
The permitted operations are defined by the Access-Control-Point list, described in Access-control-point
list on page 640.
The lower time limit and upper time limit fields are 2-byte structures with each byte containing a binary
value. The first byte contains the hour (0-23) and the second byte contains the minute (0-59). For
example, 8:45 AM is represented by X'08' in the first byte, and X'2D' in the second.
If the lower time limit and upper time limit are identical, the role is valid for use at any time of the day.
The valid days-of-the-week are represented in a single byte with each bit representing a single day. Set
the appropriate bit to B'1' to validate a specific day. The first, or most significant bit (MSB) represents
Sunday, the second bit represents Monday, and so on. The last or least significant bit (LSB) is reserved
and must be set to zero.
Aggregate role structure

A set of zero, one, or more role definitions are sent in a single data structure. This structure consists of a
header, followed by one or more role structures as defined in Basic structure of a role.
The header defines the number of roles that follow in the rest of the structure. Its layout is shown in
Figure 25 on page 640, with three concatenated role structures shown for illustration.

Bytes Field

4 Number of roles in aggregate structure

4 Reserved

variable First role

variable Second role

variable Third role

Figure 25. Aggregate role structure with header
The user's permissions (permitted operations) are attached to each role in the form of an
Access-Control-Point list. This list is a map of bits, with one bit for each primitive function that can be
independently controlled. If a bit is True (1), the user has the authority to use the corresponding function, if
all other access conditions are also satisfied. If the bit is False (0), the user is not permitted to make use
of the function that bit represents.
Each access-control-point identifier (offset) is a two-byte integer (X'0000' - X'FFFF'). This allows
addressability of 2 (64K) bits. Only a small fraction of these addressable bits are used, so storing the
entire 64K bit (8K byte) table in each role would waste memory space. Instead, the table is stored as a
sparse matrix, where only the necessary bits are included.
To accomplish this, each bit map is stored as a series of one or more bit-map segments, where each can
hold a variable number of bits. Each segment must start with a bit that is the high-order bit in a byte, and
each must end with a bit that is the low order bit in a byte. This restriction results in segments that have
no partial bytes at the beginning or end. Any bits that do not represent defined access-control points must
be set to zero, indicating that the corresponding function is not permitted.
The bitmap portion of each segment is preceded by a header, providing information about the segment.
The header contains the following fields:
Starting bit number
The index of the first bit contained in the segment. The index of the first access-control point in the
table is zero (X'0000').
Ending bit number
The index of the last bit contained in the segment.
Number of bytes in segment
The number of bytes of bit-map data contained in this segment.
The entire access-control-point structure is comprised of a header, followed by one or more

access-control-point segments. The header indicates how many segments are contained in the entire
structure.
The layout of this structure is illustrated in Figure 26 on page 641.

Bytes Field

2 Number of segments
Header
2 Reserved

2 Start bit number

2 End bit number
First
2 Number of bitmap bytes bit-map
segment
2 Reserved

variable Bitmap data

. .
. .
. .

2 Start bit number

2 End bit number
Last
2 Number of bitmap bytes bit-map
segment
2 Reserved

variable Bitmap data

Figure 26. Access-control-point structure
Default role contents

The default role has the following characteristics:
v The role ID is DEFAULT.
v The required authentication strength level is zero.
v The role is valid at all times and on all days of the week.
v The only functions that are permitted are those related to access-control initialization. This guarantees
that the owner initializes the coprocessor before any cryptographic work can be done. This requirement
prevents security accidents in which unrestricted default authority might accidentally be left intact when
the system is put into service.
The access-control points that are enabled in the default role are shown in Table 154.
Table 154. Commands permitted in default role
Access-control-point Command name
X'0107' One-Way Hash, SHA-1
X'0110' Set Clock
X'0111' Reinitialize Device
X'0112' Initialize Access-Control System
X'0113' Change User Profile Expiration Date
X'0114' Change User Profile Authentication Data
X'0115' Reset User Profile Logon-Attempt-Failure Count
X'0116' Read Public Access-Control Information
X'0117' Delete User Profile

Table 154. Commands permitted in default role (continued)
Access-control-point Command name
X'0118' Delete Role
X'0119' Load Function-Control Vector
X'011A' Clear Function-Control Vector
Profile structures
This section describes the data structures related to access-control profiles. Each profile defines a unique
8-character user ID, padded on the right with space characters. Use the Logon_Control verb to log on to
the coprocessor using the profile identified by the specified user ID. Once logged on, the user has the
authority to use commands as defined by the role ID identified by the user profile.
Basic structure of a profile

The following figures describe how the profile data is structured. This is the format used when profile data
is transferred to or from the coprocessor, using the Access_Control_Initialization or
Access_Control_Maintenance verbs.
Bytes Field

2 Profile structure version (X01, X00)

2 Profile length

20 Comment

2 Checksum

1 Logon failure count

1 Reserved

8 User ID

8 Role ID

4 Activation date (see format below)

4 Expiration date (see format below)

variable Authentication data

Figure 27. Access-control system profile structure
Bytes Field

2 Year (big-endian format)

1 Month (1-12)

1 Day (1-31)

Figure 28. Format of profile activation date and expiration date

When a new profile is loaded, the host application does not provide the logon failure-count value. This field
is automatically set to zero when the profile is stored in the coprocessor. The failure-count field must have
a value of zero in the initialization data you send with Access_Control_Initialization.
The checksum is defined as the exclusive-OR of each byte in the profile structure. The high-order byte of
the checksum field is set to zero (X'00'), and the exclusive-OR result is put in the low-order byte.
Note: The checksum value is not used in the current profile structure.
Aggregate profile structure

For initialization, a set of zero or one profile definitions are sent to the coprocessor together, in a single
data structure. This structure consists of a header, followed by one or more profile structures as defined in
Profile structures on page 642.
The header defines the number of profiles that follow in the rest of the structure. Its layout is shown in
Figure 29, with three concatenated profile structures shown for illustration.
Bytes Field

4 Number of profiles in aggregate structure

4 Reserved

variable First profile

variable Second profile

variable Third profile

Figure 29. Aggregate profile structure with header
Authentication data structure

This section describes the authentication data, which is part of each user profile. Authentication data is the
information the coprocessor uses to verify your identity when you log on.
There are two versions of the authentication data structure, corresponding to profiles versions 1.0 and 1.1.
The only difference is in the meaning of the length field, as described below.
General structure of authentication data: The authentication data field is a series of one or more
authentication data structures, each containing the data and parameters for a single authentication
method. The field begins with a header, which contains two data elements.
Length
A 2-byte integer value defining how many bytes of authentication information are in the structure.
For profile structure version 1.0, the length includes all bytes after the length field itself. For profile
structure version 1.1, the length includes all bytes after the header, where the header includes
both the Length field and the Field type-identifier field.
Field type-identifier
A 2-byte integer value which identifies the type of data following the header. The identifier must be
set to the integer value X'0001', which indicates that the data is of type authentication data.
The header is followed by individual sets of authentication data, each containing the data for one
authentication mechanism. This layout is shown pictorially in Figure 30 on page 644.

Figure 30. Layout of the authentication data field
The content of the individual authentication data structures is shown in Table 155.
Table 155. Authentication data for each authentication mechanism
Field name Length Description
(bytes)
Length 2 The size of this set of authentication mechanism data, in bytes. The length field
includes all bytes of mechanism data following the length field itself.

Table 155. Authentication data for each authentication mechanism (continued)
Field name Length Description
(bytes)
Mechanism ID 2 An identifier that describes the authentication mechanism associated with this set of
data. For example, there might be identifiers for passphrase, PIN, fingerprint,
public-key based identification, and others. This is an integer value.
For passphrase authentication, the mechanism ID is the integer value X'0001'.

Mechanism 2 An integer value which defines the strength of this identification mechanism,
strength relative to all others. Higher values reflect greater strength. A value of 0 is reserved
for users who have not been authenticated in any way.
Expiration date 4 The last date on which this authentication data can be used to identify the user.
The field contains the month, day, and year of expiration. All four digits of the year
are stored, so that no problems occur at the turn of the century.
The expiration date is a 4-byte structure, as shown in the following C type

definition.
typedef struct {
unsigned char exp_year[2];
unsigned char exp_month;
unsigned char exp_day;
} expiration_date_t;
The 2-byte exp_year is in big-endian format. The high-order byte is at the lower
numbered address.
Mechanism 4 This field contains flags and attributes needed to fully describe the operation and
attributes use of the authentication mechanism. One flag is defined for all methods:
Renewable
A Boolean value that indicates whether the user is permitted to renew the
authentication data. If this value is true (1), the user can renew the data by
authenticating, and then providing new authentication data. For example, to
replace a passphrase, the user first logs on using his or her passphrase. Then,
the passphrase would be changed by providing the new passphrase
authentication data using the Access_Control_Initialization verb with the
CHG-AD rule-array keyword. The format of the passphrase authentication data
is described immediately below under mechanism data.
The renewable bit is the most-significant bit (MSB) in the 4-byte attributes field. The
other 31 bits are unused, and must be set to B'0'.
Mechanism variable This field contains the data needed to perform the authentication. The size, content,
data and complexity of this data varies according to the authentication mechanism. For
example, the content might be as simple as a password that is compared to one
entered by the user, or it might be as complex as a set of sophisticated biometric
reference data, or a public key certificate.
Authentication data for passphrase authentication: For passphrase authentication, the mechanism
data field contains the 20-byte SHA-1 hash value of the user's passphrase. The hash value is computed in
the host, where it is used to construct the profile that is downloaded to the coprocessor.

Examples of the access-control data structures
passphrase authentication data
Figure 31 shows the contents of a sample authentication mechanism data structure for a passphrase.
00 20 00 01 00 ff 07 db 06 01 80 00 00 00 fb f5 . ..............
c4 84 75 5f ba 59 6b ca 4a 9d ca 08 fb 52 9e e2 ..u_.Yk.J....R..
45 41 EA
Figure 31. Passphrase authentication data structure example
This data breaks down into the following fields:

00 20 The length of the authentication mechanism data, excluding the length field itself (32 bytes).
00 01 The mechanism identifier, for passphrase authentication data.
00 FF The mechanism strength, hex 00FF, or decimal 255.
07 DB The year of the passphrase expiration date, hex 07DB, or decimal 2011.
06 01 The month and day of the passphrase expiration date. This represents June 1.
80 00 00 00
The mechanism attributes. The renewable bit is set.
FB F5 C4 84 75 5F BA 59 6B CA 4A 9D CA 08 FB 52 9E E2 45 41
The authentication data. This 20-byte value is the SHA-1 hash value of the user's passphrase. In
this case, the passphrase is:
This is my passphrase.
User profile
Figure 32 provides an example of the contents of an entire user profile, containing the passphrase data
shown above.
01 00 00 5a 2d 20 53 61 6d 70 6c 65 20 50 72 6f ...Z- Sample Pro

66 69 6c 65 20 31 20 2d ab cd 00 00 4a 5f 53 6d file 1 -....J_Sm
69 74 68 20 41 44 4d 49 4e 31 20 20 07 da 06 01 ith ADMIN1 ....
07 db 0c 1f 00 24 00 01 00 20 00 01 00 ff 07 da ....."... ......
06 01 80 00 00 00 fb f5 c4 84 75 5f ba 59 6b ca ..........u_.Yk.
4a 9d ca 08 fb 52 9e e2 45 41 J....R..EA
Figure 32. User profile data structure example
This user profile contains the following fields:

01 00 The profile structure version number. For a version 1.1 profile structure, this would have the value
01 01.
00 5A The length of the profile in bytes, including the length field itself. Hex 5A is equal to decimal 90.
- Sample Profile 1 -
The 20-character comment for this user profile.
AB CD
The checksum for the user profile.
Note: The checksum value is not used. The data is a placeholder.

00 The logon failure count.
00 Reserved field, which must be 0.
J_Smith
The user ID for this profile.

ADMIN1
The role that defines the authority associated with this profile.
07 DA The year of the profile's activation date. Hex 07DA is equal to decimal 2010.
06 01 The month and day of the profile's activation date. This represents June 1.
07 DB The year of the profile's expiration date. Hex 07DB is equal to decimal 2011.
0C 1F The month and day of the profile's expiration date. Hex 0C is equal to decimal 12, and hex 1F is
equal to decimal 31, so the profile expires on December 31.
00 24 The total length of all the authentication data for this profile, not including the length of this field
itself.
00 01 The field type identifier, indicating that the following data is authentication data.
Passphrase data
The remainder of the field is the passphrase data structure, as described above.
Aggregate profile structure

Figure 33 shows the aggregate profile structure, containing one sample user profile. This is the structure
that is passed to the CSUAACI verb in order to load one or more user profiles.
00 00 00 01 00 00 00 00 01 00 00 5a 2d 20 53 61 ...........Z- Sa
6d 70 6c 65 20 50 72 6f 66 69 6c 65 20 31 20 2d mple Profile 1 -
ab cd 00 00 4a 5f 53 6d 69 74 68 20 41 44 4d 49 ....J_Smith ADMI
4e 31 20 20 07 da 06 01 07 db 0c 1f 00 24 00 01 N1 ........."..
00 20 00 01 00 ff 07 da 06 01 80 00 00 00 fb f5 . ..............
c4 84 75 5f ba 59 6b ca 4a 9d ca 08 fb 52 9e e2 ..u_.Yk.J....R..
45 41 EA
Figure 33. Aggregate profile structure example
This structure contains the following data fields:

00 00 00 01
The number of profiles that are in the aggregate structure. This example contains only one user
profile, but any number can be included in the same aggregate structure.
00 00 00 00
A reserved field, which must contain zeros.
User profile
The remainder of this structure contains the single user profile that was described earlier in this
section.
Figure 34 shows the contents of a sample access-control-point list.
00 02 00 00 00 00 01 17 00 23 00 00 f0 ff ff ff .........#......
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 02 ................
00 02 17 00 03 00 00 8f 99 fe ..........
Figure 34. Access-control-point list example
The access-control-point list contains the following data fields:

00 02 The number of segments of data in the access-control-point list. In this list, there are two
discontiguous segments of access-control points. One starts at access-control point 0, and the
other starts at access-control point X'200'.
00 00 A reserved field, which must be filled with zeros.

00 00 The number of the first access-control point in this segment.
01 17 The number of the last access-control point in this segment. The segment starts at access-control
point 0, and ends with access control point X'0117', which is decimal 279.
00 23 The number of bytes of data in the access-control points for this segment. There are X'23' bytes,
which is 35 decimal.
F0 FF FF FF ... FF FF (35 bytes)
The first set of access-control points, with one bit corresponding to each point. Thus, the first byte
contains bits 0-7, the next byte contains 8-15, and so on.
02 00 The number of the first access-control point in the second segment.
02 17 The number of the last access-control point in this segment. The segment starts at access-control
point X'200' (decimal 512), and ends with access-control point X'217' (decimal 535).
00 03 The number of bytes of data in the access-control points for this segment. There are 3 bytes for
the access-control points from 512 through 535.
8F 99 FE
The second set of access-control points, with one bit corresponding to each point. Thus, the first
byte contains bits 512-519, the second byte contains 520-527, and the third byte contains
528-535.
Role data structure

Figure 35 shows the contents of a sample role data structure.
01 00 00 62 2a 4e 65 77 20 64 65 66 61 75 6c 74 ....*New default
20 72 6f 6c 65 20 31 2a ab cd 00 00 44 45 46 41 role 1*....DEFA
55 4c 54 20 23 45 01 0f 17 1e 7c 00 00 02 00 00 ULT #E....|.....
00 00 01 17 00 23 00 00 f0 ff ff ff ff ff ff ff .....#..........
ff ff ff ff ff ff ff ff ff ff ff 02 00 02 17 8f ................
99 fe ..
Figure 35. Role data structure example
This structure contains the following data fields:

00 01 The role structure version number.
00 62 The length of the role structure, including the length field itself.
*New default role 1*
The 20-character comment describing this role.
AB CD
The checksum for the role.
Note: The checksum value is not used.

DEFAULT
The Role ID for this role. The role in this example replaces the DEFAULT role.
23 45 The required authentication strength field.
01 0F The lower time limit. X'01' is the hour, and X'0F' is the minute (decimal 15), so the lower time limit
is 1:15 AM, UTC.

17 1E The upper time limit. X'17' is the hour (decimal 23), and X'1E' is the minute (30), so the upper time
limit is 23:30 UTC.
7C This byte maps the valid days of the week for the role. The first (high order) bit represents
Sunday, the second represents Monday, and so on. Hex 7C is binary 01111100, and enables the
weekdays Monday through Friday.
00 This byte is a reserved field, and must be zero.
The remainder of the role structure contains the access-control-point list described above.
Aggregate role data structure

Figure 36 shows an aggregate role data structure, as you might load using the CSUAACI verb.
00 00 00 01 00 00 00 00 01 00 00 62 2a 4e 65 77 ............*New
20 64 65 66 61 75 6c 74 20 72 6f 6c 65 20 31 2a default role 1*
ab cd 00 00 44 45 46 41 55 4c 54 20 23 45 01 0f ....DEFAULT #E..
17 1e 7c 00 00 02 00 00 00 00 01 17 00 23 00 00 ..|..........#..
f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
ff ff ff 02 00 02 17 8f 99 fe ..........
Figure 36. Aggregate role data structure example
This structure contains the following data fields.

00 00 00 01
The number of roles that are in the aggregate structure. This example contains only one role, but
any number can be included in the same aggregate structure.
00 00 00 00
A reserved field, which must contain zeros.
Role data structure
The remainder of the aggregate structure contains the role structure, which was described above.
Master-key shares data formats

A DES or PKA master key can be cloned from one coprocessor node to another coprocessor node
through master-key-shares distribution. Master-key shares, and potentially other information to be cloned
from one coprocessor to another coprocessor, are packed into a data structure as described in Table 156
on page 650.

Table 156. Cloning information token data structure
Length
000 001 X'1D', token identifier.
001 001 X'00', version.
002 002 Length of the cloning information token.
008 004 Cloning-share index number, i; 1i15.
012 016 Origin-node EID.
028 008 Origin-coprocessor serial number.
036 xxx Cloning information TLV's:
v Master-key share (see Table 157)
v Signature (see Table 158)
Add 1 - 7 bytes of padding to ensure that length 'xxx' is a multiple of 8 bytes.
Note: The information from offset 036 through 036+xxx is triple encrypted with a triple-length DES key using the
EDE3 encryption process, see Triple-DES ciphering algorithms on page 685.
Table 157. Master-key-share TLV

000 001 X'01', master-key-share identifier.
001 001 X'00', version.
002 002 X'001D', length of the TLV.
004 001 Index value, i, binary.
005 024 Master-key share.
Table 158. Cloning information signature TLV

000 001 X'45', signature subsection header.
001 001 X'00', version.
002 002 Subsection length, 70+sss.
004 001 Hashing algorithm identifier; X'01' signifies use of SHA-1.
005 001 Signature formatting identifier; X'01' signifies use of the ISO/IEC 9796-1 process.
006 064 Signature-key identifier; the key label of the key used to generate the signature.
070 sss The signature field.
The signature is calculated on data that begins with the cloning-information-token

data structure identifier (X'1D') through the byte immediately preceding this
signature field.
Distributed function control vector

The export (distribution) of cryptographic implementations by USA companies is controlled under USA
Government export regulations. An IBM 4765 or IBM 4764 becomes a practical cryptographic engine when
it accepts and validates digitally signed software. IBM exports the IBM 4765 and IBM 4764 as
non-cryptographic products, and controls and reports the export of the cryptography-enabling software as
required.

The CCA software that can be loaded into the coprocessor limits the functionality of the coprocessor
based on the values in a function control vector (FCV). The following capabilities are controlled:
v The length of keys used with the AES algorithm for general data ciphering
v The length of keys used with the DES algorithm for general data ciphering
v Use of SET services
v The length of an RSA key used to cipher DES keys
v The length of the highest supported curve order or size for ECC key-agreement services.
IBM distributes the FCV in a digitally signed data structure (certificate). Table 159 and Table 160 on page
653 show the format of the data structure that contains the FCV as distributed by IBM. Use Table 159 for
releases before Release 4.1, and use Table 160 on page 653 for Release 4.1 or later. As shown in
Table 159, the FCV is located at offset 470 (X'1D6'), and has a length of 204 bytes. Table 160 on page
653 shows that the FCV is located at offset 1,238 (X'4D6'), and has a length of 588 bytes. This information
is needed for loading an FCV using the Cryptographic_Facility_Control verb.
For information on loading or clearing an FCV, see the Cryptographic_Facility_Control verb on page 42.
For information on querying an FCV, see the Cryptographic_Facility_Query verb on page 48.
Notes:
1. Government policies and the FCV do not limit the key-length of keys used in digital signature
operations.
2. The SET services can employ 56-bit DES for data encryption, and 1024-bit RSA key-lengths when
distributing DES keys.
3. AES is not supported in releases before Release 3.30.
4. Keys with a modulus length greater than 2048 bits are not supported in releases before Release 3.30.
5. ECC key-agreement services are not supported in releases before Release 4.1.
Table 159. FCV distribution structure, FCV format version X'00' (releases before Release 4.1)
Offset decimal Length
(hex) decimal Description
000 (000) 390 Package header and validating-key public key certificate.
390 (186) 080 Descriptive text coded in ASCII.
470 (1D6) 204 Function control vector (FCV).
This is the information that you supply to the Cryptographic_Facility_Control

(CSUACFC) verb to load the FCV into the cryptographic coprocessor. It consists
of the cryptographic enablement information and a digital signature that is
validated by the CCA code within the coprocessor before accepting and activating
the new FCV.
674 (2A2) 128 Digital signature on the complete structure (excepting this signature itself).
FCV supplied to coprocessor (offset X'1D6' above)
000 (000) 001 Record ID, X'06'.
001 (001) 001 Version, X'00'.
002 (002) 002 Padding, X'0000'.
004 (004) 004 FCV record structure length, X'CC000000' (204, little endian).
008 (008) 004 Signature rules, X'FF000000' (255, little-endian).
012 (00C) 001 FCV format version, X'00'.
013 (00D) 001 CCA services class, X'01', Basic. Currently ignored.

Table 159. FCV distribution structure, FCV format version X'00' (releases before Release 4.1) (continued)
014 (00E) 001 Symmetric algorithm enablement flag byte:
B'xxxxxxx1' CDMF enabled (IBM 4758 only)
B'xxxxxx1x' 56-bit DES enabled
B'xxxxx1xx' Triple-DES enabled
B'xxxx1xxx' 128-bit AES enabled (Release 3.30 or later)
B'xxx11xxx' 192-bit AES enabled (Release 3.30 or later)
B'xx111xxx' 256-bit AES enabled (Release 3.30 or later)
015 (00F) 001 SET services byte:
X'00' No SET services
X'01' CSNDSBD and CSNDSBC with 56-bit DES and 1024-bit RSA key length
permitted.
016 (010) 004 Reserved, X'00000000'.
020 (014) 002 Maximum modulus length for symmetric encryption and decryption, in little-endian
format:
X'0000' Not supported
X'0002' 512 bits
X'0004' 1024 bits
X'0008' 2048 bits
X'0010' 4096 bits (Release 3.30 or later)
022 (016) 002 Reserved, X'0000'.
024 (018) 052 Reserved, X'00...00'.
076 (04C) 128 Digital signature validated by the cryptographic coprocessor (using key FcvPuK)
on preceding fields of FCV.

Table 160. FCV distribution structure, FCV format version X'01' (Release 4.1 or later)
000 (000) 1,158 Package header and validating-key public key certificate.
1,158 (486) 080 Descriptive text coded in ASCII.
1,238 (4D6) 588 Function control vector (FCV).
This is the information that you supply to the Cryptographic_Facility_Control

(CSUACFC) verb to load the FCV into the cryptographic coprocessor. It consists
of the cryptographic enablement information and a digital signature that is
validated by the CCA code within the coprocessor before accepting and activating
the new FCV.
1,826 (722) 512 Digital signature on the complete structure (excepting this signature itself).
FCV supplied to coprocessor (offset X'4D6' above)
000 (000) 001 Record ID, X'06'.
001 (001) 001 Version, X'00'.
002 (002) 002 Padding, X'0000'.
004 (004) 004 FCV record structure length, X'4C020000' (588, little endian).
008 (008) 004 Signature rules, X'FF000000' (255, little-endian).
012 (00C) 001 FCV format version, X'01'.
013 (00D) 001 CCA services class, X'01', Basic. Currently ignored.
014 (00E) 001 Symmetric algorithm enablement flag byte:
B'xxxxxxx1' CDMF enabled (IBM 4758 only)
B'xxxxxx1x' 56-bit DES enabled
B'xxxxx1xx' Triple-DES enabled
B'xxxx1xxx' 128-bit AES enabled (Release 3.30 or later)
B'xxx11xxx' 192-bit AES enabled (Release 3.30 or later)
B'xx111xxx' 256-bit AES enabled (Release 3.30 or later)
015 (00F) 001 SET services byte:
X'00' No SET services
X'01' CSNDSBD and CSNDSBC with 56-bit DES and 1024-bit RSA key length
permitted.
016 (010) 004 Reserved, X'00000000'.
020 (014) 002 Maximum modulus length for symmetric encryption and decryption, in little-endian
format:
X'0000' Not supported
X'0002' 512 bits
X'0004' 1024 bits
X'0008' 2048 bits
X'0010' 4096 bits
022 (016) 002 Maximum supported curve order or size for ECC key-agreement services, in little
endian format:
X'0000' Not supported.
X'0902' 521 bits
024 (018) 052 Reserved X'00...00'.
076 (04C) 512 Digital signature validated by the cryptographic coprocessor (using key FcvPuK)
on preceding fields of FCV.

Appendix C. CCA control-vector definitions and key
encryption
This section describes the following concepts and tasks:
v Understanding DES control-vector values
v Specifying a control-vector-base value on page 661
v Changing control vectors on page 664
v Understanding DES and RSA key encryption and decryption processes on page 671
Note: Unless noted otherwise, a control vector is a DES control vector base in this appendix.
In CCA, a control vector is a non-secret quantity that expresses permissible usages for an associated key.
When a CCA DES key is encrypted, the key-encrypting key is exclusive-ORed with the control vector to
form the actual key used in the DES key-encrypting process. This technique allows the generator or
introducer of a key to specify how the key is to be distributed and used. Attacks can be mounted against a
cryptographic system when it is possible to use a key for other than its intended purpose. The CCA
control-vector key-typing scheme and the command authorization and control-vector checking performed
by a CCA node together provide an important defense against misuse of keys and related attacks.
Understanding DES control-vector values

The CCA DES key token includes the control vector and the encrypted key that the control vector
describes. The control vector is as long as the key, either 64 or 128 bits in length. The control vector is
coupled to the key because it modifies the key-encrypting key value used to encrypt the key found in the
key token. See DES key encryption and decryption processes on page 671.
Although the CCA architecture permits several advanced techniques, the techniques described in this book
use the same control-vector value for the second half of a double-length key as for the first half, except for
the reversal of two bits. This topic about control-vector values focuses on a 64-bit vector with the
understanding that, for a double-length key, the control-vector value associated with each key half is
essentially the same.
Bits 8 to 14, and sometimes bits 18 to 22, of a control vector define the key as belonging to one of several
general classes of keys as shown in Table 161.
Table 161. DES key classes
Key type Key usage
Key-encrypting keys
IMPORTER Used to decrypt a key brought to this local node.
EXPORTER Used to encrypt a key taken from this local node.
IKEYXLAT Used to decrypt an input key in the Key_Translate service.
OKEYXLAT Used to encrypt an output key in the Key_Translate service.
Data operation keys
CIPHER, Used only to encrypt or decrypt data.
DECIPHER,
ENCIPHER
DATA Used to encrypt or decrypt data, or to generate or verify a MAC.
DATAC Used to specify a DATA-class key that performs in the Encipher and Decipher verbs, but not in
the MAC_Generate and MAC_Verify verbs.
655
Table 161. DES key classes (continued)
Key type Key usage
DATAM Used to specify a DATA-class key that performs in the MAC_Generate and MAC_Verify verbs,
but not in the Encipher and Decipher verbs.
DATAMV Used to specify a DATA-class key that performs in the MAC_Verify verb, but not in the
MAC_Generate, Encipher, or Decipher verbs.
MAC Used to generate or verify a MAC.
MACVER Used to verify a MAC code; cannot be used in MAC-generation.
SECMSG Used to encrypt keys or PINs in a secure message.
PIN-processing keys
IPINENC Inbound PIN encrypting key, used to decrypt a PIN block.
OPINENC Outbound PIN encrypting key, used to encrypt a PIN block.
PINGEN Used to generate and verify PIN values.
PINVER Used to verify, but not generate, PIN values.
Special cryptographic-variable encrypting keys
CVARENC Used to encrypt the mask arrays in the Cryptographic_Variable_Encipher verb for the
Control_Vector_Translate verb.
CVARPINE Used to encrypt a clear PIN in the no-longer-supported Encrypted_PIN_Generate_Alternate
verb.
CVARXCVL, Used to encrypt special control values in the Cryptographic_Variable_Encipher verb for use with
CVARXCVR the Control_Vector_Translate verb.
Key-generating keys
DKYGENKY Used to generate a diversified key based on a key-generating key.
KEYGENKY Used to generate or derive other keys.
Usually, there is a default control-vector associated with each of the key types previously listed; see
Table 162 on page 657. The bits in positions 16 - 22 and 33 - 37 generally have different meanings for
every key class. Many of the remaining bits in a control vector have a common meaning. Most of the DES
key-management services permit you to use the default control-vector value by naming the key class in
the service's key-type variable. This does not apply to all key-type classes.
You can use the default control-vector for a key type, or you can create a more restrictive control-vector.
The default control-vector for a key type provides basic key-separation functions. Optional usage
restrictions can further tighten the security of the system.
The cryptographic subsystem creates a default control vector for a key type when you use the
Key_Generate verb and specify a null key token and a key-type in the key_type parameter. Also, when
you import or export a key, you can specify a key type to obtain a default control-vector instead of
supplying a control vector in a key token. If you specify a key type with the Key_Import verb, ensure that
the default control-vector is the same as the control vector that was used to encrypt the key.
The additional control-vector bits that you can turn on or off permit you to further restrict the use of a key.
This gives you the ability to implement the general security policy of permitting only those capabilities
actually required in a system. The additional bits are designed to block specific attacks although these
attacks are often obscure.
You can obtain the value for a control vector in one of several ways:
v To use a default-value control vector, obtain the value from Table 162 on page 657.

v See Specifying a control-vector-base value on page 661. The material presents an ordered set of
tasks to enable you to create the value for a control vector.
v Use the Key_Token_Build verb or the Control_Vector_Generate verb and keywords to construct a
control vector and incorporate this control vector into a key token. See Figure 10 on page 161.
Table 162. Key-type default control-vector values
| Default control vector hexadecimal Default control vector hexadecimal
value for a single-length key, or left value for right half of a
Key type half of a double-length key double-length key
CIPHER 00 03 71 00 03 00 00 00
CVARDEC 00 3F 42 00 03 00 00 00
CVARENC 00 3F 48 00 03 00 00 00
CVARPINE 00 3F 41 00 03 00 00 00
CVARXCVL 00 3F 44 00 03 00 00 00
CVARXCVR 00 3F 47 00 03 00 00 00
DATA (single-length)
(Internal) 00 00 7D 00 03 00 00 00
(External) 00 00 00 00 00 00 00 00
DATA (double-length)
(Internal) 00 00 7D 00 03 41 00 00 00 00 7D 00 03 21 00 00
(External) 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
DATAC 00 00 71 00 03 41 00 00 00 00 71 00 03 21 00 00
DATAM 00 00 4D 00 03 41 00 00 00 00 4D 00 03 21 00 00
DATAMV 00 00 44 00 03 41 00 00 00 00 44 00 03 21 00 00
DECIPHER 00 03 50 00 03 00 00 00
DKYGENKY 00 71 44 00 03 41 00 00 00 71 44 00 03 21 00 00
ENCIPHER 00 03 60 00 03 00 00 00
EXPORTER 00 41 7D 00 03 41 00 00 00 41 7D 00 03 21 00 00
IKEYXLAT 00 42 42 00 03 41 00 00 00 42 42 00 03 21 00 00
IMPORTER 00 42 7D 00 03 41 00 00 00 42 7D 00 03 21 00 00
IMP-PKA 00 42 05 00 03 41 00 00 00 42 05 00 03 21 00 00
IPINENC 00 21 5F 00 03 41 00 00 00 21 5F 00 03 21 00 00
MAC 00 05 4D 00 03 00 00 00
MACVER 00 05 44 00 03 00 00 00
OKEYXLAT 00 41 42 00 03 41 00 00 00 41 42 00 03 21 00 00
OPINENC 00 24 77 00 03 41 00 00 00 24 77 00 03 21 00 00
PINGEN 00 22 7E 00 03 41 00 00 00 22 7E 00 03 21 00 00
PINVER 00 22 42 00 03 41 00 00 00 22 42 00 03 21 00 00
Appendix C. CCA control-vector definitions and key encryption 657

| DES control-vector-base bits (00-63)
| <00..07><08..15><16..23><24..31><32..39><40..47><48..55><56..63>
| 0 0 0 0 0 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 5 5 5 5 5 6 6
| 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2
| ................................................................
|
|
| Most significant CV bit (00) Least significant CV bit (63)
|
| Bits common to all DES control vectors:
| Even parity bits
|
|
|
| ....uu.P.......P.E.....P......0P......1Pfff.K..P.......PWT...u.P
|
| 1=UDX5 0=NO-XPORT 1=ENH-ONLY 1=NOT-CCA
| 1=UDX4 1=XPORT-OK (Rel 4.1
| or later) 0=T31XPTOK
| 1=NOT31XPT
| 1=KEY-PART (Rel 4.2
| or later)
| 000=SINGLE,KEYLN8 (only fff, not FFF)
| Anti-variant bits 010=DOUBLE,KEYLN16,MIXED,left half
| 001=DOUBLE,KEYLN16,MIXED,right half
| 1..=Halves guaranteed unique (110 or 101)
|
| Data operation keys (bits 08-11 = B0000):
| 1=Encipher
| 1=Decipher
| 1=MAC generate
| 1=MAC verify
| DATA
| 0000uu0P000000000Eedmv0P0000000000000011fff0K00P0000000000000u0P
| DATAC
| 0000uu0P000000000E11000P0000000000000011FFF0K00P0000000000000u0P
| DATAM
| 0000uu0P000000000E00110P0000000000000011FFF0K00P0000000000000u0P
| DATAMV
| 0000uu0P000000000E00010P0000000000000011FFF0K00P0000000000000u0P
|
| CIPHER
| 0000uu0P000000110E11000P0000000000000011fff0K00P0000000000000u0P
| DECIPHER
| 0000uu0P000000110E01000P0000000000000011fff0K00P0000000000000u0P
| ENCIPHER
| 0000uu0P000000110E10000P0000000000000011fff0K00P0000000000000u0P
|
| 1=MAC generate
| 1=MAC verify
| MAC
| ccccuu0P000001010E00110P0000000000000011fff0K00P0000000000000u0P
| MACVER
| ccccuu0P000001010E00010P0000000000000011fff0K00P0000000000000u0P
|
|
| 0000=ANY-MAC
| 0001=ANSIX9.9
| 0010=CVVKEY-A
| 0011=CVVKEY-B
| 0100=AMEX-CSC
|
Figure 37. DES control-vector-base bit map (Part 1 of 3)

DES control-vector-base bits (00-63)
<00..07><08..15><16..23><24..31><32..39><40..47><48..55><56..63>
0 0 0 0 0 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 5 5 5 5 5 6 6
0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2
................................................................
SECMSG
0000uu0P000010100Ekp000P0000000000000011FFF0K00P0000000000000u0P

1=SMPIN
1=SMKEY

PIN processing keys (bits 08-11 = B0010):
1=CPINGEN
1=EPINGENA
1=EPINGEN
1=CPINGENA
1=EPINVER
PINGEN
aaaauu0P001000100E.....P0000000000000o1PFFF0K00P0000000000000u0P

0000=NO-SPEC
0001=IBM-PIN/IBM-PINO
0010=VISA-PVV 1=NOOFFSET
0011=INBK-PIN
0100=GBP-PIN/GBP-PINO
0101=NL-PIN-1

PINVER
aaaauu0P001000100E00001P0000000000000o1PFFF0K00P0000000000000u0P

1=EPINVER
1=CPINGENA
IPINENC
0000uu0P001000010E0..trP0000000000000011FFF0K00P0000000000000u0P

OPINENC
0000uu0P001001000E..0trP0000000000000011FFF0K00P0000000000000u0P

CPINENC=1 1=REFORMAT
EPINGEN=1 1=TRANSLAT

Cryptographic variable encrypting keys (bits 08-11 = B0011):
0000uu0P001111110EvvvvvP0000000000000011fff0K00P0000000000000u0P

00000=CVARPINE
00001=CVARDEC
00010=CVARXCVL
00011=CVARXCVR
00100=CVARENC


DES control-vector-base bits (00-63)
<00..07><08..15><16..23><24..31><32..39><40..47><48..55><56..63>
0 0 0 0 0 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 5 5 5 5 5 6 6
0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2
................................................................

Key-encrypting keys (bits 08-11 = B0100):
EXEX=1
OPEX=11=EXPORT
IMEX=11=XLATE
EXPORTER
0000uu0P010000010EgksixP00000000000kkk1PFFF0K00P0000000000000u0P
OKEYXLAT
0000uu0P010000010E00001P00000000000kkk1PFFF0K00P0000000000000u0P
IKEYXLAT
0000uu0P010000100E00001P00000000000kkk1PFFF0K00P0000000000000u0P
IMPORTER
0000uu0P010000100EgksixP00000000000kkk1PFFF0K00P0000000000000u0P

IMEX=11=XLATE 000=ANY*
OPIM=11=IMPORT 001=NOT-KEK* *Discontinued.
IMIM=1 010=DATA* Allowed for
011=PIN* backward
100=LMTD-KEK* compatibility.

KEYGENKY key-generating keys (bits 08-11 = B0101):
0000uu0P010100110E..000P0000000000000011FFF0K00P0000000000000u0P

1=CLR8-ENC
1=UKPT

DKYGENKY key-generating keys (bits 08-11 = B0111):
0000uu0P0111sssP0E0vvvvP0000000000000011FFF0K00P0000000000000u0P

DKYL0=000 0001=DDATA
DKYL1=001 0010=DMAC
DKYL2=010 0011=DMV
DKYL3=011 0100=DIMP
DKYL4=100 0101=DEXP
DKYL5=101 0110=DPVR
DKYL6=110 1000=DMKEY
DKYL7=111 1001=DMPIN
1111=DALL

Key-form bits, 'fff' and 'FFF'

The key-form bits, 40 - 42, and for a double-length key, bits 104 - 106, are designated 'fff' and 'FFF' in the
preceding diagram. These bits can have these values:
B'000' Single-length key (only fff, not FFF)
B'010' Double-length key, left half
B'001' Double-length key, right half
The bits can also have the following values in some CCA implementations although not created by
keyword in the IBM 4765 or IBM 4764 implementations:
B'110' Double-length key, left half, halves guaranteed unique
B'101' Double-length key, right half, halves guaranteed unique

Specifying a control-vector-base value
You can determine the value of a control vector by working through the following series of questions:
1. Begin with a field of 64 bits (8 bytes) set to B'0'. The most significant bit is referred to as bit 0. Define
the key type and subtype (bits 8 14), as follows:
v The main key-type bits (bits 8 - 11). Set bits 8 - 11 to one of the following values:
Bits 8 - 11 Main key type

B'0000' Data operation keys, SECMSG secure messaging keys
B'0010' PIN keys
B'0011' Cryptographic-variable encrypting keys
B'0100' Key-encrypting keys
B'0101' KEYGENKY key-generating keys
B'0111' DKYGENKY key-generating keys
v The key subtype bits (bits 12 - 14). Set bits 12 - 14 to one of the following values:
Bits 12 - 14 Key subtype

Data operation keys
B'000' Compatibility key (DATA)
B'001' Confidentiality key (CIPHER, DECIPHER, or ENCIPHER)
B'010' MAC key (MAC or MACVER)
B'101' SECMSG secure messaging keys
Key-encrypting keys
B'000' Transport-sending keys (EXPORTER and OKEYXLAT)
B'001' Transport-receiving keys (IMPORTER and IKEYXLAT)
PIN Keys
B'001' PIN-generating key (PINGEN, PINVER)
B'000' Inbound PIN-block decrypting key (IPINENC)
B'010' Outbound PIN-block encrypting key (OPINENC)
Key-generating keys
B'001' KEYGENKY key-generating keys
sss In DKYGENKY key-generating keys, sss is the count minus one of the number
of diversifications used to obtain the final, non-diversification key. See
Diversifying DES keys on page 177. The Key_Token_Build verb can set the
sss bits when you supply the DKYL0, ..., and DKYL7 keywords.
Cryptographic-variable encrypting keys
B'111' Cryptographic-variable encrypting key (CVAR....)
2. For key-encrypting keys:

v The key-encrypting key-limiting bits, previously described as bits hhh, bits 35 - 37, are not
supported in any current release of the coprocessor CCA support.
v The key-generating usage bits (gks, bits 18 - 20). Set the gks bits to B'111' to indicate that the
Key_Generate verb can use the associated key-encrypting key to encipher generated keys when
the Key_Generate verb is generating various key-pair key-form combinations (see the
Key-encrypting keys section of Figure 37 on page 658). Without any of the gks bits set to B'1', the
Key_Generate verb cannot use the associated key-encrypting key. The Key_Token_Build verb can
set the gks bits to B'1' when you supply the OPIM, IMEX, IMIM, OPEX, and EXEX keywords.

v The IMPORT and EXPORT bit and the XLATE bit (ix, bits 21 and 22). If you set the i bit to B'1',
the associated key-encrypting key can be used in the Data_Key_Import, Key_Import,
Data_Key_Export, and Key_Export verbs. If you set the x bit to B'1', the associated key-encrypting
key can be used in the Key_Translate and Key_Translate2 verbs. The Control_Vector_Generate
verb can set the ix bits to B'1' when you supply the IMPORT, EXPORT, and XLATE keywords.
v The key-form bits (fff or FFF, bits 40 - 42). The key-form bits indicate how the key was generated
and how the control vector participates in multiple-enciphering. To consist of two different 8-byte
values, set the key-form bits to B'110'; to be the same value, set these bits to B'010'. For
information about the value of the key-form bits in the right half of a control vector, see step 13 on
page 664.
3. For the DATA-class keys (DATA, DATAC, DATM, DATAMV) set the edmv bits (bits 18 - 21) to B'1' to
respectively enable encipher, decipher, mac-generation, and mac-verification operations.
4. For the cipher-class keys (CIPHER, DECIPHER, ENCIPHER, DATA, DATAC) (bits 18 and 19). Set bit
18 is to B'1' for the key to encipher data. Set bit 19 is to B'1' for the key to decipher data.
5. For MAC, MACVER, DATAM, and DATAMV keys, set the following bits:
v The MAC control bits (bits 20 and 21). For a MAC generation key, set bits 20 and 21 to B'11'. For
a MAC verification key, set bits 20 and 21 to B'01'.
v The key-form bits (fff or FFF, bits 40 - 42). For a single-length key, set the bits to B'000'. For a
double-length key, set the bits to B'010'.
6. For SECMSG keys, set one or both of the following bits:
v Set the SMKEY bit (k, bit 18) to B'1' to enable this key type to operate in secure message services
that imbed a key.
v Set the SMPIN bit (p, bit 19) to B'1' to enable this key type to operate in secure message services
that imbed a PIN.
Verbs Secure_Messaging_for_Keys and Secure_Messaging_for_PINs, as used with, for example,
EMV smart cards.
7. For PINGEN and PINVER keys, set the following bits:
v The PIN-calculation-method bits (aaaa, bits 0 - 3). Set these bits to one of the following values:
PIN-calculation method
Bits 0 - 3 keyword Description
B'0000' NO-SPEC A key with this control vector can be used with any
PIN-calculation method.
B'0001' IBM-PIN or IBM-PINO A key with this control vector can be used only with the
IBM PIN or PIN-offset calculation method.
B'0010' VISA-PVV A key with this control vector can be used only with the
Visa PVV PIN-calculation method.
B'0100' GBP-PIN or GBP-PINO A key with this control vector can be used only with the
German Banking Pool PIN or PIN-offset calculation
method.
B'0011' INBK-PIN A key with this control vector can be used only with the
InterBank PIN-calculation method.
B'0101' NL-PIN-1 A key with this control vector can be used only with the
Netherlands PIN-1 calculation method.
v The prohibit-offset bit (o, bit 37) to restrict operations to the PIN value. Set the bit to B'1' to prevent
operation with the IBM 3624 PIN-offset calculation method and the IBM German Bank Pool
PIN-offset calculation method.
8. For PINGEN, IPINENC, and OPINENC keys, set bits 18 - 22 to indicate whether the key can be used
with the following verbs; for the bit numbers, see Figure 37 on page 658:

Verb allowed Bit name Bit
Clear_PIN_Generate CPINGEN 18 for PINGEN
Encrypted_PIN_Generate_Alternate (no longer supported) EPINGENA 19 for PINGEN
Encrypted_PIN_Generate EPINGEN 20 for PINGEN
19 for OPINENC
Clear_PIN_Generate_Alternate CPINGENA 21 for PINGEN
20 for IPINENC
Encrypted_PIN_Verify EPINVER 22 for PINGEN or PINVER
19 for IPINENC
Clear_PIN_Encrypt CPINENC 18 for OPINENC
9. For the IPINENC and OPINENC PIN-block ciphering keys, do the following:
v Set the TRANSLAT bit (t, bit 21) to B'1' to permit the key to be used in the
Encrypted_PIN_Translate verb. The Control_Vector_Generate verb can set the TRANSLAT bit to
B'1' when you supply the TRANSLAT keyword.
v Set the REFORMAT bit (r, bit 22) to B'1' to permit the key to be used in the
Encrypted_PIN_Translate verb. The Control_Vector_Generate verb can set the REFORMAT bit and
the TRANSLAT bit to B'1' when you supply the REFORMAT keyword.
10. For the cryptographic-variable encrypting keys (bits 18 - 22), set the key-usage bits (bits 18 - 22) to
one of the following values:
Bits 18 - 22 Key type Description

B'00000' CVARPINE Used in the (no-longer-supported)
Encrypted_PIN_Generate_Alternate verb to encrypt a clear PIN.
B'00010' CVARXCVL Used in the Control_Vector_Translate verb to decrypt the left
mask-array.
B'00011' CVARXCVR Used in the Control_Vector_Translate verb to decrypt the right
mask-array.
B'00100' CVARENC Used in the Cryptographic_Variable_Encipher verb to encrypt an
unformatted PIN.
11. For KEYGENKY key-generating keys, set the following bits:

v Set the CLR8-ENC bit (bit 19) to B'1' if the key is to be used in the Diversified_Key_Generate
(CSNBDKG) verb to generate a diversified key.
v Bit 18 is reserved for unique key per transaction (UKPT) usage.
12. For DKYGENKY key-generating keys that are used in the TDES-ENC or TDES-DEC mode of the
Diversified_Key_Generate (CSNBDKG) verb, set bits 19 - 22 according to the type of final key that is
to be obtained as shown in the following table:

Bits 19 - 22 Keyword To obtain
B'0001' DDATA single-length or double-length DATA key
B'0010' DMAC single-length or double-length MAC key
B'0011' DMV single-length or double-length MACVER key
B'0100' DIMP IMPORTER key
B'0101' DEXP EXPORTER key
B'0110' DPVR PIN verify key
B'1000' DMKEY double-length SMKEY SECMSG key
B'1001' DMPIN double-length SMPIN SECMSG key
B'1111' DALL any of the above
13. For all keys, set the following bits:

v The export bit (E, bit 17). Set this bit to B'0' to prevent the receiver of a key from exporting or
translating the key for use in another cryptographic subsystem. Once this bit is set to B'0', it cannot
be set to B'1' by any verb. The Prohibit_Export verb can set the export bit to B'0'.
v The key-part bit (K, bit 44). Set the key-part bit to B'1' in a control vector associated with a key
part. When the final key part is combined with previously accumulated key parts, the key-part bit in
the control vector for the final key part is set to B'0'. The Control_Vector_Generate verb can set the
key-part bit to B'1' when you supply the KEY-PART keyword.
v For the user definition bits (uu...u, bits 4, 5, and 61), do the following:
Set to B'1' either or both u4 and u5 as required by a user-defined extension (UDX). These bits
are reserved for use by UDX.
Set the u61 bit to B'1' if the key is only permitted to function in a user-defined extension. That
is, the key is not usable in CCA services defined in this publication. Keys with bits 4, 5, or 61
set to B'1' can be generated, and can be imported and exported (provided other conditions
permit).
v The anti-variant bits (bit 30 and bit 38). Set bit 30 to B'0' and bit 38 to to B'1'. Many cryptographic
systems have implemented a system of variants where a 7-bit value is exclusive-ORed with each
7-bit group of a key-encrypting key before enciphering the target key. By setting bits 30 and 38 to
opposite values, control vectors do not produce patterns that can occur in variant-based systems.
v Control vector bits 64 - 127. If bits 40 - 42 are B'000' (single-length key), set bits 64 - 127 to B'0'.
Otherwise, copy bits 0 - 63 into bits 64 - 127 and set bits 105 and 106 to B'01'.
v Set the parity bits (low-order bit of each byte, bits 7, 15, ..., 127). These bits contain the parity bits
(P) of the control vector. Set the parity bit of each byte so the number of zero-value bits in the byte
is an even number.
Changing control vectors

Use the following techniques to change the control vector associated with a key:
Pre-exclusive-OR
Use this technique to import or export a key from a cryptographic node if you can exclusive-OR one
or more bit patterns into the value of the key-encrypting key used to import the key.
Control_Vector_Translate verb
Use the Control_Vector_Translate verb to change the control vector of an external key.
Note: An external key is a key enciphered by a KEK other than the master key.
Remote_Key_Export verb
Use the Remote_Key_Export verb to change a control vector during an export operation.

Changing control vectors with the pre-exclusive-OR technique
Use the pre-exclusive-OR technique to change a key's control vector when exporting or importing the key
from or to a CCA cryptographic node. By exclusive-ORing information with the KEK used to import or
export the key, you can effectively change the control vector associated with the key.
The pre-exclusive-OR technique requires exclusive-ORing additional information into the value of the
IMPORTER or EXPORTER KEK by one of the following methods:
v Exchange the KEK in the form of a plaintext value or in the form of key parts. For example, if you use
the Key_Part_Import verb to enter the KEK key parts, you can enter another part that is set to the value
of the pre-exclusive-OR quantity (which quantity is discussed later).
v Use the Key_Generate verb to generate an IMPORTER/EXPORTER pair of KEKs, with the KEY-PART
control vector bit set on. Then use the Key_Part_Import verb to enter an additional key part that is set
to the value of the pre-exclusive-OR quantity.
To understand how you can change a keys control vector when importing or exporting keys, you must first
understand the importing and exporting process. For example, when exporting key K, the cryptogram
e*KmCVk(K) is changed to the cryptogram e*KEKCVk1(K).
Notes:
1. The first cryptogram is read as the multiple encipherment of key K by the key formed from the
exclusive-OR of the master key and the control vector, CVk, of key K.
2. The second cryptogram is read as the multiple encipherment of key K by the key formed from the
exclusive-OR of the KEK and the control vector, CVk1, of key K. KEK represents the value of the
EXPORTER key.
3. A control vector of value binary zero is equivalent to not having a control vector.
The CCA specifies that in all but one case, CVk is the same as CVk1. The exception is that a DATA key
where the CVk contains the value of a default CV for that key type, has a CVk1 value equal to binary zero.
To change the control vector on key K, the KEK must be set to the value:
v KEK CVk1 CVk2
where:
v KEK is the value of the shared EXPORTER key.
v represents exclusive-OR.
v CVk1 is the control vector value used with the operational key K at the local node.
v CVk2 is the desired control vector value for the exported key K.
This process works because the value CVk1 is specified in the key token for the exported key. The
Key_Export verb provides this control-vector value to the hardware, which exclusive-ORs it with the
EXPORTER KEK. However, you have set the EXPORTER KEK to the value KEKCVk1, and when CVk1 is
exclusive-ORed with CVk1, the effect is that CVk1 is removed. Because you also set the KEK to include the
desired control vector, CVk2, the exported key has a changed control vector.
If you need to change the control vector for a key when importing the key, the Key_Import verb works in a
similar manner. You exclusive-OR the actual control vector value and the desired control vector value for
the imported key into the value of the key-encrypting key. Then when you call the Key_Import verb, be
sure that the source-key token contains the control vector of the desired target key.
If you are processing a double-length key, you must process the key twice, using the key-encrypting key
modified by different values each appropriate to a key half. Then you concatenate the resulting two correct
key-halves.

PINblockenciphering key (Kp)

Othersystem variant

XOR
Encipherkey process

Transport key (Kt)

Typical non-CCA system eKt(Kp) = e*Kt(Kp)
CCA system

Transport-key XOR
othersystem variant XOR
control vector to obtain
KEK-left and KEK-right e*KEK.Variant(Kp)

Doublelength KEK

XOR
Decipherkey process

Control vector for the
PINblockenciphering key,
control vector left and
control vector right PINblockenciphering key (Kp)

Figure 38. Exchanging a key with a non-control-vector system
Figure 38 shows a typical situation. In a non-CCA system, a PIN-block encrypting key is singly encrypted
by a transport key. No control vector modifies the value of the transport key, Kt, used to encrypt the
PIN-block encrypting key, Kp. The resulting cryptogram can be designated eKt(Kp). Because
triple-encryption is the same as single-encryption when both halves of the encrypting key are equal,
eKt(Kp) = e*Kt(Kp).
In the CCA system, a PIN-block decrypting key is an IPINENC key and must be double length. If both
halves of the double-length key are the same, the IPINENC key effectively performs single encryption. You
must import both halves of the target IPINENC key in different steps and combine the result to obtain the
desired result key.
1. Create two key-encrypting keys to import each half of the target input PIN-block encrypting key. When
you receive key Kt, store this as two different keys:
e*KmCViml(KtCVil) \ e*KmCVimr(KtCVil)
where:
CViml is the control vector for the left half of an IMPORTER key
CVimr is the control vector for the right half of an IMPORTER key
CVil is the control vector for the left half of the target input PIN-block encrypting key
e*KmCViml(KtCVir) \ e*KmCVimr(KtCVir)
where:
CVir is the control vector for the right half of the target input PIN-block encrypting key

2. Use the Key_Token_Build verb to build source and target key tokens with:
v eKt(Kp) \ eKt(Kp)
v CVil \ CVil
3. Use Key_Import and the first of the IMPORTER keys to import the left half of the target key (discard
the right half).
4. Use the Key_Token_Build verb to build source and target key tokens with:
v eKt(Kp) \ eKt(Kp)
v CVir \ CVir
5. Use Key_Import and the second of the IMPORTER keys to import the right half of the target key
(discard the left half).
6. Concatenate the two key halves. You can use the Key_Token_Parse and Key_Token_Build verbs to
parse and build the required key tokens.
Changing control vectors with the Control_Vector_Translate verb

Do the following when using the Control_Vector_Translate verb:
v Provide the control information for testing the control vectors of the source, target, and key-encrypting
keys to ensure that only sanctioned changes can be performed
v Select the key-half processing mode.
Providing the control information for testing the control vectors

To minimize your security exposure, the Control_Vector_Translate verb requires mask array information to
limit the range of allowable control-vector changes. To ensure that this verb is used only for authorized
purposes, the source-key control vector, target-key control vector, and key-encrypting key (KEK) control
vector must pass specific tests. The tests on the control vectors are performed within the secured
The tests consist of evaluating four logic expressions, the results of which must be a string of binary zeros.
The expressions operate bit-for-bit on information that is contained in the mask arrays and in the portions
of the control vectors associated with the key or key-half that is being processed. If any of the expression
evaluations do not result in all zero bits, the verb is ended with a control vector violation return code 8 and
reason code 39. See Figure 39 on page 669. Only the 56 bit positions that are associated with a key value
are evaluated. The low-order bit that is associated with key parity in each key-byte is not evaluated.
Mask array preparation

A mask array consists of seven 8-byte elements: A1, B1, A2, B2, A3, B3, and B4. You choose the values of
the array elements such that each of the following four expressions evaluates to a string of binary zeros.
(See Figure 39 on page 669.) Set the A bits to the value that you require for the corresponding
control-vector bits. In expressions 1 through 3, set the B bits to select the control-vector bits to be
evaluated. In expression 4, set the B bits to select the source and target control-vector bits to be
evaluated. Also, use the following control-vector information:
C1 is the control vector associated with the left half of the KEK.
C2 is the control vector associated with the source key, or selected source-key half/halves.
C3 is the control vector associated with the target key or selected target-key half/halves.
1. (C1 exclusive-OR A1) logical-AND B1
This expression tests whether the KEK used to encipher the key meets your criteria for the desired
translation.
This expression tests whether the control vector associated with the source key meets your criteria for
the desired translation.

This expression tests whether the control vector associated with the target key meets your criteria for
the desired translation.
4. (C2 exclusive-OR C3) logical-AND B4
This expression tests whether the control vectors associated with the source key and the target key
meet your criteria for the desired translation.
Encipher two copies of the mask array, each under a different cryptographic-variable key using key type
CVARENC. To encipher each copy of the mask array, use the Cryptographic_Variable_Encipher verb. Use
two different keys so that the enciphered-array copies are unique values. When using the
Control_Vector_Translate verb, the mask_array_left parameter and the mask_array_right parameter
identify the enciphered mask arrays. The array_key_left_identifier parameter and the
array_key_right_identifier parameter identify the target keys for deciphering the mask arrays. The
array_key_left_identifier key must have a key type of CVARXCVL and the array_key_right_identifier key
must have a key type of CVARXCVR. The cryptographic process deciphers the arrays and compares the
results; for the verb to continue, the deciphered arrays must be equal. If the results are not equal, the verb
returns the return code 8 and reason code 385 (X'181') for data that is not valid.
When using the Key_Generate verb to create the key pairs CVARENC-CVARXCVL and
CVARENC-CVARXCVR, the hardware requires the Generate_Key_Set_Extended command to be enabled.
Each key in the key pair must be generated for a different node. The CVARENC keys are generated for, or
imported into, the node where the mask array is enciphered. After enciphering the mask array, destroy the
enciphering key. The CVARXCVL and CVARXCVR keys are generated for, or imported into, the node
where the Control_Vector_Translate verb is performed.
If using the BOTH keyword to process both halves of a double-length key, remember that key-form bits 41,
42, 105, and 106 are different in the left and right halves of the CCA control-vector and must be ignored in
your mask-array tests (that is, make the corresponding B2 or B3 bits equal to zero).
When the control vectors pass the masking tests, the verb does the following:
v Deciphers the source key. In the decipher process, the verb uses a key that is formed by the
exclusive-OR of the KEK and the control vector in the key-token variable the source_key_token
parameter identifies.
v Enciphers the deciphered source key. In the encipher process, the verb uses a key that is formed by
the exclusive-OR of the KEK and the control vector in the key token variable the target_key_token
parameter identifies.
v Places the enciphered key in the key field in the key token variable the target_key_token parameter
identifies.

For expression
1: KEK CV Control vector
2: Source CV 0101... 0101... under test
3: Target CV

Exclusive-OR

Set tested positions
A_values 0011... 0011... to the value that
the CV must match

Intermediate 0110... 0110...
result

Logical-AND

Set to 1
B_values 0000... 1111... those positions
to be tested

Report a CV
Final result 0000... 0110... violation if any
bit position is 1
For expression
4: Source CV 0101... 0101... Source CV

Exclusive-OR

Target CV 0011... 0011... Target CV

Intermediate 0110... 0110...
result

Logical-AND

Set to 1
B_values 0000... 1111... those positions
to be tested

Report a CV
Final Result 0000... 0110... violation if any
bit position is 1
Figure 39. Control_Vector_Translate verb mask_array processing
Selecting the key-half processing mode

The Control_Vector_Translate verb rule-array keywords determine which key halves are processed in the
verb call, as shown in Figure 40 on page 670. In this figure, CHANGE-CV means the requested control
vector translation change; LEFT and RIGHT mean the left and right halves of a key and its control vector.

Keyword SINGLE Keyword RIGHT Keyword BOTH Keyword LEFT

Source Key LEFT RIGHT LEFT RIGHT LEFT RIGHT LEFT CV-RIGHT

key

Process CHANGECV Copy CHANGECV CHANGECVCHANGECV CHANGECVCHANGECV

(Unchanged)

Target Key LEFT RIGHT LEFT RIGHT LEFT RIGHT LEFT RIGHT

Figure 40. Control_Vector_Translate verb process
The following list provides definitions for keywords:

SINGLE
This keyword causes the control vector of the left half of the source key to be changed. The updated
key half is placed into the left half of the target key in the target key token. The right half of the target
key is unchanged.
The SINGLE keyword is useful when processing a single-length key, or when first processing the left
half of a double-length key (to be followed by processing the right half).
RIGHT
This keyword causes the control vector of the right half of the source key to be changed. The
updated key half is placed into the right half of the target key of the target key token. The left half of
the source key is copied unchanged into the left half of the target key in the target key token.
BOTH
This keyword causes the control vector of both halves of the source key to be changed. The updated
key is placed into the target key in the target key token.
A single set of control information must permit the control vector changes applied to each key half.
Normally, control vector bit positions 41, 42, 105, and 106 are different for each key half. Therefore,
set bits 41 and 42 to B'00' in mask array elements B1, B2, and B3.
You can verify that the source and target key tokens have control vectors with matching bits in bit
positions 40-42 and 104-106, the form field bits. Ensuring that bits 40-42 of mask array B4 are set to
B'111'.
LEFT
This keyword enables you to supply a single-length key and obtain a double-length key. The source
key token must contain:
v The KEK-enciphered single-length key
v The control vector for the single-length key (often this is a null value)
v A control vector, stored in the source token where the right-half control vector is normally stored,
used in decrypting the single-length source key when the key is being processed for the target
right half of the key.
The verb first processes the source and target tokens as with the SINGLE keyword. Then the source
token is processed using the single-length enciphered key and the source token right-half control
vector to obtain the actual key value. The key value is then enciphered using the KEK and the control
vector in the target token for the right-half of the key.
This approach is frequently of use when you must obtain a double-length CCA key from a system
that only supports a single-length key. For example when processing PIN keys or key-encrypting keys
received from non-CCA systems.
To prevent the verb from ensuring that each key byte has odd parity, you can specify the NOADJUST
keyword. If you do not specify the NOADJUST keyword, or if you specify the ADJUST keyword, the verb
ensures that each byte of the target key has odd parity.

When the target key-token CV is null
When you use any of the LEFT, BOTH, or RIGHT keywords, and when the control vector in the target key
token is null (all B'0'), then bit 0 in byte 59 of the target version X'01' key token is set to B'1' to indicate
that this is a double-length DATA key.
Control_Vector_Translate Example
As an example, consider the case of receiving a single-length PIN-block encrypting key from a non-CCA
system. Often such a key is encrypted by an unmodified transport key (no control vector is used). In a
CCA system, an inbound PIN encrypting key (IPINENC) is double-length.
First, use the Key_Token_Build verb to insert the single-length key value into the left-half key-space in a
key token. Specify USE-CV as a key type and a control vector value set to 16 bytes of X'00'. Also specify
EXTERNAL, KEY, and CV keywords in the rule array. This key token is the source token.
The target key token can also be created using the Key_Token_Build verb. Specify a key type of IPINENC
and the NO-EXPORT rule-array keyword.
Second, call the Control_Vector_Translate verb and specify a rule-array keyword of LEFT. The mask
arrays can be constructed as follows:
v A1 is set to the value of the KEK's control vector, most likely the value of an IMPORTER key, perhaps
with the NO-EXPORT bit set. B1 is set to 8 bytes of X'FF' so that all bits of the KEK's control vector are
tested.
v A2 is set to 8 bytes of X'00', the null value of the source key control vector. B2 is set to 8 bytes of X'FF'
so that all bits of the source-key control vector is tested.
v A3 is set to the value of the target key's left-half control vector. B3 is set to X'FFFF FFFF FF9F FFFF'.
This causes all bits of the control vector to be tested except for the two (fff) bits used to distinguish
between the left-half and right-half target-key control vector.
v B4 is set to 8 bytes of X'00' so that no comparison is made between the source and target control
vectors.
Changing control vectors with the Remote_Key_Export verb

The Remote_Key_Export verb can be used to change the control vector of the output external CCA DES
key-token created during an export operation. Normally the control vector is copied as is from the input
internal CCA DES key-token during an export operation. See Table 121 on page 607 for information on
defining a trusted block that can change control vectors during an export operation.
Understanding DES and RSA key encryption and decryption processes

This section describes the CCA key-encryption and key-decryption processes:
v DES key encryption
v RSA private-key encryption
v Encipherment of DES keys under RSA in PKA92 format
v Encipherment of a DES key-encrypting key under RSA in NL-EPP-5 format
DES key encryption and decryption processes

The process exclusive-ORs the subject keys control vector with the master key or with a key-encrypting
key to form keys K1 through K6. The resulting keys (Kn) are used in the multiple-encipherment of a clear
key, or the multiple-decipherment of an encrypted key; see Figure 41 on page 673 for the formation of K1
through K6 and their use with DES encoding and decoding.
RSA private-key encryption and decryption process

RSA private keys are generally encrypted using an EDE algorithm. See Triple-DES ciphering algorithms
on page 685.

With the CCA Support Program Version 1, a private RSA key in an internal PKA key-token encrypted by
the PKA master key is encrypted using the EDE3 process. The secret key is deciphered using the DED3
process. A private RSA key in an external PKA key-token encrypted by a transport key is encrypted using
the EDE2 process. The secret key is deciphered using the DED2 process.
Beginning with the CCA Support Program Version 2, the private RSA secret key values in an internal PKA
key-token are encrypted using a randomly generated Object Protection Key (OPK). The OPK is then
encrypted with the asymmetric (PKA) master key and stored in the key token. For external encrypted RSA
private keys, encryption of the secret key values is provided by the DES transport key. See Table 98 on
page 590 and Table 100 on page 592.

Master key Control vector

0 7 8 15 16 23 0 7 8 15

XOR XOR XOR

K1 K2 K3

XOR XOR XOR

K4 K5 K6

Key-encrypting key

0 7 8 15

XOR XOR

K1,K3 K2

XOR XOR

K4,K6 K5
Multiple Multiple
encipherment decipherment

Clear key Multiply-enciphered key

0 7 8 15 0 7 8 15

K1
Encode EncodeK4 K3
Decode DecodeK6

K2
Decode DecodeK5 K2
Encode EncodeK5

K3
Encode EncodeK6 K1
Decode DecodeK4

Multiply-enciphered key Clear key

Figure 41. Multiply-enciphering and multiply-deciphering DES and RSA keys

Notes:
1. The encode and decode processes are the DES Electronic Code Book (ECB) processes for ciphering
64 data bits using a single-length key, Kn.
2. A CCA cryptographic implementation processes a single-length key in the same way as it processes
the left half of a double-length key.
3. If the left and right halves of a double-length key-encrypting key have the same value, using the key in
multiple-encipherment or multiple-decipherment of a key is equal to single-encipherment or
single-decipherment of a key.
4. The control vector for a double-length key consists of two halves. The second half is the same as the
first half except for bits 41 and 42, which are reversed in value.
PKA92 key format and encryption process

With the Symmetric_Key_Export, Symmetric_Key_Generate, and the Symmetric_Key_Import verbs, you
can use a PKA92 method of encrypting a DES or CDMF key with an RSA public key. This format is
adapted from the IBM Transaction Security System (TSS) 4753 and 4755 product implementation of
PKA92. The verbs do not create or accept the complete PKA92 AS key token as defined for the TSS
products. Rather, the verbs only use the actual RSA-encrypted portion of a TSS PKA92 key token, the AS
external key block.
Forming an AS external key block

The PKA92 implementation forms an AS external key block by RSA-encrypting a key block using a public
key. The key block is formed by padding the PKA key record (PKR) detailed in Table 163 with zero bits on
the left, high-order end of the key record up to the length of the modulus. The process completes the key
block with three subprocesses: masking, overwriting, and RSA encrypting.
Table 163. PKA92 clear DES key-record (PKR)
The public key modulus is constrained to a multiple of 64 bits in the range of 512 to the maximum length for
symmetric encryption set by the FCV. Governmental export or import regulations can impose limits on the modulus
length. The maximum length is validated by a check against a value in the function control vector. See Table 159 on
page 651 and Table 160 on page 653 for additional information.
000 005 Header and flags: X'01 0000 0000'
005 016 EID encoded in ASCII
021 008 Control vector base for the DES key
029 008 Repeat of the CV data at offset 021
037 008 The single-length DES key or the left half of a double-length DES key
045 008 The right half of a double-length DES key or a random number. This value is
locally designated, K.
053 008 Random number, IV
061 001 Ending byte, X'00'
Mask subprocess:
1. Form the initial key block by padding the PKR with zero bits on the left, high-order end to the length of
the modulus.
2. Create a mask by CBC-encrypting a multiple of 8 bytes of binary zeros using K as the key and the
length of the modulus, and IV as the initialization vector as defined in the PKR at offsets 45 and 53.
3. Exclusive-OR the mask with the key block.
Overwrite subprocess:
1. Set the high-order bits of the masked key block to B'01'.

2. Set the low-order bits of the masked key block to B'0110'.
3. Exclusive-OR K and IV.
4. Write the result at offset 45 in the masked PKR.
5. Write IV at offset 53 in the masked PKR. This causes the masked and overwritten PKR to have IV at
its original position.
RSA-encrypt subprocess: RSA-encrypt the masked and overwritten key-record using the public key of
the receiving node. This is the last step in creating an AS external key block.
Recovering a key from an AS external key block

Recover the encrypted DES key from an AS external key block by performing decrypting, validating,
unmasking, and extraction subprocesses.
Decrypting subprocess: RSA-decrypt the AS external key block using an RSA private key. The private
key must be usable for key management purposes.
Validating subprocess: Verify that the high-order 2 bits of the decrypted key block are valued to B'01'
and that the low-order 4 bits of the key block are valued to B'0110'.
Unmasking subprocess: Set IV to the value of the 8 bytes at offset 53 of PKR. There is a variable
quantity of padding in the key block prior to offset 0. See Table 163 on page 674.
Set K to the exclusive-OR of IV and the value of the 8 bytes at offset 45 of the PKR record.
Create a mask that is equal in length to the key block by CBC encrypting a multiple of 8 bytes of binary
zeros using K as the key and IV as the initialization vector. Exclusive-OR the mask with the key record.
Copy K to offset 45 in PKR.
Extraction subprocess: Confirm that:

v The 4 bytes at offset 1 in the PKR are valued to X'0000 0000'
v The two control vector fields at offsets 21 and 29 are identical
v If the control vector is an IMPORTER or EXPORTER key class, that the EID in the key record is not the
same as the EID stored in the cryptographic engine
The control vector base of the recovered key is the value at offset 21. If the control vector base bits 40-42
are valued to B'010' or B'110', the key is double length. Set the right half of the received key's control
vector equal to the left half and reverse bits 41 and 42 in the right half.
The recovered key is at offset 37 and is either 8 or 16 bytes long based on the control vector base bits
40-42. If these bits are valued to B'000', the key is single length. If these bits are valued to B'010' or
B'110', the key is double length.
Encrypting a key-encrypting key in the NL-EPP-5 format

The Symmetric_Key_Generate verb supports a NL-EPP-5 method of encrypting a DES key-encrypting key
with an RSA public key. The verb returns an encrypted key block by RSA-encrypting a key record formed
in the following manner:
1. Format the key and other data as shown in Table 164 on page 676.
2. Insert random padding data into the record.
3. Insert the count of pad bytes plus one.

Table 164. NL-EPP-5 key-record format
000 02 Header and null cancellation bytes, X'0B00'
002 08 Single length key-encrypting key
16 Double length key-encrypting key

010 or 018 Random padding data
063 01 Padding count byte:
v With an RSA key of length 512 bits: X'36' for a single length key-encrypting key, or X'2E' for
a double length key-encrypting key
v With an RSA key of length 1024 bits: X'76' for a single length key-encrypting key, or X'6E'
for a double length key-encrypting key

Appendix D. Algorithms and processes
This section provides processing details for the following aspects of the CCA design:
v Cryptographic key-verification techniques
v Modification Detection Code calculation on page 679
v Ciphering methods on page 681
v Triple-DES ciphering algorithms on page 685
v MAC calculation methods on page 689
v RSA key-pair generation on page 691
v Passphrase verification protocol on page 692
v Master-key-splitting algorithm on page 693
v Formatting hashes and keys in public-key cryptography on page 694
Cryptographic key-verification techniques

The key-verification implementations described in this document employ several mechanisms for assuring
the integrity and value of the key. These topics are discussed:
v Master-key verification algorithms
v CCA DES-key and key-part verification algorithm
v Encrypt zeros algorithm
Master-key verification algorithms

The IBM 4765 and IBM 4764 implementations employ triple-length DES and PKA master keys (three DES
keys) that are internally represented in 24 bytes (168 bits). Beginning with Release 3.30 and Release 4.0,
the IBM 4764 and IBM 4765 implementations employ an AES master-key represented in 32 bytes (256
bits). Beginning with Release 4.1, the IBM 4765 implementation employs an APKA master-key represented
in 32 bytes (256 bits). Key verification patterns on the contents of the new, current, and old master key
registers can be generated and verified when the selected register is not in the empty state.
The IBM 4765 and the IBM 4764 employ several verification pattern generation methods.
SHA-1 based master-key verification method

A SHA-1 hash algorithm is calculated on the quantity X'01' prepended to the 24-byte DES and PKA
master-key-register contents. The resulting 20-byte hash value is used in the following ways:
v The Key_Test verb uses the first eight bytes of the 20-byte hash value as the random_number variable,
and uses the second eight bytes as the verification_pattern.
v A SHA-1 based master-key verification pattern is stored either in a two-byte master-key version number
(Version 1 software) or an eight-byte master-key verification pattern field in an internal key-token. The
stored verification pattern consists of the first two or the first eight bytes of the calculated SHA-1 value,
respectively.
z/OS-based master-key verification method

When the first and third portions of the symmetric DES master-key have the same value, the master key is
effectively a double-length DES key. In this case, the master-key verification pattern (MKVP) is based on
this algorithm:
v C = X'4545454545454545'
v IR = MKfirst-part eC(MKfirst-part)
v MKVP = MKsecond-part eIR(MKsecond-part)
where:
677
v ex(Y) is the DES encoding of Y using x as a key
v represents the bitwise exclusive-OR function
Version X'00' internal CCA DES key tokens use this eight-byte master-key verification pattern.
SHA-256 based master-key verification method

A SHA-256 hash algorithm is calculated on the quantity X'01' prepended to the 32-byte register contents
For AES, there will be verification patterns for both the AES master key and for AES operational keys that
are used to encipher or decipher data. The verification pattern on the master key is called the MKVP. The
verification pattern on operational keys is referred to as a key-verification pattern (KVP).
Both the MKVP and KVP for AES will use the same algorithm. Both will be computed with the following
process.
1. Compute the SHA-256 hash of the string formed by prepending the byte X'01' to the cleartext key
value.
2. Take the leftmost eight bytes of the hash as the verification pattern.
The value is truncated to eight bytes because this is the length allocated for the verification in several CCA
structures and APIs. For example, the AES key token has eight bytes for the MKVP, and the Key_Test
verb has an eight-byte parameter for the verification pattern.
Asymmetric master key MDC-based verification method

The verification pattern for the asymmetric RSA master keys is based on hashing the value of the
master-key using the MDC-4 hashing algorithm. The master key is not parity adjusted.
The RSA private key sections X'06' and X'08' use this 16-byte MDC value as the master-key verification
pattern.
Key-token verification patterns

The verification pattern techniques used in the several types of CCA key tokens are:
v AES and ECC key tokens: leftmost 8 bytes of SHA-256 hash of the string formed by pre-pending X'01'
to the cleartext key value
v DES key tokens:
Triple-length master key, key token version X'00': leftmost 8 bytes of SHA-1 hash
Triple-length master key, key token version X'03': leftmost 2 bytes of SHA-1 hash
Double-length master key, key token version X'00': leftmost 8 bytes of z/OS hash
Double-length master key, key token version X'03': leftmost 2 bytes of SHA-1 hash
v RSA key tokens:
Private-key section types X'06' and X'08': 16-byte MDC-4 value
Private-key section types X'02' and X'05': leftmost 2 bytes of SHA-1 hash
v Trusted blocks: 16-byte MDC-4 value
CCA DES-key verification algorithm

The cryptographic engines provide a method for verifying the value of a DES cryptographic key or key part
without revealing information about the value of the key or key part.
The CCA verification method first creates a random number. A one-way cryptographic function combines
the random number with the key or key part. The verification method returns the result of this one-way
cryptographic function (the verification pattern) and the random number.
Note: A one-way cryptographic function is a function in which it is easy to compute the output from a
given input, but it is not computationally feasible to compute the input given an output.

For information about how you can use an application program to invoke this verification method, see the
verb Key_Test (CSNBKYT) on page 256.
The CCA DES key verification algorithm does the following:

1. Sets KKR = KKR exclusive-OR RN
2. Sets K1 = X'4545454545454545'
3. Sets X1 = DES encoding of KKL using key K1
4. Sets K2 = X1 exclusive-OR KKL
5. Sets X2 = DES encoding of KKR using key K2
6. Sets VP = X2 exclusive-OR KKR
where:
RN Is the random number generated or provided
KKL Is the value of the single-length key, or is the left half of the double-length key
KKR Is XL8'00' if the key is a single-length key, or is the value of the right half of the double-length key
VP Is the verification pattern
| Encrypt zeros AES-key verification algorithm

| The cryptographic engine provides a method for verifying the value of an AES cryptographic key or key
| part without revealing information about the value of the key or key part.
| In this method, the AES key data encryption algorithm encodes a 128-bit value that is all zero bits. The
| leftmost 32 bits of the result are compared to the trial input value or returned from the Key_Test2 verb in
| an 8-byte variable that is padded with bits valued to zero.
Encrypt zeros DES-key verification algorithm

The cryptographic engine provides a method for verifying the value of a DES cryptographic key or key part
without revealing information about the value of the key or key part.
In this method the single-length or double-length key data encryption algorithm encodes a 64-bit value that
is all zero bits. The leftmost 32 bits of the result are compared to the trial input value or returned from the
Key_Test verb.
For a single-length key, the key data encryption algorithm encodes an 8-byte, all-zero-bits value.
For a double-length key, the key data encryption algorithm triple-encodes an 8-byte, all-zero-bits value.
The left half (high-order half) key encodes the zero-bit value, this result is data encryption algorithm
decoded by the right key half, and that result is data encryption algorithm encoded by the left key half.
Modification Detection Code calculation

The Modification Detection Code (MDC) calculation method defines a one-way cryptographic function. A
one-way cryptographic function is a function in which it is easy to compute the input into output (a digest)
but very difficult to compute the output into input. MDC uses DES encryption only and a default key of
X'5252 5252 5252 5252 2525 2525 2525 2525'.
The MDC_Generate verb supports four versions of the MDC calculation method that you specify by using
one of the keywords shown in Table 165 on page 680. All versions use the MDC-1 calculation.
Appendix D. Algorithms and processes 679

Table 165. Versions of the MDC calculation method
Keyword Version of the MDC calculation
MDC-2, PADMDC-2 Specifies two encipherments for each 8-byte input data block. These versions
use the MDC-2 calculation procedure described in Table 166 on page 681.
MDC-4, PADMDC-4 Specifies four encipherments for each 8-byte input data block. These versions
use the MDC-4 calculation procedure described in Table 166 on page 681.
When the keywords PADMDC-2 and PADMDC-4 are used, the supplied text is always padded as follows:
v If the total supplied text is less than 16 bytes in length, pad bytes are appended to make the text length
equal to 16 bytes. A length of zero is allowed.
v If the total supplied text is at least 16 bytes in length, pad bytes are appended to make the text length
equal to the next-higher multiple of 8 bytes. One or more pad bytes are always added.
v All appended pad bytes, other than the last pad byte, are set to X'FF'.
v The last pad byte is set to a binary value equal to the count of all appended pad bytes (X'01' to X'10').
Use the resulting pad text in the following procedures. The MDC_Generate verb uses these MDC
calculation methods. See MDC_Generate (CSNBMDG) on page 126 for more information about the
MDC_Generate verb.

Table 166. MDC calculation procedures
Calculation Procedure
MDC-1 MDC-1(KD1, KD2, IN1, IN2, OUT1, OUT2);
Set KD1mod := set KD1 bit 1 to B1 and bit 2 to B0 (bits 0-7)
Set KD2mod := set KD2 bit 1 to B0 and bit 2 to B1 (bits 0-7)
Set F1 := IN1 XOR eKD1mod(IN1)
Set F2 := IN2 XOR eKD2mod(IN2)
Set OUT1 := (bits 0..31 of F1) || (bits 32..63 of F2)
Set OUT2 := (bits 0..31 of F2) || (bits 32..63 of F1)
End procedure
MDC-2 MDC-2(n, text, KEY1, KEY2, MDC);
For i := 1, 2, ..., n do
Call MDC-1(KEY1, KEY2, T8<i>, T8<i>, OUT1, OUT2)
Set KEY1 := OUT1
Set KEY2 := OUT2
End do
Set output MDC := (KEY1 || KEY2)
End procedure
MDC-4 MDC-4(n, text, KEY1, KEY2, MDC);
For i := 1, 2, ..., n do
Call MDC-1(KEY1, KEY2, T8<i>, T8<i>, OUT1, OUT2)
Set KEY1int := OUT1
Set KEY2int := OUT2
Call MDC-1(KEY1int, KEY2int, KEY2, KEY1, OUT1, OUT2)
Set KEY1 := OUT1
Set KEY2 := OUT2
End do
Set output MDC := (KEY1 || KEY2)
End procedure
Notation:
eK(X) DES encryption of plaintext X using key K
|| Concatenation operation
XOR Exclusive-OR operation
:= Assignment operation
T8<1> First 8-byte block of text
T8<2> Second 8-byte block of text
KD1, KD2 64-bit quantities
IN1, IN2 64-bit quantities
OUT1, OUT2 64-bit quantities
n Number of 8-byte blocks
Ciphering methods
The Data Encryption Standard (DES) algorithm defines operations on 8-byte data strings. The DES
algorithm is used in many different processes within CCA:
v Encrypting and decrypting general data
v Triple-encrypting and triple-decrypting PIN blocks
v Triple-encrypting and triple-decrypting DES keys
v Triple-encrypting and triple-decrypting RSA private keys with several processes
v Deriving keys, hashing data, generating CVV values, and so forth
The Encipher and Decipher verbs describe how you can request encryption or decryption of application
data. See the following topic: General data-encryption processes on page 682 for a description of the two
standardized processes you can use.

In CCA, PIN blocks are encrypted with double-length keys. The PIN block is encrypted with the left-half
key, for which the result is decrypted with the right-half key and this result is encrypted with the left-half
key.
See DES key encryption and decryption processes on page 671, and Triple-DES ciphering algorithms
on page 685, which describe how CCA DES keys are enciphered.
General data-encryption processes

Although the fundamental concepts of enciphering and deciphering data are simple, different methods
exist to process data strings that are not a multiple of 8 bytes in length. Two widely used methods for
enciphering general data are defined in these standards:
v NIST SP 800-38A cipher block chaining (CBC), multiple of 8 bytes (no padding)
v ANS X9.23 CBC, with 1 - 8 bytes of padding
These methods also differ in how they define the initial chaining value (ICV).
This section describes how the Encipher and Decipher verbs implement these methods.
Single-DES and Triple-DES encryption algorithms for general data

Using the IBM 4765 and the IBM 4764, you can use the Triple-DES algorithm in addition to the classical
single-DES algorithm. In the subsequent descriptions of the CBC method and ANS X9.23 method, the
actions of the Encipher and Decipher verbs encompass both single-DES and Triple-DES algorithms. The
Triple-DES processes are depicted in Figure 42 where left key and right key refer to the two halves of a
double-length DES key.
Cleartext, 8 bytes Ciphertext, 8 bytes

Left key
Encipher Left key
Decipher

Right key
Decipher Right key
Encipher

Left key
Encipher Left key
Decipher

Ciphertext Cleartext
Figure 42. Triple-DES data encryption and decryption
NIST SP 800-38A CBC method (no padding)

The NIST SP 800-38A standard defines five modes of operation for ciphering. One of these confidentiality
modes, Cipher Block Chaining (CBC), defines the basic method for ciphering multiple 8-byte data strings.
Figure 43 on page 683 and Figure 44 on page 684 show CBC using the Encipher and Decipher verbs. A
plaintext data string that must be a multiple of 8 bytes is processed as a series of 8-byte blocks. The

ciphered result from processing an 8-byte block is exclusive-ORed with the next block of 8 input bytes.
The last 8-byte ciphered result is defined as an output chaining value (OCV). The security server stores
the OCV in bytes 0 - 7 of the chaining_vector variable.
An ICV is exclusive-ORed with the first block of 8 bytes. When you call the Encipher verb or the Decipher
verb, specify the INITIAL or CONTINUE keywords. If you specify the INITIAL keyword, the default, the
initialization vector from the verb parameter is exclusive-ORed with the first 8 bytes of data. If you specify
the CONTINUE keyword, the OCV identified by the chaining_vector parameter is exclusive-ORed with the
first 8 bytes of data.
Verb parameter

Plaintext from application program
Initialization
vector Data (1,8) Data (9,16) Data (N*87,N*8)

INITIAL
keyword

or
ICV
XOR
XOR
XOR

CONTINUE
keyword
Encipher Encipher Encipher

OCV

Data (1,8) Data (9,16) Data (N*87,N*8)

Ciphertext to application program

Chaining vector

Figure 43. Enciphering using the NIST SP 800-38A CBC method

Verb parameter

Ciphertext from application program
Initialization
vector Data (1,8) Data (9,16) Data (N*87,N*8)

OCV

Decipher Decipher Decipher
INITIAL
keyword

or
ICV
XOR
XOR
XOR

CONTINUE
keyword

Data (1,8) Data (9,16) Data (N*87,N*8)

Plaintext to application program

Chaining vector

Figure 44. Deciphering using the CBC method
ANS X9.23 CBC method (1 - 8 bytes of padding)

The ANS X9.23 standard defines an enhancement to the basic cipher block chaining (CBC) mode of NIST
SP 800-38A. This enhancement enables the system to process data with a length that is not an exact
multiple of 8 bytes. The ANS X9.23 method always appends from 1 - 8 bytes to the plaintext before
encipherment. The last appended byte is the count of the added bytes and is in the range of X'01' - X'08'.
The standard defines that any other added bytes, or pad characters, be random.
When the coprocessor enciphers the plaintext, the resulting ciphertext is always 1 - 8 bytes longer than
the plaintext. See Figure 45 on page 685. This is true even if the length of the plaintext is a multiple of
eight bytes. When the coprocessor deciphers the ciphertext, it uses the last byte of the deciphered data as
the number of bytes to remove from the end (pad bytes, if any, and count byte). The result is the original
plaintext. See Figure 46 on page 685.
The output chaining vector can be used as feedback with this method in the same way as with the NIST
SP 800-38A method.
The ANS X9.23 method requires the caller to supply an initialization vector, and it does not allow
specification of a pad character.
Note: The ANS X9.23 standard has been withdrawn, but the X9.23 padding method is retained in CCA for
compatibility with applications that rely on this method.

Verb parameter

Plaintext from application program
Initialization
vector Data (1,8) Data (N*87,N*8) Data Pad Count

XOR
XOR
XOR

Encipher Encipher Encipher

Data (1,8) Data (N*87,N*8) Last block

Ciphertext to application program
Figure 45. Enciphering using the ANS X9.23 method
Verb parameter

Ciphertext from application program
Initialization
vector Data (1,8) Data (N*87,N*8) Last block

Decipher Decipher Decipher

XOR
XOR
XOR

Data (1,8) Data (N*87,N*8) Data Pad Count

Plaintext to application program
Figure 46. Deciphering using the ANS X9.23 method
Triple-DES ciphering algorithms

A Triple-DES (TDES) algorithm is used to encrypt keys, PIN blocks, and general data. Several techniques
are employed:
TDES ECB
DES keys, when triple encrypted under a double-length DES key, are ciphered using an
encipher-decipher-encipher (EDE) scheme without feedback. See Figure 41 on page 673.

TDES CBC
Encryption of general data, and RSA section type X'08' CRT-format private keys and OPK keys,
employs the scheme depicted in Figure 47 and Figure 48 on page 687. This is often referred to as
outer CBC mode.
CCA supports double-length DES keys for Triple-DES data encryption using the Decipher and
Encipher verbs. The triple-length asymmetric master key is used to CBC encrypt CRT-format OPK
keys. (See also Table 100 on page 592.)
EDEx / DEDx
CCA employs EDEx processes for encrypting several of the RSA private key formats (section
types X'02', X'05', and X'06') and the OPK key in section type X'06'. The EDEx processes make
successive use of single-key DES CBC processes. EDE2, EDE3, and EDE5 processes have been
defined, based on the number of keys and initialization vectors used in the process. See Figure 49
on page 688 and Figure 50 on page 689. K1, K2, and K3 are true keys while K4 and K5 are
initialization vectors. See Figure 49 on page 688 and Figure 50 on page 689.
/
T164
T264
T364
Tn64

/

IV
XOR
XOR
XOR //
XOR

Ka
e Ka
e Ka
e Ka
e

Kb
d Kb
d Kb
d Kb
d

Kc
e Kc
e Kc
e Kc
e

/
S164
S264
S364
Sn64

/
For 2-key Triple-DES, Kc = Ka
Figure 47. Triple-DES CBC encryption process

/
S164
S264
S364
Sn64

/

Kc
d Kc
d Kc
d Kc
d

Kb
e Kb
e Kb
e Kb
e

Ka
d Ka
d Ka
d Ka
d

IV
XOR
XOR
XOR //
XOR

/
T164
T264
T364
Tn64

/
For 2-key Triple-DES, Kc = Ka
Figure 48. Triple-DES CBC decryption process

/
EDE2 EDE3 EDE5 T1<64> T2<64> T3<64> Tn<64>
/

0 0 K4 IVa
XOR
XOR
XOR //
XOR

K1 K1 K1 Ka
e Ka
e Ka
e Ka
e

K2 K2 K2 Kb
d Kb
d Kb
d Kb
d

0 0 0 IVb
XOR
XOR
XOR //
XOR

0 0 K5 IVc
XOR
XOR
XOR //
XOR

K1 K3 K3 Kc
e Kc
e Kc
e Kc
e

/
S1<64> S2<64> S3<64> Sn<64>
/
Figure 49. EDE algorithm

/
EDE2 EDE3 EDE5 S1<64> S2<64> S3<64> Sn<64>
/

K1 K3 K3 Kc
d Kc
d Kc
d Kc
d

0 0 K5 IVc
XOR
XOR
XOR //
XOR

0 0 0 IVb
XOR
XOR
XOR //
XOR

K2 K2 K2 Kb
e Kb
e Kb
e Kb
e

K1 K1 K1 Ka
d Ka
d Ka
d Ka
d

0 0 K4 IVa
XOR
XOR
XOR //
XOR

/
T1<64> T2<64> T3<64> Tn<64>
/
Figure 50. DED process
MAC calculation methods

Four variations of DES-based message authentication can be used by the MAC_Generate and
MAC_Verify verbs:
v ANS X9.9 Option 1
v ANS X9.19 Optional Procedure
v EMV post-padding of X'80'
v ISO 16609 Triple-DES MAC
| A keyed-hash MAC (HMAC) based message authentication can be used by the HMAC_Generate and
| HMAC_Verify verbs.
ANS X9.9 Option 1 MAC

The Financial Institution Message Authentication (Wholesale) standard (ANS X9.9:1986) defines a process
for the authentication of messages from originator to recipient. This process is called the message
authentication code (MAC) calculation method.5
5. The ANS X9.9 standard defines five authentication options. The MAC_Generate and MAC_Verify verbs implement Option 1, binary
data.

Figure 51 shows the MAC calculation for ANS X9.9 Option 1 (binary data). In this figure, KEY is a 64-bit
key, and T1 through Tn are 64-bit data blocks of text. If Tn is less than 64 bits long, binary zeros are
appended to the right of Tn. Data blocks T1...Tn are DES CBC-encrypted with all output discarded except
for the final output block, On.
Note: ANS X9.19 Basic Procedure and ISO/IEC 9797-1 MAC Algorithm 1 are the same as ANS X9.9
Option 1.
ANS X9.19 Optional Procedure MAC

The Financial Institution Message Authentication (Retail) standard ANS X9.19 Optional Procedure (same
as ISO/IEC 9797-1, MAC Algorithm 3) specifies additional processing of the 64-bit On MAC value. The
CCA X9.19OPT process employs a double-length DES key. After calculating the 64-bit MAC as above with
the left half of the double-length key, the result is decrypted using the right half of the double-length key.
This result is then encrypted with the left half of the double-length key. The resulting MAC value is
processed according to other specifications supplied to the verb call.
EMV MAC
| The EMV smart card standards define MAC generation and verification processes that are the same as
| ANS X9.9 Option 1 (same as ISO/IEC 9797-1 MAC Algorithm 1) and ANS X9.19 Optional Procedure
| (same as ISO/IEC 9797-1, MAC Algorithm 3), except for padding added to the end of the message.
| Append 1 byte of X'80' to the original message, then append from 0 - 7 additional bytes, as required, of
| X'00' to form an extended message, which is a multiple of 8 bytes in length.
Using X9.9 Option 1 and X9.19 Optional Procedure, the leftmost 32 bits (4 bytes) of On are taken as the
MAC. In the EMV standards, the MAC value is 4-8 bytes in length. CCA provides support for the leftmost
4, 6 and 8 bytes of MAC value.
Figure 51. MAC calculation method
ISO 16609 Triple-DES MAC

ISO 16609 defines a process for protecting the integrity of transmitted banking messages and for verifying
that a message has originated from an authorized source. This process is called the ISO 16609
CBC-mode Triple-DES (TDES) MAC method. The ISO 16609 CBC-mode Triple-DES MAC method

corresponds to ISO/IEC 9797-1 MAC Algorithm 1 using Triple-DES (ANS X9.52). ISO 16609 CBC-mode
Triple-DES identifies this method as one of the recommended ways to generate a MAC using symmetric
techniques.
The ISO 16609 CBC-mode Triple-DES MAC method uses a double-length DES key and operates on data
blocks that are a multiple of 8 bytes. If the last input data block is not a multiple of 8 bytes, binary zeros
are appended to the right of the block. A CBC-mode Triple-DES encryption operation is performed on the
data, with all output discarded except for the final output block.
The resulting MAC value is processed according to other specifications supplied to the verb call.
| Keyed-hash MAC (HMAC)

| The Keyed-Hash Message Authentication Code (HMAC) standard (FIPS PUB 198-1) describes a
| mechanism for message authentication using cryptographic hash functions. HMAC can be used with a
| hash function in combination with a shared secret key.
| To see how to compute a MAC over the data, see FIPS PUB 198-1 available at http://csrc.nist.gov/
| publications/fips/fips198-1/FIPS-198-1_final.pdf.
RSA key-pair generation

RSA key-pair generation is determined based on user input of the modulus bit length, public exponent, and
key type. The output is based on creating primes p and q in conformance with ANS X9.31 requirements as
follows:
v prime p bit length = ((modulus_bit_length +1)/2)
v prime q bit length = modulus_bit_length - p_bit_length
v p and q are randomly chosen prime numbers
v p>q
v By default, the Rabin-Miller Probabilistic Primality Test is iterated 7 times for each prime. This test
determines that a false prime is produced with probability no greater then 1/4c, where c is the number of
iterations. Refer to the ANS X9.31 standard and see the section entitled Miller-Rabin Probabilistic
Primality Test.
v Primes p and q are relatively prime with the public exponent.
v Primes p and q are different in at least one of the first 100 most significant bits, that is, |p-q| > 2(prime bit
length - 100). For example, when the modulus bit length is 1024, then both primes bit length are 512 bits
and the difference of the two primes is |p-q| > 2412.
An RSA key is generated by the IBM 4764 PCI-X and the IBM 4765 PCIe Cryptographic Coprocessors in
the following manner with respect to random numbers:
1. For each key generation, and for any size of key, the PKA manager seeds an internal FIPS-approved,
SHA-1 based psuedo random number generator (PRNG) with the first 24 bytes of information that it
receives from three successive calls to the random number generator (RNG) manager's PRNG
interface.
2. The RNG manager can supply a random number in two ways, but with the CCA Support Program only
one way is used, namely, the PRNG method. The PKA manager seeds an internal FIPS-approved,
SHA-1 based PRNG with 24 bytes obtained.
The RNG manager can respond to requests for random numbers from other processes with such
responses interspersed between responses to PKA manager requests. An RSA key is generated from
random information obtained from two cascaded SHA-1 PRNGs.
3. An RSA key is based on one or more 24-byte seeds from the RNG manager souce depending on the
dynamic mix of tasks running inside the coprocessor.

There exists a system RNG manager (ANS X9.31 compliant) that is used as the source for pseudo
random numbers. The PKA manager also has a PRNG that is DSA compliant for generating primes. The
PKA manager PRNG is re-seeded from the system RNG manager, for every new key pair generation,
which is for every generation of a public/private key pair.
Passphrase verification protocol

This section describes the process used to log a user on to the coprocessor.
Design criteria
The passphrase verification protocol is designed to meet the following criteria.
v The use of cryptographic algorithms is permitted in the client logon software, but there must be no
storage of any long-term cryptographic keys. This is because secure key storage is generally not
available in the client workstation.
v Replay attacks must not be feasible. This means that the logon request message must be protected so
that it cannot be captured by an adversary, and later replayed to gain access to the genuine user's
privileges.
v An attacker should not be able to guess the cleartext content of the logon request message.
v No special hardware should be required on the client workstation.
v The logon process must result in the establishment of a session key known only to the cryptographic
coprocessor and the client. This key is used on subsequent transactions to prove the identity of the
sender, and to secure transmitted data.
v The session key is generated in the coprocessor.
Description of the protocol

The protocol is comprised of the following steps:
1. The user provides the user ID (UID) and passphrase.
2. The passphrase is hashed in the client workstation, using SHA-1 algorithm. The resulting hash value
is used to construct a logon key, denoted KL.
KL is a triple-length DES key. The three components of the triple-length key are denoted K1L, K2L,
and K3L. K1L is comprised of the first 8 bytes of the hash, K2L is comprised of the second 8 bytes,
and K3L is comprised of the last 4 bytes, concatenated with 4 bytes of X'00'. Figure 52 shows an
example to clarify this.
Passphrase is "This is my passphrase!"
SHA-1 hash of the passphrase is hex 42BED1CD 1DB68934 6319E315 F3C096A8 B2E08DB2

K1 is 42BED1CD 1DB68934
K2 is 6319E315 F3C096A8
K3 is B2E08DB2 00000000
Figure 52. Example of logon key computation
3. The client workstation generates a random number, RN (64 bits).
Note: The random-number RN is not used inside the Cryptographic Coprocessor. It is only included
in the protocol to guarantee that the cleartext of the logon request is different every time.
4. The client workstation sends a logon request to the Cryptographic Coprocessor, including the
following information:
v { UID, eKL(RN, UID, timestamp) }

Encryption uses DES EDE36 mode, performed by the software in the client workstation. The
timestamp includes both the time and the date, in UTC. It is used to prevent replay of the logon
request. The timestamp is formed from the concatenation of binary encoded values of the year,
month, day, hour, minute, and second. Each value is held in 1 byte except for the year which is held
in a 2-byte value.
5. The Cryptographic Coprocessor retrieves the user profile, which it has in secure coprocessor
memory. It uses the received user ID value to locate the corresponding profile. If the user's profile is
not found, the logon request is rejected.
6. The coprocessor reads the hash of the user's passphrase from the profile, obtaining KL.
7. The coprocessor uses KL to decrypt the user's logon data, recovering the UID, timestamp, and RN. It
compares the recovered UID with the cleartext UID it received, and abnormally ends if the two are
not equal. Inequality is an indication that the passphrase was incorrect, or that someone tried to
splice another user's captured logon data into their own request.
8. The coprocessor verifies that the recovered timestamp is within 5 minutes of the current time,
according to the coprocessor's secure clock. If the timestamp falls outside this window, it indicates a
probable replay attack, and the logon request is rejected.
9. If everything in the preceding steps was acceptable, the user is logged on to the coprocessor. The
coprocessor generates a 192-bit session key, KS, and returns this key to the client in the form of
eKL(KS).
10. In a secure internal table, the coprocessor stores the user ID, the value of KS, and the user's role
identifier, which is extracted from the profile. This information is used on later requests to verify that
the user is logged on, and to find the role defining the user's privileges. The table entry is destroyed
when the user logs off the system.
11. The client workstation or server software (security API) saves KS for use in validating subsequent verb
calls. The security API code in the client and the coprocessor compute the industry-standard HMAC
keyed-hash algorithm over sensitive portions of subsequent verb calls and responses. An HMAC is
computed using KS as the key.
Master-key-splitting algorithm
This section describes the mathematical and cryptographic basis for the m-of-n key shares scheme.
The key splitting is based on Shamir's secret sharing algorithm:
The value to be shared is the master key, Km, which is a Triple-DES key and 168 bits long. Let P be the
first prime number larger than 2168. All operations are carried out modulo P.
Shamir's secret sharing allows the sharing of Km among n trustees in a way that no set of t or less of
trustees has any information about Km, while t+1 trustees can reconstruct Km.
Sharing phase:
1. Randomly choose a_t,...,a_1 in [0..P-1]
2. Consider the polynomial f(x) = a_t x t + ... + a_1 x + a_0, where a_0=Km.
Compute mk_i = f(i) mod P for all i=1,...n
3. Proceed to distribute the values mk_i as described above.
Reconstruction phase:
After generating the set of authentic values proceed as follows:
6. For a description of the EDE3 encryption process, see Figure 49 on page 688.

1. Take t+1 values and interpolate the polynomial f(x) of degree t. Pass through these values using
Lagrange interpolation. This defines a polynomial f(x) such that: f(i)=mk_i, and further more f(0) = MK.
Use the mathematical formula to reconstruct the free term of the polynomial f(x). Let k_1,...,k_{t+1} be
the indices of the mk_i's used for reconstruction. Then
a_0=SUM_j( b_{k_j} PROD_h (x_{k_h} / (x_{k_h}- x_{k_j}))) mod P
2. Install key Km = a_0 = f(0) mod P.
Formatting hashes and keys in public-key cryptography

The Digital_Signature_Generate and Digital_Signature_Verify verbs can use several methods for
formatting a hash value, and in some cases a descriptor for the hashing method, into a bit-string to be
processed by the cryptographic algorithm. This section discusses the ANS X9.31 and PKCS #1 methods.
The ISO/IEC 9796-1 method can be found in the ISO/IEC standard. The method used for the ECDSA
algorithm can be found in the ANS X9.62 standard.
This section also describes the PKCS #1 methods for placing a key in a bit string for RSA ciphering as
part of a key exchange.
ANS X9.31 hash format

With ANS X9.31, the string that is processed by the RSA algorithm is formatted by the concatenation of a
header, padding, the hash value and a trailer, from the most significant bit to the least significant bit, so
that the resulting string is the same length as the modulus of the key. For CCA, the modulus length must
be a multiple of 8 bits.
v The header consists of the value X'6B'
v The padding consists of the value X'BB', repeated as many times as required, and ended with X'BA'
v The hash value follows the padding
v The trailer consists of a hashing-mechanism specifier and final byte. The hashing-mechanism specifier
is defined as one of the following values:
X'31' RIPEMD-160
X'33' SHA-1
X'34' SHA-256 (Release 3.30.05 or later)
X'35' SHA-512 (Release 4.0 or later)
X'36' SHA-384 (Release 4.0 or later)
The final byte is X'CC'.
PKCS #1 hash formats

Versions 2.0 and 2.1 of the RSA PKCS #1 standard7 define different methods for formatting keys and hash
values prior to RSA encryption of the resulting data structures. PKCS #1 v1.5 defined block types 00, 01,
and 02, but that terminology was subsequently dropped.
The CCA products described in this document implement these processes using the terminology of the
Version 1.5, Version 2.0, and Version 2.1 standards:
v For formatting keys for secured transport:
| Encryption/decryption scheme RSAES-OAEP is the preferred method for key encipherment8 when
| exchanging data keys between systems. In CCA, keywords PKCSOAEP (Version 2.0) and
7. PKCS standards can be retrieved from http://www.rsasecurity.com/rsalabs/pkcs.

8. The PKA92 method and the method incorporated into the SET standard are other examples of the OAEP technique. The OAEP
technique is attributed to Bellare and Rogaway and stands for Optimal Asymmetric Encryption Padding.

| PKOAEP2 (Version 2.1) are used to invoke this formatting technique. The P encoding parameter
| described in the standard is not used and its length is set to zero.
| Encryption/decryption scheme RSAES-PKCS1-v1_5 is an older method for formatting keys. It is
| included for compatibility with existing applications. In CCA, keyword PKCS-1.2 is used to specify
| this formatting technique.
v For formatting hash values for digital signatures:
Signature scheme RSASSA-PKCS1-v1_5 is the name for the block-type 01 format. In CCA, keyword
PKCS-1.1 is used to specify this formatting technique.
For the block-type 00 format, in CCA, keyword PKCS-1.0 is used to specify this formatting
technique.
Using the terminology from the older PKCS #1 v1.5 standard, block types 00 and 01 are used to format a
hash, and block-type 02 is used to format a DES key. The blocks consist of the following (\ means
concatenation):
X'00' \ BT \ PS \ X'00' \ D
where:
BT Is the block-type, X'00', X'01', or X'02'.
PS Is the padding of as many bytes as required to make the block the same length as the modulus of
the RSA key. Pad bytes are X'00' for block-type 00, X'FF' for block-type 01, and random and nonzero
for block-type 02. The length of PS must be at least 8 bytes.
D Is the key, or the concatenation of the ASN.1 BER-encoded hash identifier and the hash value
| You can create the ASN.1 BER encoding of an MD5, SHA-1, or SHA-256 value by prepending these
strings to the 16-byte or 20-byte hash values, respectively:
MD5 X'3020300C 06082A86 4886F70D 02050500 0410'
SHA-1 X'30213009 06052B0E 03021A05 000414'
| SHA-256 X'3031300D 06096086 48016503 04020105 000420'

Appendix E. Financial system verbs calculation methods and
data formats
This section describes the following:
v PIN calculation methods
v PIN-block formats on page 700
v Derived unique-key-per-transaction calculation method on page 704
v CVV and CVC card-verification method on page 706
v Visa and EMV-related smart card formats and processes on page 707
The PIN-calculation methods are independent from PIN-block formats. A PIN can be calculated by any
method and generally used in any PIN-block format. For example, a PIN can be calculated by the IBM
3624 PIN-calculation method and used either in the IBM 3624 PIN-block format or in another PIN-block
format.
Table 167. Financial PIN-calculation methods, data formats, and other items
Item Page
IBM 3624 PIN-calculation method 698
IBM 3624 PIN-offset calculation method 698
Netherlands PIN-1 calculation method 699
IBM German Bank Pool Institution PIN-calculation method 699
Visa PIN-validation value (PVV) PIN-calculation method 700
InterBank PIN-calculation method 700
3624 PIN-block format 701
ISO-0 PIN-block format 701
ISO-3 PIN-block format (Release 3.30 or later) 703
UKPT calculation methods (ANS X9.24) 704
CVV, CVC (Visa, MasterCard) 706
Visa and EMV formats and processes 707
PIN calculation methods

The financial PIN verbs support some or all of these PIN calculation methods, see Table 51 on page 430:
v IBM 3624 PIN (IBM-PIN)
v IBM 3624 PIN-offset (IBM-PINO)
v Netherlands PIN-1 (NL-PIN-1)
v IBM German Bank Pool Institution PIN (GBP-PIN)
v Visa PIN-validation value (VISA-PVV)
v InterBank PIN (INBK-PIN)
In the description of the financial PIN verbs, these terms are employed:
A-PIN The quantity derived from a function of the account number, PIN-generating key (PINGEN or
PINVER), and other inputs such as a decimalization table.
697
C-PIN The quantity that a customer should use to identify himself; in general, this can be a
customer-selected or institution-assigned quantity.
O-PIN A quantity, sometimes called an offset, that relates the A-PIN to the C-PIN as permitted by certain
methods.
T-PIN The trial PIN presented for verification.
IBM 3624 PIN-calculation method

The IBM 3624 PIN-calculation method calculates a PIN that is from 4 16 digits in length.
The IBM 3624 PIN-calculation method consists of the following steps to create the A-PIN:
1. Encrypt the hexadecimal validation data with a key that has a control vector that specifies the PINGEN
(or PINVER) key type to produce a 64-bit quantity.
2. Convert the character format decimalization table to an equivalent array of sixteen 4-bit hexadecimal
digits, and use the decimalization table to convert the hexadecimal digits (X'0' to X'F') of the encrypted
validation data to decimal digits (X'0' to X'9'). Call this result newpin.
Let newpin(i), decimalization_table(i), and encrypted_validation_data(i) each represent the (i)th
hexadecimal digit in each quantity.
The digits of newpin are obtained by the following procedure:
For i = 1 to 16 do:
j := encrypted_validation_data(i)
newpin(i) := decimalization_table(j)
end do
3. Select the n leftmost decimal digits of newpin, where n is the PIN length. The result is an n-digit
calculated A-PIN. The PIN must be from 4 16 digits in length.
Example:
Encrypted validation data = E5C1BD67B66AE7C6
Decimalization table index = 0123456789ABCDEF
Decimalization table = 8351296477461538
Newpin = 3913656466643416
PIN length = 6
Calculated A-PIN = 391365 (leftmost 6 digits of newpin)
IBM 3624 PIN-offset calculation method

The IBM 3624 PIN-offset calculation method is the same as the IBM 3624 PIN-calculation method except
that a step is added after the A-PIN is calculated to calculate or use an offset, O-PIN:
v To calculate an O-PIN, the additional step subtracts (digit-by-digit, modulo 10, with no carry) the
calculated A-PIN from the customer-selected C-PIN.
The result is an O-PIN (offset) of n decimal digits, where n is the PIN length and must be in the range
from 4 16. The PIN_check_length parameter specifies n as the low-order (rightmost) digits of the
n-digit PIN offset. The O-PIN (offset) is not encrypted.
v To use an offset to verify a trial PIN, the additional step adds (digit-by-digit, modulo 10, with no carry)
the offset to the calculated A-PIN. The result is compared to the customer-entered trial PIN (T-PIN).
Notes:
1. The digit-wise subtraction is defined only for digits in the range from X'0' to X'9'. Any other value is
not valid and causes processing to fail.
2. The length of the offset depends on the length of the PIN and must be less than or equal to the length
of the PIN. The financial institution that issues the magnetic-stripe card determines the length of the
PIN offset, which you specify with the PIN_check_length parameter.
3. When the length of the PIN offset is less than the length of the calculated PIN, the subtraction or
addition begins with the low order PIN digit.

Netherlands PIN-1 calculation method
The Netherlands PIN-1 (NL-PIN-1) calculation method calculates a PIN that is 4 digits in length.
The method consists of the following steps to create the A-PIN:

1. Encrypt the hexadecimal validation data with a key that has a control vector that specifies the PINGEN
(or PINVER) key type to produce a 64-bit quantity.
digits, and use the decimalization table to convert the third through sixth hexadecimal digits (X'0' to
X'F') of the encrypted validation data to decimal digits (X'0' to X'9'). Call this result newpin.
Note: The application must specify a decimalization table of 0, 1, ..., 9, 0, ..., 5.

Let A-PIN(i), decimalization_table(i), and encrypted_validation_data(i) each represent the (i)th
hexadecimal digit in each quantity.
The digits of A-PIN are obtained by the following procedure:
For i = 3 to 6 do:
A-PIN(i-2) := decimalization_table(j)
end do
3. The O-PIN offset, also a 4 digit quantity, when added digit-wise modulo 10 to the A-PIN results in the
C-PIN, customer-used-PIN value.
Example:
Encrypted validation data = 8325A637B66EA7A8
Decimalization table index = 0123456789ABCEDF
A-PIN = 2506
O-PIN = 9957
C-PIN, Customer PIN = 1453
IBM German Bank Pool Institution PIN-calculation method

The IBM German Bank Pool Institution PIN-calculation method calculates an institution PIN that is 4 digits
in length.
The German Bank Pool Institution PIN-calculation method consists of the following steps:
1. Encrypt the hexadecimal validation data with an institution key that has a control vector that specifies
the PINGEN (or PINVER) key type to get a 64-bit quantity.
digits, and use the decimalization table to convert the first 6 hexadecimal digits (X'0' to X'F') of the
encrypted validation data to decimal digits (X'0' to X'9'). Call this result newpin.
The digits of newpin are obtained by the following procedure:
For i = 1 to 6 do:
newpin(i) := decimalization_table(j)
end do
3. Select the 4 rightmost digits of newpin. The result is a 4-digit intermediate PIN.
4. If the first digit of the intermediate PIN is 0, assign 1 to the first digit of the institution PIN, and assign
the remaining 3 digits of the intermediate PIN to the institution PIN.
If the first digit of the intermediate PIN is not 0, assign the value of the intermediate PIN to the
institution PIN.
The PIN is not encrypted.
Example:
Appendix E. Financial system verbs calculation methods and data formats 699
Encrypted validation data = E5A4FD67B66AE7C6
Decimalization table index = 0123456789ABCDEF
Newpin = 450453
Intermediate PIN = 0453 (4 rightmost digits of newpin)
Institution PIN = 1453 (first digit is changed to 1
because the intermediate PIN had a
first digit of 0)
Visa PIN-validation value PIN-calculation method

The Visa PIN-validation value (PVV) PIN-calculation method calculates a Visa PVV that is 4 digits in
length.
The PVV calculation method consists of the following steps:

1. Let X denote the transaction_security_parameter element. This parameter is the result of
concatenating the 12-numeric-digit generating data (a portion of the account number) with the
4-numeric-digit customer-entered PIN. (C-PIN when calculating the PVV, or T-PIN when validating a
transaction.)
2. Encrypt X with the double-length key that has a control vector that specifies the PINGEN (or PINVER)
key type to get 16 hexadecimal digits (64 bits).
3. Perform decimalization on the result of the previous step by scanning the 16 hexadecimal digits from
left to right, skipping any digit greater than X'9', until 4 decimal digits (digits that have values from
X'0' to X'9') are found.
If all digits are scanned but 4 decimal digits are not found, repeat the scanning process, skipping all
digits that are X'9' or less and selecting the digits that are greater than X'9'. Subtract 10 (X'A') from
each digit selected in this scan.
4. Concatenate and use the resulting digits for the PVV. The PVV is not encrypted.
InterBank PIN-calculation method

The InterBank PIN-calculation method consists of the following steps:
1. Let X denote the transaction_security_parameter element converted to an array of sixteen 4-bit
numeric values. This parameter consists of (in the following sequence) the 11 rightmost digits of the
customer PAN (excluding the check digit), a constant of 6, a 1-digit key indicator, and a 3-digit
validation field.
2. Encrypt X with the double-length PINGEN (or PINVER) key to get 16 hexadecimal digits (64 bits).
3. Perform decimalization on the result of the previous step by scanning the 16 hexadecimal digits from
left to right, skipping any digit greater than X'9', until 4 decimal digits (for example, digits that have
values from X'0' to X'9') are found.
If all digits are scanned but 4 decimal digits are not found, repeat the scanning process, skipping all
digits that are X'9' or less and selecting the digits that are greater than X'9'. Subtract 10 (X'A') from
each digit selected in this scan.
If the 4 digits that were found are all zeros, replace the 4 digits with 0100.
4. Concatenate and use the resulting digits for the InterBank PIN. The 4-digit PIN consists of the decimal
digits in the sequence in which they are found. The PIN is not encrypted.
PIN-block formats
The PIN verbs support one or more of the following PIN-block formats:
v IBM 3624
v ISO-0 (same as ANS X9.8, VISA-1, and ECI-1).
v ISO-1 (same as the ECI-4)
v ISO-2

IBM 3624 PIN-block format

The IBM 3624 PIN-block format supports a PIN from 1 - 16 digits in length. A PIN that is longer than 16
digits is truncated on the right.
The following is the 3624 PIN-block format:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

P P/XP/XP/XP/XP/XP/XP/XP/XP/XP/XP/XP/XP/XP/XP/X

Figure 53. 3624 PIN-block format
where:
P Is a PIN digit, which is a 4-bit value from X'0' - X'9'. The values of the PIN digits are independent.
P/X Is a PIN digit or a pad value. A PIN digit has a 4-bit value from X'0' - X'9'. A pad value has a 4-bit
value from X'0' - X'F' and must be different from any PIN digit. The number of pad values for this
format is in the range from 0 - 15, and all the pad values must have the same value.
Example:
PIN = 0123456, Pad = X'E'
PIN block = X'0123456EEEEEEEEE'
ISO-0 PIN-block format

An ISO-0 PIN-block format is the same as the ANS X9.8, VISA-1, and ECI-1 PIN-block formats. The ISO-0
PIN-block format supports a PIN from 4 - 12 digits in length. A PIN that is longer than 12 digits is truncated
on the right.
The following are the formats of the intermediate PIN-block, the PAN block, and the ISO-0 PIN-block:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

0 L P P P P P/FP/FP/FP/FP/FP/FP/FP/F F F

Intermediate PIN-Block = IPB

0 0 0 0 PANPANPANPANPANPANPANPANPANPANPANPAN

PAN Block

P P P/FP/FP/FP/FP/FP/FP/FP/F F F
0 L P P XORXORXORXORXORXORXORXORXORXORXORXOR
PANPANPANPANPANPANPANPANPANPANPANPAN

PIN Block = IPB XOR PAN Block
Figure 54. ISO-0 PIN-block format
where:
0 Is the value X'0' for ISO-0.
L Is the length of the PIN, which is a 4-bit value from X'4' - X'C'.
P/F Is a PIN digit or pad value. A PIN digit has a 4-bit value from X'0' - X'9'. A pad value has a 4-bit
value of X'F'. The number of pad values in the intermediate PIN block (IPB) is from 2 - 10.
F Is the value X'F' for the pad value.
PAN Is twelve 4-bit digits that represent the rightmost 12 digits of the primary account-number
(excluding the check digit).
Each PAN digit has a value from X'0' - X'9'.
The PIN block is the result of exclusive-ORing the 64-bit IPB with the 64-bit PAN block.
Example:
L = 6, PIN = 123456, Personal Account Number = 111222333444555
06123456FFFFFFFF : IPB
0000222333444555 : PAN block for ISO-0 (ANS X9.8, VISA-1, ECI-1) PIN-block format
06121675CCBBBAAA : PIN block for ISO-0 (ANS X9.8, VISA-1, ECI-1) PIN-block format

The ISO-1 PIN-block format is equivalent to an ECI-4 PIN-block format. The ISO-1 PIN-block format
supports a PIN from 4 - 12 digits in length. A PIN that is longer than 12 digits is truncated on the right.
The following is the ISO-1 PIN-block format:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

1 L P P P P P/RP/RP/RP/RP/RP/RP/RP/R R R

where:
R Is a random digit, which is a value from X'0' - X'F'. Typically, this should be used for predetermined
transaction unique data such as a sequence number.
P/R Is a PIN digit or a random digit, depending on the value of PIN length L. The number of random
digits is in the range from 2 - 10, and each random digit in a PIN-block format can be different.
Example:
L = 6, PIN = 123456
PIN block = X'161234566ABCFDE1', where X'6', X'A', X'B', X'C', X'F',
X'D', X'E', and X'1' are the random fillers

The ISO-2 PIN-block format supports a PIN from 4 - 12 digits in length. A PIN that is longer than 12 digits
is truncated on the right.
The following is the ISO-2 PIN-block format:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

2 L P P P P P/FP/FP/FP/FP/FP/FP/FP/F F F


where:
F Is a fill digit valued to X'F'.
P/F Is a PIN digit or a fill digit.
Example:
L = 6, PIN = 123456
PIN block = X'26123456FFFFFFFF'

An ISO-3 PIN-block format is the same as the ANS X9.8, VISA-1, and ECI-1 PIN-block formats in length
(4 - 12 digits). A PIN that is longer than 12 digits is truncated on the right.
The following are the formats of the intermediate PIN-block, the PAN block, and the ISO-3 PIN-block:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

3 L P P P P P/RP/RP/RP/RP/RP/RP/RP/R R R

Intermediate PIN-Block = IPB

0 0 0 0 PANPANPANPANPANPANPANPANPANPANPANPAN

PAN Block

P P P/RP/RP/RP/RP/RP/RP/RP/R R R
3 L P P XORXORXORXORXORXORXORXORXORXORXORXOR
PANPANPANPANPANPANPANPANPANPANPANPAN

PIN Block = IPB XOR PAN Block
where:
P/R Is a PIN digit or pad value. A PIN digit has a 4-bit value from X'0' - X'9'. A pad value has a random
4-bit value of X'A' - X'F'. The number of pad values in the intermediate PIN block (IPB) is from 2 -
10.
R Is a random digit, which is a value from X'A' - X'F'.
PAN Is twelve 4-bit digits that represent the rightmost 12 digits of the primary account-number
(excluding the check digit).
Each PAN digit has a value from X'0' - X'9'.
The PIN block is the result of exclusive-ORing the 64-bit IPB with the 64-bit PAN block.
Example:
L = 6, PIN = 123456, Personal Account Number = 111222333444555
36123456AFBECDDC : IPB (where XAFBECDDC are random digits)
0000222333444555 : PAN block for ISO-3 (ANS X9.8, VISA-1, ECI-1) PIN-block format
361216759CFA8889 : PIN block for ISO-3 (ANS X9.8, VISA-1, ECI-1) PIN-block format
Derived unique-key-per-transaction calculation method

This section describes the calculation method for deriving the unique-key-per-transaction (UKPT) key
according to ANS X9.24 and performing the special encryption and special decryption processes.9
Deriving an ANS X9.24 unique-key-per-transaction key

To determine the current-transaction encrypting key used by a terminal which is encrypting PIN-blocks
under the ANS X9.24 standard, the ANS X9.24 algorithm uses a derivation key and the current-key serial
number (CKSN) as inputs.
v The derivation key must be a double-length KEYGENKY key-type with the UKPT control vector bit set
on. The right half of the derivation key cannot be the same as the left half of the derivation key.
v The initial key serial number is a 59-bit value that contains terminal identification information that is
unique among the set of terminals initialized under a given derivation key.
v The encryption counter is a 21-bit counter value. The value in the counter is set to 0 when the terminal
is initialized. The counter increments each time the terminal performs a PIN-block encryption. The
counter increments such that a maximum of 10 bits can be set on; the counter can record 1 000 000
encryptions.
v The CKSN is the concatenation of the initial key serial number and the encryption counter. This
concatenation is an 80-bit (10-byte) value.
The calculation method consists of the following steps:

1. Calculate the initial encrypting key. To calculate the initial encrypting key, do the following:
a. Move the leftmost 8 bytes of the CKSN to a work area (Ca).
b. Perform an AND operation with the last byte of Ca and X'EO'. This operation clears the high-order
bits of the encryption counter. The value that Ca now contains is the initial serial number that was
loaded when the PIN keypad was initialized.
c. Encrypt Ca, using the left half of the derivation key; name the result Cb.
d. Decrypt Cb, using the right half of the derivation key; name the result Cc.
e. Encrypt Cc, using the left half of the derivation key; name the result Cd. Cd is the initial PIN
encrypting key that was loaded when the terminal was initialized.
f. Rename Cd to be Ka, the initial PIN encrypting key.
2. Calculate the current encrypting key. To calculate the current encrypting key, do the following:
a. Move the rightmost 8 bytes of the CKSN to a work area (Wa).
b. Move the rightmost 3 bytes of Wa to another work area (Ca).
c. Perform an AND operation with the rightmost 3 bytes of Wa with X'E00000'. This operation clears
the encryption counter from Wa.
d. Perform an AND operation with Ca and X'1FFFFF'. This operation clears the low-order bits of the
initial serial number from the encryption counter.
e. Initialize a 3-byte area to X'100000'; name the result Sa.
f. Initialize a 1-byte counter to X'00'; name the result Ba.
g. Test each bit of the encryption counter, looking for B'1' bits by doing the following loop:
v When a B'1' bit is found, it ORs this bit into the initial serial number. It then special encrypts the
result with Ka.
9. This material is adapted from the Visa Point-of-Sale Equipment Requirements: PIN Processing and Data Authentication publication.

v The result of this special encryption is the new Ka.
v When all B'1' bits are processed, a variant of the value in Ka becomes the current encrypting
key.
Use the following procedure to do this loop:
DO i=1 to 21
a. IF (Ca AND Sa) is not equal to 0 THEN DO
1) ADD 1 to Ba
2) IF Ba > 10 THEN exit algorithm with an error
indicating too many B'1' bits were set in the encryption
counter
3) OR Sa into the rightmost 3 bytes of Wa;
store the result in Ta
4) XOR Ta and Ka; store the result in Tb
5) Encrypt Tb with Ka; store the result in Tc
6) XOR Tc with Ka; store the result in Ka
b. END IF
c. Shift Sa one bit to the right.
Fill in on the left with a B'0' bit.
END DO
The value in Ka is the current encrypting key.
Note: The CCA implementation does not adjust key parity on any of the bytes of the derived
encrypting key before encrypting them under its master key. Parity adjustment is not done
because the key value is used in two XOR operations during the special decrypt process of
recovering the clear PIN-block.
The following is an example of calculating the initial PIN encrypting key:

Derivation key = X'5152 5457 585B 5D5E 6162 6467 686B 6D6E'
Current key serial number = X'0123 4567 89AB CDF0 0001'
Ca = X'0123 4567 89AB CDE0'

Cb = X'6497 E2F4 C59D 952E'
Cc = X'0163 CE85 359F F599'
Initial PIN encrypting key = Ka1 = Cd = X'21EE 7C08 DBE8 20AB'
The following is an example of calculating the current PIN encrypting key:

Wa = X'4567 89AB CDE0 0000'
Ca = X'10001'
Sa1 = X'100000'
Ta1 = X'4567 89AB CDF0 0000'

Tb1 = X'6489 F5A3 1618 20AB'
Tc1 = X'F9AC C638 1939 44BC'
Ka2 .= X'D842 BA30 C2D1 6417'
..
Sa20 = X'000001'
Ta20 = X'4567 89AB CDF0 0001'
Tb20 = X'9D25 339B 0F21 6416'
Tc20 = X'BF49 836E AE2A 042A'
Ka20 = X'670B 395E 6CFB 603D'
Current PIN encrypting key = X'670B 395E 6CFB 60C2'
Performing the special encryption and special decryption processes

The special encryption process consists of the following steps:
1. Name the derived unique key for the current transaction Ku.
2. Name the clear PIN-block that was built from the user-entered PIN Pc.
3. Perform an XOR operation with the rightmost byte of Ku and X'FF' to produce a variant of the key;
name the result Kuv.
4. Perform an XOR operation with Kuv and Pc; store the result in T1.
5. Encrypt T1 with Kuv; store the result in T2.
6. Perform an XOR operation with Kuv; store the result in Pe.
The value in Pe is the encrypted PIN-block that the POS terminal sends.
The special decryption process consists of the previous steps, but in reverse.
The following is an example of the special encryption process:

Current encrypting key = Ku = X'670B 395E 6CFB 603D'
User-entered PIN = 1234
User's primary account-number = X'4012 3456 7890'
Clear PIN-block (unformatted) = X'0412 34FF FFFF FFFF'
Primary account-number (formatted) = X'0000 4012 3456 7890'
Clear PIN-block (ANS format) = Pc = X'0412 74ED CBA9 876F'
Variant of PIN encrypting key = Kuv = X'670B 395E 6CFB 60C2'
T1 = X'6319 4DB3 A752 E7AD'

T2 = X'5145 3CA3 E474 2148'
Pe = X'364E 05FD 888F 418A'
CVV and CVC card-verification method

Figure 58 on page 70710 shows the method used to generate a Visa card-verification value (CVV) and a
MasterCard card-verification code (CVC) for track 2. Each (decimal) digit is represented as a 4-bit, binary
value and packed two digits per byte.
10. Adapted from VisaNet Electronic Value Exchange Standards Manual, pages AA-8 and AA-9.

PAN Exp Date Service Code 0 pad
13, 16, 19 digits 4 digits 3 digits Pad to 16 bytes

0 15

Divide into two 8-byte fields
Digits are represented
in 4-bit groups, 2
groups per byte.
Left Right

Key A Encipher

XOR

Key A Encipher

Key B Decipher

Key A Encipher

Decimalize Result
1) Select only 0-9 left to right
2) Left align result of 1 in field
3) Select only A-F left to right
4) Subtract 10 from each in 3
5) Concatenate to result from 2
6) CVV is the left 1 to 5 digits.

Figure 58. CVV track 2 algorithm
At the CCA API, the CVV_Generate and CVV_Verify verbs require two operational key identifiers, key-A
and key-B, as defined in the CVV method. The identifiers can be key labels or internal key-tokens.
The key-A and key-B key pair can include the following key types:
1. Both keys can be DATA keys.
2. Both keys can be MAC-class keys with the ANY subtype extension.
3. Both keys can be MAC-class keys with the KEY-A and KEY-B subtype extensions as appropriate.
The CVV_Generate verb requires the control-vector bit 20 to be set to B'1'. The CVV_Verify verb requires
the control-vector bit 21 to be set to B'1'.
Visa and EMV-related smart card formats and processes

The VISA and EMV specifications for performing secure messaging with an EMV compliant smart card are
covered in these documents:
Book 2, Annex A1.3, describes how a smart-card, card-specific authentication code is derived from a
card-issuer-supplied encryption key (ENC-MDK). The Integrated Circuit Card Specification (VIS) 1.4.0
Corrections indicates that the key used should be an authentication key (MAC-MDK).
Book 2, Annex A1.3 describes how a smart-card, card-specific session key is derived from a
card-issuer-supplied PIN-block-encryption key (ENC-MDK). The encryption key is derived using a
tree-based-derivation technique. IBM CCA offers two variations of the tree-based technique (TDESEMV2
and TDESEMV4), and a third technique CCA designates TDES-XOR.
In addition, Book 2 describes construction of the PIN block sent to an EMV card to initialize or update the
user's PIN.
Visa Integrated Circuit Card Specification Manual, Version 1.4.0, Appendix B.4, contains a description of
the session-key derivation technique CCA designates TDES-XOR.
Augmented by the above-mentioned documentation, the relevant processes are described in these
sections:
v Derivation of the smart-card-specific authentication code
v Constructing the PIN-block for transporting an EMV smart-card PIN
v Derivation of the CCA TDES-XOR session key
v Derivation of the EMV TDESEMVn tree-based session-key
v PIN-block self-encryption
Deriving the smart-card-specific authentication code

To ensure that an original or replacement PIN is received from an authorized source, the EMV
PIN-transport PIN block incorporates an authentication code. The authentication code is the rightmost four
bytes resulting from the ECB-mode Triple-DES encryption of (the first) eight bytes of card-specific data
(that is, the rightmost four bytes of the Unique DES Key A).
Constructing the PIN-block for transporting an EMV smart-card PIN

The PIN block is used to transport a new PIN value. The PIN block also contains an authentication code,
and optionally the current PIN value, enabling the smart card to further ensure receipt of a valid PIN
value. To enable incorporation of the PIN block into the a message for an EMV smart card, the PIN block
is padded to 16 bytes prior to encryption.
PINs of length 4 - 12 digits are supported.
PIN-block construction:
1. Form three 8-byte, 16-digit blocks, block-1, block-2, and block-3, and set all digits to X'0'.
2. Replace the rightmost four bytes of block-1 with the authentication code described in the previous
section.
3. Set the second digit of block-2 to the length of the new PIN (4 to 12), followed by the new PIN, and
padded to the right with X'F'.
4. Include any current PIN by placing it into the leftmost digits of block-3.
5. Exclusive-OR block-1, block-2, and block-3 to form the 8-byte PIN block.
6. Pad the PIN block with other portions of the message for the smart card:
v Prepend X'08' (the length of the PIN block)
v Append X'80', followed by 6 bytes of X'00'
The resulting message is ECB-mode triple-encrypted with an appropriate session key.
Deriving the CCA TDES-XOR session key

In the Diversified_Key_Generate and PIN_Change/Unblock verbs, the TDES-XOR process first derives a
smart-card-specific intermediate key from the issuer-supplied ENC-MDK key and card-specific data. (This

intermediate key is also used in the TDESEMV2 and TDESEMV4 processes. See the next section.) The
intermediate key is then modified using the application transaction counter (ATC) value supplied by the
smart card.
The double-length session-key creation steps:

1. Obtain the left-half of an intermediate key by ECB-mode Triple-DES encrypting the (first) eight bytes of
card specific data using the issuer-supplied ENC-MDK key.
2. Again using the ENC-MDK key, obtain the right-half of the intermediate key by ECB-mode Triple-DES
encrypting:
v The second 8 bytes of card-specific derivation data when 16 bytes have been supplied, else
v The exclusive-OR of the supplied 8 bytes of derivation data with X'FFFFFFFF FFFFFFFF'.
3. Pad the ATC value to the left with six bytes of X'00' and exclusive-OR the result with the left-half of the
intermediate key to obtain the left-half of the session key.
4. Obtain the one's complement of the ATC by exclusive-ORing the ATC with X'FFFF'. Pad the result on
the left with six bytes of X'00'. Exclusive-OR the 8-byte result with the right-half of the intermediate key
to obtain the right-half of the session key.
Deriving of the EMV TDESEMVn tree-based session key

In the Diversified_Key_Generate and PIN_Change/Unblock verbs, the TDESEMV2 and TDESEMV4
keywords call for the creation of the session key with this process:
1. The intermediate key is obtained as explained above for the TDES-XOR process.
2. Combine the intermediate key with the two-byte Application Transaction Counter (ATC) and an optional
Initial Value. The process is defined in the EMV 2000 Integrated Circuit Card Specifications for
Payment Systems Version 4.0 (EMV4.0) Book 2, Annex A1.3.
v TDESEMV2 causes processing with a branch factor of 2 and a height of 16.
v TDESEMV4 causes processing with a branch factor of 4 and a height of 8.
PIN-block self-encryption
In the Secure_Messaging_for_PINs (CSNBSPN) verb, you can use the SELFENC rule-array keyword to
specify that the 8-byte PIN block shall be used as a DES key to encrypt the PIN block. The verb copies
the self-encrypted PIN block to the clear PIN-block in the output message.
Appendix F. Verb list
This section lists the verbs supported by the CCA Support Program. Table 168 lists each verb by the
verbs pseudonym and entry-point name and lists the page for the verb. Be sure to look at the top of the
first page of a verb description to determine which platform and product supports the verb.
Table 168. Security API verbs in supported environments
Pseudonym Entry point Page
AES and DES key-processing and key-storage verbs
AES_Key_Record_Create CSNBAKRC 392
AES_Key_Record_Delete CSNBAKRD 394
AES_Key_Record_List CSNBAKRL 396
AES_Key_Record_Read CSNBAKRR 398
AES_Key_Record_Write CSNBAKRW 400
Clear_Key_Import CSNBCKI 198
Control_Vector_Generate CSNBCVG 200
Control_Vector_Translate CSNBCVT 203
Cryptographic_Variable_Encipher CSNBCVE 205
Data_Key_Export CSNBDKX 207
Data_Key_Import CSNBDKM 209
DES_Key_Record_Create CSNBKRC 402
DES_Key_Record_Delete CSNBKRD 404
DES_Key_Record_List CSNBKRL 406
DES_Key_Record_Read CSNBKRR 408
DES_Key_Record_Write CSNBKRW 409
Diversified_Key_Generate CSNBDKG 211
| EC_Diffie-Hellman CSNDEDH 217
Key_Encryption_Translate CSNBKET 224
Key_Export CSNBKEX 227
Key_Generate CSNBKGN 229
Key_Generate2 CSNBKGN2 239
Key_Import CSNBKIM 245
Key_Part_Import CSNBKPI 247
Key_Part_Import2 CSNBKPI2 251
Key_Storage_Initialization CSNBKSI 65
Key_Test CSNBKYT 256
Key_Test2 CSNBKYT2 261
Key_Test_Extended CSNBKYTX 265
Key_Token_Build CSNBKTB 270
Key_Token_Build2 CSNBKTB2 275
Key_Token_Change CSNBKTC 279
Key_Token_Change2 CSNBKTC2 281
Key_Token_Parse CSNBKTP 283
711
Table 168. Security API verbs in supported environments (continued)
| Key_Token_Parse2 CSNBKTP2 286
Key_Translate CSNBKTR 294
Key_Translate2 CSNBKTR2 296
Multiple_Clear_Key_Import CSNBCKM 301
PKA_Decrypt CSNDPKD 305
PKA_Encrypt CSNDPKE 307
Prohibit_Export CSNBPEX 309
Prohibit_Export_Extended CSNBPEXX 311
Random_Number_Generate CSNBRNG 313
Random_Number_Generate_Long CSNBRNGL 315
Remote_Key_Export CSNDRKX 317
Restrict_Key_Attribute CSNBRKA 328
Symmetric_Algorithm_Decipher CSNBSAD 378
Symmetric_Algorithm_Encipher CSNBSAE 383
Symmetric_Key_Export CSNDSYX 333
Symmetric_Key_Generate CSNDSYG 339
Symmetric_Key_Import CSNDSYI 345
Symmetric_Key_Import2 CSNDSYI2 350
Trusted_Block_Create CSNDTBC 353
Data confidentiality and data integrity verbs
Decipher CSNBDEC 360
Digital_Signature_Generate CSNDDSG 118
Digital_Signature_Verify CSNDDSV 122
Encipher CSNBENC 363
HMAC_Generate CSNBHMG 366
HMAC_Verify CSNBHMV 369
MAC_Generate CSNBMGN 372
MAC_Verify CSNBMVR 375
MDC_Generate CSNBMDG 126
One_Way_Hash CSNBOWH 134
Random_Number_Tests CSUARNT 78
Coprocessor control verbs
Access_Control_Initialization CSUAACI 35
Access_Control_Maintenance CSUAACM 38
Cryptographic_Facility_Control CSUACFC 42
Cryptographic_Facility_Query CSUACFQ 48
Cryptographic_Facility_Version CSUACFV 58
Cryptographic_Resource_Allocate CSUACRA 59
Cryptographic_Resource_Deallocate CSUACRD 61
Key_Storage_Designate CSUAKSD 63

Logon_Control CSUALCT 67
Master_Key_Distribution CSUAMKD 70
Master_Key_Process CSNBMKP 74
PKA key-administration and key-storage verbs
Key_Storage_Initialization CSNBKSI 65
PKA_Key_Generate CSNDPKG 87
PKA_Key_Import CSNDPKI 92
PKA_Key_Token_Build CSNDPKB 95
PKA_Key_Token_Change CSNDKTC 103
PKA_Key_Translate CSNDPKT 105
PKA_Key_Record_Create CSNDKRC 410
PKA_Key_Record_Delete CSNDKRD 412
PKA_Key_Record_List CSNDKRL 414
PKA_Key_Record_Read CSNDKRR 416
PKA_Key_Record_Write CSNDKRW 418
PKA_Public_Key_Extract CSNDPKX 108
PKA_Public_Key_Hash_Register CSNDPKH 110
PKA_Public_Key_Register CSNDPKR 112
Retained_Key_Delete CSNDRKD 420
Retained_Key_List CSNDRKL 422
Financial services support verbs
Clear_PIN_Encrypt CSNBCPE 438
Clear_PIN_Generate CSNBPGN 441
Clear_PIN_Generate_Alternate CSNBCPA 444
CVV_Generate CSNBCSG 449
| CVV_Key_Combine CSNBCKC 452
CVV_Verify CSNBCSV 456
Encrypted_PIN_Generate CSNBEPG 459
Encrypted_PIN_Translate CSNBPTR 463
Encrypted_PIN_Verify CSNBPVR 469
PIN_Change/Unblock CSNBPCU 475
Secure_Messaging_for_Keys CSNBSKY 481
Secure_Messaging_for_PINs CSNBSPN 484
SET_Block_Compose CSNDSBC 489
SET_Block_Decompose CSNDSBD 492
Transaction_Validation CSNBTRV 496
| TR-31 DES-key management verbs
| Key_Export_to_TR31 CSNBT31X 501
| TR31_Key_Import CSNBT31I 528
| TR31_Key_Token_Parse CSNBT31P 551
Appendix F. Verb list 713

| TR31_Optional_Data_Build CSNBT31O 555
| TR31_Optional_Data_Read CSNBT31R 558

Appendix G. Access-control-point codes
The table in this section lists the CCA access-control commands (access-control points). The role to which
a user is assigned determines the commands available to that user.
Important: By default, you should disable commands. Do not enable an access-control point unless you
know why you are enabling it.
The table includes the following columns:

Offset
The hexadecimal offset, or access-control-point code, for the command. Offsets between X'0000' and
X'FFFF' inclusive that are not listed in this table are reserved.
Command name
The name of the command required by the following verbs. These command names are defined in
the csuap.def file used by the CNM utility, and in the Required commands section at the end of
each verb description.
Verb name
The names of the verbs that require that command to be enabled; for example, the Encipher
(CSNBENC) verb fails without permission to use the Encipher command, offset X'000E'.
Entry
The entry-point name of the verb.
Usage
Usage recommendations for the command. The abbreviations in this column are explained at the end
of the table.
See the Required commands section at the end of each verb description for access-control guidance for
each verb.
Table 169. Supported CCA commands
Offset Command name Verb name Entry Usage
X'000E' Encipher Encipher CSNBENC O
X'000F' Decipher Decipher CSNBDEC O
X'0010' Generate MAC MAC_Generate CSNBMGN O
X'0011' Verify MAC MAC_Verify CSNBMVR O
X'0012' Reencipher to Master Key Key_Import CSNBKIM O
X'0013' Reencipher from Master Key Key_Export CSNBKEX O
X'0018' Load First Master Key Part Master_Key_Process CSNBMKP SC, SEL
X'0019' Combine Master Key Parts Master_Key_Process CSNBMKP SC, SEL
X'001A' Set Master Key Master_Key_Process CSNBMKP SC, SEL

X'001B' Load First Key Part Key_Part_Import CSNBKPI SC, SEL
X'001C' Combine Key Parts Key_Part_Import CSNBKPI SC, SEL
715
Table 169. Supported CCA commands (continued)
X'001D' Compute Verification Pattern AES_Key_Record_Create CSNBAKRC R
AES_Key_Record_Delete CSNBAKRD
AES_Key_Record_List CSNBAKRL
AES_Key_Record_Read CSNBAKRR
AES_Key_Record_Write CSNBAKRW
DES_Key_Record_Create CSNBKRC
DES_Key_Record_Delete CSNBKRD
DES_Key_Record_List CSNBKRL
DES_Key_Record_Read CSNBKRR
DES_Key_Record_Write CSNBKRW
Key_Storage_Initialization CSNBKSI
Key_Test CSNBKYT
| Key_Test2 (Rel. 4.0 or later) CSNBKYT2
Key_Test_Extended CSNBKYTX
PKA_Key_Record_Create CSNDKRC
PKA_Key_Record_Delete CSNDKRD
PKA_Key_Record_List CSNDKRL
PKA_Key_Record_Read CSNDKRR
PKA_Key_Record_Write CSNDKRW
X'001F' Translate Key Key_Translate CSNBKTR O
X'0020' Generate Random Master Key Master_Key_Process CSNBMKP O, SEL
| X'0021' Compute ENC-ZERO Verification Pattern for AES Key_Test2 CSNBKYT2 O (Rel. 4.2 or later)
X'0032' Clear New Master Key Register Master_Key_Process CSNBMKP O, SUP
X'0033' Clear Old Master Key Register Master_Key_Process CSNBMKP O, SUP
X'0040' Generate Diversified Key (CLR8-ENC) Diversified_Key_Generate CSNBDKG O, SEL
X'0041' Generate Diversified Key (TDES-ENC) Diversified_Key_Generate CSNBDKG O, SEL
X'0042' Generate Diversified Key (TDES-DEC) Diversified_Key_Generate CSNBDKG O, SEL

X'0043' Generate Diversified Key (SESS-XOR) Diversified_Key_Generate CSNBDKG O, SEL
X'0044' Enable DKG Single Length Keys and Equal Halves for Diversified_Key_Generate CSNBDKG SC, SEL
TDES-ENC, TDES-DEC
X'0045' Generate Diversified Key (TDES-XOR) Diversified_Key_Generate CSNBDKG O, SEL
X'0046' Generate Diversified Key (TDESEMVn) Diversified_Key_Generate CSNBDKG O, SEL
X'0053' Load First Asymmetric Master Key Part Master_Key_Process CSNBMKP SC, SEL

X'0054' Combine Asymmetric Master Key Parts Master_Key_Process CSNBMKP SC, SEL
X'0057' Set Asymmetric Master Key Master_Key_Process CSNBMKP SC, SEL
X'0060' Clear New Asymmetric Master Key Buffer Master_Key_Process CSNBMKP SC, SEL
X'0061' Clear Old Asymmetric Master Key Buffer Master_Key_Process CSNBMKP SC, SEL
X'008A' Generate MDC MDC_Generate CSNBMDG R
| X'008C' Generate Key Set Key_Generate
CSNBKGN O
| X'008E' Generate Key Key_Generate CSNBKGN R
| Random_Number_Generate CSNBRNG
X'0090' Reencipher to Current Master Key Key_Token_Change CSNBKTC R
X'00A0' Generate Clear 3624 PIN Clear_PIN_Generate CSNBPGN O
X'00A4' Generate Clear 3624 PIN Offset Clear_PIN_Generate_Alternate CSNBCPA O
X'00AB' Verify Encrypted 3624 PIN Encrypted_PIN_Verify CSNBPVR O
X'00AC' Verify Encrypted German Bank Pool PIN Encrypted_PIN_Verify CSNBPVR O
X'00AD' Verify Encrypted Visa PVV Encrypted_PIN_Verify CSNBPVR O
X'00AE' Verify Encrypted InterBank PIN Encrypted_PIN_Verify CSNBPVR O
X'00AF' Format and Encrypt PIN Clear_PIN_Encrypt CSNBCPE O
X'00B0' Generate Formatted and Encrypted 3624 PIN Encrypted_PIN_Generate CSNBEPG O
X'00B1' Generate Formatted and Encrypted German Bank Encrypted_PIN_Generate CSNBEPG O
Pool PIN
X'00B2' Generate Formatted and Encrypted InterBank PIN Encrypted_PIN_Generate CSNBEPG O
X'00B3' Translate PIN with No Format-Control to No Encrypted_PIN_Translate CSNBPTR O
Format-Control
X'00B7' Reformat PIN with No Format-Control to No Encrypted_PIN_Translate CSNBPTR O
Format-Control
X'00BB' Generate Clear Visa PVV Alternate Clear_PIN_Generate_Alternate CSNBCPA O


X'00BC' Generate PIN Change Using OPINENC PIN_Change/Unblock CSNBPCU O
X'00BD' Generate PIN Change Using IPINENC PIN_Change/Unblock CSNBPCU O
X'00C3' Encipher Under Master Key Clear_Key_Import CSNBCKI SC
Multiple_Clear_Key_Import CSNBCKM
X'00CD' Lower Export Authority Prohibit_Export CSNBPEX O
X'00D6' Translate Control Vector Control_Vector_Translate CSNBCVT SC

X'00D7' Generate Key Set Extended Key_Generate CSNBKGN SC, SUP
X'00DA' Encipher Cryptovariable Cryptographic_Variable_Encipher CSNBCVE NRP, O, SUP
X'00DB' Replicate Key Key_Generate CSNBKGN NR, SC
Remote_Key_Export CSNDRKX
X'00DF' Generate CVV CVV_Generate CSNBCSG O
X'00E0' Verify CVV CVV_Verify CSNBCSV O

X'00E1' Unique Key Per Transaction, ANS X9.24 Encrypted_PIN_Translate CSNBPTR O
Encrypted_PIN_Verify CSNBPVR
X'00E4' Generate SHA-1 HMAC HMAC_Generate CSNBHMG O (Rel. 4.1 or later)

X'00E9' Lower Export Authority2 Restrict_Key_Attribute CSNBRKA O (Rel. 4.1 or later)
X'00EA' Generate2 Key Key_Generate2 CSNBKGN2 O (Rel. 4.1 or later)
X'00EB' Generate2 Key Set Key_Generate2 CSNBKGN2 O (Rel. 4.1 or later)
X'00F1' Reencipher to Current Master Key2 Key_Token_Change2 CSNBKTC2 R (Rel. 4.1 or later)

X'00F4' Import HMAC Key (PKOAEP2) Symmetric_Key_Import CSNDSYI O (Rel. 4.1 or later)
X'00F5' Export HMAC Key (PKOAEP2) Symmetric_Key_Export CSNDSYX O (Rel. 4.1 or later)
X'00F7' Verify SHA-1 HMAC HMAC_Verify CSNBHMV O (Rel. 4.1 or later)
X'00FA' Verify SHA-384 HMAC HMAC_Verify CSNBHMV O (Rel. 4.1 or later)

X'00FB' Verify SHA-512 HMAC HMAC_Verify CSNBHMV O (Rel. 4.1 or later)
| X'00FC' Export AES Key (PKOAEP2) Symmetric_Key_Export CSNDSYX O (Rel. 4.2 or later)
| X'00FD' Import AES Key (PKOAEP2) Symmetric_Key_Import CSNDSYI O (Rel. 4.2 or later)
X'0100' PKA96 Digital Signature Generate Digital_Signature_Generate CSNDDSG O, SC
X'0101' PKA96 Digital Signature Verify Digital_Signature_Verify CSNDDSV O
X'0102' PKA96 Reencipher to Current Master Key PKA_Key_Token_Change CSNDKTC O
X'0103' PKA96 PKA Key Generate PKA_Key_Generate CSNDPKG O, SUP
X'0104' PKA96 PKA Key Import PKA_Key_Import CSNDPKI O, SUP
X'0105' Symmetric Key Export PKCS-1.2/OAEP Symmetric_Key_Export CSNDSYX SC
X'0106' Symmetric Key Import PKCS-1.2/OAEP Symmetric_Key_Import CSNDSYI O
X'0107' One-Way Hash, SHA-1 One_Way_Hash CSNBOWH ID, R
X'0109' Data Key Import Data_Key_Import CSNBDKM O
X'010A' Data Key Export Data_Key_Export CSNBDKX O
X'010B' Compose SET Block SET_Block_Compose CSNDSBC O
X'010C' Decompose SET Block SET_Block_Decompose CSNDSBD O
X'010D' PKA96 Symmetric Key Generate Symmetric_Key_Generate CSNDSYG SC

X'010E' NL-EPP-5 Symmetric Key Generate Symmetric_Key_Generate CSNDSYG O
X'010F' Reset Intrusion Latch Cryptographic_Facility_Control CSUACFC O, SUP
X'0110' Set Clock Cryptographic_Facility_Control CSUACFC ID, SUP
X'0111' Reinitialize Device Cryptographic_Facility_Control CSUACFC ID, SUP
X'0112' Initialize Access-Control System Access_Control_Initialization CSUAACI ID, NRP, SUP
X'0113' Change User Profile Expiration Date Access_Control_Initialization CSUAACI ID, SUP
Appendix G. Access-control-point codes 717


X'0114' Change User Profile Authentication Data Access_Control_Initialization CSUAACI ID, NRP, SUP
X'0115' Reset User Profile Logon-Attempt-Failure Count Access_Control_Initialization CSUAACI ID, SUP
X'0116' Read Public Access-Control Information Access_Control_Maintenance CSUAACM ID, O
X'0117' Delete User Profile Access_Control_Maintenance CSUAACM ID, SUP
X'0118' Delete Role Access_Control_Maintenance CSUAACM ID, SUP
X'0119' Load Function-Control Vector Cryptographic_Facility_Control CSUACFC ID, NRP, SUP

X'011A' Clear Function-Control Vector Cryptographic_Facility_Control CSUACFC ID, NR
X'011B' Force User Logoff Logon_Control CSUALCT O, SUP
X'011C' Set EID Cryptographic_Facility_Control CSUACFC O, SUP
X'011D' Initialize Master Key Cloning Cryptographic_Facility_Control CSUACFC O, SUP
X'011E' PKA Encipher Clear Key PKA_Encrypt CSNDPKE O, SEL
X'011F' PKA Decipher Key Data PKA_Decrypt CSNDPKD SC, SEL
X'0120' Generate Random Asymmetric Master Key Master_Key_Process CSNBMKP SC, SEL
X'0121' SET PIN Encrypt with IPINENC SET_Block_Decompose CSNDSBD O
X'0122' SET PIN Encrypt with OPINENC SET_Block_Decompose CSNDSBD O
X'0123' Clear AES OMK Register (CLR-OLD) Master_Key_Process CSNBMKP O, SUP (Rel. 3.30
or later)
X'0124' Clear AES NMK Register (CLEAR) Master_Key_Process CSNBMKP O, SUP (Rel. 3.30
or later)
X'0125' Load First AES Master Key Part Master_Key_Process CSNBMKP O, SUP (Rel. 3.30
or later)
X'0126' Combine Intermediate AES Master Key Parts Master_Key_Process CSNBMKP O, SUP (Rel. 3.30
or later)
X'0128' Activate New AES Master Key (SET) Master_Key_Process CSNBMKP O, SUP (Rel. 3.30
or later)
X'0129' Encipher Under AES Master Key Multiple_Clear_Key_Import CSNBCKM SC (Rel. 3.30 or
later)
X'012A' Encipher Data Using AES Symmetric_Algorithm_Encipher CSNBSAE O (Rel. 3.30 or
later)
X'012B' Decipher Data Using AES Symmetric_Algorithm_Decipher CSNBSAD O (Rel. 3.30 or
later)
X'012C' Generate AES DATA Key (PKCSOAEP or PKCS-1.2) Symmetric_Key_Generate CSNDSYG SC (Rel. 3.30 or
later)
X'012D' Generate AES DATA Key (ZERO-PAD) Symmetric_Key_Generate CSNDSYG SC (Rel. 3.30 or
later)
X'012E' Import AES Key (PKCSOAEP or PKCS-1.2) Symmetric_Key_Import CSNDSYI O (Rel. 3.30 or
later)
X'012F' Import AES Key (ZERO-PAD) Symmetric_Key_Import CSNDSYI O (Rel. 3.30 or
later)
X'0130' Export AES Key (PKCSOAEP or PKCS-1.2) Symmetric_Key_Export CSNDSYX SC (Rel. 3.30 or
later)
X'0131' Export AES Key (ZERO-PAD) Symmetric_Key_Export CSNDSYX SC (Rel. 3.30 or
later)
X'0135' One-Way Hash, SHA-224 One_Way_Hash CSNBOWH O (Rel. 4.0 or later)
X'0139' Wrap Internal Key with Enhanced Method Cryptographic_Facility_Control CSUACFC O (Rel. 4.1 or later)

X'013A' Wrap Internal Key with ECB Method Cryptographic_Facility_Control CSUACFC O (Rel. 4.1 or later)
X'013B' Wrap External Key with Enhanced Method Cryptographic_Facility_Control CSUACFC O (Rel. 4.1 or later)
X'013C' Wrap External Key with ECB Method Cryptographic_Facility_Control CSUACFC O (Rel. 4.1 or later)
X'013D' Allow Configuration Override with Keyword in DKG Diversified_Key_Generate CSNBDKG O (Rel. 4.1 or later)
X'013E' Allow Configuration Override with Keyword in SYG Symmetric_Key_Generate CSNDSYG O (Rel. 4.1 or later)
X'0140' Allow Configuration Override with Keyword in KPI Key_Part_Import CSNBKPI O (Rel. 4.1 or later)
X'0141' Allow Configuration Override with Keyword in CKM Multiple_Clear_Key_Import CSNBCKM O (Rel. 4.1 or later)


X'0144' Allow Configuration Override with Keyword in SYI Symmetric_Key_Import CSNDSYI O (Rel. 4.1 or later)
X'0146' Allow Configuration Override with Keyword in KTC Key_Token_Change CSNBKTC O (Rel. 4.1 or later)
X'0147' Enable Translation from New to Old Format in KTC Key_Token_Change CSNBKTC O, NRP (Rel. 4.1 or
and KTR2 Key_Translate2 CSNBKTR2 later)
X'0149' Translate Key2 Key_Translate2 CSNBKTR2 O (Rel. 4.1 or later)
X'014A' Allow Configuration Override with Keyword in KTR2 Key_Translate2 CSNBKTR2 O (Rel. 4.1 or later)

X'014B' Translate Key2 (REFORMAT) Key_Translate2 CSNBKTR2 O (Rel. 4.1 or later)
X'014C' Key Token Change (REFORMAT) Key_Token_Change CSNBKTC O (Rel. 4.1 or later)
| X'014D' TR31 Export - Permit Version A TR-31 Key Blocks Key_Export_to_TR31 CSNBT31X O
| X'014E' TR31 Export - Permit Version B TR-31 Key Blocks Key_Export_to_TR31 CSNBT31X O
| X'014F' TR31 Export - Permit Version C TR-31 Key Blocks Key_Export_to_TR31 CSNBT31X O
| X'0150' TR31 Import - Permit Version A TR-31 Key Blocks TR31_Key_Import
CSNBT31I O
| X'0151' TR31 Import - Permit Version B TR-31 Key Blocks TR31_Key_Import CSNBT31I O
| X'0152' TR31 Import - Permit Version C TR-31 Key Blocks TR31_Key_Import CSNBT31I O
| X'0153' TR31 Import - Permit Override of Default Wrapping TR31_Key_Import CSNBT31I O, SC
| Method
| X'0154' Restrict Key Attribute - Permit Setting the TR-31 Restrict_Key_Attribute CSNBRKA O (Rel. 4.2 or later)
| Export Bit
| X'0155' CVV Key Combine CVV_Key_Combine CSNBCKC O
| X'0156' CVV Key Combine - Allow Wrapping Override CVV_Key_Combine CSNBCKC O, SC
| Keywords
| X'0157' CVV Key Combine - Permit Mixed Key Types CVV_Key_Combine CSNBCKC O, SC
| X'0158' TR31 Export - Permit Any CCA Key if INCL-CV Is Key_Export_to_TR31 CSNBT31X O, SC
| Specified
| X'015A' TR31 Import - Permit C0 to MAC/ TR31_Key_Import CSNBT31I O, SC
| MACVER:CVVKEY-A
| X'015B' TR31 Import - Permit C0 to MAC/MACVER:AMEX- TR31_Key_Import CSNBT31I O, SC
| CSC
| X'015C' TR31 Import - Permit K0:E to EXPORTER/ TR31_Key_Import CSNBT31I O
| OKEYXLAT
| X'015D' TR31 Import - Permit K0:D to IMPORTER/IKEYXLAT TR31_Key_Import CSNBT31I O
| X'015E' TR31 Import - Permit K0:B to EXPORTER/ TR31_Key_Import CSNBT31I O
| OKEYXLAT
| X'015F' TR31 Import - Permit K0:B to IMPORTER/IKEYXLAT TR31_Key_Import CSNBT31I O
| X'0160' TR31 Import - Permit K1:E to EXPORTER/ TR31_Key_Import CSNBT31I O
| OKEYXLAT
| X'0161' TR31 Import - Permit K1:D to IMPORTER/IKEYXLAT TR31_Key_Import CSNBT31I O
| X'0162' TR31 Import - Permit K1:B to EXPORTER/ TR31_Key_Import CSNBT31I O
| OKEYXLAT
| X'0163' TR31 Import - Permit K1:B to IMPORTER/IKEYXLAT TR31_Key_Import CSNBT31I O
| X'0164' TR31 Import - Permit M0/M1/M3 to TR31_Key_Import CSNBT31I O
| MAC/MACVER:ANY-MAC
| X'0165' TR31 Import - Permit P0:E to OPINENC TR31_Key_Import CSNBT31I O
| X'0166' TR31 Import - Permit P0:D to IPINENC TR31_Key_Import CSNBT31I O
| X'0167' TR31 Import - Permit V0 to PINGEN:NO-SPEC TR31_Key_Import CSNBT31I O
| X'0168' TR31 Import - Permit V0 to PINVER:NO-SPEC TR31_Key_Import CSNBT31I O
| X'0169' TR31 Import - Permit V1 to PINGEN:IBM-PIN/IBM- TR31_Key_Import CSNBT31I O
| PINO
| X'016A' TR31 Import - Permit V1 to PINVER:IBM-PIN/IBM- TR31_Key_Import CSNBT31I O
| PINO
| X'016B' TR31 Import - Permit V2 to PINGEN:VISA-PVV TR31_Key_Import CSNBT31I O
| X'016C' TR31 Import - Permit V2 to PINVER:VISA-PVV TR31_Key_Import CSNBT31I O
| X'016D' TR31 Import - Permit E0 to TR31_Key_Import CSNBT31I O
| X'016E' TR31 Import - Permit E0 to DKYGENKY:DKYL0+DMV TR31_Key_Import CSNBT31I O

| X'016F' TR31 Import - Permit E0 to TR31_Key_Import
CSNBT31I O
| X'0170' TR31 Import - Permit E0 to DKYGENKY:DKYL1+DMV TR31_Key_Import CSNBT31I O
| X'0171' TR31 Import - Permit E1 to TR31_Key_Import CSNBT31I O
| X'0177' TR31 Import - Permit E3 to ENCIPHER TR31_Key_Import CSNBT31I O
| X'017A' TR31 Import - Permit E5 to TR31_Key_Import CSNBT31I O
| X'017B' TR31 Import - Permit E5 to TR31_Key_Import CSNBT31I O
| DKYGENKY:DKYL0+DEXP
| X'017C' TR31 Import - Permit V0/V1/V2:N to PINGEN/PINVER TR31_Key_Import CSNBT31I O, SC
| X'0180' TR31 Export - Permit KEYGENKY:UKPT to B0 Key_Export_to_TR31
CSNBT31X O
| X'0181' TR31 Export - Permit MAC/MACVER:AMEX-CSC to Key_Export_to_TR31 CSNBT31X O
| C0:G/C/V
| X'0182' TR31 Export - Permit MAC/MACVER:CVV-KEYA to Key_Export_to_TR31 CSNBT31X O
| C0:G/C/V
| X'0183' TR31 Export - Permit MAC/MACVER:ANY-MAC to Key_Export_to_TR31 CSNBT31X O
| C0:G/C/V
| X'0184' TR31 Export - Permit DATA to C0:G/C Key_Export_to_TR31 CSNBT31X O
| X'0185' TR31 Export - Permit ENCIPHER/DECIPHER/ Key_Export_to_TR31 CSNBT31X O
| CIPHER to D0:E/D/B
| X'0186' TR31 Export - Permit DATA to D0:B Key_Export_to_TR31 CSNBT31X O
| X'0187' TR31 Export - Permit EXPORTER/OKEYXLAT to Key_Export_to_TR31 CSNBT31X O
| K0:E
| X'0188' TR31 Export - Permit IMPORTER/IKEYXLAT to K0:D Key_Export_to_TR31 CSNBT31X O
| X'0189' TR31 Export - Permit EXPORTER/OKEYXLAT to Key_Export_to_TR31 CSNBT31X O
| K1:E
| X'018A' TR31 Export - Permit IMPORTER/IKEYXLAT to K1:D Key_Export_to_TR31 CSNBT31X O
| X'018B' TR31 Export - Permit MAC/DATA/DATAM to M0:G/C Key_Export_to_TR31 CSNBT31X O
| X'018C' TR31 Export - Permit MACVER/DATAMV to M0:V Key_Export_to_TR31
CSNBT31X O
| X'018D' TR31 Export - Permit MAC/DATA/DATAM to M1:G/C Key_Export_to_TR31 CSNBT31X O
| X'018E' TR31 Export - Permit MACVER/DATAMV to M1:V Key_Export_to_TR31 CSNBT31X O
| X'018F' TR31 Export - Permit MAC/DATA/DATAM to M3:G/C Key_Export_to_TR31 CSNBT31X O
| X'0190' TR31 Export - Permit MACVER/DATAMV to M3:V Key_Export_to_TR31 CSNBT31X O
| X'0191' TR31 Export - Permit OPINENC to P0:E Key_Export_to_TR31 CSNBT31X O
| X'0192' TR31 Export - Permit IPINENC to P0:D Key_Export_to_TR31
CSNBT31X O
| X'0193' TR31 Export - Permit PINVER:NO-SPEC to V0 Key_Export_to_TR31 CSNBT31X O
| X'0194' TR31 Export - Permit PINGEN:NO-SPEC to V0 Key_Export_to_TR31 CSNBT31X O
| X'0195' TR31 Export - Permit PINVER:NO-SPEC/IBM-PIN/ Key_Export_to_TR31 CSNBT31X O
| IBM-PINO to V1
| X'0196' TR31 Export - Permit PINGEN:NO-SPEC/IBM-PIN/ Key_Export_to_TR31 CSNBT31X O
| IBM-PINO to V1

| X'0197' TR31 Export - Permit PINVER:NO-SPEC/VISA-PVV Key_Export_to_TR31
CSNBT31X O
| to V2
| X'0198' TR31 Export - Permit PINGEN:NO-SPEC/VISA-PVV Key_Export_to_TR31 CSNBT31X O
| to V2
| X'0199' TR31 Export - Permit DKYGENKY:DKYL0+DMAC to Key_Export_to_TR31 CSNBT31X O
| E0
| X'019A' TR31 Export - Permit DKYGENKY:DKYL0+DMV to E0 Key_Export_to_TR31 CSNBT31X O
| X'019B' TR31 Export - Permit DKYGENKY:DKYL0+DALL to Key_Export_to_TR31 CSNBT31X O
| E0
| X'019C' TR31 Export - Permit DKYGENKY:DKYL1+DMAC to Key_Export_to_TR31 CSNBT31X O
| E0
| X'019D' TR31 Export - Permit DKYGENKY:DKYL1+DMV to E0 Key_Export_to_TR31 CSNBT31X O
| X'019E' TR31 Export - Permit DKYGENKY:DKYL1+DALL to Key_Export_to_TR31
CSNBT31X O
| E0
| X'019F' TR31 Export - Permit DKYGENKY:DKYL0+DDATA to Key_Export_to_TR31 CSNBT31X O
| E1
| X'01A0' TR31 Export - Permit DKYGENKY:DKYL0+DMPIN to Key_Export_to_TR31 CSNBT31X O
| E1
| X'01A1' TR31 Export - Permit DKYGENKY:DKYL0+DALL to Key_Export_to_TR31 CSNBT31X O
| E1
| X'01A2' TR31 Export - Permit DKYGENKY:DKYL1+DDATA to Key_Export_to_TR31 CSNBT31X O
| E1
| X'01A3' TR31 Export - Permit DKYGENKY:DKYL1+DMPIN to Key_Export_to_TR31 CSNBT31X O
| E1
| E1
| X'01A5' TR31 Export - Permit DKYGENKY:DKYL0+DMAC to Key_Export_to_TR31 CSNBT31X O
| E2
| E2
| X'01A7' TR31 Export - Permit DKYGENKY:DKYL1+DMAC to Key_Export_to_TR31 CSNBT31X O
| E2
| E2
| X'01A9' TR31 Export - Permit DATA/MAC/CIPHER/ENCIPHER Key_Export_to_TR31 CSNBT31X O
| to E3
| X'01AA' TR31 Export - Permit DKYGENKY:DKYL0+DDATA to Key_Export_to_TR31 CSNBT31X O
| E4
| X'01AB' TR31 Export - Permit DKYGENKY:DKYL0+DALL to Key_Export_to_TR31 CSNBT31X O
| E4
| X'01AC' TR31 Export - Permit DKYGENKY:DKYL0+DEXP to Key_Export_to_TR31 CSNBT31X O
| E5
| X'01AD' TR31 Export - Permit DKYGENKY:DKYL0+DMAC to Key_Export_to_TR31 CSNBT31X O
| E5
| X'01AE' TR31 Export - Permit DKYGENKY:DKYL0+DDATA to Key_Export_to_TR31 CSNBT31X O
| E5
| X'01AF' TR31 Export - Permit DKYGENKY:DKYL0+DALL to Key_Export_to_TR31 CSNBT31X O
| E5
| X'01B0' TR31 Export - Permit PINGEN/PINVER to V0/V1/V2:N Key_Export_to_TR31 CSNBT31X O, SC
X'0200' PKA Register Public Key Hash PKA_Public_Key_Hash_Register CSNDPKH O
X'0201' PKA Public Key Register PKA_Public_Key_Register CSNDPKR O, SEL
X'0202' PKA Public Key Register with Cloning PKA_Public_Key_Register CSNDPKR O, SEL
X'0203' Delete Retained Key Retained_Key_Delete CSNDKRD O, SEL
X'0204' PKA Clone Key Generate PKA_Key_Generate CSNDPKG O, SUP
X'0205' PKA Clear Key Generate PKA_Key_Generate CSNDPKG O, SUP
X'0211' Clone-info (Share) Obtain 1 - Master_Key_Distribution CSUAMKD O, SUP
X'021F' Clone-info (Share) Obtain 15


X'0221' Clone-info (Share) Install 1 - Master_Key_Distribution CSUAMKD O, SUP
X'022F' Clone-info (Share) Install 15
X'0230' List Retained Key Retained_Key_List CSNDRKL O
X'0231' Generate Clear NL-PIN-1 Offset Clear_PIN_Generate_Alternate CSNBCPA O
X'0232' Verify Encrypted NL-PIN-1 Encrypted_PIN_Verify CSNBPVR O
X'0235' PKA96 Symmetric Key Import Symmetric_Key_Import CSNDSYI O

X'0236' PKA96 Symmetric Key Import with PIN Keys Symmetric_Key_Import CSNDSYI O
X'023C' ZERO-PAD Symmetric Key Generate Symmetric_Key_Generate CSNDSYG O, SC
X'023D' ZERO-PAD Symmetric Key Import Symmetric_Key_Import CSNDSYI O, SC
X'023E' ZERO-PAD Symmetric Key Export Symmetric_Key_Export CSNDSYX O, SC
X'023F' Symmetric Key Generate PKCS-1.2/OAEP Symmetric_Key_Generate CSNDSYG O, SC
X'0273' Secure Messaging for Keys Secure_Messaging_for_Keys CSNBSKY O
X'0274' Secure Messaging for PINs Secure_Messaging_for_PINs CSNBSPN O
X'0276' Unrestrict Reencipher from Master Key Key_Export CSNBKEX O, SC
X'0277' Unrestrict Data Key Export Data_Key_Export CSNBDKX O, SC
X'0278' Add Key Part Key_Part_Import CSNBKPI SC, SEL
X'0279' Complete Key Part Key_Part_Import CSNBKPI SC, SEL

X'027A' Unrestrict Combine Key Parts Key_Part_Import CSNBKPI O, NRP, SC
X'027B' Unrestrict Reencipher to Master Key Key_Import CSNBKIM O, SC
X'027C' Unrestrict Data Key Import Data_Key_Import CSNBDKM O, SC
X'027D' Permit Regeneration Data PKA_Key_Generate CSNDPKG O, NRP, SC
X'027E' Permit Regeneration Data for Retained Keys PKA_Key_Generate CSNDPKG O, NRP, SC
X'0290' Generate Diversified Key (DALL with DKYGENKY Key Diversified_Key_Generate CSNBDKG O, SC
Type) PIN_Change/Unblock CSNBPCU
X'0291' Generate CSC 3, 4 and 5 Values Transaction_Validation CSNBTRV O, SEL
X'0292' Verify CSC 3 Values Transaction_Validation CSNBTRV O

X'0297' Import Minimum Three Parts Key_Part_Import2 CSNBKPI2 O (Rel. 4.1 or later)
X'0298' Import Minimum Two Parts Key_Part_Import2 CSNBKPI2 O (Rel. 4.1 or later)
X'0299' Import Minimum One Part Key_Part_Import2 CSNBKPI2 O (Rel. 4.1 or later)
X'029A' Import Second of Three or More Parts Key_Part_Import2 CSNBKPI2 O (Rel. 4.1 or later)
X'029B' Import Last Minimum Required Part Key_Part_Import2 CSNBKPI2 O (Rel. 4.1 or later)
X'029C' Import Optional Part Key_Part_Import2 CSNBKPI2 O (Rel. 4.1 or later)

X'029D' Complete Import of Key Parts Key_Part_Import2 CSNBKPI2 SEL (Rel. 4.1 or
later)
X'0301' Lower Export Authority, Extended Prohibit_Export_Extended CSNBPEXX O
X'0304' Error Injection 1 Cryptographic_Facility_Control CSUACFC SC, SUP
X'030B' Reset Battery-Low Indicator Cryptographic_Facility_Control CSUACFC SUP
X'030C' Override DSG ZERO-PAD Length Restriction Digital_Signature_Generate CSNDDSG O, SC
X'030D' Translate Key from CBC to ECB Key_Encryption_Translate CSNBKET O
X'030E' Translate Key from ECB to CBC Key_Encryption_Translate CSNBKET O
X'030F' Create a Trusted Block in Inactive Form Trusted_Block_Create CSNDTBC O, SUP
X'0310' Activate an Inactive Trusted Block Trusted_Block_Create CSNDTBC O, SUP
X'0311' Convert Trusted Block from External to Internal Form PKA_Key_Import CSNDPKI O, SEL
X'0312' Generate or Export a Key for Use by a Non-CCA Remote_Key_Export CSNDRKX O, SEL
Node
X'0313' Enhanced PIN Security Mode Clear_PIN_Generate_Alternate CSNBCPA O, SC, SEL
Clear_PIN_Encrypt CSNBCPE
Encrypted_PIN_Generate CSNBEPG
Encrypted_PIN_Translate CSNBPTR
Encrypted_PIN_Verify CSNBPVR
PIN_Change/Unblock CSNBPCU


X'0318' Translate from CCA RSA to SC Visa Format PKA_Key_Translate CSNDPKT O (Rel. 4.0 or later)
X'0319' Translate from CCA RSA to SC M-E Format PKA_Key_Translate CSNDPKT O (Rel. 4.0 or later)
X'031A' Translate from CCA RSA to SC CRT Format PKA_Key_Translate CSNDPKT O (Rel. 4.0 or later)
X'031B' XLATE from Encryption Under Source EXP KEK to PKA_Key_Translate CSNDPKT O (Rel. 4.0 or later)
Target EXP KEK
X'031C' XLATE from Encryption Under Source IMP KEK to PKA_Key_Translate CSNDPKT O (Rel. 4.0 or later)
Target EXP KEK
X'031D' XLATE from Encryption Under Source IMP KEK to PKA_Key_Translate CSNDPKT O (Rel. 4.0 or later)
Target IMP KEK
X'031E' Clear APKA OMK Register (CLR-OLD) Master_Key_Process CSNBMKP O (Rel. 4.0 or later)
X'031F' Clear APKA NMK Register (CLEAR) Master_Key_Process CSNBMKP O (Rel. 4.0 or later)
X'0320' Load First APKA Master Key Part Master_Key_Process CSNBMKP O (Rel. 4.0 or later)

X'0321' Combine Intermediate APKA Master Key Parts Master_Key_Process CSNBMKP O (Rel. 4.0 or later)
X'0322' Activate New APKA Master Key (SET) Master_Key_Process CSNBMKP O (Rel. 4.0 or later)
X'0326' Generate ECC Keys in the Clear PKA_Key_Generate CSNDPKG O (Rel. 4.0 or later)
| X'0327' Export AES Key (AESKW) Symmetric_Key_Export CSNDSYX O, R (Rel. 4.2 or
| later)
| X'0328' Disallow Weak Key Wrap EC_Diffie-Hellman CSNDEDH O, R (Rel. 4.2 or
| Key_Generate2 CSNBKGN2 later)
| PKA_Key_Generate CSNDPKG
| Symmetric_Key_Export CSNDSYX
| X'0329' Import AES Key (AESKW) Symmetric_Key_Import2 CSNDSYI2 O (Rel. 4.2 or later)
| X'032A' Disallow Translation from an AES X'05' to an AES Key_Translate2 CSNBKTR2 O, R (Rel. 4.2 or
| X'04' Token later)
| X'032B' Disallow Weak Import Symmetric_Key_Import2 CSNDSYI2 O, R (Rel. 4.2 or
| later)
| X'032C' Warn When Wrapping Weak Keys EC_Diffie-Hellman CSNDEDH O, R (Rel. 4.2 or
| Key_Generate2 CSNBKGN2 later)
| Symmetric_Key_Export CSNDSYX
| Symmetric_Key_Import2 CSNDSYI2
X'0350' Enforce ANS X9.8 PIN Rules Clear_PIN_Generate_Alternate CSNBCPA O, R (Rel. 4.0 or
Encrypted_PIN_Translate CSNBPTR later)
Secure_Messaging_for_PINs CSNBSPN
X'0351' Allow Change of PAN with ANS X9.8 PIN Rules Encrypted_PIN_Translate CSNBPTR O, SC (Rel. 4.0 or
Secure_Messaging_for_PINs CSNBSPN later)
X'0352' Enforce ANS X9.8 PIN Rules and Disallow Use of Encrypted_PIN_Translate CSNBPTR O, SC (Rel. 4.0 or
Non-ISO PINs Secure_Messaging_for_PINs CSNBSPN later)
| X'0353' Load Decimalization Tables Cryptographic_Facility_Control CSUACFC O (Rel. 4.2 or later)
| X'0354' Delete Decimalization Tables Cryptographic_Facility_Control CSUACFC O (Rel. 4.2 or later)
| X'0355' Activate Decimalization Tables Cryptographic_Facility_Control CSUACFC O (Rel. 4.2 or later)
| X'0356' Use Only Valid Decimalization Tables Clear_PIN_Generate CSNBPGN O, R (Rel. 4.2 or
| Clear_PIN_Generate_Alternate CSNBCPA later)
| Encrypted_PIN_Generate CSNBEPG
| Encrypted_PIN_Verify CSNBPVR
| X'0360' Elliptic Curve Diffie-Hellman EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'0362' Allow Configuration Override with Keyword in EDH EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'0363' Allow Prime Curve 192 EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'0366' Allow Prime Curve 384 EC_Diffie-Hellman
CSNDEDH O (Rel. 4.2 or later)
| X'0368' Allow Brainpool Curve 160 EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'0369' Allow Brainpool Curve 192 EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'036A' Allow Brainpool Curve 224 EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'036B' Allow Brainpool Curve 256 EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'036C' Allow Brainpool Curve 320 EC_Diffie-Hellman

| X'036D' Allow Brainpool Curve 384 EC_Diffie-Hellman
| X'036E' Allow Brainpool Curve 512 EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| X'036F' Prevent Weaker Keys from Being Used to Generate EC_Diffie-Hellman CSNDEDH O (Rel. 4.2 or later)
| Stronger Keys
The following abbreviations and symbols are used in this table:
ID Initial default.
O Usage of this command is optional; enable it as required for authorized usage.
R Enabling this command is recommended.
NR Enabling this command is not recommended.
NRP Enabling this command is not recommended for production.
SC Usage of this command requires special consideration.
SEL Usage of this command is normally restricted to one or more selected roles.
SUP This command is normally restricted to one or more supervisory roles.
This verb performs more than one function, as determined by the keywords identified by the rule_array parameter of the verb call. Not all
functions of the verb require the command in this row.
| This verb does not always require the command in this row. Use as determined by the control vector or key usage fields for the key and
| the action being performed.

Appendix H. Observations on secure operations
This section offers a series of observations about the setup and use of the IBM 4765 and IBM 4764 CCA
cryptographic node that you might consider in order to enhance secure operations. Topics include:
v Ensuring code levels match and IBM CCA code is installed
v Managing access controls
v Protecting cryptographic keys on page 727
v PIN data considerations on page 732
v Validating coprocessor status data on page 732
v RS-232 port on page 732
v Master-key cloning on page 732
v Sample access-control regimes on page 732
Ensuring code levels match and IBM CCA code is installed

The level of the CCA code in the host system should match that used within the coprocessor. Follow the
procedures for obtaining code for your system type and ensure you have matching code for both the host
environment and for the coprocessor. You should ensure that the host-system code supplied for use with
CCA and the coprocessor has not been altered from that obtained from IBM.
Managing access controls

The access-control system and the grouping of permissible commands that you can employ are designed
to support a variety of security policies. In particular, you can set up the CCA node to enforce a
dual-control, split-knowledge policy. Under this policy, once the node is fully activated, no one person
should be able to cause detrimental actions other than a denial-of-service attack. To implement this policy,
and many other approaches, you must limit your use of certain commands. Therefore, as you design your
application, you should consider the commands you must enable or restrict in the access-control system
and the implications to your security policy. See Appendix G, Access-control-point codes, on page 715 for
a table of commands with general guidance in the right-hand column.
The following sections describe:

v Locking the access-control system
v Changing a passphrase
v Defining roles and profiles
Locking the access-control system

For secure operation after performing any initializing processes, consider locking the access-control
system. You can render the access-control system unchangeable by deleting any profile that would allow
use of the Access Control Initialization command (X'0112', invoked with the Access_Control_Initialization
verb and INIT-AC keyword), and the Delete Role command (X'0118', invoked with the
Access_Control_Maintenance verb and DEL-ROLE keyword). Without these commands, further changes
to the access-control roles are not possible.
Before the CCA node is put into normal operation, the access-control setup can be audited using the
Access_Control_Maintenance and Cryptographic_Facility_Query verbs. If for any reason the status
response is not as anticipated, the node should not be activated for application purposes.
Note: With authority to use either the Initialize Access Control or Delete Role commands, you can delete
the DEFAULT role. Deleting the DEFAULT role causes the automatic recreation of the initial
725
DEFAULT role. The initial DEFAULT role permits setting up any capabilities. Users with access to
these commands have unlimited authority through manipulation of the access-control system.
Changing a passphrase
The passphrase used to authenticate access to a profile is not communicated out of the DLL or shared
library you call with the Logon_Control verb. Rather, the passphrase is hashed to form a cryptographic key
that is used to pass the profile identifier and other information to permit the coprocessor to validate access
to the profile.
When you change a passphrase with the Access_Control_Initialization verb, use the PROTECTD keyword.
This causes the passphrase to be encrypted within the DLL or shared-library layer before it is
communicated to the coprocessor. This can block a lower-level sniffer program or the CCA trace facility
from capturing the new, clear passphrase.
If a role contains permission to change a passphrase, the passphrase of any profile can be changed. You
should consider if passphrase Change a User Profile Authentication Data command, should be permitted
and, if so, which roles should have this authority (offset X'0114').
If any user reports an inability to log on, this should be reported to someone other than (or certainly in
addition to) an individual with passphrase-changing permission.
Defining roles and profiles

The access-control system permits users to define roles and profiles as suits their operation and security
needs. Roles and profiles you might consider include the following:
Table 170. Example roles
Setup A Setup role can be defined that enables loading of required roles, profiles, and
other special values such as the node environment identifier (EID), function control
vector (FCV), set up of the master-key-shares cloning m-of-n values, and
registration of public keys for later use in key distribution.
Administrator You can establish an Administrator role with extensive supervisory capabilities. The
administrative roles could be permitted to change the passphrase of any profile
and reset the logon failure-count of any profile (Access_Control_Initialization verb).
An individual entrusted with these responsibilities can log on to any role by

changing the passphrase of an associated profile and thereby gain the permissions
of any role. However, he might not be able to restore the passphrase of the normal
user of the profile because in a secure installation he should not know another
user's passphrase. You can address this problem in the following ways:
v Disabling a role that permits passphrase changing
v Ensuring that any suspected authentication problems are reported to someone
other than the administrator, who uses roles that permit passphrase changing
Note: You should set up a duplicate administrator role and associated profiles with
a different expiration date to ensure that you have access to those services
appropriate to the administrator. This might give you an opportunity to recover
should the primary administrator make an error that cannot be rectified.
Security Officer 1 (SO1) Security Officer 1's role could be permitted to:
v Randomly generate a master key
v Import a key-encrypting key
Note: If you employ introduction of keys in parts (Key_Part_Import or
Master_Key_Process verbs; see Protecting cryptographic keys on page 727 for
more information), the first-part and second-part permissions should be assigned to
SO1 and SO2, respectively.

Table 170. Example roles (continued)
Security Officer 2 (SO2) Security Officer 2's role could be permitted to:
v Set a master key
v Import keys
Note: If you employ introduction of keys in parts (Key_Part_Import or
Master_Key_Process verbs; see Protecting cryptographic keys for more
information), the first-part and second-part permissions should be assigned to SO1
and SO2, respectively.
Default You must have a Default role. When a host thread is not logged on, requests from
such a thread are performed based on the permissions set in the default role. You
should enable only those commands necessary for normal operations. At a
maximum, only those functions specifically required should be enabled. All
sensitive or unusual requirements should be processed following a logon to an
appropriate profile (and thus its role).
Application user n As required, n application-specific roles and associated profiles should be
established for processing portions of applications with security requirements
different from those permitted under the Default role. For example, enabling any of
the key export verbs could release keys to an adversary. Such operations are
candidates for selective enablement under control of a specific role.
In all cases, enable only the commands needed to accommodate the permitted applications.
Protecting cryptographic keys

Cryptographic keys are typically passed across the CCA interface as encrypted objects in key-token data
structures. Rogue processes on your host system might be able to capture a copy of such keys, or the
contents of the key-storage dataset might be copied. You must rely on your operating system security,
system-operational security, and physical security to counter any threat from an encrypted-key copy. Do
not allow a rogue process to make use of the encrypted key. Your environmental security policy should
consider how rogue processes could make use of a copy of an encrypted key. You must consider the
handling of any clear keys.
Keys are further discussed under these topics:

v CCA asymmetric DES keys
v Clear key parts
v Key export
v Key unwrapping
v Clear key operations
v DES replicated keys
v RSA keys
CCA asymmetric DES keys

With CCA, you can often make use of a unique capability afforded through the CCA control vector and
command architecture. CCA enables DES keys to have asymmetric properties. Using MAC or MACVER,
ENCIPHER/DECIPHER, IMPORTER/EXPORTER, PINGEN/PINVER, and IPINENC/OPINENC key types,
you can separate which systems and processes can reverse various cryptographic functions.
MAC and MACVER

A node that has a MAC-class key can both generate and verify a DES MAC value. A CCA node having
only the key with MACVER properties is unable to create an authentication code or MAC with the key.
Thus, data recipients who receive only a MACVER key can be enabled to validate data, but are prevented
from producing a MAC on data potentially altered to their advantage.
Appendix H. Observations on secure operations 727

Also, a DES MAC is computed by enciphering the cleartext data. You need to ensure that an adversary is
denied access to enciphering processes with the key used in the MAC computations. For this reason,
consider using the MAC and MACVER keys rather than the DATA-class keys.
By default, DATA-class keys perform in both encipher and MAC generation and verification operations.
ENCIPHER and DECIPHER

You can separate the ability to reverse a DES ciphering process. Use an ENCIPHER key at the
data-encryption node, and only supply the data-decryption node with the DECIPHER form of the ciphering
key.
You might also find uses for enciphering data where you want to disallow the possibility that the data is
ever deciphered. You can determine the equivalence of two copies of source data by comparing their
enciphered value. Thus, you can store an enciphered copy of data and determine later that other data is
not equivalent without revealing the clear value of the original data. A hash process can give the same
effect, but in some environments, encryption might be faster than hashing.
Consider the use of the CIPHER-class keys rather than the more general DATA-class keys because the
CIPHER-class keys have reduced capabilities and thus offer fewer opportunities for misuse.
IMPORTER and EXPORTER

You use a key in these key classes to set up a one-way key-distribution channel. In fact, it is generally
considered inappropriate to have the same key-value encrypted as both an IMPORTER and as an
EXPORTER on the same CCA node. You can use the functionality of the Key_Generate verb and the
one-way key-distribution channel to distribute CCA asymmetric DES keys to node pairs.
For example, a data originator can encipher data and be sure that no one can decipher the data on his
node using an ENCIPHER-class key. The DECIPHER-class copy of the key, probably with the CCA
export-allowed control-vector bit turned off, can be sent over the one-way key-distribution channel to
another node. Only there can the data be deciphered.
As another example, a key-distribution center can originate and distribute a no-export-allowed MAC key to
one node and the matching MACVER key, also with the no-export-allowed attribute, can be sent to
another node. In this scenario (and if the CCA master keys are managed and audited in a secure manner),
the MAC verification node has no means of producing a valid MAC on altered data.
PINGEN and PINVER

You can segregate the ability to create a PIN value from the ability to validate a PIN value (and PIN
offsets, PVV values, and so on).
OPINENC and IPINENC

As with one-way key-distribution channels, you can set up one-way encrypted PIN-block distribution
channels. This can enable you to further segregate which nodes in your network can perform various
forms of PIN processing.
Clear key parts

Typically, two or more users each install a key part to instantiate a cryptographic key. The key parts are
exclusive-ORed together to form the final key. CCA supports this option with the Key_Part_Import and
Master_Key_Process verbs. You can force the separation of key-part installation into two groups by
enabling the first-part capability and the key-part-combine capability in different roles. You can also use
different roles for processing master keys versus other key types.
The Key_Part_Import verb provides additional separation in functional capability. The preexisting Combine
Key Parts command (X'001C', invoked with the MIDDLE and LAST keywords) processes key-part
information and completes a key by turning off the key-part control-vector bit. Two new options are added:

v Use the Add Key Part command (X'0278'), invoked with the ADD-PART keyword, to exclusive-OR
additional information into an incomplete key.
v Use the Complete Key Part command (X'0279'), invoked with the COMPLETE keyword, to turn off the
key-part control-vector bit.
These commands enable you to designate an individual with the authority to accept a key without
providing that individual with the possibility of modifying the value of the key.
Pre-exclusive-OR
Additional information, such as a variant or a control-vector value, can be exclusive-ORed into a
key-encrypting key so other keys processed with the modified key-encrypting key can be assigned
alternative control vectors and alternative functionality. This pre-exclusive-OR technique can be
valuable when exchanging keys with non-CCA systems. However, an adversary, if permitted to
employ the technique, could change the control vector of a key to his advantage. To counter this
threat, separate key-part loading responsibilities so that an individual can oversee the operations
and complete a key without having the authority to add information to the key.
Clear key-part interception
Key-part information flows in the clear through your host system. If you view this as an
unacceptable risk, consider the following alternatives:
Random generation of master keys
If you need to backup the master key or have the same master key in an additional
coprocessor, use master-key cloning to securely transfer the value of the master key to
additional coprocessors.
Random key-generation and RSA-based key-distribution
Distribute RSA-encrypted, randomly generated DES data or DES key-encrypting keys to
the node where the key should be instantiated. With CCA and this strategy, you do not
need key parts or secrecy. Continue to use two-channel distribution techniques to ensure
integrity of the public-key distribution. This is true even when certificates are in use; you
must provide integrity for the top-level public key.
Key export
Be careful when allowing the export of keys from your system, especially when enabling the
Symmetric_Key_Generate verb and the other key-export verbs:
v Data_Key_Export
v Key_Export
In particular, the verbs Symmetric_Key_Export and Symmetric_Key_Generate permit the export of selected
classes of keys under any public key. Ensure that the target nodes are legitimate and that only appropriate
processes have use of these verbs, EXPORTER keys, and public keys.
Consider taking advantage of the export-allowed control-vector bit. By switching this bit off, you can
prevent a key from being exported.
Note: Master-key-encrypted RSA private keys or retained RSA private keys cannot be exported from a
CCA node.
Key unwrapping
An RSA private key that is used in a symmetric-key exchange to unwrap or decrypt a DES key should not
typically be allowed to perform digital signature signing. This is because the Digital_Signature_Generate
verb could be used with the ZERO-PAD keyword to reveal the DES key. To prevent this from happening,

generate RSA keys used for symmetric key-exchange with their key-usage flag bits set to KM-ONLY. The
key-usage flag bits should not be set to KEY-MGMT, as this allows the key to be used for both symmetric
key exchange and digital signature signing.
Clear-key operations
Remember that the following CCA verbs operate with keys in the clear. Carefully consider using them.
CSNDSYX A clear, unprotected public key is entered under which DATA keys can
Symmetric_Key_Export be enciphered. This operation can be disallowed through the
access-control system.
This is a potentially insecure operation. Any DATA key with the

XPORT-OK bit on in the control vector (bit 17) can be exported to the
owner of the associated private key.
CSNDSYG A clear, unprotected public key is entered under which a freshly
Symmetric_Key_Generate generated KEK or DATA key can be created. This operation can be
disallowed through the access-control system.
This is a potentially insecure operation if you set up a key-distribution

channel with an inappropriate public key. Be sure that you know who
has access to the associated private key.
CSNBCKI Either 8 or 16 bytes of clear information can be accepted to be
Clear_Key_Import returned as an encrypted DATA key. This operation can be disallowed
CSNBCKM through the access-control system. The clear-key information could be
Multiple_Clear_Key_Import intercepted as it is transmitted to the coprocessor. Consider freshly
generating a key using Key_Generate.
CSNBKPI This verb requires use of two commands (using the FIRST, with
Key_Part_Import MIDDLE and LAST keywords), or three commands (using the FIRST,
with ADD-PART and COMPLETE keywords) to complete the
establishment of a productive key of any type. The key information is
passed in the clear. These operations can be disallowed through the
access-control system.
The access controls can enforce a dual-control, split-knowledge

security policy, but the key components still pass across the general
interface in the clear. As an alternative, consider using
Symmetric_Key_Import and Key_Import to receive keys from another
source.
An adversary might be able to change the value of a key by employing

the MIDDLE or ADD-PART keywords. If the key were for an
IMPORTER or EXPORTER, this could be used later to alter the control
vector of an imported or exported key. This pre-exclusive OR technique
is sometimes viewed as a legitimate means for altering control vectors.
(See Pre-exclusive-OR on page 729 and Clear key-part interception
on page 729 for more information.)
CSNBMKP Use of the FIRST, MIDDLE, and LAST keywords employs clear data to
Master_Key_Process establish the value of a master key. These operations can be
disallowed through the access-control system. The preferred means to
establish a master key is through random generation (RANDOM
keyword) or through the master-key cloning process. (See Clear
key-part interception on page 729 for more information.)
| CSNDDSG The ZERO-PAD option allows a hash value to be specified that can be
| Digital_Signature_Generate up to the length of the modulus of the RSA key. If the hash is in fact a
public-key-encrypted key, the key can be recovered in the clear. RSA
keys intended for key management should be restricted to that usage
by specifying KM-ONLY in PKA_Key_Token_Build and
PKA_Key_Generate.

DES replicated keys
A replicated key is defined as a double-length DES key having equal left and right halves. Such a key
performs as a single-length key. Because CCA always uses double-length key-encrypting keys and
PIN-processing keys, it is sometimes advantageous to generate or install replicated keys to inter-operate
with non-CCA systems that are using single-length DES keys. Be careful in permitting the generation and
use of replicated keys as overcoming the work factor to attack single-length DES keys might be within the
capability of certain adversaries. You can block the generation of replicated DES keys in the
Key_Generate and the Diversified_Key_Generate verbs by not enabling optional commands.
The Key_Import, Key_Export, Data_Key_Import, and Data_Key_Export verbs do not permit use of a
replicated key-encrypting key to import or export a non-replicated key unless special permission is granted
using the unrestrict commands, X'0276', X'0277', X'027B', and X'027C'.
RSA keys
When generating RSA key pairs, you must consider these issues:
v Regeneration data (excluding ECC key pairs)
v Attributes for signature and key management
v Retained keys (not valid with an ECC private key)
Regeneration data
When an application calls the PKA_Key_Generate verb to generate a non-ECC key pair, it can specify
regeneration_data that seeds the random number generator. If the same regeneration data is supplied in
the future, the same RSA key-pair is generated. This can be useful in a development environment, but is
inappropriate in a production environment.
The access control system only allows use of regeneration data when you enable command X'027D',
Permit Regeneration Data.
Attributes for signature and key management

The skeleton key-token that an application provides when calling the PKA_Key_Generate verb assigns
usage attributes to the generated private key. You can assign attributes that only permit the key to perform
in digital signature generation or only in unwrapping or importing symmetric keys, or you can assign
attributes that enable the key to generate both digital signatures and unwrap keys.
If you use the Digital_Signature_Generate verb with the ZERO-PAD option and supply a wrapped
symmetric key, the verb decrypts the wrapped key and an application can then recover the symmetric key
in the clear. This most likely is undesirable. Generally, private keys intended for use in key-management
applications should be generated with the KM-ONLY attribute to block the use of the key in the
Digital_Signature_Generate verb. For private keys used to generate digital signatures, consider applying
the SIG-ONLY attribute.
Retained keys
In some applications you must not release an RSA private key in any form from the device in which it is
generated. Using the RETAIN keyword with the PKA_Key_Generate verb prevents the coprocessor from
outputting the private key. Alternative choices permit the key to be returned to the application wrapped
under the master key or a transport key, or returned in the clear with access-control permission.
You can confirm that a key has been generated and retained in the coprocessor using the
Retained_Key_List verb and the verification of a digital signature made with the retained key. Because no
means exist to import an RSA private key into retained-key storage, the list of key labels returned from the
Retained_Key_List verb demonstrates the existence of a particular named key. You can confirm that the
same label does not exist in host-system key-storage using the PKA_Key_Record_List verb.

PIN data considerations
A personal identification number (PIN) is generally passed across the CCA interface as an encrypted
object in an encrypted PIN-block. Typically, verbs protect PIN values using encryption. The exceptions are
described in the following table:
Table 171. PIN data exceptions
Verb Exception to protected PIN value
Clear_PIN_Encrypt (CSNBCPE) Encrypts a clear-PIN value and returns the result under an OPINENC class key.
This operation can be disallowed through the access-control system.
Unrestricted usage can permit the construction of a dictionary of encrypted PIN

values.
Clear_PIN_Generate Generates the PIN for a given account number. This operation can be disallowed
(CSNBPGN) through the access-control system.
Unrestricted usage permits the generation of PIN numbers for the specified
account numbers, using information that can be known to an adversary.
Validating coprocessor status data

Status is returned from the CCA application through the Access_Control_Maintenance and
Cryptographic_Facility_Query verbs. An adversary with access to the computing system could alter
coprocessor status responses.
Certain status information can be obtained from the Miniboot component of the coprocessor through the
coprocessor load utility (CLU). This response is signed and can be validated using the CLU utility.
RS-232 port
All CCA input and output is via the embedded control program within the coprocessor. The embedded
control program of the 4764 PCI-X Cryptographic Coprocessor provides a device driver for the RS-232
communications port which is integral to the coprocessor. For the 4765 PCIe Cryptographic Coprocessor,
the embedded kernel provides a device driver for its RS-232 communications port. A second RS-232
communications port on the PCIe coprocessor is strictly for use by the MicroBlaze soft processor.
However, the standard CCA application program makes no use of the ports and, therefore, they are
functionally inert. No information from or to the standard implementation of CCA will pass over the RS-232
port interface.
Master-key cloning
If you employ master-key cloning, then the distribution of shares needs to be accommodated, perhaps with
a unique role and profile for the individual permitted to process sharen. Registering the public key of the
authorization node should be split between two users such as SO1 and SO2. See Table 170 on page 726.
Sample access-control regimes

The CCA access-control system is quite flexible so as to accommodate a wide variety of needs. Your task
is to balance simplicity of operation against the requirements for a secure installation. This section
discusses several cases as an introduction to establishing your access-control regime.
v Considerations for a digital-signing server
v Considerations for a secured code-signing node

Digital-signing server
The European Union has issued a directive outlining the requirements for equipment and software to
qualify for use in certain Public Key Infrastructure (PKI) applications. In compliance with the directive,
individual countries such as Germany have issued detailed requirements for evaluations under the
Common Criteria. In IBM's opinion, the IBM 4765 and IBM 4764 operating with the CCA Support Program
can be employed as a hardware security module (HSM) in PKI CA, RA, OCSP responder,11 and
time-stamp authority applications in compliance with the directive.
The remainder of this section outlines considerations for use of the IBM 4765 and IBM 4764 consistent
with the high-security requirements of these application areas. The IBM 4765 and IBM 4764 with CCA
offer many capabilities. If you choose to deviate from some of the guidelines in this section, for example,
to achieve greater flexibility in operation, be sure to review the earlier portions of this section for guidance.
The guidelines are organized under these topics:

v Application environment
v Threat considerations
v Security objectives
v Application requirements
v Policy requirements
v Operational requirements and plan
Application environment
The application environment includes a computing system and the surrounding policies, personnel, and
physical security to address Public Key Infrastructure CA, RA, OCSP responder, or time-stamping
services. An application program must be selected that employs CCA and the coprocessor, and that
implements the desired services. The application program must be reviewed against the guidelines
discussed in the section Application requirements on page 734. The organization must install an IBM
4765 or IBM 4764 Coprocessor and the CCA Support Program. The organization will need to observe the
requirements discussed in sections Policy requirements on page 735 and Operational requirements and
plan on page 736.
The security functions of the coprocessor do not rely on the correctness of the host software or the fact
that this software is not tampered with or bypassed. But, of course, for the coprocessor to be useful,
functions of the host system need to execute correctly. For example, if a human user wants a document to
be signed, it is a requirement that the host software ensure that (1) the document displayed to the user is
represented by a hash of the document, and that (2) the hash is forwarded unaltered to the coprocessor
for inclusion in the digital signature.
Threat considerations
Appendix E, "Threat considerations for a digital-signing server" in the IBM 4765 PCIe Cryptographic
Coprocessor CCA Support Program Installation Manual and in the IBM 4764 PCI-X Cryptographic
Coprocessor CCA Support Program Installation Manual contain a list of threats which should be
considered specific to a digital-signing server. For each threat, the appendix describes how the
coprocessor and the CCA Support Program address the threat and/or actions the using organization
should take to mitigate the exposure. As your plans for using the coprocessor evolve, periodically check
them against requirements noted in the appendix.
Security objectives
The security objectives can be broken into two broad classes:
v Objectives met by the coprocessor and its internal software
v Objectives to be met by the using organization
11. CA: Certification Authority; RA: Registration Authority; OCSP responder: Open Certificate Status Protocol responder.

Objectives met by the coprocessor and its internal software: The coprocessor will, when configured
and operated as subsequently described:
1. Create industry-standard digital signatures
2. Not reveal the private signing key
3. Generate an RSA key-pair in compliance with appropriate standards
4. Employ the RSA algorithm in compliance with appropriate standards
5. Enable control of the setup and use of the coprocessor and signing key
6. Without revealing internal security information, withstand normal and adversarial environmental
stresses including: physical attacks, abnormal power, temperature, and, on the IBM 4764 only,
radiation conditions
7. Withstand attacks based on repetitive probing and/or the insertion of false data
8. Enforce a defined sequence of setup operations leading to normal operation
9. Not reveal sensitive information regardless of the number and sequence of requests
10. Ensure the integrity of the electronics and internal software, and provide proof of same
11. Verify the integrity of a signing request and the user's rights to the service
Objectives to be met by the using organization: The using organization must meet these security
objectives without placing further requirements on the coprocessor:
1. Provide a system environment including host computer, operating system, application program(s), and
data repositories that provide the normal operating environment for the coprocessor
2. Provide for secure data storage for sensitive information such as user passphrases
3. Provide trusted, trained individuals to perform as subsequently described
4. Perform the setup and normal operations according to the guidelines in subsequent sections
5. Monitor for and respond to error situations that could represent a deviation from normal operation
Application requirements
The selected application must:
1. Employ the CCA interface as described in the appropriate IBM 4765 or IBM 4764 publications:
v This CCA Basic Services Reference and Guide
v The IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual or the
IBM 4764 PCI-X Cryptographic Coprocessor CCA Support Program Installation Manual
2. Generate an RSA key-pair which meets these requirements:
a. Has an appropriate key-length, 1024 + 256 * s, where 0 s 8
b. Flags the key for use only in digital signature operations12
c. Extends the skeleton key-token to obtain a self-signature that incorporates the coprocessor serial
number and application-supplied information 13
d. Is retained within the coprocessor14
e. Is not generated with reference to any regeneration data15
f. Makes known the key label used to access the private key so that an auditor might confirm that a
retained key is in use16
12. Employ a skeleton key-token (from the PKA_Key_Generate verb) with the SIG-ONLY (signature only) attribute.
13. The application might permit the introduction of a nonce to be included in the self-signed public-key certificate returned from the
PKA_Key_Generate verb. Note that this does not guarantee that the private key exists in a coprocessor, but does provide
additional assurance and integrity on the public-key value.
14. Use the RETAIN rule-array keyword on the PKA_Key_Generate verb.
15. The regeneration_data_length variable in the PKA_Key_Generate call must be valued to zero.
16. The key label also must not exist in the key storage of the host system.

3. Generate digital signatures using a call to the Digital_Signature_Generate (CSNDDSG) verb, naming
the retained private key generated in the prior step and employing either the ISO-9796, PKCS-1.0,
PKCS-1.1, or the X9.31 hash-formatting method.
4. Support logon operations via the CSUALCT verb (Logon_Control) on the processing threads which
invoke key generation and digital-signature generation.
5. Output the public-key value and the key label used to access the retained private-key.
6. Ensure that the application can operate properly in an environment with the access-control restrictions
listed in Table 172 on page 738.
Policy requirements
These policy requirements are focused on the coprocessor and must be augmented through consideration
of the host-system operating system and digital-signing application, the physical environment, and so forth,
which are necessarily unique to each installation.
Policy requirements address subjects including:

v Required tasks
v Personnel assignments
Required tasks: The organization must establish a complete set of rules (policy) governing the selection,
installation, commissioning, operation, decommissioning, and auditing of the proposed digital-signing
server. With reference to the coprocessor, consider these items:
1. Refer to Appendix E, "Threat considerations for a digital-signing server" in the IBM 4765 PCIe
Cryptographic Coprocessor CCA Support Program Installation Manual or in the IBM 4764 PCI-X
Cryptographic Coprocessor CCA Support Program Installation Manual to check your decisions.
2. Assign individuals to roles as discussed in Personnel assignments.
3. Identify, procure, install, and test a host-system computer paying attention to the security requirements
which the operating system should support. You need to limit the exposure from rogue processes
which might:
v Intercept passphrases
v Modify the data to be signed after the data has been approved for signing
v Substitute an alternative cryptographic process that could be subverted
4. Install an IBM cryptographic coprocessor and CCA software and prerequisite software as documented
in the IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation Manual or the
IBM 4764 PCI-X Cryptographic Coprocessor CCA Support Program Installation Manual.
v The CCA Support Program software must be installed as indicated in Chapters 3, 4, and up through
the section entitled "How to establish a test node" in the IBM 4765 PCIe Cryptographic Coprocessor
CCA Support Program Installation Manual or the IBM 4764 PCI-X Cryptographic Coprocessor CCA
Support Program Installation Manual.
v An auditor should use the CLU utility VA command to confirm that the code loaded in the
coprocessor is validated, has the correct release identifiers, and has SEG2 and SEG3 owner
identifiers valued to 2.
5. Identify, procure, install, and test a host-system application program that conforms to your
requirements and which can employ the coprocessor within the constraints described under the
Application requirements on page 734.
6. Limit access to the environment of the coprocessor.
7. Make maximum use of host-system security features.
8. Carry out the tasks detailed in Operational requirements and plan on page 736.
9. Provide for periodic audit review of the system and associated records.
Personnel assignments: Related to the use of the coprocessor, assign and train individuals to serve in
these capacities:

Installer
An individual or team who makes the initial installation of the hardware and software for the
application environment.
Administrator
An individual17 responsible for the Setup phase of the installation, including promoting the system
to the key generation phase.
The individual might be granted authority and technical capability to terminate normal production,
or such authority and capability might be granted to another person such as an auditor.
Auditor
An individual responsible for confirming that the installation is in an appropriate condition for
entering and continuing in production, and who can report problems to authorities independent
from others involved with the system.
The auditor might be granted authority and technical capability to terminate normal production, or
such authority and capability might be granted to an additional auditor.
Key Generator
An individual responsible for the key-pair generation phase of operation. This individual might also
be responsible for obtaining certification of the generated public key. (You might incorporate this
responsibility in the role of either the administrator or the signer.)
Signer
An individual responsible for conditioning the system to use the digital-signing key.
Operational requirements and plan

These operational requirements and plan steps are focused on the coprocessor and must be augmented
through consideration of the host-system operating system and digital-signing application, the physical
environment, and so forth, which are necessarily unique to each installation.
The secure usage of the coprocessor is dependent on the definition of roles in accordance with a specific
usage policy. A role defines a set of permissible coprocessor commands. To perform a CCA verb (service)
requires the use of one or more commands. A command is enabled by a permission in the active role. If
the caller of a verb is not logged on, the DEFAULT role is active. There is always a DEFAULT role. A user
might log on by referencing his profile and presenting his passphrase. The user's profile identifies a role
which expresses his permissions to enable commands and thus CCA verbs.
The CCA Support Program provides considerable flexibility in the configuration of roles. Other suitable
ways to set up a secure CCA system as a digital-signing server exist beyond the example described here.
For more details of the concept of roles within the coprocessor, see the introductory material in Chapter 2,
CCA node management and access control, on page 13 and Appendix G, Access-control-point codes,
on page 715.
The plan should address these phases of activity related to the coprocessor:
Checkout
In this phase, the hardware and software are installed and preliminary tests are performed,
individuals are trained, and so forth. Refer to the CCA Support Program Installation Manual.
Setup
In this phase, the specific set of access controls are established by the administrator, as listed in
Table 172 on page 738. Perform these steps:
1. Begin this activity by reinstalling the CCA software using the CLU utility and the software file
CNWxxxxx.CLU as described in the section, "Loading software into the coprocessor" of the CCA
Support Program Installation Manual.
17. Two or more administrators might be assigned to work together to ensure that the required tasks, and no more, are performed
correctly and in sequence. An objective is that the administrators will not collude with each other.

2. The auditor must (re)confirm that the proper CCA Support Program software is installed and that
the SEG2 and SEG3 segment identifiers are 2. (Use the CLU utility. Refer to the section entitled
"Loading software into the coprocessor" of the CCA Support Program Installation Manual. The
auditor might also wish to confirm that the remainder of the CCA Support Program has been
loaded from the product Web site, http://www.ibm.com/security/cryptocards)
3. Follow the procedure listed in the section "How to establish a test node" of the CCA Support
Program Installation Manual to condition the CCA application within the coprocessor.
4. Create the specific roles as listed in Table 172 on page 738.
5. Create the profiles you will require to access the roles. Each individual should have his own
profile. It is technically possible to have multiple individuals (and therefore profiles) able to
access a single role. Your installation policy will dictate what profiles to establish.
6. Update the DEFAULT role with the permissions defined for the OP-DEF role. See Table 172 on
page 738.
7. Delete profile(s) that point to the SETUP role. This prevents the addition or modification of roles
and profiles.
8. The auditor should (re)verify:
v The installed software including the code loaded in SEG2 and SEG3, ensuring that the
segment owner identifiers are valued to 2.
v The set of installed profiles and roles, and the permissions in each role. (Use the CNM utility
or other trusted tool.)
9. Have the individual users modify the passphrase for their profiles by signing on to the SETUP-1
role. Then delete profile(s) that point to the SETUP-1 role. Note that any user's passphrase can
be changed when the Change User Profile Authentication Data command (X'0114') is enabled.
10. Have the auditor:
v Confirm that the profiles which invoke the SETUP-1 role have been deleted
v Obtain test patterns for the current and old master keys
Key generate
Have the key-generator:
1. Generate the required public-private key(s). Note the key label which the application program
uses to reference the generated key-pair.
2. Then generate a random master key and set this master key. Repeat this process so that both
the current-master-key and old-master-key registers contain random, unknown master keys. (This
prevents the use of any preexisting master-key-encrypted private keys. You can use the CNM
utility.)
3. Have the auditor:
v Confirm that the master-key test patterns obtained earlier will not verify either the current or the
old master key. (You can use the CNM utility.)
v Confirm the existence of the key label of the retained private key in the coprocessor through
the use of the Retained_Key_List verb. (You can use the CNM utility.)
v Observe the generation and verification of a test message. The public key might be used in
another system to validate both the test digital signature and the self-signature on the
generated public key.
Sign (production)
1. Use the SIGNER role and the Digital_Signature_Generate verb to sign appropriate messages.
2. Delete profiles as might be required to invalidate specific users. (You can use the CNM utility and
whatever role you have established with the Delete User Profile command, offset X'0117'.)
Note that deleting all of the profiles that permit digital-signature generation effectively terminates
the production phase.
3. Delete a specific retained private-key as might be required using the Retained_Key_Delete verb.
(You can use the CNM utility and whatever role you have established, if any, with the Delete
Retained Key command, offset X'0203'.)
Decommission
Clear the coprocessor of any residual information, including retained private keys and access-control
information, by using the CLU utility with the file CRSxxxxx.CLU file.
The auditor should use the CLU utility to confirm that SEG2 is unowned.

(Alternatively you could use the Cryptographic_Facility_Control verb if you had established a profile
and a role with the Reinitialize Device command, offset X'0111'. The auditor should confirm that there
are no retained private keys and that he is working from a role with all permissions.)
Table 172 describes possible roles and appropriate permissions.

Table 172. Roles and permissions for a digital-signing server
Roles Permissions
DEFAULT All
This role is used to verify reasonable (Use the "Enable All" button in the CNM utility.)
operation of the installed hardware
and software. Once checkout is
complete and setup is underway, this
role is replaced by the OP-DEF role
(Operational Default) and the other
roles described next.
SETUP X'001A', (MKP) Set Master Key
X'001D', (KSI) Compute Verification Pattern
Use this role during initial application X'0020', (MKP) Generate Random Master Key
testing and establishment of roles and X'0101', (DSV) Digital_Signature_Verify
profiles. Once proper operation is X'0107', (OWH) One-Way Hash, SHA-1
confirmed, delete the profile(s) which X'010F', (CFC) Reset Intrusion Latch
activates this role. This role permits X'0110', (CFC) Set Clock
alteration and extension of the X'0111', (CFC) Reinitialize Device
access-control regime. X'0112', (ACI) Initialize Access-Control System
X'0113', (ACI) Change User Profile Expiration Date
X'0114', (ACI) Change User Profile Authentication Data
X'0115', (ACI) Reset User Profile Logon-Attempt-Failure
Count
X'0116', (ACM) Read Public Access-Control Information
X'0117', (ACM) Delete User Profile
X'0118', (ACM) Delete Role
X'0119', (CFC) Load Function-Control Vector
X'011A', (CFC) Clear Function-Control Vector
X'011C', (CFC) Set EID
X'0203', (RKD) Delete Retained Key
X'0230', (RKL) List Retained Key Names
SETUP-1 X'001D', (KSI) Compute Verification Pattern
Use this role to alter the passphrases X'0115', (ACI) Reset User Profile Logon-Attempt-Failure
of users. Once passphrases have Count
been changed, delete the profile(s) X'0116', (ACM) Read Public Access-Control Information
which activates this role. X'0117', (ACM) Delete User Profile
OP-DEF Operational Default X'001D', (KRL) Compute Verification Pattern
X'0101', (DSV) Digital_Signature_Verify
The role permits very limited X'0107', (OWH) One-Way Hash, SHA-1
functionality when no user is logged X'0116', (ACM) Read Public Access-Control Information
on.
AUDITOR X'001D', (KRL) Compute Verification Pattern
X'0101', (DSV) Digital_Signature_Verify
Use this role to query the X'0107', (OWH) One-Way Hash, SHA-1
access-control setup and to confirm X'0111', (CFC) Reinitialize Device
that the profiles which employ the X'0116', (ACM) Read Public Access-Control Information
setup roles are deleted. The role X'0117', (ACM) Delete User Profile
permits confirmation of retained-key X'0203', (RKD) Delete Retained Key
labels. X'0230', (RKL) List Retained Key Names

Table 172. Roles and permissions for a digital-signing server (continued)
Roles Permissions
KEY-GEN Key Generator X'001A', (MKP) Set Master Key
Use this role to generate RSA X'0020', (MKP) Generate Random Master Key
key-pair(s) through the use of the X'0230', (RKL) List Retained Key Names
PKA_Key_Generate verb. X'0103', (PKG) PKA Key Generate
SIGNER X'001D', (DSG) Compute Verification Pattern
X'0100', (DSG) Digital Signature Generate
Use this role to create digital X'0101', (DSV) Digital Signature Verify
signatures through the use of the X'0103', (PKG) PKA_Key_Generate
Digital_Signature_Generate verb. X'0107', (OWH) One-Way Hash, SHA-1
X'0203', (RKD) Delete Retained Key
(...), the last three letters in the verb entry-point name
An optional command
Possibly an auditor should be able to disable use of the cryptographic facility or a specific key. Enablement of
these commands for the auditor is an application design issue.
Alternatives to the role scheme: These variations to the role scheme can be considered:
Key Generation
You can eliminate the role used specifically for key generation and grant that authority to any one
of the SIGNER, SETUP-1, or SETUP roles.
An advantage of the distinct KEY-GEN role is an improved procedure for enabling the auditor to
confirm the appropriateness of the generated key prior to productive use.
An advantage in permitting the signer to generate the key lies in the fact that the signer is
responsible for use of the key.
Permitting the SETUP role to generate the key can reduce the number of roles. However, note
that under the SETUP role, the access controls remain changeable. It might be advantageous to
delay key generation until the access controls are rendered unchangeable.
Private Key Deletion
The private key(s) can be deleted by zeroizing the segment 2 and segment 3 software. It is also
possible to delete a retained private-key using the Retained_Key_Delete verb which uses the
Delete Retained Key command (X'0203'). You should decide when and who will have the
responsibility for key deletion (zeroization). As appropriate, enable the Delete Retained Key
command in any of the defined roles.
Passphrase Changes
You can eliminate the SETUP-1 role if you have the user passphrases set using the SETUP role.
The SETUP-1 role enables an auditor to first check the roles prior to having the various users
come and establish their passphrases.
Secured code-signing node

IBM offers Toolkits for creating custom code that runs in the coprocessor. When development of the
custom code is complete, the code can be digitally signed so that coprocessors will accept the code and
report ownership under the identifier assigned to the developer. Using the Signer and Packager utilities
provided in the Toolkit, the access controls for the code-signing CCA node can enable control over the
generation and use of the private keys.

Two private keys are used by the Signer utility, and a third key is used by the Packager utility. The Signer
utility can be used to generate all three keys using the CRUSIGNR KEYGEN 0 command as described in
the IBM 4765 PCIe Cryptographic Coprocessor Custom Software Developer's Toolkit Guide or the IBM
4764 PCI-X Cryptographic Coprocessor Custom Software Developer's Toolkit Guide. The private keys are
encrypted by the CCA master keys. To backup the private keys, make duplicate copies of the key files
created by the Signer utility. Consider use of master-key cloning to another coprocessor so that any loss of
the master key on the primary signing node will still enable use of the key files on the backup node.
Before continuing with this material, you should understand the introductory material in Chapter 2, CCA
node management and access control, on page 13 and Appendix G, Access-control-point codes, on
page 715.
Consider use of these roles:

Initial Default
Use this or a similar default role to check out the coprocessor installation and CCA software. Refer to
the section entitled "How to establish a test node" in the CCA Support Program Installation Manual.
At the conclusion of the checkout, zeroize the node. Refer to the section entitled "How to initialize
(zeroize) the node" in the CCA Support Program Installation Manual.
Setup
Use this role during node set up exclusive of master-key cloning, RSA key-generation, and code
signing digital-signature generation. This role permits modifications to the access-control system,
therefore, use of the role should be disabled prior to normal operations so as to lock the
access-control system. Delete all profiles that enable this role using Access_Control_Maintenance
with the DEL-PROF keyword, or that command via the CNM utility.
Auditor
Use this role prior to the start of normal operations, and later as required, to confirm the
access-control system settings.
The auditor should confirm that the roles and profiles within the coprocessor are appropriate.
The auditor might also be assigned the right(s) to zeroize the entire cryptographic node.
Administrator-1
An individual authorized to participate in master-key creation and optionally in cloning of master keys.
Administrator-2
An individual authorized to participate in activating master keys and therefore the CCA node(s), and
optionally in cloning of master keys.
Key-Generator
An individual authorized to generate the code-signing keys. Also generate the public-private key-pairs
used in master-key cloning.
Signer
An individual authorized to use the code-signing keys. If using master-key cloning, also certifies the
master-key cloning CSS and CSR keys.
Table 173 describes possible roles and appropriate permissions.

Table 173. Roles and permissions for a simple certification authority case
Roles Permissions
Initial default All
This role is used to verify reasonable (Use the "Enable All" button in the CNM utility.)
operation of the installed hardware
and software. Once initial checkout is
complete, this role is replaced by the
Operational Default role and the other
roles described next.

Table 173. Roles and permissions for a simple certification authority case (continued)
Roles Permissions
Setup X'001A', (MKP) Set Master Key
This role can be used during initial X'0020', (MKP) Generate Random Master Key
application testing and establishment X'0101', (DSV) Digital_Signature_Verify
of test roles. Once proper operation is X'0107', (OWH) One-Way Hash, SHA-1
confirmed, the profile(s) which X'010F', (CFC) Reset Intrusion Latch
activates this role should be deleted X'0110', (CFC) Set Clock
because it can be used to alter and X'0111', (CFC) Reinitialize Device
extend the access-control regime. X'0112', (ACI) Initialize Access-Control System
X'0113', (ACI) Change User Profile Expiration Date
X'0115', (ACI) Reset User Profile Logon-Attempt-Failure
Count
X'0116', (ACM) Read Public Access-Control Information
X'0117', (ACM) Delete User Profile
X'0118', (ACM) Delete Role
X'0119', (CFC) Load Function-Control Vector
X'011A', (CFC) Clear Function-Control Vector
X'011C', (CFC) Set EID
X'011D', (CFC) Initialize Master Key Cloning
Operational default X'0116', (ACM) Read Public Access-Control Information
(Replaces Initial Default.)
This role is in effect if any call is made

to the CCA Coprocessor function from
a caller who has not successfully
logged on to the Coprocessor.
Auditor X'0107', (OWH) One-Way Hash, SHA-1
X'0111', (CFC) Reinitialize Device
This role is used to query the X'0116', (ACM) Read Public Access-Control Information
access-controls setup and to confirm X'0117', (ACM) Delete User Profile
that the profile(s) that could activate
the setup role have been deleted prior
to sanctioning start-up of normal
operations.
Administrator-1 X'0020', (MKP) Generate Random Master Key
X'0032', (MKP) Clear New Master Key Register
Establishes master key and works X'008E', (RNG) Generate Key (and random number)
with first of two-part key operations. X'0101', (DSV) Digital Signature Verify
X'0107', (OWH) One-Way Hash, SHA-1
X'0200', (PKH) Register Public Key Hash
X'0211', (MKD) Clone-info (Share 1) Obtain
X'0221', (MKD) Clone-info (Share 1) Install
Administrator-2 X'001A', (MKP) Set Master Key
X'0033', (MKP) Clear Old Master Key Register
Activates master key and work with X'008E', (RNG) Generate Key (and random number)
second of two-part key operations. X'0107', (OWH) One-Way Hash, SHA-1
X'0201', (PKR) PKA Public Key Register
X'0212', (MKD) Clone-info (Share 2) Obtain
X'0222', (MKD) Clone-info (Share 2) Install
Key generator X'008E', (RNG) Generate Key (and random number)
X'0103', (PKG) PKA Key Generate
Generates the code-signing RSA X'0107', (OWH) One-Way Hash, SHA-1
keys. Also generates the public-private X'0204', (PKG) PKA Clone Key Generate
key-pairs used in master-key cloning.

Table 173. Roles and permissions for a simple certification authority case (continued)
Roles Permissions
Signer X'008E', (RNG) Generate Key (and random number)
X'0100', (DSG) Digital Signature Generate
Uses the Signer and Packager utilities X'0101', (DSV) Digital Signature Verify
for signing code. If using master-key X'0107', (OWH) One-Way Hash, SHA-1
cloning, also certifies the master-key
cloning CSS and CSR keys.
(...), the last three letters in the verb entry-point name
An optional command
Possibly an auditor should be able to disable use of the cryptographic facility or a specific key. Enablement of
these commands for the auditor is an application design issue.

Appendix I. Java Native Interface
Beginning with Release 4.1, each CCA verb (excluding Key_Storage_Designate) described in this book
has both a C interface and a Java Native Interface (JNI). The JNI entry-point name is formed from the C
entry-point name by appending the letter "J" to the end of the C entry-point name. For example,
CSNBKGN is the C entry-point name for the Key_Generate verb, and CSNBKGNJ is the JNI entry-point
name for this verb.
An overview of the way in which users can build Java programs to use with the CCA Support Program is
provided in Chapter 7 of the IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program Installation
Manual. It includes:
v The procedure for compiling a program calling the CCA Java Native Interface (JNI)
v A sample Java routine for calling the CCA JNI
Table 174 gives the entry point names and JNI formats for each verb, and the page where the verb is
described in detail. The names are listed alphabetically.
Table 174. Format summary of JNI calls
JNI entry-point name JNI format Page
CSNBAKRCJ public native void CSNBAKRCJ(hikmNativeInteger return_code, 392
hikmNativeInteger reason_code, hikmNativeInteger exit_data_length,
byte[] exit_data, hikmNativeInteger rule_array_count, byte[] rule_array,
byte[] key_label, hikmNativeInteger key_token_length, byte[] key_token);
CSNBAKRDJ public native void CSNBAKRDJ(hikmNativeInteger return_code, 394
byte[] key_label);
CSNBAKRLJ public native void CSNBAKRLJ(hikmNativeInteger return_code, 396
byte[] key_label, hikmNativeInteger dataset_name_length,
byte[] dataset_name, byte[] security_server_name);
CSNBAKRRJ public native void CSNBAKRRJ(hikmNativeInteger return_code, 398
CSNBAKRWJ public native void CSNBAKRWJ(hikmNativeInteger return_code, 400
| CSNBCKCJ public native void CSNBCKCJ(hikmNativeInteger return_code, hikmNativeInteger 452
| reason_code, hikmNativeInteger exit_data_length, byte[] exit_data,
| hikmNativeInteger rule_array_count, byte[] rule_array, hikmNativeInteger
| key_a_identifier_length, byte[] key_a_identifier, hikmNativeInteger
| key_b_identifier_length, byte[] key_b_identifier, hikmNativeInteger
| output_key_identifier_length, byte[] output_key_identifier);
CSNBCKIJ public native void CSNBCKIJ(hikmNativeInteger return_code, 198
byte[] exit_data, byte[] clear_key, byte[] target_key_identifier);
CSNBCKMJ public native void CSNBCKMJ(hikmNativeInteger return_code, 301
hikmNativeInteger clear_key_length, byte[] clear_key,
byte[] key_identifier);
743
Table 174. Format summary of JNI calls (continued)
CSNBCPAJ public native void CSNBCPAJ(hikmNativeInteger return_code, 444
byte[] exit_data, byte[] inbound_PIN_encrypting_key_identifier,
byte[] PIN_generating_key_identifier, byte[] input_PIN_profile,
byte[] PAN_data, byte[] encrypted_PIN_block, hikmNativeInteger
rule_array_count, byte[] rule_array, hikmNativeInteger PIN_check_length,
byte[] data_array, byte[] returned_result);
CSNBCPEJ public native void CSNBCPEJ(hikmNativeInteger return_code, 438
byte[] exit_data, byte[] PIN_encrypting_key_identifier, hikmNativeInteger
rule_array_count, byte[] rule_array, byte[] clear_PIN, byte[] PIN_profile,
byte[] PAN_data, hikmNativeInteger sequence_number,
byte[] encrypted_PIN_block);
CSNBCSGJ public native void CSNBCSGJ(hikmNativeInteger return_code, 449
byte[] PAN_data, byte[] expiration_date, byte[] service_code,
byte[] CVV_key-A_identifier, byte[] CVV_key-B_identifier,
byte[] CVV_value);
CSNBCSVJ public native void CSNBCSVJ(hikmNativeInteger return_code, 456
byte[] PAN_data, byte[] expiration_date, byte[] service_code,
byte[] CVV_key-A_identifier, byte[] CVV_key-B_identifier,
byte[] CVV_value);
CSNBCVEJ public native void CSNBCVEJ(hikmNativeInteger return_code, hikmNativeInteger 205
reason_code, hikmNativeInteger exit_data_length, byte[] exit_data,
byte[] c-variable_encrypting_key_identifier, hikmNativeInteger
text_length, byte[] plaintext, byte[] initialization_vector,
byte[] ciphertext);
CSNBCVGJ public native void CSNBCVGJ(hikmNativeInteger return_code, hikmNativeInteger 200
byte[] key_type, hikmNativeInteger rule_array_count, byte[] rule_array,
byte[] reserved, byte[] control_vector);
CSNBCVTJ public native void CSNBCVTJ(hikmNativeInteger return_code, hikmNativeInteger 203
byte[] KEK_key_identifier, byte[] source_key_token,
byte[] array_key_left_identifier, byte[] mask_array_left,
byte[] array_key_right_identifier, byte[] mask_array_right,
hikmNativeInteger rule_array_count, byte[] rule_array,
byte[] target_key_token);
CSNBDECJ public native void CSNBDECJ(hikmNativeInteger return_code, hikmNativeInteger 360
byte[] key_identifier, hikmNativeInteger text_length, byte[] ciphertext,
byte[] initialization_vector, hikmNativeInteger rule_array_count,
byte[] rule_array, byte[] chaining_vector, byte[] plaintext);
CSNBDKGJ public native void CSNBDKGJ(hikmNativeInteger return_code, hikmNativeInteger 211
byte[] generating_key_identifier, hikmNativeInteger data_length,
byte[] data, byte[] data_decrypting_key_identifier,
byte[] generated_key_identifier);
CSNBDKMJ public native void CSNBDKMJ(hikmNativeInteger return_code, hikmNativeInteger 209
reason_code, hikmNativeInteger exit_data_lengthh, byte[] exit_data,
byte[] source_key_token, byte[] importer_key_identifier,
byte[] target_key_identifier);

CSNBDKXJ public native void CSNBDKXJ(hikmNativeInteger return_code, hikmNativeInteger 207
byte[] source_key_identifier, byte[] exporter_key_identifier,
byte[] target_key_token);
CSNBENCJ public native void CSNBENCJ(hikmNativeInteger return_code, hikmNativeInteger 363
byte[] key_identifier, hikmNativeInteger text_length, byte[] plaintext,
byte[] initialization_vector, hikmNativeInteger rule_array_count,
byte[] rule_array, hikmNativeInteger pad_character,
byte[] chaining_vector, byte[] ciphertext);
CSNBEPGJ public native void CSNBEPGJ(hikmNativeInteger return_code, hikmNativeInteger 459
byte[] PIN_generating_key_identifier,
byte[] outbound_PIN_encrypting_key_identifier, hikmNativeInteger
rule_array_count, byte[] rule_array, hikmNativeInteger PIN_length,
byte[] data_array, byte[] PIN_profile, byte[] PAN_data,
hikmNativeInteger sequence_number, byte[] encrypted_PIN_block);
CSNBHMGJ public native void CSNBHMGJ(hikmNativeInteger return_code, hikmNativeInteger 366
hikmNativeInteger rule_array_count, byte[] rule_array, hikmNativeInteger
key_identifier_length, byte[] key_identifier, hikmNativeInteger
message_text_length, byte[] message_text, hikmNativeInteger
chaining_vector_length, byte[] chaining_vector,
hikmNativeInteger MAC_length, byte[] MAC);
CSNBHMVJ public native void CSNBHMVJ(hikmNativeInteger return_code, hikmNativeInteger 369
message_text_length, byte[] message_text, hikmNativeInteger
chaining_vector_length, byte[] chaining_vector,
hikmNativeInteger MAC_length, byte[] MAC);
CSNBKETJ public native void CSNBKETJ(hikmNativeInteger return_code, hikmNativeInteger 224
kek_key_identifier_length, byte[] kek_key_identifier, hikmNativeInteger
key_in_length, byte[] key_in, hikmNativeInteger key_out_length,
byte[] key_out);
CSNBKEXJ public native void CSNBKEXJ(hikmNativeInteger return_code, hikmNativeInteger 227
byte[] key_type, byte[] source_key_identifier,
byte[] exporter_key_identifier, byte[] target_key_token);
CSNBKGNJ public native void CSNBKGNJ(hikmNativeInteger return_code, hikmNativeInteger 229
byte[] key_form, byte[] key_length, byte[] key_type_1, byte[] key_type_2,
byte[] KEK_key_identifier_1, byte[] KEK_key_identifier_2,
byte[] generated_key_identifier_1, byte[] generated_key_identifier_2);
Appendix I. Java Native Interface 745

CSNBKGN2J public native void CSNBKGN2J(hikmNativeInteger return_code, 239
hikmNativeInteger clear_key_bit_length, byte[] key_type_1,
byte[] key_type_2, hikmNativeInteger key_name_1_length, byte[] key_name_1,
hikmNativeInteger key_name_2_length, byte[] key_name_2, hikmNativeInteger
user_associated_data_1_length, byte[] user_associated_data_1,
hikmNativeInteger user_associated_data_2_length,
byte[] user_associated_data_2, hikmNativeInteger
KEK_key_identifier_1_length, byte[] KEK_key_identifier_1,
hikmNativeInteger KEK_key_identifier_2_length,
byte[] KEK_key_identifier_2,
hikmNativeInteger generated_key_identifier_1_length,
byte[] generated_key_identifier_1, hikmNativeInteger
generated_key_identifier_2_length, byte[] generated_key_identifier_2);
CSNBKIMJ public native void CSNBKIMJ(hikmNativeInteger return_code, hikmNativeInteger 245
byte[] key_type, byte[] source_key_token, byte[] importer_key_identifier,
CSNBKPIJ public native void CSNBKPIJ(hikmNativeInteger return_code, hikmNativeInteger 247
hikmNativeInteger rule_array_count, byte[] rule_array, byte[] key_part,
CSNBKPI2J public native void CSNBKPI2J(hikmNativeInteger return_code, 251
hikmNativeInteger clear_key_part_bit_length, byte[] clear_key_part,
hikmNativeInteger key_identifier_length, byte[] key_identifier);
CSNBKRCJ public native void CSNBKRCJ(hikmNativeInteger return_code, hikmNativeInteger 402
byte[] key_label);
CSNBKRDJ public native void CSNBKRDJ(hikmNativeInteger return_code, hikmNativeInteger 404
hikmNativeInteger rule_array_count, byte[] rule_array, byte[] key_label);
CSNBKRLJ public native void CSNBKRLJ(hikmNativeInteger return_code, hikmNativeInteger 406
byte[] key_label, hikmNativeInteger data_setname_length,
byte[] dataset_name, byte[] security_server_name);
CSNBKRRJ public native void CSNBKRRJ(hikmNativeInteger return_code, hikmNativeInteger 408
byte[] key_label, byte[] key_token);
CSNBKRWJ public native void CSNBKRWJ(hikmNativeInteger return_code, hikmNativeInteger 409
byte[] key_token, byte[] key_label);
CSNBKSIJ public native void CSNBKSIJ(hikmNativeInteger return_code, hikmNativeInteger 65
key_storage_file_name_length, byte[] key_storage_file_name,
hikmNativeInteger key_storage_description_length,
byte[] key_storage_description, byte[] clear_master_key);
CSNBKTBJ public native void CSNBKTBJ(hikmNativeInteger return_code, hikmNativeInteger 270
byte[] key_token, byte[] key_type, hikmNativeInteger rule_array_count,
byte[] rule_array, byte[] key_value, byte[] reserved_1, hikmNativeInteger
reserved_2, byte[] token_data_1, byte[] control_vector,
byte[] reserved_4, hikmNativeInteger reserved_5, byte[] reserved_6,
byte[] master_key_verification_pattern);

CSNBKTB2J public native void CSNBKTB2J(hikmNativeInteger return_code, 275
hikmNativeInteger clear_key_bit_length, byte[] clear_key_value,
hikmNativeInteger key_name_length, byte[] key_name, hikmNativeInteger
user_associated_data_length, byte[] user_associated_data,
hikmNativeInteger token_data_length, byte[] token_data,
hikmNativeInteger reserved_length, byte[] reserved,
hikmNativeInteger target_key_token_length, byte[] target_key_token);
CSNBKTCJ public native void CSNBKTCJ(hikmNativeInteger return_code, hikmNativeInteger 279
CSNBKTC2J public native void CSNBKTC2J(hikmNativeInteger return_code, 281
CSNBKTPJ public native void CSNBKTPJ(hikmNativeInteger return_code, hikmNativeInteger 283
byte[] key_token, byte[] key_type, hikmNativeInteger rule_array_count,
byte[] rule_array, byte[] key_value, hikmNativeInteger
master_key_version_number, hikmNativeInteger reserved_2,
byte[] reserved_3, byte[] control_vector, byte[] reserved_4,
hikmNativeInteger reserved_5, byte[] reserved_6,
byte[] master_key_verification_pattern);
| CSNBKTP2J public native void CSNBKTP2J(hikmNativeInteger return_code, 286
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length, byte[] exit_data,
| hikmNativeInteger key_token_length, byte[] key_token, byte[] key_type,
| key_material_state, hikmNativeInteger payload_bit_length, byte[]
| payload, hikmNativeInteger key_verification_pattern_type,
| hikmNativeInteger key_verification_pattern_length, byte[]
| key_verification_pattern, hikmNativeInteger key_wrapping_method,
| hikmNativeInteger key_hash_algorithm, hikmNativeInteger key_name_length,
| byte[] key_name, hikmNativeInteger TLV_data_length, byte[] TLV_data,
| hikmNativeInteger user_associated_data_length, byte[]
| user_associated_data, hikmNativeInteger reserved_length, byte[] reserved);
CSNBKTRJ public native void CSNBKTRJ(hikmNativeInteger return_code, hikmNativeInteger 294
byte[] input_key_token, byte[] input_KEK_key_identifier,
byte[] output_KEK_key_identifier, byte[] output_key_token);
CSNBKTR2J public native void CSNBKTR2J(hikmNativeInteger return_code, 296
hikmNativeInteger input_key_token_length, byte[] input_key_token,
hikmNativeInteger input_KEK_key_identifier_length,
byte[] input_KEK_key_identifier, hikmNativeInteger
output_KEK_key_identifier_length, byte[] output_KEK_identifier,
hikmNativeInteger output_key_token_length, byte[] output_key_token);
CSNBKYTJ public native void CSNBKYTJ(hikmNativeInteger return_code, hikmNativeInteger 256
| byte[] key_identifier, byte[] value_1, byte[] value_2);

CSNBKYT2J public native void CSNBKYT2J(hikmNativeInteger return_code, 261
hikmNativeInteger key_identifier_length, byte[] key_identifier,
hikmNativeInteger KEK_key_identifier_length, byte[] KEK_key_identifier,
| hikmNativeInteger reserved_length, byte[] reserved,
hikmNativeInteger key_verification_pattern_length,
byte[] key_verification_pattern);
CSNBKYTXJ public native void CSNBKYTXJ(hikmNativeInteger return_code, 265
byte[] exit_data, hikmNativeInteger rule_array_count,
| byte[] rule_array, byte[] key_identifier, byte[] value_1,
| byte[] value_2, byte[] kek_key_identifier);
CSNBMDGJ public native void CSNBMDGJ(hikmNativeInteger return_code, hikmNativeInteger 126
hikmNativeInteger text_length, byte[] text, hikmNativeInteger
rule_array_count, byte[] rule_array, byte[] chaining_vector, byte[] MDC);
CSNBMGNJ public native void CSNBMGNJ(hikmNativeInteger return_code, hikmNativeInteger 372
byte[] key_identifier, hikmNativeInteger text_length, byte[] text,
byte[] chaining_vector, byte[] MAC);
CSNBMKPJ public native void CSNBMKPJ(hikmNativeInteger return_code, hikmNativeInteger 74
hikmNativeInteger rule_array_count, byte[] rule_array, byte[] key_part);
CSNBMVRJ public native void CSNBMVRJ(hikmNativeInteger return_code, hikmNativeInteger 375
byte[] key_identifier, hikmNativeInteger text_length, byte[] text,
byte[] chaining_vector, byte[] MAC);
CSNBOWHJ public native void CSNBOWHJ(hikmNativeInteger return_code, hikmNativeInteger 134
text_length, byte[] text, hikmNativeInteger chaining_vector_length,
byte[] chaining_vector, hikmNativeInteger hash_length, byte[] hash);
CSNBPCUJ public native void CSNBPCUJ(hikmNativeInteger return_code, hikmNativeInteger 475
hikmNativeInteger authentication_key_identifier_length,
byte[] authentication_key_identifier, hikmNativeInteger
encryption_key_identifier_length, byte[] encryption_key_identifier,
hikmNativeInteger diversification_data_length,
byte[] diversification_data,
hikmNativeInteger new_reference_PIN_key_identifier_length,
byte[] new_reference_PIN_key_identifier, byte[] new_reference_PIN_block,
byte[] new_reference_PIN_profile, byte[] new_reference_PIN_PAN_data,
hikmNativeInteger current_reference_PIN_key_identifier_length,
byte[] current_reference_PIN_key_identifier,
byte[] current_reference_PIN_block, byte[] current_reference_PIN_profile,
byte[] current_reference_PIN_PAN_data, hikmNativeInteger
output_PIN_data_length, byte[] output_PIN_data, byte[] output_PIN_profile,
hikmNativeInteger output_PIN_message_length, byte[] output_PIN_message);
CSNBPEXJ public native void CSNBPEXJ(hikmNativeInteger return_code, hikmNativeInteger 309
CSNBPEXXJ public native void CSNBPEXXJ(hikmNativeInteger return_code, 311
byte[] exit_data, byte[] source_key_token, byte[] KEK_key_identifier);

CSNBPGNJ public native void CSNBPGNJ(hikmNativeInteger return_code, hikmNativeInteger 441
byte[] PIN_generating_key_identifier, hikmNativeInteger rule_array_count,
byte[] rule_array, hikmNativeInteger PIN_length, hikmNativeInteger
PIN_check_length, byte[] data_array, byte[] returned_result);
CSNBPTRJ public native void CSNBPTRJ(hikmNativeInteger return_code, hikmNativeInteger 463
byte[] input_PIN_encrypting_key_identifier,
byte[] output_PIN_encrypting_key_identifier,
byte[] input_PIN_profile, byte[] input_PAN_data,
byte[] input_PIN_block, hikmNativeInteger rule_array_count,
byte[] rule_array, byte[] output_PIN_profile, byte[] output_PAN_data,
hikmNativeInteger sequence_number, byte[] output_PIN_block);
CSNBPVRJ public native void CSNBPVRJ(hikmNativeInteger return_code, hikmNativeInteger 469
byte[] PIN_encrypting_key_identifier, byte[] PIN_verifying_key_identifier,
byte[] PIN_profile, byte[] PAN_data, byte[] encrypted_PIN_block,
PIN_check_length, byte[] data_array);
CSNBRKAJ public native void CSNBRKAJ(hikmNativeInteger return_code, hikmNativeInteger 328
KEK_key_identifier_length, byte[] KEK_key_identifier, hikmNativeInteger
opt_parameter1_length, byte[] opt_parameter1, hikmNativeInteger
opt_parameter2_length, byte[] opt_parameter2);
CSNBRNGJ public native void CSNBRNGJ(hikmNativeInteger return_code, hikmNativeInteger 313
byte[] form, byte[] random_number);
CSNBRNGLJ public native void CSNBRNGLJ(hikmNativeInteger return_code, 315
hikmNativeInteger seed_length, byte[] seed, hikmNativeInteger
random_number_length, byte[] random_number);
CSNBSADJ public native void CSNBSADJ(hikmNativeInteger return_code, hikmNativeInteger 378
key_parms_length, byte[] key_parms, hikmNativeInteger block_size,
hikmNativeInteger initialization_vector_length,
byte[] initialization_vector, hikmNativeInteger chain_data_length,
byte[] chain_data, hikmNativeInteger ciphertext_length,
byte[] ciphertext, hikmNativeInteger cleartext_length, byte[] cleartext,
hikmNativeInteger optional_data_length, byte[] optional_data);
CSNBSAEJ public native void CSNBSAEJ(hikmNativeInteger return_code, hikmNativeInteger 383
key_parms_length, byte[] key_parms, hikmNativeInteger block_size,
hikmNativeInteger initialization_vector_length,
byte[] initialization_vector, hikmNativeInteger chain_data_length,
byte[] chain_data, hikmNativeInteger cleartext_length, byte[] cleartext,
hikmNativeInteger ciphertext_length, byte[] ciphertext,
hikmNativeInteger optional_data_length, byte[] optional_data);

CSNBSKYJ public native void CSNBSKYJ(hikmNativeInteger return_code, hikmNativeInteger 481
byte[] input_key_identifier, byte[] key_encrypting_key_identifier,
byte[] secmsg_key_identifier, hikmNativeInteger cleartext_length,
byte[] cleartext, byte[] initialization_vector, hikmNativeInteger
key_offset, hikmNativeInteger key_field_length, byte[] enciphered_text,
byte[] output_chaining_vector);
CSNBSPNJ public native void CSNBSPNJ(hikmNativeInteger return_code, hikmNativeInteger 484
byte[] input_PIN_block, byte[] PIN_encrypting_key_identifier,
byte[] input_PIN_profile, byte[] input_PAN_data,
byte[] secmsg_key_identifier, byte[] output_PIN_profile,
byte[] output_PAN_data, hikmNativeInteger cleartext_length,
byte[] cleartext, byte[] initialization_vector, hikmNativeInteger
PIN_offset, hikmNativeInteger PIN_offset_field_length,
byte[] enciphered_text, byte[] output_chaining_vector);
| CSNBT31IJ public native void CSNBT31IJ(hikmNativeInteger return_code, 528
| hikmNativeInteger reason_code, hikmNativeInteger exit_data_length,
| byte[] exit_data, hikmNativeInteger rule_array_count, byte[] rule_array,
| hikmNativeInteger tr31_key_block_length, byte[] tr31_key_block,
| hikmNativeInteger unwrap_kek_identifier_length, byte[]
| unwrap_kek_identifier, hikmNativeInteger wrap_kek_identifier_length,
| byte[] wrap_kek_identifier, hikmNativeInteger
| output_key_identifier_length, byte[] output_key_identifier,
| hikmNativeInteger num_opt_blocks, hikmNativeInteger cv_source,
| hikmNativeInteger protection_method);
| CSNBT31OJ public native void CSNBT31OJ(hikmNativeInteger return_code, 555
| byte[] exit_data, hikmNativeInteger rule_array_count,
| byte[] rule_array, hikmNativeInteger opt_blocks_bfr_length,
| hikmNativeInteger opt_blocks_length, byte[] opt_blocks,
| hikmNativeInteger num_opt_blocks, byte[] opt_block_id,
| hikmNativeInteger opt_block_data_length, byte[] opt_block_data);
| CSNBT31PJ public native void CSNBT31PJ(hikmNativeInteger return_code, 551
| byte[] rule_array, hikmNativeInteger tr31_key_length, byte[] tr31_key,
| byte[] key_block_version, hikmNativeInteger key_block_length,
| byte[] key_usage, byte[] algorithm, byte[] mode,
| byte[] key_version_number, byte[] exportability,
| hikmNativeInteger num_opt_blocks);
| CSNBT31RJ public native void CSNBT31RJ(hikmNativeInteger return_code, 558
| byte[] rule_array, hikmNativeInteger tr31_key_length, byte[] tr31_key,
| byte[] opt_block_id, hikmNativeInteger num_opt_blocks,
| byte[] opt_block_ids, byte[] opt_block_lengths,
| hikmNativeInteger opt_block_data_length, byte[] opt_block_data);

| CSNBT31XJ public native void CSNBT31XJ(hikmNativeInteger return_code, 501
| byte[] rule_array, byte[] key_version_number, hikmNativeInteger
| key_field_length, hikmNativeInteger source_key_identifier_length,
| byte[] source_key_identifier, hikmNativeInteger
| unwrap_kek_identifier_length, byte[] unwrap_kek_identifier,
| hikmNativeInteger wrap_kek_identifier_length,
| byte[] wrap_kek_identifier, hikmNativeInteger opt_blocks_length,
| byte[] opt_blocks, hikmNativeInteger tr31_key_block_length,
| byte[] tr31_key_block);
CSNBTRVJ public native void CSNBTRVJ(hikmNativeInteger return_code, hikmNativeInteger 496
transaction_key_identifier_length, byte[] transaction_key_identifier,
hikmNativeInteger transaction_info_length, byte[] transaction_info,
hikmNativeInteger validation_values_length, byte[] validation_values);
CSNDDSGJ public native void CSNDDSGJ(hikmNativeInteger return_code, hikmNativeInteger 118
PKA_private_key_identifier_length, byte[] PKA_private_key_identifier,
hikmNativeInteger hash_length, byte[] hash,
hikmNativeInteger signature_field_length,
hikmNativeInteger signature_bit_length, byte[] signature_field);
CSNDDSVJ public native void CSNDDSVJ(hikmNativeInteger return_code, hikmNativeInteger 122
PKA_public_key_identifier_length, byte[] PKA_public_key_identifier,
hikmNativeInteger hash_length, byte[] hash,
hikmNativeInteger signature_field_length, byte[] signature_field);
| CSNDEDHJ public native void CSNDEDHJ(hikmNativeInteger return_code, hikmNativeInteger 217
| private_key_identifier_length, byte[] private_key_identifier,
| hikmNativeInteger private_KEK_key_identifier_length, byte[]
| private_KEK_key_identifier, hikmNativeInteger
| public_key_identifier_length, byte[] public_key_identifier,
| hikmNativeInteger chaining_vector_length, byte[] chaining_vector,
| hikmNativeInteger party_info_length, byte[] party_info,
| hikmNativeInteger key_bit_length, hikmNativeInteger reserved_1_length,
| byte[] reserved_1, hikmNativeInteger reserved_2_length, byte[] reserved_2,
| hikmNativeInteger reserved_3_length, byte[] reserved_3,
| hikmNativeInteger reserved_4_length, byte[] reserved_4, hikmNativeInteger
| reserved_5_length, byte[] reserved_5, hikmNativeInteger
| output_KEK_key_identifier_length, byte[] output_KEK_key_identifier,
| hikmNativeInteger output_key_identifier_length,
| byte[] output_key_identifier);
CSNDKRCJ public native void CSNDKRCJ(hikmNativeInteger return_code, hikmNativeInteger 410
hikmNativeInteger rule_array_count, byte[] rule_array, byte[] key_label,
hikmNativeInteger key_token_length, byte[] key_token);
CSNDKRDJ public native void CSNDKRDJ(hikmNativeInteger return_code, hikmNativeInteger 412
CSNDKRLJ public native void CSNDKRLJ(hikmNativeInteger return_code, hikmNativeInteger 414
hikmNativeInteger dataset_name_length, byte[] dataset_name,
byte[] security_server_name);

CSNDKRRJ public native void CSNDKRRJ(hikmNativeInteger return_code, hikmNativeInteger 416
CSNDKRWJ public native void CSNDKRWJ(hikmNativeInteger return_code, hikmNativeInteger 418
CSNDKTCJ public native void CSNDKTCJ(hikmNativeInteger return_code, hikmNativeInteger 103
CSNDPKBJ public native void CSNDPKBJ(hikmNativeInteger return_code, hikmNativeInteger 95
key_values_structure_length, byte[] key_values_structure,
hikmNativeInteger key_name_length, byte[] key_name,
hikmNativeInteger user_definable_associated_data_length,
byte[] user_definable_associated_data, hikmNativeInteger
reserved_2_length, byte[] reserved_2, hikmNativeInteger reserved_3_length,
byte[] reserved_3, hikmNativeInteger reserved_4_length, byte[] reserved_4,
hikmNativeInteger reserved_5_length, byte[] reserved_5,
hikmNativeInteger token_length, byte[] token);
CSNDPKDJ public native void CSNDPKDJ(hikmNativeInteger return_code, hikmNativeInteger 305
source_encrypted_key_length, byte[] source_encrypted_key,
hikmNativeInteger data_structure_length, byte[] data_structure,
hikmNativeInteger private_key_identifier_length,
byte[] private_key_identifier, hikmNativeInteger clear_target_key_length,
byte[] clear_target_key);
CSNDPKEJ public native void CSNDPKEJ(hikmNativeInteger return_code, hikmNativeInteger 307
clear_source_data_length, byte[] clear_source_data, hikmNativeInteger
data_structure_length, byte[] data_structure, hikmNativeInteger
public_key_identifier_length, byte[] public_key_identifier,
hikmNativeInteger target_data_length, byte[] target_data);
CSNDPKGJ public native void CSNDPKGJ(hikmNativeInteger return_code, hikmNativeInteger 87
regeneration_data_length, byte[] regeneration_data, hikmNativeInteger
skeleton_key_token_length, byte[] skeleton_key_token,
byte[] transport_key_identifier, hikmNativeInteger
generated_key_identifier_length, byte[] generated_key_identifier);
CSNDPKHJ public native void CSNDPKHJ(hikmNativeInteger return_code, hikmNativeInteger 110
byte[] public_key_name, hikmNativeInteger hash_data_length,
byte[] hash_data);
CSNDPKIJ public native void CSNDPKIJ(hikmNativeInteger return_code, hikmNativeInteger 92
source_key_token_length, byte[] source_key_token,
target_key_identifier_length, byte[] target_key_identifier);

CSNDPKRJ public native void CSNDPKRJ(hikmNativeInteger return_code, hikmNativeInteger 112
byte[] public_key_name, hikmNativeInteger public_key_certificate_length,
byte[] public_key_certificate);
CSNDPKTJ public native void CSNDPKTJ(hikmNativeInteger return_code, hikmNativeInteger 105
source_key_identifier_length, byte[] source_key_identifier,
hikmNativeInteger source_transport_key_identifier_length,
byte[] source_transport_key_identifier, hikmNativeInteger
target_transport_key_identifier_length,
byte[] target_transport_key_identifier, hikmNativeInteger
target_key_token_length, byte[] target_key_token);
CSNDPKXJ public native void CSNDPKXJ(hikmNativeInteger return_code, hikmNativeInteger 108
hikmNativeInteger target_key_token_length, byte[] target_key_token);
CSNDRKDJ public native void CSNDRKDJ(hikmNativeInteger return_code, hikmNativeInteger 420
CSNDRKLJ public native void CSNDRKLJ(hikmNativeInteger return_code, hikmNativeInteger 422
byte[] key_label_mask, hikmNativeInteger retained_keys_count,
hikmNativeInteger key_labels_count, byte[] key_labels);
CSNDRKXJ public native void CSNDRKXJ(hikmNativeInteger return_code, hikmNativeInteger 317
trusted_block_identifier_length, byte[] trusted_block_identifier,
hikmNativeInteger certificate_length, byte[] certificate,
hikmNativeInteger certificate_parms_length, byte[] certificate_parms,
hikmNativeInteger transport_key_identifier_length,
byte[] transport_key_identifier, hikmNativeInteger rule_id_length,
byte[] rule_id, hikmNativeInteger importer_key_identifier_length,
byte[] importer_key_identifier, hikmNativeInteger
hikmNativeInteger asym_encrypted_key_length, byte[] asym_encrypted_key,
hikmNativeInteger sym_encrypted_key_identifier_length,
byte[] sym_encrypted_key_identifier, hikmNativeInteger extra_data_length,
byte[] extra_data, hikmNativeInteger key_check_parameters_length,
byte[] key_check_parameters, hikmNativeInteger key_check_value_length,
byte[] key_check_value);
CSNDSBCJ public native void CSNDSBCJ(hikmNativeInteger return_code, hikmNativeInteger 489
byte[] block_contents_identifier, hikmNativeInteger XData_string_length,
byte[] XData_string, hikmNativeInteger data_to_encrypt_length,
byte[] data_to_encrypt, hikmNativeInteger data_to_hash_length,
byte[] data_to_hash, byte[] initialization_vector, hikmNativeInteger
RSA_public_key_identifier_length, byte[] RSA_public_key_identifier,
hikmNativeInteger DES_key_block_length, byte[] DES_key_block,
hikmNativeInteger RSA-OAEP_block_length, byte[] RSA-OAEP_block,
byte[] chaining_vector, byte[] DES_encrypted_block);

CSNDSBDJ public native void CSNDSBDJ(hikmNativeInteger return_code, hikmNativeInteger 492
RSA-OAEP_block_length, byte[] RSA-OAEP_block, hikmNativeInteger
DES_encrypted_data_block_length, byte[] DES_encrypted_data_block,
byte[] initialization_vector, hikmNativeInteger
RSA_private_key_identifier_length, byte[] RSA_private_key_identifier,
hikmNativeInteger DES_key_block_length, byte[] DES_key_block,
byte[] block_contents_identifier, hikmNativeInteger XData_string_length,
byte[] XData_string, byte[] chaining_vector, byte[] data_block,
hikmNativeInteger hash_block_length, byte[] hash_block);
CSNDSYGJ public native void CSNDSYGJ(hikmNativeInteger return_code, hikmNativeInteger 339
byte[] key_encrypting_key_identifier, hikmNativeInteger
RSA_public_key_identifier_length, byte[] RSA_public_key_identifier,
hikmNativeInteger local_enciphered_key_identifier_length,
byte[] local_enciphered_key_identifier, hikmNativeInteger
RSA_enciphered_key_identifier_length,
byte[] RSA_enciphered_key_identifier);
CSNDSYIJ public native void CSNDSYIJ(hikmNativeInteger return_code, hikmNativeInteger 345
RSA_enciphered_key_length, byte[] RSA_enciphered_key, hikmNativeInteger
RSA_private_key_identifier_length, byte[] RSA_private_key_identifier,
hikmNativeInteger target_key_identifier_length,
CSNDSYI2J public native void CSNDSYI2J(hikmNativeInteger return_code, 350
| hikmNativeInteger enciphered_key_length, byte[] enciphered_key,
| hikmNativeInteger transport_key_identifier_length,
| byte[] transport_key_identifier, hikmNativeInteger
| key_name_length, byte[] key_name, hikmNativeInteger
target_key_identifier_length, byte[] target_key_identifier);
| CSNDSYXJ public native void CSNDSYXJ(hikmNativeInteger return_code, hikmNativeInteger 333
| source_key_identifier_length, byte[] source_key_identifier,
| hikmNativeInteger transport_key_identifier_length ,
| byte[] transport_key_identifier, hikmNativeInteger
| enciphered_key_length, byte[] enciphered_key);
CSNDTBCJ public native void CSNDTBCJ(hikmNativeInteger return_code, hikmNativeInteger 353
input_block_identifier_length, byte[] input_block_identifier,
trusted_block_identifier_length, byte[] trusted_block_identifier);
CSUAACIJ public native void CSUAACIJ(hikmNativeInteger return_code, hikmNativeInteger 35
hikmNativeInteger verb_data_1_length, byte[] verb_data_1,
hikmNativeInteger verb_data_2_length, byte[] verb_data_2);
CSUAACMJ public native void CSUAACMJ(hikmNativeInteger return_code, hikmNativeInteger 38
hikmNativeInteger rule_array_count, byte[] rule_array, byte[] name,
hikmNativeInteger output_data_length, byte[] output_data);

CSUACFCJ public native void CSUACFCJ(hikmNativeInteger return_code, hikmNativeInteger 42
hikmNativeInteger verb_data_length, byte[] verb_data);
CSUACFQJ public native void CSUACFQJ(hikmNativeInteger return_code, hikmNativeInteger 48
hikmNativeInteger verb_data_length, byte[] verb_data);
CSUACFVJ public native void CSUACFVJ(hikmNativeInteger return_code, hikmNativeInteger 58
hikmNativeInteger version_data_length, byte[] version_data);
CSUACRAJ public native void CSUACRAJ(hikmNativeInteger return_code, hikmNativeInteger 59
reason_code, hikmNativeInteger exit_data_lengthh, byte[] exit_data,
hikmNativeInteger resource_name_length, byte[] resource_name);
CSUACRDJ public native void CSUACRDJ(hikmNativeInteger return_code, hikmNativeInteger 61
resource_name_length, byte[] resource_name);
CSUALCTJ public native void CSUALCTJ(hikmNativeInteger return_code, hikmNativeInteger 67
hikmNativeInteger rule_array_count, byte[] rule_array, byte[] user_id,
hikmNativeInteger auth_parms_length, byte[] auth_parms,
hikmNativeInteger auth_data_length, byte[] auth_data);
CSUAMKDJ public native void CSUAMKDJ(hikmNativeInteger return_code, hikmNativeInteger 70
share_index, byte[] private_key_name, byte[] certifying_key_name,
hikmNativeInteger certificate_length, byte[] certificate,
hikmNativeInteger clone_info_encrypting_key_length,
byte[] clone_info_encrypting_key,
hikmNativeInteger clone_info_length, byte[] clone_info);
CSUARNTJ public native void CSUARNTJ(hikmNativeInteger return_code, hikmNativeInteger 78
hikmNativeInteger rule_array_count, byte[] rule_array);

Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that only
that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATIONS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publications. IBM
may make improvements and/or changes in the product(s) and/or program(s) described in this publication
at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this one)
and (ii) the mutual use of the information which has been exchanged, should contact:
| crypto@us.ibm.com
757
Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows: (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. Copyright IBM Corp. _enter the year or years_.
IBM agreement for licensed internal code
Read Before Using

IMPORTANT
YOU ACCEPT THE TERMS OF THIS IBM LICENSE AGREEMENT FOR MACHINE CODE BY
YOUR USE OF THE HARDWARE PRODUCT OR MACHINE CODE. PLEASE READ THE
AGREEMENT CONTAINED IN THIS BOOK BEFORE USING THE HARDWARE PRODUCT.
You accept the terms of this Agreement18 by your initial use of a machine that contains IBM Licensed
Internal Code (called Code). These terms apply to Code used by certain machines IBM or your reseller
specifies (called Specific Machines). International Business Machines Corporation or one of its
subsidiaries (IBM) owns copyrights in Code or has the right to license Code. IBM or a third party owns all
copies of Code, including all copies made from them.
If you are the rightful possessor of a Specific Machine, IBM grants you a license to use the Code (or any
replacement IBM provides) on, or in conjunction with, only the Specific Machine for which the Code is
provided. IBM licenses the Code to only one rightful possessor at a time.
18. Form Z125-4144

Under each license, IBM authorizes you to do only the following:
1. execute the Code to enable the Specific Machine to function according to its Official Published
Specifications (called Specifications);
2. make a backup or archival copy of the Code (unless IBM makes one available for your use), provided
you reproduce the copyright notice and any other legend of ownership on the copy. You may use the
copy only to replace the original, when necessary; and
3. execute and display the Code as necessary to maintain the Specific Machine.
You agree to acquire any replacement for, or additional copy of, Code directly from IBM in accordance with
IBM's standard policies and practices. You also agree to use that Code under these terms.
You may transfer possession of the Code to another party only with the transfer of the Specific Machine. If
you do so, you must 1) destroy all your copies of the Code that were not provided by IBM, 2) either give
the other party all your IBM-provided copies of the Code or destroy them, and 3) notify the other party of
these terms. IBM licenses the other party when it accepts these terms. These terms apply to all Code you
acquire from any source.
Your license terminates when you no longer rightfully possess the Specific Machine.
Actions you must not take

You agree to use the Code only as authorized above. You must not do, for example, any of the following:
1. Otherwise copy, display, transfer, adapt, modify, or distribute the Code (electronically or otherwise),
except as IBM may authorize in the Specific Machine's Specifications or in writing to you;
2. Reverse assemble, reverse compile, or otherwise translate the Code unless expressly permitted by
applicable law without the possibility of contractual waiver;
3. Sublicense or assign the license for the Code; or
4. Lease the Code or any copy of it.
Notices 759
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at
"Copyright and trademark information at:
www.ibm.com/legal/copytrade.shtml
Adobe is either a registered trademark or trademark of Adobe Systems Incorporated in the United States,
and/or other countries.
Intel is a trademark or registered trademark of Intel Corporation or its subsidiaries in the United States and
other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, and service names may be trademarks or service marks of others.
761
List of abbreviations
ADB Actual Data Block EDE Encipher-Decipher-Encipher
AES Advanced Encryption Standard EEPROM
AIX Advanced Interactive Executive operating Electrically Erasable, Programmable
system Read-Only Memory
| ANS American National Standards EID Environment Identifier
ANSI American National Standards Institute EPP Encrypting PIN PAD
API Application Programming Interface FCV Function Control Vector
ASCII American National Standard Code for FIPS Federal Information Processing Standards
Information Interchange HMAC Keyed Hash MAC
ASN Abstract Syntax Notation | HSM Hardware Security Module
ATC Application Transaction Counter IBM International Business Machines
ATM Automated Teller Machine ICSF Integrated Cryptographic Service Facility
BC Block Contents ICV Initial Chaining Value
| BDK Base Derivation Key IEC International Electrotechnical Commission
BER ASN.1 Basic Encoding Rules I/O Input/Output
CA Certification Authority IPL Initial Program Load
CBC Cipher Block Chaining ISO International Organization for
CCA Common Cryptographic Architecture Standardization
| CDMF Commercial Data Masking Facility (IBM ISO/DIS
| 4758 only) International Organization for
CKSN Current-Key Serial Number Standardization/Draft International
CLU Coprocessor Load Utility Standard
| CMS Cryptographic Message Syntax ISO/FDIS
CNI Coprocessor Node Initialization International Organization for
CMOS Complementary Metal Oxide Standardization/Final Draft International
Semiconductor Standard
CMK Current Master Key JNI Java Native Interface
CNM Cryptographic Node Management (utility) | KC Key Confirmation
COBOL | KDF Key Derivation Function
Common Business-Oriented Language KEK Key-Encrypting Key
CRT Chinese-Remainder Theorem KM Master Key
| CSC Card Security Code KVP Key Verification Pattern
CV Control Vector LRC Longitudinal Redundancy Check
CVC Card-Verification Code LSB Least significant bit
| CVK Card Verification Key MB Megabyte
CVV Card-Verification Value MAC Message Authentication Code
DEA Data Encryption Algorithm MD5 Message Digest-5 Hash Algorithm
DES Data Encryption Standard MDC Modification Detection Code
DOW Day of the Week MDK Master-Derivation Key
DMA Direct Memory Access | MFK Master File Key
DSS Digital Signature Standard MK Master Key
| DUKPT MKVP Master-Key Verification Pattern
| Derived Unique Key Per Transaction MSB Most significant bit
EBCDIC NIST National Institute of Standards and
Extended Binary Coded Decimal Technology (USA)
Interchange Code NL Netherlands
| EC Elliptic Curve NMK New Master Key
ECB Electronic Code Book OAEP Optimal Asymmetric Encryption Padding
ECC Elliptic Curve Cryptography OCSP Open Certificate Status Protocol
| ECDH Elliptic Curve Diffie-Hellman OEM Original Equipment Manufacturer
| ECDSA | OID Object Identifier
| Elliptic Curve Digital Signature Algorithm OMK Old Master Key
ECI Eurocheque International OPK Object Protection Key
763
PAN Personal Account Number
PCI Peripheral Component Interconnect
PCIe PCI Express
PCI-XPCI Extended
PIN Personal Identification Number
PKA Public Key Algorithm
PKCS Public-Key Cryptography Standards
POST Power-On Self Test
PRNG Pseudo Random Number Generator
PROM Programmable Read-Only Memory
| PVV PIN Validation Value
RA Registration Authority
RACF Resource Access Control Facility
RAM Random Access Memory
| RFC Request for Comments
RHEL Red Hat Enterprise Linux
RNG Random Number Generator
ROM Read-Only Memory
RSA Rivest, Shamir, and Adleman
| SEC 2Standards for Efficient Cryptography 2
| SECG Standards for Efficient Cryptography
| Group
SET Secure Electronic Transaction
SHA Secure Hash Algorithm
SLES SUSE Linux Enterprise Server
SNA Systems Network Architecture
SSL Secure Sockets Layer
TLV Tag, Length, Value
TVV Token-validation value
UDK Unique DEA Key
UDX User-Defined Extension
UKPT Unique Key Per Transaction
UTC Coordinated Universal Time
VIS Visa Integrated Circuit Card Specification
XOR Exlusive-OR

Glossary
This glossary includes some terms and definitions Advanced Interactive Executive (AIX) operating
from the IBM Dictionary of Computing, New York: system. IBM's implementation of the UNIX19 operating
McGraw Hill, 1994. This glossary also includes system.
some terms and definitions from:
American National Standard Code for Information
v The American National Standard Dictionary for Interchange (ASCII). The standard code (8 bits
Information Systems, ANS X3.172-1990, including parity a bit), used for information interchange
copyright 1990 by the U.S. American National among data processing systems, data communication
Standards Institute (ANSI). Definitions are systems, and associated equipment. The ASCII set
identified by the symbol (A) after the definition. consists of control characters and graphic characters.
v The Information Technology Vocabulary, American National Standards Institute (ANSI). An
developed by Subcommittee 1, Joint Technical organization, consisting of producers, consumers, and
Committee 1, of the International Organization general interest groups that establishes the procedures
for Standardization and the International by which accredited organizations create and maintain
Electrotechnical Commission (ISO/IEC voluntary industry standards in the United States. (A)
JTC1/SC1). Definitions of published parts of this
Application System/400 system (AS/400). AS/400
vocabulary are identified by the symbol (I) after
was one of a family of general purpose midrange
the definition. systems with a single operating system, Operating
v The IBM TotalStorage Enterprise Storage System/400, that provides application portability across
Server documentation. Definitions of published all models. AS/400 is now referred to as IBM i.
parts of this vocabulary are identified by the
assembler language. A source language that includes
symbol (E) after the definition.
symbolic machine language statements in which there is
a one-to-one correspondence between the instruction
A formats and the data formats of the computer.
access. A specific type of interaction between a authentication. A process used to verify the integrity
subject and an object that results in the flow of of transmitted data, especially a message (I). In
information from one to the other. computer security, a process used to verify the user of
an information system or protected resources.
access control. Ensuring that the resources of a
computer system can be accessed only by authorized authorization. The right granted to a user to
users in authorized ways. communicate with or make use of a computer system
(I). The process of granting a user either complete or
access method. A technique for moving data between restricted access to an object, resource, or function.
main storage and input/output devices.
authorize. To permit or give authority to a user to
adapter. A printed circuit card that modifies the system communicate with or make use of an object, resource,
unit to allow it to operate in a particular way. or function.
address. In data communication, the unique code

assigned to each device or workstation connected to a B
network. A character or group of characters that
identifies a register, a particular part of storage, or some bus. In a processor, a physical facility along which
other data source or data destination. (A) To refer to a data is transferred.
device or an item of data by its address. (A) (I)
byte. A binary character operated on as a unit and
Advanced Encryption Standard (AES). A data usually shorter than a computer word. (A) A string that
encryption technique that improved upon and officially consists of a number of bits, treated as a unit, and
replaced the Data Encryption Standard (DES). AES is representing a character. A group of eight adjacent
sometimes referred to as Rijndael, which is the binary digits that represents one EBCDIC character.
algorithm on which the standard is based.
19. UNIX is a trademark of UNIX Systems Laboratories,

Incorporated.
765
C Cryptographic Node Management (CNM) utility.
One of the utility programs supplied with the CCA
Support Program. It enables you to initialize the
Card-Verification Code (CVC). See Card-Verification
coprocessor access controls and the cryptographic
Value.
master keys.
Card-Verification Value (CVV). A cryptographic
cryptography. The transformation of data to conceal
method, defined by VISA, for detecting forged
its meaning.
magnetic-striped cards. This method cryptographically
checks the contents of a magnetic stripe. This process
is functionally the same as MasterCards D
Card-Verification Code (CVC) process.
data. A representation of facts or instructions in a form
Commercial Data Masking Facility (CDMF). An suitable for communication, interpretation, or processing
alternate algorithm for data confidentiality applications, by human or automatic means. Data includes constants,
based on the DES algorithm with an effective 40-bit key variables, arrays, and character strings. Any
strength. CDMF is supported only prior to Version 3. representations such as characters or analog quantities
to which meaning is or might be assigned. (A)
channel. A path along which signals can be sent; for
example, a data channel or an output channel. (A) data-encrypting key. A key used to encipher,
decipher, or authenticate data. Contrast with
ciphertext. Text that results from the encipherment of
key-encrypting key.
plaintext. See also plaintext.
Data Encryption Algorithm (DEA). A 64-bit block
Cipher Block Chaining (CBC). A mode of operation
cipher that uses a 64-bit key, of which 56 bits are used
that cryptographically connects one block of ciphertext
to control the cryptographic process and 8 bits are used
to the next plaintext block.
for parity checking to ensure that the key is transmitted
clear data. Data that is not enciphered. properly.
cleartext. Text that has not been altered by a Data Encryption Standard (DES). The National
cryptographic process. Synonym for plaintext. See also Institute of Standards and Technology Data Encryption
ciphertext. Standard, adopted by the U.S. government as Federal
Information Processing Standard (FIPS) Publication 46.
Common Cryptographic Architecture (CCA). The which allows only hardware implementations of the
CCA API is the programming interface described in this data-encryption algorithm.
document.
dataset. The major unit of data storage and retrieval,
concatenation. An operation that joins two characters consisting of a collection of data in one of several
or strings in the order specified, forming one string prescribed arrangements and described by control
whose length is equal to the sum of the lengths of its information to which the system has access.
parts.
decipher. To convert enciphered data into clear data.
configuration. The manner in which the hardware and Synonym for decrypt. Contrast with encipher.
software of an information processing system are
organized and interconnected. (I) The physical and decode. To convert data by reversing the effect of
logical arrangement of devices and programs that some previous encoding. (A) (I) In the CCA products,
constitutes a data processing system. decode and encode relate to the Electronic Code Book
mode of the Data Encryption Standard (DES). Contrast
control program. A computer program designed to with encode and decipher.
schedule and to supervise the programs running in a
computer system. (A) (I) decrypt. To decipher or decode. Synonym for
decipher. Contrast with encrypt.
control vector (CV). In CCA, a 16-byte string that is
exclusive-ORed with a master key or a key-encrypting device driver. A program that contains the code
key to create another key that is used to encipher and needed to attach and use a device.
decipher data or data keys. A control vector determines
device ID. In the IBM 4765 and IBM 4764 CCA
the type of key and the restrictions on the use of that
implementations, a user-defined field in the
key.
configuration data that can be used for any purpose the
coprocessor. In this document, the IBM 4765 PCIe user specifies. For example, it can be used to identify a
and IBM 4764 PCI-X Cryptographic Coprocessors, particular device, by using a unique ID similar to a serial
generally also when using the CCA Support Program. number.

diagnostic. Pertaining to the detection and isolation of Federal Information Processing Standard (FIPS). A
errors in programs, and faults in equipment. standard published by the US National Institute of
Science and Technology.
directory server. A server that manages key records
in key storage by using an Indexed Sequential Access financial PIN. A Personal Identification Number used
Method. to identify an individual in some financial transactions.
To maintain the security of the PIN, processes and data
structures have been adopted for creating,
E communicating, and verifying PINs used in financial
transactions. See also Personal Identification Number.
Electronic Code Book (ECB). A mode of operation
used with block cipher cryptographic algorithms in which Flash-Erasable Programmable Read-Only Memory.
plaintext or ciphertext is placed in the input to the A memory that has to be erased before new data can
algorithm and the result is contained in the output of the be saved into the memory.
algorithm.
Elliptic Curve Cryptography (ECC). A public-key H

process discovered independently in 1985 by Victor
Miller (IBM) and Neal Koblitz (University of Washington). host. In this publication, same as host computer or
ECC is based on discrete logarithms. The algebraic host processor. The machine in which the coprocessor
structure of elliptic curves over finite fields makes it resides. In a computer network, the computer that
much more difficult to challenge at equivalent RSA key usually performs network-control functions and provides
lengths. end-users with services such as computation and
database access. (I)
encipher. To scramble data or to convert data to a
secret code that masks the meaning of the data to
unauthorized recipients. Synonym for encrypt. Contrast I
with decipher. See also encode.
IMPORTER key. In the CCA implementation, a type of
enciphered data. Data whose meaning is concealed DES key-encrypting key that can decipher a key at a
from unauthorized users or observers. See also receiving mode. Contrast with EXPORTER key.
ciphertext.
initialize. In programming languages, to give a value
encode. To convert data by the use of a code in such to a data object at the beginning of its lifetime. (I) To
a manner that reconversion to the original form is set counters, switches, addresses, or contents of
possible. (I) In the CCA implementation, decode and storage to zero or other starting values at the beginning
encode relate to the Electronic Code Book mode of the of, or at prescribed points in, the operation of a
Data Encryption Standard. Contrast with decode. See computer routine. (A)
also encipher.
Integrated Cryptographic Service Facility (ICSF). An
encrypt. Synonym for encipher. (I) To convert cleartext IBM licensed program that supports the cryptographic
into ciphertext. Contrast with decrypt. hardware feature for the high-end System/390
processor running in a z/OS environment.
erasable programmable read-only memory
(EPROM). A type of memory chip that can retain its International Organization for Standardization
contents without electricity. Unlike the programmable (ISO). An organization of national standards bodies
read-only memory (PROM), which can be programmed established to promote the development of standards to
only once, the EPROM can be erased by ultraviolet light facilitate the international exchange of goods and
and then reprogrammed. (E) services, and develop cooperation in intellectual,
scientific, technological, and economic activity.
exit routine. In the CCA products, a user-provided
routine that acts as an extension to the processing
provided with calls to the security API. J
EXPORTER key. In the CCA implementation, a type of jumper. A wire that joins two unconnected circuits on a
DES key-encrypting key that can encipher a key at a printed circuit board.
sending node. Contrast with IMPORTER key.
K
F
key. In computer security, a sequence of symbols used
feature. A part of an IBM product that can be ordered with a cryptographic algorithm to encrypt or decrypt
separately. data.
Glossary 767
key-encrypting key (KEK). A key used for the Modification Detection Code (MDC). In cryptography,
encryption and decryption of other keys. Contrast with a number or value that interrelates all bits of a data
data-encrypting key. Also called a transport key. stream so that, when enciphered, modification of any bit
in the data stream results in a new MDC.
| key agreement. A key establishment procedure where
| the resultant secret keying material is a function of multi-user environment. A computer system that
| information contributed by two participants, so that no provides terminals and keyboards for more than one
| party can predetermine the value of the secret keying user at the same time.
| material independently from the contributions from the
| other parties.
N
key half. In the CCA implementation, one of the two
DES keys that make up a double-length key. National Institute of Science and Technology
(NIST). The current name for the US National Bureau
key identifier. In the CCA implementation, a 64-byte of Standards.
variable which is either a key label or a key token.
network. A configuration of data-processing devices
key label. In the CCA implementation, an identifier of and software programs connected for information
a key-record in key storage. See Key labels on page interchange. An arrangement of nodes and connecting
170 and Key-label content on page 390. branches. (I)
key storage. In the CCA implementation, a data file node. In a network, a point at which one-or-more
that contains cryptographic keys which are accessed by functional units connect channels or data circuits. (I)
key label.
| nonce. A time-varying value that has at most a
key token. In the CCA implementation, a data | negligible chance of repeating, such as a random value
structure that can contain a cryptographic key, a control | that is generated anew for each use, a timestamp, a
vector, and other information related to the key. | sequence number, or some combination of these.
L P
link. The logical connection between nodes including panel. The complete set of information shown in a
the end-to-end control procedures. The combination of single image on a display station screen.
physical media, protocols, and programming that
connects devices on a network. In computer parameter. In the CCA security API, an address
programming, the part of a program, in some cases a pointer passed to a verb to address a variable
single instruction or an address, that passes control and exchanged between an application program and the
parameters between separate portions of the computer verb.
program. (A) (I) To interconnect items of data or
password. In computer security, a string of characters
portions of one or more computer programs. (I) In SNA,
known to the computer system and a user; the user
the combination of the link connection and link stations
must specify it to gain full or limited access to a system
joining network nodes.
and to the data stored within it.
M personal identification number (PIN). In some

financial-transaction-authentication systems, the PIN is
make file. A composite file that contains either device the secret number given to a consumer with an
configuration data or individual user profiles. identification card. This number is selected by the
consumer, or it is assigned by the financial institution.
master key (MK, KM). In computer security, the
top-level key in a hierarchy of key-encrypting keys. profile ID. In the CCA implementation, the value used
to access a profile within the CCA access-control
message authentication code (MAC). A number or system.
value derived by processing data with an authentication
algorithm, The cryptographic result of block cipher plaintext. Data that has nor been altered by a
operations on text or data using a Cipher Block cryptographic process. Synonym for cleartext. See also
Chaining (CBC) mode of operation, A digital signature ciphertext.
code.
Power-On Self Test (POST). A series of diagnostic
migrate. To move data from one hierarchy of storage tests run automatically by a device when the power is
to another. To move to a changed operating turned on.
environment, usually to a new release or a new version
of a system.

private key. In computer security, a key that is known replicated key-half. In the CCA implementation, a
only to the owner and used together with a public-key double-length DES key where the two halves of the
algorithm to decipher data. The data is enciphered clear-key value are equal.
using the related public key. Contrast with public key.
See also public-key algorithm. Resource Access Control Facility (RACF). An IBM
licensed program that enables access control by
procedure call. In programming languages, a identifying and verifying the users to the system,
language construct for invoking execution of a authorizing access to protected resources, logging
procedure. (I) A procedure call usually includes an entry detected unauthorized attempts to enter the system,
name and possible parameters. and logging detected accesses to protected resources.
profile. Data that describes the significant return code. A code used to influence the execution of
characteristics of a user, a group of users, or succeeding instructions. (A) A value returned to a
one-or-more computer resources. program to indicate the results of an operation
requested by that program. In the CCA implementation,
protocol. A set of semantic and syntactic rules that a value that provides a general result as opposed to a
determines the behavior of functional units in achieving specific result. Contrast with reason code.
communication. (I) In SNA, the meanings of and the
sequencing rules for requests and responses used to Rivest-Shamir-Adleman (RSA) algorithm. A
manage the network, transfer data, and synchronize the public-key cryptography process developed by R.
states of network components. A specification for the Rivest, A. Shamir, and L. Adleman.
format and relative timing of information exchanged
between communicating parties. RS-232. A specification that defines the interface
between data terminal equipment and data
public key. In computer security, a key that is widely circuit-terminating equipment, using serial binary data
known, and used with a public-key algorithm to encrypt interchange.
data. The encrypted data can be decrypted only with
the related private key. Contrast with private key. See RS-232C. A standard that defines the specific physical,
also public-key algorithm. electronic, and functional characteristics of an interface
line that uses a 25-pin connector to connect a
Public-Key Algorithm (PKA). In computer security, an workstation to a communication device.
asymmetric cryptographic process that uses a public
key to encrypt data and a related private key to decrypt RSA algorithm. Rivest-Shamir-Adleman encryption
data. Contrast with Data Encryption Algorithm and Data algorithm.
Encryption Standard algorithm. See also
Rivest-Shamir-Adleman algorithm. S
public-key hardware. That portion of the security
security. The protection of data, system operations,
module in an IBM 4765 and IBM 4764 that performs
and devices from accidental or intentional ruin, damage,
modulus-exponentiation arithmetic.
or exposure.
Public-Key Cryptography Standards (PKCS).
security server. In the CCA implementation, the
Specifications produced by RSA Laboratories in
functions provided through calls made to the security
cooperation with secure system developers worldwide,
API.
for the purpose of accelerating the deployment of
public-key cryptography. First published in 1991. server. On a Local Area Network, a data station that
provides facilities to other data stations; for example, a
R file server, a print server, a mail server. (A)
Random access memory (RAM). A storage device session. In network architecture, for the purpose of
into which data are entered and from which data are data communication between functional units, all the
retrieved in a non-sequential manner. activities that take place during the establishment,
maintenance, and release of the connection. (I) The
Read-only memory (ROM). Memory in which stored period of time during which a user of a terminal can
data cannot be modified by the user except under communicate with an interactive system (usually, the
special conditions. elapsed time between logon and logoff).
reason code. A value that provides a specific result as Session-Level Encryption (SLE). A Systems Network
opposed to a general result. Contrast with return code. Architecture (SNA) protocol that provides a method for
establishing a session with a unique key for that
Glossary 769
session. This protocol establishes a cryptographic key userid. A string of characters that uniquely identifies a
and the rules for deciphering and enciphering user to the system.
information in a session.
utility program. A computer program in general
string. A sequence of elements of the same nature, support of computer processes. (I)
such as characters, considered as a whole. (I)
subsystem. A secondary or subordinate system, V

usually capable of operating independently of, or
asynchronously with, a controlling system. (I) verb. A function that has an entry-point-name and a
fixed-length parameter list. The procedure call for a verb
system administrator. The person at a computer uses the standard syntax of a programming language.
installation who designs, controls, and manages the use
of the computer system. virtual machine (VM). A functional simulation of a
computer and its associated devices. Each virtual
Systems Network Architecture (SNA). An machine is controlled by a suitable operating system.
architecture that describes logical structure, formats, VM controls concurrent execution of multiple virtual
protocols, and operational sequences for transmitting machines on one host computer.
information units through, and controlling the
configuration and operation of, networks. Note: The VISA. A financial institution consortium which defines
layered structure of SNA allows the ultimate origins and four PIN-block formats and a method of PIN verification.
destinations of information, that is, the end users, to be
independent of and unaffected by the specific SNA W
network services and facilities used for information
exchange. workstation. A terminal or microcomputer, usually one
that is connected to a mainframe or to a network, at
T which a user can perform applications.
z/OS. An operating system for the IBM product line

throughput. A measure of the amount of work
that uses 64-bit real storage. (E)
performed by a computer system over a given period of
time; for example, number of jobs per day. (A) (I) A
measure of the amount of information transmitted over a Numerics
network in a given period of time; for example, a
networks data-transfer-rate is usually measured in bits 4764. IBM 4764 PCI-X Cryptographic Coprocessor.
per second.
4765. IBM 4765 PCIe Cryptographic Coprocessor.
TLV. A widely used construct, Tag, Length, Value, to
render data self-identifying. For example, such
constructs are used with EMV smart cards.
token. In a Local Area Network, the symbol of

authority passed successively from one data station to
another to indicate the station is temporarily in control of
the transmission medium. (I) A string of characters
treated as a single entity.
trace file. A file that contains a record of trace

information for the selected processing.
transport key. See key-encrypting key.
U
Unique key per transaction (UKPT). A cryptographic
process that can be used to decipher PIN blocks in a
transaction.
user-exit routine. A user-written routine that receives

control at predefined user-exit points.
user ID. User identification.

Index
Special characters card verification value (Visa) (continued)
generating 449
(CSNDEDH (EC_Diffie-Hellman) 217
process 706
Transaction_Validation verb 496
validation 496
A verifying 456
access control regimes CCA management 1
examples 732 CCA, common cryptographic architecture
access control, CCA 14 control-vector definitions 655
Access_Control_Initialization (CSUAACI) 35 functional overview 1
Access_Control_Maintenance (CSUAACM) 38 key encryption 655
AES key-token list of security API verbs 711
records relationship to security API 6
AES_Key_Record_Create verb 392 certificate 29
AES_Key_Record_Delete verb 394 chaining vector 359
creating 392 chaining-vector-record format 633
deleting 394 changing encipherment 103, 105
AES_Key_Record_Create (CSNBAKRC) 392 CIPHER
AES_Key_Record_Delete (CSNBAKRD) 394 control-vector default values 657
AES_Key_Record_List (CSNBAKRL) 396 Decipher verb 150
AES_Key_Record_Read (CSNBAKRR) 398 Encipher verb 150
AES_Key_Record_Write (CSNBAKRW) 400 cipher-class keys 150
agreement for licensed internal code 758 ciphering
American Express keys 150, 162
Transaction_Validation verb 496 methods
American National Standards Institute (ANSI) 3624 PIN 698, 699
X9.19 method 689 3624 PIN offset 698
X9.9 method 689 German Bank Pool Institution PIN 699
ANS X9.24 diversified UKPT 463 InterBank PIN 700
ANS X9.31 hash format 694 message authentication code (MAC) 689
ANS X9.9:1986 Modification Detection Code (MDC) 679
message authentication code (MAC) calculation NIST SP 800-38A 684
method 689 NL-PIN-1 699
asymmetric keys 151 SNA-SLE 684
ATM 426 Visa PIN-validation value (PVV) 700
authentication 1 CKSN 431, 434, 463, 464, 469, 704
authentication data structure 643 clear keys 173
clear PIN
3624 441
B generating 441, 444
battery-low indicator 42 security 430
battery-low indicator (latch) 25 Clear_Key_Import (CSNBCKI) 198
Bellare-Rogaway 694 Clear_PIN_Encrypt (CSNBCPE) 438
building key tokens 95 Clear_PIN_Generate (CSNBPGN) 441
Clear_PIN_Generate_Alternate (CSNBCPA) 444
cloning a master key
C certificate 29
calculation methods code-signing node 739
message authentication code (MAC) 689 coding procedure calls 7
Modification Detection Code (MDC) 679 common parameters 9
PIN 431, 697 confidentiality, data 357
card security value control vectors (CVs)
EMV PIN-block 708 bit map
card verification code 706 EXPORT bit 662
card verification value 706 gks bits 661
card verification value (Visa) IMPORT bit 662
CVV_Generate verb 449 key-part bit 664
CVV_Verify verb 456 parity bits 664
771
control vectors (CVs) (continued) CSNBAKRL (AES_Key_Record_List) 396
bit map (continued) CSNBAKRLJ 743
XLATE bit 662 CSNBAKRR (AES_Key_Record_Read) 398
changing 203, 205 CSNBAKRRJ 743
Changing CSNBAKRW (AES_Key_Record_Write) 400
Control_Vector_Translate verb 667 CSNBAKRWJ 743
pre-exclusive-OR technique 665 CSNBCKC (CVV_Key_Combine) 452
changing method of key encryption 224 CSNBCKCJ 743
checking 148 CSNBCKI (Clear_Key_Import) 198
control information 667 CSNBCKIJ 743
default values 152 CSNBCKM (Multiple_Clear_Key_Import) 301
description 148 CSNBCKMJ 743
determining values 661 CSNBCPA (Clear_PIN_Generate_Alternate) 444
enciphering 198 CSNBCPAJ 744
exporting a DATA key 207 CSNBCPE (Clear_PIN_Encrypt) 438
exporting a key 227 CSNBCPEJ 744
exporting a key to TR31 501 CSNBCSG (CVV_Generate) 449
generating 200 CSNBCSGJ 744
generating a key 211, 229, 239 CSNBCSV (CVV_Verify) 456
importing a DATA key 209 CSNBCSVJ 744
importing a key 245 CSNBCVE (Cryptographic_Variable_Encipher) 205
importing parts of a key 247, 251 CSNBCVEJ 744
key form bits, fff 660 CSNBCVG (Control_Vector_Generate) 200
key separation 147 CSNBCVGJ 744
key-half processing mode 669 CSNBCVT (Control_Vector_Translate) 203
keywords 162 CSNBCVTJ 744
mask array information 667 CSNBDEC (Decipher) 360
multiply-deciphering keys 671 CSNBDECJ 744
multiply-enciphering keys 671 CSNBDKG (Diversified_Key_Generate) 211
producing ciphertext 205 CSNBDKGJ 744
specifying values 661 CSNBDKM (Data_Key_Import) 209
testing 667 CSNBDKMJ 744
translating 203 CSNBDKX (Data_Key_Export) 207
values 655 CSNBDKXJ 745
verbs 198, 200, 203, 205, 207, 209, 211, 217, 224, CSNBENC (Encipher) 363
227, 229, 239, 245, 247, 251, 256, 261, 265, 501 CSNBENCJ 745
verifying key value 256, 261 CSNBEPG (Encrypted_PIN_Generate) 459
verifying value of key, external 265 CSNBEPGJ 745
violation 667 CSNBHMG (HMAC_Generate) 366
Control_Vector_Generate (CSNBCVG) 200 CSNBHMGJ 745
Control_Vector_Translate CSNBHMV (HMAC_Verify) 369
example 671 CSNBHMVJ 745
mask array 667 CSNBKET (Key_Encryption_Translate) 224
Control_Vector_Translate (CSNBCVT) 203 CSNBKETJ 745
controlling the cryptographic facility 20 CSNBKEX (Key_Export) 227
coprocessor resource selection 59, 61 CSNBKEXJ 745
creating a hash value 126 CSNBKGN (Key_Generate) 229
cryptographic CSNBKGN2 (Key_Generate2) 239
separation 141 CSNBKGN2J 746
cryptographic engine 3 CSNBKGNJ 745
Cryptographic_Facility_Control (CSUACFC) 42 CSNBKIM (Key_Import) 245
Cryptographic_Facility_Query (CSUACFQ) 48 CSNBKIMJ 746
Cryptographic_Facility_Version (CSUACFV) 58 CSNBKPI (Key_Part_Import) 247
Cryptographic_Resource_Allocate (CSUACRA) 59 CSNBKPI2 (Key_Part_Import2) 251
Cryptographic_Resource_Deallocate (CSUACRD) 61 CSNBKPI2J 746
Cryptographic_Variable_Encipher (CSNBCVE) 205 CSNBKPIJ 746
cryptographic-variable-class keys 151 CSNBKRC (DES_Key_Record_Create) 402
CSNBAKRC (AES_Key_Record_Create) 392 CSNBKRCJ 746
CSNBAKRCJ 743 CSNBKRD (DES_Key_Record_Delete) 404
CSNBAKRD (AES_Key_Record_Delete) 394 CSNBKRDJ 746
CSNBAKRDJ 743 CSNBKRL (DES_Key_Record_List) 406

CSNBKRLJ 746 CSNBSKY (Secure_Messaging_for_Keys) 481
CSNBKRR (DES_Key_Record_Read) 408 CSNBSKYJ 750
CSNBKRRJ 746 CSNBSPN (Secure_Messaging_for_PINs) 484
CSNBKRW (DES_Key_Record_Write ) 409 CSNBSPNJ 750
CSNBKRWJ 746 CSNBT31I (TR31_Key_Import) 528
CSNBKSI (Key_Storage_Initialization) 65 CSNBT31IJ 750
CSNBKSIJ 746 CSNBT31O (TR31_Optional_Data_Build) 555
CSNBKTB (Key_Token_Build) 270 CSNBT31OJ 750
CSNBKTB2 (Key_Token_Build2) 275 CSNBT31P (TR31_Key_Token_Parse) 551
CSNBKTB2J 747 CSNBT31PJ 750
CSNBKTBJ 746 CSNBT31R (TR31_Optional_Data_Read) 558
CSNBKTC (Key_Token_Change) 279 CSNBT31RJ 750
CSNBKTC2 (Key_Token_Change2) 281 CSNBT31X (Key_Export) 501
CSNBKTC2J 747 CSNBT31XJ 751
CSNBKTCJ 747 CSNBTRV (Transaction_Validation) 496
CSNBKTP (Key_Token_Parse) 283 CSNBTRVJ 751
CSNBKTP2 (Key_Token_Parse2) 286 CSNDDSG (Digital_Signature_Generate) 118
CSNBKTP2J 747 CSNDDSGJ 751
CSNBKTPJ 747 CSNDDSV (Digital_Signature_Verify) 122
CSNBKTR (Key_Translate) 294 CSNDDSVJ 751
CSNBKTR2 (Key_Translate2) 296 CSNDEDHJ 751
CSNBKTR2J 747 CSNDKRC (PKA_Key_Record_Create) 410
CSNBKTRJ 747 CSNDKRCJ 751
CSNBKYT (Key_Test) 256 CSNDKRD (PKA_Key_Record_Delete) 412
CSNBKYT2 (Key_Test2) 261 CSNDKRDJ 751
CSNBKYT2J 748 CSNDKRL (PKA_Key_Record_List) 414
CSNBKYTJ 747 CSNDKRLJ 751
CSNBKYTX (Key_Test_Extended) 265 CSNDKRR (PKA_Key_Record_Read) 416
CSNBKYTXJ 748 CSNDKRRJ 752
CSNBMDG (MDC_Generate) 126 CSNDKRW (PKA_Key_Record_Write) 418
CSNBMDGJ 748 CSNDKRWJ 752
CSNBMGN (MAC_Generate) 372 CSNDKTC (PKA_Key_Token_Change) 103
CSNBMGNJ 748 CSNDKTCJ 752
CSNBMKP (Master_Key_Process) 74 CSNDPKB (PKA_Key_Token_Build) 95
CSNBMKPJ 748 CSNDPKBJ 752
CSNBMVR (MAC_Verify) 375 CSNDPKD (PKA_Decrypt) 305
CSNBMVRJ 748 CSNDPKDJ 752
CSNBOWH (One_Way_Hash) 134 CSNDPKE (PKA_Encrypt) 307
CSNBOWHJ 748 CSNDPKEJ 752
CSNBPCU (PIN_Change/Unblock) 475 CSNDPKG (PKA_Key_Generate) 87
CSNBPCUJ 748 CSNDPKGJ 752
CSNBPEX (Prohibit_Export) 309 CSNDPKH (PKA_Public_Key_Hash_Register) 110
CSNBPEXJ 748 CSNDPKHJ 752
CSNBPEXX (Prohibit_Export_Extended) 311 CSNDPKI (PKA_Key_Import) 92
CSNBPEXXJ 748 CSNDPKIJ 752
CSNBPGN (Clear_PIN_Generate) 441 CSNDPKR (PKA_Public_Key_Register) 112
CSNBPGNJ 749 CSNDPKRJ 753
CSNBPTR (Encrypted_PIN_Translate) 463 CSNDPKT (PKA_Key_Translate) 105
CSNBPTRJ 749 CSNDPKTJ 753
CSNBPVR (Encrypted_PIN_Verify) 469 CSNDPKX (PKA_Public_Key_Extract) 108
CSNBPVRJ 749 CSNDPKXJ 753
CSNBRKA (Restrict_Key_Attribute) 328 CSNDRKD (Retained_Key_Delete) 420
CSNBRKAJ 749 CSNDRKDJ 753
CSNBRNG (Random_Number_Generate) 313 CSNDRKL (Retained_Key_List) 422
CSNBRNGJ 749 CSNDRKLJ 753
CSNBRNGL (Random_Number_Generate_Long) 315 CSNDRKX (Remote_Key_Export) 317
CSNBRNGLJ 749 CSNDRKXJ 753
CSNBSAD (Symmetric_Algorithm_Decipher) 378 CSNDSBC (SET_Block_Compose) 489
CSNBSADJ 749 CSNDSBCJ 753
CSNBSAE (Symmetric_Algorithm_Encipher) 383 CSNDSBD (SET_Block_Decompose) 492
CSNBSAEJ 749 CSNDSBDJ 754
Index 773
CSNDSYG (Symmetric_Key_Generate) 339 data structure (continued)
CSNDSYGJ 754 authentication data 643
CSNDSYI (Symmetric_Key_Import) 345 chaining-vector-record format 633
CSNDSYI2 (Symmetric_Key_Import2) 350 examples 646
CSNDSYI2J 754 key-record-list datasets 637
CSNDSYIJ 754 key-storage record 633
CSNDSYX (Symmetric_Key_Export) 333 key-token formats 577
CSNDSYXJ 754 list of 577
CSNDTBC (Trusted_Block_Create) 353 passphrase authentication 645
CSNDTBCJ 754 profile 642, 643, 646, 647
CSUAACI (Access_Control_Initialization) 35 role 648, 649
CSUAACIJ 754 role, aggregate 639
CSUAACM (Access_Control_Maintenance) 38 role, basic 639
CSUAACMJ 754 Data_Key_Export (CSNBDKX) 207
CSUACFC (Cryptographic_Facility_Control) 42 Data_Key_Import (CSNBDKM) 209
CSUACFCJ 755 DATA-class keys 150, 162
CSUACFQ (Cryptographic_Facility_Query) 48 deactivating keys 404, 412, 420
CSUACFQJ 755 deallocating a coprocessor resource 61
CSUACFV (Cryptographic_Facility_Version) 58 decimalization table 432
CSUACFVJ 755 Decipher (CSNBDEC) 360
CSUACRA (Cryptographic_Resource_Allocate) 59 default role 641
CSUACRAJ 755 defaults, control vectors 152
CSUACRD (Cryptographic_Resource_Deallocate) 61 deleting
CSUACRDJ 755 key records 404, 412, 420, 422
CSUAKSD (Key_Storage_Designate) 63 key tokens 87, 92, 95, 103, 105, 108, 110, 112,
CSUALCT (Logon_Control) 67 404, 412, 420, 422
CSUALCTJ 755 DES key-storage initialization 65
CSUAMKD (Master_Key_Distribution) 70 DES_Key_Record_Create (CSNBKRC) 402
CSUAMKDJ 755 DES_Key_Record_Delete (CSNBKRD) 404
CSUARNT (Random_Number_Tests) 78 DES_Key_Record_List (CSNBKRL) 406
CSUARNTJ 755 DES_Key_Record_Read (CSNBKRR) 408
current key serial number 431, 434, 463, 464, 469, DES_Key_Record_Write (CSNBKRW) 409
704 device key 4
CVARENC key type 151 digital signature 1, 117
CVARXCVL key type 151 ANS X9.31 694
CVARXCVR key type 151 hash formats 694
CVC 436, 449, 456, 706 PKCS #1 694
CVV 436, 449, 456, 706 digital signature processing
CVV_Generate (CSNBCSG) 449 Digital_Signature_Generate (CSNDDSG) 118
CVV_Key_Combine (CSNBCKC) 452 Digital_Signature_Verify (CSNDDSV) 122
CVV_Verify (CSNBCSV) 456 MDC_Generate (CSNBMDG) 126
One_Way_Hash (CSNBOWH) 134
Digital_Signature_Generate (CSNDDSG) 118
D Digital_Signature_Verify (CSNDDSV) 122
data digital-signing server 733
array elements 432 Diversified_Key_Generate (CSNBDKG) 211
confidentiality 357 diversifying (smart card) keys 177
ensuring 357 dual-control security policy 247
integrity 357, 358
segmented 359
validation 432 E
data confidentiality 1, 357 EC_Diffie-Hellman (CSNDEDH) 217
Data Encryption Algorithm electronic code-book
ciphering methods 357, 681 Control_Vector_Translate verb 203
ciphering verbs 357 Cryptographic_Variable_Encipher verb 205
data confidentiality 357 Data_Key_Export verb 207
verbs 357 Data_Key_Import verb 209
data integrity 1, 357 default value 667
data structure Diversified_Key_Generate verb 211
access control 647 EC_Diffie-Hellman verb 217
authentication 643, 646 Key_Encryption_Translate verb 224

electronic code-book (continued)
Key_Export verb 227
F
financial personal identification number (PIN)
Key_Export_to_TR31 verb 501
blocks
Key_Generate verb 229
3624 434, 701
Key_Generate2 verb 239
description 430, 433, 700
Key_Import verb 245
format control 434
Key_Part_Import verb 247
ISO-0 434, 701
Key_Part_Import2 verb 251
ISO-1 434, 702
Key_Test verb 256
ISO-2 434, 702
Key_Test_Extended verb 265
ISO-3 434, 703
Key_Test2 verb 261
multiple 433
EMV standard
PIN-calculation methods 697
application transaction counter (ATC) 709
profile 433
Encrypted_PIN_Verify verb 469
calculation
MAC padding method 689
3624 PIN 698, 699
PIN_Change/Unblock verb 475
3624 PIN Offset 698
PIN-block self-encryption 709
descriptions 431, 697
Secure_Messaging_for_Keys verb 481
German Bank Pool Institution PIN 699
Secure_Messaging_for_PINs verb 484
InterBank PIN 700
session key derivation, TDES-XOR 708
supporting multiple PIN-calculation methods 431
session-key tree-based key-diversification 709
VISA-PVV 700
smart-card-specific key 708
data array
unique derivation key 707
decimalization table 432
working with EMV smart cards 437
transaction security data 432, 433
Encipher (CSNBENC) 363
validation data 432
Encrypted_PIN_Generate (CSNBEPG) 459
extracting 435
Encrypted_PIN_Translate (CSNBPTR) 463
extraction methods 435
Encrypted_PIN_Verify (CSNBPVR) 469
format control 434
entry-point names 6, 7
formatting 434
prefixes 6, 7
generating clear PIN 441, 444
environment identifier (EID) 29
key types 430
environment, supported 7
key-usage bits 430
establishing master keys 28
personal account number (PAN) 436
EX (exportable) keys 142
PIN profile
exit_data parameter 9
format-control element 434
exit_data_length parameter 9
pad-digit element 434
exportable (EX) keys 142
PIN-block format element 433
exporting keys
processing
trusted blocks 184
description 426
exporting, description 175, 665
extraction methods 433
external
security 430
key tokens
supporting multiple PIN-calculation methods 431
building 270, 275
verbs 426
changing 279, 281
security 430
format 581
verbs
Key_Token_Build verb 270
CSNBCKC (CVV_Key_Combine) 452
Key_Token_Build2 verb 275
CSNBCPA (Clear_PIN_Generate_Alternate) 444
Key_Token_Change verb 279
CSNBCPE (Clear_PIN_Encrypt) 438
Key_Token_Change2 verb 281
CSNBCSG (CVV_Generate) 449
PKA, RSA 585
CSNBCSV (CVV_Verify) 456
RSA 585
CSNBEPG (Encrypted_PIN_Generate) 459
trusted block 600
CSNBPCU (PIN_Change/Unblock 475
key tokens, description 168
CSNBPGN (Clear_PIN_Generate) 441
keys 142, 175
CSNBPTR (Encrypted_PIN_Translate) 463
extracting keys 108
CSNBPVR (Encrypted_PIN_Verify) 469
extraction methods, financial PIN 435
CSNBSKY (Secure_Messaging_for_Keys) 481
CSNBSPN (Secure_Messaging_for_PINs) 484
CSNBTRV (Transaction_Validation) 496
CSNDSBC (SET_Block_Compose) 489
CSNDSBD (SET_Block_Decompose) 492
flag byte 580
Index 775
flag byte 1 583 importer (continued)
format Key_Import verb 150
chaining_vector record 633 Key_Translate verb 150
control, financial PIN 434 importing keys 92
key tokens description 175
external 581 importing, description 175, 665
internal 581 initializing key storage 63, 65
null 578 Input/Output
key-record-list datasets 637 parameters 8
key-storage record 633 input/output (I/O) parameters 8
formatting hashes and keys 694 installing keys 172
function control vector 650 Interbank
functional overview, CCA 1 calculation method 433, 700
intermediate PIN-block (IPB) 702, 703
internal 169
G key tokens
generating a digital signature 118 building 270, 275
generating key changing 279, 281
control vectors 200 copying into application storage 408
CSNBTRV 496 copying into key storage 409, 418
CVV 449 format 581
Key_Generate verb 173 Key_Token_Build verb 270
keys 173 Key_Token_Build2 verb 275
generating keys 87 Key_Token_Change verb 279
remote key export 187 Key_Token_Change2 verb 281
German Bank Pool Institution PIN RSA 585
calculation method 699 introduction 1
introduction of master-key parts 28
intrusion latch 24, 42
H IPB (intermediate PIN-block) 702, 703
hash formatting 694 IPINENC
hashing Clear_PIN_Generate_Alternate verb 151, 431
data 115 control-vector default values 657
Digital_Signature_Generate 118 Encrypted_PIN_Translate verb 151, 431
Digital_Signature_Verify 122 Encrypted_PIN_Verify verb 151, 431
MD5 116 ISO-0 PIN-block format 701
MDC 116 ISO-1 PIN-block format 702
One_Way_Hash 134 ISO-2 PIN-block format 702
RIPEMD-160 116 ISO-3 PIN-block format 703
SHA-1 116
SHA-224 134
SHA-256 134 J
SHA-384 134 Java interaction 1
SHA-512 134 Java Native Interface (JNI) 743
HMAC_Generate (CSNBHMG) 366
HMAC_Verify (CSNBHMV) 369
K
key cache, host side 6
I key diversification 177
IBM 3624 PIN-calculation method key formatting 694
block format 701 key identifier 170
calculation method 698, 699 key label 164, 170, 390
clear 441 key management 1
offset calculation method 698 (CSNBCKI) 198
IM (importable) keys 142 exporting keys 665
importable (IM) keys 142 generating keys 173
importer importing keys 175
Control_Vector Translate verb 150 key shares 28
control-vector default values 657 key storage
Data_Key_Import verb 150 description 178
Key_Generate verb 150

key storage (continued) key token (continued)
key-record-list datasets Key_Translate2 verb 296
listing 396, 406 listing 422
listing key record 414 null 169, 578
verbs 170 operational 10
key token PKA_Decrypt verb 305
assembling 270, 275 PKA_Encrypt verb 307
changing 103, 105, 279, 281 prohibit export 309
clear key multiple enciphering 301 prohibit export extended 311
contents 165 Prohibit_Export verb 309
decrypting 305 Prohibit_Export_Extended verb 311
deleting 412, 420 Random_Number_Generate verb 313
DES 580 Random_Number_Generate_Long verb 315
DES external 581 record-validation value (RVV) 578
DES internal 581 remote key export 317
description 165 Remote_Key_Export verb 317
description, external 577 RSA 585
description, internal 577 section sequence, ECC 587
disassembling 283 section sequence, PKA/RSA 586
encrypting 307 section sequence, trusted block 601
exporting 333 symmetric algorithm decipher 378
external 10, 168, 270, 275 symmetric algorithm encipher 383
Key_Token_Build verb 270 Symmetric_Algorithm_Decipher verb 378
Key_Token_Build2 verb 275 Symmetric_Algorithm_Encipher verb 383
PKA_Key_Generate verb 87 Symmetric_Key_Export verb 333
PKA_Key_Import verb 92 Symmetric_Key_Generate verb 339
PKA_Key_Record_Delete verb 412 Symmetric_Key_Import verb 345
PKA_Key_Token_Build verb 95 Symmetric_Key_Import2 verb 350
PKA_Key_Token_Change verb 103 token-validation value (TVV) 578
PKA_Key_Translate verb 105 translating 294, 296
PKA_Public_Key_Extract verb 108 transport key 577
PKA_Public_Key_Hash_Register verb 110 trusted block 600
PKA_Public_Key_Register verb 112 trusted block create 353, 528, 551, 555, 558
flag byte 580 Trusted Block Create verb 353
flag byte 1 583 key usage
format 165, 577 importing and exporting keys 175
generate long random number 315 key-usage keywords 162
generate random number 313 transport keys 175
generating 339 use in multiply-enciphering a key in an external
importing 345, 350 key-token 168
internal 10, 169, 270, 275 use in the exclusive-OR step in multiple-
Key_Token_Build verb 270 encipherment and multiple-decipherment 671
Key_Token_Build2 verb 275 Key_Encryption_Translate (CSNBKET) 224
Key_Token_Parse verb 283 Key_Export (CSNBKEX) 227
Key_Token_Parse2 verb 286 Key_Export_to_TR31 (CSNBT31X) 501
PKA_Key_Generate verb 87 Key_Generate (CSNBKGN) 229
PKA_Key_Import verb 92 Key_Generate2 (CSNBKGN2) 239
PKA_Key_Record_Delete verb 412 Key_Import (CSNBKIM) 245
PKA_Key_Token_Build verb 95 Key_Part_Import (CSNBKPI) 247
PKA_Key_Token_Change verb 103 Key_Part_Import2 (CSNBKPI2) 251
PKA_Key_Translate verb 105 Key_Storage_Designate (CSUAKSD) 63
PKA_Public_Key_Extract verb 108 Key_Storage_Initialization (CSNBKSI) 65
PKA_Public_Key_Hash_Register verb 110 Key_Test (CSNBKYT) 256
PKA_Public_Key_Register verb 112 Key_Test_Extended (CSNBKYTX) 265
Key_Token_Build verb 270 Key_Test2 (CSNBKYT2) 261
Key_Token_Build2 verb 275 Key_Token_Build (CSNBKTB) 270
Key_Token_Change verb 279 Key_Token_Build2 (CSNBKTB2) 275
Key_Token_Change2 verb 281 Key_Token_Change (CSNBKTC) 279
Key_Token_Parse verb 283 Key_Token_Change2 (CSNBKTC2) 281
Key_Token_Parse2 verb 286 Key_Token_Parse (CSNBKTP) 283
Key_Translate verb 294 Key_Token_Parse2 (CSNBKTP2) 286
Index 777
Key_Translate (CSNBKTR) 294 key-processing and key-storage verbs (continued)
Key_Translate2 (CSNBKTR2) 296 Symmetric_Algorithm_Encipher (CSNBSAE) 383
key-encrypting key 142 TR31_Key_Import (CSNBT31I) 528
key-encrypting-key class keys 150 TR31_Key_Token_Parse (CSNBT31P) 551
key-export operation 175 TR31_Optional_Data_Build (CSNBT31O) 555
key-generating keys 163 TR31_Optional_Data_Read (CSNBT31R) 558
key-generating-key class keys 151 Trusted_Block_Create (CSNDTBC) 353
key-half processing mode 669 using 170
key-import operation 176 key-record-list datasets 637
key-management keys key-storage initialization 63, 65
Common Cryptographic Architecture key-storage selection 63
support 137 key-token verification patterns 678
key-processing and key-storage verbs 170 keys
AES_Key_Record_Create (CSNBAKRC) 392 asymmetric 151
AES_Key_Record_Delete (CSNBAKRD) 394 ciphering 150, 162
AES_Key_Record_List (CSNBAKRL) 396 class 137
AES_Key_Record_Read (CSNBAKRR) 398 clear 173
AES_Key_Record_Write (CSNBAKRW) 400 control vectors 147
Control_Vector_Translate (CSNBCVT) 203 deciphering 360
Cryptographic_Resource_Allocate (CSUACRA) 59 Decipher verb 360
Cryptographic_Resource_Deallocate deleting 412, 420
(CSUACRD) 61 double-length 152
Cryptographic_Variable_Encipher (CSNBCVE) 205 enciphering 363
CVV_Key_Combine (CSNBCKC) 452 Encipher verb 363
Data_Key_Export (CSNBDKX) 207 exportable (EX) 142
Data_Key_Import (CSNBDKM) 209 exporting, asymmetric techniques 176
DES_Key_Record_Create (CSNBKRC) 402 exporting, symmetric techniques 175
DES_Key_Record_Delete (CSNBKRD) 404 external 142
DES_Key_Record_List (CSNBKRL) 406 external DES key-tokens 168
DES_Key_Record_Read (CSNBKRR) 408 extracting 108
DES_Key_Record_Write (CSNBKRW) 409 generate HMAC 366
Diversified_Key_Generate (CSNBDKG) 211 HMAC_Generate verb 366
EC_Diffie-Hellman (CSNDEDH) 217 generate MAC 372
Key_Encryption_Translate (CSNBKET) 224 MAC_Generate verb 372
Key_Export (CSNBKEX) 227 generating, DES 173
Key_Export_to_TR31 (CSNBT31X) 501 generating, RSA 691
Key_Generate (CSNBKGN) 229 identifiers 170
Key_Generate2 (CSNBKGN2) 239 importable (IM) 142
Key_Import (CSNBKIM) 245 importing 175
Key_Part_Import (CSNBKPI) 247 importing, asymmetric techniques 176
Key_Part_Import2 (CSNBKPI2) 251 installing 172
Key_Storage_Designate (CSUAKSD) 63 key management 137, 140
Key_Storage_Initialization (CSNBKSI) 65 key-encrypting key 142
Key_Test (CSNBKYT) 256 key-storage initialization 63, 65
Key_Test_Extended (CSNBKYTX) 265 key-usage keywords 160
Key_Test2 (CSNBKYT2) 261 label 164
PKA_Key_Import (CSNDPKI) 92 label, content 390
PKA_Key_Record_Create (CSNDKRC) 410 labels
PKA_Key_Record_Delete (CSNDKRD) 412 definition 170
PKA_Key_Record_List (CSNDKRL) 414 length 164
PKA_Key_Record_Read (CSNDKRR) 416 listing 422
PKA_Key_Record_Write (CSNDKRW) 418 managing 137, 140
PKA_Key_Token_Build (CSNDPKB) 95 master key 11
PKA_Key_Token_Change (CSNDKTC) 103 master-key loading 74, 78
PKA_Public_Key_Extract (CSNDPKX) 108 multiply-deciphered 142, 176
PKA_Public_Key_Hash_Register (CSNDPKH) 110 multiply-enciphered 141, 173
PKA_Public_Key_Register (CSNDPKR) 112 operational (OP) 142
Remote_Key_Export (CSNDRKX) 317 parity 142
Retained_Key_Delete (CSNDRKD) 420 parts
Retained_Key_List (CSNDRKL) 422 generating 173
Symmetric_Algorithm_Decipher (CSNBSAD) 378 secure 172

keys (continued) keys (continued)
processing types (continued)
verbs 170 PINGEN 151, 431
records PINVER 151, 431
add key record 410 secure-messaging-class keys 150
AES_Key_Record_Delete verb 394 symmetric 151
AES_Key_Record_List verb 396 unique-key-per-transaction (UKPT) 463
AES_Key_Record_Read verb 398 usage
AES_Key_Record_Write verb 400 bits 430
creating 87, 112, 402, 410 key form 173
deleting 394, 404, 412, 420 key type 173
DES_Key_Record_Create verb 402 keywords 160
DES_Key_Record_Delete verb 404 restrictions 173
DES_Key_Record_List verb 406 verification pattern 173
DES_Key_Record_Read verb 408 verify MAC 369, 375
DES_Key_Record_Write verb 409 HMAC_Verify verb 369
importing 92 MAC_Verify verb 375
listing 396, 406, 422 verifying 172
PKA_Key_Record_Create verb 410 keywords, key-usage 160
PKA_Key_Record_Delete verb 412
PKA_Key_Record_List verb 414
PKA_Key_Record_Read verb 416 L
PKA_Key_Record_Write verb 418 licensed internal code
reading 398, 408, 416 agreement 758
Retained_Key_Delete verb 420 list, access-control commands 715
Retained_Key_List verb 422 listing keys 422
writing 400, 409, 418 loading a master key 74, 78
reenciphering 103, 105 Logging on and logging off 18
RSA token sections 585 logon context information 19
secure messaging 150 Logon_Control (CSUALCT) 67
separation 147
storing 178
symmetric 151 M
transport 577 MAC verify
trusted block 600 control-vector default values 657
types MAC_Generate (CSNBMGN) 359, 372
and verbs 160 MAC_Verify (CSNBMVR) 359, 375
asymmetric 151 managing
CIPHER 150 DES keys
cipher-class keys 150 Common Cryptographic Architecture 137
cryptographic-variable class keys 151 mask array preparation 667
CVARENC 151 master key 4, 11
CVARXCVL 151 m-of-n 28
CVARXCVR 151 cloning 29
DATA-class keys 150 current master-key 27
DECIPHER 150 environment identifier (EID) 29
description 149 establishing 28
ENCIPHER 150 introduction of master-key parts 28
EXPORTER 150 master-key cloning 28
IKEYXLAT 150 multi-coprocessor considerations 31
IMPORTER 150 new master-key 27
IPINENC 151, 431 old master-key 27
key-encrypting-key class keys 150 random generation of a new master-key 28
key-generating-key class keys 151 shares 28
key-usage keywords 162 symmetric and asymmetric 27
MAC-class keys 150 understanding and managing master keys 27
OKEYXLAT 150 Master_Key_Distribution (CSUAMKD) 70
one-way key-distribution channels 152 Master_Key_Process (CSNBMKP) 74
OPINENC 151, 431 master-derivation keys (MDK) 475
PIN security 430 master-key cloning 28
PIN-class keys 151 master-key loading 65, 74, 78
Index 779
master-key verification pattern 27 OPINENC (continued)
MasterCard, CVC 449, 456, 706 Encrypted_PIN_Translate verb 151, 431
MD5 116 OPK, object protection key 590, 592, 610
MDC 116 output chaining value (OCV) 683
MDC keyed hash 128 overlapped processing restrictions 6
MDC_Generate (CSNBMDG) 126
message authentication code
calculation methods 689 P
ensuring data integrity 358 pad digit 434
generating 359 PAN (personal account number) 436
segmented data 359 parameters
values 359 common 9
Modification Detection Code description 9
calculation method 679 exit_data 9
segmented data 359 exit_data_length 9
services 358 keyword 10
multi-coprocessor reason_code 9, 561
0S/400 support 26, 31 return_code 9, 561
AIX, Linux, and Windows support 26 rule_array 10
capability 25 transaction_security 432
CCA host implementation 26 variable direction and type 9
control vector 671 verb 7
description 141 parity 142
generating 173 parity, key 142
IBM i 31 parity, key parts 247
master key considerations 31 personal account number (PAN) 436
single- and double-length keys 673 PIN
multiple PIN-calculation methods 431 calculation methods 697
Multiple_Clear_Key_Import (CSNBCKM) 301 PIN verify
multiply-deciphered keys 142, 176 control-vector default values 657
multiply-enciphered keys 141, 173 Encrypted_PIN_Verify verb 151, 431
PIN_Change/Unblock (CSNBPCU) 475
PIN-block encrypting key 431
N PIN-class keys 151, 163
NIST SP 800-38A CBC method 682, 684 PINGEN
non-repudiation 1 Clear_PIN_Generate verb 151, 431
notices Clear_PIN_Generate_Alternate verb 151, 431
licensed internal code 758 Clear_PIN_Verify verb 431
notices statement 757 control-vector default values 657
null DES key-token 169 Encrypted_PIN_Generate verb 151, 431
null key-token 578 Encrypted_PIN_Generate_Alternate verb 151, 431
Encrypted_PIN_Verify verb 151
PKA_Decrypt (CSNDPKD) 305
O PKA_Encrypt (CSNDPKE) 307
OAEP 694 PKA_Key_Generate (CSNDPKG) 87
object protection key (OPK) 590, 592, 610 PKA_Key_Import (CSNDPKI) 92
obtaining a hash value 134 PKA_Key_Record_Create (CSNDKRC) 410
OCV (output chaining value) 683 PKA_Key_Record_Delete (CSNDKRD) 412
OKEYXLAT PKA_Key_Record_List (CSNDKRL) 414
control-vector default values 657 PKA_Key_Record_Read (CSNDKRR) 416
Key_Translate verb 150 PKA_Key_Record_Write (CSNDKRW) 418
One_Way_Hash (CSNBOWH) 134 PKA_Key_Token_Build (CSNDPKB) 95
OP (operational) keys 142, 176 PKA_Key_Token_Change (CSNDKTC) 103
operating environments PKA_Key_Translate (CSNDPKT) 105
supported environments 6 PKA_Public_Key_Extract (CSNDPKX) 108
operational (OP) keys 176 PKA_Public_Key_Hash_Register (CSNDPKH) 110
operational keys (OP) 142 PKA_Public_Key_Register (CSNDPKR) 112
OPINENC PKCS #1 formats 694
Clear_PIN_Encrypt verb 151, 431 pre-exclusive-OR technique 665
control-vector default values 657 private key
Encrypted_PIN_Generate verb 151, 431 Integrity 587, 602

private key (continued) RIPEMD-160 116
OPK, object protection key 590, 592, 610 RKX key-token 183, 583
procedure calls 6, 7 role, default 641
processing a master key 74, 78 roles, access control
processing overlap 6 default role 15
profile structure, aggregate 643 overview 14
profiles verbs for initialization and management 16
overview 15 RSA key generation
passphrase verification protocol 692 4764 691
passphrases 18 4765 691
personal identification number (PIN) RSA key-pair generation 691
PIN profile 433 RSA private key
verbs for initialization and management 16 decrypting 305
Prohibit_Export (CSNBPEX) 309 RSA public key
Prohibit_Export_Extended (CSNBPEXX) 311 encrypting 307
pseudonyms 7, 711 exporting 333
generate long random number 315
generate random number 313
R generating 339
random generation of a new master-key 28 importing 345, 350
Random_Number_Generate (CSNBRNG) 313 prohibit export 309
Random_Number_Generate_Long (CSNBRNGL) 315 prohibit export extended 311
Random_Number_Tests (CSUARNT) 78 remote key export 317
reason codes 561 trusted block create 353
reason_code parameter 9 rule_array parameter description 10
record RVV (record-validation value) 578
chaining vector 633
key storage 633
key-record-list 637 S
record-validation value (RVV) 578 Secure_Messaging_for_Keys (CSNBSKY) 481
reenciphering keys 103, 105, 422 Secure_Messaging_for_PINs (CSNBSPN) 484
registering a hash value 110 secure-messaging-class keys 150
registering a public key 112 secured code-signing node 739
remote key distribution 178 security API
benefits 197 fundamentals 6
scenario 189 security API verbs
remote key export fundamentals 6
exporting keys 184 list of verbs 711
generating keys 187 procedure calls 7
remote key-loading 178 verbs 7
CCA API changes 182 security precautions 197
example 178 segmented data 359
new method 179 selecting a coprocessor resource 59, 61
Remote_Key_Export (CSNDRKX) 317 selecting key storage 63
replicated key-half self-encryption, EMV-related PIN block 709
export restriction 210, 227, 245 SET_Block_Compose (CSNDSBC) 489
export restriction an EXPORTER transport key 207 SET_Block_Decompose (CSNDSBD) 492
required commands SHA-1 116
description 640 SHA-224 134
list of access-control-point codes 715 SHA-256 134
overview 15 smart-card PIN transport 708
Restrict_Key_Attribute (CSNBRKA) 328 SNA-SLE
Restrict_Key_Attribute verb 328 ciphering method 684
Retained_Key_Delete (CSNDRKD) 420 special encryption 705
Retained_Key_List (CSNDRKL) 422 supported environment descriptor 7
return codes symmetric and asymmetric master keys 27
and reason codes 561 symmetric keys 151
description 561 Symmetric_Algorithm_Decipher (CSNBSAD) 378
parameter descriptions 7 Symmetric_Algorithm_Encipher (CSNBSAE) 383
verb 561 Symmetric_Key_Export (CSNDSYX) 333
return_code parameter 9 Symmetric_Key_Generate (CSNDSYG) 339
Index 781
Symmetric_Key_Import (CSNDSYI) 345 verb entry-point names (continued)
Symmetric_Key_Import2 (CSNDSYI2) 350 CSNBCVT 203
CSNBDEC 360
CSNBDKG 211
T CSNBDKM 209
TDES 685 CSNBDKX 207
tests, control vectors 667 CSNBENC 363
token-validation value (TVV) 578 CSNBEPG 459
TR31_Key_Import (CSNBT31I) 528 CSNBHMG 366
TR31_Key_Token_Parse (CSNBT31P) 551 CSNBHMV 369
TR31_Optional_Data_Build (CSNBT31O) 555 CSNBKET 224
TR31_Optional_Data_Read (CSNBT31R) 558 CSNBKEX 227
Transaction_Validation (CSNBTRV) 496 CSNBKGN 229
transport key 577 CSNBKGN2 239
trial pin 426 CSNBKIM 245
Triple-DES 685 CSNBKPI 247
trusted blocks 179 CSNBKPI2 251
CCA API changes 182 CSNBKRC 402
creating 184 CSNBKRD 404
exporting keys 184 CSNBKRL 406
using 184 CSNBKRR 408
Trusted_Block_Create (CSNDTBC) 353 CSNBKRW 409
TVV (token-validation value) 578 CSNBKSI 65
CSNBKTB 270
CSNBKTB2 275
U CSNBKTC 279
UKPT 704 CSNBKTC2 281
UKPT (unique key per transaction) 463 CSNBKTP 283
understanding and managing master keys 27 CSNBKTP2 286
current master-key 27 CSNBKTR 294
new master-key 27 CSNBKTR2 296
old master-key 27 CSNBKYT 256
unique key per transaction (UKPT) 463 CSNBKYT2 261
unique-key-per-transaction 704 CSNBKYTX 265
Encrypted_PIN_Translate verb 431 CSNBMDG 126
Encrypted_PIN_Verify verb 431 CSNBMGN 372
CSNBMKP 74
CSNBMVR 375
V CSNBOWH 134
CSNBPCU 475
validation data 432
CSNBPEX 309
variables
CSNBPEXX 311
description 7
CSNBPGN 441
direction 8
CSNBPTR 463
length 9
CSNBPVR 469
maximum length 8
CSNBRNG 313
types 8
CSNBRNGL 315
verb entry-point names
CSNBSAD 378
CSNBAKRC 392
CSNBSAE 383
CSNBAKRD 394
CSNBSKY 481
CSNBAKRL 396
CSNBSPN 484
CSNBAKRR 398
CSNBT31I 528
CSNBAKRW 400
CSNBT31O 555
CSNBCKC 452
CSNBT31P 551
CSNBCKI 198
CSNBT31R 558
CSNBCKM 301
CSNBT31X 501
CSNBCPA 444
CSNBTRV 496
CSNBCPE 438
CSNDDSG 118
CSNBCSG 449
CSNDDSV 122
CSNBCSV 456
CSNDEDH 217
CSNBCVE 205
CSNDKRC 410
CSNBCVG 200

verb entry-point names (continued) verb entry-point names (continued)
CSNDKRD 412 Key_Test2 (CSNBKYT2) 261
CSNDKRL 414 verbs
CSNDKRR 416 common parameters
CSNDKRW 418 exit_data 9
CSNDKTC 103 exit_data_length 9
CSNDPKB 95 reason_code 9
CSNDPKD 305 return_code 9
CSNDPKE 307 rule_array 10
CSNDPKG 87 data confidentiality 357
CSNDPKH 110 data integrity 357
CSNDPKI 92 descriptions 7
CSNDPKR 112 entry-point names 6
CSNDPKT 105 list of 6
CSNDPKX 108 parameters 9
CSNDRKD 420 procedure calls 6, 7
CSNDRKL 422 processing 561
CSNDRKX 317 pseudonyms 7, 711
CSNDSBC 489 reason codes 561
CSNDSBD 492 return codes 561
CSNDSYG 339 supported environments 6
CSNDSYI 345, 350 variables 9
CSNDSYI2 350 verification pattern 173, 677
CSNDSYX 333 verifying a digital signature 122
CSNDTBC 353 verifying key
CSUAACI 35 card-verification value (CVV) 449, 456
CSUAACM 38 keys 172
CSUACFC 42 Visa PIN-validation value (PVV)
CSUACFQ 48 calculation method 432, 700
CSUACFV 58 Visa, CVV 449, 456, 706
CSUACRA 59
CSUACRD 61
CSUAKSD 63 X
CSUALCT 67 X9.31 hash format 694
CSUAMKD 70
CSUARNT 78
Index 783

Bs Latest Edition

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Bs Latest Edition

Transféré par

Droits d'auteur :

Formats disponibles

CCA Basic Services Reference and Guide

for the IBM 4765 PCIe and IBM 4764

About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

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

Chapter 2. CCA node management and access control . . . . . . . . . . . . . . . . . 13

Chapter 3. PKA key-management . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 4. Hashing and digital signatures . . . . . . . . . . . . . . . . . . . . . . 115

| Chapter 5. AES, DES, and HMAC symmetric-key management . . . . . . . . . . . . . . 137

iv CCA Basic Services October 14, 2011

Chapter 7. Key-storage mechanisms . . . . . . . . . . . . . . . . . . . . . . . . 389

Chapter 8. Financial services support . . . . . . . . . . . . . . . . . . . . . . . 425

vi CCA Basic Services October 14, 2011

| Chapter 9. TR-31 symmetric-key management . . . . . . . . . . . . . . . . . . . . 499

Appendix A. Return codes and reason codes . . . . . . . . . . . . . . . . . . . . 561

Appendix B. Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

Appendix C. CCA control-vector definitions and key encryption . . . . . . . . . . . . . 655

Appendix D. Algorithms and processes . . . . . . . . . . . . . . . . . . . . . . . 677

viii CCA Basic Services October 14, 2011

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

Appendix H. Observations on secure operations . . . . . . . . . . . . . . . . . . . 725

Appendix I. Java Native Interface . . . . . . . . . . . . . . . . . . . . . . . . . 743

List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

xii CCA Basic Services October 14, 2011

xiv CCA Basic Services October 14, 2011

xvi CCA Basic Services October 14, 2011

| On Power Systems, the following operating systems are supported:

| System x has the following operating systems supported:

| Twenty-fourth edition, September 2011, CCA Support Program,

| Other Release 4.2 changes

xviii CCA Basic Services October 14, 2011

About this document xix

xx CCA Basic Services October 14, 2011

Twenty-third edition, June 2011, CCA Support Program, Releases 4.1,

About this document xxi

Twenty-second edition, February 2011, CCA Support Program,

Other Release 3.60 changes

Twenty-first edition, September 2010, CCA Support Program, Releases

Other Release 4.1 changes

xxii CCA Basic Services October 14, 2011

Twentieth edition, April 2010, CCA Support Program, Releases 3.20,

Other Release 4.0 changes

About this document xxiii

Nineteenth edition, September 2008, CCA Support Program, Releases

Other Release 3.30 changes

xxiv CCA Basic Services October 14, 2011

About this document xxv

xxvi CCA Basic Services October 14, 2011

Eighteenth edition, October 2006, CCA Support Program, Releases

Seventeenth edition, May 2006, CCA Support Program, Releases 3.20,

Other Release 3.25 changes

About this document xxvii

xxviii CCA Basic Services October 14, 2011

How this document is organized

About this document xxix

xxx CCA Basic Services October 14, 2011

About this document xxxi

xxxii CCA Basic Services October 14, 2011

Section topics include:

Available Common Cryptographic Architecture verbs

Common Cryptographic Architecture functional overview

Figure 1. CCA security API, access layer, and cryptographic engine

Note: AES is not supported in releases before Release 3.30.

2 CCA Basic Services October 14, 2011

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