# SecureKey Programming


---

(cid:2)(cid:3)(cid:4)
Linux for System z
Secure Key Solution with the Common
Cryptographic Architecture Application
Programmer's Guide
SC33-8294-02

(cid:2)(cid:3)(cid:4)
Linux for System z
Secure Key Solution with the Common
Cryptographic Architecture Application
Programmer's Guide
SC33-8294-02

Note!
Beforeusingthisinformationandtheproductitsupports,besuretoreadthegeneralinformationinthe“Notices”onpage
561.
ThirdEdition(March2011)
ThiseditionappliestotheCommonCryptographicArchitecture(CCA)API,Release4.1.0,forLinuxonIBMSystem
z,andtoallsubsequentreleasesandmodificationsuntilotherwiseindicatedinneweditions.
ThiseditionreplacesSC33-8294-01.
Thisbookisforplanningandprogrammingpurposesonly.
IBMwelcomesyourcomments.Aformforreaders'commentsmaybeprovidedatthebackofthisdocument,oryou
mayaddressyourcommentstothefollowingaddress:
IBMDeutschlandResearch&DevelopmentGmbH
InformationDevelopment
Department3248
SchoenaicherStrasse220
71032Boeblingen
Germany
Internete-mail:eservdoc@de.ibm.com
Ifyouwouldlikeareply,besuretoincludeyourname,address,telephonenumber,orFAXnumber.
Makesuretoincludethefollowinginyourcommentornote:
v Titleandordernumberofthisdocument
v Pagenumberortopicrelatedtoyourcomment
WhenyousendinformationtoIBM,yougrantIBManonexclusiverighttouseordistributetheinformationinany
wayitbelievesappropriatewithoutincurringanyobligationtoyou.
©CopyrightIBMCorporation2007,2011.
USGovernmentUsersRestrictedRights–Use,duplicationordisclosurerestrictedbyGSAADPScheduleContract
withIBMCorp.

Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
|| Third edition, March 2011, CCASupport Program Release 4.1.0 . . . . . . . . . . . . . . xv
Second edition,April 2010, CCASupport Program Release 4.0.0. . . . . . . . . . . . . . xvi
Who should use this document . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Distribution-specific information . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
How to use this document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Where to find more information . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Do you have problems, comments, or suggestions?. . . . . . . . . . . . . . . . . . . . xx
Part 1. IBM CCA programming. . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter1. Introduction to programming for the IBM Common CryptographicArchitecture. . . . 3
Available Common CryptographicArchitecture verbs . . . . . . . . . . . . . . . . . . . . 3
Common CryptographicArchitecture functional overview . . . . . . . . . . . . . . . . . . 4
How application programs obtain service . . . . . . . . . . . . . . . . . . . . . . . 7
Overlapped processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CPACF support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Environment variables that affect CPACF usage. . . . . . . . . . . . . . . . . . . . . 8
Access control points that affect CPACF protected key operations . . . . . . . . . . . . . . 9
CPACF operation (protected key) . . . . . . . . . . . . . . . . . . . . . . . . . . 9
CCAlibrary CPACF preparation at startup . . . . . . . . . . . . . . . . . . . . . . 11
Interaction between the 'default card' and use of Protected Key CPACF . . . . . . . . . . . 11
SecurityAPI programming fundamentals . . . . . . . . . . . . . . . . . . . . . . . . 12
Verbs, variables, and parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 12
Commonly encountered parameters. . . . . . . . . . . . . . . . . . . . . . . . . 14
How to compile and link CCAapplication programs . . . . . . . . . . . . . . . . . . . . 16
Building Java applications to use with the CCAJNI . . . . . . . . . . . . . . . . . . . 16
|| Chapter2. UsingAES, DES, and HMAC cryptography and verbs . . . . . . . . . . . . . 19
|| Functions of theAES, DES and HMAC cryptographic keys . . . . . . . . . . . . . . . . . 19
Key separation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Master key variant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Transport key variant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Key forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
|| Key wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Control vector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Types of keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Multi-coprocessor capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Using the CCAnode and master key management verbs. . . . . . . . . . . . . . . . . . 32
Verbs for managingAES and DES key storage files. . . . . . . . . . . . . . . . . . . . 33
Verbs for managing the PKAkey storage file and PKAkeys in the cryptographic engine . . . . . . 33
|| Improved remote key distribution. . . . . . . . . . . . . . . . . . . . . . . . . . . 34
|| Remote key loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Verbs that support Secure Sockets Layer (SSL) . . . . . . . . . . . . . . . . . . . . . 36
©CopyrightIBMCorp.2007,2011 iii

Enciphering and deciphering data . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Managing data integrity and message authentication . . . . . . . . . . . . . . . . . . . 36
Message authentication code processing. . . . . . . . . . . . . . . . . . . . . . . 36
Hashing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Processing personal identification numbers . . . . . . . . . . . . . . . . . . . . . . . 37
Verifying credit card data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Secure messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Trusted Key Entry support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Typical sequences of CCAverbs. . . . . . . . . . . . . . . . . . . . . . . . . . . 39
|| Summary of the CCAnodes and resource control verbs . . . . . . . . . . . . . . . . . . 40
Summary of theAES, DES, and HMAC verbs . . . . . . . . . . . . . . . . . . . . . . 40
Chapter3. Introducing PKAcryptography and using PKAverbs. . . . . . . . . . . . . . 47
|| PKAkey algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
PKAmaster keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Operational private keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
PKAverbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Verbs supporting digital signatures . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Verbs for PKAkey management . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
PKAkey tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
PKAkey management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Key identifier for PKAkey token . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Key label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Summary of the PKAverbs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Part 2. CCA verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
|| Chapter4. Using the CCAnodes and resource control verbs. . . . . . . . . . . . . . . 57
Cryptographic Facility Query (CSUACFQ) . . . . . . . . . . . . . . . . . . . . . . . 58
Determining if a card is a CEX2C or CEX3C . . . . . . . . . . . . . . . . . . . . . 58
Cryptographic Facility Version (CSUACFV) . . . . . . . . . . . . . . . . . . . . . . . 84
Cryptographic ResourceAllocate (CSUACRA) . . . . . . . . . . . . . . . . . . . . . . 86
Cryptographic Resource Deallocate (CSUACRD). . . . . . . . . . . . . . . . . . . . . 88
Key Storage Initialization (CSNBKSI) . . . . . . . . . . . . . . . . . . . . . . . . . 90
Master Key Process (CSNBMKP) . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Questionable DES keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Random Number Tests (CSUARNT) . . . . . . . . . . . . . . . . . . . . . . . . . 97
|| Chapter5. ManagingAES and DES cryptographic keys . . . . . . . . . . . . . . . . . 99
Clear Key Import (CSNBCKI). . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Control Vector Generate (CSNBCVG) . . . . . . . . . . . . . . . . . . . . . . . . 102
Control Vector Translate (CSNBCVT). . . . . . . . . . . . . . . . . . . . . . . . . 104
Cryptographic Variable Encipher (CSNBCVE). . . . . . . . . . . . . . . . . . . . . . 107
Data Key Export (CSNBDKX) . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Data Key Import (CSNBDKM) . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Diversified Key Generate (CSNBDKG) . . . . . . . . . . . . . . . . . . . . . . . . 113
Key Export (CSNBKEX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Key Generate (CSNBKGN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
|| Key Generate2 (CSNBKGN2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Key Import (CSNBKIM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Key Part Import (CSNBKPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
|| Key Part Import2 (CSNBKPI2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Key Test (CSNBKYT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
|| Key Test2 (CSNBKYT2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Key Test Extended (CSNBKYTX) . . . . . . . . . . . . . . . . . . . . . . . . . . 150
iv LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Build (CSNBKTB). . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
|| Key Token Build2 (CSNBKTB2). . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Key Token Change (CSNBKTC) . . . . . . . . . . . . . . . . . . . . . . . . . . 163
|| Key Token Change2 (CSNBKTC2). . . . . . . . . . . . . . . . . . . . . . . . . . 166
Key Token Parse (CSNBKTP) . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Key Translate (CSNBKTR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
|| Key Translate2 (CSNBKTR2). . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Multiple Clear Key Import (CSNBCKM) . . . . . . . . . . . . . . . . . . . . . . . . 179
PKADecrypt (CSNDPKD). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
PKAEncrypt (CSNDPKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Prohibit Export (CSNBPEX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Prohibit Export Extended (CSNBPEXX). . . . . . . . . . . . . . . . . . . . . . . . 189
Random Number Generate (CSNBRNG) . . . . . . . . . . . . . . . . . . . . . . . 191
Random Number Generate Long (CSNBRNGL). . . . . . . . . . . . . . . . . . . . . 193
|| Restrict KeyAttribute (CSNBRKA). . . . . . . . . . . . . . . . . . . . . . . . . . 195
Symmetric Key Export (CSNDSYX) . . . . . . . . . . . . . . . . . . . . . . . . . 198
Symmetric Key Generate (CSNDSYG) . . . . . . . . . . . . . . . . . . . . . . . . 201
Symmetric Key Import (CSNDSYI). . . . . . . . . . . . . . . . . . . . . . . . . . 205
|| Symmetric Key Import2 (CSNDSYI2). . . . . . . . . . . . . . . . . . . . . . . . . 208
Chapter6. Protecting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
|| Modes of operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
|| Cipher Block Chaining (CBC) mode . . . . . . . . . . . . . . . . . . . . . . . . 211
|| Electronic Code Book (ECB) mode . . . . . . . . . . . . . . . . . . . . . . . . 211
|| Processing rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
|| Triple-DES encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Decipher (CSNBDEC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Encipher (CSNBENC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
SymmetricAlgorithm Decipher (CSNBSAD) . . . . . . . . . . . . . . . . . . . . . . 221
SymmetricAlgorithm Encipher (CSNBSAE) . . . . . . . . . . . . . . . . . . . . . . 226
Chapter7. Verifying data integrity and authenticating messages . . . . . . . . . . . . . 233
How MACs are used. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
How hashing functions and MDCs are used . . . . . . . . . . . . . . . . . . . . . . 234
|| HMAC Generate (CSNBHMG) . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
|| HMAC Verify (CSNBHMV). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
MAC Generate (CSNBMGN). . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
MAC Verify (CSNBMVR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
MDC Generate (CSNBMDG). . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
One-Way Hash (CSNBOWH). . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Chapter8. Key storage mechanisms . . . . . . . . . . . . . . . . . . . . . . . . 261
Key labels and key-storage management . . . . . . . . . . . . . . . . . . . . . . . 261
Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z . . . . . . . . . 263
AES Key Record Create (CSNBAKRC) . . . . . . . . . . . . . . . . . . . . . . . . 267
AES Key Record Delete (CSNBAKRD) . . . . . . . . . . . . . . . . . . . . . . . . 269
AES Key Record List (CSNBAKRL) . . . . . . . . . . . . . . . . . . . . . . . . . 271
AES Key Record Read (CSNBAKRR) . . . . . . . . . . . . . . . . . . . . . . . . 274
AES Key Record Write (CSNBAKRW) . . . . . . . . . . . . . . . . . . . . . . . . 276
DES Key Record Create (CSNBKRC) . . . . . . . . . . . . . . . . . . . . . . . . 278
DES Key Record Delete (CSNBKRD) . . . . . . . . . . . . . . . . . . . . . . . . 280
DES Key Record List (CSNBKRL). . . . . . . . . . . . . . . . . . . . . . . . . . 282
DES Key Record Read (CSNBKRR) . . . . . . . . . . . . . . . . . . . . . . . . . 284
DES Key Record Write (CSNBKRW). . . . . . . . . . . . . . . . . . . . . . . . . 286
PKAKey Record Create (CSNDKRC) . . . . . . . . . . . . . . . . . . . . . . . . 288
PKAKey Record Delete (CSNDKRD) . . . . . . . . . . . . . . . . . . . . . . . . 290
Contents v

PKAKey Record List (CSNDKRL). . . . . . . . . . . . . . . . . . . . . . . . . . 292
PKAKey Record Read (CSNDKRR) . . . . . . . . . . . . . . . . . . . . . . . . . 295
PKAKey Record Write (CSNDKRW) . . . . . . . . . . . . . . . . . . . . . . . . . 297
Retained Key Delete (CSNDRKD). . . . . . . . . . . . . . . . . . . . . . . . . . 299
Retained Key List (CSNDRKL) . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Chapter9. Financial services . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
How personal identification numbers (PINs) are used. . . . . . . . . . . . . . . . . . . 303
How VISAcard verification values are used . . . . . . . . . . . . . . . . . . . . . . 303
Translating data and PINs in networks . . . . . . . . . . . . . . . . . . . . . . . . 304
|| Working with Europay-Mastercard-Visa Smart cards . . . . . . . . . . . . . . . . . . . 304
PIN verbs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
|| ANSI X9.8 PIN restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
The PIN profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Clear PIN Encrypt (CSNBCPE) . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Clear PIN Generate (CSNBPGN) . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Clear PIN GenerateAlternate (CSNBCPA). . . . . . . . . . . . . . . . . . . . . . . 318
CVV Generate (CSNBCSG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
CVV Verify (CSNBCSV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Encrypted PIN Generate (CSNBEPG) . . . . . . . . . . . . . . . . . . . . . . . . 328
Encrypted PIN Translate (CSNBPTR) . . . . . . . . . . . . . . . . . . . . . . . . 332
Encrypted PIN Verify (CSNBPVR) . . . . . . . . . . . . . . . . . . . . . . . . . . 338
PIN Change/Unblock (CSNBPCU). . . . . . . . . . . . . . . . . . . . . . . . . . 342
Secure Messaging for Keys (CSNBSKY) . . . . . . . . . . . . . . . . . . . . . . . 348
Secure Messaging for PINs (CSNBSPN) . . . . . . . . . . . . . . . . . . . . . . . 351
Transaction Validation (CSNBTRV) . . . . . . . . . . . . . . . . . . . . . . . . . 355
Chapter10. Using digital signatures . . . . . . . . . . . . . . . . . . . . . . . . 359
Digital Signature Generate (CSNDDSG). . . . . . . . . . . . . . . . . . . . . . . . 360
Digital Signature Verify (CSNDDSV) . . . . . . . . . . . . . . . . . . . . . . . . . 364
Chapter11. Managing PKAcryptographic keys . . . . . . . . . . . . . . . . . . . . 369
PKAKey Generate (CSNDPKG) . . . . . . . . . . . . . . . . . . . . . . . . . . 370
PKAKey Import (CSNDPKI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
PKAKey Token Build (CSNDPKB). . . . . . . . . . . . . . . . . . . . . . . . . . 377
PKAKey Token Change (CSNDKTC). . . . . . . . . . . . . . . . . . . . . . . . . 385
PKAKey Translate (CSNDPKT). . . . . . . . . . . . . . . . . . . . . . . . . . . 388
PKAPublic Key Extract (CSNDPKX) . . . . . . . . . . . . . . . . . . . . . . . . . 392
Remote Key Export (CSNDRKX) . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Trusted Block Create (CSNDTBC). . . . . . . . . . . . . . . . . . . . . . . . . . 403
AppendixA. Return codes and reason codes . . . . . . . . . . . . . . . . . . . . 407
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Reason codes that accompany return code 0. . . . . . . . . . . . . . . . . . . . . 408
Reason codes that accompany return code 4. . . . . . . . . . . . . . . . . . . . . 408
Reason codes that accompany return code 8. . . . . . . . . . . . . . . . . . . . . 409
Reason codes that accompany return code 12 . . . . . . . . . . . . . . . . . . . . 418
Reason codes that accompany return code 16 . . . . . . . . . . . . . . . . . . . . 419
AppendixB. Key token formats . . . . . . . . . . . . . . . . . . . . . . . . . . 421
|| AES internal key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Token Validation Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
|| DES internal key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
DES external key token. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
DES null key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
vi LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

RSApublic key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
RSAprivate external key token . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
|| RSAprivate internal key token . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
|| ECC key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
|| Associated data format for ECC private key token . . . . . . . . . . . . . . . . . . . 438
|| AESKW wrapped payload format for ECC private key token . . . . . . . . . . . . . . . 439
PKAnull key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
|| HMAC key token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
|| HMAC variable-length symmetric key token . . . . . . . . . . . . . . . . . . . . . 439
|| HMAC symmetric null key token . . . . . . . . . . . . . . . . . . . . . . . . . 443
Trusted blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Trusted block organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
AppendixC. Key forms and types used in the Key Generate verb . . . . . . . . . . . . 459
Generating an operational key . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Generating an importable key . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Generating an exportable key . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Examples of single-length keys in one form only . . . . . . . . . . . . . . . . . . . . 459
Examples of OPIM single-length, double-length, and triple-length keys in two forms . . . . . . . 460
Examples of OPEX single-length, double-length, and triple-length keys in two forms . . . . . . . 460
Examples of IMEX single-length and double-length keys in two forms. . . . . . . . . . . . . 461
Examples of EXEX single-length and double-length keys in two forms . . . . . . . . . . . . 461
AppendixD. Control vectors and changing control vectors with the Control Vector Translate
verb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Control vector table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Control-vector-base bit maps. . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Key Form Bits, 'fff'. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Specifying a control-vector-base value . . . . . . . . . . . . . . . . . . . . . . . 468
Changing control vectors with the Control Vector Translate verb. . . . . . . . . . . . . . . 472
Providing the control information for testing the control vectors . . . . . . . . . . . . . . 472
Mask array preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Selecting the key-half processing mode. . . . . . . . . . . . . . . . . . . . . . . 474
When the target key-token CV is null. . . . . . . . . . . . . . . . . . . . . . . . 476
Control vector translate example . . . . . . . . . . . . . . . . . . . . . . . . . 476
AppendixE. PIN formats and algorithms . . . . . . . . . . . . . . . . . . . . . . 477
PIN notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
PIN block formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
PIN extraction rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
IBM PIN algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
VISAPIN algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
AppendixF. Cryptographic algorithms and processes . . . . . . . . . . . . . . . . . 491
Cryptographic key-verification techniques . . . . . . . . . . . . . . . . . . . . . . . 491
Modification Detection Code calculation. . . . . . . . . . . . . . . . . . . . . . . . 493
Ciphering methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
MAC calculation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
RSAkey-pair generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Multiple decipherment and encipherment . . . . . . . . . . . . . . . . . . . . . . . 504
PKA92 key format and encryption process. . . . . . . . . . . . . . . . . . . . . . . 511
Formatting hashes and keys in public-key cryptography . . . . . . . . . . . . . . . . . . 513
AppendixG.Access control points and verbs . . . . . . . . . . . . . . . . . . . . 515
TKE Version 6.0 and higher . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Contents vii

AppendixH. Sample verb call routines . . . . . . . . . . . . . . . . . . . . . . . 527
Sample program in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Sample program in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
AppendixI. Initial system set up tips . . . . . . . . . . . . . . . . . . . . . . . . 537
Installing and loading the cryptographic device driver. . . . . . . . . . . . . . . . . . . 537
zcrypt device driver usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
High resolution polling timer . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
The sysfs interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Running secure key under a z/VM guest . . . . . . . . . . . . . . . . . . . . . . . 539
AppendixJ. CCAinstallation instructions . . . . . . . . . . . . . . . . . . . . . . 541
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Download and install the RPM . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Files in the RPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Samples in the RPM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Groups in the RPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Install and configure the RPM . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Uninstall the RPM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
|| AppendixK. Coexistence of CEX3C and CEX2C features . . . . . . . . . . . . . . . . 549
|| Legacy support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
|| Concurrent installations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
|| Dual Support: Key storage interactions . . . . . . . . . . . . . . . . . . . . . . . 551
|| Dual Support: TKE catcher can run in only one instance. . . . . . . . . . . . . . . . . 552
AppendixL. Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
The panel.exe utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
panel.exe syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
panel.exe functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Using panel.exe for key storage initialization . . . . . . . . . . . . . . . . . . . . . 555
Using panel.exe for key storage reencipher when changing the master key. . . . . . . . . . 556
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Documentation accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
IBM and accessibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Programming interface information. . . . . . . . . . . . . . . . . . . . . . . . . . 562
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
viii LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Figures
|| 1. CCAsecurityAPI, access layer, and cryptographic engine . . . . . . . . . . . . . . . . 4
|| 2. CPACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3. Control Vector Generate and Key Token Build CV keyword combinations . . . . . . . . . . 30
4. PKAkey management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5. Control vector base bit map (common bits and key-encrypting keys) . . . . . . . . . . . 465
6. Control vector base bit map (data operation keys) . . . . . . . . . . . . . . . . . . 466
7. Control vector base bit map (PIN processing keys and cryptographic variable-encrypting keys) 467
8. Control vector base bit map (key generating keys) . . . . . . . . . . . . . . . . . . 468
9. Control Vector Translate verb mask_array processing. . . . . . . . . . . . . . . . . 474
10. Control Vector Translate verb. . . . . . . . . . . . . . . . . . . . . . . . . . 475
11. ISO-3 PIN-block format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
12. 3624 PIN generation algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 481
13. GBP PIN generation algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 482
14. PIN-Offset generation algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 483
15. PIN verification algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
16. GBP PIN verification algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 487
17. PVV generation algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
18. Triple-DES data encryption and decryption. . . . . . . . . . . . . . . . . . . . . 495
19. Enciphering using theANSI X3.106 CBC method . . . . . . . . . . . . . . . . . . 496
20. Deciphering using the CBC method . . . . . . . . . . . . . . . . . . . . . . . 497
21. Enciphering using theANSI X9.23 method . . . . . . . . . . . . . . . . . . . . . 498
22. Deciphering using theANSI X9.23 method. . . . . . . . . . . . . . . . . . . . . 498
23. Triple-DES CBC encryption process . . . . . . . . . . . . . . . . . . . . . . . 499
24. Triple-DES CBC decryption process . . . . . . . . . . . . . . . . . . . . . . . 500
25. EDE algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
26. DED process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
27. MAC calculation method . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
28. Multiple encipherment of single-length keys . . . . . . . . . . . . . . . . . . . . 506
29. Multiple decipherment of single-length keys . . . . . . . . . . . . . . . . . . . . 507
30. Multiple encipherment of double-length keys . . . . . . . . . . . . . . . . . . . . 508
31. Multiple decipherment of double-length keys . . . . . . . . . . . . . . . . . . . . 509
32. Multiple encipherment of triple-length keys . . . . . . . . . . . . . . . . . . . . . 510
33. Multiple decipherment of triple-length keys . . . . . . . . . . . . . . . . . . . . . 511
34. Syntax, sample routine in C . . . . . . . . . . . . . . . . . . . . . . . . . . 528
35. Syntax, sample routine in Java . . . . . . . . . . . . . . . . . . . . . . . . . 533
©CopyrightIBMCorp.2007,2011 ix

x LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Tables
1.Key types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.Key subtypes specified by the rule_array keyword . . . . . . . . . . . . . . . . . . 29
|| 3.Access Control Points Used byATM remote key loading . . . . . . . . . . . . . . . . 34
4.Combinations of the verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.Summary of CCAnodes and resource control verbs. . . . . . . . . . . . . . . . . . 40
6.Summary of CCAAES, DES, and HMAC verbs . . . . . . . . . . . . . . . . . . . 40
7.Summary of PKAkey token sections . . . . . . . . . . . . . . . . . . . . . . . 48
8.Summary of PKAverbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
9.Keywords for Cryptographic Facility Query control information . . . . . . . . . . . . . . 59
10.Cryptographic Facility Query information returned in the rule_array . . . . . . . . . . . . 61
11. Output data format for STATKPR operational key parts. . . . . . . . . . . . . . . . . 73
12.Output data format for STATICSAoperational key parts . . . . . . . . . . . . . . . . 74
13.Output data format for STATICSE operational key parts . . . . . . . . . . . . . . . . 76
|| 14.Output data format for STATICSB operational key parts . . . . . . . . . . . . . . . . 78
15.Output data format for STATICSX operational key parts . . . . . . . . . . . . . . . . 81
16.Keywords for Cryptographic ResourceAllocate control information . . . . . . . . . . . . 86
17.Keywords for Cryptographic Resource Deallocate control information . . . . . . . . . . . 88
18.Keywords for Key Storage Initialization control information . . . . . . . . . . . . . . . 90
19.Keywords for Master Key Process control information . . . . . . . . . . . . . . . . . 94
20.Keywords for Random Number Tests control information . . . . . . . . . . . . . . . . 97
21.Keywords for Control Vector Translate control information . . . . . . . . . . . . . . . 105
22.Keywords for Diversified Key Generate control information . . . . . . . . . . . . . . . 114
23.Keywords for the Key Generate verb key_form parameter . . . . . . . . . . . . . . . 121
|| 24.Key length values for the Key Generate verb . . . . . . . . . . . . . . . . . . . . 122
25.Key Generate - key lengths for each key type. . . . . . . . . . . . . . . . . . . . 122
26.Keywords for Key Generate, valid key types and key forms for a single key. . . . . . . . . 126
27.Keywords for Key Generate, valid key types and key forms for a key pair . . . . . . . . . 126
|| 28.Keywords for Key Generate2 control information. . . . . . . . . . . . . . . . . . . 128
|| 29.Key Generate2 valid key type and key forms for HMAC keys . . . . . . . . . . . . . . 132
|| 30.Required access control points for Key Generate2 . . . . . . . . . . . . . . . . . . 132
31.Keywords for Key Part Import control information . . . . . . . . . . . . . . . . . . 137
|| 32.Keywords for Key Part Import2 control information . . . . . . . . . . . . . . . . . . 140
33.Verification pattern input and output . . . . . . . . . . . . . . . . . . . . . . . 143
34.Keywords for Key Test control information . . . . . . . . . . . . . . . . . . . . . 144
|| 35.Keywords for Key Test2 control information. . . . . . . . . . . . . . . . . . . . . 147
36.Keywords for Key Test Extended control information . . . . . . . . . . . . . . . . . 151
37.Keywords for Key Token Build control information . . . . . . . . . . . . . . . . . . 156
|| 38.Keywords for Key Token Build2 control information. . . . . . . . . . . . . . . . . . 160
39.Keywords for Key Token Change control information . . . . . . . . . . . . . . . . . 163
|| 40.Keywords for Key Token Change2 control information. . . . . . . . . . . . . . . . . 166
41.Keywords for Key Token Parse control information . . . . . . . . . . . . . . . . . . 170
|| 42.Keywords for Key Translate2 control information. . . . . . . . . . . . . . . . . . . 175
43.Keywords for Multiple Clear Key Import control information. . . . . . . . . . . . . . . 179
44.Keywords for PKADecrypt control information . . . . . . . . . . . . . . . . . . . 182
45.Keywords for PKAEncrypt control information. . . . . . . . . . . . . . . . . . . . 185
46.Keywords for Random Number Generate form parameter . . . . . . . . . . . . . . . 191
47.Keywords for Random Number Generate Long control information . . . . . . . . . . . . 193
|| 48.Keywords for Restrict KeyAttribute control information . . . . . . . . . . . . . . . . 195
49.Keywords for Symmetric Key Export control information . . . . . . . . . . . . . . . . 198
50.Keywords for Symmetric Key Generate control information . . . . . . . . . . . . . . . 201
51.Keywords for Symmetric Key Import control information . . . . . . . . . . . . . . . . 205
|| 52.Keywords for Symmetric Key Import2 control information . . . . . . . . . . . . . . . 208
|| 53.PKCS#1 OAEP encoded message layout (PKOAEP2) . . . . . . . . . . . . . . . . 209
©CopyrightIBMCorp.2007,2011 xi

54.Keywords for Decipher control information . . . . . . . . . . . . . . . . . . . . . 215
55.Keywords for Encipher control information . . . . . . . . . . . . . . . . . . . . . 219
56.Keywords for SymmetricAlgorithm Decipher control information . . . . . . . . . . . . . 222
57.Keywords for SymmetricAlgorithm Encipher control information . . . . . . . . . . . . . 227
|| 58.Keywords for HMAC Generate control information . . . . . . . . . . . . . . . . . . 235
|| 59.Keywords for HMAC Verify control information . . . . . . . . . . . . . . . . . . . 238
60.Keywords for MAC Generate control information. . . . . . . . . . . . . . . . . . . 242
61.Keywords for MAC Verify control information . . . . . . . . . . . . . . . . . . . . 246
62.Keywords for MDC Generate control information. . . . . . . . . . . . . . . . . . . 250
63.Keywords for One-Way Hash control information. . . . . . . . . . . . . . . . . . . 258
64.Valid symbols for the name token . . . . . . . . . . . . . . . . . . . . . . . . 262
65.Key labels that are not valid . . . . . . . . . . . . . . . . . . . . . . . . . . 263
66.Keywords forAES Key Record Delete control information . . . . . . . . . . . . . . . 269
67.Keywords forAES Key Record Write control information. . . . . . . . . . . . . . . . 276
68.Keywords for DES Key Record Delete control information . . . . . . . . . . . . . . . 280
69.Keywords for PKAKey Record Delete control information . . . . . . . . . . . . . . . 290
70.Keywords for PKAKey Record Write control information. . . . . . . . . . . . . . . . 297
|| 71.ANSI X9.8 PIN -Allow onlyANSI PIN blocks . . . . . . . . . . . . . . . . . . . . 307
72.Format of a PIN profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
73.Format values of PIN blocks . . . . . . . . . . . . . . . . . . . . . . . . . . 308
74.PIN block format and PIN extraction method keywords . . . . . . . . . . . . . . . . 308
|| 75.Verbs affected by enhanced PIN security mode . . . . . . . . . . . . . . . . . . . 309
76.Format of a pad digit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
77.Pad digits for PIN block formats. . . . . . . . . . . . . . . . . . . . . . . . . 310
78.Format of the Current Key Serial Number Field . . . . . . . . . . . . . . . . . . . 311
79.Keywords for Clear PIN Encrypt control information . . . . . . . . . . . . . . . . . 313
80.Keywords for Clear PIN Generate control information . . . . . . . . . . . . . . . . . 315
81.Array elements for the Clear PIN Generate verb. . . . . . . . . . . . . . . . . . . 316
82.Array elements for Clear PIN Generate . . . . . . . . . . . . . . . . . . . . . . 316
|| 83.Keywords for Clear PIN GenerateAlternate control information . . . . . . . . . . . . . 319
84.Array elements for Clear PIN GenerateAlternate, data_array (IBM-PINO) . . . . . . . . . 320
85.Array elements for Clear PIN GenerateAlternate, data_array (VISA-PVV) . . . . . . . . . 320
86.Keywords for CVV Generate control information . . . . . . . . . . . . . . . . . . . 322
87.Keywords for CVV Verify control information . . . . . . . . . . . . . . . . . . . . 325
88.Keywords for Encrypted PIN Generate control information . . . . . . . . . . . . . . . 329
89.Array elements for Encrypted PIN Generate data_array parameter . . . . . . . . . . . . 329
90.Keywords for Encrypted PIN Generate control information . . . . . . . . . . . . . . . 330
91.Keywords for Encrypted PIN Translate control information . . . . . . . . . . . . . . . 333
92.Additional names for PIN formats . . . . . . . . . . . . . . . . . . . . . . . . 336
93.Keywords for Encrypted PIN Verify control information . . . . . . . . . . . . . . . . 339
94.Array elements for Encrypted PIN Verify data_array parameter . . . . . . . . . . . . . 340
95.Array elements required by the process rule . . . . . . . . . . . . . . . . . . . . 340
96.Keywords for PIN Change/Unblock control information . . . . . . . . . . . . . . . . 343
97.Keywords for Secure Messaging for Keys control information . . . . . . . . . . . . . . 348
98.Keywords for Secure Messaging for PINs control information . . . . . . . . . . . . . . 351
99.Keywords for Transaction Validation control information . . . . . . . . . . . . . . . . 355
100.Values for Transaction Validation validation_values parameter. . . . . . . . . . . . . . 356
101.Keywords for Digital Signature Generate control information . . . . . . . . . . . . . . 361
102.Keywords for Digital Signature Verify control information. . . . . . . . . . . . . . . . 365
103.Keywords for PKAKey Generate control information . . . . . . . . . . . . . . . . . 371
|| 104.Keywords for PKAKey Import control information . . . . . . . . . . . . . . . . . . 374
105.Keywords for PKAKey Token Build control information . . . . . . . . . . . . . . . . 378
|| 106.PKAKey Token Build - Key value structure length maximum values . . . . . . . . . . . 379
107.PKAKey Token Build - Key value structure elements . . . . . . . . . . . . . . . . . 379
108.Keywords for PKAKey Token Change control information . . . . . . . . . . . . . . . 385
109.Keywords for PKAKey Translate control information . . . . . . . . . . . . . . . . . 388
xii LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

110. Keywords for Remote Key Export certificate_parms parameter . . . . . . . . . . . . . 397
111. Keywords for Trusted Block Create control information . . . . . . . . . . . . . . . . 404
112. Return code values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
113. Reason codes for return code 0. . . . . . . . . . . . . . . . . . . . . . . . . 408
114. Reason codes for return code 4. . . . . . . . . . . . . . . . . . . . . . . . . 408
115. Reason codes for return code 8. . . . . . . . . . . . . . . . . . . . . . . . . 409
116. Reason codes for return code 12 . . . . . . . . . . . . . . . . . . . . . . . . 418
117. Reason codes for return code 16 . . . . . . . . . . . . . . . . . . . . . . . . 419
118. AES Internal key token format, version X'04' . . . . . . . . . . . . . . . . . . . . 421
119. AES internal key-token flag byte. . . . . . . . . . . . . . . . . . . . . . . . . 422
120.Internal clear key token format . . . . . . . . . . . . . . . . . . . . . . . . . 423
121.DES internal key token format . . . . . . . . . . . . . . . . . . . . . . . . . 423
122.DES external key token format . . . . . . . . . . . . . . . . . . . . . . . . . 424
123.DES null key token format . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
124.RSAPublic Key Token format. . . . . . . . . . . . . . . . . . . . . . . . . . 426
125.RSAprivate external key token basic record format. . . . . . . . . . . . . . . . . . 427
126.RSAprivate key token, 1024-bit Modulus-Exponent external format. . . . . . . . . . . . 428
127.RSAprivate key token, 2048-bit Chinese Remainder Theorem external format. . . . . . . . 428
128.RSAprivate internal key token basic record format. . . . . . . . . . . . . . . . . . 430
129.RSAprivate internal key token, 1024-bit Modulus-Exponent format for cryptographic coprocessor
feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
130.RSAprivate internal key token, 1024-bit Modulus-Exponent format for CEX3C. . . . . . . . 432
131.RSAprivate internal key token, 2048-bit Chinese Remainder Theorem internal format . . . . . 433
132.RSAvariable Modulus-Exponent token format. . . . . . . . . . . . . . . . . . . . 435
|| 133.ECC key token format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
|| 134.Associated data format for ECC private key token . . . . . . . . . . . . . . . . . . 438
|| 135.AESKW wrapped payload format for ECC private key token . . . . . . . . . . . . . . 439
136.PKAnull key token format . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
|| 137.HMAC variable-length symmetric key-token, version X'05' (CCA4.1.0 or later). . . . . . . . 439
|| 138.HMAC symmetric null key token format . . . . . . . . . . . . . . . . . . . . . . 443
139.Trusted block sections and their use . . . . . . . . . . . . . . . . . . . . . . . 444
140.Trusted block header format . . . . . . . . . . . . . . . . . . . . . . . . . . 446
141.Trusted block trusted RSApublic key section (X'11') . . . . . . . . . . . . . . . . . 447
142.Trusted block rule section (X'12') . . . . . . . . . . . . . . . . . . . . . . . . 448
143.Summary of trusted block X'12' subsections . . . . . . . . . . . . . . . . . . . . 449
144.Transport key variant subsection (X'0001') of trusted block rule section (X'12'). . . . . . . . 450
145.Transport key rule reference subsection (X'0002') of trusted block rule section (X'12') . . . . . 451
146.Common export key parameters subsection (X'0003') of trusted block rule section (X'12') 451
147.Source key rule reference subsection (X'0004') of trusted block rule section (X'12') . . . . . . 453
148.Export key CCAtoken parameters subsection (X'0005') of trusted block rule section (X'12') 453
149.Trusted block key label (name) section (X'13') . . . . . . . . . . . . . . . . . . . 455
150.Trusted block information section (X'14'). . . . . . . . . . . . . . . . . . . . . . 455
151.Summary of trusted block information subsections . . . . . . . . . . . . . . . . . . 456
152.Protection information subsection (X'0001') of trusted block information section (X'14'). . . . . 456
153.Activation and expiration dates subsection (X'0002') of trusted block information section (X'14') 457
154.Trusted block application-defined data section (X'15') . . . . . . . . . . . . . . . . . 457
155.Default control vector values . . . . . . . . . . . . . . . . . . . . . . . . . . 463
156.Versions of the MDC calculation method. . . . . . . . . . . . . . . . . . . . . . 493
157.MDC calculation procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 494
158.PKA96 clear DES key record . . . . . . . . . . . . . . . . . . . . . . . . . . 511
|| 159.Access Control Points and corresponding CCAverbs . . . . . . . . . . . . . . . . . 515
160.Verbs called by the sample routines . . . . . . . . . . . . . . . . . . . . . . . 527
161.CCAgroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Tables xiii

xiv LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

About this document
See “Terminology” on page xvii for the correct CCAfeature terminology.
| This document describes how to use the verbs provided in the Common CryptographicArchitecture (CCA)
| Release 4.0.0 and Release 4.1.0APIs for Linux on IBM® System z®. The CCAfunctions perform
| cryptographic operations using the IBM 4765 Crypto Express3 feature (CEX3C) in coprocessor mode. The
| CCAfunctions also perform some cryptographic operations using the IBM 4764 Crypto Express2 (CEX2C)
| feature in coprocessor mode. See “Concurrent installations” on page 549 for details.
This book is for planning and programming purposes only.
The CCAhost software provides an application programming interface through which applications request
secure, high-speed cryptographic services from the hardware cryptographic features.
| Where CCARelease 4.1.0 has been changed or enhanced from CCARelease 4.0.0, these changes have
| been noted.
Revision history
Third edition, March 2011, CCA Support Program Release 4.1.0
|
| This edition describes the IBM CCABasic ServicesAPI for Release 4.1.0. For the supported environments
| and product ordering information, see:
| http://www.ibm.com/security/cryptocards
| For Linux for IBM System z, Release 4.1.0 changes to the CCAAPI include:
| v Enhanced PIN security with the addition ofANSI 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 GenerateAlternate (CSNBCPA), Encrypted PIN
| Translate (CSNBPTR), and Secure Messaging for PINs (CSNBSPN) verbs.
| v Wrap CCAkeys in Cipher-Block Chaining (CBC) mode
| Asecond 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
| CCAlegacy ECB mode of wrapping Triple-DES keys. The two methods can coexist on the same or
| multiple systems.
| v Elliptic Curve Cryptography (ECC) support
| New Elliptic Curve Cryptography (ECC) key generation, along with support for digital signature
| generation and verification using the Elliptic Curve Digital SignatureAlgorithm (ECDSA). This
| enhancement includes a new PKAkey-token for housing ECC public-key cryptographic keys and a new
| asymmetricAPKAmaster-key (32-byteAES key) for wrapping an ECC key-token, along with added
| support to the Master Key Process verb.
| v Hashed MessageAuthentication Code (HMAC) support for key generation and processing, but not for
| key storage.
| v These new verbs:
| – HMAC Generate (CSNBHMG)
| – HMAC Verify (CSNBHMV)
| – Key Generate2 (CSNBKGN2)
| – Key Part Import2 (CSNBKPI2)
©CopyrightIBMCorp.2007,2011 xv

| – Key Test2 (CSNBKYT2)
| – Key Token Build2 (CSNBKTB2)
| – Key Token Change2 (CSNBKTC2)
| – Key Translate2 (CSNBKTR2)
| – Restrict KeyAttribute (CSNBRKA)
| – Symmetric Key Import2 (CSNDSYI2)
Second edition, April 2010, CCA Support Program Release 4.0.0
This edition describes the IBM CCABasic ServicesAPI for Release 4.0.0. For the supported environments
and product ordering information, see:
http://www.ibm.com/security/cryptocards
For Linux for IBM System z, release 4.0.0 changes to the CCAAPI include:
v Support for the IBM Crypto Express3 feature (CEX3C) in coprocessor mode
v AJava Native Interface (JNI) form for most of the verbs
v Central ProcessorAssist for Cryptographic Functions (CPACF) support
v These new verbs:
– 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)
– Control Vector Translate (CSNBCVT)
– Cryptographic Facility Version (CSUACFV)
– Cryptographic Variable Encipher (CSNBCVE)
– Key Test Extended (CSNBKYTX)
– MDC Generate (CSNBMDG)
– PKAKey Translate (CSNDPKT)
– Prohibit Export Extended (CSNBPEXX)
– Random Number Generate Long (CSNBRNGL)
– Remote Key Export (CSNDRKX)
– Retained Key Delete (CSNDRKD)
– Retained Key List (CSNDRKL)
– SymmetricAlgorithm Decipher (CSNBSAD)
– SymmetricAlgorithm Encipher (CSNBSAE)
– Trusted Block Create (CSNDTBC)
Who should use this document
This document is intended for application programmers who are responsible for writing application
programs that use the security application programming interface (API) to access cryptographic functions.
xvi LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Distribution-specific information
| In order to use the full set of CCARelease 4.1.0 functions, a distribution of Linux that has support for the
| CEX3C feature is required. This feature is available with IBM System z10® model GA3 and higher models.
| These Linux distributions support CCARelease 4.1.0, including CEX3C and CEX2C feature support:
| v Novell SUSE Linux Enterprise Server 11 SP1 (SLES 11 SP1) from Novell
| v Novell SUSE Linux Enterprise Server 10 SP3 (SLES 10 SP3) from Novell
| v Red Hat Enterprise Linux 5 Update 6
| v Red Hat Enterprise Linux 6
| Full CEX2C support is included with this CCARelease 4.1.0, however note that because of limits in the
| CEX2C hardware and firmware available, this is a limited subset of the CEX3C functions described in this
| document. In order to make use of this set of functions, a distribution of Linux that has support for the
| CEX2C feature is required.
| Note that 64-bit versions of this software are needed. 31-bit support is not provided.
Terminology
These terms are used for the CCAfeatures. For the remainder of this document, the short form (terms in
bold) will be used.
Term Description
CEX2C An IBM 4764 Crypto Express2 feature, configured in coprocessor mode.
| CEX3C An IBM 4765 Crypto Express3 feature, configured in coprocessor mode.
CEX*C Either the CEX2C, CEX3C, or (if plural) any combination of these.
Hardware requirements
In order to make use of the verbs provided in the Common CryptographicArchitecture (CCA)API for Linux
on IBM System z, your hardware must meet these minimum requirements:
v IBM System z10 model GA3
| v One CEX3C feature, with one CEX3C adapter mapped to the z/VM® image or LPAR that uses it. The
| CEX3C must have CCA4.1.0z or greater firmware loaded (in order to have available all of the CCA
| 4.1.0z function). Older levels of firmware are supported with reduced function available.
| v If you plan to use a Trusted Key Entry (TKE) workstation, you must have a TKE V6.0 or higher
| workstation in order to see supported CEX3Cs. They are not seen when using TKE V5 or earlier
| workstations.
This is the maximum supported hardware configuration:
| v IBM zEnterprise 196
v Two CEX3Cs, with four CEX3C adapters mapped to a single z/VM image or single LPAR.
| This hardware configuration is also supported:
| v IBM System z10 model GA3
| v One or more CEX3Cs, with CCA4.1.0z or CCA4.0.3z firmware loaded.
| v One or more CEX2Cs, with a supported level of CCA3.x firmware loaded. See “Legacy support” on
| page 549 for details.
See “Concurrent installations” on page 549 for details about a mixed environment of CEX2C and CEX3C.
Aboutthisdocument xvii

To determine if a card is a CEX2C or CEX3C, use one of these methods, available with two utilities
included in the CEX3C support program RPM, or your own custom implementation.
v Invoke the Cryptographic Facility Query verb (see “Determining if a card is a CEX2C or CEX3C” on
page 58)
v Use the sysfs interface, the hwtype attribute (see “The sysfs interface” on page 538)
| v Run panel.exe -x using the panel.exe utility installed with the RPM, to get a quick summary of cards
| available and their status. See “The panel.exe utility” on page 553.
| v Run ivp.e, another utility installed with the RPM, which gives more detailed information about each card
| available. SeeAppendixL, “Utilities,” on page 553.
| In order to use the CEX3C feature under z/VM versions 6.1, and 5.4, you need to apply theseAPAR fixes:
APAR number Description
VM64656 Introduces CEX3C support.
|| VM64727 Fixes problem with shared coprocessors.
VM64793 Introduces protected key CPACF support.
How to use this document
For encryption, CCAsupportsAdvanced Encryption Standard (AES), Data Encryption Standard (DES),
public key cryptography (PKAor RSA), and Elliptic Curve Cryptography (ECC). These are very different
cryptographic systems.Additionally, CCAprovidesAPIs for generating and verifying Message
Authentication Codes (MACs), Hashed MessageAuthentication Codes (HMACs), hashes, and PINS, as
well as other cryptographic functions.
Part1, “IBM CCAprogramming,” on page 1 focuses on IBM CCAprogramming. It includes the following
chapters:
v Chapter1, “Introduction to programming for the IBM Common CryptographicArchitecture,” on page 3
describes the programming considerations for using the CCAverbs. It also explains the syntax and
parameter definitions used in verbs. Concurrency is also discussed.
v Chapter2, “UsingAES, DES, and HMAC cryptography and verbs,” on page 19 gives an overview of
AES, DES, and HMAC cryptography, and provides general guidance information on how these verbs
use different key types and key forms.
v Chapter3, “Introducing PKAcryptography and using PKAverbs,” on page 47 introduces Public Key
Algorithm (PKA) support and describes programming considerations for using the CCAPKAand ECC
verbs, such as the PKAkey token structure and key management.
Part2, “CCAverbs,” on page 55 focuses on CCAverbs and includes the following chapters:
| v Chapter4, “Using the CCAnodes and resource control verbs,” on page 57 describes using the CCA
| resource control verbs.
v Chapter8, “Key storage mechanisms,” on page 261 describes the use of key storage, key tokens, and
associated verbs.
v Chapter5, “ManagingAES and DES cryptographic keys,” on page 99 describes the verbs for generating
and maintaining DES andAES cryptographic keys, the Random Number Generate verb (which
generates 8-byte random numbers), the Random Number Generate Long verb (which generates up to
8192 bytes of random content), and the Secure Sockets Layer (SSL) security protocol. This chapter
also describes utilities to build DES andAES tokens, generate and translate control vectors, and
describes the PKAverbs that support DES andAES key distribution.
v Chapter6, “Protecting data,” on page 211 describes the verbs for enciphering and deciphering data.
xviii LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

v Chapter7, “Verifying data integrity and authenticating messages,” on page 233 describes the verbs for
generating and verifying MessageAuthentication Codes (MACs), generating and verifying Hashed
MessageAuthentication Codes (HMACs), generating Modification Detection Codes (MDCs), and
generating hashes (SHA-1, MD5, RIPEMD-160).
v Chapter9, “Financial services,” on page 303 describes the verbs for use in support of finance-industry
applications. This includes several categories.
– Verbs for generating, verifying, and translating personal identification numbers (PINS).
– Verbs that generate and verify VISAcard verification values andAmerican Express card security
codes.
– Verbs to support smart card applications using the EMV (Europay MasterCard Visa) standards.
v Chapter10, “Using digital signatures,” on page 359 describes the verbs that support using digital
signatures to authenticate messages.
v Chapter11, “Managing PKAcryptographic keys,” on page 369 describes the verbs that generate and
manage PKAkeys.
The appendixes include the following information:
v AppendixA, “Return codes and reason codes,” on page 407 explains the return and reason codes
returned by the verbs.
| v AppendixB, “Key token formats,” on page 421 describes the formats forAES, DES internal, external,
| and null key tokens, for PKApublic, private external, and private internal key tokens containing
| Rivest-Shamir-Adleman (RSA) information, PKAnull key tokens, ECC key tokens, HMAC key tokens,
| Transaction Validation Values (TVVs), and trusted blocks.
| v AppendixC, “Key forms and types used in the Key Generate verb,” on page 459 describes the key
| forms and types used by the Key Generate verb.
v AppendixD, “Control vectors and changing control vectors with the Control Vector Translate verb,” on
page 463 contains a table of the default control vector values that are associated with each key type
and describes the control information for testing control vectors, mask array preparation, selecting the
key-half processing mode, and an example of using the Control Vector Translate verb.
| v AppendixE, “PIN formats and algorithms,” on page 477 describes the PIN notation, formats, extraction
| rules, and algorithms.
v AppendixF, “Cryptographic algorithms and processes,” on page 491 describes various ciphering and
key verification algorithms, as well as the formatting of hashes and keys.
| v AppendixG, “Access control points and verbs,” on page 515 lists the access control points and their
| corresponding verbs.
v AppendixH, “Sample verb call routines,” on page 527 contains sample verb call routines, both in C and
Java, that illustrates the practical application of CCAverb calls.
v AppendixI, “Initial system set up tips,” on page 537 includes tips to help you set up your system for the
first time.
v AppendixJ, “CCAinstallation instructions,” on page 541 includes RPM installation, configuration, and
uninstallation instructions.
v AppendixK, “Coexistence of CEX3C and CEX2C features,” on page 549 includes information about
using CEX2C and CEX3C features in the same system, and other restrictions.
v AppendixL, “Utilities,” on page 553 describes the ivp.e and panel.exe utilities.
v “Notices” on page 561 contains notices, programming interface information, and trademarks.
Where to find more information
Other documents referenced in this document are:
v IBM Common CryptographicArchitecture: CryptographicApplication Programming Interface Reference,
SC40-1675
Aboutthisdocument xix

Related publications
v Device Drivers, Features, and Commands, SC33-8411
See one of these Web Sites for the version of this book that is correct for your distribution of Linux:
– http://www.ibm.com/developerworks/linux/linux390/documentation_novell_suse.html
– http://www.ibm.com/developerworks/linux/linux390/documentation_red_hat.html
v z/OS Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation User’s Guide, SA23-2211-05
Do you have problems, comments, or suggestions?
Your suggestions and ideas can contribute to the quality and the usability of this document. If you have
problems using this document, or if you have suggestions for improving it, complete and mail the Reader's
Comment Form found at the back of the document.
xx LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Part 1. IBM CCA programming
This part of the document introduces programming for the IBM CCA,AES, DES, and PKAcryptography.
The chapters in this part explain how to use CCAnodes andAES, DES and PKAverbs.
| v Chapter1, “Introduction to programming for the IBM Common CryptographicArchitecture” describes the
| programming considerations for using the CCAverbs. It also explains the syntax and parameter
| definitions used in the verbs. Concurrency is also discussed.
| v Chapter2, “UsingAES, DES, and HMAC cryptography and verbs” gives an overview ofAES, DES, and
| ECC cryptography and provides general guidance information on how these verbs use different key
| types and key forms.
| v Chapter3, “Introducing PKAcryptography and using PKAverbs” introduces Public KeyAlgorithm (PKA)
| and Elliptic Curve Cryptography (ECC) support, and describes programming considerations for using the
| CCAPKAverbs, such as the PKAkey token structure and key management.
©CopyrightIBMCorp.2007,2011 1

2 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 1. Introduction to programming for the IBM Common
Cryptographic Architecture
This chapter introduces the IBM CCAapplication programming interface (API). The section explains basic
concepts and describes how you can obtain cryptographic and other services from the CEX3C feature and
CCA.
This chapter includes the following topics:
v “Available Common CryptographicArchitecture verbs”
v “Common CryptographicArchitecture functional overview” on page 4
v “CPACF support” on page 8
v “SecurityAPI programming fundamentals” on page 12
v “How to compile and link CCAapplication programs” on page 16
Available Common Cryptographic Architecture verbs
CCAproducts 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 theAES 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 MessageAuthentication Code (MAC) or
| keyed hash MAC (HMAC), that is useful in demonstrating data integrity.
| Non-repudiation
| Generate and verify digital signatures using either the RSAalgorithm or the ECDSAalgorithm, 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 variousAES, DES, ECC, and RSAkeys necessary to perform the above operations.
| Java interaction
| Interact with the Java Native Interface (JNI). Some of the CCAverbs have a specific version that can
| be used for JNI work.
| CCAmanagement
| Control the initialization and operation of CCA.
Subsequent sections group the many available verbs by topic. Each section lists the verbs in alphabetical
order by verb pseudonym.
The remainder of this section provides an overview of the structure of a CCAcryptographic framework and
introduces some important concepts and terms.
©CopyrightIBMCorp.2007,2011 3

Common Cryptographic Architecture functional overview
Figure1 provides a conceptual framework for positioning the CCAsecurityAPI, which you use to access a
common cryptographic architecture.Application programs make procedure calls to the CCAsecurityAPI to
obtain cryptographic and related I/O services. The CCAsecurityAPI is designed so that a call can be
issued from essentially any high-level programming language. The call, or request, is forwarded to the
cryptographic services access layer and receives a synchronous response; that is, your application
program loses control until the access layer returns a response after processing your request.
|
|
| Figure1.CCAsecurityAPI,accesslayer,andcryptographicengine
|
The products that implement the CCAsecurityAPI consist of both hardware and software components.
CCAsoftware 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 theAPI. Language bindings are provided
| for the C and Java programming languages.
v The runtime software can be divided into the following categories:
– Service-requesting programs, including application and utility programs.
– The securityAPI, 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 support services, and device driver to access one or more hardware cryptographic
engines.
4 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

– The cryptographic engine software that gives access to the cryptographic engine hardware.
The cryptographic engine is implemented in the hardware of the CEX3C coprocessor.
Security-sensitive portions of CCAare implemented in the cryptographic engine software running in
the protected coprocessor environment.
| – Utility programs and tools provide support for administering CCAsecret keys, interacting with CCA
| managed symmetric and public key cryptography key storage, and configuring the software support.
You can create application programs that employ the CCAsecurityAPI 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 CCAsecurityAPI with the cryptographic
coprocessors.
Cryptographic engine: The CCAarchitecture 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 CCAarchitecture
provides the logical security needed for the full protection of critical information.
| CEX2C Coprocessor: The coprocessor provides a secure programming and hardware environment
| whereinAES, DES and RSAprocesses are performed. Each cryptographic coprocessor includes a
| general-purpose processor, non-volatile storage, and specialized cryptographic electronics. These
| components are encapsulated in a protective environment to enhance security. The IBM CCASupport
| Program enables applications to employ a set ofAES, DES and RSA-based cryptographic services
| utilizing the coprocessor hardware. Services include:
| v DES key and RSAkey-pair generation
| v DES and RSAhost-based key record management
| v Digital signature generation and verification
| v Cryptographic key wrapping and unwrapping
| v Data encryption, decryption and MAC generation/verification
| v PIN processing for the financial services industry
| v Other services, including DES key-management based on CCA's control-vector-enforced key separation
| CEX3C Coprocessor: The coprocessor provides a secure programming and hardware environment
| whereinAES, DES, RSA, Elliptic Curve, and HMAC processes are performed. Each cryptographic
| coprocessor includes a general-purpose processor, non-volatile storage, and specialized cryptographic
| electronics. These components are encapsulated in a protective environment to enhance security. The IBM
| CCASupport Program enables applications to employ a set ofAES, DES, RSA, Elliptic Curve, and
| HMAC-based cryptographic services utilizing the coprocessor hardware. Services include:
| v DES,AES, RSA, Elliptic Curve, and HMAC key-pair generation
| v DES,AES, RSA, Elliptic Curve, and HMAC host-based key record management
v Digital signature generation and verification
v Cryptographic key wrapping and unwrapping
v Data encryption, decryption and MAC generation/verification
v PIN processing for the financial services industry
v Other services, including DES key-management based on CCA's control-vector-enforced key separation
CCA: Common CryptographicArchitecture (CCA) is the basis for a consistent cryptographic product family.
Applications employ the CCAsecurityAPI to obtain services from, and to manage the operation of, a
cryptographic system that meets CCAarchitecture specifications.
CCAaccess control: Each CCAnode has an access-control system enforced by the hardware and
protected software. The robust UNIX style access controls integrated into the Linux operating system are
used to protect the integrity of the underlying CCAhardware environment. The specialized processing
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 5

environment provided by the cryptographic engine can be kept secure because selected services are
provided only when certain requirements are met or a Trusted Key-Entry console is used to enable
access. 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 RSAkey-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
device key is stored within the coprocessor. The manufacturing facility key has itself been certified by a
securely held key unique to the CEX3C product line.
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 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-protected
memory.
CCAmaster key: When using the CCAarchitecture, working keys, including session keys and the RSA
| and ECC private keys used at a node to form digital signatures or to unwrap other keys, are generally
stored outside the cryptographic-engine protected environment. These working keys are wrapped (DES
triple-encrypted orAES encrypted) by the CCAmaster key. The master key is held in the clear (not
enciphered) within the cryptographic engine.
The number of keys usable with a CCAsubsystem 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 CCAcryptographic engines which have the same master key. This CCAcharacteristic is
useful in high-availability and high-throughput environments where multiple cryptographic processors must
function in parallel.
Establishing a CCAmaster key: To protect working keys, the master key must be generated and
initialized in a secure manner. One method uses the internal random-number generator for the source of
the master key. In this case, the master key is never external to the node as an entity and no other node
has the same master key unless master-key cloning is authorized and in use (unless, out of all the
possible values, another node randomly generates the same master-key data). If an uncloned coprocessor
loses its 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. The number of possible values is:
v For DES and RSAmaster keys, 2168
| v ForAES andAPKAmaster keys, 2256
Another master-key-establishment method enables authorized users to enter multiple, separate key parts
into the cryptographic engine.As each part is entered, that part is XORed with the contents of the new
master-key register. When all parts have been accumulated, a separate command is issued to promote the
contents of the current master-key register to the old master-key register and to promote the contents of
the new master-key register to the current master-key register. The length of the key parts is:
v For DES and RSAmaster keys, 168 bits
| v ForAES andAPKAmaster keys, 256 bits
CCAverbs:Application and utility programs called requestors obtain service from the CCASupport
Program by issuing service requests (verb calls or procedure calls) to the runtime subsystem (see
AppendixH, “Sample verb call routines,” on page 527 for sample routines). To fulfill these requests, the
Support Program obtains service from the coprocessor software and hardware.
6 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

The available services are collectively described as the CCAsecurityAPI.All the software and hardware
accessed through the CCAsecurityAPI should be considered an integrated subsystem.Acommand
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. In the System z environment, all application programs run using the permissions defined
in the DEFAULT role for their domain. The DEFAULT role can only be modified using the TKE workstation.
For a description of the functions that are permitted by the default version of the DEFAULT role, see z/OS
Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation User’s Guide.
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 securityAPI.All the
software and hardware accessed through the securityAPI should be considered an integrated subsystem.
When the cryptographic services access layer receives requests concurrently from multiple application
programs, it serializes the requests and returns a response for each request. There are other
multiprocessing implications arising from the existence of a common master-key and a common
key-storage facility. These topics are covered later in this book.
The way application programs and utilities are linked to theAPI services depends on the computing
environment. In the Linux environment, the operating system dynamically links application securityAPI
requests to the subsystem shared object library code. Compile application programs that use CCAand link
the compiled programs to the CCAlibrary. The library and its default distribution location is
/usr/lib64/libcsulcca.so.
Together, the securityAPI shared library 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
securityAPI 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 CCAsecurityAPI are synchronous, that is, your program loses control until the verb
completes. Multiple processing-threads can make concurrent calls to theAPI.
You can maximize throughput by organizing your application or applications to make multiple, overlapping
calls to the CCAAPI. You can also increase throughput by employing multiple coprocessors, each with
CCA.
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 7

Within the coprocessor, the CCAsoftware is organized into multiple threads of processing. This
multiprocessing design is intended to enable concurrent use of the coprocessor's main engine, PCIe
communications, DES and Secure HashAlgorithm-1 (SHA-1) engine, and modular-exponentiation engine.
Host-side key caching
Calls to the CCAsecurityAPI are synchronous, that is, your program loses control until the verb
completes. Multiple processing-threads can make concurrent calls to theAPI.
CCAprovides caching of key records obtained from key storage within the CCAhost 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 all processes
access the most current key-records. To suppress caching of key records, use the SET command to set
the environment variable CSUCACHE to NO. If this environment variable is not set, or is set to anything
other than NO, caching of key records will not be suppressed. The CSUCACHE environment variable does
not impact CPACF translated key caching.
CPACF support
Central ProcessorAssist for Cryptographic Functions (CPACF) support has these features:
v “Environment variables that affect CPACF usage”
v “Access control points that affect CPACF protected key operations” on page 9
v “CPACF operation (protected key)” on page 9
v “CCAlibrary CPACF preparation at startup” on page 11
v “Interaction between the 'default card' and use of Protected Key CPACF” on page 11
Environment variables that affect CPACF usage
The CSU_HCPUACLR and CSU_HCPUAPRT environment variables control whether the CPACF is used
for certain CCAfunctions. These variables are overridden by the explicit use of the Cryptographic
ResourceAllocate (CSUACRA) and Cryptographic Resource Deallocate (CSUACRD) verbs to enable or
disable these access patterns. To avoid confusion, the environment variables are given similar names to
the keywords used by Cryptographic ResourceAllocate (CSUACRA) and Cryptographic Resource
Deallocate (CSUACRD).
Note: The default values listed here are valid even if these environment variables are not defined. Their
settings represent default policy decisions made in the library code.
CSU_HCPUACLR
Use of the CPACF for clear key operations and hashing algorithms is allowed if this variable is set to '1' in
a profile setup file or with this command:
export CSU_HCPUACLR=1
Setting this variable to any other value (except for the case where the variable has not been set, as noted
above) results in disabling the use of the CPACF for clear key operations and hashing algorithms. The
default is '1', meaning that the function is enabled.
Affected verbs:
v MDC Generate (CSNBMDG)
v One-Way Hash (CSNBOWH)
v SymmetricAlgorithm Decipher (CSNBSAD) (clear keyAES)
v SymmetricAlgorithm Encipher (CSNBSAE) (clear keyAES)
8 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CSU_HCPUAPRT
Use of the CPACF for protected key (translated secure key) operations is allowed if this variable is set to
'1' in a profile setup file or with this command:
export CSU_HCPUAPRT=1
Setting this variable to any other value (except for the case where the variable has not been set, as noted
above) results in disabling the use of the CPACF for protected key (translated secure key) operations. The
default is '0', meaning that the function is disabled.
Affected verbs:
v Decipher (CSNBDEC)
v Encipher (CSNBENC)
v MAC Generate (CSNBMGN)
v MAC Verify (CSNBMVR)
v SymmetricAlgorithm Decipher (CSNBSAD) (clear keyAES)
v SymmetricAlgorithm Encipher (CSNBSAE) (clear keyAES)
Access control points that affect CPACF protected key operations
There are two access points that enable the protected key feature:
Symmetric Key Encipher/Decipher - Encrypted DES keys
This is bit X'0295', and is set ON by default.
ThisACP enables translating DES keys for use with the CPACF. Without this bit set ON, the call to the
CEX3C to rewrap the key under the CPACF wrapping key will fail with a return code 8 and reason code
90, which will in turn imply disabling the use of this function by the host user. This error will not be
returned to the user, instead the operation will be sent to the CEX3C. Because the default value of the
bit is ON, it is assumed that the user will know that it is set OFF on purpose.Areturn code 8 and
reason code 90 will cause no further requests to go to the CEX3C verb that translates keys, in an effort
to preserve normal path performance.
Symmetric Key Encipher/Decipher - EncryptedAES keys
This is bit X'0296', and is set ON by default.
ThisACP enables translatingAES keys for use with the CPACF. Without this bit set ON, the call to the
CEX3C to rewrap the key under the CPACF wrapping key will fail with a return code 8 and reason code
90, which will in turn imply disabling the use of this function by the host user. This error will not be
returned to the user, instead the operation will be sent to the CEX3C. Because the default value of the
bit is ON, it is assumed that the user will know that it is set OFF on purpose.Areturn code 8 and
reason code 90 will cause no further requests to go to the CEX3C verb that translates keys, in an effort
to preserve normal path performance.
CPACF operation (protected key)
These are details for Central ProcessorAssist for Cryptographic Functions (CPACF) usage by the host
library.
Note that at system power-on, the CPACF generates a new Key Encryption Key (KEK, kek-t) for wrapping
translated keys.
Figure2 on page 10 illustrates the CPACF layer as it relates to the security accessAPI and cryptographic
engine. The CPACF exploitation layer examines commands received by the security server to see if they
can be redirected to the CPACF. If so, this layer makes preparations (including translating secure keys to
protected keys), and then call the CPACF directly. If all preparations and the CPACF operations are
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 9

successful, the results are returned as a normal return through the security server. For any errors, the
command is redirected back through the security server to the normal path, using the allocated CEX3C for
the thread making the call.
|
|
| Figure2.CPACF
|
| Clear key or No key: For operations that do not use keys (such as hash algorithms) or operations that
| use keys that are not encrypted under the card master key, (called clear keys), no translation is necessary
| and the CPACF is used immediately.
Protected key: The device driver and the other layers are used for protected key support, for translating
keys. This relationship is similar to the 'directory server' relationship: a translation layer invisible to the
customer.After translation the 'translated-key' is stored in an invisible runtime cache so that the next use
of the key can avoid the translation step. For protected key usage, a CEX3C feature must be available
and allocated for use by the thread.
Important note about CPACF service actions and running applications
This note applies to processes using protected keys.
The CPACF is an independent hardware unit, like the CEX3C itself, and can be independently configured
available or unavailable while an S/390® Linux instance is running by service technicians performing
service actions. If the CPACF is cycled it will generate a new wrapping key for translated keys, invalidating
all of the keys in the CCAlibrary key translation cache. Therefore, it is never advisable to attempt such a
service action while there are system instances with applications running that use the CPACF.
10 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

If such an action is undertaken, applications should be stopped and restarted so that the libcsulcca.so is
unloaded from memory and reloaded. This will cause the key cache to be cycled.Amore complete
measure would be to reboot system images. If these precautions are disregarded and a CPACF service
action is undertaken as described, application crashes may ensue with a SIGSEGV error. This could occur
due to translated keys wrapped under outdated CPACF wrapping keys being used.
Anormal system-wide power cycle will cause the CPACF to generate a new wrapping key by design,
however, this action also of course cycles all of the hosted system LPARs and VM system images so there
is no problem; translated keys are not cached in permanent storage.
Using keys with CPACF, protected key
1. An eligible CCAverb call (see lists in “Access control points that affect CPACF protected key
operations” on page 9) specifying a key token or key identifier for a key token that is a normal internal
CCAkey token, called key-e here, comes into the CCAlibrary.
2. The CCAlibrary verifies that a CEX3C is available for key translation. If not, then the standard
‘no-available-device’error will be returned.
3. The CCAlibrary tries to find an already translated version (key-t) that matches the key-e passed into
the CCAlibrary.
v The user application (CCAlibrary in this case) must cache translated key-t objects in RAM, using
the key-e tokens as references.
4. If a key-t is not found for the key-e used:
The CCAlibrary translates the key-e to a key-t for use with the CPACF using CCAsecure services,
then caches the key pair.
5. At this point, either a fresh key-t has been obtained, or a key-t was found in RAM cache for the
operation.
6. The CCAlibrary directs the operation to the CPACF using the key-t.
The panel.exe -m command displays all the supported CPACF functions. This is especially useful on a
z/VM system, to make sure that the protected key functions are available. For details, see “The panel.exe
utility” on page 553.
| Using keys with CPACF, clear key or no key
1. An eligible CCAverb call (see lists in “Access control points that affect CPACF protected key
operations” on page 9) comes into the CCAlibrary.
2. No CEX3C is necessary, so no check for availability or Cryptographic ResourceAllocate (CSUACRA)
call will be implied.
3. The CCAlibrary prepares an appropriate CPACF clear key (key-c) structure using the clear key passed
to the CCAverb (key-v).
4. The CCAlibrary directs the operation to the CPACF using the key-c.
CCA library CPACF preparation at startup
When the CCAlibrary first starts up, it must prepare for use of the Central ProcessorAssist for
Cryptographic Functions (CPACF) by taking the following initialization steps:
1. Check configuration options to see if either is set to 'on', allowing some use of the CPACF.
If neither is on, skip the rest of initialization.
2. Check for existence and configuration of the CPACF.
Interaction between the 'default card' and use of Protected Key CPACF
While the CPACF can be used to encrypt and decrypt data in the absence of a CEX3C, for protected key
operations a CEX3C is still necessary and it must be the allocated or default adapter for the thread doing
the processing. This is necessary because the users' key tokens are translated with a service only
available on the CEX3C for use with the CPACF. Note also that for mixed CEX2C and CEX3C
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 11

configurations, the allocated adapter for the thread must be a CEX3C because the service that translates
the keys is not available on the CEX2C, for any CCAfirmware version.
Security API programming fundamentals
You obtain CCAcryptographic services from the coprocessor through procedure calls to the CCAsecurity
application programming interface (API). Most of the services provided are considered an implementation
of the IBM Common CryptographicArchitecture (CCA). Most of the extensions that differ from other IBM
CCAimplementations are in the area of the access-control services. If your application program is used
with other CCAproducts, compare the product literature for differences.
Your application program requests a service through the securityAPI 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 securityAPI is designed for use with high-level languages, such as C, COBOL, or RPG 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 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 Part2, “CCAverbs,” on page 55, and provides an
explanation of the characteristics of the securityAPI.
Each verb has an entry-point name and a fixed-length parameter list. Part2, “CCAverbs,” on page 55
describes each verb, and includes the following information for each verb:
v Pseudonym
v Entry-point name
v Description
v Format
v Parameters
v Restrictions
v Required commands
v Usage notes
v Related information
| v JNI version
Pseudonym
Also known as a general-language name or verb name, this name describes the function that the
verb performs, such as Key Generate.
Entry-point name
Also known as a computer-language name, this name is used in your program to call the verb. Each
verb's 7 or 8 character, entry-point name begins with one of the following prefixes:
Prefix Type of verb
CSNB Generally, theAES and DES verbs
| CSND Public key cryptography verbs, including RSAand Elliptic Curve
CSUA Cryptographic-node and hardware-control verbs
12 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

The last three or four letters in the entry-point name after the prefix identify the specific verb in a
group and are often the first letters of the principal words in the verb pseudonym.
| When verbs are described throughout this publication, they are sometimes referred to by the
| pseudonym, and at other times by the pseudonym followed by the verb entry point name in
| parenthesis.An example of this is: Key Generate (CSNBKGN).
| The verb prefixes used here are different from those used by IBM's Integrated Cryptographic Service
| Facility (ICSF).
Description
The verb is described in general terms. Be sure to read the parameter descriptions because these
add additional detail.
Format
The format section for each verb lists the entry-point name on the first line. This is followed by the list
of parameters for the verb. You must code all the parameters, and they must be in the order listed.
entry-point name(
return_code,
reason_code,
exit_data_length,
exit_data,
parameter_5,
parameter_6,
.
.
.
parameter_n )
Parameters
All information exchanged between your application program and a verb is through the variables
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 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 14 and the individual verbs. The remaining parameters
are unique for each verb. For descriptions of these parameters, see the definitions with the individual
verbs.
In the description for each parameter, data flow direction and data type are indicated, as follows.
Direction: Direction Type: Data type
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.
Input/Output The application program sends the variable to the verb or the verb returns the
variable to the application program, or both.
Type: Data identified by a verb parameter can be a single value or a one-dimensional array. If a
parameter identifies an array, each data element of the array is of the same data type. If the number
of elements in the array is variable, a preceding parameter identifies a variable that contains the
actual number of elements in the associated array. Unless otherwise stated, a variable is a single
value, not an array.
For each verb, the parameter descriptions use the following terms to describe the type of variable:
Integer
A4-byte (32-bit), signed, two's-complement binary number.
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 13

String Aseries 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 “The rule_array and
other keyword parameters” on page 15.
Restrictions
Any restrictions are noted.
Required commands
Any access control points required to use the verb are described here.
Usage notes
Usage notes about this verb are listed.
Related information
Any related information is noted.
JNI version
If the verb has a Java Native Interface version, it is described.
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 “The rule_array and other keyword parameters” on page 15
v “Key tokens, key labels, and key identifiers” on page 15
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.Aparameter is an address pointer to the associated variable in application program storage.
return_code
The return code specifies the general result of the verb.AppendixA, “Return codes and reason codes”
lists the return codes.
reason_code
The reason code specifies the result of the verb that is returned to the application program. Each
return code has different reason codes assigned to it that indicate specific processing problems.
AppendixA, “Return codes and reason codes” lists the reason codes.
exit_data_length
Apointer to an integer value containing the length of the string (in bytes) that is returned by the
exit_data value. This parameter should point to a value of zero, to ensure compatibility with any future
extension or other operating environment.
exit_data
The data that is passed to an installation exit. Exits are not supported and no exit data is allowed in
this parameter.
Restriction: 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.
14 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Return code and reason code overview: The return_code variable provides a general indication of the
results of verb processing and is the value your application program should generally use in determining
the course of further processing. For a list of return codes and their meanings, see “Return codes” on
page 407. The reason_code variable provides more specific information about the outcome of verb
processing. Reason code values generally differ between CCAproduct 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.
SeeAppendixA, “Return codes and reason codes” for a detailed discussion of return codes and a
complete list of all return and reason codes.
The rule_array and other keyword parameters
rule_array parameters and some other parameters use keywords to transfer information. Generally, a
rule_array consists of a variable number of data elements that contain keywords that direct specific details
of the verb process.Almost all keywords, in a rule_array or otherwise, are eight bytes in length, and
should be uppercase, left-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 is used to convey information other than keywords between your application
and the server. This is, however, an exception. For a list of key types that are passed in the rule_array
keyword, see Table2 on page 29.
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.Averb 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.
Key tokens are described as either internal, operational, or external, as follows:
Internal Akey token that contains an encrypted key for local use. The cryptographic engine
decrypts an internal key to use the key in a local operation. When a key is entered into the
system, it is always encrypted if it appears outside 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 key that is
encrypted under a master key. During entry of a key, the internal key-token can have a
flag set indicating the key information is incomplete.
External Akey token that contains 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.Akey wrapped by a (transport) key-encrypting key is
designated as being external.
| RSAand ECC public-keys are not encrypted values and, when not accompanied by
| private-key information, are retained in an external key-token.
Internal key tokens can be stored in a file maintained by the directory server. These key tokens are
referenced by use of a key label.Akey label is an alphanumeric string you place in a variable and
reference with a verb parameter.
Verb descriptions specify how you can provide a key using these terms:
Term Description
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 15

Key token The variable must contain a proper key-token structure.
Key label The variable must contain a key-label string used to locate a key record in key storage.
Key identifier The variable must contain either a key token or a key label. The first byte in the variable
indicates whether the variable contains a key token or a key label. When the first byte is in
the range X'20' - X'FE', the variable is processed as a key label. There are additional
restrictions on the value of a key label. The first byte in all key-token structures is in the
range of X'01' - X'1F'. The value X'00' indicates a DES null key-token. The value X'FF' as
the first byte of a key-related variable passed to theAPI raises an error condition.
How to compile and link CCA application programs
The Support Program includes the C language source code and the make file for a sample program. The
file and its default distribution location is:
/opt/IBM/CEX3C/samples
Compile application programs that use CCA, and link the compiled programs to the CCAlibraries. The
libraries and their default distribution locations are:
/usr/lib64/libcsulcca.so.*
/usr/lib64/libcsulccamk.so.*
Note: /usr/lib64/libcsulccamk.so contains the Master Key Process (CSNBMKP) verb.Any use of the
libcsulccamk.so library is restricted because the library is installed so that only the 'root' user (user
id of 0) and members of the group 'cca_admin' have read access. The cca_admin group is added
by the CCARPM install procedure. This is done to limit the ability of an untrusted user to copy the
library with the purpose of reverse-engineering the master-key access methods inside it.
Furthermore, use of some specific access methods through the Master Key Process (CSNBMKP)
verb are restricted to corresponding Linux group membership of the user trying to make that
access. Table161 on page 546 contains a list of the groups and their functions.
Users without the required group membership are denied use. For more information, see Master
key load (Step 7 on page 544).
Building Java applications to use with the CCA JNI
The CCASupport Program includes a CCAJava Native Interface (JNI). To illustrate how to use the CCA
JNI to call CCAverbs, a sample module named mac.java is provided. The mac.java sample program calls
the same CCAverbs as the sample C language program mac.c. See “Sample program in Java” on page
532.
The default distribution location of the sample code is:
Operating system Default distribution location
Novell SUSE Linux /opt/IBM/CEX3C/samples
Red Hat Linux /opt/IBM/CEX3C/samples
These versions of Java are supported for JNI:
v Java 1.6.0 for Red Hat Enterprise Linux
v Java 1.4.2 for SUSE Linux Enterprise Server 10 and 11 (SLES 10 and 11) from Novell
These Java versions are the tested versions, and they were installed from the distribution CD or other
authorized source for that distribution, and they were not customized in any way.
So that the CCAcan access Java, do one of the following:
16 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

1. Add the path to the java/javac executable to the user's PATH environment variable, so that they can
call the command without preconditions.
2. Create soft-links from the java/javac executables from wherever they are located to a directory that is
in the user's PATH environment variable by default, such as /usr/bin/.
The Java entry points of CCAverbs are very similar to the C entry points except that a letter 'J' is
appended to the entry point name. For example, CSNBKGN is the C entry point for the Key Generate
verb, and CSNBKGNJ is the Java entry point for this verb. Where each verb is described in detail in
Part2, “CCAverbs,” on page 55, a section for the JNI interface is included.
Data types used in the JNI
These two data types are defined and used in the JNI:
hikmNativeInteger 64-bit native signed integer (type long), matching the C interface
Byte * General pointer type to unsigned byte
Afile named hikmNativeInteger.html provides information about this class, and is located in the same
directory as the mac.java file.
Building the Java Byte code
Issue the following command from the directory that contains the source code file <yourfile>.java to
compile the program:
javac -classpath /opt/IBM/CEX3C/cnm/HIKM.zip <yourfile>.java
Notes:
1. The classpath option points to the HIKM.zip file because the hikmNativeInteger class and JNI verb
front end classes are in this file.
2. The path shown for the HIKM.zip file is the default RPM installation location of that file.
For applications that also use the Master Key Process (CSNBMKP) verb: For security, the JNI
interface for the Master Key Process (CSNBMKP) verb is also in the restricted access library
libcsulccamk.so, and the Java class front end is implemented in a separate compressed file. Therefore, to
compile a Java Byte code file named <yourfile>.java, issue this command:
javac -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:/opt/IBM/CEX3C/cnm/HIKMMK.zip <yourfile>.java
Notes:
1. The classpath option points to the HIKM.zip file because the hikmNativeInteger class and JNI verb
front end classes are in this file.
2. The classpath option also points to the HIKMMK.zip file, where the Master Key Process (CSNBMKP)
verb Java class front end for the JNI implementation is found.
3. The path shown for the HIKM.zip and HIKMMK.zip files is the default RPM installation location of that
file.
Running the Java Byte code
Issue the following command from the directory that contains the Java Byte code file <yourfile>.class to
run the program:
java -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:.<yourfile>.class
Notes:
1. See “Building the Java Byte code” for notes on the HIKM.zip classpath.
2. Notice that '.' (period) is added to the class path so that Java can find <yourfile>.class in the current
directory.
For applications that also use the Master Key Process (CSNBMKP) verb: You must also add the
extra classpath option noted above for building to the run step:
Chapter1.IntroductiontoprogrammingfortheIBMCommonCryptographicArchitecture 17

java -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:/opt/IBM/CEX3C/cnm/HIKMMK.zip:.<yourfile>.class
Notes:
1. See “Building the Java Byte code” on page 17 for notes on the HIKM.zip classpath.
2. Notice that '.' (period) is added to the class path so that Java can find <yourfile>.class in the current
directory.
18 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

|
Chapter 2. Using AES, DES, and HMAC cryptography and
verbs
The CEX3C protects data from unauthorized disclosure or modification. This coprocessor protects data
stored within a system, stored in a file off a system on magnetic tape, and sent between systems. The
coprocessor also authenticates the identity of customers in the financial industry and authenticates
messages from originator to receiver. The coprocessor uses cryptography to perform these functions.
The CCAAPI for the coprocessor provides access to cryptographic functions through verbs.Averb is a
routine that receives control using a function call from an application program. Each verb performs one or
more cryptographic functions, including:
v Generating and managing cryptographic keys
v Enciphering and deciphering data with encrypted keys using either the U.S. National Institute of
Standards and Technology (NIST) Data Encryption Standard (DES) orAdvanced Encryption Standard
(AES)
v Re-enciphering text from encryption under one key to encryption under another key
v Encoding and decoding data with clear keys
v Generating random numbers
v Ensuring data integrity and verifying message authentication
v Generating, verifying, and translating personal identification numbers (PINs) that identify a customer on
a financial system
| This chapter provides an overview of theAES, DES, and HMAC cryptographic functions provided by CCA,
| explains the functions of the cryptographic keys, and introduces the topic of building key tokens.
Functions of the AES, DES and HMAC cryptographic keys
|
| The CCAAPI provides functions to create, import, and exportAES, DES and HMAC keys. This section
| gives an overview of these cryptographic keys.
Key separation
The cryptographic coprocessor controls the use of keys by separating them into unique types, allowing you
to use a specific type of key only for its intended purpose. For example, a key used to protect data cannot
be used to protect a key.
ACCAsystem has only one DES orAES master key. However, to provide for key separation, the
cryptographic coprocessor automatically encrypts each type of key under a unique variation of the master
key. Each variation of the master key encrypts a different type of key.Although you enter only one master
key, you have a unique master key to encrypt all other keys of a certain type.
Master key variant
Whenever the master key is used to encipher a key, the cryptographic coprocessor produces a variation of
the master key according to the type of key that the master key will encipher. These variations are called
master key variants. The cryptographic coprocessor creates a master key variant by XORing a fixed
pattern, called a control vector, onto the master key.Aunique control vector is associated with each type
of key. For example, all the different types of data-encrypting, PIN, MAC, and transport keys each use a
unique control vector which is XORed with the master key in order to produce the variant. The different
key types are described in “Types of keys” on page 25.
Each master key variant protects a different type of key. It is similar to having a unique master key protect
all the keys of a certain type.
©CopyrightIBMCorp.2007,2011 19

The master key, in the form of master key variants, protects keys operating on the system.Akey can be
used in a cryptographic function only when it is enciphered under a master key. When systems want to
share keys, transport keys are used to protect keys sent outside of systems. When a key is enciphered
under a transport key, the key cannot be used in a cryptographic function. It must first be brought on to a
system and enciphered under the system's master key, or exported to another system where it will then be
enciphered under that system's master key.
Transport key variant
Like the master key, the coprocessor creates variations of a transport key to encrypt a key according to its
type. This allows for key separation when a key is transported off the system.Atransport key variant, also
called key-encrypting key variant, is created the same way a master key variant is created. The transport
key's clear value is XORed with a control vector associated with the key type of the key it protects.
Note: To exchange keys with systems that do not recognize transport key variants, the coprocessor
allows you to encrypt selected keys under a transport key itself, not under the transport key variant.
For more information, see NOCV Importers and Exporters on page 26.
Key forms
Akey that is protected under the master key is in operational form, which means the coprocessor can use
it in cryptographic functions on the system.
When you store a key with a file or send it to another system, the key is enciphered under a transport key
rather than the master key. The transport key is a key shared by your system and another system for the
purpose of securely exchanging other keys. When CCAenciphers a key under a transport key, the key is
not in operational form and cannot be used to perform cryptographic functions.
When a key is enciphered under a transport key, the sending system considers the key in exportable form.
The receiving system considers the key in importable form. When a key is re-enciphered from under a
transport key to under a system's master key, it is in operational form again.
Enciphered keys appear in three forms. The form you need depends on how and when you use a key.
v Operational key form is used at the local system. Many verbs can use an operational key form.
The Key Generate, Key Import, Data Key Import, Clear Key Import, and Multiple Clear Key Import verbs
can create an operational key form.
v Exportable key form is transported to another cryptographic system. It can be passed only to another
system. The CCAverbs cannot use it for cryptographic functions. The Key Generate, Data Key Export,
and Key Export verbs produce the exportable key form.
v Importable key form can be transformed into operational form on the local system. The Key Import verb
(CSNBKIM) and the Data Key Import verb (CSNBDKM) can use an importable key form. Only the Key
Generate verb (CSNBKGN) can create an importable key form.
For more information about the key types, see “Functions of theAES, DES and HMAC cryptographic keys”
on page 19. SeeAppendixC, “Key forms and types used in the Key Generate verb,” on page 459 for
more information about key form.
Symmetric key (DES, AES) flow
The conversion from one key to another key is considered to be a one-way flow.An operational key form
cannot be turned back into an importable key form.An exportable key form cannot be turned back into an
operational or importable key form. The flow of CCAkey forms can be in only one direction:
IMPORTABLE —to→ OPERATIONAL —to→ EXPORTABLE
20 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token
| AnAES or DES key token is a 64-byte field composed of a key value and control information.An HMAC
| key token is a variable-length token composed of a key value and control information. The control
| information is assigned to the key when the coprocessor creates the key. The key token can be either an
| internal key token, an external key token, or a null key token. Through the use of key tokens, CCAcan do
| the following:
| v Support continuous operation across a master key change
| v Control use of keys in cryptographic services
If the first byte of the key identifier is X'01', the key identifier is interpreted as an internal key token.An
internal key token is a token that can be used only on the CCAsystem that created it or another CCA
system with the same host master key. It contains a key that is encrypted under the master key.
An application obtains an internal key token by using one of the verbs such as those listed below. The
verbs are described in detail in Chapter5, “ManagingAES and DES cryptographic keys.”
| v AES Key Record Read
v Clear Key Import
v Data Key Import
| v DES Key Record Read
v Key Generate
| v Key Generate2
v Key Import
| v Key Part Import
| v Key Part Import2
v Key Token Build
| v Key Token Build2
v Multiple Clear Key Import
The master key could be dynamically changed between the time that you invoke a verb, such as the Key
Import verb, to obtain a key token, and the time that you pass the key token to the Encipher verb. When a
change to the master key occurs, the coprocessor will still successfully use the key, because it stores a
copy of the old master key as well as the new one.
| Attention: If an internal key token held in user storage is not used while the master key is changed
| twice, the internal key token is no longer usable.Areturn code of 0 with a reason code of 10001 notifies
| you that the master key used to decrypt the key used in your operation was an old master key, as a
| reminder that you should use one of the Key Token Change verbs to re-encipher your key under the
| current or new master key (as desired, see verbs for description).
For debugging information, seeAppendixB, “Key token formats” for the format of an internal key token.
If the first byte of the key identifier is X'02', the key identifier is interpreted as an external key token. By
using the external key token, you can exchange keys between systems. It contains a key that is encrypted
under a key-encrypting key.
An external key token contains an encrypted key and control information to allow compatible cryptographic
systems to:
v Have a standard method of exchanging keys
v Control the use of keys through the control vector
v Merge the key with other information needed to use the key
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 21

An application obtains the external key token by using one of the verbs such as those listed below. They
are described in detail in Chapter5, “ManagingAES and DES cryptographic keys.”
v Key Generate
v Key Export
v Data Key Export
For debugging information, seeAppendixB, “Key token formats” for the format of an external key token.
If the first byte of the key identifier is X'00', the key identifier is interpreted as a null key token. Use the
null key token to import a key from a system that cannot produce external key tokens. That is, if you have
an 8 or 16-byte key that has been encrypted under an importer key, but is not imbedded within a token,
place the encrypted key in a null key token and then invoke the Key Import verb to get the key in
operational form.
For debugging information, seeAppendixB, “Key token formats” for the format of a null key token.
Key wrapping
|
| This section explains how symmetric keys are wrapped with master and key-encrypting keys. For DES and
| AES keys, two methods are detailed. These methods use the 64-byte token. HMAC keys use a variable
| length token with associated data and the payload wrapping method.
| AES key wrapping
| The key value inAES tokens are wrapped using theAES algorithm and cipher block chaining (CBC) mode
| of encryption. The key value is left justified in a 32-byte block, padded on the right with zero, and
| encrypted.
| The enhanced wrapping of anAES key (*K) using anAES *MK is defined as:
| e*MK(*K) = ecbcMK(*K)
| DES key wrapping
| The key value in a DES key token are wrapped using one of two possible methods:
| Original method
| The key value in DES tokens are encrypted using triple-DES encryption, and key parts are encrypted
| separately. See “ECB wrapping of DES keys (Original method).”
| Enhanced method
| The key value for keys is bundled with other token data and encrypted using triple-DES encryption and
| cipher block chaining mode. The enhanced method applies only to DES key tokens. The enhanced
| method of symmetric key wrapping is designed to beANSI X9.24 compliant. This method was
| introduced with CCA4.1.0. See “Enhanced CBC wrapping of DES keys (Enhanced method)” on page
| 23.
| ECB wrapping of DES keys (Original method)
| The wrapping of a double-length key (*K) using a double-length key-encrypting key (*KEK) is defined as
| follows:
| e*KEK(KL) || e*KEK(KR) = eKEKL(dKEKR(eKEKL(KL))) || eKEKL(dKEKR(eKEKL(KR)))
| Where:
|| KL Is the left 64 bits of *K
|| KR Is the right 64 bits of *K
|| KEKL Is the left 64 bits of *KEK
|| KEKR Is the right 64 bits of *KEK
22 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

|| | | Means concatenation
| Enhanced CBC wrapping of DES keys (Enhanced method)
| The enhanced CBC wrapping method uses triple-DES encryption, an internal chaining of the key value,
| and CBC mode. This method was introduced with CCA4.1.0.
| The enhanced wrapping of a double-length key (*K) using a double-length key-encrypting key (*KEK) is
| defined as:
| e*KEK(*KL) = ecbcKEKL(dcbcKEKR(ecbcKEKL(KLPRIME || KR)))
| KLPRIME = KL XOR SHA1(KR)
| Where:
|| KL Is the left 64 bits of *K
|| KR Is the right 64 bits of *K
|| KLPRIME Is the 64-bit modified value of KL
|| KEKL Is the left 64 bits of *KEK
|| KEKR Is the right 64 bits of *KEK
|| SHA1(X) Is the 160-bit SHA-1 hash of X
|| | | Means concatenation
|| XOR Means bitwise exclusive OR
|| ecbc Means encryption using cipher block chaining mode
|| dcbc Means decryption using cipher block chaining mode
| Wrapping key derivation for enhanced wrapping of DES keys: The wrapping key is exactly the same
| key that is used by the legacy wrapping method (the only method used by CCA4.0.0), with one exception.
| Instead of using the base key itself (master key or key-encrypting key), a key that is derived from that
| base key is used. The derived key will have the control vector applied to it in the standard CCAmanner,
| and then use the resulting key to wrap the new-format target key token.
| The reason for using a derived key is to ensure that no attacks against this wrapping scheme are possible
| using the existing CCAfunctions. For example, it was observed that an attack was possible by copying the
| wrapped key into an ECB CCAkey token, if the wrapping key was used instead of a derivative of that key.
| The key will be derived using a method defined in the U.S. National Institute of Standards and Technology
| (NIST) standard SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions
| (October, 2009). Derivation will use the method KDF in Counter Mode using pseudorandom function (PRF)
| HMAC-SHA256. This method provides sufficient strength for deriving keys for any algorithm used.
| The HMAC algorithm is defined as:
| HMAC(K, text) = H((K0 XOR opad ) || H((K0 XOR ipad) || text))
| Where:
|| H Is an approved hash function.
|| K Is a secret key shared between the originator and the intended receivers.
|| K0 The key K after any necessary preprocessing to form a key of the proper length.
|| ipad Is the constant X'36' repeated to form a string the same length as K0
|| opad Is the constant X'5C' repeated to form a string the same length as K0
|| text Is the text to be hashed.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 23

|| || Means concatenation
|| XOR Means bitwise exclusive OR
| If the key K is equal in length to the input block size of the hash function (512 bits for SHA-256), K0 is set
| to the value of K. Otherwise, K0 is formed from K by hashing or padding.
| The Key Derivation Function (KDF) specification calls for inputs optionally including two byte strings, Label
| and Context. The Context will not be used. The Label will contain information on the usage of this key, to
| distinguish it from other derivations that CCAmay use in the future for different purposes. Because the
| security of the derivation process is rooted in the security of the derivation key and in the HMAC and Key
| Derivation Functions (KDF) themselves, it is not necessary for this label string to be of any particular
| minimum size. The separation indicator byte of X'00' specified in the NIST document will follow the label.
| The label value will be defined so that it is unique to derivation for this key wrapping process. This means
| that any future designs that use the same KDF must use a different value for the label. The label will be
| the 16 byte value consisting of the followingASCII characters:
| ENHANCEDWRAP2010 (X’454E4841 4E434544 57524150 32303130’)
| The parameters for the counter mode KDF defined in NIST standard SP 800-108 are:
| Fixed values:
|| h Length of output of PRF, 256 bits
|| r Length of the counter, in bits, 32. The counter will be an unsigned 4-byte value.
| Inputs:
| v KI (input key) - The key we are deriving from.
| v Label - The value shown above (ASCII ENHANCEDWRAP2010).
| v Separator byte - X'00' following the label value.
| v Context -Anull string. No context is used.
| v L- The length of the derived key to be produced, rounded up to the next multiple of 256.
| v PRF - HMAC-SHA256.
| Variable length token (AESKW method)
| The wrapping method for the variable-length key tokens withAESKW is defined in standardANSI X9.102.
| The wrapping of the payload of a variable length key (*K) using anAES *MK is defined as:
| e*MK(*K) = eAESKW*MK(P)
| P = ICV || Pad length || Hash length || Hash options || Data hash || *K || Padding
| Where:
|| ICV Is the 6 byte constant X'A6A6A6A6A6A6'.
|| Pad length Is the length of the padding in bits.
|| Hash length Is the length of the Data Hash in bytes.
|| Hash options Is a 4-byte field.
|| Data hash Is the hash of the associated data block.
|| Padding Is the number of bytes of X'00' used to make the overall length of P a multiple of 16.
|| eAESKW Means encryption using theAESKW method.
24 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Control vector
Aunique control vector exists for each type of CCAkey. For an internal key token, the coprocessor XORs
the master key with the control vector associated with the type of key the master key will encipher. The
control vector ensures that an operational key is used only in cryptographic functions for which it is
intended. For example, the control vector for an input PIN-encrypting key ensures that such a key can be
used only in the Encrypted PIN Translate and Encrypted PIN Verify functions.
Types of keys
The cryptographic keys are grouped into the following categories based on the functions that they perform:
Symmetric keys master key (SYM-MK)
The SYM-MK master key is a triple-length (192-bit) key that is used only to encrypt other DES keys on
the coprocessor. The administrator installs and changes the SYM-MK master key using the panel.exe
utility, the clear key entry panels, the z/OS® clear key entry panels, or the optional Trusted Key Entry
(TKE) workstation. The master key always remains within the secure boundary of the coprocessor. It is
used only to encipher and decipher keys that are in operational form.
For details about panel.exe, see “The panel.exe utility” on page 553.
Note: If the coprocessor is shared with z/OS, the SYM-MK key must be a double-length (128-bit) key.
This means that the first 64 bits and the last 64 bits of the key must be identical. If the master
key is loaded by z/OS CCAor from a TKE workstation, it will automatically be a double-length
key.
AES keys master key (AES-MK)
| TheAES-MK master key is a 256-bit key that is used to encrypt otherAES keys and HMAC keys on
| the coprocessor. The administrator installs and changes theAES-MK master key using the panel.exe
| utility, the clear key entry panels, the z/OS clear key entry panels, or the optional Trusted Key Entry
| (TKE) workstation. The master key always remains within the secure boundary of the coprocessor. It is
| used only to encipher and decipher keys that are in operational form.
| For details about panel.exe, see “The panel.exe utility” on page 553.
Asymmetric keys master key (ASYM-MK)
TheASYM-MK is a triple-length (192-bit) key that is used to protect RSAprivate keys on the
coprocessor. The administrator installs and changes theASYM-MK master key using the panel.exe
utility, the clear key entry panels, the z/OS clear key entry panels, or the optional Trusted Key Entry
(TKE) workstation. The master key always remains within the secure boundary of the coprocessor. It is
used only to encipher and decipher keys that are in operational form.
For details about panel.exe, see “The panel.exe utility” on page 553.
| AES PKAmaster key (APKA-MK)
| TheAPKA-MK key, introduced to CCAbeginning with Release 4.1.0, 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. TheAPKA-MK is a 256-bit (32-byte) value. The
| administrator installs and changes theAPKA-MK master key using the panel.exe utility, the clear key
| entry panels, the z/OS clear key entry panels, or the optional Trusted Key Entry (TKE) workstation.
Data-encrypting keys
The data-encrypting keys are single-length DES (64-bit), double-length DES (128-bit), or triple-length
DES (192-bit) keys, or 128-bit, 192-bit or 256-bitAES keys that protect data privacy. Single-length DES
data-encrypting keys can also be used to encode and decode data and authenticate data sent in
messages. If you intend to use a data-encrypting key for an extended period of time, you can store it in
the CCAkey storage file so that it will be re-enciphered if the master key is changed.
You can use single-length DES data-encrypting keys in the Encipher and Decipher verbs to manage
data, and also in the MAC Generate and MAC Verify verbs. Double-length DES and triple-length DES
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 25

data-encrypting keys can be used in the Encipher and Decipher verbs for more secure data privacy.
DATAC is also a double-length DES data encrypting key.
AES data-encrypting keys can be used in services similar to DES data-encrypting key services.
CIPHER keys
These consist of CIPHER, ENCIPHER, and DECIPHER keys. They are single and double length DES
keys for enciphering and deciphering data.
| HMAC keys
| HMAC keys are variable-length symmetric keys. The length is in the range of 80 - 2024. HMAC keys
| are used to generate and verify HMACs using the FIPS-198 algorithm, with the HMAC Generate and
| HMAC Verify verbs.
| v Operational keys will be encrypted under theAES master key
| v HMAC keys can be imported and exported under an RSAkey.
| v HMAC keys will be stored in theAES key storage file. TheAES master key must be active.
| For more information about HMAC keys and verb processing, see Chapter7, “Verifying data integrity
| and authenticating messages,” on page 233.
MAC keys
The MAC keys are single-length DES (64-bits - DATAM, DATAMV, MAC, and MACVER, ) and
double-length DES (128-bits - DATAM, DATAMV, MAC, and MACVER) keys used for the verbs that
generate and verify MACs.
PIN keys
The personal identification number (PIN) is a basis for verifying the identity of a customer across
financial industry networks. PIN keys are used in cryptographic functions to generate, translate, and
verify PINs, and protect PIN blocks. They are all double-length DES (128 bits) keys. PIN keys are used
in the Clear PIN Generate, Encrypted PIN Verify, and Encrypted PIN Translate verbs.
For installations that do not support double-length DES 128-bit keys, effective single-length DES keys
are provided. For a single-length DES key, the left key half of the key equals the right key half.
“Processing personal identification numbers” on page 37 gives an overview of the PIN algorithms you
need to know to write your own application programs.
Transport keys (or key-encrypting keys)
Transport keys are also known as key-encrypting keys, or KEKs. They are double-length DES (128
bits) keys used to protect other keys when you distribute them from one system to another.
There are several types of transport keys:
Exporter or OKEYXLAT key-encrypting key
This type of key protects keys of any type that are sent from your system to another system. The
exporter key at the originator is the same key as the importer key of the receiver.
Importer or IKEYXLAT key-encrypting key
This type of key protects keys of any type that are sent from another system to your system. It also
protects keys that you store externally in a file that you can import to your system later. The importer
key at the receiver is the same key as the exporter key at the originator.
NOCV Importers and Exporters
These keys are key-encrypting keys used to exchange keys with systems that do not recognize
key-encrypting key variants. There are some requirements and restrictions for the use of NOCV
key-encrypting keys:
v The use of NOCV IMPORTERs and EXPORTERs is controlled by access control points in the
coprocessor's role-based access control system.
v Only programs in system or supervisor state can use the NOCV key-encrypting key in the form of
tokens in verbs.Any program can use NOCV key-encrypting keys with label names from the key
storage.
26 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

v Access to NOCV key-encrypting keys should be carefully controlled, because use of these keys
can reduce security in your key management process.
v NOCV key-encrypting key can be used to encrypt single or double length DES keys with standard
CVs for key types DATA, DATAC, DATAM, DATAMV, DATAXLAT, EXPORTER, IKEYXLAT,
IMPORTER, IPINENC, single-length MAC, single-length MACVER, OKEYXLAT, OPINENC,
PINGEN and PINVER.
v NOCV key-encrypting keys can be used with triple length DATAkeys. Because DATAkeys have 0
CVs, processing will be the same as if the key-encrypting keys are standard key-encrypting keys
(not the NOCV key-encrypting key).
| You use key-encrypting keys to protect keys that are transported using any of the following verbs: Data
| Key Export, Key Export, Key Import, Clear Key Import, Multiple Clear Key Import, Key Generate, Key
| Generate2, Key Translate and Key Translate2.
For installations that do not support double-length key-encrypting keys, effective single-length keys are
provided. For an effective single-length key, the clear key value of the left key half equals the clear key
value of the right key half.
Key-generating keys
Key-generating keys are double-length keys used to derive other keys. This is often used in smart card
applications.
Table1 describes the key types.
Table1.Keytypes
KeyType Description
|| AESDATA Dataencryptingkey.UsetheAES128-bit,192-bit,or256-bitkeytoencipheranddecipherdata.
|| AESTOKEN CancontainanAESkey.
|| CIPHER Usedonlytoencryptordecryptdata.Thisisasingleordoublelengthkeyandcanbeusedin
| theEncipherorDecipherverbs.
|| CLRAES Dataencryptingkey.Thekeyvalueisnotencrypted.UsethisAES128-bit,192-bit,or256-bit
| keytoencipheranddecipherdata.
|| CLRDES Dataencryptingkey.Thekeyvalueisnotencrypted.UsethisDESsingle-length,double-length,
| ortriple-lengthkeytoencipheranddecipherdata.
CVARDEC Thecryptographicvariabledecipherservice,whichisavailableinsomeCCAimplementations,
usesaCVARDECkeytodecryptplaintextbyusingtheCipherBlockChaining(CBC)method.
Thisisasingle-lengthkey.
CVARENC Thecryptographicvariableencipherservice,whichisavailableinsomeCCAimplementations,
usesaCVARENCkeytoencryptplaintextbyusingtheCipherBlockChaining(CBC)method.
Thisisasingle-lengthkey.
CVARPINE UsedtoencryptaPINvaluefordecryptioninaPIN-printingapplication.Thisisasingle-length
key.
CVARXCVL UsedtoencryptspecialcontrolvaluesinDESkeymanagement.Thisisasingle-lengthkey.
CVARXCVR UsedtoencryptspecialcontrolvaluesinDESkeymanagement.Thisisasingle-lengthkey.
|| DATA Dataencryptingkey.UsethisDESsingle-length,double-length,ortriple-lengthkeytoencipher
| anddecipherdata.UsetheAES128-bit,192-bit,or256-bitkeytoencipheranddecipherdata.
DATAC UsedtospecifyaDATA-classkeythatwillperformintheEncipherandDecipherverbs,butnot
intheMACGenerateorMACVerifyverbs.Thisisadouble-lengthkey.Onlyavailablewitha
CEX3C.
DATAM Key-encryptingkeysthathaveacontrolvectorwiththisattributeformerlycouldonlybeusedto
transportkeyswithakeytypeofDATA,CIPHER,ENCIPHER,DECIPHER,MAC,andMACVER.
Themeaningofthiskeywordhasbeendiscontinuedanditsusageisallowedforbackward
compatibilityreasonsonly.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 27

Table1.Keytypes (continued)
KeyType Description
DATAMV UsedtospecifyaDATA-classkeythatperformsintheMACVerifyverb,butnotintheMAC
Generate,Encipher,orDecipherverbs.
|| DATAXLAT Datatranslationkey.Usethissingle-lengthkeytoreenciphertextfromoneDATAkeytoanother.
DECIPHER Usedonlytodecryptdata.DECIPHERkeyscannotbeusedintheEncipher(CSNBENC)verb.
Thisisasingle-lengthkey.
ThisisasingleordoublelengthkeyandcanbeusedintheDecipherverb.
DKYGENKY Usedtogenerateadiversifiedkeybasedonthekey-generatingkey.Thisisadouble-lengthkey.
ENCIPHER Usedonlytoencryptdata.ENCIPHERkeyscannotbeusedintheDecipher(CSNBDEC)verb.
Thisisasingle-lengthkey.
ThisisasingleordoublelengthkeyandcanbeusedintheEncipherverb.
EXPORTER Exporterkey-encryptingkey.Usethisdouble-lengthkeytoconvertakeyfromtheoperational
formintoexportableform.
|| HMAC Variable-lengthHMACgenerationkey.UsethiskeytogenerateorverifyaMessage
| AuthenticationCodeusingthekeyed-hashMACalgorithm.
|| HMACVER Variable-lengthHMACverificationkey.UsethiskeytoverifyaMessageAuthenticationCode
| usingthekeyed-hashMACalgorithm.
| IKEYXLAT UsedtodecryptaninputkeyintheKeyTranslateandKeyTranslate2verbs.Thisisa
| double-lengthkey.
IMPORTER Importerkey-encryptingkey.Usethisdouble-lengthkeytoconvertakeyfromimportableform
intooperationalform.
|| IMP-PKA Double-lengthlimited-authorityimporterkeyusedtoencryptPKAprivatekeyvaluesinPKA
| externaltokens.
IPINENC Double-lengthinputPIN-encryptingkey.PINblocksreceivedfromothernodesorautomaticteller
machine(ATM)terminalsareencryptedunderthistypeofkey.TheseencryptedPINblocksare
theinputtotheEncryptedPINTranslate,EncryptedPINVerify,andClearPINGenerate
Alternateverbs.
KEYGENKY Usedtogenerateakeybasedonthekey-generatingkey.Thisisadouble-lengthkey.
MAC MACgenerationkey.Usethissingle-lengthkeytogenerateaMessageAuthenticationCode.
ThisisasingleordoublelengthkeyonaCEX3C.
MACVER MACverificationkey.Usethissingle-lengthkeytoverifyaMessageAuthenticationCode.
ThisisasingleordoublelengthkeyonCEX3C.
| OKEYXLAT UsedtoencryptanoutputkeyintheKeyTranslateandKeyTranslate2verbs.Thisisa
| double-lengthkey.
OPINENC OutputPIN-encryptingkey.Usethisdouble-lengthoutputkeytotranslatePINs.TheoutputPIN
blocksfromtheEncryptedPINTranslate,EncryptedPINGenerate,andClearPINGenerate
Alternateverbsareencryptedunderthistypeofkey.
PINGEN PINgenerationkey.Usethisdouble-lengthkeytogeneratePINs.
PINVER PINverificationkey.Usethisdouble-lengthkeytoverifyPINs.
SECMSG UsedtoencryptPINsorkeysinasecuremessage.Thisisadouble-lengthkey.
|| TOKEN Akeytokenthatmightcontainakey.
Table2 on page 29 lists key subtypes passed in the rule_array keyword.
28 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table2.Keysubtypesspecifiedbytherule_arraykeyword
rule_array
keyword Description
AMEX-CSC AMACkeythatcanbeusedfortheAMEXCSCtransactionvalidationprocessMACcalculation
method,usedwiththeTransactionValidation(CSNBTRV)verb.
ANSIX9.9 AMACkeythatcanbeusedfortheANSIX9.9MACcalculationmethod,eitherforMAC
Generate(CSNBMGN),MACVerify(CSNBMVR),orTransactionValidation(CSNBTRV).Other
ControlVectorbitscouldlimittheseusages.
ANY Key-encryptingkeysthathaveacontrolvectorwiththisattributecanbeusedtotransportany
typeofkey.Themeaningofthiskeywordhasbeendiscontinued,anditsusageisallowedfor
backwardcompatibilityreasonsonly.
ANY-MAC CanbeusedwithanyfunctionorMACcalculationmethodthatusesaMACkey,suchasMAC
Generate(CSNBMGN),MACVerify(CSNBMVR),orTransactionValidation(CSNBTRV).Thisis
thedefaultconfigurationforaMACkeycontrolvector.
CVVKEY-A Canbeusedas'KeyA'ineithertheCVVGenerate(CSNBCSG)orCVVVerify(CSNBCSV)
verbs,ascontrolledbytheCVVgenerationandverificationControlVectorbits(bits20and21
respectively).
CVVKEY-B Canbeusedas'KeyB'ineithertheCVVGenerate(CSNBCSG)orCVVVerify(CSNBCSV)
verbs,ascontrolledbytheCVVgenerationandverificationControlVectorbits(bits20and21
respectively).
DATA Dataencryptingkey.Usethis8-byte,16-byteor24-byteDESkeyor16-byte,24-byteor32-byte
AESkeytoencipheranddecipherdata.
EPINGENA Legacykeysubtype,usedtoturnonbit19ofaPINGeneratingKeyControlVector.Thedefault
PINGeneratingKeytypewillhavethisbiton.NoPINgeneratingorprocessingbehavioris
currentlyinfluencedbythiskeysubtypeparameter.EPINGENAisnolongersupported,although
thebitretainsthisdefinitionforcompatibilityThereisnoEncryptedPinGenerateAlternateverb
LMTD-KEK Key-encryptingkeysthathaveacontrolvectorwiththisattributeformerlycouldonlybeusedto
exchangekeyswithkey-encryptingkeysthatcarryNOT-KEK,PIN,orDATAkey-typeciphering
restrictions.Theusageofthiskeywordhasbeendiscontinuedanditsusageisallowedfor
backwardcompatibilityreasonsonly.
NOT-KEK Key-encryptingkeysthathaveacontrolvectorwiththisattributeformerlycouldnotbeusedto
transportkey-encryptingkeys.Themeaningofthiskeywordhasbeendiscontinuedandits
usageisallowedforbackwardcompatibilityreasonsonly.
PIN Key-encryptingkeysthathaveacontrolvectorwiththisattributeformerlycouldonlybeusedto
transportkeyswithakeytypeofPINVER,IPINENC,andOPINENC.Theusageofthiskeyword
hasbeendiscontinuedanditsusageisallowedforbackwardcompatibilityreasonsonly.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 29

├─Key Type─┤├─Key Subtype─┤├─Key Usage──────────────────────────────────────────────────────────────────────┤
(cid:6)(cid:6)┬─MAC ─────┐ Note: ANY is default
├─MACVER───┴────────────────┬─────────┐
├─DATA─────┐ ├─ANY─────┤
├─CIPHER───┤ ├─ANSIX9.9┤
├─ENCIPHER─┤ ├─CVVKEY─A┤
├─DECIPHER─┤ ├─CVVKEY─B┤
├─CVARENC──┤ └─AMEX─CSC┴────────────┐ Note: SINGLE
├─CVARXCVL─┤ │ is default
├─CVARXCVR─┴───────────────────────────────────────┴─────────────────────┬──────────┐
│ Note: DKYL0 Note: DMAC ├─SINGLE───┤
│ is default is default ├─KEYLN8───┤
├─DKYGENKY──┬─────────┐ ┌──┬─────────┐ ├─DOUBLE───┤
│ ├─DKYL0───┤ │ ├─DMAC────┤ ├─KEYLN16──┤
│ ├─DKYL1───┤ │ ├─DDATA───┤ └─MIXED────┴─┐
│ ├─DKYL2───┤ │ ├─DMV─────┤ │
│ ├─DKYL3───┤ │ ├─DIMP────┤ │
│ ├─DKYL4───┤ │ ├─DEXP────┤ │
│ ├─DKYL5───┤ │ ├─DPVR────┤ │
│ ├─DKYL6───┤ │ ├─DMKEY───┤ │
│ └─DKYL7───┴──┘ ├─DMPIN───┤ │
│ └─DALL────┴───────────────────────────────────┐ │
├─SECMSG────────────────────┬─SMKEY───┐ │ │
├─DATAC────┐ └─SMPIN───┴───────────────────────────────────┤ │
├─DATAM────┤ │ │
├─DATAMV───┴──────────────────────────────────────────────────────────────┤ │
├─KEYGENKY──────────────────┬─CLR8─ENC────────────────────────────────────┤ │
├─IKEYXLAT─┐ └─UKPT────────────────────────────────────────┤ │
├─OKEYXLAT─┴─────────────────────────────────────────────────┐ │ │
├─IMPORTER───────────────┬────Note 1────┐ │ │ │
│ │ ┌──────────┐ │ │ │ │
│ │ (cid:14) │ │ │ │ │
│ └──┬─OPIM────┤ │ │ │ │
│ ├─IMEX────┤ │ │ │ │
│ ├─IMIM────┤ │ │ │ │
│ └─IMPORT──┴─┤ │ │ │
├─EXPORTER───────────────┬────Note 1────┤ │ │ │
│ │ ┌──────────┐ │ │ │ │
│ │ (cid:14) │ │ │ │ │
│ └──┬─OPEX────┤ │ │ │ │
│ ├─IMEX────┤ │ │ │ │
│ ├─EXEX────┤ │ │ │ │
│ └─EXPORT──┴─┴─────────┬────────┐ │ Note: ANY │ │
│ └─XLATE──┴─┤ is default │ │
├─PINVER─────────────────────────────────────────┐ ├──────────┐ │ │
├─PINGEN─────────────────┬────Note 1────┐ │ ├─ANY──────┤ │ │
│ │ ┌──────────┐ │ │ ├─NOT─KEK──┤ │ │
│ │ (cid:14) │ │ │ ├─DATA─────┤ │ │
│ └──┬─CPINGEN─┤ │ │ ├─PIN──────┤ │ │
│ ├─CPINGENA┤ │ │ └─LMTD─KEK─┴─┤ │
│ ├─EPINGEN─┤ │ │ │ │
│ └─EPINVER─┴─┴────────┤ │ │
├─IPINENC────────────────┬────Note 1─────┐ │ Note: NO─SPEC │ │
│ │ ┌───────────┐ │ │ is default │ │
│ │ (cid:14) │ │ ├──────────┐ │ │
│ └──┬─CPINGENA─┤ │ ├─NO─SPEC──┤ │ │
│ ├─EPINVER──┤ │ ├─IBM─PIN──┤ │ │
│ ├─REFORMAT─┤ │ ├─GBP─PIN──┴──┬──────────┤ │
│ └─TRANSLAT─┴─┴───┐ ├─IBM─PINO─┐ └─NOOFFSET─┤ │
└─OPINENC────────────────┬────Note 1─────┐ │ ├─GBP─PINO─┤ │ │
│ ┌───────────┐ │ │ ├─VISA─PVV─┤ │ │
│ (cid:14) │ │ │ └─INBK─PIN─┴─────────────┤ │
└──┬─CPINENC──┤ │ │ │ Note: │
├─EPINGEN──┤ │ │ │ DOUBLE │
├─REFORMAT─┤ │ │ │ is default│
└─TRANSLAT─┴─┴───┴────────────────────────────┼──────────┐│
├─DOUBLE───┤│
Note 1: All keywords in the list below are ├─KEYLN16──┤│ Note: XPORT─OK
defaults unless one or more keywords └─MIXED────┴┤ is default
in the list are specified. ├──────────┐
├─XPORT─OK─┤
└─NO─XPORT─┴┬──────────┐
└─KEY─PART─┴─(cid:6)(cid:6)
Figure3.ControlVectorGenerateandKeyTokenBuildCVkeywordcombinations
Clear keys
Aclear key is the base value of a key, and is not encrypted under another key. Encrypted keys are keys
whose base value has been encrypted under another key.
30 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

To convert a clear key to an encrypted data key in operational form, use either the Clear Key Import verb
or the Multiple Clear Key Import verb.
Multi-coprocessor capabilities
Multi-coprocessor capabilities allow you to employ more than one coprocessor. When more than one
coprocessor with CCAis 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 ResourceAllocate verb. This verb allocates a coprocessor loaded with
the CCAsoftware. When a coprocessor is allocated, CCArequests 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, use the Cryptographic Facility Query verb with the STATCARD rule_array keyword.
The verb returns the number of coprocessors running CCAsoftware, which includes any coprocessors
loaded with CCAuser defined function (UDX) code.
To determine if a card is a CEX2C or CEX3C, use one of these methods:
v Invoke the Cryptographic Facility Query verb (see “Determining if a card is a CEX2C or CEX3C” on
page 58).
v Use the sysfs interface, the hwtype attribute (see “The sysfs interface” on page 538).
| v Run panel.exe -x using the panel.exe utility installed with the RPM, to get a quick summary of cards
| available and their status. See “The panel.exe utility” on page 553.
| v Run ivp.e, another utility installed with the RPM, which gives more detailed information about each card
| available. SeeAppendixL, “Utilities,” on page 553.
With the first call to CCAfrom a process, CCAassociates 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.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 CCAapplication.As each coprocessor is evaluated, the CCAhost associates the
identifiers CRP01, CRP02, and so forth to the coprocessors with CCA. Coprocessors loaded with a UDX
extension to CCAare also assigned a CRPnn identifier.
| For a specific device driver, names such as these are used: CRPnn, cardnn,APnn, and so forth, where
| the nn values normally do not match (some start with 0, others 1, for example).
You can alter the default designation by explicitly setting the CSU_DEFAULT_ADAPTER environment
variable. This is accomplished by issuing following command:
export CSU_DEFAULT_ADAPTER=CRPxx
Replace CRPxx with the identifier for the resource you wish to use, such as CRP02.
The selection of a default device occurs with the first CCAcall to a coprocessor. When the default device
is selected, it 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 de-allocating the coprocessor, excess memory
consumption results. It is not necessary to deallocate a cryptographic resource if the process itself ends; it
is suggested only if individual threads end while the process continues to run.
When CEX2C and CEX3C cards are active in the same system, take note of these points:
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 31

v The CCAlibrary will detect CEX2C and CEX3C adapters and intermingle them in the CRPnn adapter
instance list. This is a list of all available adapters, in the order that they were discovered by the device
driver.
v The default adapter will be the lowest numbered CEX3C instance found by the device driver.
v Auser can specify the proper 'CRPnn' number to allocate and work with any card however, CEX2C or
CEX3C.
| v For a specific device driver, names such as these are used: CRPnn, cardnn,APnn, and so forth, where
| the nn values normally do not match (some start with 0, others 1, for example).
Note: The scope of the Cryptographic ResourceAllocate and the Cryptographic Resource Deallocate
verbs is to a thread.Amultithreaded application program can use all of the installed CCA
coprocessors simultaneously.Aprogram 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 ResourceAllocate verb fails if
a cryptographic resource is already allocated.
Note that the mapping of logical card identifiers such as CRP01 and CRP02 to physical cards in your
machine is not defined. This is because the mapping can change depending on the machine and its
configuration. If your application needs to identify specific coprocessor cards, you can do one of the
following:
v Use the Cryptographic Facility Query verb (see “Cryptographic Facility Query (CSUACFQ)” on page 58)
with the STATCARD rule_array keyword
v Use the panel.exe utility program with option -x, in order to read a card's serial number (see “The
panel.exe utility” on page 553).
To determine if a card is a CEX2C or CEX3C, use one of these methods:
v Invoke the Cryptographic Facility Query verb (see “Determining if a card is a CEX2C or CEX3C” on
page 58).
v Use the sysfs interface, the hwtype attribute (see “The sysfs interface” on page 538).
| v Run panel.exe -x using the panel.exe utility installed with the RPM, to get a quick summary of cards
| available and their status. See “The panel.exe utility” on page 553.
| v Run ivp.e, another utility installed with the RPM, which gives more detailed information about each card
| available. SeeAppendixL, “Utilities,” on page 553.
Using the CCA node and master key management verbs
The following verbs are used for the CCAnode and master key management functions:
v Cryptographic Facility Query (CSUACFQ)
v Cryptographic Facility Version (CSUACFV)
v Cryptographic ResourceAllocate (CSUACRA)
v Cryptographic Resource Deallocate (CSUACRD)
v Cryptographic Variable Encipher (CSNBCVE)
v Data Key Export (CSNBDKX)
v Data Key Import (CSNBDKM)
v Diversified Key Generate (CSNBDKG)
v Key Export (CSNBKEX)
v Key Generate (CSNBKGN)
v Key Import (CSNBKIM)
v Key Part Import (CSNBKPI)
32 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

v Key Storage Initialization (CSNBKSI)
v Key Test (CSNBKYT)
v Key Test Extended (CSNBKYTX)
v Key Token Build (CSNBKTB)
v Key Token Change (CSNBKTC)
v Key Token Parse (CSNBKTP)
v Key Translate (CSNBKTR)
v Master Key Process (CSNBMKP)
v Multiple Clear Key Import (CSNBCKM)
v Prohibit Export (CSNBPEX)
v Prohibit Export Extended (CSNBPEXX)
v Random Number Generate (CSNBRNG)
v Random Number Generate Long (CSNBRNGL)
v Random Number Tests (CSUARNT)
v Symmetric Key Export (CSNDSYX)
v Symmetric Key Generate (CSNDSYG)
v Symmetric Key Import (CSNDSYI)
v Symmetric Key Import2 (CSNDSYI2)
Verbs for managing AES and DES key storage files
| CCAprovidesAPI functions to allow application programs to manage theAES and DES key storage file,
| where key tokens are stored when the program references them by key label name. The following verbs
| are used to manage theAES and DES key storage files:
| v AES Key Record Create (CSNBAKRC)
| v AES Key Record Delete (CSNBAKRD)
| v AES Key Record List (CSNBAKRL)
| v AES Key Record Read (CSNBAKRR)
| v AES Key Record Write (CSNBAKRW)
| v DES Key Record Create (CSNBKRC)
| v DES Key Record Delete (CSNBKRD)
| v DES Key Record List (CSNBKRL)
| v DES Key Record Read (CSNBKRR)
| v DES Key Record Write (CSNBKRW)
Verbs for managing the PKA key storage file and PKA keys in the
cryptographic engine
The PKAkey storage file is a repository for RSAkeys, similar to theAES and DES key storage files.An
application can store keys in the key storage file and refer to them by label when using any of the verbs
which accept RSAkey tokens as input. The following verbs are used to manage the PKAkey storage file,
or PKAkeys stored in the cryptographic engine:
v PKAKey Record Create (CSNDKRC)
v PKAKey Record Delete (CSNDKRD)
v PKAKey Record List (CSNDKRL)
v PKAKey Record Read (CSNDKRR)
v PKAKey Record Write (CSNDKRW)
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 33

v Retained Key Delete (CSNDRKD)
v Retained Key List (CSNDRKL)
Improved remote key distribution
|
| Note: This improved remote key distribute support is only available on the IBM z9® EC, z9 BC, z10™ EC
| and z10 BC servers.
| New methods have been added for securely transferring symmetric encryption keys to remote devices,
| such asAutomated Teller Machines (ATMs), PIN-entry devices, and point of sale terminals. These
| methods can also be used to transfer symmetric 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 replaces expensive human operations with network transactions that can be processed quickly and
| inexpensively. This method makes significant interoperability improvements to related cryptographic
| key-management functions.
| For the purposes of this description, theATM scenario will be used to illustrate operation of the new
| methods. Other uses of this method are also possible.
Remote key loading
|
| Remote key loading is the process of installing symmetric 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.AKEK is a type of
| symmetric encryption key that is used to encrypt other keys so that they can be securely transmitted
| over unprotected paths.
| v Distribution of operational keys or replacement KEKs, enciphered under a KEK currently installed in the
| device.
| Access control points are assigned to roles to control keyword usage in the services provided forATM
| remote key loading. Table3 lists the access control points used by theATM remote key loading function.
|| Table3.AccessControlPointsUsedbyATMremotekeyloading
|||| Verbname Entrypoint Offset AccessControlPointnameandcomments
|||| TrustedBlockCreate CSNDTBC X'030F' TrustedBlockCreate-CreateaTrustedKeyBlockinInactive
| form
|||| TrustedBlockCreate CSNDTBC X'0310' TrustedBlockCreate-ActivateanInactiveTrustedKeyBlock
|||| PKAKeyImport CSNDPKI X'0311' PKAKeyImport-ImportanExternalTrustedKeyBlockto
| internalform
| ConvertTrustedBlockfromexternaltointernalformat
|||| PKAKeyImport CSNDPKI X'0104' PKAKeyImport
|||| RemoteKeyExport CSNDRKX X'0312' RemoteKeyExport-Generateorexportakeyforusebya
| non-CCAnode
|||| Key Generate CSNBKGN X''00DB' KeyGenerate-SINGLE-R
|| Remote Key Export CSNDRKX
| Replicationofasingle-lengthsourcekey(whichiseitheran
| RKXtokenoraCCAtoken)iftheoutputsymmetricencryption
| resultistobeaCCAtoken,andtheCVinthetrustedblock's
| CommonExportKeyParametersTLVObjectis16byteswith
| keyformbits'fff'settoX''010'forthelefthalfandX'001'for
| therighthalf.
34 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| Table3.AccessControlPointsUsedbyATMremotekeyloading (continued)
|||| Verbname Entrypoint Offset AccessControlPointnameandcomments
|||| KeyImport CSNBKIM X'027B' KeyImport-Unrestricted
| Theimporterkeyidentifierintheinitialcodereleasemust
| haveuniquehalves.
|||| KeyExport CSNBKEX X''0276' KeyExport-Unrestricted
| Thetransportkeyidentifierintheinitialcodereleasemust
| haveuniquehalves.
|
| Old remote key loading example
| Use anATM as an example of the remote key loading process.AnewATM has none of the purchaser's
| keys installed when it is delivered from the manufacturer. The process of getting the first key securely
| loaded is difficult.
| The installation of the first key on theATM has typically been done by loading the first KEK into eachATM
| manually, in multiple cleartext key parts. Using dual control for key parts, two separate people must carry
| key part values to theATM, then load each key part manually.After they are inside theATM, 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.
| 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, initial KEKs can be loaded 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 provide new methods for the creation and use of the special key forms
| needed for remote key distribution of this type. In addition, the new cryptographic features provide ways to
| solve long-standing barriers to secure key exchange with non-IBM cryptographic systems.
| After anATM is in operation, new keys can be installed as needed, by sending them enciphered under a
| KEK installed previously. This is straightforward in concept, but the cryptographic architecture inATMs is
| often different from that of the host system that is sending the keys, and it is difficult to export the keys in
| a form understood by theATM. 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 MessageAuthentication 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 prior to a key being 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.
| Adata 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. See “Trusted blocks” on page 444.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 35

Verbs that support Secure Sockets Layer (SSL)
The Secure Sockets Layer (SSL) protocol, developed by Netscape Development Corporation, provides
communications privacy over the Internet. Client/server applications can use the SSLprotocol to provide
secure communications and prevent eavesdropping, tampering, or message forgery.
CCAprovides verbs that support the RSA-encryption and RSA-decryption of PKCS 1.2-formatted
symmetric key data to produce symmetric session keys. These session keys can then be used to establish
an SSLsession between the sender and receiver. The verbs provide SSLsupport:
v PKADecrypt (CSNDPKD)
v PKAEncrypt (CSNDPKE)
Enciphering and deciphering data
Enciphering data protects it from disclosure to people who do not have authority to access it. Using
algorithms that make it difficult and expensive for an unauthorized user to derive the original clear data
within a practical time period assures privacy.
To protect data, CCAcan use the Data Encryption Standard (DES) orAdvanced Encryption Standard
(AES) algorithms to encipher or decipher data or keys. These verbs perform the enciphering and
deciphering functions:
v Decipher (CSNBDEC)
v Encipher (CSNBENC)
v SymmetricAlgorithm Decipher (CSNBSAD)
v SymmetricAlgorithm Encipher (CSNBSAE)
Managing data integrity and message authentication
To ensure the integrity of transmitted messages and stored data, CCAprovides:
v DES-based MessageAuthentication Code (MAC) functions
v Several hashing functions, including Modification Detection Code (MDC), SHA-1, RIPEMD-160 and MD5
See Chapter10, “Using digital signatures,” on page 359 for an alternate method of message authentication
using digital signatures.
The choice of verb depends on the security requirements of the environment in which you are operating. If
you need to ensure the authenticity of the sender and also the integrity of the data, consider Message
Authentication Code processing. If you need to ensure the integrity of transmitted data in an environment
where it is not possible for the sender and the receiver to share a secret cryptographic key, consider
hashing functions.
Message authentication code processing
The process of verifying the integrity and authenticity of transmitted messages is called message
authentication. Message authentication code (MAC) processing allows you to verify that a message was
not altered or a message was not fraudulently introduced onto the system. You can check that a message
you have received is the same one sent by the message originator. The message itself can be in clear or
encrypted form. The comparison is performed within the cryptographic coprocessor. Because both the
sender and receiver share a secret cryptographic key used in the MAC calculation, the MAC comparison
also ensures the authenticity of the message.
In a similar manner, MACs can be used to ensure the integrity of data stored on the system or on
removable media, such as tape.
36 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CCAkey typing makes it possible to give one party a key that can only be used to generate a MAC, and
to give another party a corresponding key that can only be used to verify the MAC. This ensures that the
second party cannot impersonate the first by generating MACs with their version of the key.
The coprocessor provides support for both single-length and double-length MAC generation and MAC
verification keys. With theANSI X9.9-1 single key algorithm, use the single-length MAC and MACVER
keys.
CCAprovides support for the use of data-encrypting keys in the MAC Generate and MAC Verify verbs,
and also the use of a MAC generation key in the MAC Verify verb. This support permits CCAMAC verbs
to interface more smoothly with non-CCAkey distribution system.
| HMAC codes are computed using the FIPS-198 Keyed-Hash MessageAuthentication Code method. See
| Chapter7, “Verifying data integrity and authenticating messages,” on page 233.
These verbs are used to process MACs:
v MAC Generate (CSNBMGN)
v MAC Verify (CSNBMVR)
Hashing functions
Hashing functions are provided by these verbs:
v MDC Generate (CSNBMDG)
v One-Way Hash (CSNBOWH)
Processing personal identification numbers
The process of validating personal identities in a financial transaction system is called personal
authentication. The personal identification number (PIN) is the basis for verifying the identity of a customer
across the financial industry networks. The financial industry needs functions to generate, translate, and
verify PINs. These functions prevent unauthorized disclosures when organizations handle personal
identification numbers.
The coprocessor supports the following algorithms for generating and verifying personal identification
numbers:
v IBM 3624
v IBM 3624 PIN offset
v IBM German Bank Pool
v IBM German Bank Pool PIN Offset (GBP-PINO)
v VISAPIN validation value
v Interbank
You can translate PIN blocks from one format to another without the PIN being exposed in cleartext form.
The coprocessor supports the following formats:
v ANSI X9.8
v ISO formats 0, 1, 2, 3
v VISAformats 1, 2, 3, 4
v IBM 4704 Encrypting PINPAD format
v IBM 3624 formats
v IBM 3621 formats
v ECI formats 1, 2, 3
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 37

With the capability to translate personal identification numbers into different PIN block formats, you can
use personal identification numbers on different systems.
Verifying credit card data
The Visa International ServiceAssociation (VISA) and MasterCard International, Incorporated have
specified a cryptographic method to calculate a value that relates to the personal account number (PAN),
the card expiration date, and the service code. The VISAcard-verification value (CVV) and the MasterCard
card-verification code (CVC) can be encoded on either track 1 or track 2 of a magnetic striped card and
are used to detect forged cards. Because most online transactions use track-2, the CCAverbs generate
and verify the CVV1 by the track-2 method.
The CVV Generate verb calculates a 1 - 5-byte value through the DES-encryption of the PAN, the card
expiration date, and the service code using two data-encrypting keys or two MAC keys. The CVV Verify
verb calculates the CVV by the same method, compares it to the CVV supplied by the application (which
reads the credit card's magnetic stripe) in the CVV_value, and issues a return code that indicates whether
the card is authentic.
The following verbs are used to process and verify credit card data:
v Clear PIN Encrypt (CSNBCPE)
v Clear PIN Generate (CSNBPGN)
v Clear PIN GenerateAlternate (CSNBCPA)
v CVV Generate (CSNBCSG)
v CVV Verify (CSNBCSV)
v Encrypted PIN Generate (CSNBEPG)
v Encrypted PIN Translate (CSNBPTR)
v Encrypted PIN Verify (CSNBPVR)
v PIN Change/Unblock (CSNBPCU)
v Transaction Validation (CSNBTRV)
Secure messaging
The following verbs will assist applications in encrypting secret information such as clear keys and PIN
blocks in a secure message. These verbs will execute within the secure boundary of the cryptographic
coprocessor:
v Secure Messaging for Keys (CSNBSKY)
v Secure Messaging for PINs (CSNBSPN)
Trusted Key Entry support
The Trusted Key Entry (TKE) workstation provides a secure method of initializing and administering
cryptographic coprocessors. It is an optional System z feature, but it is mandatory if z/OS and CCAare not
available on your system. Initialization of the coprocessor can be done through CCAfor both the z/OS and
Linux environments, either with or without TKE.
| TKE Version 6.0 or higher is required in order to administer the CEX3C coprocessor features. You can use
| the TKE workstation to load DES master keys, PKAmaster keys, and operational keys in a secure way.
| TKE Version 6.0 and 7.0 can also setAES master keys on the CEX3C coprocessor.
1.TheVISACVVandtheMasterCardCVCrefertothesamevalue.CVVisusedheretomeanbothCVVandCVC.
38 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

You can load keys remotely and for multiple coprocessors, which can be in a single machine or in multiple
machines. The TKE workstation eases the administration for using one coprocessor as a production
machine and as a test machine at the same time, while maintaining security and reliability.
The TKE workstation can be used for enabling and disabling access control points for verbs executed on
the cryptographic coprocessor. SeeAppendixG, “Access control points and verbs,” on page 515 for
additional information.
For complete details about the TKE workstation, see z/OS Cryptographic Services ICSF: Trusted Key
Entry PCIX Workstation User’s Guide.
Typical sequences of CCA verbs
Sample sequences in which the CCAverbs might be called are shown in Table4.
Table4.Combinationsoftheverbs
| Combination A (DATA keys only) Combination B
|
| 1. Random Number Generate 1. Random Number Generate
| 2. Clear Key Import or 2. Any Service
| Multiple Clear Key Import 3. Data Key Export for DATA keys, or
| 4. Data Key Export or Key Export Key Export in the general case
| (optional step) (optional step)
|
| Combination C Combination D
|
| 1. Key Generate (OP form only) 1. Key Generate (OPEX form)
| 2. Any service 2. Any service
| 3. Key Export (optional)
|
| Combination E Combination F
|
| 1. Key Generate (IM form only) 1. Key Generate (IMEX form)
| 2. Key Import 2. Key Import
| 3. Any service 3. Any service
| 4. Key Export (optional)
|
| Combination G Combination H
|
| 1. Key Generate 1. Key Import
| 2. AES or DES Key Record Create 2. AES or DES Key Record Create
| 3. AES or DES Key Record Write 3. AES or DES Key Record Write
| 4. Any service (passing label 4. Any service (passing label
| of the key just generated) of the key just generated)
Notes:
1. Anexampleof“anyservice”isCSNBENC.
2. Thesecombinationsexcludeverbsthatcanbeusedontheirown;forexample,KeyExportorencode,orusing
theKeyGenerateverbtogenerateanexportablekey.
3. Thesecombinationsdonotshowkeycommunication,orthetransmissionofanyoutputfromanCCAverb.
| The key forms are described inAppendixC, “Key forms and types used in the Key Generate verb,” on
| page 459 and “Key Generate (CSNBKGN)” on page 120.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 39

Summary of the CCA nodes and resource control verbs
|
Table5 lists the CCAnodes and resource control verbs described in this document. The table also
references the chapter that describes the verb.
Table5.SummaryofCCAnodesandresourcecontrolverbs
Entrypoint Verbname Description Page
Chapter4,“UsingtheCCAnodesandresourcecontrolverbs,”onpage57
CSUACFQ CryptographicFacilityQuery Retrievesinformationaboutthecoprocessorand 58
theCCAapplicationprograminthatcoprocessor.
CSUACFV CryptographicFacilityVersion RetrievetheSecurityApplicationProgramInterface 84
(SAPI)versionandbuilddate.
CSUACRA CryptographicResource AllocatesspecificCCAcoprocessorforusebythe 86
Allocate threadorprocess,dependingonthescopeofthe
verb.
CSUACRD CryptographicResource De-allocatesaspecificCCAcoprocessorthatis 88
Deallocate allocatedbythethreadorprocess,dependingon
thescopeoftheverb.
| CSNBKSI KeyStorageInitialization Thisverbinitializesakey-storagefileusingthe 90
| currentsymmetricorasymmetricmaster-key.The
| initializedkeystoragedoesnotcontainany
| preexistingkeyrecords.Thenameandpathofthe
| keystoragedataandindexfileareestablished
| differentlyineachoperatingenvironment.Notethat
| HMACkeysarenotsupportedforkeystorage.
CSNBMKP MasterKeyProcess Operatesonthethreemaster-keyregisters:new, 93
current,andold.
Thisverbisusedtoclearthenewandtheold
master-keyregisters,generatearandom
master-keyvalueinthenewmaster-keyregister,
XORaclearvalueasakeypartintothenew
master-keyregister,andsetthemasterkey,which
transfersthecurrentmaster-keytotheold
master-keyregisterandthenewmaster-keytothe
currentmaster-keyregister.
CSUARNT RandomNumberTests InvokestheUSANISTFIPSPUB140-1specified 97
cryptographicoperationaltests.Thesetests,
selectedbyarule_arraykeyword,consistof
known-answertestsofDES,RSA,andSHA-1
processesand,forrandomnumbers,monobittest,
pokertest,runstest,andlog-runtest.
Summary of the AES, DES, and HMAC verbs
Hash MessageAuthentication Code (HMAC) support was added in CCARelease 4.1.0.All of the HMAC
verbs and features described in this chapter require CCA4.1.0 in order to run.
Table6 lists theAES, DES, and HMAC verbs described in this document. The table also references the
chapter that describes the verb.
Table6.SummaryofCCAAES,DES,andHMACverbs
Entrypoint Verbname Description Page
Chapter5,“ManagingAESandDEScryptographickeys,”onpage99
40 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table6.SummaryofCCAAES,DES,andHMACverbs (continued)
Entrypoint Verbname Description Page
CSNBCKI ClearKeyImport Importsan8-byteclearDATAkey,enciphersit 100
underthemasterkey,andplacestheresultintoan
internalkeytoken.Thisverbconvertstheclearkey
intooperationalformasaDATAkey.
CSNBCVG ControlVectorGenerate Buildsacontrolvectorfromkeywordsspecifiedby 102
thekey_typeandrule_arrayparameters.
CSNBCVT ControlVectorTranslate Changesthecontrolvectorusedtoencipheran 104
externalDESkey.
CSNBCVE CryptographicVariable EncryptsplaintextusingaCVARENCkeyto 107
Encipher produceciphertextusingtheCipherBlockChaining
(CBC)method.
CSNBDKX DataKeyExport Re-enciphersaDATAkeyfromencryptionunder 109
themasterkeytoencryptionunderanexporter
key-encryptingkey,makingitsuitableforexportto
anothersystem.
CSNBDKM DataKeyImport ImportsanencryptedsourceDESsingle-or 111
double-lengthDATAkeyandcreatesorupdatesa
targetinternalkeytokenwiththemasterkey
encipheredsourcekey.
CSNBDKG DiversifiedKeyGenerate Generatesakeybaseduponthekey-generating 113
key,theprocessingmethod,andtheparameter
datathatissupplied.Thecontrolvectorofthe
key-generatingkeyalsodeterminesthetypeof
targetkeythatcanbegenerated.
CSNBKEX KeyExport Re-enciphersakeyfromencryptionundera 117
masterkeyvarianttoencryptionunderthesame
variantofanexporterkey-encryptingkey,makingit
suitableforexporttoanothersystem.
| CSNBKGN KeyGenerate Generatesa64-bit,128-bit,192-bit,or256-bitodd 120
paritykey,orapairofkeys;andreturnsthemin
encryptedforms(operational,exportable,or
importable).KeyGeneratedoesnotproducekeys
inplaintext.
|||| CSNBKGN2 KeyGenerate2 GenerateseitheroneortwoHMACkeys.Thisverb 128
| doesnotproducekeysinclearformandallkeys
| arereturnedinencryptedform.Whentwokeysare
| generated,eachkeyhasthesameclearvalue,
| althoughthisclearvalueisnotexposedoutside
| thesecurecryptographicfeature.
| Thisverbreturnsvariable-lengthCCAkeytokens
| andusestheAESKWwrappingmethod.
| OperationalkeyswillbeencryptedundertheAES
| masterkey.
CSNBKIM KeyImport Re-enciphersakeyfromencryptionunderan 133
importerkey-encryptingkeytoencryptionunder
themasterkey.There-encipheredkeyisinthe
operationalform.
CSNBKPI KeyPartImport Combinestheclearkeypartsofanykeytypeand 136
returnsthecombinedkeyvalueinaninternalkey
tokenoranupdatetotheCCAkeystoragefile.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 41

Table6.SummaryofCCAAES,DES,andHMACverbs (continued)
Entrypoint Verbname Description Page
|||| CSNBKPI2 KeyPartImport2 CombinestheclearkeypartsofanyHMACkey 139
| typefromaninternalvariable-lengthsymmetric
| key-token,andreturnsthecombinedkeyvaluein
| aninternalvariable-lengthsymmetrickey-tokenor
| anupdatetotheCCAkeystoragefile.
CSNBKYT KeyTest Generatesorverifies(dependingonkeywordsin 143
therule_array)asecureverificationpatternfor
keys.Thisverbrequiresthetestedkeytobeinthe
clearorencryptedunderthemasterkey.
|||| CSNBKYT2 KeyTest2 Generatesorverifies(dependingonkeywordsin 147
| therule_array)asecurecryptographicverification
| patternforkeyscontainedinavariable-length
| symmetrickey-token.Thekeytotestcanbeinthe
| clearorencryptedunderamasterkey.Requires
| thetestedkeytobeintheclearorencrypted
| underthemasterkey.
CSNBKYTX KeyTestExtended ThisverbisessentiallythesameasKeyTest, 150
exceptforthefollowing:
v Inadditiontooperatingoninternalkeysandkey
parts,thisverbalsooperatesonexternalkeys
andkeyparts.
v Thisverbdoesnotoperateonclearkeys,and
doesnotacceptrule_arraykeywordsCLR-A128,
CLR-A192,CLR-A256,KEY-CLR,and
KEY-CLRD.
CSNBKTB KeyTokenBuild Buildsaninternalorexternaltokenfromthe 155
suppliedparameters.Youcanusethisverbtobuild
CCAkeytokensforallkeytypesthatCCA
supports.Theresultingtokencanbeusedasinput
totheKeyGenerate,andKeyPartImportverbs.
|||| CSNBKTB2 KeyTokenBuild2 Buildsvariable-lengthinternalorexternalkey 159
| tokensforallkeytypesthatthecoprocessor
| supports.Thekeytokenisbuiltbasedon
| parametersthatyousupply.Theresultingtoken
| canbeusedasinputtotheKeyGenerate2,and
| KeyPartImport2verbs.Aclearkeytokenbuiltby
| thisverbcanbeusedasinputtotheKeyTest2
| verb.
| ThisverbsupportsinternalHMACtokens,bothas
| clearkeytokensandasskeletontokenscontaining
| nokey.
CSNBKTC KeyTokenChange Re-enciphersaDESkeyfromencryptionunderthe 163
oldmasterkeytoencryptionunderthecurrent
masterkey,andtoupdatethekeysininternalDES
key-tokens.
|||| CSNBKTC2 KeyTokenChange2 Re-enciphersavariable-lengthHMACkeyfrom 166
| encryptionundertheoldmasterkeytoencryption
| underthecurrentmasterkey.Thisverbalso
| updatesthekeysininternalHMACkey-tokens.
CSNBKTP KeyTokenParse Disassemblesakeytokenintoseparatepiecesof 169
information.Thisverbcandisassembleanexternal
key-tokenoraninternalkey-tokeninapplication
storage.
42 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table6.SummaryofCCAAES,DES,andHMACverbs (continued)
Entrypoint Verbname Description Page
CSNBKTR KeyTranslate Usesonekey-encryptingkeytodecipheraninput 173
keyandthenenciphersthiskeyusinganother
key-encryptingkeywithinthesecureenvironment.
|||| CSNBKTR2 KeyTranslate2 Usesonekey-encryptingkeytodecipheraninput 175
| keyandthenenciphersthiskeyusinganother
| key-encryptingkeywithinthesecureenvironment.
| ThisverbdiffersfromtheKeyTranslateverbin
| thatKeyTranslate2canprocessbothfixed-length
| andvariable-lengthsymmetrickeytokens.
CSNBCKM MultipleClearKeyImport Importsasingle-length,double-length,or 179
triple-lengthclearDATAkeythatisusedto
encipherordecipherdata.Itacceptsaclearkey
andenciphersthekeyunderthehostmasterkey,
returninganencryptedDATAkeyinoperational
forminaninternalkeytoken.
CSNDPKD PKADecrypt UsesanRSAprivatekeytodecryptthe 182
RSA-encryptedkeyvalueandreturntheclearkey
valuetotheapplication.
CSNDPKE PKAEncrypt EncryptsasuppliedclearkeyvalueunderanRSA 185
publickey.Thesuppliedkeycanbeformatted
usingthePKCS1.2orZERO-PADmethodsprior
toencryption.
CSNBPEX ProhibitExport ModifiesthecontrolvectorofaCCAkeytokenso 188
thatthekeycannotbeexported.Thisverb
operatesonlyoninternalkeytokens.
CSNBPEXX ProhibitExportExtended ModifiesanexternalDESkey-tokensothatthe 189
keycannolongerbeexportedafterithasbeen
imported.Thisverboperatesonlyoninternalkey
tokens.
CSNBRNG RandomNumberGenerate Generatesan8-bytecryptographic-qualityrandom 191
numbersuitableforuseasanencryptionkeyorfor
otherpurposes.Theoutputcanbespecifiedin
threeformsofparity:RANDOM,ODD,andEVEN.
CSNBRNGL RandomNumberGenerate Generatesacryptographic-qualityrandomnumber 193
Long suitableforuseasanencryptionkeyorforother
purposes,rangingfrom1-8192bytesinlength.
Theoutputcanbespecifiedinthreeformsof
parity:RANDOM,ODD,andEVEN.
|||| CSNBRKA RestrictKeyAttribute Modifiesanoperationalvariable-lengthkeysothat 195
| itcannotbeexported.
|||| CSNDSYX SymmetricKeyExport Transferanapplication-suppliedsymmetrickey(a 198
| DATAkey)fromencryptionundertheAES,DESor
| HMACmasterkeytoencryptionunderan
| application-suppliedRSApublickey.The
| application-suppliedDATAkeymustbeanAES,
| DESorHMACinternalkeytoken,orthelabelof
| anAESorDESkeytokenintheCCAkeystorage
| file.TheSymmetricKeyImportandSymmetricKey
| Import2verbcanimportthePKA-encryptedkey
| formatthereceivingnode.SupportforHMACkey
| wasaddedbeginningwithCCA4.1.0.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 43

Table6.SummaryofCCAAES,DES,andHMACverbs (continued)
Entrypoint Verbname Description Page
|||| CSNDSYG SymmetricKeyGenerate Generateasymmetrickey(aDATAkey)andreturn 201
| thekeyintwoforms:DES-encryptedand
| encryptedunderanRSApublickey.The
| DES-encryptedkeycanbeaninternaltoken
| encryptedunderahostDESmasterkey,oran
| externalformencryptedunderaKEK.(Youcan
| usetheSymmetricKeyImportverbtoimportthe
| PKA-encryptedform.)
|||| CSNDSYI SymmetricKeyImport ImportasymmetricAESorDESDATAkey 205
| encipheredunderanRSApublickeyinto
| operationalformencipheredunderaDESmaster
| key.
|||| CSNDSYI2 SymmetricKeyImport2 UsethisverbtoimportanHMACkeythathas 208
| beenpreviouslyformattedandencipheredunder
| anRSApublickeybytheSymmetricKeyExport
| verb.TheformattedandRSA-encipheredkeyis
| containedinanexternalvariable-lengthsymmetric
| key-token.Thekeyisdecipheredusingthe
| associatedRSAprivate-key.TherecoveredHMAC
| keyisre-encipheredundertheAESmaster-key.
| There-encipheredkeyisthenreturnedinan
| internalvariable-lengthsymmetrickey-token.The
| keyalgorithmforthisverbisHMAC.
Chapter6,“Protectingdata,”onpage211
CSNBDEC Decipher Deciphersdatausingcipherblockchainingmode 213
ofDES.Theresultiscalledplaintext.
CSNBENC Encipher Enciphersdatausingthecipherblockchaining 217
modeofDES.Theresultiscalledciphertext.
CSNBSAD SymmetricAlgorithmDecipher DeciphersdatausingtheAEScipherblock 221
chainingmode.
CSNBSAE SymmetricAlgorithmEncipher EnciphersdatausingtheAEScipherblock 226
chainingmode
Chapter7,“Verifyingdataintegrityandauthenticatingmessages,”onpage233
CSNBHMG HMACGenerate Generatesakeyedhashmessageauthentication 235
code(HMAC)forthetextstringprovidedasinput.
SeeChapter7,“Verifyingdataintegrityand
authenticatingmessages,”onpage233.
CSNBHMV HMACVerify Verifiesakeyedhashmessageauthentication 238
code(HMAC)forthetextstringprovidedasinput.
SeeChapter7,“Verifyingdataintegrityand
authenticatingmessages,”onpage233.
CSNBMGN MACGenerate Generatesa4,6,or8-byteMessage 241
AuthenticationCode(MAC)foratextstringthat
theapplicationprogramsupplies.TheMACis
computedusingeithertheANSIX9.9-1algorithm
ortheANSIX9.19optionaldoublekeyalgorithm
andpaddingcouldbeappliedaccordingtothe
EMVspecification.
44 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table6.SummaryofCCAAES,DES,andHMACverbs (continued)
Entrypoint Verbname Description Page
CSNBMVR MACVerify Verifiesa4,6,or8-byteMessageAuthentication 245
Code(MAC)foratextstringthattheapplication
programsupplies.TheMACiscomputedusing
eithertheANSIX9.9-1algorithmortheANSIX9.19
optionaldoublekeyalgorithmandpaddingcould
beappliedaccordingtotheEMVspecification.The
computedMACiscomparedwithauser-supplied
MAC.
CSNBMDG MDCGenerate Createsa128-bithashvalue(Modification 249
DetectionCode)onadatastringwhoseintegrity
youintendtoconfirm.
CSNBOWH One-WayHash Generatesaone-wayhashonspecifiedtext. 258
Chapter9,“Financialservices,”onpage303
CSNBCPE ClearPINEncrypt FormatsaPINintoaPINblockformatand 312
encryptstheresults.Youcanalsousethisverbto
createanencryptedPINblockfortransmission.
WiththeRANDOMkeyword,youcanhavethe
verbgeneraterandomPINnumbers.
CSNBPGN ClearPINGenerate Generatesaclearpersonalidentificationnumber 315
(PIN),aPINverificationvalue(PVV),oranoffset
usingoneofthefollowingalgorithms:
v IBM3624(IBM-PINorIBM-PINO)
v IBMGermanBankPool(GBP-PINor
GBP-PINO)
v VISAPINvalidationvalue(VISA-PVV)
v InterbankPIN(INBK-PIN)
CSNBCPA ClearPINGenerateAlternate GeneratesaclearVISAPINvalidationvalue(PVV) 318
fromaninputencryptedPINblock.ThePINblock
mighthavebeenencryptedundereitheraninput
oroutputPINencryptingkey.TheIBM-PINO
algorithmissupportedtoproducea3624offset
fromacustomerselectedencryptedPIN.ThePIN
blockmustbeencryptedundereitheraninput
PIN-encryptingkey(IPINENC)oroutput
PIN-encryptingkey(OPINENC).
CSNBCSG CVVGenerate GeneratesaVISACardVerificationValue(CVV)or 322
aMasterCardCardVerificationCode(CVC)as
definedfortrack2.
CSNBCSV CVVVerify VerifiesaVISACardVerificationValue(CVV)ora 325
MasterCardCardVerificationCode(CVC)as
definedfortrack2.
CSNBEPG EncryptedPINGenerate GeneratesandformatsaPINandencryptsthePIN 328
block.
CSNBPTR EncryptedPINTranslate Re-enciphersaPINblockfromonePIN-encrypting 332
keytoanotherand,optionally,changesthePIN
blockformat.UKPTkeywordsaresupported.You
mustidentifytheinputPIN-encryptingkeythat
originallyenciphersthePIN.Youalsoneedto
specifytheoutputPIN-encryptingkeythatyou
wanttheverbtousetoencipherthePIN.Ifyou
wanttochangethePINblockformat,specifya
differentoutputPINblockformatfromtheinput
PINblockformat.
Chapter2.UsingAES,DES,andHMACcryptographyandverbs 45

Table6.SummaryofCCAAES,DES,andHMACverbs (continued)
Entrypoint Verbname Description Page
CSNBPVR EncryptedPINVerify VerifiesasuppliedPINusingoneofthefollowing 338
algorithms:
v IBM3624(IBM-PINorIBM-PINO)
v IBMGermanBankPool(GBP-PINor
GBP-PINO)
v VISAPINvalidationvalue(VISA-PVV)
v InterbankPIN(INBK-PIN)
UKPTkeywordsaresupported.
CSNBPCU PINChange/Unblock SupportsthePINchangealgorithmsspecifiedin 342
theVISAIntegratedCircuitCardSpecification;
availableonlyonanIBMz890orIBMz990with
May2004orlaterversionofLicensedInternal
Code(LIC).
CSNBSKY SecureMessagingforKeys Encryptsatextblock,includingaclearkeyvalue 348
decryptedfromaninternalorexternalDEStoken.
CSNBSPN SecureMessagingforPINs Encryptsatextblock,includingaclearPINblock 351
recoveredfromanencryptedPINblock.
CSNBTRV TransactionValidation SupportsthegenerationandvalidationofAmerican 355
Expresscardsecuritycodes;availableonlyonan
IBMz890orIBMz990withMay2004orlater
versionofLicensedInternalCode(LIC).
46 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 3. Introducing PKA cryptography and using PKA
verbs
The preceding chapters focused onAES or DES cryptography or secret-key cryptography. This
cryptography is symmetric (senders and receivers use the same key, which must be exchanged securely
in advance, to encipher and decipher data).
Public key cryptography does not require exchanging a secret key. It is asymmetric (the sender and
receiver each have a pair of keys, a public key and a different but corresponding private key).
| You can use PKAsupport to exchange symmetric algorithm secret keys securely, and to compute digital
| signatures for authenticating messages to users.
PKA key algorithms
|
| Public key cryptography uses a key pair consisting of a public key and a private key. The PKApublic key
| uses one of the following algorithms:
| Rivest-Shamir-Adleman (RSA)
| The RSAalgorithm is the most widely used and accepted of the public key algorithms. It uses three
| quantities to encrypt and decrypt text: a public exponent (PU), a private exponent (PR), and a
| modulus (M). Given these three and some cleartext data, the algorithm generates ciphertext as
| follows:
| ciphertext = cleartextPU (modulo M)
| Similarly, the following operation recovers cleartext from ciphertext:
| cleartext = ciphertextPR (modulo M)
| Elliptic Curve Digital SignatureAlgorithm (ECDSA)
| The ECDSAalgorithm uses elliptic curve cryptography (an encryption system based on the properties
| of elliptic curves) to provide a variant of the Digital SignatureAlgorithm.
PKA master keys
| On the PCI-X Cryptographic Coprocessor, CEX2C, or CEX3C, PKAkeys are protected by the
| Asymmetric-Keys Master Key (ASYM-MK). TheASYM-MK is a triple-length DES key used to protect PKA
| private keys. On the PCI-X Cryptographic Coprocessor, CEX2C and CEX3C, theASYM-MK protects RSA
| private keys.
| Starting with the IBM zEnterprise 196 configured with a CEX3C, there are two PKAmaster keys: the
| ASYM-MK mentioned above, and the 256-bitAES PKAMaster Key (APKA-MK), used to protect ECC
| private keys stored in ECC key tokens.
| In order for PKAverbs to function on the processor, the hash pattern of theASYM-MK must match the
| hash pattern of the SYM-MK on the Cryptographic Coprocessor Feature. The administrator installs the
| PKAmaster keys on the Cryptographic Coprocessor Feature and theASYM-MK on the coprocessor by
| using either the pass phrase initialization routine, the Clear Master Key Entry panels, or the optional
| Trusted Key Entry (TKE) workstation.
Operational private keys
| Operational private keys are protected under two layers of DES encryption. They are encrypted under an
| Object Protection Key (OPK) that in turn is encrypted under theASYM-MK. You dynamically generate the
| OPK for each private key at import time or when the private key is generated on a CEX2C or CEX3C.
| CCAprovides a public key storage file for the storage of application PKAkeys.Although you cannot
©CopyrightIBMCorp.2007,2011 47

| change PKAmaster keys dynamically, the PKAKey Token Change verb can be run to change a private
| PKAtoken (RSAor ECC) from encryption under the oldASYM-MK (orAPKA-MK) to encryption under the
| currentASYM-MK (orAPKA-MK). This verb requires a CEX2C or CEX3C.
PKA verbs
| The CEX2C provides RSAdigital signature functions, key management and key generation functions, DES
| key distribution functions, and data encryption functions, and application programming interfaces to these
| functions through verbs.
| The CEX3C running on the IBM System z10 model GA3 provides RSAand ECC digital signature
| functions, key management and key generation functions, DES key distribution functions, and data
| encryption functions, and application programming interfaces to these functions through verbs.
Verbs supporting digital signatures
CCAprovides the following verbs that support digital signatures:
v Digital Signature Generate (CSNDDSG)
v Digital Signature Verify (CSNDDSV)
Verbs for PKA key management
CCAprovides the following verbs for PKAkey management:
v PKAKey Generate (CSNDPKG)
v PKAKey Import (CSNDPKI)
v PKAKey Token Build (CSNDPKB)
v PKAKey Token Change (CSNDKTC)
v PKAKey Translate (CSNDPKT)
v PKAPublic Key Extract (CSNDPKX)
v Remote Key Export (CSNDRKX)
v Trusted Block Create (CSNDTBC)
PKA key tokens
| PKAkey tokens contain RSAor ECC private or public keys. PKAtokens are variable length because they
| contain either RSAor ECC key values, which are variable in length. Consequently, length parameters
| precede all PKAtoken parameters. The maximum allowed size is 3500 bytes. PKAkey tokens consist of a
| token header, any required sections, and any optional sections. Optional sections depend on the token
| type. PKAkey tokens can be public or private, and private key tokens can be internal or external.
| Therefore, there are three basic types of tokens, each of which can contain either RSAor ECC
| information:
| v Apublic key token
| v Aprivate external key token
| v Aprivate internal key token
| Public key tokens contain only the public key. Private key tokens contain the public and private key pair.
Table7 summarizes the sections in each type of token.
Table7.SummaryofPKAkeytokensections
Section Publicexternalkey Privateexternalkey Privateinternalkey
token token token
Header X X X
48 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table7.SummaryofPKAkeytokensections (continued)
Section Publicexternalkey Privateexternalkey Privateinternalkey
token token token
|||| RSAorECCprivatekeyinformation X X
|||| RSAorECCpublickeyinformation X X X
Keyname(optional) X X
Internalinformation X
As with DES key tokens, the first byte of a PKAkey token contains the token identifier which indicates the
type of token.
Afirst byte of X'1E' indicates an external token with a cleartext public key and optionally a private key that
is either in cleartext or enciphered by a transport key-encrypting key.An external key token is in importable
key form. It can be sent on the link.
Afirst byte of X'1F' indicates an internal token with a cleartext public key and a private key that is
enciphered by the PKAmaster key and ready for internal use.An internal key token is in operational key
form.APKAprivate key token must be in operational form for the coprocessor to use it. (PKApublic key
tokens are used directly in the external form.)
| Formats for public and private external and internal RSAand ECC key tokens begin in “RSApublic key
| token” on page 426.
PKA key management
You can generate RSAand ECC keys using the CCAPKAKey Generate verb.
v Using the Transaction Security System PKAKey Generate verb, or a comparable product from another
vendor.
Chapter3.IntroducingPKAcryptographyandusingPKAverbs 49

Encryptedexternal Clearkeyvalues Skeleton key token
keytokenfrom
otherCCAsystem
PKA KeyToken Build PKA Key Generate
Cleartext external
key token
Encryptedexternal
keytoken
PKA Key Import
Internal key token
Figure4.PKAkeymanagement
You can use the PKAKey Generate verb to generate internal and external PKAtokens. You can also
generate RSAkeys on another system and then import them to the cryptographic coprocessor. To input a
clear RSAkey, create the token with the PKAKey Token Build verb and import it using the PKAKey
Import verb. To input an encrypted RSAkey, use the PKAKey Import verb.
In either case, use the PKAKey Token Build verb to create a skeleton key token as input (see “PKAKey
Token Build (CSNDPKB)” on page 377).
The PKAKey Import verb uses the clear token from the PKAKey Token Build verb or a clear or encrypted
token from the CCAsystem to securely import the key token into operational form for the coprocessor to
use. CCAdoes not permit the export of the imported PKAkey.
The PKAPublic Key Extract verb builds a public key token from a private key token.
Application RSApublic and private keys can be stored in the PKAkey storage file.
Key identifier for PKA key token
Akey identifier for a PKAkey token is a variable length (maximum allowed size is 2500 bytes) area that
contains either a key label or a key token.
v Akey label identifies keys that are in the PKAkey storage file.
v Akey token can be either an internal key token, an external key token, or a null key token. Key tokens
are generated by an application (for example, using the PKAKey Generate verb), or received from
another system that can produce external key tokens.
50 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

An internal key token can be used only on the local system, because the PKAmaster key encrypts the
key value. Internal key tokens contain keys in operational form only.
An external key token can be exchanged with other systems because a transport key that is shared
with the other system encrypts the key value. External key tokens contain keys in either exportable or
importable form.
Anull key token consists of eight bytes of binary zeros. The PKAKey Record Create verb can be used
to write a null token to the key storage file. This record can subsequently be identified as the target
token for the PKAKey Import or PKAKey Generate verb.
The term key identifier is used when a parameter could be one of the above items, and indicates that
different inputs are possible. For example, you might want to specify a specific parameter as either an
internal key token or a key label. The key label is, in effect, an indirect reference to a stored internal key
token.
Key label
If the first byte of the key identifier is greater than X'20' but less than X'FF', the field is considered to be
holding a key label. The contents of a key label are interpreted as the identifier of a key entry in the PKA
storage file. The key label is an indirect reference to an internal key token.
If the first byte of the key identifier is X'FF', the identifier is not valid. If the first byte is less than X'20', the
identifier is treated as a key token as described below.
Akey label is specified on verbs with the key_identifier parameter as a 64-byte character string,
left-justified, and padded on the right with blanks. In most cases, the verb does not check the syntax of the
key label other than the first byte.
Akey label has the following form:
Offset Length Data
00-63 64 Keylabelname
Key token
| Akey token is a variable length (maximum allowed size is 3500 bytes) field composed of key value and
| control information. PKAkeys can be either public or private RSA, or ECC keys. Each key token can be
| either an internal key token (the first byte of the key identifier is X'1F'), an external key token (the first byte
| of the key identifier is X'1E'), or a null PKAprivate key token (the first byte of the key identifier is X'00').
SeeAppendixB, “Key token formats,” on page 421 for descriptions of the PKAkey tokens.
Internal key token
An internal key token is a token that can be used only on the system that created it or another system with
the same PKAmaster key. It contains a key that is encrypted under the PKAmaster key.
An application obtains an internal key token by using one of the verbs such as those listed below. The
verbs are described in detail in Chapter11, “Managing PKAcryptographic keys.”
v PKAKey Generate
v PKAKey Import
| The PKAKey Token Change verb can re-encipher private internal tokens from encryption under the old
| ASYM-MK to encryption under the currentASYM-MK. PKDS Reencipher/Activate options are available to
| re-encipher RSAand ECC internal tokens in the PKDS when the SYM-MK/ASYM-MK (orAPKA-MK) keys
| are changed.
Chapter3.IntroducingPKAcryptographyandusingPKAverbs 51

| PKAmaster keys cannot be changed dynamically.
For debugging information, seeAppendixB, “Key token formats” for the format of an internal key token.
External key token
If the first byte of the key identifier is X'1E', the key identifier is interpreted as an external key token.An
external PKAkey token contains key (possibly encrypted) and control information. By using the external
key token, you can exchange keys between systems.
An application obtains the external key token by using one of the verbs such as those listed below. They
are described in detail in Chapter11, “Managing PKAcryptographic keys.”
v PKAPublic Key Extract
v PKAKey Token Build
v PKAKey Generate
For debugging information, seeAppendixB, “Key token formats” for the format of an external key token.
Null key token
If the first byte of the key identifier is X'00', the key identifier is interpreted as a null key token.
For debugging information, seeAppendixB, “Key token formats” for the format of a null key token.
Summary of the PKA verbs
Table8 lists the PKAverbs, described in this book, and their corresponding verb names. The PKAverb
names start with CSND. This table also references the chapter that describes the verb.
Table8.SummaryofPKAverbs
Entrypoint Verbname Description Page
Chapter10,“Usingdigitalsignatures,”onpage359
|| CSNDDSG DigitalSignatureGenerate GeneratesadigitalsignatureusinganRSAor 360
| ECCprivatekey.
|| CSNDDSV DigitalSignatureVerify VerifiesadigitalsignatureusinganRSAorECC 364
| publickey.
Chapter11,“ManagingPKAcryptographickeys”
CSNDPKG PKAKeyGenerate GeneratesanRSAkeypair. 370
|| CSNDPKI PKAKeyImport Importsakeytokencontainingeitheraclearkey 374
| oranRSAorECCkeyencipheredundera
| transportkey.
CSNDPKB PKAKeyTokenBuild CreatesanexternalPKAkeytokencontaininga 377
clearprivateRSAkey.Usingthistokenasinputto
thePKAKeyImportverbreturnsanoperational
internaltokencontaininganencipheredprivate
key.UsingPKAKeyTokenBuildonaclearpublic
RSAkey,returnsthepublickeyinatokenformat
thatotherPKAverbscandirectlyuse.PKAKey
TokenBuildcanalsobeusedtocreateaskeleton
tokenforinputtothePKAKeyGenerateverbfor
thegenerationofaninternalRSAkeytoken.
CSNDKTC PKAKeyTokenChange ChangesPKAkeytokensfromenciphermentwith 385
theoldasymmetric-keysmasterkeyto
enciphermentwiththecurrentasymmetric-keys
masterkey.Thisverbchangesonlyprivateinternal
tokens.
52 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table8.SummaryofPKAverbs (continued)
Entrypoint Verbname Description Page
CSNDPKT PKAKeyTranslate TranslatesPKAkeytokensfromencipherment 388
undertheoldAsymmetric-KeysMasterKeyto
enciphermentunderthecurrentAsymmetric-Keys
MasterKey.ThisverbchangesonlyPrivate
InternalPKAKeyTokens.
CSNDPKX PKAPublicKeyExtract ExtractsaPKApublickeytokenfromasupplied 392
PKAinternalorexternalprivatekeytoken.
PerformsnocryptographicverificationofthePKA
privatetoken.
CSNDRKX RemoteKeyExport SecuretransportofDESkeysusingasymmetric 394
techniquesfromasecuritymodule(forexample,
theCEX3C)toaremotedevicesuchasan
AutomatedTellerMachine(ATM).
CSNDTBC TrustedBlockCreate Createsanexternaltrustedblockunderdual 403
control.AtrustedblockisanextensionofCCA
PKAkeytokensusingnewsectionidentifiers.
Chapter3.IntroducingPKAcryptographyandusingPKAverbs 53

54 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Part 2. CCA verbs
This part of the document introducesAES, DES and PKAverbs, and includes the following chapters:
| v Chapter4, “Using the CCAnodes and resource control verbs” describes using the CCAresource control
| verbs.
| v Chapter8, “Key storage mechanisms” describes the use of key storage, key tokens, and associated
| verbs.
| v Chapter5, “ManagingAES and DES cryptographic keys” describes the verbs for generating and
| maintainingAES, DES, and HMAC cryptographic keys, the Random Number Generate verb (which
| generates 8-byte random numbers), the Random Number Generate Long verb (which generates up to
| 8192 bytes of random content), and the Secure Sockets Layer (SSL) security protocol. This chapter
| also describes utilities to build DES andAES tokens, generate and translate control vectors, and
| describes the PKAverbs that support DES andAES key distribution.
| v Chapter6, “Protecting data” describes the verbs for enciphering and deciphering data.
| v Chapter7, “Verifying data integrity and authenticating messages” describes the verbs for generating and
| verifying MessageAuthentication Codes (MACs), generating Modification Detection Codes (MDCs) and
| generating hashes (SHA-1, MD5, RIPEMD-160).
| v Chapter9, “Financial services” describes the verbs for use in support of finance-industry applications.
| This includes several categories.
| – Verbs for generating, verifying, and translating personal identification numbers (PINS).
| – Verbs that generate and verify VISAcard verification values andAmerican Express card security
| codes.
| – Verbs to support smart card applications using the EMV (Europay MasterCard Visa) standards.
| v Chapter10, “Using digital signatures” describes the verbs that support using digital signatures to
| authenticate messages.
| v Chapter11, “Managing PKAcryptographic keys” describes the verbs that generate and manage PKA
| keys.
©CopyrightIBMCorp.2007,2011 55

56 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

|
Chapter 4. Using the CCA nodes and resource control verbs
This chapter describes the following verbs:
v “Cryptographic Facility Query (CSUACFQ)” on page 58
v “Cryptographic Facility Version (CSUACFV)” on page 84
v “Cryptographic ResourceAllocate (CSUACRA)” on page 86
v “Cryptographic Resource Deallocate (CSUACRD)” on page 88
v “Key Storage Initialization (CSNBKSI)” on page 90
v “Master Key Process (CSNBMKP)” on page 93
v “Random Number Tests (CSUARNT)” on page 97
©CopyrightIBMCorp.2007,2011 57

Cryptographic Facility Query (CSUACFQ)
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 CCAapplication
v The Environment Identifier (EID)
v Diagnostic information from the coprocessor
v Export-control information from the coprocessor
v Time and date information from the coprocessor
Determining if a card is a CEX2C or CEX3C
Using Cryptographic Facility Query, the output rule_array for option STATCCAis the most accurate way to
determine if you are using a CEX2C or CEX3C:
v If first two characters of the CCAapplication version field are 'z' followed by '3', then this card is a
CEX2C adapter.
An updated device driver might not be available yet for all distributions where this RPM is usable. The
CCAhost library uses this mechanism to determine card version, and we recommend here that the
application developer also use this method. Where this output and the device driver disagree about the
version of a particular card, it is the device driver that will be out of date because the Cryptographic
Facility Query data is not interpreted in any way; it comes direct from the adapter.
v If first character of the CCAapplication version field is a number, such as '4' or greater, then this card is
not a CEX2C. For example, a '4' in the first character indicates a CEX3C.
v The results of this query come directly from the card itself. If the host device driver is not up to date, it
could incorrectly identify a CEX3C as a CEX2C. Therefore, looking at the CCAapplication version field
for the output rule_array for option STATCCAresolves all questions.
The commands ivp.e and panel.exe -x will also tell you whether your cards are CEX3C or CEX2C, by
calling the Cryptographic Facility Query verb for all available adapters.
For details about panel.exe, see “The panel.exe utility” on page 553.
On input, you specify:
v Arule_array_count of 1 or 2
v Optionally, a rule_array keyword of ADAPTER1 (for backward compatibility)
v The class of information queried with a rule_array keyword
This verb returns information elements in the rule_array and sets the rule_array_count variable to the
number of returned elements.
Format
CSUACFQ(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
verb_data_length,
verb_data )
58 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
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 14.
rule_array_count
Direction: Input/Output Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. On input,
this 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 you
specified on input. Be sure you allocate adequate memory to receive all the information elements
according to the information class you select on input with the information-to-return keyword in
the rule_array.
rule_array
Direction: Input/Output Type:Array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters.
On input, set the rule_array to specify the type of information to retrieve. There are two input
rule_array elements, as described in Table9.
Table9.KeywordsforCryptographicFacilityQuerycontrolinformation
Keyword Description
Adaptertouse(Optional)
ADAPTER1 Thiskeywordisignored.Itisacceptedforbackwardcompatibility.
Informationtoreturn(Onerequired)
STATCCA ObtainsCCA-relatedstatusinformation.
STATCCAE ObtainsCCA-relatedextendedstatusinformation.
STATCARD Obtainscoprocessor-relatedbasicstatusinformation.
STATDIAG Obtainsdiagnosticinformation.
STATEID ObtainstheEnvironmentIdentifier(EID).
STATEXPT Obtainsfunctioncontrolvector-relatedstatusinformation.
TIMEDATE Readsthecurrentdate,time,anddayoftheweekfromthesecureclockwithinthe
coprocessor.
STATAES ObtainsstatusinformationonAESmaster-keyregistersandAESkey-lengthenablement.
STATMOFN Obtainsmaster-keysharesdistributioninformation.
|| STATAPKA ObtainsstatusinformationonAPKAmaster-keyregistersandAPKAkey-length
| enablement.
| ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAPMTHD Obtainsthedefaultkeywrappingmethod.
| ThiskeywordwasintroducedwithCCA4.1.0.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 59

Cryptographic Facility Query (CSUACFQ)
Table9.KeywordsforCryptographicFacilityQuerycontrolinformation (continued)
Keyword Description
QPENDING TKEusesthisrule_arraykeywordtorequestinformationaboutpendingchanges
previouslysubmittedbythisTKEoranotherTKEtothisadapter.OnlyTKEcansubmit
changestobestoredinthePendingChangeBufferqueriedwiththiscommand.
ThekeywordisavailablefornormalusersofCryptographicFacilityQuery,for
informationalordebuggingreasons(nosecretsareexposed).
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
STATICSF ThiskeywordreturnstheadapterserialnumberandstatusinformationabouttheSYM
(DES)andASYM(RSA)master-keyregisters,includingwhetheravalidkeyispresentin
eachoftheold,current,andnewregisters.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
GET-UDX ObtainsUDXidentifiers.See“GET-UDX”onpage73.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
STATKPRL Obtainsthenamesoftheoperationalkeyparts.See“STATKPRL”onpage73.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
STATKPR Obtainsnon-secretinformationaboutanoperationalkeypart.See“STATKPR”onpage
73.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
TKESTATE IndicateswhetherTKEaccessisenabledornot.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
STATICSX Obtainstheindicatedmasterkeyhashandverificationpatternstobereturnedforthe
masterkeysloadedinthecurrentdomain.See“STATICSX”onpage81.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
STATICSA Obtainstheindicatedmasterkeyhashandverificationpatternstobereturnedforthe
masterkeysloadedinthecurrentdomain.See“STATICSA”onpage74.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
STATICSE Obtainstheindicatedmasterkeyhashandverificationpatternstobereturnedforthe
masterkeysloadedinthecurrentdomain.See“STATICSE”onpage76.
ThiskeywordappliesonlywhenusingLinuxonIBMSystemz.
|| STATICSB Obtainstheindicatedmasterkeyhashandverificationpatternstobereturnedforthe
| masterkeysloadedinthecurrentdomain.See“STATICSB”onpage78.
| ThiskeywordwasintroducedwithCCA4.1.0.ThiskeywordappliesonlywhenusingLinux
| onIBMSystemz.
The format of the output rule_array depends on the value of the rule_array element, which identifies
the information to be returned. Different sets of rule_array elements are returned depending on
whether the input keyword is STATCCA, STATCCAE, STATCARD, STATDIAG, STATEID, STATEXPT,
STATMOFN, or TIMEDATE.
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 that contains the number 2 contains the character string “2 ” (the number 2 followed
by seven space characters).
On output, the rule_array elements can have the values shown in Table10 on page 61.
60 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array
Elementnumber Name Description
Outputrule_arrayforoptionSTATCCA
1 NMKstatus Thestateofthenewmaster-keyregister:
Value Description
1 Theregisterisclear.
2 Theregistercontainsapartiallycompletekey.
3 Theregistercontainsakey.
2 CMKstatus Thestateofthecurrentmaster-keyregister:
Value Description
1 Theregisterisclear.
2 Theregistercontainsakey.
3 OMKstatus Thestateoftheoldmaster-keyregister:
Value Description
1 Theregisterisclear.
2 Theregistercontainsakey.
4 CCAapplication AcharacterstringthatidentifiestheversionoftheCCAapplicationprogram
version runninginthecoprocessor.
Iffirsttwocharactersare'z'followedby'3',thenthiscardisaCEX2C
adapter(nomatterwhatdevicedriverindicates).
Iffirstcharacterisanumber,suchas'4'orgreater,thenthiscardisnota
CEX2C.Forexample,a'4'inthefirstcharacterindicatesaCEX3C.
Theresultsofthisquerycomedirectlyfromthecarditself.Ifthehostdevice
driverisnotuptodate,itcouldincorrectlyidentifyaCEX3CasaCEX2C.
Therefore,lookingatthisfieldresolvesallquestions.
5 CCAapplication AcharacterstringcontainingthebuilddatefortheCCAapplicationprogram
builddate runninginthecoprocessor.
6 Userrole Acharacterstringcontainingtheroleidentifierwhichdefinesthehost
applicationuser'scurrentauthority.
Outputrule_arrayforoptionSTATCCAE
1 SymmetricNMK Thestateofthesymmetricnewmaster-keyregister:
status
Value Description
1 Theregisterisclear.
2 Theregistercontainsapartiallycompletekey.
3 Theregistercontainsakey.
2 SymmetricCMK Thestateofthesymmetriccurrentmaster-keyregister:
status
Value Description
1 Theregisterisclear.
2 Theregistercontainsakey.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 61

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
3 SymmetricOMK Thestateofthesymmetricoldmaster-keyregister:
status
Value Description
1 Theregisterisclear.
2 Theregistercontainsakey.
4 CCAapplication AcharacterstringthatidentifiestheversionoftheCCAapplicationprogram
version thatisrunninginthecoprocessor.
5 CCAapplication AcharacterstringcontainingthebuilddatefortheCCAapplicationprogram
builddate thatisrunninginthecoprocessor.
6 Userrole Acharacterstringcontainingtheroleidentifierwhichdefinesthehost
applicationuser'scurrentauthority.
7 AsymmetricNMK Thestateoftheasymmetricnewmaster-keyregister:
status
Value Description
1 Theregisterisclear.
2 Theregistercontainsapartiallycompletekey.
3 Theregistercontainsakey.
8 AsymmetricCMK Thestateoftheasymmetriccurrentmaster-keyregister:
status
Value Description
1 Theregisterisclear.
2 Theregistercontainsakey.
9 AsymmetricOMK Thestateoftheasymmetricoldmaster-keyregister:
status
Value Description
1 Theregisterisclear.
2 Theregistercontainsakey.
Outputrule_arrayforoptionSTATCARD
1 Numberof Anumericcharacterstringcontainingthenumberofactivecoprocessors
installedadapters installedinthemachine.ThisincludesonlycoprocessorsthathaveCCA
softwareloaded(includingthosewithCCAUDXsoftware).Non-CCA
coprocessorsarenotincludedinthisnumber.
2 DEShardware Anumericcharacterstringcontaininganintegervalueidentifyingthe
level versionofDEShardwareonthecoprocessor.
3 RSAhardware Anumericcharacterstringcontaininganintegervalueidentifyingthe
level versionofRSAhardwareonthecoprocessor.
4 POSTversion Acharacterstringidentifyingtheversionofthecoprocessor'sPower-OnSelf
Test(POST)firmware.
ThefirstfourcharactersdefinethePOST0versionandthelastfour
charactersdefinethePOST1version.
5 Coprocessor Acharacterstringidentifyingtheoperatingsystemfirmwareonthe
operatingsystem coprocessor.
name
62 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
6 Coprocessor Acharacterstringidentifyingtheversionofthecoprocessor'soperating
operatingsystem systemfirmware.
version
7 Coprocessorpart Acharacterstringcontainingthe8characterpartnumberidentifyingthe
number versionofthecoprocessor.
8 CoprocessorEC Acharacterstringcontainingthe8characterengineeringchange(EC)level
level forthisversionofthecoprocessor.
9 Minibootversion Acharacterstringidentifyingtheversionofthecoprocessor'sminiboot
firmware.Thisfirmwarecontrolstheloadingofprogramsintothe
coprocessor.
ThefirstfourcharactersdefinetheMiniBoot0versionandthelastfour
charactersdefinetheMiniBoot1version.
10 CPUspeed Anumericcharacterstringcontainingtheoperatingspeedofthe
microprocessorchip,inmegahertz.
11 AdapterID(see Auniqueidentifiermanufacturedintothecoprocessor.Thecoprocessor
alsoelement adapterIDisan8-bytebinaryvalue.
number15)
12 Flashmemorysize AnumericcharacterstringcontainingthesizeoftheflashEPROMmemory
onthecoprocessor,in64KBincrements.
13 DRAMmemory AnumericcharacterstringcontainingthesizeofthedynamicRAM(DRAM)
size memoryonthecoprocessor,inkilobytes.
14 Battery-backed Anumericcharacterstringcontainingthesizeofthebattery-backedRAM
memorysize onthecoprocessor,inkilobytes.
15 Serialnumber Acharacterstringcontainingtheuniqueserialnumberofthecoprocessor.
Theserialnumberisfactoryinstalled.
Outputrule_arrayforoptionSTATDIAG
1 Batterystate Anumericcharacterstringcontainingavaluewhichindicateswhetherthe
batteryonthecoprocessorneedstobereplaced:
Value Description
1 Thebatteryisgood.
2 Thebatteryshouldbereplaced.
2 Intrusionlatch Anumericcharacterstringcontainingavaluewhichindicateswhetherthe
state intrusionlatchonthecoprocessorissetorcleared:
Value Description
1 Thelatchiscleared.
2 Thelatchisset.
3 Errorlogstatus Anumericcharacterstringcontainingavaluewhichindicateswhetherthere
isdatainthecoprocessorCCAerrorlog:
Value Description
1 Theerrorlogisempty.
2 Theerrorlogcontainsabnormalterminationdata,butisnotyetfull.
3 Theerrorlogisfullandcannotholdanymoredata.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 63

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
4 Meshintrusion Anumericcharacterstringcontainingavaluetoindicatewhetherthe
coprocessorhasdetectedtamperingwiththeprotectivemeshthat
surroundsthesecuremodule.Thisindicatesaprobableattemptto
physicallypenetratethemodule:
Value Description
1 Nointrusionhasbeendetected.
2 Anintrusionattempthasbeendetected.
5 Lowvoltage Anumericcharacterstringcontainingavaluetoindicatewhethera
detected power-supplyvoltagewasbelowtheminimumacceptablelevel.Thismight
indicateanattempttoattackthesecuritymodule:
Value Description
1 Onlyacceptablevoltageshavebeendetected.
2 Avoltagehasbeendetectedbelowthelow-voltagetamper
threshold.
6 Highvoltage Anumericcharacterstringcontainingavalueindicateswhethera
detected power-supplyvoltagewasgreaterthanthemaximumacceptablelevel.This
mightindicateanattempttoattackthesecuritymodule:
Value Description
1 Onlyacceptablevoltageshavebeendetected.
2 Avoltagehasbeendetectedgreaterthanthehigh-voltagetamper
threshold.
7 Temperaturerange Anumericcharacterstringcontainingavaluetoindicatewhetherthe
exceeded temperatureinthesecuremodulewasoutsideoftheacceptablelimits.This
mightindicateanattempttoattackthesecuritymodule:
Value Description
1 Thetemperatureisacceptable.
2 Thetemperaturehasbeendetectedoutsideofanacceptablelimit.
8 Radiationdetected Anumericcharacterstringcontainingavaluetoindicatewhetherradiation
wasdetectedinsidethesecuremodule.Thismightindicateanattemptto
attackthesecuritymodule:
Value Description
1 Noradiationhasbeendetected.
2 Radiationhasbeendetected.
9,11,13,15,17 Last5commands Thesefiverule_arrayelementscontainthelastfivecommandsthatwere
run runbythecoprocessorCCAapplication.Theyareinchronologicalorder,
withthemostrecentcommandinelement9.Eachelementcontainsthe
securityAPIcommandcodeinthefirstfourcharactersandthe
subcommandcodeinthelastfourcharacters.
10,12,14,16,18 Last5return Thesefiverule_arrayelementscontainthesecurityAPIreturncodesand
codes reasoncodescorrespondingtothefivecommandsinrule_arrayelements9,
11,13,15,and17.Eachelementcontainsthereturncodeinthefirstfour
charactersandthereasoncodeinthelastfourcharacters.
64 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
Outputrule_arrayforoptionSTATEID
1,2 EID Thetwoelements,whenconcatenated,providethe16-byteEnvironment
Identifier(EID)value.
Outputrule_arrayforoptionSTATEXPT
1 BaseCCA AnumericcharacterstringcontainingavaluetoindicatewhetherbaseCCA
services servicesareavailable:
availability
Value Description
0 BaseCCAservicesarenotavailable.
1 BaseCCAservicesareavailable.
3 56-bitDES Anumericcharacterstringcontainingavaluetoindicatewhether56-bit
availability DESencryptionisavailable:
Value Description
0 56-bitDESencryptionisnotavailable.
1 56-bitDESencryptionisavailable.
4 Triple-DES AnumericcharacterstringcontainingavaluetoindicatewhetherTriple-DES
availability encryptionisavailable:
Value Description
0 Triple-DESencryptionisnotavailable.
1 Triple-DESencryptionisavailable.
5 SETservices AnumericcharacterstringcontainingavaluetoindicatewhetherSET
availability (secureelectronictransaction)servicesareavailable:
Value Description
0 SETservicesarenotavailable.
1 SETservicesareavailable.
Note: TheSETservicesarenotsupportedintheLinuxonIBMSystemz
environment.
6 Maximummodulus Anumericcharacterstringcontainingthemaximummodulussizeenabled
forsymmetrickey fortheencryptionofsymmetrickeys.Thisdefinesthelongestpublic-key
encryption modulusthatcanbeusedforkeymanagementofsymmetric-algorithm
keys.
Outputrule_arrayforoptionTIMEDATE
1 Date ThecurrentdateisreturnedasacharacterstringoftheformYYYYMMDD,
where:
YYYY Representstheyear.
MM Representsthemonth(01-12).
DD Representsthedayofthemonth(01-31).
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 65

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
2 Time ThecurrentUTCtimeofdayisreturnedasacharacterstringoftheform
HHMMSS,where:
HH Representsthehour(0-23).
MM Representstheminute(0-59).
SS Representssecond(0-59).
3 Dayoftheweek Thedayoftheweekisreturnedasanumberbetween1(Sunday)and7
(Saturday).
Outputrule_arrayforoptionQPENDING
1 Changetype AnASCIInumberthatindicatesthetypeofpendingchangestoredinthe
(ASCIInumber) adapter(ifthereisone)
Value Description
none Nopendingchange
1 Roleload
2 Profileload
3 Roledelete
4 Profiledelete
5 Domainzeroize
6 Enable
2 userID(string) AstringofeightASCIIcharactersfortheuserIDoftheuserwhoinitiated
thependingchange.
Outputrule_arrayforoptionGET-UDX
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72
Outputrule_arrayforoptionSTATKPRL
Thiskeywordcausesalistofallthenamesprovidedforloadedoperationalkeyparts.Thekeypartsareonly
loadablefromtheTKEusingTKE-specificsecuredverbs.
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72.
Outputrule_arrayforoptionSTATKPR
ThiskeywordhasINPUTverb_dataaswellasOUTPUTverb_data.Anameforanoperationalkeypartisexpected
tobeprovidedintheverb_datafield,withanappropriatelysetverb_data_length.Thisnamemustmatchexactlya
namereturnedbytheSTATKPRLkeywordtolistoperationalkeypartnames,andhavethesamelength.
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72.
Outputrule_arrayforoptionTKESTATE
1 TKEaccess IndicateswhetheraTKEcanbeusedtoadministerthisCEX3C.Valuesare:
enabled TKEPERM Allowed
TKEDENY Notallowed
Outputrule_arrayforoptionSTATICSF
1 Cardserial EightASCIIcharactersfortheadapterserialnumber
number
66 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
2 DESnew AnASCIInumbershowingthestateoftheDESnewmaster-kyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
3 DEScurrent AnASCIInumbershowingthestateoftheDEScurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
4 DESold AnASCIInumbershowingthestateoftheDESoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
5 PKAnew AnASCIInumbershowingthestateofthePKAnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
6 PKAcurrent AnASCIInumbershowingthestateofthePKAcurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
7 PKAold AnASCIInumbershowingthestateofthePKAoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
Outputrule_arrayforoptionSTATICSX
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72.
1 Cardserial EightASCIIcharactersfortheadapterserialnumber
number
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 67

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
2 DESnew AnASCIInumbershowingthestateoftheDESnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
3 DEScurrent AnASCIInumbershowingthestateoftheDEScurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
4 DESold AnASCIInumbershowingthestateoftheDESoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
5 PKAnew AnASCIInumbershowingthestateofthePKAnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
6 PKAcurrent AnASCIInumbershowingthestateofthePKAcurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
7 PKAold AnASCIInumbershowingthestateofthePKAoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
Outputrule_arrayforoptionSTATICSA
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72.
1 Cardserial EightASCIIcharactersfortheadapterserialnumber
number
68 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
2 DESnew AnASCIInumbershowingthestateoftheDESnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
3 DEScurrent AnASCIInumbershowingthestateoftheDEScurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
4 DESold AnASCIInumbershowingthestateoftheDESoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
5 PKAnew AnASCIInumbershowingthestateofthePKAnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
6 PKAcurrent AnASCIInumbershowingthestateofthePKAcurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
7 PKAold AnASCIInumbershowingthestateofthePKAoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
8 AESnew AnASCIInumbershowingthestateoftheAESnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 69

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
9 AEScurrent AnASCIInumbershowingthestateoftheAEScurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
10 AESold AnASCIInumbershowingthestateoftheAESoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
| Outputrule_arrayforoptionSTATICSB
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72.
||| 1 Cardserial EightASCIIcharactersfortheadapterserialnumber
| number
||| 2 DESnew AnASCIInumbershowingthestateoftheDESnewmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Empty
|| 2 Partiallyfull
|| 3 Full
|
||| 3 DEScurrent AnASCIInumbershowingthestateoftheDEScurrentmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Invalid
|| 2 Valid
|
||| 4 DESold AnASCIInumbershowingthestateoftheDESoldmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Invalid
|| 2 Valid
|
||| 5 PKAnew AnASCIInumbershowingthestateofthePKAnewmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Empty
|| 2 Partiallyfull
|| 3 Full
|
||| 6 PKAcurrent AnASCIInumbershowingthestateofthePKAcurrentmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Invalid
|| 2 Valid
|
70 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
||| 7 PKAold AnASCIInumbershowingthestateofthePKAoldmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Invalid
|| 2 Valid
|
||| 8 APKAnew AnASCIInumbershowingthestateoftheAPKAnewmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Empty
|| 2 Partiallyfull
|| 3 Full
|
||| 9 APKAcurrent AnASCIInumbershowingthestateoftheAPKAcurrentmaster-key
|| master-key register:
| registerstate
|| Value Description
|| 1 Invalid
|| 2 Valid
|
||| 10 APKAold AnASCIInumbershowingthestateoftheAPKAoldmaster-keyregister:
| master-key
|| Value Description
| registerstate
|| 1 Invalid
|| 2 Valid
|
Outputrule_arrayforoptionSTATICSE
Thiskeywordhasverbdatareturnedintheverb_datafield.See“VerbdatareturnedforCryptographicFacilityQuery
rule_arraykeywordsonIBMSystemz”onpage72.
1 Cardserial EightASCIIcharactersfortheadapterserialnumber
number
2 DESnew AnASCIInumbershowingthestateoftheDESnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
3 DEScurrent AnASCIInumbershowingthestateoftheDEScurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 71

Cryptographic Facility Query (CSUACFQ)
Table10.CryptographicFacilityQueryinformationreturnedintherule_array (continued)
Elementnumber Name Description
4 DESold AnASCIInumbershowingthestateoftheDESoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
5 PKAnew AnASCIInumbershowingthestateofthePKAnewmaster-keyregister:
master-key
Value Description
registerstate
1 Empty
2 Partiallyfull
3 Full
6 PKAcurrent AnASCIInumbershowingthestateofthePKAcurrentmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
7 PKAold AnASCIInumbershowingthestateofthePKAoldmaster-keyregister:
master-key
Value Description
registerstate
1 Invalid
2 Valid
verb_data_length
Direction: Input/Output Type: Integer
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
Direction: Input/Output Type: String
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.
The verb_data parameter is not used by this verb.
Verb data returned for Cryptographic Facility Query rule_array
keywords on IBM System z
Some keywords return specific data in the verb_data parameter, and update the verb_data_length field
with the count of bytes returned. The verb_data buffer must be large enough to receive the data (see
keyword-specific sizes below) and the verb_data_length parameter as passed in to Cryptographic Facility
Query (CSUACFQ) must indicate that size (or a larger value). If either the verb_data or verb_data_length
fields are not valid, there will be no data returned at all. In this case, a return code of 8 and a reason code
of 72 will be returned.
72 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
GET-UDX
This rule_array keyword causes a variable length list of 2-byte UDX identifiers to be returned. The
identifiers represent the authorized UDX verb IDs for the adapter.AUDX is a set of one or more custom
CCAAPIs added to the adapter, using the installable code feature. Unless the programming source has
also provided an updated host library, these UDX calls will not be accessible from the IBM System z Linux
host library. If an updated host library is provided, refer to the accompanying documentation for usage.
The maximum number of names to be returned is 100. Using this number, the maximum size buffer is
6400 bytes.
STATKPRL
This keyword causes a list of the names of all the operational key parts loaded by the TKE into the
CEX3C to be returned. Each name has a length of 64 bytes. If not enough space has been provided
(using the verb_data_length field passed in by the application) to return the available list, a return code of
8 and a reason code of 72 is returned.
STATKPR
This keyword cause non-secret information about a particular named operational key part loaded by the
TKE to returned to the user. The structures for various key types are given under “OUTPUT DATA.”An
appropriate name for an existing operational key part is expected to be provided as “INPUT DATA.” If not,
the error return code of 8 and a reason code of 1026 will be returned, meaning 'key name not found'.
INPUT DATA: A64-byte key name must be provided in the verb_data field, while the verb_data_length
must be set to a value of 64. The operational key name must match exactly the name returned by a call to
STATKPRL.
OUTPUT DATA: The output data format for STATKPR operational key parts is given in Table11.
Notes:
1. The fields will be returned in the order given.
2. Output data will overwrite the input data in the verb_data field, and set the verb_data_length field to
the output value.
3. The verb_data_length parameter will indicate the total size, at the bottom of the table describing the
verb_data.
Notice that the output data is smaller than the input data.
4. Multiple byte fields are stored in Big-Endian format, as is typical for CEX3C communication.
Table11.OutputdataformatforSTATKPRoperationalkeyparts
Fieldname Lengthinbytes Description
state 1 Stateofthekeypartregister:
Value Description
X'00' Theregisterisempty.
X'01' ThefirstDESkeypartwasenteredforthenamedkeyintothis
register.
X'02' AnintermediateDESkeypart(partafterfirst)hasbeenentered.
X'03' TheregistercontainsacompletedDESkey.
X'11' ThefirstAESkeypartwasenteredforthenamedkeyintothis
register.
X'12' AnintermediateAESkeypart(partafterfirst)hasbeenentered.
X'13' TheregistercontainsacompletedAESkey.
reserved 1 WillhaveavalueofX'00'.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 73

Cryptographic Facility Query (CSUACFQ)
Table11.OutputdataformatforSTATKPRoperationalkeyparts (continued)
Fieldname Lengthinbytes Description
key_length 1 Lengthofkeyinbytes.ForDESkeys,valuesare:8,16,24.ForAESkeys,
valuesare:16,24,32.
cv_length 1 LengthofControlVector(CV)forkeypart,inbytes.Thevaluewillbe8or
16bytes,indicatinghowmuchoftheCVfieldtouse.NotethatCVisNOT
avariablelengthfield.
cv 16 ControlVectorfortheoperationalkeypart.
reserved_2 8 WillhaveavalueofX'00'fortheentirelength.
key_part_hash 20 Hashoverthekeystoredinthekeypartregister.ForDESkeys,thehash
algorithmisSHA-1.ForAESkeys,thehashalgorithmisSHA-256.
ver_pattern 4 Verificationpatternoverthekeycalculatedusingthedefaultalgorithm.
Totalbytecount 52
STATICSA
This rule_array keyword causes the indicated master key hash and verification patterns to be returned for
the master keys loaded in the current domain. The status variables for the various master key registers
returned in the rule_array will indicate which of these verification pattern structures returned contain useful
data.An empty master key register cannot have a meaningful verification pattern. However, the data
structures are returned for all registers indicated, so that interpretation is reliable.
The output data format for STATICSAoperational key parts is given in Table12.
Notes:
1. The fields will be returned in the order given, however the *_ID fields should be used for verification.
2. The verb_data_length parameter will indicate the total size at the bottom of the table describing the
verb_data.
3. Multiple byte fields are stored in Big-Endian format, as is typical for CEX3C communication.
Table12.OutputdataformatforSTATICSAoperationalkeyparts
Lengthin Field
Fieldname bytes value Description
SYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_OMK_MDC4_ID 2 X'0F02' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_OMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeyoldmaster-keyregister,
calculatedusingtheMDC4algorithm.
SYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_CMK_MDC4_ID 2 X'0F01' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_CMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeycurrentmaster-key
register,calculatedusingtheMDC4algorithm.
SYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_NMK_MDC4_ID 2 X'0F00' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
74 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table12.OutputdataformatforSTATICSAoperationalkeyparts (continued)
Lengthin Field
Fieldname bytes value Description
SYM_NMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeynewmaster-keyregister,
calculatedusingtheMDC4algorithm.
ASYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_OMK_MDC4_ID 2 X'0F05' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_OMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeyoldmaster-keyregister,
calculatedusingtheMDC4algorithm.
ASYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_CMK_MDC4_ID 2 X'0F04' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_CMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeycurrentmaster-key
register,calculatedusingtheMDC4algorithm.
ASYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_NMK_MDC4_ID 2 X'0F03' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_NMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeynewmaster-keyregister,
calculatedusingtheMDC4algorithm.
SYM_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_OMK_VP_ID 2 X'0F08' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_OMK_VP 8 variable VerificationpatternovertheSymmetricKeyoldmaster-key
registercalculatedusingthedefaultalgorithm.
SYM_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_CMK_VP_ID 2 X'0F07' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_CMK_VP 8 variable VerificationpatternovertheSymmetricKeycurrentmaster-key
register,calculatedusingthedefaultalgorithm.
SYM_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_NMK_VP_ID 2 X'0F06' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_NMK_VP 8 variable VerificationpatternovertheSymmetricKeynewmaster-key
register,calculatedusingthedefaultalgorithm.
SYM_NMK_MKAP_LEN 2 12 LengthinbytesofthisAuthenticationpatternblockinthe
verb_data(comprisingthislengthfield,thefollowingIDfield,
andthefieldfortheAuthenticationpattern).
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 75

Cryptographic Facility Query (CSUACFQ)
Table12.OutputdataformatforSTATICSAoperationalkeyparts (continued)
Lengthin Field
Fieldname bytes value Description
SYM_NMK_MKAP_ID 2 X'0F09' Hexadecimalidentifierindicatingthecontentsofthefollowing
Authenticationpatternfield.
SYM_NMK_MKAP 8 variable AuthenticationpatternovertheSymmetricKeynewmaster-key
register,calculatedusingtheICSFspecifiedalgorithm.
AES_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
AES_OMK_VP_ID 2 X'0F0C' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
AES_OMK_VP 8 variable VerificationpatternovertheAESKeyoldmaster-keyregister,
calculatedusingtheSHA-256algorithm.
AES_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
AES_CMK_VP_ID 2 X'0F0B' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
AES_CMK_VP 8 variable VerificationpatternovertheAESKeycurrentmaster-key
registercalculatedusingtheSHA-256algorithm.
AES_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
AES_NMK_VP_ID 2 X'0F0A' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
AES_NMK_VP 8 variable VerificationpatternovertheAESKeynewmaster-keyregister,
calculatedusingtheSHA-256algorithm.
Totalbytecount 204
STATICSE
This rule_array keyword causes the indicated master key hash and verification patterns to be returned for
the master keys loaded in the current domain. The status variables for the various master-key registers
returned in the rule_array will indicate which of these verification pattern structures returned contain useful
data.An empty master-key register cannot have a meaningful verification pattern. However, the data
structures are returned for all registers indicated, so that interpretation is reliable.
The output data format for STATICSE operational key parts is given in Table13.
Notes:
1. The fields will be returned in the order given, however the *_ID fields should be used for verification.
2. The verb_data_length parameter will indicate the total size at the bottom of the table describing the
verb_data.
3. Multiple byte fields are stored in Big-Endian format, as is typical for CEX3C communication.
Table13.OutputdataformatforSTATICSEoperationalkeyparts
Lengthin Field
Fieldname bytes value Description
SYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
76 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table13.OutputdataformatforSTATICSEoperationalkeyparts (continued)
Lengthin Field
Fieldname bytes value Description
SYM_OMK_MDC4_ID 2 X'0F02' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_OMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeyoldmaster-keyregister,
calculatedusingtheMDC4algorithm.
SYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_CMK_MDC4_ID 2 X'0F01' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_CMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeycurrentmaster-key
register,calculatedusingtheMDC4algorithm.
SYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_NMK_MDC4_ID 2 X'0F00' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_NMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeynewmaster-keyregister,
calculatedusingtheMDC4algorithm.
ASYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_OMK_MDC4_ID 2 X'0F05' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_OMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeyoldmaster-keyregister,
calculatedusingtheMDC4algorithm.
ASYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_CMK_MDC4_ID 2 X'0F04' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_CMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeycurrentmaster-key
register,calculatedusingtheMDC4algorithm.
ASYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_NMK_MDC4_ID 2 X'0F03' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_NMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeynewmaster-keyregister,
calculatedusingtheMDC4algorithm.
SYM_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_OMK_VP_ID 2 X'0F08' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_OMK_VP 8 variable VerificationpatternovertheSymmetricKeyoldmaster-key
registercalculatedusingthedefaultalgorithm.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 77

Cryptographic Facility Query (CSUACFQ)
Table13.OutputdataformatforSTATICSEoperationalkeyparts (continued)
Lengthin Field
Fieldname bytes value Description
SYM_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_CMK_VP_ID 2 X'0F07' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_CMK_VP 8 variable VerificationpatternovertheSymmetricKeycurrentmaster-key
register,calculatedusingthedefaultalgorithm.
SYM_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_NMK_VP_ID 2 X'0F06' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_NMK_VP 8 variable VerificationpatternovertheSymmetricKeynewmaster-key
register,calculatedusingthedefaultalgorithm.
SYM_NMK_MKAP_LEN 2 12 LengthinbytesofthisAuthenticationpatternblockinthe
verb_data(comprisingthislengthfield,thefollowingIDfield,
andthefieldfortheAuthenticationpattern).
SYM_NMK_MKAP_ID 2 X'0F09' Hexadecimalidentifierindicatingthecontentsofthefollowing
Authenticationpatternfield.
SYM_NMK_MKAP 8 variable AuthenticationpatternovertheSymmetricKeynewmaster-key
register,calculatedusingtheICSFspecifiedalgorithm.
Totalbytecount 168
| STATICSB
| This rule_array keyword causes the indicated master key hash and verification patterns to be returned for
| the master keys loaded in the current domain. The status variables for the various master-key registers
| returned in the rule_array will indicate which of these verification pattern structures returned contain useful
| data.An empty master-key register cannot have a meaningful verification pattern. However, the data
| structures are returned for all registers indicated, so that interpretation is reliable.
| The output data format for STATICSB operational key parts is given in Table14.
| Notes:
| 1. The fields will be returned in the order given, however the *_ID fields should be used for verification.
| 2. The verb_data_length parameter will indicate the total size at the bottom of the table describing the
| verb_data.
| 3. Multiple byte fields are stored in Big-Endian format, as is typical for CEX3C communication.
|| Table14.OutputdataformatforSTATICSBoperationalkeyparts
|| Lengthin Field
|||| Fieldname bytes value Description
|||| SYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheHashpattern).
|||| SYM_OMK_MDC4_ID 2 X'0F02' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Hashpatternfield.
|||| SYM_OMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeyoldmaster-keyregister,
| calculatedusingtheMDC4algorithm.
78 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
| Table14.OutputdataformatforSTATICSBoperationalkeyparts (continued)
|| Lengthin Field
|||| Fieldname bytes value Description
|||| SYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheHashpattern).
|||| SYM_CMK_MDC4_ID 2 X'0F01' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Hashpatternfield.
|||| SYM_CMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeycurrentmaster-key
| register,calculatedusingtheMDC4algorithm.
|||| SYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheHashpattern).
|||| SYM_NMK_MDC4_ID 2 X'0F00' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Hashpatternfield.
|||| SYM_NMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeynewmaster-keyregister,
| calculatedusingtheMDC4algorithm.
|||| ASYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheHashpattern).
|||| ASYM_OMK_MDC4_ID 2 X'0F05' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Hashpatternfield.
|||| ASYM_OMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeyoldmaster-keyregister,
| calculatedusingtheMDC4algorithm.
|||| ASYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheHashpattern).
|||| ASYM_CMK_MDC4_ID 2 X'0F04' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Hashpatternfield.
|||| ASYM_CMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeycurrentmaster-key
| register,calculatedusingtheMDC4algorithm.
|||| ASYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheHashpattern).
|||| ASYM_NMK_MDC4_ID 2 X'0F03' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Hashpatternfield.
|||| ASYM_NMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeynewmaster-keyregister,
| calculatedusingtheMDC4algorithm.
|||| SYM_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern).
|||| SYM_OMK_VP_ID 2 X'0F08' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| SYM_OMK_VP 8 variable VerificationpatternovertheSymmetricKeyoldmaster-key
| registercalculatedusingthedefaultalgorithm.
|||| SYM_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern).
|||| SYM_CMK_VP_ID 2 X'0F07' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 79

Cryptographic Facility Query (CSUACFQ)
| Table14.OutputdataformatforSTATICSBoperationalkeyparts (continued)
|| Lengthin Field
|||| Fieldname bytes value Description
|||| SYM_CMK_VP 8 variable VerificationpatternovertheSymmetricKeycurrentmaster-key
| register,calculatedusingthedefaultalgorithm.
|||| SYM_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern).
|||| SYM_NMK_VP_ID 2 X'0F06' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| SYM_NMK_VP 8 variable VerificationpatternovertheSymmetricKeynewmaster-key
| register,calculatedusingthedefaultalgorithm.
|||| SYM_NMK_MKAP_LEN 2 12 LengthinbytesofthisAuthenticationpatternblockinthe
| verb_data(comprisingthislengthfield,thefollowingIDfield,
| andthefieldfortheAuthenticationpattern).
|||| SYM_NMK_MKAP_ID 2 X'0F09' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Authenticationpatternfield.
|||| SYM_NMK_MKAP 8 variable AuthenticationpatternovertheSymmetricKeynewmaster-key
| register,calculatedusingtheICSFspecifiedalgorithm.
|||| AES_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern)
|||| AES_OMK_VP_ID 2 X'0F0C' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| AES_OMK_VP 8 variable VerificationpatternovertheSymmetricKeyoldmaster-key
| register,calculatedusingtheSHA-256algorithm.
|||| AES_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern).
|||| AES_CMK_VP_ID 2 X'0F0B' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| AES_CMK_VP 8 variable VerificationpatternovertheSymmetricKeycurrentmaster-key
| register,calculatedusingtheSHA-256algorithm.
|||| AES_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheAuthenticationpattern).
|||| AES_NMK_VP_ID 2 X'0F0A' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| AES_NMK_VP 8 variable VerificationpatternovertheSymmetricKeynewmaster-key
| register,calculatedusingtheSHA-256algorithm.
|||| APKA_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern)
|||| APKA_OMK_VP_ID 2 X'0F0F' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| APKA_OMK_VP 8 variable VerificationpatternovertheSymmetricKeyoldmaster-key
| register,calculatedusingtheSHA-256algorithm.
|||| APKA_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheVerificationpattern).
80 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
| Table14.OutputdataformatforSTATICSBoperationalkeyparts (continued)
|| Lengthin Field
|||| Fieldname bytes value Description
|||| APKA_CMK_VP_ID 2 X'0F0E' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| APKA_CMK_VP 8 variable VerificationpatternovertheSymmetricKeycurrentmaster-key
| register,calculatedusingtheSHA-256algorithm.
|||| APKA_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
| (comprisingthislengthfield,thefollowingIDfield,andthefield
| fortheAuthenticationpattern).
|||| APKA_NMK_VP_ID 2 X'0F0D' Hexadecimalidentifierindicatingthecontentsofthefollowing
| Verificationpatternfield.
|||| APKA_NMK_VP 8 variable VerificationpatternovertheSymmetricKeynewmaster-key
| register,calculatedusingtheSHA-256algorithm.
|| Totalbytecount 240
|
| This keyword was introduced with CCA4.1.0.
STATICSX
This rule_array keyword causes the indicated master key hash and verification patterns to be returned for
the master keys loaded in the current domain. The status variables for the various master key registers
returned in the rule_array will indicate which of these verification pattern structures returned contain useful
data.An empty master key register cannot have a meaningful verification pattern. However, the data
structures are returned for all registers indicated, so that interpretation is reliable.
The output data format for STATICSX operational key parts is given in Table15.
Notes:
1. The fields will be returned in the order given, however the *_ID fields should be used for verification.
2. The verb_data_length parameter will indicate the total size at the bottom of the table describing the
verb_data.
3. Multiple byte fields are stored in Big-Endian format, as is typical for CEX3C communication.
Table15.OutputdataformatforSTATICSXoperationalkeyparts
Lengthin Field
Fieldname bytes value Description
SYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_OMK_MDC4_ID 2 X'0F02' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_OMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeyoldmaster-keyregister,
calculatedusingtheMDC4algorithm.
SYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_CMK_MDC4_ID 2 X'0F01' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_CMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeycurrentmaster-key
register,calculatedusingtheMDC4algorithm.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 81

Cryptographic Facility Query (CSUACFQ)
Table15.OutputdataformatforSTATICSXoperationalkeyparts (continued)
Lengthin Field
Fieldname bytes value Description
SYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
SYM_NMK_MDC4_ID 2 X'0F00' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
SYM_NMK_MDC4_HP 16 variable HashpatternovertheSymmetricKeynewmaster-keyregister,
calculatedusingtheMDC4algorithm.
ASYM_OMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_OMK_MDC4_ID 2 X'0F05' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_OMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeyoldmaster-keyregister,
calculatedusingtheMDC4algorithm.
ASYM_CMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_CMK_MDC4_ID 2 X'0F04' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_CMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeycurrentmaster-key
register,calculatedusingtheMDC4algorithm.
ASYM_NMK_MDC4_LEN 2 20 LengthinbytesofthisHashpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheHashpattern).
ASYM_NMK_MDC4_ID 2 X'0F03' Hexadecimalidentifierindicatingthecontentsofthefollowing
Hashpatternfield.
ASYM_NMK_MDC4_HP 16 variable HashpatternovertheAsymmetricKeynewmaster-keyregister,
calculatedusingtheMDC4algorithm.
SYM_OMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_OMK_VP_ID 2 X'0F08' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_OMK_VP 8 variable VerificationpatternovertheSymmetricKeyoldmaster-key
registercalculatedusingthedefaultalgorithm.
SYM_CMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_CMK_VP_ID 2 X'0F07' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
SYM_CMK_VP 8 variable VerificationpatternovertheSymmetricKeycurrentmaster-key
register,calculatedusingthedefaultalgorithm.
SYM_NMK_VP_LEN 2 12 LengthinbytesofthisVerificationpatternblockintheverb_data
(comprisingthislengthfield,thefollowingIDfield,andthefield
fortheVerificationpattern).
SYM_NMK_VP_ID 2 X'0F06' Hexadecimalidentifierindicatingthecontentsofthefollowing
Verificationpatternfield.
82 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Query (CSUACFQ)
Table15.OutputdataformatforSTATICSXoperationalkeyparts (continued)
Lengthin Field
Fieldname bytes value Description
SYM_NMK_VP 8 variable VerificationpatternovertheSymmetricKeynewmaster-key
register,calculatedusingthedefaultalgorithm.
Totalbytecount 156
Restrictions
You cannot limit the number of returned rule_array elements. Table10 on page 61 describes the number
and meaning of the information in output rule_array elements.
Tip: Allocate a minimum of 30 rule_array elements to allow for extensions of the returned information.
Required commands
None
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSUACFQJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSUACFQJ are shown here.
Format
public native void CSUACFQJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger verb_data_length,
byte[] verb_data
);
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 83

Cryptographic Facility Version (CSUACFV)
Cryptographic Facility Version (CSUACFV)
The Cryptographic Facility Version verb is used to retrieve information about the SecurityApplication
Program Interface (SAPI) Version and the SecurityApplication Program Interface build date. In the same
format as the Cryptographic Facility Query (CSUACFQ) verb returns for the CCAapplication with the
STATCCArule_array option.
This verb returns information elements in the version_data variable.
Format
CSUACFV(
return_code,
reason_code,
exit_data_length,
exit_data,
version_data_length,
version_data )
Parameters
Note that there is no rule_array keyword.
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see
“Parameters common to all verbs” on page 14.
version_data_length
Direction: Input/Output Type: Integer
The version_data_length parameter is a pointer to an integer variable containing the number of bytes
in the version data variable. This value must be a minimum of 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
Direction: Output Type: String
The version_data parameter is a pointer to a string variable containing data returned by the verb.An
8-byte character string identifies the version of the SecurityApplication Program Interface (SAPI)
library, followed by an 8-byte character string containing the build date for the SAPI library, followed by
a null terminating character. The build date is in the format: yyyymmdd, where yyyy is the year, mm is
the month, and dd is the day of the month.
Restrictions
None
Required commands
None
Usage notes
None
84 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Facility Version (CSUACFV)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSUACFVJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSUACFVJ are shown here.
Format
public native void CSUACFVJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger version_data_length,
byte[] version_data
);
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 85

Cryptographic Resource Allocate (CSUACRA)
Cryptographic Resource Allocate (CSUACRA)
The Cryptographic ResourceAllocate verb is used to allocate a specific CCAcoprocessor for use by the
thread or process, depending on the scope of the verb. 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. 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 (see “Cryptographic Resource Deallocate (CSUACRD)” on page 88) to
deallocate an allocated cryptographic resource.
Be sure to review “Multi-coprocessor capabilities” on page 31.
Format
CSUACRA(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
resource_name_length,
resource_name )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type:Array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters. The rule_array keyword is described in Table16.
Table16.KeywordsforCryptographicResourceAllocatecontrolinformation
Keyword Description
Cryptographicresource(Required)
DEVICE SpecifiesaCEX3Ccoprocessor.
HCPUACLR SpecifiestheuseofhostCPUassistforclearkeys.Thiskeywordenablesclearkeyuseof
theCPACF,forclearkeyAESencryptionanddecryptionwithhashalgorithms:SHA-1,
SHA-224,SHA-256,SHA-384,andSHA-512.Thisisthedefaultstateatthetimeofthefirst
useoftheCCAlibrarybyaPIDorTID.
HCPUAPRT SpecifiestheuseofhostCPUassistforprotectedkeys.Thiskeywordenablesprotected
keyuseoftheCPACFforprotectedkeyAESandDES,TDES,andMAC.Thisisnotthe
defaultstateatthetimeofthefirstuseoftheCCAlibrarybyaPIDorTID.
86 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Resource Allocate (CSUACRA)
There are environment variable that also impacts default card, CSU_DEFAULT_ADAPTER (see
“Multi-coprocessor capabilities” on page 31, and environment variables that influence CPACF support
(see “Environment variables that affect CPACF usage” on page 8).
The actual hardware configuration determines what features are available, and CCAwill use what
exists if the user sets these values as desired, with respect to appropriate defaults.
resource_name_length
Direction: Input Type: Integer
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
Direction: Input Type: String
The resource_name parameter is a pointer to a string variable containing the name of the coprocessor
to be allocated.
Restrictions
None
Required commands
None.
Usage notes
For optimal performance, ensure that you have enabled CPACF in the thread doing the processing, by
making a quick call on the host side at thread startup time, to Cryptographic ResourceAllocate, specifying
the correct HCPUACLR and HCPUAPRT keyword values for your operation. See the Cryptographic
ResourceAllocate rule_array keyword definitions, and see “Access control points that affect CPACF
protected key operations” on page 9 for more affected verbs.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSUACRAJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSUACRAJ are shown here.
Format
public native void CSUACRAJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_lengthh,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger resource_name_length,
byte[] resource_name
);
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 87

Cryptographic Resource Deallocate (CSUACRD)
Cryptographic Resource Deallocate (CSUACRD)
The Cryptographic Resource Deallocate verb is used to deallocate a specific CCAcoprocessor that is
allocated by the thread or process, depending on the scope of the verb. This verb is scoped to a thread.
When a thread or process, depending on the scope, de-allocates a cryptographic resource, requests are
routed to the default cryptographic resource.
You can set the default cryptographic resource. If you take no action, the default assignment is CRP01.
If a thread with an allocated coprocessor ends without first de-allocating 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.
Be sure to review “Multi-coprocessor capabilities” on page 31.
Format
CSUACRD(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count
rule_array,
resource_name_length,
resource_name )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type:Array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters. The rule_array keyword is described in Table17.
Table17.KeywordsforCryptographicResourceDeallocatecontrolinformation
Keyword Description
Cryptographicresource(Required)
DEVICE SpecifiesaCEX3CCoprocessor.
HCPUACLR SpecifiestheuseofhostCPUassistforclearkeys.Thiskeywordenablesclearkeyuse
oftheCPACF,forclearkeyAESencryptionanddecryptionwithhashalgorithms:SHA-1,
SHA-224,SHA-256,SHA-384,andSHA-512.Thisisthedefaultstateatthetimeofthe
firstuseoftheCCAlibrarybyaPIDorTID.
HCPUAPRT SpecifiestheuseofhostCPUassistforprotectedkeys.Thiskeyworddisablesprotected
keyuseoftheCPACFforprotectedkeyAESandDES,TDES,andMAC.Thisisthe
defaultstateatthetimeofthefirstuseoftheCCAlibrarybyaPIDorTID.
88 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Resource Deallocate (CSUACRD)
There are environment variable that also impacts default card, CSU_DEFAULT_ADAPTER (see
“Multi-coprocessor capabilities” on page 31, and environment variables that influence CPACF support
(see “Environment variables that affect CPACF usage” on page 8).
The actual hardware configuration determines what features are available, and CCAwill use what
exists if the user sets these values as desired, with respect to appropriate defaults.
resource_name_length
Direction: Input Type: Integer
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
Direction: Input Type: String
The resource_name parameter is a pointer to a string variable containing the name of the coprocessor
to be deallocated.
Restrictions
None
Required commands
None
Usage notes
To disable CPACF usage in your processing thread, make a call to Cryptographic Resource Deallocate,
specifying the correct HCPUACLR and HCPUAPRT keyword as appropriate. See the Cryptographic
Resource Deallocate rule_array keyword definitions, and see “Access control points that affect CPACF
protected key operations” on page 9 for more affected verbs.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSUACRDJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSUACRDJ are shown here.
Format
public native void CSUACRDJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger resource_name_length,
byte[] resource_name);
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 89

Key Storage Initialization (CSNBKSI)
Key Storage Initialization (CSNBKSI)
The Key Storage Initialization verb initializes a key-storage file using the current symmetric or asymmetric
master-key. The initialized key storage file does not contain any preexisting key records. The key storage
data and index files are in the /opt/IBM/CEX3C/keys directory.
| The key storage functions do not work with HMAC keys.
Format
CSNBKSI(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_storage_file_name_length,
key_storage_file_name,
key_storage_description_length,
key_storage_description,
clear_master_key )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 2.
rule_array
Direction: Input Type:Array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters. The rule_array keywords are described in Table18.
Table18.KeywordsforKeyStorageInitializationcontrolinformation
Keyword Description
Master-keysource(Required)
CURRENT Specifiesthecurrentsymmetricmaster-keyofthe
defaultcryptographicfacilityistobeusedforthe
initialization.
Key-storageselection(Onerequired)
AES InitializeAESkeystorage.
DES InitializeDESkeystorage.
| PKA InitializePKAkeystorage(PKAand,beginningwith
| Release4.1.0,ECCkeytokens).
key_storage_file_name_length
Direction: Input Type: Integer
90 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Storage Initialization (CSNBKSI)
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
Direction: Input Type: String
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
Direction: Input Type: Integer
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
Direction: Input Type: String
The key_storage_description parameter is a pointer to a string variable containing the description
string stored in the key-storage file when it is initialized.
clear_master_key
Direction: Input Type: String
The clear_master_key parameter is unused, but it must be declared and point to 24 data bytes in
application storage.
Restrictions
| ECC and variable-length symmetric key tokens are not supported in releases before Release 4.1.0.
Required commands
| The Key Storage Initialization verb requires the Key Test and Key Test2 command (offset X'001D') to be
| enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKSIJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKSIJ are shown here.
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 91

Key Storage Initialization (CSNBKSI)
Format
public native void CSNBKSIJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger filename_length,
byte[] filename,
hikmNativeInteger key_storage_description_length,
byte[] key_storage_description,
byte[] clear_master_key );
92 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Master Key Process (CSNBMKP)
Master Key Process (CSNBMKP)
The Master Key Process verb operates on the three master-key registers: new, current, and old. Use the
verb to perform the following services:
v Clear the new and clear the old master-key registers.
v Generate a random master-key value in the new master-key register.
v XOR a clear value as a key part into the new master-key register.
v Set the 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.
You can choose to process either the symmetric or asymmetric registers by specifying the SYM-MK and
the ASYM-MK rule_array keywords.
Tip: Before starting to load new master-key information, ensure the new master-key register is cleared.
Do this by using the CLEAR keyword in the rule_array.
To form a master key from key parts in the new master-key register, use the verb several times to
complete the following tasks:
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.
v SET or confirm a master key for which the last key part has been loaded into the new master-key
register.
For the SYM-MK, 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, a warning
is issued. The product maintains odd parity on the accumulated symmetric master-key value.
When the last master key part is entered, this additional processing is performed:
v If any two of the 8-byte parts of the new master-key have the same value, a warning is issued. Do not
ignore this warning. Do not use a key with this property.
v If any of the 8-byte parts of the new master-key compares equal to one of the weak DES-keys, the verb
fails with return code 8, reason code 703. See “Questionable DES keys” on page 95 for a list of these
weak keys.Aparity-adjusted version of the asymmetric master-key is used to look for weak keys.
If anAES, DES or PKAkey storage exists, the header record of each key storage is updated with the
verification pattern of the new, current master-key.
Format
CSNBMKP(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_part )
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 14.
rule_array_count
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 93

Master Key Process (CSNBMKP)
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, or 3.
rule_array
Direction: Input Type:Array
FoThe rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters. The rule_array keywords are described in Table19.
Table19.KeywordsforMasterKeyProcesscontrolinformation
Keyword Description
Cryptographiccomponent(Optional)
ADAPTER Specifiesthecoprocessor.Thisisthedefault.
Masterkeyregisterclass(One,required)
SeeNoteattheendofthistable.
AES-MK SpecifiesoperationwiththeAESmaster-keyregisters.
|| APKA-MK SpecifiesoperationwiththeAPKAmaster-keyregisters.ThiskeywordwasintroducedwithCCA
| 4.1.0.
ASYM-MK Specifiesoperationwiththeasymmetricmaster-keyregisters.
SYM-MK Specifiesoperationwiththesymmetricmaster-keyregisters.
Master-keyprocess(One,required)
CLEAR SpecifiestocleartheNMKregister.
FIRST Specifiestoloadthefirstkey_part.
MIDDLE SpecifiestoXORthesecond,third,orotherintermediatekey_partintotheNMKregister.
LAST SpecifiestoXORthelastkey_partintotheNMKregister.
SET SpecifiestoadvancetheCMKtotheOMKregister,toadvancetheNMKtotheCMKregister,and
tocleartheNMKregister.
Note: Themaster-keyregisterclassisnotoptionalforLinuxonIBMSystemz.Thereisnodefaultforthis
environment.Ifasuitablekeywordisnotspecified,returncode8withreasoncode33willbereturned.
key_part
Direction: Input Type: String
Apointer to a string variable containing a 168-bit or 192-bit clear key-part used when you specify one
of the keywords FIRST, MIDDLE, or LAST. If you use the CLEAR or SET keywords, the information
in the variable is ignored, but you must declare the variable.
Restrictions
General restrictions:
v You must set up the groups for the users who will be loading the master keys to the cards. Each part of
the load process is owned by a different Linux group created by the RPM install procedure, and verified
in the host library implementing theAPI allowing master key processing. To complete a specific step,
the user must have membership in the proper group. See Master key load (Step 7 on page 544).
| v TheAES-MK rule-array keyword is not supported in releases before Release 3.30.
| v TheAPKA-MK rule-array keyword is not supported in releases before Release 4.1.0.
For applications that use this verb:
94 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Master Key Process (CSNBMKP)
v When writing your own application, you must link it with the /usr/lib64/libcsulccamk.so library.
Required commands
This verb requires the following commands to be enabled in the active role based on the master-key class
and master-key operation:
Master-key
operation Master-keyclass Offset Command
| CLEAR AES-MK X'0124' Clear New AES Master Key
| SYM-MK X'0032' Clear New DES Master Key Register
| ASYM-MK X'0060' Clear New RSA Master Key Register
|| APKA-MK X'031F' Clear New ECC Master Key
| FIRST AES-MK X'0125' Load First AES Master Key Part
| SYM-MK X'0018' Load First DES Master Key Part
| ASYM-MK X'0053' Load First RSA Master Key Part
|| APKA-MK X'0320' Load First ECC Master Key Part
| MIDDLEorLAST AES-MK X'0126' Combine AES Master Key Parts
| SYM-MK X'0019' Combine DES Master Key Parts
| ASYM-MK X'0054' Combine RSA Master Key Parts
|| APKA-MK X'0321' Combine ECC Master Key Parts
| SET AES-MK X'0128' Set AES Master Key
| SYM-MK X'001A' Set DES Master Key
| ASYM-MK X'0057' Set RSA Master Key
|| APKA-MK X'0322' Set ECC Master Key
Usage notes
None
Questionable DES keys
These keys are considered questionable DES keys, and so should probably not be used when entering
SYM-MK orASYM-MK master keys.
01 01 01 01 01 01 01 01 /* weak */
FE FE FE FE FE FE FE FE /* weak */
1F 1F 1F 1F 0E 0E 0E 0E /* weak */
E0 E0 E0 E0 F1 F1 F1 F1 /* weak */
01 FE 01 FE 01 FE 01 FE /* semi-weak */
FE 01 FE 01 FE 01 FE 01 /* semi-weak */
1F E0 1F E0 0E F1 0E F1 /* semi-weak */
E0 1F E0 1F F1 0E F1 0E /* semi-weak */
01 E0 01 E0 01 F1 01 F1 /* semi-weak */
E0 01 E0 01 F1 01 F1 01 /* semi-weak */
1F FE 1F FE 0E FE 0E FE /* semi-weak */
FE 1F FE 1F FE 0E FE 0E /* semi-weak */
01 1F 01 1F 01 0E 01 0E /* semi-weak */
1F 01 1F 01 0E 01 0E 01 /* semi-weak */
E0 FE E0 FE F1 FE F1 FE /* semi-weak */
FE E0 FE E0 FE F1 FE F1 /* semi-weak */
1F 1F 01 01 0E 0E 01 01 /* possibly semi-weak */
01 1F 1F 01 01 0E 0E 01 /* possibly semi-weak */
1F 01 01 1F 0E 01 01 0E /* possibly semi-weak */
01 01 1F 1F 01 01 0E 0E /* possibly semi-weak */
E0 E0 01 01 F1 F1 01 01 /* possibly semi-weak */
FE FE 01 01 FE FE 01 01 /* possibly semi-weak */
FE E0 1F 01 FE F1 0E 01 /* possibly semi-weak */
E0 FE 1F 01 F1 FE 0E 01 /* possibly semi-weak */
FE E0 01 1F FE F1 01 0E /* possibly semi-weak */
E0 FE 01 1F F1 FE 01 0E /* possibly semi-weak */
E0 E0 1F 1F F1 F1 0E 0E /* possibly semi-weak */
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 95

Master Key Process (CSNBMKP)
FE FE 1F 1F FE FE 0E 0E /* possibly semi-weak */
FE 1F E0 01 FE 0E F1 01 /* possibly semi-weak */
E0 1F FE 01 F1 0E FE 01 /* possibly semi-weak */
FE 01 E0 1F FE 01 F1 0E /* possibly semi-weak */
E0 01 FE 1F F1 01 FE 0E /* possibly semi-weak */
01 E0 E0 01 01 F1 F1 01 /* possibly semi-weak */
1F FE E0 01 0E FE F1 01 /* possibly semi-weak */
1F E0 FE 01 0E F1 FE 01 /* possibly semi-weak */
01 FE FE 01 01 FE FE 01 /* possibly semi-weak */
1F E0 E0 1F 0E F1 F1 0E /* possibly semi-weak */
01 FE E0 1F 01 FE F1 0E /* possibly semi-weak */
01 E0 FE 1F 01 F1 FE 0E /* possibly semi-weak */
1F FE FE 1F 0E FE FE 0E /* possibly semi-weak */
E0 01 01 E0 F1 01 01 F1 /* possibly semi-weak */
FE 1F 01 E0 FE 0E 01 F1 /* possibly semi-weak */
FE 01 1F E0 FE 01 0E F1 /* possibly semi-weak */
E0 1F 1F E0 F1 0E 0E F1 /* possibly semi-weak */
FE 01 01 FE FE 01 01 FE /* possibly semi-weak */
E0 1F 01 FE F1 0E 01 FE /* possibly semi-weak */
E0 01 1F FE F1 01 0E FE /* possibly semi-weak */
FE 1F 1F FE FE 0E 0E FE /* possibly semi-weak */
1F FE 01 E0 E0 FE 01 F1 /* possibly semi-weak */
01 FE 1F E0 01 FE 0E F1 /* possibly semi-weak */
1F E0 01 FE 0E F1 01 FE /* possibly semi-weak */
01 E0 1F FE 01 F1 0E FE /* possibly semi-weak */
01 01 E0 E0 01 01 F1 F1 /* possibly semi-weak */
1F 1F E0 E0 0E 0E F1 F1 /* possibly semi-weak */
1F 01 FE E0 0E 01 FE F1 /* possibly semi-weak */
01 1F FE E0 01 0E FE F1 /* possibly semi-weak */
1F 01 E0 FE 0E 01 F1 FE /* possibly semi-weak */
01 1F E0 FE 01 E0 F1 FE /* possibly semi-weak */
01 01 FE FE 01 01 FE FE /* possibly semi-weak */
1F 1F FE FE 0E 0E FE FE /* possibly semi-weak */
FE FE E0 E0 FE FE F1 F1 /* possibly semi-weak */
E0 FE FE E0 F1 FE FE F1 /* possibly semi-weak */
FE E0 E0 FE FE F1 F1 FE /* possibly semi-weak */
E0 E0 FE FE F1 F1 FE FE /* possibly semi-weak */
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBMKPJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBMKPJ are shown here.
Format
public native void CSNBMKPJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_part );
96 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Random Number Tests (CSUARNT)
Random Number Tests (CSUARNT)
The Random Number Tests verb invokes the USANIST FIPS PUB 140-1 specified cryptographic
operational tests. 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, RSA, and SHA-1 processes
The tests are performed three times. If there is any test failure, the verb returns return code 4 and reason
code 1.
Format
CSUARNT(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array )
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see
“Parameters common to all verbs” on page 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type:Array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters. The rule_array keywords are described in Table20.
Table20.KeywordsforRandomNumberTestscontrolinformation
Keyword Description
Testselection(Onerequired)
FIPS-RNT PerformtheFIPS140-1specifiedtestontherandom
numbergenerationoutput.
KAT PerformtheFIPS140-1specifiedknown-answertests
onDES,RSA,andSHA-1.
Restrictions
None
Required commands
None
Chapter4.UsingtheCCAnodesandresourcecontrolverbs 97

Random Number Tests (CSUARNT)
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSUARNTJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSUARNTJ are shown here.
Format
public native void CSUARNTJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array);
98 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

|
Chapter 5. Managing AES and DES cryptographic keys
| This chapter describes the verbs that generate and maintainAES and DES cryptographic keys.
| Using CCA, you can generate keys using the Key Generate verb. CCAprovides a number of verbs to
| assist you in managing and distributingAES and DES keys, generating random numbers, and maintaining
| the key storage files.
This chapter describes the following verbs:
v “Clear Key Import (CSNBCKI)” on page 100
v “Control Vector Generate (CSNBCVG)” on page 102
v “Control Vector Translate (CSNBCVT)” on page 104
v “Cryptographic Variable Encipher (CSNBCVE)” on page 107
v “Data Key Export (CSNBDKX)” on page 109
v “Data Key Import (CSNBDKM)” on page 111
v “Diversified Key Generate (CSNBDKG)” on page 113
v “Key Export (CSNBKEX)” on page 117
v “Key Generate (CSNBKGN)” on page 120
| v “Key Generate2 (CSNBKGN2)” on page 128
v “Key Import (CSNBKIM)” on page 133
v “Key Part Import (CSNBKPI)” on page 136
| v “Key Part Import2 (CSNBKPI2)” on page 139
v “Key Test (CSNBKYT)” on page 143
| v “Key Test2 (CSNBKYT2)” on page 147
v “Key Test Extended (CSNBKYTX)” on page 150
v “Key Token Build (CSNBKTB)” on page 155
| v “Key Token Build2 (CSNBKTB2)” on page 159
v “Key Token Change (CSNBKTC)” on page 163
| v “Key Token Change2 (CSNBKTC2)” on page 166
v “Key Token Parse (CSNBKTP)” on page 169
v “Key Translate (CSNBKTR)” on page 173
| v “Key Translate2 (CSNBKTR2)” on page 175
v “Multiple Clear Key Import (CSNBCKM)” on page 179
v “PKADecrypt (CSNDPKD)” on page 182
v “PKAEncrypt (CSNDPKE)” on page 185
v “Prohibit Export (CSNBPEX)” on page 188
v “Prohibit Export Extended (CSNBPEXX)” on page 189
v “Random Number Generate (CSNBRNG)” on page 191
v “Random Number Generate Long (CSNBRNGL)” on page 193
| v “Restrict KeyAttribute (CSNBRKA)” on page 195
v “Symmetric Key Export (CSNDSYX)” on page 198
v “Symmetric Key Generate (CSNDSYG)” on page 201
v “Symmetric Key Import (CSNDSYI)” on page 205
| v “Symmetric Key Import2 (CSNDSYI2)” on page 208
©CopyrightIBMCorp.2007,2011 99

Clear Key Import (CSNBCKI)
Clear Key Import (CSNBCKI)
Use the Clear Key Import verb to import a clear DATAkey that is to be used to encipher or decipher data.
This verb can import only DATAkeys. The Clear Key Import verb accepts an 8-byte clear DATAkey,
enciphers it under the master key, and returns the encrypted DATAkey in operational form in an internal
key token.
If the clear key value does not have odd parity in the low-order bit of each byte, the verb returns a warning
value in the reason_code parameter. This verb does not adjust the parity of the key.
Note: To import 16-byte or 24-byte DATAkeys, use the Multiple Clear Key Import verb that is described in
“Multiple Clear Key Import (CSNBCKM)” on page 179.
Format
CSNBCKI(
return_code,
reason_code,
exit_data_length,
exit_data,
clear_key,
key_identifier )
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 14.
clear_key
Direction: Input Type: String
The clear_key specifies the 8-byte clear key value to import.
key_identifier
Direction: Input/Output Type: String
A64-byte string that is to receive the internal key token. “Key tokens, key labels, and key identifiers”
on page 15 describes the internal key token.
Restrictions
None
Required commands
| This verb requires the Clear Key Import/Multiple Clear Key Import - DES command (offset X'00C3') to be
| enabled in the active role.
Note: Arole with offset X'00C3' enabled can also use the Multiple Clear Key Import verb with the DES
algorithm.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCKIJ. See “Building Java
applications to use with the CCAJNI” on page 16.
100 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Clear Key Import (CSNBCKI)
The parameters for CSNBCKIJ are shown here.
Format
public native void CSNBCKIJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] clear_key,
byte[] target_key_identifier
);
Chapter5.ManagingAESandDEScryptographickeys 101

Control Vector Generate (CSNBCVG)
Control Vector Generate (CSNBCVG)
The Control Vector Generate verb builds a control vector from keywords specified by the key_type and
rule_array parameters.
Format
CSNBCVG(
return_code,
reason_code,
exit_data_length,
exit_data,
key_type,
rule_array_count,
rule_array,
reserved,
control_vector )
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 14.
key_type
Direction: Input Type: String
Astring variable containing a keyword for the key type. The keyword is eight bytes in length, left
justified, and padded on the right with space characters. It is taken from the following list:
CIPHER DATAC IKEYXLAT OPINENC
CVARDEC DATAM IMPORTER PINGEN
CVARENC DATAMV IPINENC PINVER
CVARPINE DECIPHER KEYGENKY SECMSG
CVARXCVL DKYGENKY MAC
CVARXCVR ENCIPHER MACVER
DATA EXPORTER OKEYXLAT
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left justified in 8-byte fields,
and padded on the right with blanks.All keywords must be in contiguous storage. “Key Token Build
(CSNBKTB)” on page 155 illustrates the key type and key usage keywords that can be combined in
the Control Vector Generate and Key Token Build verbs to create a control vector.
| See Figure3 on page 30 for the key usage keywords that can be specified for a given key type. The
rule_array keywords are shown here:
| AMEX-CSC DKYL0 EPINGEN KEYLN16 UKPT
| ANSIX9.9 DKYL1 EPINGENA LMTD-KEK VISA-PVV
| ANY DKYL2 EPINVER MIXED WRAP-ECB
| ANY-MAC DKYL3 EXEX NO-SPEC WRAP-ENH
| CLR8-ENC DKYL4 EXPORT NO-XPORT XLATE
| CPINENC DKYL5 GBP-PIN NOOFFSET XPORT-OK
| CPINGEN DKYL6 GBP-PINO NOT-KEK
| CPINGENA DKYL7 IBM-PIN OPEX
| CVVKEY-A DMAC IBM-PINO OPIM
| CVVKEY-B DMKEY IMEX PIN
102 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Control Vector Generate (CSNBCVG)
| DALL DMPIN IMIM REFORMAT
| DATA DMV IMPORT SINGLE
| DDATA DOUBLE INBK-PIN SMKEY
| DEXP DPVR KEY-PART SMPIN
| DIMP ENH-ONLY KEYLN8 TRANSLAT
Notes:
1. When the KEYGENKY key type is coded, either CLR8-ENC or UKPT must be specified in
rule_array.
2. When the SECMSG key_type is coded, either SMKEY or SMPIN must be specified in the
rule_array.
3. Keywords ENH-ONLY, WRAP-ECB, and WRAP-ENH were introduced with CCA4.1.0.
reserved
Direction: Input Type: String
The reserved parameter must be a variable of eight bytes of X'00'.
control_vector
Direction: Output Type: String
A16-byte string variable in application storage where the verb returns the generated control vector.
Restrictions
None
Required commands
None
Usage notes
See the key_type parameter on page 155 for an illustration of key type and key usage keywords that can
be combined in the Control Vector Generate and Key Token Build verbs to create a control vector.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCVGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCVGJ are shown here.
Format
public native void CSNBCVGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_type,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] reserved_field_1,
byte[] control_vector);
Chapter5.ManagingAESandDEScryptographickeys 103

Control Vector Translate (CSNBCVT)
Control Vector Translate (CSNBCVT)
The Control Vector Translate verb changes the control vector used to encipher an external DES key.
| Detailed information about control vectors and how to use this verb can be found inAppendixD, “Control
| vectors and changing control vectors with the Control Vector Translate verb,” on page 463.
Format
CSNBCVT(
return_code,
reason_code,
exit_data_length,
exit_data,
KEK_key_identifier,
source_key_token,
array_key_left_identifier,
mask_array_left,
array_key_right_identifier,
mask_array_right,
rule_array_count,
rule_array,
target_key_token )
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 14.
KEK_key_identifier
Direction: Input Type: String
Apointer to a string variable containing an operational key-token or the key label of an operational
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
Direction: Input Type: String
Apointer to a string variable containing the external DES key-token with the key and control vector to
be processed.
array_key_left_identifier
Direction: Input Type: String
Apointer to a string variable containing an operational DES key-token or a key label of an operational
DES key-token record that deciphers the left mask-array. The key token must contain a control vector
specifying a CVARXCVLkey-type. The CVARXCVLkey must be single length.
mask_array_left
Direction: Input Type: String
Apointer to a string variable containing the mask array enciphered under the left-array key.
array_key_right_identifier
Direction: Input Type: String
Apointer to a string variable containing an operational DES key-token or the key label of an
operational 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.
104 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Control Vector Translate (CSNBCVT)
mask_array_right
Direction: Input Type: String
Apointer to a string variable containing the mask array enciphered under the right-array key.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0, 1, or 2.
rule_array
Direction: Input Type:Array
Apointer to a string variable containing an array of keywords. The keywords are eight bytes in length
and must be left-aligned and padded on the right with space characters. The rule_array keywords are
descrobed in Table21.
Table21.KeywordsforControlVectorTranslatecontrolinformation
Keyword Description
Parityadjustment(One,optional)
ADJUST Ensuresthatalltarget-keybyteshaveoddparity.Thisisthedefault.
NOADJUST Preventstheparityofthetargetkeyfrombeingaltered.
Keyhalfprocessingmode(One,optional)
LEFT Causesan8-bytesourcekey,orthelefthalfofa16-bytesourcekey,tobeprocessedwith
theresultplacedintobothhalvesofthetargetkey.Thisisthedefault.
RIGHT Causestherighthalfofa16-bytesourcekeytobeprocessedwiththeresultplacedinto
onlytherighthalfofthetargetkey.Thelefthalfofthetargetkeyisunchanged.
BOTH Causesbothhalvesofa16-bytesourcekeytobeprocessedwiththeresultplacedinto
correspondinghalvesofthetargetkey.WhenyouusetheBOTHkeyword,themaskarray
mustbeabletovalidatethetranslationofbothhalves.
SINGLE Causesthelefthalfofthesourcekeytobeprocessedwiththeresultplacedintoonlythe
lefthalfofthetarget.Therighthalfofthetargetkeyisunchanged.
target_key_token
Direction: Input/Output Type: String
Apointer to a string variable containing an external DES key-token with the new control vector. This
key token contains the key halves with the new control vector.
Restrictions
None
Required commands
| This verb requires the Control Vector Translate command (offset X'00D6') to be enabled in the active role.
Usage notes
Consider that Control Vector Translate represents the capability to translate, by definition, the limitations on
the operations that a key can be used for, into a different set of limitations. The control vector is the heart
of security against the misuse of keys that were defined for a specific purpose. The masks that control
what the key can be translated into being able to do (the right and left masks) are themselves
single-length (8-byte), and are encrypted with DES. Therefore, the protection against translating the key to
have more power (or less power) than it did before are protected with single-DES. This reduces the
Chapter5.ManagingAESandDEScryptographickeys 105

Control Vector Translate (CSNBCVT)
security (somewhat) of a double-length DES key. You cannot decrypt the double-length key with this
approach, or gain access to a key that you did not otherwise have the rights to use. But you can make a
key which you already have access to, on a system you already have access to, more powerful than it
was before if you can break single-DES.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCVTJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCVTJ are shown here.
Format
public native void CSNBCVTJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] kek_key_identifier,
byte[] source_key_token,
byte[] array_key_left,
byte[] mask_array_left,
byte[] array_key_right,
byte[] mask_array_right,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] target_key_token);
106 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Cryptographic Variable Encipher (CSNBCVE)
Cryptographic Variable Encipher (CSNBCVE)
This verb is used to encrypt plaintext using a CVARENC key to produce ciphertext using the Cipher Block
Chaining (CBC) method. The plaintext must be a multiple of eight bytes in length.
Specify the following parameters to encrypt plaintext:
v An operational DES key-token or a key label of an operational 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 eight bytes in length.
v The plaintext with the plaintext parameter.
v The initialization vector with the initialization_vector parameter.
v Avariable for the returned ciphertext with the ciphertext parameter. The length of this field is specified
with the text_length variable.
This 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.
Format
CSNBCVE(
return_code,
reason_code,
exit_data_length,
exit_data,
c-variable_encrypting_key_identifier,
text_length,
plaintext,
initialization_vector,
ciphertext )
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 14.
c-variable_encrypting_key_identifier
Direction: Input Type: String
Apointer to a string variable containing an operational DES key-token or a key label of an operational
DES key-token record. The key token must contain a control vector that specifies a CVARENC
key-type.
text_length
Direction: Input Type: Integer
Apointer to an integer variable containing the length of the plaintext variable and the ciphertext
variable.
plaintext
Direction: Input Type: String
Apointer to is a string variable containing the plaintext to be encrypted.
initialization_vector
Chapter5.ManagingAESandDEScryptographickeys 107

Cryptographic Variable Encipher (CSNBCVE)
Direction: Input Type: String
Apointer to a string variable containing the 8-byte initialization vector that the verb uses in encrypting
the plaintext.
ciphertext
Direction: Output Type: String
Apointer to a string variable containing the ciphertext returned by the verb.
Restrictions
The text length must be a multiple of eight bytes.
The minimum length of text that the security server can process is eight bytes and the maximum is 256
bytes.
Required commands
| This verb requires the Cryptographic Variable Encipher command (offset X'00DA') to be enabled in the
| active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCVEJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCVEJ are shown here.
Format
public native void CSNBCVEJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] cvarenc_key_id,
hikmNativeInteger text_length,
byte[] plain_text,
byte[] init_vector,
byte[] cipher_text);
108 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Data Key Export (CSNBDKX)
Data Key Export (CSNBDKX)
Use the Data Key Export verb to re-encipher a data-encrypting key (key type of DATAonly) from
encryption under the master key to encryption under an exporter key-encrypting key. The re-enciphered
key is in a form suitable for export to another system.
The Data Key Export verb generates a key token with the same key length as the input token's key.
Format
CSNBDKX(
return_code,
reason_code,
exit_data_length,
exit_data,
source_key_identifier,
exporter_key_identifier,
target_key_identifier )
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 14.
source_key_identifier
Direction: Input/Output Type: String
A64-byte string for an internal key token or label that contains a data-encrypting key to be
re-enciphered. The data-encrypting key is encrypted under the master key.
exporter_key_identifier
Direction: Input/Output Type: String
A64-byte string for an internal key token or key label that contains the exporter key_encrypting key.
The data-encrypting key above will be encrypted under this exporter key_encrypting key.
target_key_identifier
Direction: Input/Output Type: String
A64-byte field that is to receive the external key token, which contains the re-enciphered key that has
been exported. The re-enciphered key can now be exchanged with another cryptographic system.
Restrictions
For security reasons, requests will fail by default if they use an equal key halves exporter to export a key
with unequal key halves. You must have access control point 'Data Key Export - Unrestricted' explicitly
enabled if you want to export keys in this manner.
Required commands
| This verb requires the Data Key Export command (offset X'010A') to be enabled in the active role.
| By also specifying the Data Key Export - Unrestricted 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).
Usage notes
None
Chapter5.ManagingAESandDEScryptographickeys 109

Data Key Export (CSNBDKX)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBDKXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBDKXJ are shown here.
Format
public native void CSNBDKXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] source_key_identifier,
byte[] exporter_key_identifier,
byte[] target_key_token
);
110 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Data Key Import (CSNBDKM)
Data Key Import (CSNBDKM)
Use the Data Key Import verb to import an encrypted source DES single-length, double-length or
triple-length DATAkey and create or update a target internal key token with the master key enciphered
source key.
Format
CSNBDKM(
return_code,
reason_code,
exit_data_length,
exit_data,
source_key_token,
importer_key_identifier,
target_key_identifier )
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 14.
source_key_token
Direction: Input Type: String
64-byte string variable containing the source key to be imported. The source key must be an external
token or null token. The external key token must indicate that a control vector is present; however, the
control vector is usually valued at zero.Adouble-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 and
double-length keys are presented in a version X'00' key token. For the null token, the verb will process
this token format as a DATAkey encrypted by the importer key and a null (all zero) control vector.
importer_key_identifier
Direction: Input/Output Type: String
A64-byte string variable containing the (IMPORTER) transport key or key label of the transport key
used to decipher the source key.
target_key_identifier
Direction: Output Type: String
A64-byte string variable containing a null key token or an internal key token. The key token receives
the imported key.
Restrictions
For security reasons, requests will fail by default if they use an equal key halves importer to import a key
with unequal key halves. You must have access control point 'Data Key Import - Unrestricted' explicitly
enabled if you want to import keys in this manner.
Required commands
This verb requires the Data Key Import command (offset X'0109') to be enabled in the active role.
| By also specifying the Data Key Import - Unrestricted 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).
Chapter5.ManagingAESandDEScryptographickeys 111

Data Key Import (CSNBDKM)
Usage notes
This verb does not adjust the key parity of the source key.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBDKMJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBDKMJ are shown here.
Format
public native void CSNBDKMJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_lengthh,
byte[] exit_data,
byte[] source_key_token,
byte[] importer_key_identifier,
byte[] target_key_identifier
);
112 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Diversified Key Generate (CSNBDKG)
Diversified Key Generate (CSNBDKG)
Use the Diversified Key Generate verb to generate a key based on the key-generating key, the processing
method, and the parameter supplied. The control vector of the key-generating key also determines the
type of target key that can be generated.
To use this verb, specify the following:
v The rule_array keyword to select the diversification process.
v The operational key-generating key from which the diversified keys are generated. The control vector
associated with this key restricts the use of this key to the key generation process. This control vector
also restricts the type of key that can be generated.
v The data and length of data used in the diversification process.
v The generated-key could be an internal token or a skeleton token containing the desired CV of the
generated-key. The generated key CV must be one that is permitted by the processing method and the
key-generating key. The generated key will be returned in this parameter.
v Akey generation method keyword.
This verb generates diversified keys as follows:
v Determines if it can support the process specified in the rule_array.
v Recovers the key-generating key and checks the key-generating key class and the specified usage of
the key-generating key.
v Determines that the control vector in the generated-key token is permissible for the specified processing
method.
v Determines that the control vector in the generated-key token is permissible by the control vector of the
key-generating key.
v Determines the required data length from the processing method and the generated-key CV. Validates
the data_length.
v Generates the key appropriate to the specific processing method.Adjusts parity of the key to odd.
Creates the internal token and returns the generated diversified key.
Format
CSNBDKG(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
generating_key_identifier,
data_length,
data,
key_identifier,
generated_key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1, 2, or 3.
Chapter5.ManagingAESandDEScryptographickeys 113

Diversified Key Generate (CSNBDKG)
rule_array
Direction: Input Type: String
The keyword that provides control information to the verb. The processing method is the algorithm
used to create the generated key. The keyword is left justified and padded on the right with blanks.
The rule_array keywords are described in Table22.
Table22.KeywordsforDiversifiedKeyGeneratecontrolinformation
Keyword Description
ProcessingMethodforgeneratingorupdatingdiversifiedkeys(Onerequired)
CLR8-ENC Specifiesthateightbytesofcleardatashallbemultiplyencryptedwiththegeneratingkey.The
generating_key_identifiermustbeaKEYGENKYkeytypewithbit19ofthecontrolvectorsetto1.
Thecontrolvectoringenerated_key_identifiermustspecifyasingle-lengthkey.Thekeytypecan
beDATA,MAC,orMACVER.
Note: CIPHERclasskeysarenotsupported.
TDES-DEC Datasuppliedcouldbe8or16bytesofcleardata.Ifthegenerated_key_identifierspecifiesa
singlelengthkey,then8-bytesofdataisTDESdecryptedunderthegenerating_key_identifier.If
thegenerated_key_identifierspecifiesadoublelengthkey,then16-bytesofdataisTDESECB
modedecryptedunderthegenerating_key_identifier.Noformattingofdataisdonebefore
encryption.Thegenerating_key_identifiermustbeaDKYGENKYkeytype,withappropriateusage
bitsforthedesiredgeneratedkey.
TDES-ENC Datasuppliedcouldbe8or16bytesofcleardata.Ifthegenerated_key_identifierspecifiesa
singlelengthkey,then8bytesofdataisTDESencryptedunderthegenerating_key_identifier.If
thegenerated_key_identifierspecifiesadoublelengthkey,then16bytesofdataisTDESECB
modeencryptedunderthegenerating_key_identifier.Noformattingofdataisdonebefore
encryption.Thegenerating_key_identifiermustbeaDKYGENKYkeytype,withappropriateusage
bitsforthedesiredgeneratedkey.Thegenerated_key_identifiercanbeasingleordoublelength
key,withaCVthatispermittedbythegenerating_key_identifier.
TDES-XOR ThisoptioncombinesthefunctionoftheexistingTDES-ENCandSESS-XORintoonestep.
Thegeneratingkeymustbealevel0DKYGENKYandcannothavereplicatedhalves.Thesession
keygeneratedmustbedoublelengthandtheallowedkeytypesareDATA,DATAC,DATAM,
DATAMV,MAC,MACVER,SMPIN,andSMKEY.Keytypemustbeallowedbythegeneratingkey
controlvector.
TDESEMV2 ThisoptionsupportsgenerationofasessionkeybytheEMV2000algorithm(ThisEMV2000
algorithmusesabranchfactorof2).Thegeneratingkeymustbealevel0DKYGENKYandcannot
havereplicatedhalves.Thesessionkeygeneratedmustbedoublelengthandtheallowedkey
typesareDATA,DATAC,DATAM,DATAMV,MAC,MACVER,SMPIN,andSMKEY.Keytypemust
beallowedbythegeneratingkeycontrolvector.
TDESEMV4 ThisoptionsupportsgenerationofasessionkeybytheEMV2000algorithm(ThisEMV2000
algorithmusesabranchfactorof4).Thegeneratingkeymustbealevel0DKYGENKYandcannot
havereplicatedhalves.Thesessionkeygeneratedmustbedoublelengthandtheallowedkey
typesareDATA,DATAC,DATAM,DATAMV,MAC,MACVER,SMPIN,andSMKEY.Keytypemust
beallowedbythegeneratingkeycontrolvector.
ProcessingMethodforupdatingadiversifiedkey(optional)
SESS-XOR SpecifiestheVISAmethodforsessionkeygeneration.Datasuppliedcanbe8or16bytesofdata
dependingonwhetherthegenerating_key_identifierisasingleordoublelengthkey.The8or16
bytesofdataisXORedwiththeclearvalueofthegenerating_key_identifier.The
generated_key_identifierhasthesamecontrolvectorasthegenerating_key_identifier.The
generating_key_identifiercanbeDATA,DATAC,,DATAM,DATAMV,MAC,orMACVERkeytypes.
| Key-wrappingmethod(One,optional)
|| USECONFG Specifiestowrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.This
| keywordisignoredforAESkeys.Thisisthedefault.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ENH Specifiestowrapthekeyusingthelegacywrappingmethod.ThiskeywordisignoredforAES
| keys.ThiskeywordwasintroducedwithCCA4.1.0.
114 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Diversified Key Generate (CSNBDKG)
Table22.KeywordsforDiversifiedKeyGeneratecontrolinformation (continued)
Keyword Description
|| WRAP-ECB Specifiestowrapthekeyusingtheenhancedwrappingmethod.ValidonlyforDESkeys.This
| keywordwasintroducedwithCCA4.1.0.
| Translationcontrol(Optional).Thisisvalidonlywithkey-wrappingmethodWRAP-ENHorwithUSECONFGwhen
| thedefaultwrappingmethodisWRAP-ENH.Thisoptioncannotbeusedonakeywithacontrolvectorvaluedto
| binaryzeros.
|| ENH-ONLY Specifiestorestrictthekeyfrombeingwrappedwiththelegacywrappingmethodafterithasbeen
| wrappedwiththeenhancedwrappingmethod.Setsbit56(ENH-ONLY)ofthecontrolvectorto1.
| ThiskeywordwasintroducedwithCCA4.1.0.
generating_key_identifier
Direction: Input/Output Type: String
The label or internal token of a key generating key. The type of key-generating key depends on the
processing method.
data_length
Direction: Input Type: Integer
The length of the data parameter that follows. Length depends on the processing method and the
generated key.
data
Direction: Input Type: String
Data input to the diversified key or session key generation process. Data depends on the processing
method and the generated_key_identifier.
key_identifier
Direction: Input/Output Type: String
This parameter is currently not used. It must be a 64-byte null token.
generated_key_identifier
Direction: Input/Output Type: String
The internal token of an operational key, a skeleton token containing the control vector of the key to be
generated, or a null token.Anull token can be supplied if the generated_key_identifier will be a
DKYGENKY with a CV derived from the generating_key_identifier.Askeleton token or internal token is
required when generated_key_identifier will not be a DKYGENKY key type or the processing method
is not SESS-XOR. For SESS-XOR, this must be a null token. On output, this parameter contains the
generated key.
Restrictions
None
Required commands
This verb requires the following commands to be enabled in the active role based on the keyword
specified for the process rule:
||||
Rule-arraykeyword Offset Command
||| CLR8-ENC X'0040' DiversifiedKeyGenerate-CLR8-ENC
||| SESS-XOR X'0043' DiversifiedKeyGenerate-SESS-XOR
Chapter5.ManagingAESandDEScryptographickeys 115

Diversified Key Generate (CSNBDKG)
||| Rule-arraykeyword Offset Command
||| TDES-DEC X'0042' DiversifiedKeyGenerate-TDES-DEC
||| TDES-ENC X'0041' DiversifiedKeyGenerate-TDES-ENC
||| TDES-XOR X'0045' DiversifiedKeyGenerate-TDES-XOR
||| TDESEMV2orTDESEMV4 X'0046' DiversifiedKeyGenerate-TDESEMV2/TDESEMV4
||| WRAP-ECBorWRAP-ENH X'013D' DiversifiedKeyGenerate-Allowwrappingoverride
|| anddefaultkey-wrapping keywords
| methodsettingdoesnot
| matchkeyword
|
| When a key-generating key of key type DKYGENKY is specified with control vector bits (19 - 22) of
| B'1111', the Diversified Key Generate - DKYGENKY - DALLcommand (offset X'0290') must also be
| enabled in the active role.
Note: Arole with offset X'0290' enabled can also use the PIN Change/Unblock verb with a DALLkey.
| 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 Diversified Key Generate - Single length or same halves command (offset X'0044').
Usage notes
Refer toAppendixD, “Control vectors and changing control vectors with the Control Vector Translate verb,”
on page 463 for information on the control vector bits for the DKG key generating key.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBDKGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBDKGJ are shown here.
Format
public native void CSNBDKGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] generating_key_identifier,
hikmNativeInteger data_length,
byte[] data,
byte[] data_decrypting_key_identifier,
byte[] generated_key_identifier
);
116 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Export (CSNBKEX)
Key Export (CSNBKEX)
DATA
Use the Key Export verb to re-encipher any type of key (except an IMP-PKA) from encryption under a
master key variant to encryption under the same variant of an exporter key-encrypting key. The
re-enciphered key can be exported to another system.
If the key to be exported is a DATAkey, the Key Export verb generates a key token with the same key
length as the input token's key.
This verb supports the no-export bit that the Prohibit Export verb sets in the internal token.
Format
CSNBKEX(
return_code,
reason_code,
exit_data_length,
exit_data,
key_type,
source_key_identifier,
exporter_key_identifier,
target_key_identifier )
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 14.
key_type
Direction: Input Type: String
The parameter is an 8-byte field that contains either a key type value or the keyword TOKEN. The
keyword is left-justified and padded on the right with blanks.
If the key type is TOKEN, CCAdetermines the key type from the control vector (CV) field in the
internal key token provided in the source_key_identifier parameter.
Key type values for the Key Export verb are:
CIPHER EXPORTER OPINENC
DATA IMPORTER PINGEN
DATAC IKEYXLAT PINVER
DATAM IPINENC TOKEN
DATAMV MAC
DECIPHER MACVER
ENCIPHER OKEYXLAT
For information about the meaning of the key types, see Table1 on page 27.
source_key_identifier
Direction: Input Type: String
A64-byte string of the internal key token that contains the key to be re-enciphered. This parameter
must identify an internal key token in application storage, or a label of an existing key in the DES key
storage file.
If you supply TOKEN for the key_type parameter, CCAlooks at the control vector in the internal key
token and determines the key type from this information. If you supply TOKEN for the key_type
parameter and supply a label for this parameter, the label must be unique in the DES key storage file.
Chapter5.ManagingAESandDEScryptographickeys 117

Key Export (CSNBKEX)
exporter_key_identifier
Direction: Input/Output Type: String
A64-byte string of the internal key token or key label that contains the exporter key-encrypting key.
This parameter must identify an internal key token in application storage, or a label of an existing key
in the key storage file.
If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting
key itself (not the key-encrypting key variant) is used to encipher the generated key.
Control vectors are explained in “Control vector” on page 25 and the NOCV bit is shown in Table121
on page 423.
target_key_identifier
Direction: Input/Output Type: String
The 64-byte field external key token that contains the re-enciphered key. The re-enciphered key can
be exchanged with another cryptographic system.
Restrictions
For security reasons, requests will fail by default if they use an equal key halves exporter to export a key
with unequal key halves. You must have access control point 'Key Export - Unrestricted' explicitly enabled
if you want to export keys in this manner.
Required commands
| This verb requires the Key Export command (offset X'0013') to be enabled in the active role.
| By also specifying the Key Export - Unrestricted 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).
Usage notes
For Key Export, you can use the following combinations of parameters:
v Avalid key type in the key_type parameter and an internal key token in the source_key_identifier
parameter. The key type must be equivalent to the control vector specified in the internal key token.
v Akey_type parameter of TOKEN and an internal key token in the source_key_identifier parameter. The
source_key_identifier can be a label with TOKEN only if the label name is unique in the key storage.
The key type is extracted from the control vector contained in the internal key token.
v Avalid key type in the key_type parameter, and a label in the source_key_identifier parameter.
If internal key tokens are supplied in the source_key_identifier or exporter_key_identifier parameters, the
key in one or both tokens can be re-enciphered. This occurs if the master key was changed since the
internal key token was last used. The return and reason codes that indicate this do not indicate which key
was re-enciphered. Therefore, assume both keys have been re-enciphered.
Existing internal tokens created with key type MACD must be exported with either a TOKEN or DATAM
key type. The external CV will be DATAM CV. The MACD key type is not supported.
To export a double-length MAC generation or MAC verification key, it is recommended that a key type of
TOKEN be used.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKEXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
118 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Export (CSNBKEX)
The parameters for CSNBKEXJ are shown here.
Format
public native void CSNBKEXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_type,
byte[] source_key_identifier,
byte[] exporter_key_identifier,
byte[] target_key_token
);
Chapter5.ManagingAESandDEScryptographickeys 119

Key Generate (CSNBKGN)
Key Generate (CSNBKGN)
Use the Key Generate verb to generate anAES key of type DATA, or either one or two odd parity DES
keys of any type. The DES keys can be single-length (8-byte), double-length (16-byte), or, in the case of
DATAkeys, triple-length (24-byte). TheAES keys can be 16, 24 or 32 bytes in length. The Key Generate
verb does not produce keys in clear form; all keys are returned in encrypted form. When two keys are
generated (DES only), each key has the same clear value, although this clear value is not exposed
outside the secure cryptographic feature.
ForAES, the verb returns only one copy of the key, enciphered under theAES master key. 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.
This verb returns the key to the application program that called it and the application program can then
use the CCAkey storage verbs to store the key in the key storage file.
Format
CSNBKGN(
return_code,
reason_code,
exit_data_length,
exit_data,
key_form,
key_length,
key_type_1,
key_type_2,
kek_key_identifier_1,
kek_key_identifier_2,
generated_key_identifier_1,
generated_key_identifier_2 )
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 14.
key_form
Direction: Input Type: String
A4-byte keyword that defines the type of key you want generated. This parameter also specifies if
each key should be returned for either operational, importable, or exportable use. The keyword must
be in a 4-byte field, left-justified, and padded with blanks.
The possible key forms are:
Operational (OP)
The key is used for cryptographic operations on the local system. Operational keys are protected
by master key variants and can be stored in the CCAkey storage file or held by applications in
internal key tokens.
Importable (IM)
The key is stored with a file or sent to another system. Importable keys are protected by importer
key-encrypting keys.
Exportable (EX)
The key is transported or exported to another system and imported there for use. Exportable keys
are protected by exporter key-encrypting keys and cannot be used by CCAverb.
120 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Generate (CSNBKGN)
Importable and exportable keys are contained in external key tokens. For more information on key
tokens, refer to “Key token” on page 21.
The first two characters refer to key_type_1. The next two characters refer to key_type_2.
The following keywords are allowed: OP, IM, EX, OPIM, OPEX, IMEX, EXEX, OPOP, and IMIM. See
Table23 for their meanings.
Table23.KeywordsfortheKeyGenerateverbkey_formparameter
Keyword Description
EX Onekeythatcanbesenttoanothersystem.
EXEX Akeypair;bothkeystobesentelsewhere,possiblyforexportingtotwodifferentsystems.Thekey
pairhasthesameclearvalue.
IM Onekeythatcanbelocallyimported.Thekeycanlaterbeimportedontothissystemtomakeit
operational.
IMEX Akeypairtobeimported;onekeytobeimportedlocallyandonekeytobesentelsewhere.Bothkeys
havethesameclearvalue.
IMIM Akeypairtobeimported;bothkeystobeimportedlocallyatalatertime.
OP Oneoperationalkey.Thekeyisreturnedtothecallerinthekeytokenformat.
OPEX Akeypair;onekeythatisoperationalandonekeytobesentfromthissystem.Bothkeyshavethe
sameclearvalue.
OPIM Akeypair;onekeythatisoperationalandonekeytobeimportedtothelocalsystem.Bothkeyshave
thesameclearvalue.Ontheothersystem,theexternalkeytokencanbeimportedtomakeit
operational.
OPOP Akeypair;normallywithdifferentcontrolvectorvalues.
The key forms are defined as follows:
Operational (OP)
The key value is enciphered under a master key. The result is placed into an internal key
token. The key is then operational at the local system.
Importable (IM)
The key value is enciphered under an importer key-encrypting key. The result is placed into an
external key token.
Exportable (EX)
The key value is enciphered under an exporter key-encrypting key. The result is placed into an
external key token. The key can then be transported or exported to another system and
imported there for use. This key form cannot be used by any CCAverb.
The keys are placed into tokens that the generated_key_identifier_1 and generated_key_identifier_2
parameters identify.
Valid key type combinations depend on the key form. See Table27 for valid key combinations.
key_length
Direction: Input Type: String
| An 8-byte value that defines the length of the key as being 8, 16, 24 or 32 bytes. The keyword must
| be left-justified and padded on the right with blanks. You must supply one of the key length values in
| the key_length parameter.
| Table24 on page 122 lists the key lengths used for various key types.
Chapter5.ManagingAESandDEScryptographickeys 121

Key Generate (CSNBKGN)
|| Table24.KeylengthvaluesfortheKeyGenerateverb. KeylengthvaluesfortheKeyGenerateverb
||| Value Description Algorithm
||| SINGLE,SINGLE-RorKEYLN8 Singlelength(8-byteor64-bit)key DES
||| DOUBLEorKEYLN16 Doublelength(16-byteor128-bit)key AESorDES
||| KEYLN24 Triplelength(24-byteor192-bit)key AESorDES
||| KEYLN32 32-byte(256-bit)key AES
|
| AES keys allow only KEYLN16, KEYLN24, and KEYLN32. To generate a 128-bitAES key, specify
| key_length as KEYLN16. For 192-bitAES keys specify key_length as KENLN24.A256-bitAES key
| requires a key_length of KEYLN32.AllAES keys are DATAkeys.
Keys with a length of 32 bytes have four 8-byte key parts. This key length is valid only forAES keys.
To generate a 32-byteAES key with four different values to be the basis of each key part, specify
key_length as KEYLN32.
To generate a single-length key, specify key_length as SINGLE or KEYLN8.
| Double-length (16-byte) keys have an 8-byte left half and an 8-byte right half. Both halves can have
| identical clear values or not. If you want the same value to be used in both key halves (called
| replicated key values), specify a key_length of SINGLE, SINGLE-R or KEYLN8. If you want different
| values to be the basis of each key half, specify a key_length of DOUBLE or KEYLN16.
| Triple-length (24-byte) keys have three 8-byte key parts. This key length is valid for DATAkeys only. To
| generate a triple-length DATAkey with three different values to be the basis of each key part, specify a
| key_length of KEYLN24.
| Use SINGLE/SINGLE-R if you want to create a DES transport key that you would use to exchange
| DATAkeys with a PCF system. Because PCF does not use double-length transport keys, specify
| SINGLE so that the effects of multiple encipherment are nullified.
| When generating anAKEK, the key_length parameter is ignored. TheAKEK key length (8-byte or
| 16-byte) is determined by the skeleton token created by the Key Token Build verb and provided in the
| generated_key_identifier_1 parameter.
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. ForAES keys, the length is an explicit field in the
token. Table25shows the valid key lengths for each key type.An X indicates that a key length is
permitted for a key type.AY indicates that the key generated will be a double-length key with
replicated key values. It is preferred that SINGLE-R be used for this result.
Table25.KeyGenerate-keylengthsforeachkeytype
Single Double Triple
KeyType (KEYLN8) Single-R (KEYLN16) (KEYLN24) (KEYLN32)
X X X
AES X X X
AESTOKEN
MAC X X
MACVER X X
DATA X X X
122 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Generate (CSNBKGN)
Table25.KeyGenerate-keylengthsforeachkeytype (continued)
Single Double Triple
KeyType (KEYLN8) Single-R (KEYLN16) (KEYLN24) (KEYLN32)
DATAM X
DATAMV X
X
EXPORTER Y X X
IMPORTER Y X X
IKEYXLAT Y X X
OKEYXLAT Y X X
CIPHER X X
DECIPHER X X
ENCIPHER X X
IPINENC Y X X
OPINENC Y X X
PINGEN Y X X
PINVER Y X X
CVARDEC* X X
CVARENC* X X
CVARPINE* X X
CVARXCVL* X X
CVARXCVR* X X
DKYGENKY* X X X
KEYGENKY* X X
Note: Key types marked with an asterisk (*) are requested through the use of the TOKEN keyword
and specifying a proper control vector in a key token.
key_type_1
Direction: Input Type: String
An 8-byte keyword from the following group:
| v AESDATA,AESTOKEN, CIPHER, DATA, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER,
| EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN,
| and PINVER
v or the keyword TOKEN
For information on the meaning of the key types, see Table1 on page 27.
Use the key_type_1 parameter for the first, or only key, that you want generated. The keyword must
be left-justified and padded with blanks. Valid type combinations depend on the key form.
Chapter5.ManagingAESandDEScryptographickeys 123

Key Generate (CSNBKGN)
If key_type_1 is TOKEN, CCAexamines the control vector (CV) field in the generated_key_identifier_1
parameter to derive the key type. When key_type_1 is TOKEN, CCAdoes not check for the length of
the key for DATAkeys. Instead, it uses the key_length parameter to determine the length of the key.
Use theAESTOKEN keyword forAES keys, or the TOKEN keyword for DES keys to indicate that the
verb should determine the key type from the key token that you supply. ForAES, 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 Table26 on page 126 and Table27.
Key types can have mandatory key forms. For example, CVARENC keys must be generated in
pairs with CVARDEC keys. The reason is that a CVARENC key can only be used for encryption, and
without a CVARDEC key you cannot decrypt the data. See Table26 and Table27 for valid key type
and key form combinations.
key_type_2
Direction: Input Type: String
An 8-byte keyword from the following group:
| v AESDATA,AESTOKEN, CIPHER, DATA, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER,
| EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN,
| and PINVER
v or the keyword TOKEN
For information on the meaning of the key types, see Table1 on page 27.
Use the key_type_2 parameter for a key pair, which is shown in Table27 on page 126. The keyword
must be left-justified and padded with blanks. Valid type combinations depend on the key form.
If key_type_2 is TOKEN, CCAexamines the control vector (CV) field in the generated_key_identifier_2
parameter to derive the key type. When key_type_2 is TOKEN, CCAdoes not check for the length of
the key for DATAkeys. Instead, it uses the key_length parameter to determine the length of the key.
If you want only one key to be generated, specify the key_type_2 and KEK_key_identifier_2 as binary
zeros.
See Table26 on page 126 and Table27 on page 126 for valid key type and key form combinations.
KEK_key_identifier_1
Direction: Input/Output Type: String
A64-byte string of an internal key token containing the importer or exporter key-encrypting key, or a
key label. If you supply a key label that is less than 64-bytes, it must be left-justified and padded with
blanks. KEK_key_identifier_1 is required for a key_form of IM, EX, IMEX, EXEX, or IMIM.
If the key_form is OP, OPEX, OPIM, or OPOP, the KEK_key_identifier_1 is null.
If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting
key itself (not the key-encrypting key variant) is used to encipher the generated key.
Control vectors are explained in “Control vector” on page 25 and the NOCV bit is shown in Table121
on page 423.
This parameter is not used when generatingAES keys, and should point to null key-tokens.
KEK_key_identifier_2
Direction: Input/Output Type: String
A64-byte string of an internal key token containing the importer or exporter key-encrypting key, or a
key label of an internal token. If you supply a key label that is less than 64-bytes, it must be
left-justified and padded with blanks. KEK_key_identifier_2 is required for a key_form of OPIM, OPEX,
IMEX, IMIM, or EXEX. This field is ignored for key_form keywords OP, IM and EX.
124 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Generate (CSNBKGN)
If the NOCV bit is on in the internal key token containing the key-encrypting key, the key-encrypting
key itself (not the key-encrypting key variant) is used to encipher the generated key.
Control vectors are explained in “Control vector” on page 25 and the NOCV bit is shown in Table121
on page 423.
This parameter is not used when generatingAES keys, and should point to null key-tokens.
generated_key_identifier_1
Direction: Input/Output Type: String
This parameter specifies either a generated:
v Internal key token for an operational key form, or
v External key token containing a key enciphered under the kek_key_identifier_1 parameter.
If you specify a key_type_1 of TOKEN, then this field contains a valid token of the key type you want
to generate. Otherwise, on input, this parameter must be binary zeros. See key_type_1 for a list of
valid key types.
If you specify a key_type_1 of IMPORTER or EXPORTER and a key_form of OPEX, and if the
generated_key_identifier_1 parameter contains a valid internal token of the SAME type, the NOCV bit,
if on, is propagated to the generated key token.
Using theAESTOKEN 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 theAESTOKEN or TOKEN keyword, you must identify a
null key token in the generated key identifier parameters on input.
generated_key_identifier_2
Direction: Input/Output Type: String
This parameter specifies a generated external key token containing a key enciphered under the
kek_key_identifier_2 parameter.
If you specify a key_type_2 of TOKEN, then this field contains a valid token of the key type you want
to generate. Otherwise, on input, this parameter must be binary zeros. See key_type_1 for a list of
valid key types.
The token can be an internal or external token.
Using theAESTOKEN 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 theAESTOKEN or TOKEN keyword, you must identify a
null key token in the generated key identifier parameters on input.
Restrictions
None
Required commands
Depending on the key_type and key_form parameters selected, the verb could require one or more of
these commands to be enabled in the active role:
|||
Offset Command
|| X'008C' KeyGenerate-OPIM_OPEX_IMEX_etc.
|| X'008E' KeyGenerate-OP_IM_EX
|| X'00D7' KeyGenerate-OPIM_OPEX_IMEX_etc.extended
|| X'00DB' KeyGenerate-SINGLE-R
|
Chapter5.ManagingAESandDEScryptographickeys 125

Key Generate (CSNBKGN)
Note: Arole with offset X'00DB' enabled can also use the Remote Key Export verb.
Usage notes
| Table26 shows the valid key type and key form combinations for a single key. Key types marked with an
| '*' must be requested through the specification of a proper control vector in a key token and through the
| use of the TOKEN keyword. See alsoAppendixC, “Key forms and types used in the Key Generate verb,”
| on page 459.
| Note: Not all key types are valid on all hardware. See Table1 on page 27.
For key typeAES, only key form OP is supported.AES keys cannot be generated in pairs.
Table26.KeywordsforKeyGenerate,validkeytypesandkeyformsforasinglekey
KeyType1 KeyType2 OP IM EX
||||| AESDATA Notapplicable X X X
DATA Notapplicable X X X
DATAC* Notapplicable X X X
DATAM Notapplicable X X X
DKYGENKY* Notapplicable X X X
KEYGENKY* Notapplicable X X X
MAC Notapplicable X X X
PINGEN Notapplicable X X X
Table27 shows the valid key type and key form combinations for a key pair. Key types marked with an "*"
must be requested through the specification of a proper control vector in a key token and through the use
of the TOKEN keyword.
Table27.KeywordsforKeyGenerate,validkeytypesandkeyformsforakeypair
KeyType1 KeyType2 OPEX EXEX OPIM,OPOP, IMEX
IMIM
CIPHER CIPHER X X X X
CIPHER DECIPHER X X X X
CIPHER ENCIPHER X X X X
CVARDEC* CVARENC* X X
CVARDEC* CVARPINE* X X
CVARENC* CVARDEC* X X
CVARENC* CVARXCVL* X X
CVARENC* CVARXCVR* X X
CVARXCVL* CVARENC* X X
CVARXCVR* CVARENC* X X
CVARPINE* CVARDEC* X X
DATA DATA X X X X
DATA DATAXLAT X X X
DATAC* DATAC* X X X X
DATAM DATAM X X X X
DATAM DATAMV X X X X
126 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Generate (CSNBKGN)
Table27.KeywordsforKeyGenerate,validkeytypesandkeyformsforakeypair (continued)
KeyType1 KeyType2 OPEX EXEX OPIM,OPOP, IMEX
IMIM
DATAXLAT DATAXLAT X X X
DECIPHER CIPHER X X X X
DECIPHER ENCIPHER X X X X
DKYGENKY* DKYGENKY* X X X X
ENCIPHER CIPHER X X X X
ENCIPHER DECIPHER X X X X
EXPORTER IKEYXLAT X X X
EXPORTER IMPORTER X X X
IKEYXLAT EXPORTER X X X
IKEYXLAT OKEYXLAT X X X
IMPORTER EXPORTER X X X
IMPORTER OKEYXLAT X X X
IPINENC OPINENC X X X X
KEYGENKY* KEYGENKY* X X X X
MAC MAC X X X X
MAC MACVER X X X X
OKEYXLAT IKEYXLAT X X X
OKEYXLAT IMPORTER X X X
OPINENC IPINENC X X X X
OPINENC OPINENC X
PINVER PINGEN X X X
PINGEN PINVER X X X
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKGNJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKGNJ are shown here.
Format
public native void CSNBKGNJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
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
);
Chapter5.ManagingAESandDEScryptographickeys 127

Key Generate2 (CSNBKGN2)
Key Generate2 (CSNBKGN2)
|
| Use the Key Generate2 verb to generate either one or two keys of any type. This verb does not produce
| keys in clear form and all keys are returned in encrypted form. When two keys are generated, each key
| has the same clear value, although this clear value is not exposed outside the secure cryptographic
| feature.
| This verb returns variable-length CCAkey tokens and uses theAESKW wrapping method.
| This verb supports HMAC keys. Operational keys will be encrypted under theAES master key.
Format
|
||
CSNBKGN2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| clear_key_bit_length,
| key_type_1,
| key_type_2,
| key_name_1_length,
| key_name_1,
| key_name_2_length,
| key_name_2,
| user_associated_data_1_length,
| user_associated_data_1,
| user_associated_data_2_length,
| user_associated_data_2,
| key_encrypting_key_identifier_1_length,
| key_encrypting_key_identifier_1,
| key_encrypting_key_identifier_2_length,
| key_encrypting_key_identifier_2,
| generated_key_identifier_1_length,
| generated_key_identifier_1,
| generated_key_identifier_2_length,
| generated_key_identifier_2 )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 2.
| rule_array
|| Direction: Input Type: String
| The rule_array contains keywords that provide control information to the verb. The keywords must be
| in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on
| the right with blanks. The rule_array keywords are described in Table28.
|| Table28.KeywordsforKeyGenerate2controlinformation
|| Keyword Description
| Tokenalgorithm(Required)
128 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Generate2 (CSNBKGN2)
| Table28.KeywordsforKeyGenerate2controlinformation (continued)
|| Keyword Description
|| HMAC SpecifiestoimportanHMACkeytoken.
| Keyform(One,required)
|| OP Specifiesthatonecopyofthekeyisgenerated.Thekeywillbeanoperationalkeyofthekeytype
| specifiedbythekey_type_1parameterandisreturnedinthegenerated_key_identifier_1parameter.
|| OPOP Specifiesthattwocopiesofthekeyaregenerated.Thefirstkeywillbeanoperationalkeyofthekey
| typespecifiedbythekey_type_1parameterandisreturnedinthegenerated_key_identifier_1
| parameter.Thesecondkeywillbeanoperationalkeyofthekeytypespecifiedbythekey_type_2
| parameterandisreturnedinthegenerated_key_identifier_2parameter.
|
| clear_key_bit_length
|| Direction: Input Type: Integer
| Apointer to an integer variable containing the number of clear-key bits to randomly generate and
| return encrypted in the generated key or keys. The value can be 80 - 2048.
| key_type_1
|| Direction: Input Type: String
| Use the key_type_1 parameter for the first, or only key, that you want generated. The keyword must
| be left-justified and padded with blanks. Valid type combinations depend on the key form.
| The 8-byte keyword for the key_type_1 parameter can be one of the following:
| v MAC
| v MACVER
| v TOKEN
| If key_type_1 is TOKEN, the associated data in the generated_key_identifier_1 parameter is used to
| derive the key type.
| key_type_2
|| Direction: Input Type: String
| Use the key_type_2 parameter for a key pair, which is shown in Table29 on page 132. The keyword
| must be left-justified and padded with blanks. Valid type combinations depend on the key form.
| The 8-byte keyword for the key_type_2 parameter can be one of the following:
| v MAC
| v MACVER
| v TOKEN
| If key_type_2 is TOKEN, the associated data in the generated_key_identifier_2 parameter is used to
| derive the key type.
| When only one key is being generated, this parameter is ignored.
| key_name_1_length
|| Direction: Input Type: Integer
| The length of the key_name parameter for generated_key_identifier_1. Valid values are 0 and 64.
| key_name_1
|| Direction: Input Type: String
| A64-byte key store label to be stored in the associated data structure of generated_key_identifier_1.
| key_name_2_length
|
Chapter5.ManagingAESandDEScryptographickeys 129

Key Generate2 (CSNBKGN2)
|| Direction: Input Type: Integer
| The length of the key_name parameter for generated_key_identifier_2. Valid values are 0 and 64.
| key_name_2
|| Direction: Input Type: String
| A64-byte key store label to be stored in the associated data structure of generated_key_identifier_2.
| When only one key is being generated, this parameter is ignored.
| user_associated_data_1_length
|| Direction: Input Type: Integer
| The length of the user-associated data parameter for generated_key_identifier_1. The valid values are
| 0 - 255 bytes.
| user_associated_data_1
|| Direction: Input Type: String
| User-associated data to be stored in the associated data structure for generated_key_identifier_1.
| user_associated_data_2_length
|| Direction: Input Type: Integer
| The length of the user-associated data parameter for generated_key_identifier_2. The valid values are
| 0 - 255 bytes.
| user_associated_data_2
|| Direction: Input Type: String
| User associated data to be stored in the associated data structure for generated_key_identifier_2.
| When only one key is being generated, this parameter is ignored.
| key_encrypting_key_identifier_1_length
|| Direction: Input Type: Integer
| The byte length of the key_encrypting_key_identifier_1 parameter. This value must be 0.
| key_encrypting_key_identifier_1
|| Direction: Input Type: String
| This parameter is ignored.
| key_encrypting_key_identifier_2_length
|| Direction: Input Type: Integer
| The byte length of the key_encrypting_key_identifier_2 parameter. This value must be 0.
| key_encrypting_key_identifier_2
|| Direction: Input/Output Type: String
| This parameter is ignored.
| generated_key_identifier_1_length
|| Direction: Input/Output Type: Integer
| On input, the length of the buffer for the generated_key_identifier_1 parameter in bytes. The minimum
| value is 120 bytes and the maximum value is 725 bytes.
| On output, the parameter will hold the actual length of the generated_key_identifier_1.
130 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Generate2 (CSNBKGN2)
| generated_key_identifier_1
|| Direction: Input/Output Type: String
| The buffer for the first generated key token.
| On input, if you specify a key_type_1 of TOKEN, then the buffer contains a valid key token of the key
| type you want to generate. The key token must be left justified in the buffer. Otherwise, this parameter
| must be binary zeros. See key_type_1 for a list of valid key types.
| On output, the buffer contains the generated key token.
| generated_key_identifier_2_length
|| Direction: Input/Output Type: Integer
| On input, the length of the buffer for the generated_key_identifier_2 in bytes. The minimum value is
| 120 bytes and the maximum value is 725 bytes.
| generated_key_identifier_2
|| Direction: Input/Output Type: String
| The buffer for the second generated key token.
| On input, if you specify a key_type_2 of TOKEN, then the buffer contains a valid key token of the key
| type you want to generate. The key token must be left justified in the buffer. Otherwise, this parameter
| must be binary zeros. See key_type_2 for a list of valid key types.
| On output, the buffer contains the generated key token.
| When only one key is being generated, this parameter is ignored
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| Depending on the key_type and key_form parameters selected, the verb could require one or more of
| these commands to be enabled in the active role:
|||
Offset Command
|| X'00EA' KeyGenerate2-OP_EX_IM
|| X'00EB' KeyGenerate2-OPOP_OPIM_OPEX_etc.
|
Usage notes
|
| The key forms are defined as follows:
| Operational (OP)
| Specifies that one copy of the key is generated. The key will be an operational key of the key type
| specified by the key_type_1 parameter and is returned in the generated_key_identifier_1
| parameter.
|| OPOP Two copies of the key are generated. The first key will be an operational key of the key type
| specified by the key_type_1 parameter and is returned in the generated_key_identifier_1
| parameter. The second key will be an operational key of the key type specified by the key_type_2
| parameter and is returned in the generated_key_identifier_2 parameter.
| This table lists the valid key type and key forms for HMAC keys
Chapter5.ManagingAESandDEScryptographickeys 131

Key Generate2 (CSNBKGN2)
|| Table29.KeyGenerate2validkeytypeandkeyformsforHMACkeys
|||| KeyType1 KeyType2 OP OPOP
|||| MAC Notapplicable X
|||| MAC MAC X
|||| MAC MACVER X
|||| MACVER MAC X
|
| The following table shows the access control points that control the function of this verb.
|| Table30.RequiredaccesscontrolpointsforKeyGenerate2
||| KeyForm KeyType Accesscontrolpoint
||| OP MAC,MACVER KeyGenerate2–OP,EX,IM
||| OPOP MAC,MACVER KeyGenerate2–OPOP,OPIM,OPEX,etc.
|
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBKGN2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBKGN2J are shown here.
|
| Format
| public native void CSNBKGN2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| byte[] clear_key_bit_length,
| byte[] key_type_1,
| byte[] key_type_2,
| byte[] key_name_1_length,
| byte[] key_name_1,
| byte[] key_name_2_length,
| byte[] key_name_2,
| byte[] user_associated_data_1_length,
| byte[] user_associated_data_1,
| byte[] user_associated_data_2_length,
| byte[] user_associated_data_2,
| byte[] key_encrypting_key_identifier_1_length,
| byte[] key_encrypting_key_identifier_1,
| byte[] key_encrypting_key_identifier_2_length,
| byte[] key_encrypting_key_identifier_2,
| byte[] generated_key_identifier_1_length,
| byte[] generated_key_identifier_1,
| byte[] generated_key_identifier_2_length,
|| byte[] generated_key_identifier_2);
|
|
|
132 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Import (CSNBKIM)
Key Import (CSNBKIM)
Use the Key Import verb to re-encipher a key from encryption under an importer key-encrypting key to
encryption under the master key. The re-enciphered key is in operational form.
Choose one of the following options:
v Specify the key_type parameter as TOKEN and specify the external key token in the
source_key_identifier parameter. The key type information is determined from the control vector in the
external key token.
v Specify a key type in the key_type parameter and specify an external key token in the
source_key_identifier parameter. The specified key type must be compatible with the control vector in
the external key token.
v Specify a valid key type in the key_type parameter and a null key token in the source_key_identifier
parameter. The default control vector for the key_type specified will be used to process the key.
For DATAkeys, this verb generates a key of the same length as that contained in the input token.
Format
CSNBKIM(
return_code,
reason_code,
exit_data_length,
exit_data,
key_type,
source_key_identifier,
importer_key_identifier,
target_key_identifier )
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 14.
key_type
Direction: Input Type: String
The type of key you want to re-encipher under the master key. Specify an 8-byte keyword or the
keyword TOKEN. The keyword must be left-justified and padded on the right with blanks.
If the key type is TOKEN, CCAdetermines the key type from the control vector (CV) field in the
external key token provided in the source_key_identifier parameter.
TOKEN is never allowed when the importer_key_identifier parameter is NOCV.
Key type values for the Key Import verb are:
CIPHER EXPORTER OKEYXLAT
DATA IMPORTER OPINENC
DATAC IKEYXLAT PINGEN
DATAM IPINENC PINVER
DATAMV MAC TOKEN
DECIPHER MACVER
ENCIPHER MACD
For information on the meaning of the key types, see Table1 on page 27.
We recommend using key type of TOKEN when importing double-length MAC and MACVER keys.
source_key_identifier
Chapter5.ManagingAESandDEScryptographickeys 133

Key Import (CSNBKIM)
Direction: Input Type: String
The key you want to re-encipher under the master key. The parameter is a 64-byte field for the
enciphered key to be imported containing either an external key token or a null key token. If you
specify a null token, the token is all binary zeros, except for a key in bytes 16-23 or 16-31, or in bytes
16-31 and 48-55 for triple-length DATAkeys. Refer to Table123 on page 425.
If key type is TOKEN, this field might not specify a null token.
This verb supports the no-export function in the CV.
importer_key_identifier
Direction: Input/Output Type: String
The importer key-encrypting key that the key is currently encrypted under. The parameter is a 64-byte
area containing either the key label of the key in the cryptographic key data set or the internal key
token for the key. If you supply a key label that is less than 64-bytes, it must be left-justified and
padded with blanks.
Note: If you specify a NOCV importer in the importer_key_identifier parameter, the key to be imported
must be enciphered under the importer key itself.
target_key_identifier
Direction: Input/Output Type: String
This parameter is the generated re-enciphered key. The parameter is a 64-byte area that receives the
internal key token for the imported key.
If the imported key TYPE is IMPORTER or EXPORTER and the token key TYPE is the same, the
target_key_identifier parameter changes direction to both input and output. If the application passes a
valid internal key token for an IMPORTER or EXPORTER key in this parameter, the NOCV bit is
propagated to the imported key token.
Restrictions
For security reasons, requests will fail by default if they use an equal key halves importer to import a key
with unequal key halves. You must have access control point 'Key Import - Unrestricted' explicitly enabled
if you want to import keys in this manner.
Required commands
| This verb requires the Key Import command (offset X'0012') to be enabled in the active role.
| By also enabling the Key Import - Unrestricted 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).
Usage notes
Use of NOCV keys are controlled by an access control point in the CEX3C. Creation of NOCV
key-encrypting keys is available only for standard IMPORTERs and EXPORTERs.
This verb will mark an imported KEK as a NOCV-KEK KEK:
v If a token is supplied in the target token field, it must be a valid importer or exporter token. If the token
fails token validation, processing continues, but the NOCV flag will not be copied
v The source token (key to be imported) must be a importer or exporter with the default control vector.
v If the target token is valid and the NOCV flag is on and the source token is valid and the control vector
of the target token is exactly the same as the source token, the imported token will have the NOCV flag
set on.
134 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Import (CSNBKIM)
v If the target token is valid and the NOCV flag is on and the source token is valid and the control vector
of the target token is NOT exactly the same as the source token, a return code will be given.
v All other scenarios will complete successfully, but the NOCV flag will not be copied
The software bit used to mark the imported token with export prohibited is not supported on a CEX3C. The
internal token for an export prohibited key will have the appropriate control vector that prohibits export.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKIMJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKIMJ are shown here.
Format
public native void CSNBKIMJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_type,
byte[] source_key_token,
byte[] importer_key_identifier,
byte[] target_key_identifier
);
Chapter5.ManagingAESandDEScryptographickeys 135

Key Part Import (CSNBKPI)
Key Part Import (CSNBKPI)
Use the Key Part Import verb to combine, by XORing, the clear key parts of any key type and return the
combined key value either in an internal token or as an update to the key storage file.
| Before you use the Key Part Import verb for the first key part, you must use the Key Token Build or Key
| Token Build2 verb to create the internal key token into which the key will be imported. Subsequent key
| parts are combined with the first part in internal token form or as a label from the key storage file.
| The preferred way to specify key parts is FIRST,ADD-PART, and COMPLETE in the rule_array. Only
| when the combined key parts have been marked as COMPLETE can the key token be used in any
| cryptographic operation. The partial key can be passed to the Key Token Change or Key Token Change2
| verb for re-encipherment, in case building the key was started during a master key change operation. The
| partial key can be passed to the Key Token Parse verb, in order to discover how the key token was
| originally specified, if researching an old partial key. Partial keys can also be passed to the Key Test, Key
| Test2, and Key Test Extended verbs.
Key parts can also be specified as FIRST, MIDDLE, or LAST in the rule_array.ADD-PART or MIDDLE can
be executed multiple times for as many key parts as necessary. Only when the LAST part has been
combined can the key token be used in any other service.
New applications should employ theADD-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.
The Key Part Import verb can also be used to import a key without using key parts. Call the Key Part
Import verb FIRST with key part value X'0000...' then call the Key Part Import verb LAST with the
complete value.
Keys created using this service have odd parity. The FIRST key part is adjusted to odd parity.All
subsequent key parts are adjusted to even parity before being combined.
Format
CSNBKPI(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_part,
key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1 or 2.
rule_array
Direction: Input Type: String
136 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Part Import (CSNBKPI)
The keyword that provides control information to the verb. The keywords must be eight bytes of
contiguous storage with the keyword left-justified in its 8-byte location and padded on the right with
blanks. The rule_array keywords are described in Table31.
Table31.KeywordsforKeyPartImportcontrolinformation
Keyword Description
Keypart(One,required)
FIRST Thiskeywordspecifiesthataninitialkeypartisbeingentered.Thisverbreturnsthiskey-part
encryptedbythemasterkeyinthekeytokenthatyousupplied.
ADD-PART Thiskeywordspecifiesthatadditionalkey-partinformationisprovided.
COMPLETE Thiskeywordspecifiesthatthekey-partbitshallbeturnedoffinthecontrolvectorofthekey
renderingthekeyfullyoperational.Notethatnokey-partinformationisaddedtothekeywith
thiskeyword.
MIDDLE Thiskeywordspecifiesthatanintermediatekeypart,whichisneitherthefirstkeypartnorthe
lastkeypart,isbeingentered.Notethatthecommandcontrolpointforthiskeywordisthe
sameasthatfortheLASTkeywordanddifferentfromthatfortheADD-PARTkeyword.
LAST Thiskeywordspecifiesthatthelastkeypartisbeingentered.Thekey-partbitisturnedoffin
thecontrolvector.
RETRKPR Akeylabelmustbepassedasthekey_identifier.Thiskeylabelcorrespondstoakeystoredin
aKPITregisterinsidethecrypto-card(notinhostkeystorage).Thekeyinthatregisterhas
beenloadedbylabelandkeypartusingtheKPITverbbytheTKE.ThiskeywordforKPI
allowstheusertotellthecardtowrapthatkey(itmustbeinthecompletestate)usingthe
masterkey,placeitinaninternaltoken,andreturnthattokentotheuser.
ThiskeywordappliesonlywhenusingIBMSystemz.
| Key-wrappingmethod(One,optional)
|| USECONFG Specifiestowrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.This
| keywordisignoredforAESkeys.Thisisthedefault.ThiskeywordwasintroducedwithCCA
| 4.1.0.
|| WRAP-ENH Specifiestowrapthekeyusingthelegacywrappingmethod.ThiskeywordisignoredforAES
| keys.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ECB Specifiestowrapthekeyusingtheenhancedwrappingmethod.ValidonlyforDESkeys.This
| keywordwasintroducedwithCCA4.1.0.
key_part
Direction: Input Type: String
A16-byte field containing the clear key part to be entered. If the key is a single-length key, the key
part must be left-justified and padded on the right with zeros. This field is ignored if COMPLETE is
specified.
key_identifier
Direction: Input/Output Type: String
A64-byte field containing an internal token or a label of an existing key in the key storage file. If
rule_array is FIRST, this field is the skeleton of an internal token of a single- or double-length key with
the KEY-PART marking. If rule_array is MIDDLE or LAST, this is an internal token or key label of a
partially combined key. Depending on the input format, the accumulated partial or complete key is
returned as an internal token or as an updated key storage file record. The returned key_identifier will
be encrypted under the current master key.
Chapter5.ManagingAESandDEScryptographickeys 137

Key Part Import (CSNBKPI)
Restrictions
If a label is specified on key_identifier, the label must be unique. If more than one record is found, the verb
fails.
You must have access control point 'Key Part Import - Unrestricted' explicitly enabled. Otherwise, current
applications will fail with either of the following conditions:
v The first eight bytes of key identifier is different than the second eight bytesAND the first eight bytes of
the combined key are the same as the last second eight bytes
v The first eight bytes of key identifier is the same as the second eight bytesAND the first eight bytes of
the combined key are different than the second eight bytes.
Required commands
This verb requires the following commands to be enabled in the active role:
||||
Rule-arraykeyword Offset Command
||| FIRST X'001B' KeyPartImport-firstkeypart
||| ADD-PART X'0278' KeyPartImport-ADD-PART
||| COMPLETE X'0279' KeyPartImport-COMPLETE
||| MIDDLEorLAST X'001C' KeyPartImport-middleandlast
||| MIDDLEorLAST X'027A' KeyPartImport-Unrestricted
||| WRAP-ECBorWRAP-ENHused,anddefault X'0140' KeyPartImport-Allowwrappingoverride
|| key-wrappingmethodsettingdoesnotmatch keywords
| keyword
|
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKPIJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKPIJ are shown here.
Format
public native void CSNBKPIJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_part,
byte[] key_identifier );
138 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Part Import2 (CSNBKPI2)
Key Part Import2 (CSNBKPI2)
|
| Use the Key Part Import2 verb to combine, by XORing, the clear key parts of any key type and return the
| combined key value either in a variable-length internal key token or as an update to the key storage file.
| Before you use the Key Part Import2 verb for the first key part, you must use the Key Token Build2 verb to
| create the variable-length internal key token into which the key will be imported. Subsequent key parts are
| combined with the first part in variable-length internal key token form, or as a label from the key storage
| file.
| The preferred way to specify key parts is FIRST,ADD-PART, and COMPLETE in the rule_array. Only
| when the combined key parts have been marked as COMPLETE can the key token be used in any
| cryptographic operation. The partial key can be passed to the Key Token Change2 verb for
| re-encipherment, in case building the key was started during a master key change operation. The partial
| key can be passed to the Key Token Parse verb, in order to discover how the key token was originally
| specified, if researching an old partial key. Partial keys can also be passed to the Key Test, Key Test2, and
| Key Test Extended verbs.
| Key parts can also be specified as FIRST, MIDDLE, or LAST in the rule_array.ADD-PART or MIDDLE can
| be executed multiple times for as many key parts as necessary. Only when the LAST part has been
| combined can the key token be used by any other verb.
| New applications should employ theADD-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.
| On each call to Key Part Import2 (except with the COMPLETE keyword), specify the number of bits to use
| for the clear key part. Place the clear key part in the key_part parameter, and specify the number of bits
| using the key_part_length variable.Any extraneous bits of key_part data will be ignored.
| Consider using the Key Test2 verb to ensure a correct key value has been accumulated prior to using the
| COMPLETE option to mark the key as fully operational.
Format
|
||
CSNBKPI2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| key_part_bit_length,
| key_part,
| key_identifier_length,
| key_identifier )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 2 or 3.
| rule_array
|
Chapter5.ManagingAESandDEScryptographickeys 139

Key Part Import2 (CSNBKPI2)
|| Direction: Input Type: Integer
| The rule_array contains keywords that provide control information to the verb. The keywords must be
| in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on
| the right with blanks. The rule_array keywords are described in Table32.
|| Table32.KeywordsforKeyPartImport2controlinformation
|| Keyword Description
| Tokenalgorithm(Required)
|| HMAC SpecifiestoimportanHMACkeytoken.
| Keypart(Onerequired)
|| FIRST Thiskeywordspecifiesthataninitialkeypartisbeingentered.Thisverbreturnsthiskey-part
| encryptedbythemasterkeyinthekeytokenthatyousupplied.
|| ADD-PART Thiskeywordspecifiesthatadditionalkey-partinformationisprovided.
|| COMPLETE Thiskeywordspecifiesthatthekey-partbitshallbeturnedoffinthecontrolvectorofthekey
| renderingthekeyfullyoperational.Notethatnokey-partinformationisaddedtothekeywiththis
| keyword.
| Splitknowledge(Optional,requiredwhenkeywordFIRSTisused)
|| MIN3PART Specifiesthatthekeymustbeenteredinatleastthreeparts.
|| MIN2PART Specifiesthatthekeymustbeenteredinatleasttwoparts.
|| MIN1PART Specifiesthatthekeymustbeenteredinatleastonepart.
|
| key_part_bit_length
|| Direction: Input Type: Integer
| The length of the clear key in bits. This indicates the bit length of the key supplied in the key_part
| field. Valid lengths are 80 - 2048 for FIRST andADD-PART keywords. This value must be 0 for the
| COMPLETE keyword.
| key_part
|| Direction: Input Type: String
| This parameter is the clear key value to be applied. The key part must be left-justified. This parameter
| is ignored if COMPLETE is specified.
| key_identifier_length
|| Direction: Input/Output Type: Integer
| On input, the length of the buffer for the key_identifier parameter. For labels, the value is 64. The
| key_identifier must be left justified in the buffer. The buffer must be large enough to receive the
| updated token. The maximum value is 725. The output token will be longer when the first key part is
| imported.
| On output, the actual length of the token returned to the caller. For labels, the value will be 64.
| key_identifier
|| Direction: Input/Output Type: String
| The parameter containing an internal token or a 64-byte label of an existing key storage file record. If
| rule_array is FIRST, the key is a skeleton token. If rule_array isADD-PART, this is an internal token or
| the label of a key storage file record of a partially combined key. Depending on the input format, the
| accumulated partial or complete key is returned as an internal token or as an updated record in a key
| storage file. The returned key_identifier will be encrypted under the current master key.
140 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Part Import2 (CSNBKPI2)
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| This verb requires the following commands to be enabled in the active role:
||||
Rule-arraykeyword Offset Command
||| FIRSTandMIN3PART X'0297' KeyPartImport2-Loadfirstkeypart_
| require3keyparts
||| FIRSTandMIN2PART X'0298' KeyPartImport2-Loadfirstkeypart_
| require2keyparts
||| FIRSTandMIN1PART X'0299' KeyPartImport2-Loadfirstkeypart_
| require1keyparts
||| ADD-PART X'029A' KeyPartImport2-Addsecondof3ormore
| keyparts
|| X'029B' KeyPartImport2-Addlastrequiredkeypart
|| X'029C' KeyPartImport2-Addoptionalkeypart
||| COMPLETE X'029D' KeyPartImport2-Completekey
|
Usage notes
|
| On each call to Key Part Import2, also specify a rule-array keyword to define the service action: FIRST,
| ADD-PART, or COMPLETE.
| v With the FIRST keyword, the input key-token must be a skeleton token (no key material). Use of the
| FIRST keyword requires that the Load First Key Part2 access control point be enabled in the default
| role.
| v With theADD-PART keyword, the service XORs the clear key-part with the key value in the input
| key-token. Use of theADD-PART keyword requires that anAdd Key Part2 access control point be
| enabled in the default role. The key remains incomplete in the updated key token returned from the
| service.
| v With the COMPLETE keyword, the KEY-PART bit is set off in the updated key token that is returned
| from the service. Use of the COMPLETE keyword requires that the Complete Key Part2 access control
| point be enabled in the default role. The key_part_bit_length parameter must be set to zero.
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBKPI2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBKPI2J are shown here.
Chapter5.ManagingAESandDEScryptographickeys 141

Key Part Import2 (CSNBKPI2)
|
| Format
| public native void CSNBKPI2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger key_part_bit_length,
| hikmNativeInteger key_part,
| hikmNativeInteger key_identifier_length,
|| hikmNativeInteger key_identifier );
|
|
|
142 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Test (CSNBKYT)
Key Test (CSNBKYT)
Use the Key Test verb to generate or verify a secure, cryptographic verification pattern for keys.Akey to
test can be in the clear or encrypted under the master key. In addition, the verb permits you to test the
CCAmaster keys. Keywords in the rule_array parameter specify whether the verb generates or verifies a
verification pattern.
This algorithm is supported for clear and encrypted single and double length keys. Single, double and
triple length keys are also supported with the ENC-ZERO algorithm. Clear triple length keys are not
supported. See “Cryptographic key-verification techniques” on page 491.
With the default method, the verb generates a verification pattern and it creates and cryptographically
processes a random number. This verb returns the random number with the verification pattern.
When the verb tests a verification pattern against a key, you must supply the random number and the
verification pattern from a previous call to Key Test. This verb returns the verification result in the return
and reason codes. See Table33 for details.
Table33.Verificationpatterninputandoutput
ForkeywordGENERATE
random_numbervariable verification_patternvariable
Method Oninput Onoutput Oninput Onoutput
ENC-ZERO Unused Unused Unused Containsthe4-byte
verificationpatterninthe
high-orderfourbytesof
thevariable.The
low-orderfourbytesare
unspecified.
MDC-4 Unused Containsthelower Unused Containstheupper
(leftmost)eightbytesof (rightmost)eightbytes
theMDC-4hash. oftheMDC-4hash.
SHA-1 Unused Containsthelower Unused Containstheuppereight
(leftmost)eightbytesof bytesoftheSHA-1
theSHA-1verification verificationpattern.
pattern.
SHA-256 Unused Unused Unused SHA-256based
verificationpattern
ForkeywordVERIFY
random_numbervariable verification_patternvariable
Method Oninput Onoutput Oninput Onoutput
ENC-ZERO Unused Unused Containsthe4-byte Unused
verificationpatterninthe
high-orderfourbytesof
thevariable.The
low-orderfourbytesare
unspecified.
MDC-4 Containsthelower Unused Containstheupper Unused
(leftmost)eightbytesof (rightmost)eightbytes
theMDC-4hash. oftheMDC-4hash.
SHA-1 Containsthelower Unused Containstheuppereight Unused
(leftmost)eightbytesof bytesoftheSHA-1
theSHA-1verification verificationpattern.
pattern.
Chapter5.ManagingAESandDEScryptographickeys 143

Key Test (CSNBKYT)
Table33.Verificationpatterninputandoutput (continued)
ForkeywordGENERATE
random_numbervariable verification_patternvariable
Method Oninput Onoutput Oninput Onoutput
SHA-256 Unused Unused SHA-256based Unused
verificationpattern
Format
CSNBKYT(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_identifier,
random_number,
verification_pattern )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 2, 3, 4, or 5.
rule_array
Direction: Input Type: String
Two to five keywords provide control information to the verb. The keywords must be in contiguous
storage with each of the keywords left-justified in its own 8-byte location and padded on the right with
blanks. The rule_array keywords are described in Table34.
Table34.KeywordsforKeyTestcontrolinformation
Keyword Description
| Keyrule(One,required)
KEY-CLR Specifiesthekeysuppliedinkey_identifierisasingle-lengthclearkey.
KEY-CLRD Specifiesthekeysuppliedinkey_identifierisadouble-lengthclearkey.
KEY-ENC Specifiesthekeysuppliedinkey_identifierisasingle-lengthencryptedkey.
KEY-ENCD Specifiesthekeysuppliedinkey_identifierisadouble-lengthencryptedkey.
KEY-KM Specifiesthatthetargetisthemasterkeyregister.
KEY-NKM Specifiesthatthetargetisthenewmaster-keyregister.
KEY-OKM Specifiesthatthetargetistheoldmaster-keyregister.
CLR-A128 Processa128-bitAESclear-keyorclear-keypart.
CLR-A192 Processa192-bitAESclear-keyorclear-keypart.
CLR-A256 Processa256-bitAESclear-keyorclear-keypart.
144 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Test (CSNBKYT)
Table34.KeywordsforKeyTestcontrolinformation (continued)
Keyword Description
TOKEN ProcessanAESclearorencryptedkeycontainedinanAESkey-token.
Master-keyselector(One,optional).UseonlywithKEY-KM,KEY-NKM,orKEY-OKMkeywords.
AES-MK ProcessoneoftheAESmaster-keyregisters.
|| APKA-MK ProcessoneoftheAPKAmaster-keyregisters.ThiskeywordwasintroducedwithCCA4.1.0.
ASYM-MK Specifiesuseofonlytheasymmetricmaster-keyregisters.
SYM-MK Specifiesuseofonlythesymmetricmaster-keyregisters.
| ProcessRule(One,required)
GENERATE Generateaverificationpatternforthekeysuppliedinkey_identifier.
VERIFY Verifyaverificationpatternforthekeysuppliedinkey_identifier.
| ParityAdjustment(One,optional)
ADJUST Adjusttheparityoftestkeytooddbeforegeneratingorverifyingtheverificationpattern.The
key_identifierfielditselfisnotadjusted.
NOADJUST Donotadjusttheparityoftestkeytooddbeforegeneratingorverifyingtheverificationpattern.Thisis
thedefault.
VerificationProcessRule(One,optional)
ENC-ZERO Specifiesuseofthe"encryptedzeros"method.UseonlywithKEY-CLR,KEY-CLRD,KEY-ENC,or
KEY-ENCDkeywords.
MDC-4 SpecifiesuseoftheMDC-4masterkeyverificationmethod.UseonlywiththeKEY-KM,KEY-NKM,
KEY-OKMkeywords.Youmustspecifyonemaster-keyselectorkeywordtousethiskeyword.
SHA-1 SpecifiesuseoftheSHA-1master-key-verificationmethod.UseonlywithKEY-KM,KEY-NKM,or
KEY-OKMkeywords.Youmustspecifyonemaster-keyselectorkeywordtousethiskeyword.
SHA-256 SpecifiesuseoftheSHA-256master-key-verificationmethod.
key_identifier
Direction: Input/Output Type: String
The key for which to generate or verify the verification pattern. The parameter is a 64-byte string of an
internal token, key label, or a clear key value left-justified.
Note: If you supply a key label for this parameter, it must be unique in the key storage file.
random_number
Direction: Input/Output Type: String
This is an 8-byte field that contains a random number supplied as input for the test pattern verification
process and returned as output with the test pattern generation process. With the ENC-ZERO method,
the random number is not used, but it still must be provided.
verification_pattern
Direction: Input/Output Type: String
This is an 8-byte field that contains a verification pattern supplied as input for the test pattern
verification process and returned as output with the test pattern generation process. With the
ENC-ZERO method, the high-order four bytes contain the verification data. For more detail, see
“Cryptographic key-verification techniques” on page 491.
Restrictions
None
Chapter5.ManagingAESandDEScryptographickeys 145

Key Test (CSNBKYT)
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
You can generate the verification pattern for a key when you generate the key. You can distribute the
pattern with the key and it can be verified at the receiving node. In this way, users can ensure using the
same key at the sending and receiving locations. You can generate and verify keys of any combination of
key forms, that is, clear, operational or external.
The parity of the key is not tested.
For triple-length keys, use KEY-ENC or KEY-ENCD with ENC-ZERO. Clear triple-length keys are not
supported.
In the Transaction Security System, KEY-ENC and KEY-ENCD both support enciphered single-length and
double-length keys. They use the key-form bits in byte 5 of CV to determine the length of the key. To be
consistent, in this implementation of CCA, both KEY-ENC and KEY-ENCD handle single- and
double-length keys. Both products effectively ignore the keywords, which are supplied only for compatibility
reasons.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKYTJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKYTJ are shown here.
Format
public native void CSNBKYTJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_identifier,
byte[] random_number,
byte[] verification_pattern );
146 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Test2 (CSNBKYT2)
Key Test2 (CSNBKYT2)
|
| Use the Key Test2 verb to generate or verify a secure, cryptographic verification pattern for keys contained
| in a variable-length symmetric key-token.Akey to test can be in the clear or encrypted under the master
| key. In addition, the verb permits you to test the CCAmaster keys. Keywords in the rule_array parameter
| specify whether the verb generates or verifies a verification pattern. See “Cryptographic key-verification
| techniques” on page 491.
| When the verb tests a verification pattern against a key, you must supply the verification pattern from a
| previous call to Key Test2. This verb returns the verification result in the return code and reason code.
Format
|
||
CSNBKYT2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| key_identifier_length,
| key_identifier,
| key_encrypting_key_identifier_length,
| key_encrypting_key_identifier,
| reserved_length,
| reserved,
| verification_pattern_length,
| verification_pattern )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 2 or 3.
| rule_array
|| Direction: Input Type: String
| The rule_array contains keywords that provide control information to the verb. The keywords must be
| in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on
| the right with blanks. The rule_array keywords are described in Table35.
|| Table35.KeywordsforKeyTest2controlinformation
|| Keyword Description
| Tokenalgorithm(Required)
|| HMAC SpecifiesthekeytokenisanHMACkeytoken.
| Processrule(Onerequired)
|| GENERATE Generateaverificationpatternforthespecifiedkey.
|| VERIFY Verifythataverificationpatternmatchesthespecifiedkey.
| Verificationpatterncalculationalgorithm(Oneoptional)
|| SHA2VP1 SpecifiestousetheSHA-256basedverificationpatterncalculation
| algorithm.Thisisthedefault.
|
Chapter5.ManagingAESandDEScryptographickeys 147

Key Test2 (CSNBKYT2)
| key_identifier_length
|| Direction: Input Type: Integer
| The length of the key_identifier is bytes. The maximum value is 725.
| key_identifier
|| Direction: Input Type: String
| The key for which to generate or verify the verification pattern. The parameter is a variable length
| string of an internal token or the 64-byte label of a key in key storage.
| key_encrypting_key_identifier_length
|| Direction: Input Type: Integer
| The byte length of the key_encrypting_key_identifier parameter. This value must be 0.
| key_encrypting_key_identifier
|| Direction: Input/Output Type: String
| This parameter is ignored.
| reserved_length
|| Direction: Input Type: Integer
| The byte length of the reserved parameter. This value must be 0.
| reserved
|| Direction: Input/Output Type: String
| This parameter is ignored.
| verification_pattern_length
|| Direction: Input/Output Type: Integer
| The byte length of the verification_pattern parameter.
| On input: For GENERATE, the length must be at least 8 bytes; For VERIFY, the length must be 8
| bytes.
| On output for GENERATE, the length of the verification pattern returned.
| verification_pattern
|| Direction: Input/Output Type: String
| For GENERATE, the verification pattern generated for the key.
| For VERIFY, the supplied verification pattern to be verified.
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
|
| You can generate the verification pattern for a key when you generate the key. You can distribute the
| pattern with the key and it can be verified at the receiving node. In this way, users can ensure using the
| same key at the sending and receiving locations. You can generate and verify keys of any combination of
| key forms, that is, clear, operational or external.
148 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Test2 (CSNBKYT2)
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBKYT2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBKYT2J are shown here.
|
| Format
| public native void CSNBKYT2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger key_identifier_length,
| byte[] key_identifier,
| hikmNativeInteger key_encrypting_key_identifier_length,
| byte[] key_encrypting_key_identifier,
| hikmNativeInteger reserved_length,
| byte[] reserved,
| hikmNativeInteger verification_pattern_length,
|| byte[] verification_pattern );
|
|
|
Chapter5.ManagingAESandDEScryptographickeys 149

Key Test Extended (CSNBKYTX)
Key Test Extended (CSNBKYTX)
This verb is essentially the same as “Key Test (CSNBKYT)” on page 143, except:
v In addition to operating on internal keys and key parts, this verb also operates on external keys and key
parts.
v This verb does not operate on clear keys, and does not accept rule_array keywords CLR-A128,
CLR-A192, CLR-A256, KEY-CLR, and KEY-CLRD.
See also “Key Test (CSNBKYT)” on page 143 for operating only on internal keys.
Use this verb to verify the value of a key or key part in an external or internal key token. This verb
supports two options:
GENERATE To compute and return a verification pattern for a specified key.
VERIFY To verify that a passed verification pattern is correct for the specified key.
The verification pattern 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.
This verb supports testing ofAES (Release 3.30 or later), DES, and PKAmaster keys, and enciphered
keys or key parts. rule_array keywords are used to specify information about the target key that is not
implicit from other verb parameters.
When testing the master keys, there are two sets of rule_array keywords to indicate what key to test:
1. The SYM-MK,ASYM-MK, andAES-MK (Release 3.30 or later) master-key selector keywords indicate
whether to test the DES (symmetric) master key, the PKA(asymmetric) master key, or theAES master
key.
2. The KEY-KM, KEY-NKM, and KEY-OKM key or key-part rule keywords choose among the
current-master-key register, the new-master-key register, and the old-master-key register.
Not specifying a master-key selector keyword (SYM-MK,ASYM-MK, orAES-MK) means that the DES
(symmetric) and PKA(asymmetric) master keys have the same value, and that you want to test that value.
Several key test algorithms are supported by the verb. See “Cryptographic key-verification techniques” on
page 491. 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. You can specify one of the following:
1. The ENC-ZERO keyword to encrypt a block of binary zeros with the specified key. This verb returns
the leftmost 32 bits of the encryption result as the verification pattern. The encrypted block consists of
16 bytes of binary zeros forAES, and eight bytes for DES and Triple-DES keys. This method is valid
only with the TOKEN keyword forAES, and KEY-ENC and KEY-ENCD keywords for DES.
2. 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. The SHA-1 keyword to compute the verification pattern using the SHA-1 hashing method. This
keyword is valid only when computing the verification pattern for the DES (symmetric) or PKA
(asymmetric) master key.
4. The SHA-256 keyword to compute the verification pattern using the SHA-256 hashing method. This
keyword is valid only when computing the verification pattern for anAES key.
Table33 on page 143 describes the use of the random_number and verification_pattern fields for each of
the available verification methods.
150 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Test Extended (CSNBKYTX)
Note: For historical reasons, the verification information is passed in two 8-byte variables pointed to by
the random_number and verification_pattern parameters. The GENERATE option returns
information in these two variables, and the VERIFY option uses the information provided in these
two variables. If the verb cannot verify the information provided, it returns a return code of 4 and a
reason code of 1. For simplicity, these two variables can be two 8-byte elements of a 16-byte array,
which is processed by your application program as a single quantity. Both parameters must be
coded when calling theAPI.
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. These parity adjustment keywords allow you
to control how the Key Test Extended verb handles the parity bits:
NOADJUST Specifies not to alter the parity bit values in any way. This is the default.
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.
Format
CSNBKYTX(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_identifier,
random_number,
verification_pattern )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 2, 3, 4, or 5.
rule_array
Direction: Input Type:Array
Between two and five keywords provide control information to the verb. The keywords must be in
contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on
the right with blanks. The rule_array keywords are described in Table36.
Table36.KeywordsforKeyTestExtendedcontrolinformation
Keyword Description
Processrule(Onerequired)
GENERATE Generateaverificationpatternforthekeysuppliedinkey_identifier.
VERIFY Verifyaverificationpatternforthekeysuppliedinkey_identifier.
Keyorkey-partrule(Onerequired)
Chapter5.ManagingAESandDEScryptographickeys 151

Key Test Extended (CSNBKYTX)
Table36.KeywordsforKeyTestExtendedcontrolinformation (continued)
Keyword Description
KEY-ENC Specifiesthekeysuppliedinkey_identifierisasingle-lengthencryptedkey.
KEY-ENCD Specifiesthekeysuppliedinkey_identifierisadouble-lengthencryptedkey.
KEY-KM Specifiesthatthetargetisthemasterkeyregister.
KEY-NKM Specifiesthatthetargetisthenewmaster-keyregister.
KEY-OKM Specifiesthatthetargetistheoldmaster-keyregister.
TOKEN ProcessanAESclearorencryptedkeycontainedinanAESkey-token.
Master-keyselector(One,optional).UseonlywithKEY-KM,KEY-NKM,orKEY-OKMkeywords.Thedefaultisto
processtheASYM-MKandSYM-MKkeyregisters,whichmusthavethesamekeyforthedefaulttobevalid.
AES-MK ProcessoneoftheAESmaster-keyregisters.
|| APKA-MK ProcessoneoftheAPKAmaster-keyregisters.ThiskeywordwasintroducedwithCCA4.1.0.
ASYM-MK Specifiesuseofonlytheasymmetricmaster-keyregisters.
SYM-MK Specifiesuseofonlythesymmetricmaster-keyregisters.
ParityAdjustment(One,optional)NotvalidwithAES-MKMaster-keyselectorkeyword.
ADJUST Adjusttheparityoftestkeytooddbeforegeneratingorverifyingtheverificationpattern.The
key_identifierfielditselfisnotadjusted.
NOADJUST Donotadjusttheparityoftestkeytooddbeforegeneratingorverifyingtheverificationpattern.Thisis
thedefault.
VerificationProcessRule(One,optional)FortheAESmasterkey,SHA-256isthedefault.FortheDESorPKA
masterkeys,thedefaultistouseSHA-1ifthefirstandthirdpartsofthekeyaredifferent,ortheIBMz/OSmethodif
thefirstandthirdpartsofthekeyarethesame.
ENC-ZERO Specifiesuseofthe"encryptedzeros"method.UseonlywithKEY-CLR,KEY-CLRD,KEY-ENC,or
KEY-ENCDkeywords.
MDC-4 SpecifiesuseoftheMDC-4masterkeyverificationmethod.UseonlywiththeKEY-KM,KEY-NKM,
KEY-OKMkeywords.Youmustspecifyonemaster-keyselectorkeywordtousethiskeyword.
SHA-1 SpecifiesuseoftheSHA-1master-key-verificationmethod.UseonlywithKEY-KM,KEY-NKM,or
KEY-OKMkeywords.Youmustspecifyonemaster-keyselectorkeywordtousethiskeyword.
SHA-256 SpecifiesuseoftheSHA-256master-key-verificationmethod.
key_identifier
Direction: Input Type: String
Apointer to a string variable containing an internal or external key-token, a key label that identifies an
internal or external key-token record, or a clear key.
The key token contains the key or the key part used to generate or verify the verification pattern.
random_number
Direction: Input/Output Type: String
Apointer to a string variable containing a number the verb might use in the verification process. When
you specify the GENERATE keyword, the verb returns the random number. When you specify the
VERIFY keyword, you must supply the number. With the ENC-ZERO method, the random_number
variable is not used but must be specified.
verification_pattern
Direction: Input/Output Type: String
Apointer to a string variable containing the binary verification pattern. When you specify the
GENERATE keyword, the verb returns the verification pattern. When you specify the VERIFY keyword,
152 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Test Extended (CSNBKYTX)
you must supply the verification pattern. With the ENC-ZERO method, the verification data occupies
the high-order four bytes, while the low-order four bytes are unspecified (the data is passed between
your application and the cryptographic engine but is otherwise unused). For more detail, see
“Cryptographic key-verification techniques” on page 491.
kek_key_identifier
Direction: Input Type: String
Apointer to a string variable containing an operational key-token or the key label of an operational
key-token record containing an IMPORTER or EXPORTER key-encrypting key. If the key_identifier
parameter does not identify an external key-token, the contents of the kek_key_identifier variable
should contain a null DES key-token.
Restrictions
1. Releases earlier than Release 3.20 do not support theADJUST and NOADJUST parity adjustment
keywords.
2. AES keys and keywords are not supported in releases before Release 3.30.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
You can generate the verification pattern for a key when you generate the key. You can distribute the
pattern with the key and it can be verified at the receiving node. In this way, users can ensure using the
same key at the sending and receiving locations. You can generate and verify keys of any combination of
key forms: clear, operational, or external.
The parity of the key is not tested.
For triple-length keys, use KEY-ENC or KEY-ENCD with ENC-ZERO. Clear triple-length keys are not
supported.
In the Transaction Security System, KEY-ENC and KEY-ENCD both support enciphered single-length and
double-length keys. They use the key-form bits in byte 5 of the control vector (CV) to determine the length
of the key. To be consistent, in this implementation of CCA, both KEY-ENC and KEY-ENCD handle single-
and double-length keys. Both products effectively ignore the keywords, which are supplied only for
compatibility reasons.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKYTXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKYTXJ are shown here.
Chapter5.ManagingAESandDEScryptographickeys 153

Key Test Extended (CSNBKYTX)
Format
public native void CSNBKYTXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_identifier,
byte[] random_number,
byte[] verification_pattern,
byte[] kek_key_identifier);
154 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Build (CSNBKTB)
Key Token Build (CSNBKTB)
The Key Token Build verb assembles an external or internal key token in application storage from
information you supply.
This verb can include a control vector that you supply or can build a control vector based on the key type
and the control vector related keywords in the rule_array. The Key Token Build 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.
Format
CSNBKTB(
return_code,
reason_code,
exit_data_length,
exit_data,
key_token,
key_type,
rule_array_count,
rule_array,
key_value,
reserved_1,
reserved_2,
reserved_3,
control_vector,
reserved_4,
reserved_5,
reserved_6,
masterkey_verify_parm )
Note: Previous implementations used the reserved_1 parameter to point to a four-byte integer or string
that represented the master key verification pattern. In current versions, CCArequires this
parameter to point to a four-byte value equal to binary zero.
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 14.
key_token
Direction: Input/Output Type: String
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
Direction: Input Type: String
The key_type parameter is a pointer to a string variable containing a keyword that defines the key
type. The keyword is eight bytes in length and must be left-aligned and padded on the right with space
characters.
ValidAES key type keywords are:
CLRAES DATA
Valid DES key type keywords are:
Chapter5.ManagingAESandDEScryptographickeys 155

Key Token Build (CSNBKTB)
CIPHER DATAC IKEYXLAT OPINENC
CVARDEC DATAM IMPORTER PINGEN
CVARENC DATAMV IPINENC PINVER
CVARPINE DECIPHER KEYGENKY SECMSG
CVARXCVL DKYGENKY MAC
CVARXCVR ENCIPHER MACVER
DATA EXPORTER OKEYXLAT
Specify the USE-CV keyword to indicate that the key type should be obtained from the control_vector
variable.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1, 2, 3, 4, 5, or 6.
rule_array
Direction: Input Type: String
One to four keywords that provide control information to the verb. The keywords must be in contiguous
storage with each of the keywords left-justified in its own 8-byte location and padded on the right with
blanks. For any key type, there are no more than four valid rule_array values. The rule_array
keywords are described in Table37.
Table37.KeywordsforKeyTokenBuildcontrolinformation
Keyword Description
Tokentype(Onerequired)
EXTERNAL Anexternalkeytoken.
INTERNAL Aninternalkeytoken.
Tokenalgorithm(One,optional)
AES AnAESkey.
DES ADESkey.
Keystatus(One,optional).NotvalidforCLRDES
KEY Thekeytokentobuildwillcontainanencryptedkey.Thekey_valueparameter
identifiesthefieldthatcontainsthekey.
NO-KEY Thekeytokentobuildwillnotcontainakey.Thisisthedefaultkeystatus.
CVsource(One,optional).NotvalidforCLRDES
CV Theverbistoobtainthecontrolvectorfromthevariableidentifiedbythe
control_vectorparameter.
NO-CV Thecontrolvectoristobesuppliedbasedonthekeytypeandthecontrol
vectorrelatedkeywords.Thisisthedefault.
| Key-wrappingmethod(One,optional)
|| WRAP-ENH Useenhancedkeywrappingmethod,whichiscompliantwiththeANSIX9.24
| standard.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ECB Useoriginalkeywrappingmethod,whichusesECBwrappingforDESkey
| tokensandCBCwrappingforAESkeytokens.Thiskeywordwasintroduced
| withCCA4.1.0.
| Translationcontrol(Optional)
|| ENH-ONLY Restrictrewrappingoftheoutput_key_token.Afterthetokenhasbeenwrapped
| withtheenhancedmethod,itcannotberewrappedusingtheoriginalmethod.
| ThiskeywordwasintroducedwithCCA4.1.0.
See Figure3 on page 30 for the key usage keywords that can be specified for a given key type.
156 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Build (CSNBKTB)
The difference between Key Token Parse (CSNBKTP) and Control Vector Generate (CSNBCVG) is
that Key Token Parse returns the rule_array keywords that apply to a parsed token, such as
EXTERNAL, INTERNAL, and so forth. These rule_array parameters are returned in addition to the
key_type parameter.
| AMEX-CSC DKYL0 EPINGEN KEYLN16 UKPT
| ANSIX9.9 DKYL1 EPINGENA LMTD-KEK VISA-PVV
| ANY DKYL2 EPINVER MIXED WRAP-ECB
| ANY-MAC DKYL3 EXEX NO-SPEC WRAP-ENH
| CLR8-ENC DKYL4 EXPORT NO-XPORT XLATE
| CPINENC DKYL5 GBP-PIN NOOFFSET XPORT-OK
| CPINGEN DKYL6 GBP-PINO NOT-KEK
| CPINGENA DKYL7 IBM-PIN OPEX
| CVVKEY-A DMAC IBM-PINO OPIM
| CVVKEY-B DMKEY IMEX PIN
| DALL DMPIN IMIM REFORMAT
| DATA DMV IMPORT SINGLE
| DDATA DOUBLE INBK-PIN SMKEY
| DEXP DPVR KEY-PART SMPIN
| DIMP ENH-ONLY KEYLN8 TRANSLAT
| Keywords ENH-ONLY, WRAP-ECB, and WRAP-ENH were introduced with CCA4.1.0.
key_value
Direction: Input Type: String
This parameter is a string variable containing the encrypted key-value incorporated into the
encrypted-key portion of the key token if you use the KEY rule_array keyword. Single-length keys must
be left-aligned in the variable and padded on the right (low-order) with eight bytes of X'00'.
control_vector
Direction: Input Type: String
Apointer to a 16-byte string variable. If this parameter is specified, and you use the CV rule_array
keyword, the variable is copied to the control vector field of the key token. See “Control vector table”
on page 463 for additional information.
masterkey_verify_parm
Direction: Input Type: String
Apointer to an 8-byte string variable. This value is inserted into the key token when you specify both
the KEY and INTERNALkeywords in the rule_array.
Restrictions
None
Required commands
None
Usage notes
Because 24-byte (TRIPLE) DES keys can only be generated as DATAkeys, capability to create 24-byte
DES tokens (with keywords TRIPLE or KEYLN24 has not been added to Key Token Build (CSNBKTB).
Instead, call Key Generate (CSNBKGN) directly.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKTBJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKTBJ are shown here.
Chapter5.ManagingAESandDEScryptographickeys 157

Key Token Build (CSNBKTB)
Format
public native void CSNBKTBJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_token,
byte[] key_type,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_value,
byte[] master_key_verification_pattern,
hikmNativeInteger reserved1,
byte[] reserved2,
byte[] control_vector,
byte[] reserved3,
hikmNativeInteger reserved4,
byte[] reserved5,
byte[] reserved6 );
158 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Build2 (CSNBKTB2)
Key Token Build2 (CSNBKTB2)
|
| Use the Key Token Build2 verb to assemble an internal variable-length symmetric key-token in application
| storage from information that you supply. This verb assembles the information as a skeleton keyed hash
| MessageAuthentication Code (HMAC) internal key token. This skeleton token can be supplied to the Key
| Generate2 verb, which then provides 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.
| The Key Token Build2 verb cannot assemble a usable key-token that contains an enciphered key. It can
| assemble an internal HMAC key-token that has either a clear key, usable for a limited number of services,
| or no key, which is only usable for passing to the Key Generate2 verb in order to receive an enciphered
| key.
| The Key Token Build2 verb is a host-only verb and it does not use the cryptographic coprocessor. 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.
Format
|
||
CSNBKTB2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| clear_key_bit_length,
| clear_key_value,
| key_name_length,
| key_name,
| user_associated_data_length,
| user_associated_data,
| token_data_length,
| token_data,
| reserved_length,
| reserved
| target_key_token_length,
| target_key_token )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. The minimum value is 4.
| rule_array
|| Direction: Input Type: String
| The rule_array contains keywords that provide control information to the verb. The keywords must be
| in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on
| the right with blanks. The rule_array keywords are described in Table38 on page 160.
Chapter5.ManagingAESandDEScryptographickeys 159

Key Token Build2 (CSNBKTB2)
|| Table38.KeywordsforKeyTokenBuild2controlinformation
|| Keyword Description
| Tokentype(Required)
|| INTERNAL Specifiestobuildaninternalkeytoken.
| Tokenalgorithm(Required)
|| HMAC SpecifiestobuildanHMACkeytoken.
| Keystatus(One,optional)
|| NO-KEY Specifiestobuildthekeytokenwithoutakeyvalue.Thiscreatesaskeletonkeytokenthatcanlater
| besuppliedtotheKeyGenerate2verb.Thisisthedefault.
|| KEY-CLR Specifiestobuildthekeytokenwithaclearkeyvalue.Thiscreatesakeytokenthatcanbeused
| withtheKeyTest2verbtogenerateaverificationpatternforthekeyvalue.
| Keytype(Required)
|| MAC SpecifiesthatthiskeyisforMessageAuthenticationCodeoperations.
| Keymanagementrelatedkeywords(appliestoallkeytypes)
| Symmetric-keyexportkey-managementcontrol(One,optional)
|| NOEX-SYM Prohibitstheexportofthekeywithasymmetrickey.
|| XPRT-SYM Permitstheexportofthekeywithasymmetrickey.Thisisthedefault.
| Unauthenticatedasymmetric-keyexportkey-managementcontrol(One,optional)
|| NOEXUASY Prohibitstheexportofthekeywithanunauthenticatedasymmetrickey.
|| XPRTUASY Permitstheexportofthekeywithanunauthenticatedasymmetrickey.Thisisthedefault.
| Authenticatedasymmetric-keyexportkey-managementcontrol(One,optional)
|| NOEXAASY Prohibitstheexportofthekeywithanauthenticatedasymmetrickey.
|| XPRTAASY Permitstheexportofthekeywithanauthenticatedasymmetrickey.Thisisthedefault.
| Key-usagekeywords(thesearespecifictothekeytypespecified)
| MACkeyusage
| Generatekey-usagecontrol(Onerequired)
|| GENERATE SpecifiesthatthiskeycanbeusedtogenerateaMAC.AkeythatcangenerateaMACcanalso
| verifyaMAC.
|| VERIFY SpecifiesthatthiskeycannotbeusedtogenerateaMAC.ItcanonlybeusedtoverifyaMAC.
| Hashmethodkey-usagecontrol(anycombination,optional)
| Note: Allkeywordsinthelistbelowaredefaultsunlessoneormorekeywordsinthelistarespecified.
|| SHA-1 SpecifiesthattheSHA-1hashmethodisallowedforthekey.
|| SHA-224 SpecifiesthattheSHA-224hashmethodisallowedforthekey.
|| SHA-256 SpecifiesthattheSHA-256hashmethodisallowedforthekey.
|| SHA-384 SpecifiesthattheSHA-384hashmethodisallowedforthekey.
|| SHA-512 SpecifiesthattheSHA-512hashmethodisallowedforthekey.
|
| clear_key_bit_length
|| Direction: Input Type: Integer
| The length of the clear key in bits. Specify 0 when no key value is supplied or a valid HMAC key bit
| length, between 80 and 2048.
| clear_key_value
|| Direction: Input Type: String
160 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Build2 (CSNBKTB2)
| This parameter is used when the KEY-CLR keyword is specified. This parameter is the clear key value
| to be put into the token being built.
| key_name_length
|| Direction: Input Type: Integer
| The length of the key_name parameter. Valid values are 0 and 64.
| key_name
|| Direction: Input Type: String
| A64-byte key store label to be stored in the associated data structure of the token.
| user_associated_data_length
|| Direction: Input Type: Integer
| The length of the user-associated data. The valid values are 0 - 255 bytes.
| user_associated_data
|| Direction: Input Type: String
| User-associated data to be stored in the associated data structure.
| token_data_length
|| Direction: Input Type: Integer
| This parameter is reserved. This value must be 0.
| token_data
|| Direction: Ignored Type: String
| This parameter is ignored.
| reserved_length
|| Direction: Input Type: Integer
| This parameter is reserved. This value must be 0.
| reserved
|| Direction: Ignored Type: String
| This parameter is ignored.
| target_key_token_length
|| Direction: Input/Output Type: Integer
| On input, the length of the target_key_token parameter supplied to receive the token. On output, the
| actual length of the token returned to the caller. Maximum length is 725 bytes.
| target_key_token
|| Direction: Output Type: String
| The key token built by this verb.
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| None
Chapter5.ManagingAESandDEScryptographickeys 161

Key Token Build2 (CSNBKTB2)
Usage notes
|
| None.
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBKTB2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBKTB2J are shown here.
|
| Format
| public native void CSNBKTB2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| 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 );
|
|
|
162 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Change (CSNBKTC)
Key Token Change (CSNBKTC)
Use the Key Token Change verb to re-encipher a DES key from encryption under the old master-key to
encryption under the current master-key and to update the keys in internal DES key-tokens.
Notes:
1. An application system is responsible for keeping all of its keys in a usable form. When the master key
is changed, the CEX3C implementations can use an internal key that is enciphered by either the
current or the old master-key. Before the master key is changed a second time, it is important to have
a key re-enciphered under the current master-key for continued use of the key. Use the Key Token
Change verb to re-encipher such a keys.
2. Previous implementations of IBM CCAproducts had additional capabilities with this verb such as
deleting key records and key tokens in key storage.Also, use of a wild card (*) was supported in those
implementations.
Format
CSNBKTC(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1, 2, 3, or 4.
rule_array
Direction: Input Type:Array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The
keywords are eight bytes in length and must be left-aligned and padded on the right with space
characters. The rule_array keywords are described in Table39.
Table39.KeywordsforKeyTokenChangecontrolinformation
Keyword Description
Re-enciphermentmethod(Required)
RTCMK Re-enciphersaDESkeytothecurrentmaster-keyinaninternalkey-tokeninapplicationstorageor
inkeystorage.Ifthesuppliedkeyisalreadyencipheredunderthecurrentmaster-keytheverb
returnsapositiveresponse(returncode0,reasoncode0).Ifthesuppliedkeyisencipheredunder
theoldmaster-key,thekeyisupdatedtoenciphermentbythecurrentmaster-keyandtheverb
returnsapositiveresponse(returncode0,reasoncode0).Othercasesreturnsomeformof
abnormalresponse.
Chapter5.ManagingAESandDEScryptographickeys 163

Key Token Change (CSNBKTC)
Table39.KeywordsforKeyTokenChangecontrolinformation (continued)
Keyword Description
RTNMK Re-enciphersaninternalDESkeytothenewmaster-key.
Akeyencipheredunderthenewmasterkeyisnotusable.Itisexpectedthattheuserwillusethis
keyword(RTNMK)totakeapreparatorystepinre-encipheringanexternalkeystorethatthey
managethemselvestoanewmaster-key,beforethesetoperationhasoccurred.Notealsothatthe
newmaster-keyregistermustbefull;itmusthavehadthelastkeypartloadedandthereforenot
beemptyorpartiallyfull(partiallyfullmeansthatoneormorekeypartshavebeenloadedbutnot
thelastkeypart).
The'SET'operationmakesthenewmaster-keyoperational,movingittothecurrentmaster-key
register,andthecurrentmaster-keyisdisplacedintotheoldmaster-keyregister.Whenthis
happens,allthekeysthatwerere-encipheredtothenewmaster-keyarenowusable,becausethe
newmaster-keyisnot'new'anymore,itis'current'.
BecausetheRTNMKkeywordisaddedprimarilyforsupportofexternallymanagedkeystorage
(see“KeyStorageonz/OS(RTNMK-focused)”onpage264,itisnotvalidtopassakey_identifer
whentheRTNMKkeywordisused.Onlyafullinternalkeytoken(encryptedunderthecurrent
master-key)canbepassedforre-enciphermentwiththeRTNMKkeyword.WhenakeyLABELis
passedalongwiththeRTNMKkeyword,theerrorreturncode8withreasoncode181willbe
returned.
Formoreinformation,see“KeystoragewithLinuxforIBMSystemz,incontrasttoz/OSforIBM
Systemz”onpage263.
|| REFORMAT Rewraptheinput_key_tokenwiththekeywrappingmethodspecified.Onlytheinput_KEK_identifier
| willbeused.Theoutput_KEK_identifierisignored.ThiskeywordwasintroducedwithCCA4.1.0.
Algorithm(Optional)
AES SpecifiesthatthekeytokenisforanAESkey.
DES SpecifiesthatthekeytokenisforaDESkey.Thisisthedefault.
| Keywrappingmethod(Optional)
|| USECONFG Wrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.Thisisthedefault.
|| WRAP-ENH Useenhancedkeywrappingmethod,whichiscompliantwiththeANSIX9.24standard.
|| WRAP-ECB Useoriginalkeywrappingmethod,whichusesECBwrappingforDESkeytokensandCBC
| wrappingforAESkeytokens.
| Translationcontrol(Optional)
|| ENH-ONLY Restrictrewrappingoftheoutput_key_token.Afterthetokenhasbeenwrappedwiththeenhanced
| method,itcannotberewrappedusingtheoriginalmethod.
key_identifier
Direction: Input/Output Type: String
The key_identifier parameter is a pointer to a string variable containing the DES internal key-token or
the key label of an internal key-token record in key storage.
Restrictions
None
Required commands
| If you specify the RTCMK keyword, the Key Token Change verb requires the DES Key Token Change
| command (offset X'0090') to be enabled in the active role.
164 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Change (CSNBKTC)
| If you specify the REFORMAT keyword, the Key Token Change verb requires the CKDS Conversion2 -
| Allow use of REFORMAT command (offset X'014C') to be enabled in the active role.
| If you specify the WRAP-ECB or WRAP-ENH key wrapping method, and the default key-wrapping method
| setting does not match this keyword, theAllow Configuration Override with Keyword in KTC command
| (offset X'0146') must be enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKTCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKTCJ are shown here.
Format
public native void CSNBKTCJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_label );
Chapter5.ManagingAESandDEScryptographickeys 165

Key Token Change2 (CSNBKTC2)
Key Token Change2 (CSNBKTC2)
|
| Use the Key Token Change2 verb to re-encipher a variable-length HMAC key from encryption under the
| old master-key to encryption under the current master-key and to update the keys in internal HMAC
| key-tokens.
| Notes:
| 1. An application system is responsible for keeping all of its keys in a usable form. When the master key
| is changed, the CEX3C implementations can use an internal key that is enciphered by either the
| current or the old master-key. Before the master key is changed a second time, it is important to have
| a key re-enciphered under the current master-key for continued use of the key. Use the Key Token
| Change2 verb to re-encipher such a keys.
| 2. Previous implementations of IBM CCAproducts had additional capabilities with this verb such as
| deleting key records and key tokens in key storage.Also, use of a wild card (*) was supported in those
| implementations.
Format
|
||
CSNBKTC2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| key_identifier_length
| key_identifier )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 2.
| rule_array
|| Direction: Input Type:Array
| The rule_array parameter is a pointer to a string variable containing an array of keywords. The
| keywords are eight bytes in length and must be left-aligned and padded on the right with space
| characters. The rule_array keywords are described in Table40.
|| Table40.KeywordsforKeyTokenChange2controlinformation
|| Keyword Description
| Re-enciphermentmethod(Required)
|| RTCMK Re-enciphersavariable-lengthHMACkeytothecurrentmaster-keyinaninternalkey-tokenin
| applicationstorageorinkeystorage.Ifthesuppliedkeyisalreadyencipheredunderthecurrent
| master-keytheverbreturnsapositiveresponse(returncode0,reasoncode0).Ifthesuppliedkeyis
| encipheredundertheoldmaster-key,thekeyisupdatedtoenciphermentbythecurrentmaster-keyand
| theverbreturnsapositiveresponse(returncode0,reasoncode0).Othercasesreturnsomeformof
| abnormalresponse.
166 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Change2 (CSNBKTC2)
| Table40.KeywordsforKeyTokenChange2controlinformation (continued)
|| Keyword Description
|| RTNMK Re-enciphersaninternalvariable-lengthHMACkeytothenewmaster-key.
| Akeyencipheredunderthenewmasterkeyisnotusable.Itisexpectedthattheuserwillusethis
| keyword(RTNMK)totakeapreparatorystepinre-encipheringanexternalkeystorethattheymanage
| themselvestoanewmaster-key,beforethesetoperationhasoccurred.Notealsothatthenew
| master-keyregistermustbefull;itmusthavehadthelastkeypartloadedandthereforenotbeemptyor
| partiallyfull(partiallyfullmeansthatoneormorekeypartshavebeenloadedbutnotthelastkeypart).
| The'SET'operationmakesthenewmaster-keyoperational,movingittothecurrentmaster-keyregister,
| andthecurrentmaster-keyisdisplacedintotheoldmaster-keyregister.Whenthishappens,allthekeys
| thatwerere-encipheredtothenewmaster-keyarenowusable,becausethenewmaster-keyisnot'new'
| anymore,itis'current'.
| BecausetheRTNMKkeywordisaddedprimarilyforsupportofexternallymanagedkeystorage(see
| “KeyStorageonz/OS(RTNMK-focused)”onpage264,itisnotvalidtopassakey_identiferwhenthe
| RTNMKkeywordisused.Onlyafullinternalkeytoken(encryptedunderthecurrentmaster-key)canbe
| passedforre-enciphermentwiththeRTNMKkeyword.Whenakeylabelispassedalongwiththe
| RTNMKkeyword,theerrorreturncode8withreasoncode181willbereturned.
| Formoreinformation,see“KeystoragewithLinuxforIBMSystemz,incontrasttoz/OSforIBMSystem
| z”onpage263.
| Algorithm(One,required)
|| HMAC SpecifiesthatthekeytokenisforanHMACkey.
|
| key_identifier_length
|| Direction: Input/Output Type: Integer
| The key_identifier_length parameter is a pointer to a string variable containing the length in bytes of
| the key_identifier parameter. This value must be 1 - 800.
| key_identifier
|| Direction: Input/Output Type: String
| The key_identifier parameter is a pointer to a string variable containing a variable-length HMAC
| internal key-token or the key label of an internal key-token record in key storage.
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| If you specify the RTNMK keyword, this verb requires the Symmetric Key Token Change2 command (offset
| X'00F0') to be enabled in the active role.
| If you specify the RTCMK keyword, this verb requires the Symmetric Key Token Change2 - RTCMK
| command (offset X'00F1') to be enabled in the active role.
Usage notes
|
| None
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBKTC2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
Chapter5.ManagingAESandDEScryptographickeys 167

Key Token Change2 (CSNBKTC2)
| The parameters for CSNBKTC2J are shown here.
|
| Format
| public native void CSNBKTC2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger key_identifier_length,
|| byte[] key_identifier );
|
|
|
168 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Parse (CSNBKTP)
Key Token Parse (CSNBKTP)
The Key Token Parse verb disassembles a key token into separate pieces of information. This verb can
disassemble an external key token or an internal key token in application storage.
Use the key_token parameter to specify the key token to disassemble.
This 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. Otherwise, the verb returns return code 4, reason code 2039.
The Key Token Parse verb performs no cryptographic services.
Format
CSNBKTP(
return_code,
reason_code,
exit_data_length,
edit_data,
key_token,
key_type,
rule_array_count,
rule_array,
key_value,
MKVP,
reserved_2,
reserved_3,
control_vector,
reserved_4,
reserved_5,
reserved_6,
master_key_verification_pattern )
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 14.
key_token
Direction: Input Type: String
The key_token parameter is a pointer to a string variable in application storage containing an external
or internal key-token to be disassembled.
Note: You cannot use a key label for a key-token record in key storage. The key token must be in
application storage.
key_type
Direction: Output Type: String
The key_type parameter is a pointer to a string variable containing a keyword defining the key type.
The keyword is eight bytes in length and must be left-aligned and padded on the right with space
characters. Valid key_type keywords are shown here:
Chapter5.ManagingAESandDEScryptographickeys 169

Key Token Parse (CSNBKTP)
CIPHER DATAC IKEYXLAT OPINENC
CVARDEC DATAM IMPORTER PINGEN
CVARENC DATAMV IPINENC PINVER
CVARPINE DECIPHER KEYGENKY SECMSG
CVARXCVL DKYGENKY MAC
CVARXCVR ENCIPHER MACVER
DATA EXPORTER OKEYXLAT
rule_array_count
Direction: Input/Output Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be a minimum of 3.
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
Direction: Output Type: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 eight bytes in length and are left-aligned
and padded on the right with space characters. The rule_array keywords are described in Table41.
Table41.KeywordsforKeyTokenParsecontrolinformation
Keyword Description
Tokentype(Onereturned)
INTERNAL Specifiesaninternalkey-token.
EXTERNAL Specifiesanexternalkey-token.
Keystatus(Onereturned)
KEY Indicatesthekeytokencontainsakey.Thekey_valueparametercontainsthekey.
NO-KEY Indicatesthekeytokendoesnotcontainakey.
| Key-wrappingmethod(Onereturned)
|| WRAP-ECB Thewrappingmethodforthiskeyislegacy.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ENH Thewrappingmethodforthiskeyisenhanced.ThiskeywordwasintroducedwithCCA4.1.0.
Control-vector(CV)status(Onereturned)
CV Thekeytokenspecifiesthatacontrolvectorispresent.Theverbsetsthecontrolvectorvariable
withthevalueofthecontrolvectorfoundinthekeytoken.
NO-CV Thekeytokendoesnotspecifythepresenceofacontrolvector.Theverbsetsthecontrolvector
variablewiththevalueofthecontrolvectorvariablefoundinthekeytoken.
The difference between Key Token Parse (CSNBKTP) and Control Vector Generate (CSNBCVG) is
that Key Token Parse returns the rule_array keywords that apply to a parsed token, such as
EXTERNAL, INTERNALand so forth. These rule_array parameters are returned in addition to
key_type parameter.
| AMEX-CSC DKYL0 EPINGEN KEYLN16 UKPT
| ANSIX9.9 DKYL1 EPINGENA LMTD-KEK VISA-PVV
| ANY DKYL2 EPINVER MIXED WRAP-ECB
| ANY-MAC DKYL3 EXEX NO-SPEC WRAP-ENH
| CLR8-ENC DKYL4 EXPORT NO-XPORT XLATE
| CPINENC DKYL5 GBP-PIN NOOFFSET XPORT-OK
| CPINGEN DKYL6 GBP-PINO NOT-KEK
| CPINGENA DKYL7 IBM-PIN OPEX
| CVVKEY-A DMAC IBM-PINO OPIM
| CVVKEY-B DMKEY IMEX PIN
170 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Token Parse (CSNBKTP)
| DALL DMPIN IMIM REFORMAT
| DATA DMV IMPORT SINGLE
| DDATA DOUBLE INBK-PIN SMKEY
| DEXP DPVR KEY-PART SMPIN
| DIMP ENH-ONLY KEYLN8 TRANSLAT
key_value
Direction: Output Type: String
The key_value parameter is a pointer to a string variable. If the verb returns the KEY keyword in the
rule_array, the key_value parameter contains the 16-byte enciphered key.
MKVP
Direction: Output Type: Integer
The MKVP parameter is a pointer to an integer variable. The verb writes zero into the variable except
when parsing a version X'03' internal key-token.
reserved_2/5
Direction: Output Type: Integer
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
Direction: Output Type: String
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
Direction: Output Type: String
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
Direction: Output Type: String
The control_vector parameter is a pointer to a string variable in application storage. 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
Direction: Output Type: String
The master_key_verification_pattern parameter is a pointer to a string variable in application storage.
For version 0 key-tokens that contain a key, the 8-byte master key version number will be copied to
the variable. Otherwise the variable is filled with eight space characters.
Restrictions
None
Required commands
None
Chapter5.ManagingAESandDEScryptographickeys 171

Key Token Parse (CSNBKTP)
Usage notes
Be aware that Key Token Parse (CSNBKTP) will fail (return code 8, reason code 49) when given a DES
INTERNALkey token that is version X'01'. These tokens are DOUBLE and TRIPLE length DES
INTERNALDATAkey tokens.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKTPJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKTPJ are shown here.
Format
public native void CSNBKTPJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_token,
byte[] key_type,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_value,
hikmNativeInteger master_key_verification_pattern_v3,
hikmNativeInteger reserved_field_2,
byte[] reserved_field_3reserved_field_3,
byte[] control_vectorcontrol_vector,
byte[] reserved_field_4,
hikmNativeInteger reserved_field_5,
byte[] reserved_field_6,
byte[] master_key_verification_pattern_v0);
172 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Translate (CSNBKTR)
Key Translate (CSNBKTR)
The Key Translate verb uses one key-encrypting key to decipher an input key and then enciphers this key
using another key-encrypting key within the secure environment.
Note: All key labels must be unique.
Format
CSNBKTR(
return_code,
reason_code,
exit_data_length,
exit_data,
input_key_token,
input_KEK_key_identifier,
output_KEK_key_identifier,
output_key_token )
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 14.
input_key_token
Direction: Input Type: String
A64-byte string variable containing an external key token. The external key token contains the key to
be re-enciphered (translated).
input_KEK_key_identifier
Direction: Input/Output Type: String
A64-byte string variable containing the internal key token or the key label of an internal key token
record in the DES key storage file. The internal key token contains the key-encrypting key used to
decipher the key. The internal key token 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 1.
output_KEK_key_identifier
Direction: Input/Output Type: String
A64-byte string variable containing the internal key token or the key label of an internal key token
record in the DES key storage file. The internal key token contains the key-encrypting key used to
encipher the key. The internal key token 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 1.
output_key_token
Direction: Output Type: String
A64-byte string variable containing an external key token. The external key token contains the
re-enciphered key.
Restrictions
Triple length DATAkey tokens are not supported.
Required commands
| This verb requires the Key Translate command (offset X'001F') to be enabled in the active role.
Chapter5.ManagingAESandDEScryptographickeys 173

Key Translate (CSNBKTR)
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKTRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKTRJ are shown here.
Format
public native void CSNBKTRJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] input_key_token,
byte[] input_KEK_key_identifier,
byte[] output_KEK_key_identifier,
byte[] output_key_token
);
174 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Translate2 (CSNBKTR2)
Key Translate2 (CSNBKTR2)
|
| The Key Translate2 verb uses one key-encrypting key to decipher an input key and then enciphers this
| key using another key-encrypting key within the secure environment. It can also be used to change the
| wrapping method of the key with a single key-encrypting key.
| To reencipher a key token, specify the external key token, input and output key-encrypting keys. You can
| specify which key wrapping method to use. If no wrapping method is specified, the wrapping method of the
| input_key_token will be used.
| To change the wrapping method of an external key token, specify the REFORMAT rule array keyword, the
| wrapping method to use, the external key token, and the input key-encrypting key. If no wrapping method
| is specified, the wrapping method of the input_key_token will be used. Note that the output_KEK_identifier
| will be ignored.
| Note: All key labels must be unique.
Format
|
||
CSNBKTR2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| input_key_length,
| input_key_token,
| input_KEK_length,
| input_KEK_identifier,
| output_KEK_length,
| output_KEK_identifier,
| output_key_length,
| output_key_token )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 0, 1, 2, or 3.
| rule_array
|| Direction: Input Type: String
| Keywords that provide control information to the verb. The keywords must be 8 bytes of contiguous
| storage with the keyword left-justified in its 8-byte location and padded on the right with blanks. The
| rule_array keywords are described in Table42.
|| Table42.KeywordsforKeyTranslate2controlinformation
|| Keyword Description
| Reencipherment(Optional)
|| REFORMAT Rewraptheinput_key_tokenwiththekeywrappingmethodspecified.Onlythe
| input_KEK_identifierwillbeused.Theoutput_KEK_identifierisignored.
Chapter5.ManagingAESandDEScryptographickeys 175

Key Translate2 (CSNBKTR2)
| Table42.KeywordsforKeyTranslate2controlinformation (continued)
|| Keyword Description
| Key-wrappingmethod(Oneoptional)
|| USECONFG Wrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.Thisisthedefault.
|| WRAP-ENH Useenhancedkeywrappingmethod,whichiscompliantwiththeANSIX9.24standard.
|| WRAP-ECB Useoriginalkeywrappingmethod,whichusesECBwrappingforDESkeytokensandCBC
| wrappingforAESkeytokens.
| Translationcontrol(Optional)
|| ENH-ONLY Restrictrewrappingoftheoutput_key_token.Afterthetokenhasbeenwrappedwiththeenhanced
| method,itcannotberewrappedusingtheoriginalmethod.
|
| input_key_length
|| Direction: Input Type: Integer
| The length of the input_key_token in bytes. The maximum value allowed is 725.
| input_key_token
|| Direction: Input Type: String
| Avariable length string variable containing the external key token. The external key token contains the
| key to be re-enciphered (or rewrapped).
| input_KEK_length
|| Direction: Input Type: Integer
| The length of the input_KEK_identifier in bytes. The maximum value allowed is 725.
| input_KEK_identifier
|| Direction: Input/Output Type: String
| Avariable length string variable containing the internal key token or the key label of an internal key
| token record in the key storage file. The internal key token contains the key-encrypting key used to
| decipher the key. The internal key token 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 1.
| output_KEK_length
|| Direction: Input Type: Integer
| The length of the output_KEK_identifier in bytes. The maximum value is 725.
| If the REFORMAT keyword is specified, this value must be 0.
| output_KEK_identifier
|| Direction: Input/Output Type: String
| Avariable length string variable containing the internal key token or the key label of an internal key
| token record in the key storage file. The internal key token contains the key-encrypting key used to
| encipher the key. The internal key token 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 1.
| If the REFORMAT keyword is specified, this parameter is ignored.
| output_key_length
|| Direction: Input/Output Type: Integer
176 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Translate2 (CSNBKTR2)
| On input, the length of the output area provided for the output_key_token. This must be at least 64
| bytes. On output, the parameter is updated with the length of the token copied to the
| output_key_token.
| output_key_token
|| Direction: Output Type: String
| Avariable length string variable containing an external key token. The external key token contains the
| re-enciphered key.
Restrictions
|
| This verb does not support version X'10' external DES key tokens (RKX key tokens).
| This verb was introduced with CCA4.1.0.
Required commands
|
| This verb requires the Key Translate2 -Allow use of REFORMAT command (offset X'014B') to be enabled
| in the active role if the REFORMAT reencipherment keyword is used.
| Otherwise, the verb requires the Key Translate2 command (offset X'0149') to be enabled.
| To use the translation control keyword WRAP-ECB or WRAP-ENH when the default key-wrapping method
| setting does not match the keyword, the Key Translate2 -Allow wrapping override keywords command
| (offset X'014A') must be enabled.
| 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 CKDS Conversion2 - Convert from
| enhanced to original command (offset X'0147') to be enabled.An active role with offset X'0149' enabled
| can also use the Key Token Change verb to translate a key from the enhanced key-wrapping method to
| the less-secure legacy method.
Usage notes
|
| None
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBKTR2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBKTR2J are shown here.
Chapter5.ManagingAESandDEScryptographickeys 177

Key Translate2 (CSNBKTR2)
|
| Format
| public native void CSNBKTR2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger input_key_length,
| byte[] input_key_token,
| hikmNativeInteger input_KEK_length,
| byte[] input_KEK_identifier,
| hikmNativeInteger output_KEK_length,
| byte[] output_KEK_identifier,
| hikmNativeInteger output_key_length,
|| byte[] output_key_token);
|
|
|
178 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Multiple Clear Key Import (CSNBCKM)
Multiple Clear Key Import (CSNBCKM)
Use the Multiple Clear Key Import verb to import a clear single, double, or triple-length DATAkey that is to
be used to encipher or decipher data. This verb can import only DATAkeys. Multiple Clear Key Import
accepts a clear DATAkey, enciphers it under the master key, and returns the encrypted DATAkey in
operational form in an internal key token.
Format
CSNBCKM(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
clear_key_length,
clear_key,
key_identifier_length,
key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 0, 1, 2, or 3.
rule_array
Direction: Input Type: String
Zero or one keyword that supplies control information to the verb. The keyword must be in eight bytes
of contiguous storage, left-justified and padded on the right with blanks. The rule_array keywords are
described in Table43.
Table43.KeywordsforMultipleClearKeyImportcontrolinformation
Keyword Description
| Algorithm(On,optional)
AES ThekeyshouldbeencipheredunderthemasterkeyasanAESkey.
DES ThekeyshouldbeencipheredunderthemasterkeyasaDESkey.Thisisthedefault.
| Key-wrappingmethod(One,optional)
|| USECONFG Specifiestowrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.
| ThiskeywordisignoredforAESkeys.Thisisthedefault.Thiskeywordwasintroducedwith
| CCA4.1.0.
|| WRAP-ENH Specifiestowrapthekeyusingthelegacywrappingmethod.Thiskeywordisignoredfor
| AESkeys.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ECB Specifiestowrapthekeyusingtheenhancedwrappingmethod.ValidonlyforDESkeys.
| ThiskeywordwasintroducedwithCCA4.1.0.
| Translationcontrol(Optional).Thisisvalidonlywithkey-wrappingmethodWRAP-ENHorwithUSECONFG
| whenthedefaultwrappingmethodisWRAP-ENH.Thisoptioncannotbeusedonakeywithacontrolvector
| valuedtobinaryzeros.ThiskeywordwasintroducedwithCCA4.1.0.
Chapter5.ManagingAESandDEScryptographickeys 179

Multiple Clear Key Import (CSNBCKM)
Table43.KeywordsforMultipleClearKeyImportcontrolinformation (continued)
Keyword Description
|| ENH-ONLY Specifiestorestrictthekeyfrombeingwrappedwiththelegacywrappingmethodafterithas
| beenwrappedwiththeenhancedwrappingmethod.Setsbit56(ENH-ONLY)ofthecontrol
| vectorto1.
clear_key_length
Direction: Input Type: Integer
The clear_key_length specifies the length of the clear key value to import. This length must be 8, 16,
or 24.
clear_key
Direction: Input Type: String
The clear_key specifies the clear key value to import.
key_identifier_length
Direction: Input/Output Type: Integer
The byte length of the key_identifier parameter. This must be exactly 64 bytes.
key_identifier
Direction: Output Type: String
A64-byte string that is to receive the internal key token.AppendixB, “Key token formats,” on page
421 describes the key tokens.
Restrictions
None
Required commands
This verb requires the following commands to be enabled in the active role based on the algorithm or
key-wrapping method:
||||
Algorithmormethod Offset Command
||| AES X'0129' MultipleClearKeyImport/MultipleSecureKeyImport-
| AES
||| DES X'00C3' ClearKeyImport/MultipleClearKeyImport-DES
||| WRAP-ECBorWRAP-ENH X'0141' MultipleClearKeyImport-Allowwrappingoverride
|| used,anddefault keywords
| key-wrappingmethod
| settingdoesnotmatch
| keyword
|
Note: Note:Arole with offset X'00C3' can also use the Clear Key Import verb.
Usage notes
This verb produces an internal DATAtoken with a control vector which is usable on the Cryptographic
Coprocessor Feature. If a valid internal token is supplied as input to the verb in the key_identifier field, that
token's control vector will not be used in the encryption of the clear key value.
180 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Multiple Clear Key Import (CSNBCKM)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCKMJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCKMJ are shown here.
Format
public native void CSNBCKMJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger clear_key_length,
byte[] clear_key,
byte[] target_key_identifier);
Chapter5.ManagingAESandDEScryptographickeys 181

PKA Decrypt (CSNDPKD)
PKA Decrypt (CSNDPKD)
Use this verb to decrypt (unwrap) a formatted key value. This verb unwraps the key, parses it, and returns
the parsed value to the application in the clear. PKCS 1.2 and ZERO-PAD formatting are supported. For
PKCS 1.2, the decrypted data is examined to ensure that it meets RSADSI PKCS #1 block type 2 format
specifications. ZERO-PAD is supported only for external or clear RSAprivate keys.
This verb allows the use of clear or encrypted RSAprivate keys. If an external clear key token is used, the
master keys are not required to be installed in any cryptographic coprocessor and PKAverbs do not have
to be enabled.
Format
CSNDPKD(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
PKA_enciphered_keyvalue_length,
PKA_enciphered_keyvalue,
data_structure_length,
data_structure,
PKA_key_identifier_length,
PKA_key_identifier,
target_keyvalue_length,
target_keyvalue )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
The keyword that provides control information to the verb. The keyword is left-justified in an 8-byte
field and padded on the right with blanks. The rule_array keywords are described in Table44.
Table44.KeywordsforPKADecryptcontrolinformation
Keyword Description
| RecoveryMethod(One,required).Specifiesthemethodtousetorecoverthekeyvalue.
PKCS-1.2 RSADSIPKCS#1blocktype02willbeusedtorecoverthekeyvalue.IntheRSAPKCS#1v2.0
standard,RSAterminologydescribesthisastheRSAES-PKCS1-v1_5format.
ZERO-PAD TheinputPKA_enciphered_keyvalueisdecryptedusingtheRSAprivatekey.Theentireresult
(includingleadingzeros)willbereturnedinthetarget_keyvaluefield.ThePKA_key_identifiermust
beanexternalRSAtokenorthelabelofanexternaltoken.
PKA_enciphered_keyvalue_length
182 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Decrypt (CSNDPKD)
Direction: Input Type: Integer
The length of the PKA_enciphered_keyvalue parameter in bytes. The maximum size that you can
specify is 256 bytes. The length should be the same as the modulus length of the PKA_key_identifier.
PKA_enciphered_keyvalue
Direction: Input Type: String
This field contains the key value protected under an RSApublic key. This byte-length string is
left-justified within the PKA_enciphered_keyvalue parameter.
data_structure_length
Direction: Input Type: Integer
This value must be 0.
data_structure
Direction: Input Type: String
This parameter is ignored.
PKA_key_identifier_length
Direction: Input Type: Integer
The length of the PKA_key_identifier parameter. When the PKA_key_identifier is a key label, this field
specifies the length of the label. The maximum size that you can specify is 2500 bytes.
PKA_key_identifier
Direction: Input Type: String
An internal RSAprivate key token, the label of an internal RSAprivate key token, or an external RSA
private key token containing a clear RSAprivate key in Modulus-Exponent or Chinese Remainder
Theorem format. The corresponding public key was used to wrap the key value.
target_keyvalue_length
Direction: Input/Output Type: Integer
The length of the target_keyvalue parameter. The maximum size that you can specify is 256 bytes. On
return, this field is updated with the actual length of target_keyvalue.
If ZERO-PAD is specified, this length will be the same as the PKA_enciphered_keyvalue_length which
is equal to the RSAmodulus byte length.
target_keyvalue
Direction: Output Type: String
This field will contain the decrypted, parsed key value. If ZERO-PAD is specified, the decrypted key
value, including leading zeros, will be returned.
Restrictions
The exponent of the RSApublic key must be odd.
Required commands
| This verb requires the PKADecrypt command (offset X'011F') to be enabled in the active role.
Usage notes
The RSAprivate key must be enabled for key management functions.
Chapter5.ManagingAESandDEScryptographickeys 183

PKA Decrypt (CSNDPKD)
The hardware configuration sets the limit on the modulus size of keys for key management; thus, this verb
will fail if the RSAkey modulus bit length exceeds this limit.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKDJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKDJ are shown here.
Format
public native void CSNDPKDJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger enciphered_key_length,
byte[] enciphered_key,
hikmNativeInteger data_struct_length,
byte[] data_struct,
hikmNativeInteger RSA_private_key_length,
byte[] RSA_private_key,
hikmNativeInteger key_value_length,
byte[] key_value
);
184 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Encrypt (CSNDPKE)
PKA Encrypt (CSNDPKE)
This verb encrypts a supplied clear key value under an RSApublic key. The supplied key can be formatted
using the PKCS 1.2 or ZERO-PAD methods prior to encryption. The rule_array keyword specifies the
format of the key prior to encryption.
Format
CSNDPKE(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
keyvalue_length,
keyvalue,
data_structure_length,
data_structure,
PKA_key_identifier_length,
PKA_key_identifier,
PKA_enciphered_keyvalue_length,
PKA_enciphered_keyvalue )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
Akeyword that provides control information to the verb. The keyword is left-justified in an 8-byte field
and padded on the right with blanks. The rule_array keywords are described in Table45.
Table45.KeywordsforPKAEncryptcontrolinformation
Keyword Description
| FormattingMethod(One,required).Specifiesthemethodtousetoformatthekeyvaluepriortoencryption.
PKCS-1.2 RSADSIPKCS#1blocktype02formatwillbeusedtoformatthesuppliedkeyvalue.IntheRSA
PKCS#1v2.0standard,RSAterminologydescribesthisastheRSAES-PKCS1-v1_5format.
ZERO-PAD ThekeyvaluewillbepaddedontheleftwithbinaryzerostothelengthofthePKAkeymodulus.
Theexponentofthepublickeymustbeodd.
MRP ThekeyvaluewillbepaddedontheleftwithbinaryzerostothelengthofthePKAkeymodulus.
TheRSApublickeycanhaveanevenoroddexponent.
keyvalue_length
Direction: Input Type: Integer
The length of the keyvalue parameter. The maximum field size is 256 bytes. The actual maximum size
depends on the modulus length of PKA_key_identifier and the formatting method you specify in the
rule_array parameter. See “Usage notes” on page 187.
Chapter5.ManagingAESandDEScryptographickeys 185

PKA Encrypt (CSNDPKE)
keyvalue
Direction: Input Type: String
This field contains the supplied clear key value to be encrypted under the PKA_key_identifier.
data_structure_length
Direction: Input Type: Integer
This value must be 0.
data_structure
Direction: Input Type: String
This field is currently ignored.
PKA_key_identifier_length
Direction: Input Type: Integer
The length of the PKA_key_identifier parameter. When the PKA_key_identifier is a key label, this field
specifies the length of the label. The maximum size that you can specify is 2500 bytes.
PKA_key_identifier
Direction: Input Type: String
The RSApublic or private key token or the label of the RSApublic or private key to be used to encrypt
the supplied key value.
PKA_enciphered_keyvalue_length
Direction: Input/Output Type: Integer
The length of the PKA_enciphered_keyvalue parameter in bytes. The maximum size that you can
specify is 256 bytes. On return, this field is updated with the actual length of
PKA_enciphered_keyvalue.
This length should be the same as the modulus length of the PKA_key_identifier.
PKA_enciphered_keyvalue
Direction: Output Type: String
This field contains the key value protected under an RSApublic key. This byte-length string is
left-justified within the PKA_enciphered_keyvalue parameter.
Restrictions
IMPORTANT
Take note of these important restrictions.
v Amessage can be encrypted provided that it is smaller than the public key modulus.
The term 'smaller' refers to the exact bit count, not the byte count of the modulus. For example,
counting bits, the hexadecimal number X'FF' is several bits longer than the number X'1F', even though
both numbers are one byte long as represented in computer memory.
v The exponent of the RSApublic key must be odd unless the MRP keyword is supplied.
v The RSApublic key modulus size (key size) is limited by the Function Control Vector to accommodate
governmental export and import regulations.
Required commands
| This verb requires the PKAEncrypt command (offset X'011E') to be enabled in the active role.
186 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Encrypt (CSNDPKE)
Usage notes
v For RSADSI PKCS #1 formatting, the key value length must be a minimum of 11 bytes less than the
modulus length of the RSAkey.
v The hardware configuration sets the limit on the modulus size of keys for key management; thus, this
service will fail if the RSAkey modulus bit length exceeds this limit.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKEJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKEJ are shown here.
Format
public native void CSNDPKEJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger key_value_length,
byte[] key_value,
hikmNativeInteger data_struct_length,
byte[] data_struct,
hikmNativeInteger RSA_public_key_length,
byte[] RSA_public_key,
hikmNativeInteger RSA_encipher_length,
byte[] RSA_encipher
);
Chapter5.ManagingAESandDEScryptographickeys 187

Prohibit Export (CSNBPEX)
Prohibit Export (CSNBPEX)
Use this verb to modify an operational key so that it cannot be exported.
Format
CSNBPEX(
return_code,
reason_code,
exit_data_length,
exit_data,
key_identifier )
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 14.
key_identifier
Direction: Input/Output Type: String
A64-byte string variable containing the internal key token to be modified. The returned key_identifier
will be encrypted under the current master key.
Restrictions
None
Required commands
| This verb requires the Prohibit Export command (offset X'00CD') to be enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBPEXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBPEXJ are shown here.
Format
public native void CSNBPEXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_identifier);
188 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Prohibit Export Extended (CSNBPEXX)
Prohibit Export Extended (CSNBPEXX)
Use this verb to modify an exportable external CCADES key-token so that its key can no longer be
exported.
This verb performs the following functions:
v Multiply deciphers the source key under a key formed by the XOR of the source key’s control vector
and the specified key-encrypting key (KEK).
v Turns from on to off the XPORT-OK bit in the source key’s control vector (bit 17).
v Multiply enciphers the key under a key formed by the XOR 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.
Format
CSNBPEXX(
return_code,
reason_code,
exit_data_length,
exit_data,
source_key_token,
KEK_key_identifier )
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 14.
source_key_token
Direction: Input/Output Type: String
Apointer to a string variable containing an external key-token.
KEK_key_identifier
Direction: Input Type: String
Apointer to a string variable containing an internal key-encrypting token, or the key label of an internal
key-encrypting token record.
Restrictions
This verb does not support version X'10' external DES key tokens (RKX key tokens).
Required commands
| This verb requires the Prohibit Export Extended command (offset X'0301') to be enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBPEXXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBPEXXJ are shown here.
Chapter5.ManagingAESandDEScryptographickeys 189

Prohibit Export Extended (CSNBPEXX)
Format
public native void CSNBPEXXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] source_key_token,
byte[] KEK_key_identifier);
190 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Random Number Generate (CSNBRNG)
Random Number Generate (CSNBRNG)
This verb uses the cryptographic feature to generate a cryptographic-quality random number.
Format
CSNBRNG(
return_code,
reason_code,
exit_data_length,
exit_data,
form,
random_number )
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 14.
form
Direction: Input Type: String
The 8-byte keyword that defines the characteristics of the random number should be left-justified and
padded on the right with blanks. The keywords are listed in Table46.
Table46.KeywordsforRandomNumberGenerateformparameter
Keyword Description
EVEN Generatea64-bitrandomnumberwithevenparityineachbyte.
ODD Generatea64-bitrandomnumberwithoddparityineachbyte.
RANDOM Generatea64-bitrandomnumber.
Parity is calculated on the seven high-order bits in each byte and is presented in the low-order bit in
the byte.
random_number
Direction: Output Type: String
The generated number returned by the verb in an 8-byte variable.
Restrictions
None
Required commands
| This verb requires the Key Generate - OP_IM_EX command (offset X'008E') to be enabled in the active
| role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBRNGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBRNGJ are shown here.
Chapter5.ManagingAESandDEScryptographickeys 191

Random Number Generate (CSNBRNG)
Format
public native void CSNBRNGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] form,
byte[] random_number );
192 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Random Number Generate Long (CSNBRNGL)
Random Number Generate Long (CSNBRNGL)
This verb uses the cryptographic feature to generate a cryptographic-quality random number from 1 - 8192
bytes in length. Choose the parity of each generated random byte as even, odd, or random. This verb
returns the random number in a string variable.
Because this verb uses cryptographic processes, the quality of the output is better than that which
higher-level language compilers typically supply.
Format
CSNBRNGL(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
seed_length,
seed,
random_number_length,
random_number )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
Apointer to a string variable containing an array of keywords. The keywords are eight bytes in length,
and must be left-justified and padded on the right with space characters. The rule_array keywords are
described in Table47.
Table47.KeywordsforRandomNumberGenerateLongcontrolinformation
Keyword Description
Parityadjust(Onerequired)
EVEN Specifiesthateachgeneratedrandombyteisadjustedforevenparity.
ODD Specifiesthateachgeneratedrandombyteisadjustedforoddparity.
RANDOM Specifiesthateachgeneratedrandombyteisnotadjustedforparity.
seed_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes in the seed variable. This value must
be 0.
seed
Direction: Input Type: String
Chapter5.ManagingAESandDEScryptographickeys 193

Random Number Generate Long (CSNBRNGL)
| This parameter is ignored.
random_number_length
Direction: Input/Output Type: Integer
Apointer 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
Direction: Output Type: String
Apointer to a string variable containing the random number generated.
Restrictions
None
Required commands
None
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBRNGLJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBRNGLJ are shown here.
Format
public native void CSNBRNGLJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger reserved_seed_length,
byte[] reserved_seed,
hikmNativeInteger random_number_length,
byte[] random_number);
194 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Restrict Key Attribute (CSNBRKA)
Restrict Key Attribute (CSNBRKA)
|
| Use the Restrict KeyAttribute verb to modify an exportable internal or external variable-length symmetric
| key-token so that its key can no longer be exported.
Format
|
||
CSNBRKA (
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array
| key_identifier_length
| key_identifier
| key_encrypting_key_identifier_length
| key_encrypting_key_identifier
| opt_parameter1_length
| opt_parameter1
| opt_parameter2_length
| opt_parameter2
| )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 1 or 2.
| rule_array
|| Direction: Input Type: String
| The rule_array contains keywords that provide control information to the verb. The keywords must be
| in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on
| the right with blanks. The rule_array keywords are described in Table48.
|| Table48.KeywordsforRestrictKeyAttributecontrolinformation
|| Keyword Description
| Tokentype(One,required)
|| HMAC SpecifiesthekeytokenisanHMACkeytoken.
| Exportcontrol(One,optional)
|| NOEXPORT Prohibitsthekeyfrombeingexportedusingasymmetrickeyandprohibitsthekeyfrombeingexported
| usinganasymmetrickey.Thisisthedefault.
|| NOEX-SYM Prohibitsthekeyfrombeingexportedusingasymmetrickey.
|| NOEXUASY Prohibitsthekeyfrombeingexportedusinganunauthenticatedasymmetrickey.
|| NOEXAASY Prohibitsthekeyfrombeingexportedusinganauthenticatedasymmetrickey(forexample,anRSA
| keyinatrustedblocktoken).
|
| key_identifier_length
|| Direction: Input Type: Integer
Chapter5.ManagingAESandDEScryptographickeys 195

Restrict Key Attribute (CSNBRKA)
| The length of the key_identifier parameter in bytes. The maximum value is 725.
| key_identifier
|| Direction: Input Type: String
| The key for which the export control is to be updated. The parameter contains an internal token or the
| 64-byte label of the key in key storage. If a label is specified, the key token will be updated in key
| storage and not returned by this verb.
| key_encrypting_key_identifier_length
|| Direction: Input Type: Integer
| The byte length of the key_encrypting_key_identifier parameter. This value must be 0.
| key_encrypting_key_identifier
|| Direction: Input Type: String
| This parameter is ignored.
| opt_parameter1_length
|| Direction: Input Type: Integer
| The byte length of the opt_parameter1 parameter. This value must be 0.
| opt_parameter1
|| Direction: Input Type: String
| This parameter is ignored.
| opt_parameter2_length
|| Direction: Input Type: Integer
| The byte length of the opt_parameter2 parameter. This value must be 0.
| opt_parameter2
|| Direction: Input Type: String
| This parameter is ignored.
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| The currently supported service (Restrict Export of HMAC tokens) requires the Restrict KeyAttribute -
| Export Control command (offset X''00E9') to be enabled in the active role.
Usage notes
|
| This verb is available starting with CCA4.1.0.
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBRKAJ. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBRKAJ are shown here.
196 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Restrict Key Attribute (CSNBRKA)
|
| Format
| public native void CSNBRKAJ(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger key_identifier_length
| byte[] key_identifier
| hikmNativeInteger key_encrypting_key_identifier_length
| byte[] key_encrypting_key_identifier
| hikmNativeInteger opt_parameter1_length
| byte[] opt_parameter1
| hikmNativeInteger opt_parameter2_length
|| byte[] opt_parameter2);
|
|
|
Chapter5.ManagingAESandDEScryptographickeys 197

Symmetric Key Export (CSNDSYX)
Symmetric Key Export (CSNDSYX)
| Use this verb to transfer an application-supplied symmetric key (a DATAkey) from encryption under the
| AES or DES master key to encryption under an application-supplied RSApublic key. The
| application-supplied DATAkey must be anAES, DES or HMAC internal key token or the label of anAES
| or DES key token in theAES or DES key storage file. The Symmetric Key Import and Symmetric Key
| Import2 verbs can import the PKA-encrypted key form at the receiving node.
| Beginning with CCA4.1.0, the verb can also export an HMAC key that is contained in an internal
| variable-length symmetric key-token. The exported key is returned in an external variable-length symmetric
| key-token.
| Use the Symmetric Key Import verb to import a key exported using theAES or DES algorithm, and the
| Symmetric Key Import2 verb to import a key exported using the HMAC algorithm.
Format
CSNDSYX(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
source_key_identifier_length,
source_key_identifier,
RSA_public_key_identifier_length,
RSA_public_key_identifier,
RSA_enciphered_key_length,
RSA_enciphered_key )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1, 2, or 3.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left-justified in 8-byte fields and
padded on the right with blanks.All keywords must be in contiguous storage. The rule_array keywords
are described in Table49.
Table49.KeywordsforSymmetricKeyExportcontrolinformation
Keyword Description
Algorithm(One,optional)
AES ExportanAESkey.
DES ExportaDESkey.Thisisthedefault.
|| HMAC ExportanHMACkey.ThiskeywordwasintroducedwithCCA4.1.0.
| Recoverymethod(One,required)
198 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Key Export (CSNDSYX)
Table49.KeywordsforSymmetricKeyExportcontrolinformation (continued)
Keyword Description
PKCSOAEP SpecifiesusingthemethodfoundinRSADSIPKCS#1V2OAEP.See“PKCS#1formats”onpage
513.
PKCS-1.2 SpecifiesusingthemethodfoundinRSADSIPKCS#1blocktype02torecoverthesymmetrickey.
IntheRSAPKCS#1v2.0standard,RSAterminologydescribesthisastheRSAES-PKCS1-v1_5
format.See“PKCS#1formats”onpage513.
|| PKOAEP2 SpecifiesthatthekeyisformattedasdefinedintheRSAPKCS#1v2.1standardforthe
| RSAES-OAEPencryptionmechanism.ValidonlywithalgorithmHMAC.Thiskeywordwasintroduced
| withCCA4.1.0.See“PKCS#1formats”onpage513.
ZERO-PAD Theclearkeyisright-justifiedinthefieldprovided,andthefieldispaddedtotheleftwithzerosupto
thesizeoftheRSAencryptionblock(whichisthemoduluslength).
| Hashmethod(whenPKOAEP2isspecified,onerequired)
|| SHA-1 SpecifiestousetheSHA-1hashmethodtocalculatetheOAEPmessagehash.Thiskeywordwas
| introducedwithCCA4.1.0.
|| SHA-256 SpecifiestousetheSHA-256hashmethodtocalculatetheOAEPmessagehash.Thiskeywordwas
| introducedwithCCA4.1.0.
|| SHA-384 SpecifiestousetheSHA-384hashmethodtocalculatetheOAEPmessagehash.Thiskeywordwas
| introducedwithCCA4.1.0.
|| SHA-512 SpecifiestousetheSHA-512hashmethodtocalculatetheOAEPmessagehash.Thiskeywordwas
| introducedwithCCA4.1.0.
source_key_identifier_length
Direction: Input Type: Integer
The length of the source_key_identifier parameter. The maximum length is 3500 bytes.
source_key_identifier
Direction: Input Type: String
| The label or internal token of a secureAES DATA, DES DATA, or HMAC key to encrypt under the
| supplied RSApublic key. The key in the key identifier must match the algorithm in the rule_array. DES
| is the default algorithm.
RSA_public_key_identifier_length
Direction: Input Type: Integer
The length of the RSA_public_key_identifier parameter. The maximum size is 3500 bytes.
RSA_public_key_identifier
Direction: Input Type: String
Apointer to a string variable containing a PKA96 RSAinternal or external key-token with the RSA
public key of the remote node that is to import the exported key.
RSA_enciphered_key_length
Direction: Input/Output Type: Integer
The length of the RSA_enciphered_key parameter. On input, this is a pointer to an integer variable
containing the number of bytes of data in the RSA_enciphered_key variable. On output, the variable is
updated with the actual length of the RSA_enciphered_key variable. The maximum length is 3500
bytes.
RSA_enciphered_key
Direction: Output Type: String
Chapter5.ManagingAESandDEScryptographickeys 199

Symmetric Key Export (CSNDSYX)
This field contains the output RSA-enciphered key, protected by the public key specified in the
RSA_public_key_identifier field.
Restrictions
None
Required commands
This 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
|||| PKOAEP2 HMAC X'00F5' SymmetricKeyExport-HMAC_PKCSOAEP
|||| PKCSOAEPor AES X'0130' Symmetric Key Export - AES_ PKCSOAEP_ PKCS-1.2
|||| PKCS-1.2 DES X'0105' Symmetric Key Export - DES_ PKCS-1.2
|||| ZERO-PAD AES X'0131' Symmetric Key Export - AES_ ZERO-PAD
||| DES X'023E' Symmetric Key Export - DES_ ZERO-PAD
|
Usage notes
The hardware configuration sets the limit on the modulus size of keys for key management; thus, this verb
will fail if the RSAkey modulus bit length exceeds this limit.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDSYXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDSYXJ are shown here.
Format
public native void CSNDSYXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger source_key_identifier_length,
byte[] source_key_identifier,
hikmNativeInteger RSA_public_key_token_length,
byte[] RSA_public_key_token,
hikmNativeInteger RSA_enciphered_key_length,
byte[] RSA_enciphered_key
);
Symmetric Key Import
200 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Key Generate (CSNDSYG)
Symmetric Key Generate (CSNDSYG)
| Use the Symmetric Key Generate verb to generate anAES or DES DATAkey and return the key in two
| forms: enciphered under the master key and encrypted under an RSApublic key.
| You can import the RSApublic key encrypted form by using the Symmetric Key Import or Symmetric Key
| Import2 verbs at the receiving node.
| Also use the Symmetric Key Generate verb to generate any DES importer or exporter key-encrypting key
| encrypted under a RSApublic key according to the PKA92 formatting structure. See “PKA92 key format
| and encryption process” on page 511 for more details about PKA92 formatting.
Format
CSNDSYG(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_encrypting_key_identifier,
RSA_public_key_identifier_length,
RSA_public_key_identifier,
DES_enciphered_key_token_length,
DES_enciphered_key_token,
RSA_enciphered_key_length,
RSA_enciphered_key )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be between 1 and 6.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. The recovery method is the method to use to
recover the symmetric key. Each keyword is left-justified in an 8-byte field and padded on the right with
blanks.All keywords must be in contiguous storage. The rule_array keywords are described in
Table50.
Table50.KeywordsforSymmetricKeyGeneratecontrolinformation
Keyword Description
Algorithm(One,optional)
AES SpecifiestogenerateanAESkey.
DES SpecifiestogenerateaDESkey.Thisisthedefault.
Key-formattingmethod(Onerequired)
PKA92 Specifiesthekey-encryptingkeyistobeencryptedunderaPKA96RSApublickeyaccordingtothe
PKA92formattingstructure.
Chapter5.ManagingAESandDEScryptographickeys 201

Symmetric Key Generate (CSNDSYG)
Table50.KeywordsforSymmetricKeyGeneratecontrolinformation (continued)
Keyword Description
PKCSOAEP SpecifiesusingthemethodfoundinRSADSIPKCS#1V2OAEP.
PKCS-1.2 SpecifiesthemethodfoundinRSADSIPKCS#1blocktype02.IntheRSAPKCS#1v2.0standard,
RSAterminologydescribesthisastheRSAES-PKCS1-v1_5format.
ZERO-PAD Theclearkeyisright-justifiedinthefieldprovided,andthefieldispaddedtotheleftwithzerosupto
thesizeoftheRSAencryptionblock(whichisthemoduluslength).
Keylength(One,optionalusewithPKA92)
SINGLE-R Generatesakey-encryptingkeythathasequalleftandrighthalvesallowingittoperformasa
single-lengthkey.ValidonlyfortherecoverymethodofPKA92.
Keylength(One,optionalusewithPKCSOAEP,PKCS-1.2,orZERO-PAD)
SINGLE, Generatesasingle-lengthDESkey.ThisisthedefaultforDESkeys.
KEYLN8
DOUBLE Generatesadouble-lengthDESkey.ValidonlyforDESkeys.
KEYLN16 Generatesadouble-lengthDESDATAkey.ThisisthedefaultforAESkeys.
KEYLN24 Generatesatriple-lengthDESDATAkey.ValidonlyforAESkeys
KEYLN32 Generatesa32-byteAESkey.ValidonlyforAESkeys
Enciphermentmethodforthelocalencipheredcopyofthekey(One,optionalforusewithPKCSOAEP,
PKCS-1.2,andZERO-PAD)
EX TheDESencipheredkeyisencipheredbyanEXPORTERkeythatisprovidedthroughthe
key_encrypting_key_identifierparameter.
IM TheDESencipheredkeyisencipheredbyanIMPORTERkeythatisprovidedthroughthe
key_encrypting_key_identifierparameter.
OP TheDESencipheredkeyisencipheredbythemasterkey.Thekey_encrypting_key_identifier
parameterisignored.Thisisthedefault.
| Key-wrappingmethod(One,optional)
|| USECONFG Specifiestowrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.Thiskeyword
| isignoredforAESkeys.Thisisthedefault.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ENH Specifiestowrapthekeyusingthelegacywrappingmethod.ThiskeywordisignoredforAESkeys.
| ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ECB Specifiestowrapthekeyusingtheenhancedwrappingmethod.ValidonlyforDESkeys.Thiskeyword
| wasintroducedwithCCA4.1.0.
| Translationcontrol(Optional)Thisisvalidonlywithkey-wrappingmethodWRAP-ENHorwithUSECONFGwhen
| thedefaultwrappingmethodisWRAP-ENH.Thisoptioncannotbeusedonakeywithacontrolvectorvaluedto
| binaryzeros.
|| ENH-ONLY Specifiestorestrictthekeyfrombeingwrappedwiththelegacywrappingmethodafterithasbeen
| wrappedwiththeenhancedwrappingmethod.Setsbit56(ENH-ONLY)ofthecontrolvectorto1.This
| keywordwasintroducedwithCCA4.1.0.
key_encrypting_key_identifier
Direction: Input/Output Type: String
The label or internal token of a key-encrypting key. If the rule_array specifies IM, this DES key must
be an IMPORTER. If the rule_array specifies EX, this DES key must be an EXPORTER.
RSA_public_key_identifier_length
Direction: Input Type: Integer
The length of the RSA_public_key_identifier parameter. If the RSA_public_key_identifier parameter is
a label, this parameter specifies the length of the label. The maximum size is 3500 bytes.
202 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Key Generate (CSNDSYG)
RSA_public_key_identifier
Direction: Input Type: String
The token, or label, of the RSApublic key to be used for protecting the generated symmetric key.
local_enciphered_key_identifier_length
Direction: Input/Output Type: Integer
The length of the local_enciphered_key_identifier. This field is updated with the actual length of the
local_enciphered_key_identifier that is generated. The maximum length is 3500 bytes. However, this
value should be 64 as in current CCApractice a DES key-token or a key label is always a 64-byte
structure.
local_enciphered_key_identifier
Direction: Input/Output Type: String
Apointer to a string variable containing either a key name or a 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 key-token. Otherwise, specify an internal key-token or
a null key-token.
When PKCSOAEP, PKCS-1.2, or ZERO-PAD is specified, a null key-token can be specified. In this
case, anAES DATAor DES DATAkey is returned. For an internal key (OP), a defaultAES DATAor
DATAcontrol-vector is returned in the key token. For an external key (IM or EX), the control vector is
set to null.
RSA_enciphered_key_length
Direction: Input/Output Type: Integer
The length of the RSA_enciphered_key parameter. This verb updates this with the actual length of the
RSA_enciphered_key it generates. The maximum size is 3500 bytes.
RSA_enciphered_key
Direction: Input/Output Type: String
Apointer to a string variable containing the generated RSA-enciphered key returned by the verb. If
you specify PKCSOAEP, PKCS-1.2, or ZERO-PAD, on input specify a null key token. If you specify
PKA92 on input specify an internal (operational) CCADES key-token.
Restrictions
None
Required commands
This 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
|||| PKCSOAEPor AES X'012C' Symmetric Key Generate - AES_ PKCSOAEP_
|||| PKCS-1.2 DES PKCS-1.2
|| X'023F' Symmetric Key Generate - DES_ PKCS-1.2
|||| ZERO-PAD AES X'012D' Symmetric Key Generate - AES_ ZERO-PAD
||| DES X'023C' ZERO-PAD Symmetric Key Generate
|||| PKA92 DES X'010D' SymmetricKeyGenerate-DES_PKA92
|
Chapter5.ManagingAESandDEScryptographickeys 203

Symmetric Key Generate (CSNDSYG)
| The use of the WRAP-ECB or WRAP-ENH key-wrapping method keywords requires the Symmetric Key
| Generate -Allow wrapping override keywords command (offset X'013E') to be enabled.
Usage notes
The hardware configuration sets the limit on the modulus size of keys for key management; thus, this verb
will fail if the RSAkey modulus bit length exceeds this limit.
Specification of PKA92 with an input NOCV key-encrypting key token is not supported.
Use the PKA92 key-formatting method to generate a key-encrypting key. The verb enciphers one key copy
using the key encipherment technique employed in the IBM Transaction Security System (TSS) 4753,
4755, andAS/400® cryptographic product PKA92 implementations (see “PKA92 key format and encryption
process” on page 511). The control vector for the RSA-enciphered copy of the key is taken from an
internal (operational) DES key token that must be present on input in the RSA_enciphered_key variable.
Only key-encrypting keys that conform to the rules for an OPEX case under the Key Generate verb are
permitted. The control vector for the local key is taken from a DES key token that must be present on
input in the DES_enciphered_key_token variable. The control vector for one key copy must be from the
EXPORTER class while the control vector for the other key copy must be from the IMPORTER class.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDSYGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDSYGJ are shown here.
Format
public native void CSNDSYGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
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_token_length,
byte[] RSA_enciphered_key_token
);
204 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Key Import (CSNDSYI)
Symmetric Key Import (CSNDSYI)
| Use the Symmetric Key Import verb to import a symmetricAES DATAor DES DATAkey enciphered under
| an RSApublic key. The verb returns the key in operational form, enciphered under the master key.
This verb also supports import of a PKA92-formatted DES key-encrypting key under a PKA96 RSApublic
key.
Format
CSNDSYI(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
RSA_enciphered_key_length,
RSA_enciphered_key,
RSA_private_key_identifier_length,
RSA_private_key_identifier,
target_key_identifier_length,
target_key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1, 2, 3, or 4.
rule_array
Direction: Input Type: String
The keyword that provides control information to the verb. The recovery method is the method to use
to recover the symmetric key. The keyword is left-justified in an 8-byte field and padded on the right
with blanks. The rule_array keywords are described in Table51.
Table51.KeywordsforSymmetricKeyImportcontrolinformation
Keyword Description
Algorithm(One,optional)
AES ExportanAESkey.
DES ExportaDESkey.Thisisthedefault.
Recoverymethod(Onerequired)
PKA92 Specifiesthekey-encryptingkeyisencryptedunderaPKA96RSApublickeyaccording
tothePKA92formattingstructure.
PKCSOAEP SpecifiesusingthemethodfoundinRSADSIPKCS#1V2OAEP.
PKCS-1.2 SpecifiesthemethodfoundinRSADSIPKCS#1blocktype02.IntheRSAPKCS#1
v2.0standard,RSAterminologydescribesthisastheRSAES-PKCS1-v1_5format.
ZERO-PAD Theclearkeyisright-justifiedinthefieldprovided,andthefieldispaddedtotheleftwith
zerosuptothesizeoftheRSAencryptionblock(whichisthemoduluslength).
Chapter5.ManagingAESandDEScryptographickeys 205

Symmetric Key Import (CSNDSYI)
Table51.KeywordsforSymmetricKeyImportcontrolinformation (continued)
Keyword Description
| Key-wrappingmethod(One,optional)
|| USECONFG Specifiestowrapthekeyusingtheconfigurationsettingforthedefaultwrappingmethod.
| ThiskeywordisignoredforAESkeys.Thisisthedefault.Thiskeywordwasintroduced
| withCCA4.1.0.
|| WRAP-ENH Specifiestowrapthekeyusingthelegacywrappingmethod.Thiskeywordisignoredfor
| AESkeys.ThiskeywordwasintroducedwithCCA4.1.0.
|| WRAP-ECB Specifiestowrapthekeyusingtheenhancedwrappingmethod.ValidonlyforDESkeys.
| ThiskeywordwasintroducedwithCCA4.1.0.
| Translationcontrol(Optional)Thisisvalidonlywithkey-wrappingmethodWRAP-ENHorwithUSECONFG
| whenthedefaultwrappingmethodisWRAP-ENH.Thisoptioncannotbeusedonakeywithacontrolvector
| valuedtobinaryzeros.
|| ENH-ONLY Specifiestorestrictthekeyfrombeingwrappedwiththelegacywrappingmethodafterit
| hasbeenwrappedwiththeenhancedwrappingmethod.Setsbit56(ENH-ONLY)ofthe
| controlvectorto1.ThiskeywordwasintroducedwithCCA4.1.0.
RSA_enciphered_key_length
Direction: Input Type: Integer
The length of the RSA_enciphered_key parameter. The maximum size is 3500 bytes.
RSA_enciphered_key
Direction: Input Type: String
The key to import, protected under an RSApublic key. The encrypted key is in the low-order bits
(right-justified) of a string whose length is the minimum number of bytes that can contain the encrypted
key. This string is left-justified within the RSA_enciphered_key parameter.
RSA_private_key_identifier_length
Direction: Input Type: Integer
The length of the RSA_private_key_identifier parameter. When the RSA_private_key_identifier
parameter is a key label, this field specifies the length of the label. The maximum size is 3500 bytes.
RSA_private_key_identifier
Direction: Input Type: String
An internal RSAprivate key token or label whose corresponding public key protects the symmetric key.
target_key_identifier_length
Direction: Input/Output Type: Integer
The length of the target_key_identifier parameter. This field is updated with the actual length of the
target_key_identifier that is generated. The maximum length is 3500 bytes.
target_key_identifier
Direction: Input/Output Type: String
This field contains the internal token of the imported symmetric key.
Except for PKA92 processing, this verb produces a DATAkey token with a key of the same length as
that contained in the imported token.
Restrictions
None.
206 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Key Import (CSNDSYI)
Required commands
This 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
|||| PKA92andDATA, DES X'0235' SymmetricKeyImport-DES_PKA92KEK
| MAC,MACVER,
| KEYGENKY,
| EXPORTER,or
| OKEYXLATkey
|||| PKCSOAEPor AES X'012E' Symmetric Key Import - AES_ PKCSOAEP_ PKCS-1.2
|||| PKCS-1.2 DES X'0106' Symmetric Key Import - DES_ PKCS-1.2
|||| WRAP-ECBor DES X'0144' SymmetricKeyImport-Allowwrappingoverridekeywords
| WRAP-ENHused,
| anddefault
| key-wrappingmethod
| settingdoesnot
| matchkeyword
|||| ZERO-PAD AES X'012F' Symmetric Key Import - AES_ ZERO-PAD
||| DES X'023D' Symmetric Key Import - DES_ ZERO-PAD
|
Usage notes
The hardware configuration sets the limit on the modulus size of keys for key management; thus, this verb
will fail if the RSAkey modulus bit length exceeds this limit.
Specification of PKA92 with an input NOCV key-encrypting key token is not supported.
During initialization of a CEX3C, an Environment Identifier (EID) of zero will be set in the coprocessor. This
will be interpreted by the Symmetric Key Import verb to mean that environment identification checking is to
be bypassed. Thus it is possible on a Linux on IBM System z system for a key-encrypting key
RSA-enciphered at a node (EID) to be imported at the same node.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDSYIJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDSYIJ are shown here.
Format
public native void CSNDSYIJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger RSA_enciphered_key_length,
byte[] RSA_enciphered_key,
hikmNativeInteger RSA_private_key_identifier_length,
byte[] RSA_private_key_identifier,
hikmNativeInteger target_key_identifier_length,
byte[] target_key_identifier
);
Chapter5.ManagingAESandDEScryptographickeys 207

Symmetric Key Import2 (CSNDSYI2)
Symmetric Key Import2 (CSNDSYI2)
|
| Use the Symmetric Key Import2 verb to import an HMAC key that has been previously formatted and
| enciphered under an RSApublic key by the Symmetric Key Export (CSNDSYX) verb. The formatted and
| RSA-enciphered key is contained in an external variable-length symmetric key token. It is deciphered
| using the associated RSAprivate-key. The recovered HMAC key is reenciphered under theAES
| master-key. The re-enciphered key is then returned in an internal variable-length symmetric key-token. The
| key algorithm for this verb is HMAC.
Format
|
||
CSNDSYI2(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| RSA_enciphered_key_length,
| RSA_enciphered_key,
| RSA_private_key_identifier_length,
| RSA_private_key_identifier,
| key_name_length,
| key_name,
| target_key_identifier_length,
| target_key_identifier )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 2.
| rule_array
|| Direction: Input Type: String
| The keywords that provide control information to the verb. The following table provides a list. The
| recovery method is the method to use to recover the symmetric key. The keywords must be 8 bytes of
| contiguous storage with the keyword left-justified in its 8-byte location and padded on the right with
| blanks. The rule_array keywords are described in Table52.
|| Table52.KeywordsforSymmetricKeyImport2controlinformation
|| Keyword Description
| Algorithm(One,required)
|| HMAC ThekeybeingimportedisanHMACkey.OnlythePKOAEP2recoverymethodissupported.
| Recoverymethod(One,required)
|| PKOAEP2 SpecifiestoformatthekeyaccordingtothemethodfoundinRSADSIPKCS#1v2.1RSAES-OAEP
| documentation.
|
| RSA_enciphered_key_length
|| Direction: Input Type: Integer
| The length of the RSA_enciphered_key parameter. The maximum size is 512 bytes.
208 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Key Import2 (CSNDSYI2)
| RSA_enciphered_key
|| Direction: Input Type: String
| The key to import, protected under an RSApublic key. The encrypted key is in the low-order bits
| (right-justified) of a string whose length is the minimum number of bytes that can contain the encrypted
| key. This string is left-justified within the RSA_enciphered_key parameter.
| RSA_private_key_identifier_length
|| Direction: Input Type: Integer
| The length of the RSA_private_key_identifier parameter. When the RSA_private_key_identifier
| parameter is a key label, this field specifies the length of the label. The maximum size is 3500 bytes.
| RSA_private_key_identifier
|| Direction: Input Type: String
| An internal RSAprivate key token or the 64-byte label whose corresponding public key protects the
| symmetric key.
| key_name_length
|| Direction: Input Type: Integer
| The length of the key_name parameter for target_key_identifier. Valid values are 0 and 64.
| key_name
|| Direction: Input Type: String
| A64-byte key store label to be stored in the associated data structure of target_key_identifier.
| target_key_identifier_length
|| Direction: Input/Output Type: Integer
| On input, the byte length of the buffer for the target_key_identifier parameter. The buffer must be large
| enough to receive the target key token. The maximum value is 725 bytes.
| On output, the parameter will hold the actual length of the target key token.
| target_key_identifier
|| Direction: Output Type: String
| This parameter contains the internal token of the imported symmetric key.
Restrictions
|
| This verb was introduced with CCA4.1.0.
Required commands
|
| This verb requires the Symmetric Key Import2 - HMAC_PKCSOAEP command (offset X'00F4') to be
| enabled in the active role.
Usage notes
|
| This is the message layout used to encode the key material exported with the PKOAEP2 formatting
| method.
|| Table53.PKCS#1OAEPencodedmessagelayout(PKOAEP2)
||| Field Size Value
||| Hashfield 32Bytes SHA-256hashofassociateddatasectionin
| thesourcekeyidentifier
Chapter5.ManagingAESandDEScryptographickeys 209

Symmetric Key Import2 (CSNDSYI2)
| Table53.PKCS#1OAEPencodedmessagelayout(PKOAEP2) (continued)
||| Field Size Value
||| KeyBitLength 2Bytes variable
||| KeyMaterial Bytelengthofthekeymaterial(roundedupto variable
| thenearestbyte)
|
| Hash field
| The associated data for the HMAC variable length token is hashed using SHA-256.
| Key Bit Length
| A2 Byte key bit length field.
| Key Material
| The key material is padded to the nearest byte with '0' bits.
| The hardware configuration sets the limit on the modulus size of keys for key management; thus, this verb
| will fail if the RSAkey modulus bit length exceeds this limit.
| Specification of PKA92 with an input NOCV key-encrypting key token is not supported.
| During initialization of a CEX3C, an Environment Identifier (EID) of zero will be set in the coprocessor. This
| will be interpreted by the Symmetric Key Import2 verb to mean that environment identification checking is
| to be bypassed. Thus it is possible on a Linux on IBM System z system for a key-encrypting key
| RSA-enciphered at a node (EID) to be imported at the same node.
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNDSYI2J. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNDSYI2J are shown here.
|
| Format
| public native void CSNDSYI2J(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger RSA_enciphered_key_length,
| byte[] RSA_enciphered_key,
| hikmNativeInteger RSA_private_key_identifier_length,
| byte[] RSA_private_key_identifier,
| hikmNativeInteger key_name_length,
| byte[] key_name,
| hikmNativeInteger target_key_identifier_length,
| byte[] target_key_identifier
|| );
|
|
|
210 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 6. Protecting data
Use CCAto protect sensitive data stored on your system, sent between systems, or stored off your system
on magnetic tape. To protect data, encipher it under a key. When you want to read the data, decipher it
from ciphertext to plaintext form.
CCAprovides Encipher and Decipher verbs to perform these functions. If you use a key to encipher data,
you must use the same key to decipher the data. The Encipher and Decipher verbs use encrypted keys as
input. You can also use clear keys, indirectly, by first using the Clear Key Import verb and then using the
Encipher and Decipher verbs.
This chapter describes the following verbs used for protecting data using DES orAES:
v “Decipher (CSNBDEC)” on page 213
v “Encipher (CSNBENC)” on page 217
v “SymmetricAlgorithm Decipher (CSNBSAD)” on page 221
v “SymmetricAlgorithm Encipher (CSNBSAE)” on page 226
Modes of operation
|
| To encipher or decipher DES data or keys, CCAuses the U.S. National Institute of Standards and
| Technology (NIST) Data Encryption Standard (DES) algorithm, with single-length, double-length, or
| triple-length keys.
| To encipher or decipherAES data or keys, CCAuses the U.S. National Institute of Standards and
| Technology (NIST)Advanced Encryption Standard (AES) algorithm, with 16-byte, 24-byte or 32-byte keys.
| The Encipher and Decipher verbs operate in DES CBC (Cipher Block Chaining) mode.
Cipher Block Chaining (CBC) mode
|
| The CBC mode uses an initial chaining vector (ICV) in its processing. The CBC mode processes blocks of
| data only in exact multiples of the blocksize. The ICV is exclusive ORed with the first block of plaintext
| prior to the encryption step. The block of ciphertext just produced is exclusive-ORed with the next block of
| plaintext, and so on. You must use the same ICV to decipher the data. This disguises any pattern that may
| exist in the plaintext. CBC mode is the default for encrypting and decrypting data using the Encipher and
| Decipher verbs. “Ciphering methods” on page 494 describes the cipher processing rules in detail.
Electronic Code Book (ECB) mode
|
| In ECB mode, each block of plaintext is separately enciphered and each block of the ciphertext is
| separately deciphered. In other words, the encipherment or decipherment of a block is totally independent
| of other blocks.
Processing rules
|
| “Ciphering methods” on page 494 describes the cipher processing rules in detail.
| CCAhandles chaining for each block of data, from the first block until the last complete block of data in
| each Encipher or SymmetricAlgorithm Encipher call. There are different types of processing rules you can
| choose for block chaining:
| ANSI X9.23
| Data is not necessarily in exact multiples of the block size. This processing rule pads the plaintext so
| the ciphertext produced is in exact multiples of the block size.
©CopyrightIBMCorp.2007,2011 211

| Cipher block chaining (CBC)
| Data must be an exact multiple of the block size, and output will have the same length.
| Cryptographic Unit Support Program (CUSP)
| CBC mode (cipher block chaining) that is compatible with IBM’s CUSP and PCF products. The data
| need not be in exact multiples of the block size. The ciphertext is the same length as the plaintext.
| Electronic Code Book (ECB)
| The data length must be a multiple of the block size. See “Electronic Code Book (ECB) mode” on page
| 211.
| Information Protection System (IPS)
| CBC mode that is compatible with IBM’s IPS product. The data need not be in exact multiples of the
| block size. The ciphertext is the same length as the plaintext.
| PKCS-PAD
| The data is padded on the right with between one and 16 bytes of pad characters, making ciphertext a
| multiple of the block size.
| The resulting chaining value (except for ECB mode), after an Encipher or SymmetricAlgorithm Encipher
| call, is known as an output chaining vector (OCV). When there are multiple cipher requests, the application
| can pass the OCV from the previous Encipher or SymmetricAlgorithm Encipher call, as the input chaining
| vector (ICV) in the next Encipher or SymmetricAlgorithm Encipher call. This produces chaining between
| successive calls, which is known as record chaining. CCAprovides the ICV selection keyword CONTINUE
| in the rule_array parameter used to select record chaining with the CBC processing rule.
Triple-DES encryption
|
| Triple-DES encryption uses a triple-length DATAkey comprised of three 8-byte DES keys to encipher eight
| bytes of data using the following method:
| v Encipher the data using the first key
| v Decipher the result using the second key
| v Encipher the second result using the third key
| The procedure is reversed to decipher data that has been triple-DES enciphered:
| v Decipher the data using the third key
| v Encipher the result using the second key
| v Decipher the second result using the first key
| Avariation of the triple-DES algorithm supports the use of a double-length DATAkey comprised of two
| 8-byte DATAkeys. In this method, the first 8-byte key is reused in the last encipherment step.
| Due to export regulations, triple-DES encryption might not be available on your processor.
212 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Decipher (CSNBDEC)
Decipher (CSNBDEC)
Use the Decipher verb to decipher data using the DES cipher block chaining mode. CCAsupports the
following processing rules to decipher data. You choose the type of processing rule that the Decipher verb
should use for block chaining.
Processing Rule Purpose
ANSI X9.23 For cipher block chaining. The ciphertext must be an exact multiple of
eight bytes, but the plaintext will be between 1 and 8 bytes shorter than
the ciphertext. The text_length will also be reduced to show the original
length of the plaintext.
Cipher Block Chaining (CBC)
The ciphertext must be an exact multiple of eight bytes and the plaintext
will have the same length.
Cryptographic Unit Support Program (CUSP)
CBC mode (cipher block chaining) that is compatible with IBM’s CUSP
and PCF products. The data need not be in exact multiples of eight bytes.
The ciphertext is the same length as the plaintext.
Information Protection System (IPS)
CBC mode (cipher block chaining) that is compatible with IBM’s IPS
product. The data need not be in exact multiples of eight bytes. The
ciphertext is the same length as the plaintext.
The cipher block chaining (CBC) mode uses an initial chaining value (ICV) in its processing. The first eight
bytes of ciphertext is deciphered and then the ICV is XORed with the resulting eight bytes of data to form
the first 8-byte block of plaintext. Thereafter, the 8-byte block of ciphertext is deciphered and XORed with
the previous 8-byte block of ciphertext until all the ciphertext is deciphered.
The selection between single-DES decryption mode and triple-DES decryption mode is controlled by the
length of the key supplied in the key_identifier parameter. If a single-length key is supplied, single-DES
decryption is performed. If a double-length or triple-length key is supplied, triple-DES decryption is
performed.
Adifferent ICV could be passed on each call to the Decipher verb. However, the same ICV that was used
in the corresponding Encipher verb must be passed.
Short blocks are text lengths of between one and seven bytes.Ashort block can be the only block. Trailing
short blocks are blocks of between one and seven bytes that follow an exact multiple of eight bytes. For
example, if the text length is 21, there are two 8-byte blocks and a trailing short block of five bytes.
Because the DES processes text only in exact multiples of eight bytes, some special processing is
required to decipher such short blocks.
These methods of treating short blocks and trailing short blocks do not increase the length of the
ciphertext compared to the length of the plaintext. If the plaintext was padded during encipherment, the
length of the ciphertext will always be an exact multiple of eight bytes.
CCAsupports theANSI X9.23 padding method.
Host CPU acceleration: CPACF
Only keys with a key type of DATAcan be used successfully with the CPACF exploitation layer through
this verb. Specifically, a DATAkey has a CV (Control Vector) of all X'00' bytes for all active bytes of the CV
(eight bytes for 8-byte DES keys, 16 bytes for 16-byte DES keys, and 16 bytes for 24-byte DES keys).
For details about CPACF, see “CPACF support” on page 8.
Chapter6.Protectingdata 213

Decipher (CSNBDEC)
Format
CSNBDEC(
return_code,
reason_code,
exit_data_length,
exit_data,
key_identifier,
text_length,
cipher_text,
initialization_vector,
rule_array_count,
rule_array,
chaining_vector,
clear_text )
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 14.
key_identifier
Direction: Input/Output Type: String
A64-byte string that is the internal key token containing the data-encrypting key or the label of a DES
key storage record containing a data-encrypting key to be used for deciphering the data. If the key
token or key label contains a single-length key, single-DES decryption is performed. If the key token or
key label contains a double-length or triple-length key, triple-DES decryption is performed.
Double length CIPHER and DECIPHER keys are also supported.
text_length
Direction: Input/Output Type: Integer
On entry, you supply the length of the ciphertext. The maximum length of text is 214,783,647 bytes.A
zero value for the text_length parameter is not valid. If the returned deciphered text (clear_text
parameter) is a different length because of the removal of padding bytes, the value is updated to the
length of the plaintext.
The application program passes the length of the ciphertext to the verb. The verb returns the length of
the plaintext to your application program.
cipher_text
Direction: Input Type: String
The text to be deciphered.
initialization_vector
Direction: Input Type: String
The 8-byte supplied string for the cipher block chaining. The first block of the ciphertext is deciphered
and XORed with the initial chaining vector (ICV) to get the first block of cleartext. The input block is
the next ICV. To decipher the data, you must use the same ICV used when you enciphered the data.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, or 3.
rule_array
214 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Decipher (CSNBDEC)
Direction: Input Type: String
An array of 8-byte keywords providing the processing control information. The array is positional. The
first keyword in the array is the processing rule. You choose the processing rule you want the verb to
use for deciphering the data. The second keyword is the ICV selection keyword. The third keyword (or
the second if the ICV selection keyword is allowed to default) is the encryption algorithm to use. The
rule_array keywords are described in Table54.
Table54.KeywordsforDeciphercontrolinformation
Keyword Description
ProcessingRule(One,required)
CBC PerformsANSIX3.102cipherblockchaining.Thedatamustbeamultipleofeightbytes.AnOCVis
producedandplacedinthechaining_vectorparameter.IftheICVselectionkeywordCONTINUEis
specified,theCBCOCVfromthepreviouscallisusedastheICVforthiscall.
CUSP PerformsCryptographicUnitSupportProgram(CUSP)cipherblockchaining.
IPS PerformsInformationProtectionSystem(IPS)cipherblockchaining.
X9.23 Decipherswithcipherblockchainingandtextlengthreducedtotheoriginalvalue.Thisiscompatible
withtherequirementsinANSIstandardX9.23.Theciphertextlengthmustbeanexactmultipleofeight
bytes.Paddingisremovedfromtheplaintext.
ICVSelection(One,optional)
CONTINUE Thisspecifiestakingtheinitializationvectorfromtheoutputchainingvector(OCV)containedinthe
workareatowhichthechaining_vectorparameterpoints.CONTINUEisvalidonlyfortheCBC
processingrule.
INITIAL Thisspecifiestakingtheinitializationvectorfromtheinitialization_vectorparameter.INITIAListhe
defaultvalue.
EncryptionAlgorithm(Optional)
DES Thisspecifiesusingthedataencryptionstandardandignoringthetokenmarking.
“Ciphering methods” on page 494 describes the cipher processing rules in detail.
chaining_vector
Direction: Input/Output Type: String
An 18-byte field CCAuses as a system work area. Your application program must not change the data
in this string. The chaining vector holds the output chaining vector (OCV) from the caller. The OCV is
the first eight bytes in the 18-byte string.
The direction is Output if the ICV selection keyword of the rule_array parameter is INITIAL. The
direction is Input/Output if the ICV selection keyword of the rule_array parameter is CONTINUE.
clear_text
Direction: Output Type: String
The field where the verb returns the deciphered text.
Restrictions
This verb will fail if the key token contains double or triple-length keys and triple-DES is not enabled.
Required commands
| This verb requires the Decipher - DES command (offset X'000F') to be enabled in the active role.
Usage notes
None
Chapter6.Protectingdata 215

Decipher (CSNBDEC)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBDECJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBDECJ are shown here.
Format
public native void CSNBDECJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_identifier,
hikmNativeInteger text_length,
byte[] ciphertext,
byte[] initialization_vector,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] chaining_vector,
byte[] plaintext
);
216 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encipher (CSNBENC)
Encipher (CSNBENC)
Use the Encipher verb to encipher data using the DES cipher block chaining mode. CCAsupports the
following processing rules to encipher data. You choose the type of processing rule that the Encipher verb
should use for the block chaining.
Processing Rule Purpose
Cipher block chaining (CBC) In exact multiples of eight bytes.
Cryptographic Unit Support Program (CUSP)
CBC mode (cipher block chaining) that is compatible with IBM’s CUSP
and PCF products. The data need not be in exact multiples of eight bytes.
The ciphertext is the same length as the plaintext.
Information Protection System (IPS)
CBC mode (cipher block chaining) that is compatible with IBM’s IPS
product. The data need not be in exact multiples of eight bytes. The
ciphertext is the same length as the plaintext.
ANSI X9.23 For block chaining not necessarily in exact multiples of eight bytes. This
process rule pads the plaintext so that ciphertext produced is an exact
multiple of eight bytes.
For more information about the processing rules, see Table55 on page 219 and Ciphering methods.
The cipher block chaining (CBC) mode of operation uses an initial chaining vector (ICV) in its processing.
The ICV is XORed with the first eight bytes of plaintext before the encryption step and thereafter, the
8-byte block of ciphertext just produced is XORed with the next 8-byte block of plaintext and so on. This
disguises any pattern that might exist in the plaintext.
The selection between single-DES encryption mode and triple-DES encryption mode is controlled by the
length of the key supplied in the key_identifier parameter. If a single-length key is supplied, single-DES
encryption is performed. If a double-length or triple-length key is supplied, triple-DES encryption is
performed.
To nullify the CBC effect on the first 8-byte block, supply eight bytes of zero. However, the ICV might
require zeros.
Cipher block chaining also produces a resulting chaining value called the output chaining vector (OCV).
The application can pass the OCV as the ICV in the next encipher call. This results in record chaining.
Note that the OCV that results is the same, whether an Encipher or a Decipher verb was invoked,
assuming the same text, ICV, and key were used.
Short blocks are text lengths of between one and seven bytes.Ashort block can be the only block. Trailing
short blocks are blocks of between one and seven bytes that follow an exact multiple of eight bytes. For
example, if the text length is 21, there are two 8-byte blocks, and a trailing short block of five bytes.
An alternative method is to pad the plaintext and produce a ciphertext that is longer than the plaintext. The
plaintext can be padded with up to eight bytes using one of several padding methods. This padding
produces a ciphertext that is an exact multiple of eight bytes in length.
If the cleartext is already a multiple of eight, the ciphertext can be created using any processing rule.
Because of padding, the returned ciphertext length is longer than the provided plaintext; the text_length
parameter will have been modified. The returned ciphertext field should be eight bytes longer than the
length of the plaintext to accommodate the maximum amount of padding.
Chapter6.Protectingdata 217

Encipher (CSNBENC)
Attention: If you lose the data-encrypting key under which the data (plaintext) is enciphered, the data
enciphered under that key (ciphertext) cannot be recovered.
Host CPU acceleration: CPACF
Only keys with a key type of DATAcan be used successfully with the CPACF exploitation layer through
this verb. Specifically, a DATAkey has a CV (Control Vector) of all X'00' bytes for all active bytes of the CV
(eight bytes for 8-byte DES keys, 16 bytes for 16-byte DES keys, and 16 bytes for 24-byte DES keys).
For details about CPACF, see “CPACF support” on page 8.
Format
CSNBENC(
return_code,
reason_code,
exit_data_length,
exit_data,
key_identifier,
text_length,
clear_text,
initialization_vector,
rule_array_count,
rule_array,
pad_character,
chaining_vector,
cipher_text )
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 14.
key_identifier
Direction: Input/Output Type: String
A64-byte string that is the internal key token containing the data-encrypting key or the label of a DES
key storage record containing the data-encrypting key, to be used for encrypting the data. If the key
token or key label contains a single-length key, single-DES encryption is performed. If the key token or
key label contains a double-length or triple-length key, triple-DES encryption is performed.
Single and double-length CIPHER and ENCIPHER keys are also supported.
text_length
Direction: Input/Output Type: Integer
On entry, the length of the plaintext (clear_text parameter) you supply. The maximum length of text is
214,783,647 bytes.Azero value for the text_length parameter is not valid. If the returned enciphered
text (cipher_text parameter) is a different length because of the addition of padding bytes, the value is
updated to the length of the ciphertext.
The application program passes the length of the plaintext to the verb. This verb returns the length of
the ciphertext to the application program.
clear_text
Direction: Input Type: String
The text that is to be enciphered.
initialization_vector
Direction: Input Type: String
218 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encipher (CSNBENC)
The 8-byte supplied string for the cipher block chaining. The first eight bytes (or less) block of the data
is XORed with the ICV and then enciphered. The input block is enciphered and the next ICV is
created. You must use the same ICV to decipher the data.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, or 3.
rule_array
Direction: Input Type: String
An array of 8-byte keywords providing the processing control information. The array is positional. The
first keyword in the array is the processing rule. You choose the processing rule you want the verb to
use for enciphering the data. The second keyword is the ICV selection keyword. The third keyword (or
the second if the ICV selection keyword is allowed to default to INITIAL) is the encryption algorithm to
use. The rule_array keywords are described in Table55.
Table55.KeywordsforEnciphercontrolinformation
Keyword Description
ProcessingRule(One,required)
CBC PerformsANSIX3.102cipherblockchaining.Thedatamustbeamultipleofeightbytes.AnOCVis
producedandplacedinthechaining_vectorparameter.IftheICVselectionkeywordCONTINUEis
specified,theCBCOCVfromthepreviouscallisusedastheICVforthiscall.
CUSP PerformsCryptographicUnitSupportProgram(CUSP)cipherblockchaining.
IPS PerformsInformationProtectionSystem(IPS)cipherblockchaining.
X9.23 Performscipherblockchainingwith1-8bytesofpadding.Thisiscompatiblewiththerequirementsin
ANSIstandardX9.23.Ifthedataisnotinexactmultiplesofeightbytes,X9.23padstheplaintextsothe
ciphertextproducedisanexactmultipleofeightbytes.Theplaintextispaddedtothenextmultiple
eightbytes,evenifthisaddseightbytes.AnOCVisproduced.
ICVSelection(One,optional)
CONTINUE Thisspecifiestakingtheinitializationvectorfromtheoutputchainingvector(OCV)containedinthe
workareatowhichthechaining_vectorparameterpoints.CONTINUEisvalidonlyfortheCBC
processingrule.
INITIAL Thisspecifiestakingtheinitializationvectorfromtheinitialization_vectorparameter.INITIAListhe
defaultvalue.
EncryptionAlgorithm(Optional)
DES Thisspecifiesusingthedataencryptionstandardandignoringthetokenmarking.
“Ciphering methods” on page 494describes the cipher processing rules in detail.
pad_character
Direction: Input Type: Integer
An integer, 0 - 255, that is used as a padding character for the X9.23 process rule (rule_array
parameter).
chaining_vector
Direction: Input/Output Type: String
An 18-byte field CCAuses as a system work area. Your application program must not change the data
in this string. The chaining vector holds the output chaining vector (OCV) from the caller. The OCV is
the first eight bytes in the 18-byte string.
Chapter6.Protectingdata 219

Encipher (CSNBENC)
The direction is Output if the ICV selection keyword of the rule_array parameter is INITIAL.
The direction is Input/Output if the ICV selection keyword of the rule_array parameter is CONTINUE.
cipher_text
Direction: Output Type: String
The enciphered text the verb returns. The length of the ciphertext is returned in the text_length
parameter. The cipher_text could be eight bytes longer than the length of the clear_text field because
of the padding that is required for some processing rules.
Restrictions
This verb will fail if the key token contains double-length or triple-length keys and triple-DES is not
enabled.
Required commands
| This verb requires the Encipher - DES command (offset X'000E') to be enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBENCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBENCJ are shown here.
Format
public native void CSNBENCJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
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
);
220 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Algorithm Decipher (CSNBSAD)
Symmetric Algorithm Decipher (CSNBSAD)
Use the SymmetricAlgorithm Decipher verb to decipher data using theAES cipher block chaining mode.
CCAsupports the following processing rules to decipher data. You choose the type of processing rule that
the verb should use for block chaining.
Cipher Block Chaining (CBC)
The plaintext must be an exact multiple of eight bytes, and the ciphertext will have the same length.
Electronic Code Book (ECB)
The plaintext length must be a multiple of the block size.
PKCS-PAD
The plaintext was padded on the right with 1 - 16 bytes of pad characters, making the padded text a
multiple of the block size.
TheAES 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. Acleartext key consisting of only the key bytes, not contained in a key token.
2. Acleartext key contained in an internalAES key-token.
3. An encrypted key contained in an internalAES key-token, where the key is wrapped (encrypted) with
theAES master key.
To use this verb, specify:
v The rule_array:
1. The algorithm identifier keywordAES, 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 64-byteAES key-token, either in application storage or in key storage.
4. An optional initial chaining value (ICV) 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 64-byte internalAES key-token or the key label of an internalAES key-token.
v Ablock 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 Acleartext buffer large enough to receive the deciphered output.
This verb does the following when it deciphers the data:
1. Verifies theAES key-token for keyword KEYIDENT.
2. Verifies that the ciphertext length is a multiple of the block size.
3. Deciphers the inputAES key if the key is encrypted (MKVP was present in token).
4. Deciphers the ciphertext with theAES clear key according to the encryption mode specified.
5. Removes from 1 - 16 pad characters from the right of the clear data for keyword PKCS-PAD.
Chapter6.Protectingdata 221

Symmetric Algorithm Decipher (CSNBSAD)
6. Returns the cleartext data and its length.
7. Returns the chain data and its length if keyword ECB is not specified.
| Only keys with a key type of DATAcan be used successfully with the CPACF exploitation layer through
| this verb. Specifically, a DATAkey has a Control Vector (CV) of all X'00' bytes for all active bytes of the CV
| (eight bytes for allAES keys). Note that as of CCARelease 3.30 (the first release ofAES function on the
| CEX2C 4764 adapter) to Release 4.1.0 (the most recent release of CCAon the CEX3C feature),AES
| keys were only available as DATAkeys. For details about CPACF, see “CPACF support” on page 8.
Format
CSNBSAD(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_identifier_length,
key_identifier,
key_parms_length,
key_parms,
block_size,
initialization_vector_length,
initialization_vector,
chain_data_length,
chain_data,
ciphertext_length,
cipher_text,
cleartext_length,
cleartext,
optional_data_length,
optional_data )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, 3, or 4.
rule_array
Direction: Input Type:Array
An array of 8-byte keywords providing the processing control information. The keywords must be
left-justified and padded on the right with space characters. The rule_array keywords are described in
Table56.
Table56.KeywordsforSymmetricAlgorithmDeciphercontrolinformation
Keyword Description
Decryptionalgorithm(Onerequired)
AES SpecifiesuseoftheAdvancedEncryptionStandard(AES)asthedecipheringalgorithm.Theblocksize
forAESis16bytes,andthekeylengthis16,24,or32bytes.AESistheonlyalgorithmcurrently
supportedbythisverb.
Processingrule(One,optional)
222 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Algorithm Decipher (CSNBSAD)
Table56.KeywordsforSymmetricAlgorithmDeciphercontrolinformation (continued)
Keyword Description
CBC PerformsANSIX3.102cipherblockchaining.Thedatamustbeamultipleofeightbytes.AnOCVis
producedandplacedinthechaining_vectorparameter.IftheICVselectionkeywordCONTINUEis
specified,theCBCOCVfromthepreviouscallisusedastheICVforthiscall.
ECB SpecifiesdecipheringinElectronicCodeBookmode.Theciphertextlengthmustbeamultipleofthe
blocksize.
PKCS-PAD Specifiesthatthecleartextwaspaddedontherightwith1-16bytesofpadcharacters,makingthe
paddedtextamultipleoftheblocksize,beforethedatawasenciphered.Eachpadcharacterisvalued
tothenumberofpadcharactersadded.
Theoutputcleartextisstrippedofanypadcharactersandthecleartextlengthis1-16byteslessthan
theciphertextlength.
Keyrule(One,optional)
KEY-CLR Specifiesthatthekey_identifierparameterpointstoacleartextAESkey.Onlythekeyvalueisallowed;
thekeyisnotcontainedinakeytoken.Thisisthedefaultvalue.
KEYIDENT Specifiesthatthekey_identifierparameterpointstoaninternalAESkey-tokenorthelabelofan
internalkey-tokeninAESkey-storage.
ICVselection(One,optional)
CONTINUE Thisspecifiestakingtheinitializationvectorfromtheoutputchainingvector(OCV)containedinthe
workareatowhichthechaining_vectorparameterpoints.CONTINUEisvalidonlyfortheCBC
processingrule.
INITIAL Thisspecifiestakingtheinitializationvectorfromtheinitialization_vectorparameter.INITIAListhe
defaultvalue.
“Ciphering methods” on page 494 describes the cipher processing rules in detail.
key_identifier_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_identifier variable.
This value must be 16, 24, 32, or 64.
key_identifier
Direction: Input Type: String
Apointer to a string variable containing either a cleartextAES key or the internal key-token or a label
for an internal key-token record inAES 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 clearAES key is required. For
rule_array keyword KEYIDENT, a 64-byte internal key-token or key label for an internal key-token
record inAES key-storage is required.
key_parms_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_parms parameter.
This value must be 0.
key_parms
Direction: Input Type: String
Apointer to a string variable for key-related parameters. It is currently unused.
block_size
Chapter6.Protectingdata 223

Symmetric Algorithm Decipher (CSNBSAD)
Direction: Input Type: Integer
Apointer to an integer variable containing the block size used by the cryptographic algorithm. This
value must be 16.
initialization_vector_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the initialization_vector
variable. For cipher block chaining with an INITIALICV selection, this value must be 16. For
processing rule ECB or ICV selection CONTINUE, this value should be 0.
initialization_vector
Direction: Input Type: String
Apointer to a string variable containing the initialization vector for the INITIALcall to CBC mode
encryption. It is not used if the process rule is ECB. The same initialization vector must have been
used to encipher the data.
chain_data_length
Direction: Input/Output Type: Integer
Apointer to an integer variable containing the number of bytes of data in the chain_data variable. On
input, this variable contains the length of the buffer provided and should have 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
Direction: Input/Output Type: String
Apointer 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
Direction: Input Type: Integer
Apointer 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. This value must not be 0. If PKCS-PAD is
specified, the output cleartext_length variable will be 1 - 16 bytes less than the ciphertext_length
value.
ciphertext
Direction: Input Type: String
Apointer to a string variable containing the data to be deciphered, including any pad bytes.
cleartext_length
Direction: Input/Output Type: Integer
On input, this parameter is a pointer to an integer variable containing the number of bytes of data in
the cleartext variable. On output, this 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.
224 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Algorithm Decipher (CSNBSAD)
cleartext
Direction: Input/Output Type: String
Apointer to a string variable used to contain the data to be deciphered, excluding any pad bytes.
optional_data_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the optional_data variable.
This value should be 0.
optional_data
Direction: Input Type: String
Apointer to a string variable containing optional data for the decryption. It is currently not used.
Restrictions
None.
Required commands
| This verb requires the SymmetricAlgorithm Decipher - secureAES keys command (offset X'012B') to be
| enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBSADJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBSADJ are shown here.
Format
public native void CSNBSADJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger key_length,
byte[] key_identifier,
hikmNativeInteger key_parms_length,
byte[] key_parms,
hikmNativeInteger block_size,
hikmNativeInteger iv_length,
byte[] iv,
hikmNativeInteger chain_data_length,
byte[] chain_data,
hikmNativeInteger cipher_text_length,
byte[] cipher_text,
hikmNativeInteger clear_text_length,
byte[] clear_text,
hikmNativeInteger optional_data_length,
byte[] optional_data);
Chapter6.Protectingdata 225

Symmetric Algorithm Encipher (CSNBSAE)
Symmetric Algorithm Encipher (CSNBSAE)
Use the SymmetricAlgorithm Encipher verb to encipher data using theAES cipher block chaining mode.
CCAsupports the following processing rules to encipher data. You choose the type of processing rule that
the verb should use for block chaining.
Cipher Block Chaining (CBC)
The plaintext must be an exact multiple of eight bytes, and the ciphertext will have the same length.
Electronic Code Book (ECB)
The plaintext length must be a multiple of the block size.
PKCS-PAD
The plaintext was padded on the right with 1 - 16 bytes of pad characters, making the padded text a
multiple of the block size.
TheAES 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. Acleartext key consisting of only the key bytes, not contained in a key token.
2. Acleartext key contained in an internalAES key-token.
3. An encrypted key contained in an internalAES key-token, where the key is wrapped (encrypted) with
theAES master key.
To use this verb, specify:
v The rule_array:
1. The algorithm identifier keywordAES, 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
encryption 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 64-byteAES key-token, either in application storage or in 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 Akey identifier containing a 16-byte, 24-byte, or 32-byte clear key for a key rule of KEY-CLR, or a
64-byte internalAES key-token or the key label of an internalAES key-token for a key rule of
KEYIDENT.
v Ablock 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 Aciphertext buffer large enough to receive the enciphered output.
This verb does the following when it enciphers the data:
1. Verifies theAES key-token for keyword KEYIDENT.
2. Deciphers the inputAES key if the key is encrypted (MKVP was present in token).
3. 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.
226 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Algorithm Encipher (CSNBSAE)
4. Enciphers the cleartext, including any pad characters, with theAES clear key according to the
encryption mode specified.
5. Returns the ciphertext data and its length.
6. Returns the chain data and its length if keyword ECB is not specified.
| Only keys with a key type of DATAcan be used successfully with the CPACF exploitation layer through
| this verb. Specifically, a DATAkey has a Control Vector (CV) of all X'00' bytes for all active bytes of the CV
| (eight bytes for allAES keys). Note that as of CCARelease 3.30 (the first release ofAES function on the
| CEX2C 4764 adapter) to Release 4.1.0 (the most recent release of CCAon the CEX3C adapter),AES
| keys were only available as DATAkeys. For details about CPACF, see “CPACF support” on page 8.
Format
CSNBSAE(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_identifier_length,
key_identifier,
key_parms_length,
key_parms,
block_size,
initialization_vector_length,
initialization_vector,
chain_data_length,
chain_data,
cleartext_length,
cleartext,
ciphertext_length,
cipher_text,
optional_data_length,
optional_data )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, 3, or 4.
rule_array
Direction: Input Type:Array
Apointer to a string variable containing an array of keywords. The keywords are eight bytes in length,
and must be left-justified and padded on the right with space characters. The rule_array keywords are
described in Table57.
Table57.KeywordsforSymmetricAlgorithmEnciphercontrolinformation
Keyword Description
Encryptionalgorithm(Required)
Chapter6.Protectingdata 227

Symmetric Algorithm Encipher (CSNBSAE)
Table57.KeywordsforSymmetricAlgorithmEnciphercontrolinformation (continued)
Keyword Description
AES SpecifiesuseoftheAdvancedEncryptionStandard(AES)astheencryptionalgorithm.Theblocksize
forAESis16bytes,andthekeylengthis16,24,or32bytes.AESistheonlyalgorithmcurrently
supportedbythisverb.
Processingrule(One,optional)
CBC PerformsANSIX3.102cipherblockchaining.Thedatamustbeamultipleofeightbytes.AnOCVis
producedandplacedinthechaining_vectorparameter.IftheICVselectionkeywordCONTINUEis
specified,theCBCOCVfromthepreviouscallisusedastheICVforthiscall.
ECB SpecifiesencipheringinElectronicCodeBookmode.Thecleartextlengthmustbeamultipleofthe
blocksize.
PKCS-PAD Specifiespaddingofthecleartextontherightwith1-16bytesofpadcharacters,makingthepadded
textamultipleoftheblocksize.Eachpadcharacterisvaluedtothenumberofpadcharactersadded.
Theciphertextlengthmustbelargeenoughtoincludetheaddedpadcharacters.
Keyrule(One,optional)
KEY-CLR Specifiesthatthekey_identifierparameterpointstoacleartextAESkey.Onlythekeyvalueisallowed;
thekeyisnotcontainedinakeytoken.Thisisthedefaultvalue.
KEYIDENT Specifiesthatthekey_identifierparameterpointstoaninternalAESkey-tokenorthelabelofan
internalkey-tokeninAESkey-storage.
ICVselection(One,optional)
CONTINUE Specifiestakingtheinitializationvectorfromtheoutputchainingvector(OCV)containedinthework
areatowhichthechaining_vectorparameterpoints.CONTINUEisvalidonlyfortheCBCprocessing
rule.
INITIAL Specifiestakingtheinitializationvectorfromtheinitialization_vectorparameter.INITIAListhedefault
value.
“Ciphering methods” on page 494 describes the cipher processing rules in detail.
key_identifier_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_identifier variable.
This value must be 16, 24, 32, or 64.
key_identifier
Direction: Input Type: String
Apointer to a string variable containing either a cleartextAES key or the internal key-token or a label
for an internal key-token record inAES 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 64-byte internal key-token or key label for
an internal key-token record inAES key-storage is required.
key_parms_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_parms parameter.
This value must be 0.
key_parms
Direction: Input Type: String
Apointer to a string variable for key-related parameters. It is currently unused.
228 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Algorithm Encipher (CSNBSAE)
block_size
Direction: Input Type: Integer
Apointer to an integer variable containing the block size used by the cryptographic algorithm. This
value must be 16.
initialization_vector_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the initialization_vector
variable. For cipher block chaining with an INITIALICV selection, this value must be 16. For
processing rule ECB or ICV selection CONTINUE, this value should be 0.
initialization_vector
Direction: Input Type: String
Apointer to a string variable containing the initialization vector for the INITIALcall to CBC mode
encryption. It is not used if the process rule is ECB. The same initialization vector must be used when
deciphering the data.
chain_data_length
Direction: Input/Output Type: Integer
Apointer to an integer variable containing the number of bytes of data in the chain_data variable. On
input, this variable contains the length of the buffer provided and should have 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
Direction: Input/Output Type: String
Apointer 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
Direction: Input Type: Integer
Apointer 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
Direction: Input Type: String
Apointer to a string variable used to contain the data to be enciphered, excluding any pad bytes.
ciphertext_length
Direction: Input/Output Type: Integer
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
Chapter6.Protectingdata 229

Symmetric Algorithm Encipher (CSNBSAE)
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
Direction: Input/Output Type: String
Apointer 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
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the optional_data variable.
This value should be 0.
optional_data
Direction: Input Type: String
Apointer to a string variable containing optional data for the encryption. It is currently not used.
Restrictions
None.
Required commands
This verb requires the SymmetricAlgorithm Encipher - secureAES keys command (offset X'012A') to be
enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBSAEJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBSAEJ are shown here.
230 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Symmetric Algorithm Encipher (CSNBSAE)
Format
public native void CSNBSAEJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger key_length,
byte[] key_identifier,
hikmNativeInteger key_parms_length,
byte[] key_parms,
hikmNativeInteger block_size,
hikmNativeInteger iv_length,
byte[] iv,
hikmNativeInteger chain_data_length,
byte[] chain_data,
hikmNativeInteger clear_text_length,
byte[] clear_text,
hikmNativeInteger cipher_text_length,
byte[] cipher_text,
hikmNativeInteger optional_data_length,
byte[] optional_data);
Chapter6.Protectingdata 231

Symmetric Algorithm Encipher (CSNBSAE)
232 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 7. Verifying data integrity and authenticating
messages
CCAprovides the following methods to verify the integrity of transmitted messages and stored data:
v Message authentication code (MAC)
v Hash functions, including Modification Detection Code (MDC) processing and one-way hash generation
Note: You can also use digital signatures (see Chapter10, “Using digital signatures,” on page 359) to
authenticate messages.
The choice of verb depends on the security requirements of the environment in which you are operating. If
you need to ensure the authenticity of the sender as well as the integrity of the data and both the sender
and receiver can share a secret key, consider MessageAuthentication Code processing. If you need to
ensure the integrity of transmitted data in an environment where it is not possible for the sender and the
receiver to share a secret cryptographic key, consider hashing functions.
The verbs described in this chapter include:
| v “HMAC Generate (CSNBHMG)” on page 235
| v “HMAC Verify (CSNBHMV)” on page 238
v “MAC Generate (CSNBMGN)” on page 241
v “MAC Verify (CSNBMVR)” on page 245
v “MDC Generate (CSNBMDG)” on page 249
v “One-Way Hash (CSNBOWH)” on page 258
How MACs are used
When a message is sent, an application program can generate an authentication code for it using the
MAC Generate verb. CCAsupports theANSI X9.9-1 basic procedure and both theANSI X9.19 basic
procedure and optional double key MAC procedure. The MAC Generate verb computes the text of the
MessageAuthentication Code using the algorithm and a key. TheANSI X9.9-1 orANSI X9.19 basic
procedures accept either a single-length MAC generation (MAC) key or a data-encrypting (DATA) key, and
the message text. TheANSI X9.19 optional double key MAC procedure accepts a double-length MAC key
and the message text. The originator of the message sends the MAC with the message text.
When the receiver gets the message, an application program calls the MAC Verify verb. The MAC
Generate verb generates a MAC using the same algorithm as the sender and either the single-length or
double-length MAC verification key, the single-length or double-length MAC generation key, or DATAkey,
and the message text. The MAC Verify verb compares the MAC it generates with the one sent with the
message and issues a return code that indicates whether the MACs match. If the return code indicates
that the MACs match, the receiver can accept the message as genuine and unaltered. If the return code
indicates that the MACs do not match, the receiver can assume the message is either fraudulent or has
been altered. The newly computed MAC is not revealed outside the cryptographic coprocessor.
In a similar manner, MACs can be used to ensure the integrity of data stored on the system or on
removable media, such as tape.
Secure use of the MAC Generate and MAC Verify verbs requires the use of MAC and MACVER keys in
these verbs, respectively. To accomplish this, the originator of the message generates a MAC/MACVER
key pair, uses the MAC key in the MAC Generate verb, and exports the MACVER key to the receiver. The
originator of the message enforces key separation on the link by encrypting the MACVER key under a
transport key that is not an NOCV key before exporting the key to the receiver. With this type of key
separation enforced, the receiver can receive only a MACVER key and can use only this key in the MAC
©CopyrightIBMCorp.2007,2011 233

Verify verb. This ensures that the receiver cannot alter the message and produce a valid MAC with the
altered message. These security features are not present if DATAkeys are used in the MAC Generate
verb or if DATAor MAC keys are used in the MAC Verify verb.
By using MACs you get the following benefits:
v For data transmitted over a network, you can validate the authenticity of the message as well as
ensure the data has not been altered during transmission. For example, an active eavesdropper can tap
into a transmission line and interject fraudulent messages or alter sensitive data being transmitted. If the
data is accompanied by a MAC, the recipient can use a verb to detect whether the data has been
altered. Because both the sender and receiver share a secret key, the receiver can use a verb that
calculates a MAC on the received message and compares it to the MAC transmitted with the message.
If the comparison is equal, the message could be accepted as unaltered. Furthermore, because the
shared key is secret, when a MAC is verified it can be assumed that the sender was, in fact, the other
person who knew the secret key.
v For data stored on tape or DASD, you can ensure that the data read back onto the system was the
same as the data written onto the tape or DASD. For example, someone might be able to bypass
access controls. Such an access might escape the notice of auditors. However, if a MAC is stored with
the data, and verified when the data is read, you can detect alterations to the data.
How hashing functions and MDCs are used
Hashing functions include the MDC and one-way hash. You need to hash text before submitting it to the
Digital Signature Generate and Digital Signature Verify verbs (see Chapter10, “Using digital signatures,”
on page 359). CCAsupports the SHA-1, MD5, and RIPEMD-160 hashing functions.
When a message is sent, an application program can generate a hash or a Modification Detection Code
(MDC) for it using the One-Way Hash verb. This verb computes the hash or MDC, a short, fixed-length
value, using a one-way cryptographic function and the message text. The originator of the message
ensures the hash or MDC is transmitted with integrity to the intended receiver of the message. For
example, the value could be published in a reliable source of public information.
When the receiver gets the message, an application program calls the One-Way Hash verb to generate a
new hash or MDC using the same function and message text that were used by the sender. The
application program can compare the new value with the one generated by the originator of the message.
If the two values match, the receiver knows the message was not altered.
In a similar manner, hashes and MDCs can be used to ensure the integrity of data stored on the system or
on removable media, such as tape.
By using hashes and MDCs, you get the following benefits:
v For data transmitted over a network between locations that do not share a secret key, you can
ensure the data has not been altered during transmission. It is easy to compute a hash or MDC for
specific data, yet hard to find data that will result in a given hash or MDC. In effect, the problem of
ensuring the integrity of a large file is reduced to ensuring the integrity of a short, fixed-length value.
v For data stored on tape or DASD, you can ensure that the data read back onto the system was the
same as the data written onto the tape or DASD.After a hash has been established for a file, the
One-Way Hash verb can be run at any later time on the file. The resulting value can be compared with
the stored value to detect deliberate or inadvertent modification.
For more information, see “Modification Detection Code calculation” on page 493.
234 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

HMAC Generate (CSNBHMG)
HMAC Generate (CSNBHMG)
|
| Use the HMAC Generate verb to generate a keyed hash MessageAuthentication Code (HMAC) for the
| message string provided as input.An HMAC key that can be used for generate is required to calculate the
| HMAC.
Format
|
||
CSNBHMG(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| key_identifier_length,
| key_identifier,
| text_length,
| text,
| chaining_vector_length,
| chaining_vector,
| mac_length,
| mac )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 2 or 3.
| rule_array
|| Direction: Input Type: String
| Keywords that provide control information to the verb. The following table lists the keywords. Each
| keyword is left-justified in 8-byte fields and padded on the right with blanks.All keywords must be in
| contiguous storage. The rule_array keywords are described in Table58.
|| Table58.KeywordsforHMACGeneratecontrolinformation
|| Keyword Description
| Tokenalgorithm(Onerequired)
|| HMAC SpecifiestheHMACalgorithmtobeusedtogeneratetheMAC.
| Hashmethod(Onerequired)
|| SHA-1 SpecifiestheFIPS-198HMACprocedureusingtheSHA-1hashmethod,asymmetrickeyandtextto
| producea20-byte(160-bit)MAC.
|| SHA-224 SpecifiestheFIPS-198HMACprocedureusingtheSHA-224hashmethod,asymmetrickeyandtextto
| producea28-byte(224-bit)MAC.
|| SHA-256 SpecifiestheFIPS-198HMACprocedureusingtheSHA-256hashmethod,asymmetrickeyandtextto
| producea32-byte(256-bit)MAC.
|| SHA-384 SpecifiestheFIPS-198HMACprocedureusingtheSHA-384hashmethod,asymmetrickeyandtextto
| producea48-byte(384-bit)MAC.
|| SHA-512 SpecifiestheFIPS-198HMACprocedureusingtheSHA-512hashmethod,asymmetrickeyandtextto
| producea64-byte(512-bit)MAC.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 235

HMAC Generate (CSNBHMG)
| Table58.KeywordsforHMACGeneratecontrolinformation (continued)
|| Keyword Description
| Segmentingcontrol(Oneoptional)
|| FIRST Firstcall,thisisthefirstsegmentofdatafromtheapplicationprogram.
|| LAST Lastcall;thisisthelastdatasegment.
|| MIDDLE Middlecall;thisisanintermediatedatasegment.
|| ONLY Onlycall;segmentingisnotemployedbytheapplicationprogram.Thisisthedefaultvalue.
|
| key_identifier_length
|| Direction: Input Type: Integer
| The length of the key_identifier parameter. The maximum value is 725.
| key_identifier
|| Direction: Input Type: String
| The 64-byte label or internal token of an encrypted HMAC key.
| text_length
|| Direction: Input Type: Integer
| The length of the text you supply in the text parameter. The maximum length of text is 214783647
| bytes. For FIRST and MIDDLE calls, the text_length must be a multiple of 64 for SHA-1, SHA-224 and
| SHA-256 and a multiple of 128 for SHA-384 and SHA-512 hash methods.
| text
|| Direction: Input Type: String
| The application-supplied text for which the MAC is generated.
| chaining_vector_length
|| Direction: Input/Output Type: Integer
| The length of the chaining_vector in bytes. This value must be 128.
| chaining_vector
|| Direction: Input/Output Type: String
| An 128-byte string used as a system work area. Your application program must not change the data in
| this string. The chaining vector permits data to be chained from one invocation call to another.
| On the first call, initialize this parameter as binary zeros.
| mac_length
|| Direction: Input/Output Type: Integer
| The length of the mac parameter in bytes. This parameter is updated to the actual length of the mac
| parameter on output. The minimum value is 4, and the maximum value is 64.
| mac
|| Direction: Output Type: String
| The field in which the verb returns the MAC value if the segmenting rule is ONLY or LAST.
Restrictions
|
| This verb was introduced with CCA4.1.0.
236 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

HMAC Generate (CSNBHMG)
Required commands
|
| This verb requires the commands shown in the following table to be enabled in the active role:
||||
Rule-arraykeyword Offset Command
||| SHA-1 X'00E4' HMACGenerate-SHA-1
||| SHA-224 X'00E5' HMACGenerate-SHA-224
||| SHA-256 X'00E6' HMACGenerate-SHA-256
||| SHA-384 X'00E7' HMACGenerate-SHA-384
||| SHA-512 X'00E8' HMACGenerate-SHA-512
|
Usage notes
|
| None
Related information
|
| The HMAC Verify verb is described in “HMAC Verify (CSNBHMV)” on page 238.
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBHMGJ. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBHMGJ are shown here.
|
| Format
| public native void CSNBHMGJ(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger key_identifier_length
| byte[] key_identifier,
| hikmNativeInteger text_length,
| byte[] text,
| hikmNativeInteger chaining_vector_length,
| byte[] chaining_vector,
| hikmNativeInteger mac_length,
|| byte[] MAC);
|
|
|
Chapter7.Verifyingdataintegrityandauthenticatingmessages 237

HMAC Verify (CSNBHMV)
HMAC Verify (CSNBHMV)
|
| Use the HMAC Verify verb to verify a keyed hash MessageAuthentication Code (HMAC) for the message
| string provided as input.AMAC key contained in an internal variable-length symmetric key-token is
| required to verify the HMAC. The key must have the same value as the key used to generate the HMAC.
Format
|
||
CSNBHMV(
| return_code,
| reason_code,
| exit_data_length,
| exit_data,
| rule_array_count,
| rule_array,
| key_identifier_length,
| key_identifier,
| text_length,
| text,
| chaining_vector_length,
| chaining_vector,
| mac_length,
| mac )
|
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 14.
| rule_array_count
|| Direction: Input Type: Integer
| The number of keywords you supplied in the rule_array parameter. This value must be 2 or 3.
| rule_array
|| Direction: Input Type: String
| Keywords that provide control information to the verb. The following table lists the keywords. Each
| keyword is left-justified in 8-byte fields and padded on the right with blanks.All keywords must be in
| contiguous storage. The rule_array keywords are described in Table59.
|| Table59.KeywordsforHMACVerifycontrolinformation
|| Keyword Description
| Tokenalgorithm(Onerequired)
|| HMAC SpecifiestheHMACalgorithmtobeusedtoverifytheMAC.
| Hashmethod(Onerequired)
|| SHA-1 SpecifiestheFIPS-198HMACprocedureusingtheSHA-1hashmethod,asymmetrickeyandtextto
| producea20-byte(160-bit)MAC.
|| SHA-224 SpecifiestheFIPS-198HMACprocedureusingtheSHA-224hashmethod,asymmetrickeyandtextto
| producea28-byte(224-bit)MAC.
|| SHA-256 SpecifiestheFIPS-198HMACprocedureusingtheSHA-256hashmethod,asymmetrickeyandtextto
| producea32-byte(256-bit)MAC.
|| SHA-384 SpecifiestheFIPS-198HMACprocedureusingtheSHA-384hashmethod,asymmetrickeyandtextto
| producea48-byte(384-bit)MAC.
|| SHA-512 SpecifiestheFIPS-198HMACprocedureusingtheSHA-512hashmethod,asymmetrickeyandtextto
| producea64-byte(512-bit)MAC.
238 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

HMAC Verify (CSNBHMV)
| Table59.KeywordsforHMACVerifycontrolinformation (continued)
|| Keyword Description
| Segmentingcontrol(Optional)
|| FIRST Firstcall,thisisthefirstsegmentofdatafromtheapplicationprogram.
|| LAST Lastcall;thisisthelastdatasegment.
|| MIDDLE Middlecall;thisisanintermediatedatasegment.
|| ONLY Onlycall;segmentingisnotemployedbytheapplicationprogram.Thisisthedefaultvalue.
|
| key_identifier_length
|| Direction: Input Type: Integer
| The length of the key_identifier parameter. The maximum value is 725.
| key_identifier
|| Direction: Input/Output Type: String
| The 64-byte label or internal token of an encrypted HMAC or HMACVER key.
| text_length
|| Direction: Input Type: Integer
| The length of the text you supply in the text parameter. The maximum length of text is 214783647
| bytes. For FIRST and MIDDLE calls, the text_length must be a multiple of 64 for SHA-1, SHA-224 and
| SHA-256 and a multiple of 128 for SHA-384 and SHA-512 hash methods.
| text
|| Direction: Input Type: String
| The application-supplied text for which the HMAC is to be verified.
| chaining_vector_length
|| Direction: Input/Output Type: Integer
| The length of the chaining_vector in bytes. This value must be 128.
| chaining_vector
|| Direction: Input/Output Type: String
| An 128-byte string used as a system work area. Your application program must not change the data in
| this string. The chaining vector permits data to be chained from one invocation call to another.
| On the first call, initialize this parameter as binary zeros.
| mac_length
|| Direction: Input Type: Integer
| The length of the mac parameter in bytes. The maximum value is 64.
| mac
|| Direction: Input Type: String
| The field that contains the MAC value you want to verify.
Restrictions
|
| This verb was introduced with CCA4.1.0.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 239

HMAC Verify (CSNBHMV)
Required commands
|
| This verb requires the commands shown in the following table to be enabled in the active role:
||||
Rule-arraykeyword Offset Command
||| SHA-1 X'00F7' HMACVerify-SHA-1
||| SHA-224 X'00F8' HMACVerify-SHA-224
||| SHA-256 X'00F9' HMACVerify-SHA-256
||| SHA-384 X'00FA' HMACVerify-SHA-384
||| SHA-512 X'00FB' HMACVerify-SHA-512
|
Usage notes
|
| None
Related information
|
| The HMAC Generate verb is described in “HMAC Generate (CSNBHMG)” on page 235.
JNI version
|
| This verb has a Java Native Interface (JNI) version, which is named CSNBHMVJ. See “Building Java
| applications to use with the CCAJNI” on page 16.
| The parameters for CSNBHMVJ are shown here.
|
| Format
| public native void CSNBHMVJ(
| hikmNativeInteger return_code,
| hikmNativeInteger reason_code,
| hikmNativeInteger exit_data_length,
| byte[] exit_data,
| hikmNativeInteger rule_array_count,
| byte[] rule_array,
| hikmNativeInteger key_identifier_length
| byte[] key_identifier,
| hikmNativeInteger text_length,
| byte[] text,
| hikmNativeInteger chaining_vector_length,
| byte[] chaining_vector,
| hikmNativeInteger mac_length,
|| byte[] MAC);
|
|
|
240 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MAC Generate (CSNBMGN)
MAC Generate (CSNBMGN)
When a message is sent, an application program can generate an authentication code for it using the
MAC Generate verb. This verb to generates a 4-byte, 6-byte, or 8-byte MessageAuthentication Code
(MAC) for an application-supplied text string.
This verb computes the MessageAuthentication Code using one of the following methods:
v Using theANSI X9.9-1 single key algorithm, a single-length MAC generation key or data-encrypting key,
and the message text.
v Using theANSI X9.19 optional double key algorithm, a double-length MAC generation key and the
message text.
v Using the Europay, MasterCard and Visa (EMV) padding rules.
The MAC can be the leftmost 32 or 48 bits of the last block of the ciphertext or the entire last block (64
bits) of the ciphertext. The originator of the message sends the MessageAuthentication Code with the
message text.
Host CPU acceleration: CPACF
Only keys with a key type of DATAcan be used successfully with the CPACF exploitation layer through
this verb. Specifically, a DATAkey has a CV (Control Vector) of all X'00' bytes for all active bytes of the CV
(eight bytes for 8-byte DES keys, 16 bytes for 16-byte DES keys, and 16 bytes for 24-byte DES keys).
For details about CPACF, see “CPACF support” on page 8.
Format
CSNBMGN(
return_code,
reason_code,
exit_data_length,
exit_data,
key_identifier,
text_length,
text,
rule_array_count,
rule_array,
chaining_vector,
mac )
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 14.
key_identifier
Direction: Input/Output Type: String
The 64-byte key label or internal key token that identifies a single-length or double-length MAC
generate key or a single-length DATAor DATAM key. The type of key depends on the MAC process
rule in the rule_array parameter.
text_length
Direction: Input Type: Integer
The length of the text you supply in the text parameter. If the text_length is not a multiple of eight
bytes and if the ONLY or LAST keyword of the rule_array parameter is called, the text is padded in
accordance with the processing rule specified.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 241

MAC Generate (CSNBMGN)
text
Direction: Input Type: String
The application-supplied text for which the MAC is generated.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0, 1, 2, or 3.
rule_array
Direction: Input Type: String
Zero to three keywords that provide control information to the verb. The keywords are described in
Table60. The keywords must be in 24 bytes of contiguous storage with each of the keywords
left-justified in its own 8-byte location and padded on the right with blanks. For example,
’X9.9-1 MIDDLE MACLEN4 ’
The order of the rule_array keywords is not fixed.
You can specify one of the MAC processing rules and then choose one of the segmenting control
keywords and one of the MAC length keywords. The rule_array keywords are described in Table60.
Table60.KeywordsforMACGeneratecontrolinformation
Keyword Description
| MACprocessrules(One,optional)
EMVMAC EMVpaddingrulewithasingle-lengthMACkey.Thekey_identifierparametermustidentifya
single-lengthMACorasingle-lengthDATAkey.Thetextisalwayspaddedwith1-8bytessothe
resultingtextlengthisamultipleofeightbytes.ThefirstpadcharacterisX'80'.Theremainingpad
charactersareX'00'.
EMVMACD EMVpaddingrulewithadouble-lengthMACkey.Thekey_identifierparametermustidentifya
double-lengthMACkey.ThepaddingrulesarethesameasforEMVMAC.
TDES- ANSIX9.9-1procedureusingISO16609CBCmodetriple-DES(TDES)encryptionofthedata.Usesa
MAC double-lengthkey.
X9.19OPT ANSIX9.19optionaldoublekeyMACprocedure.Thekey_identifierparametermustidentifya
double-lengthMACkey.ThepaddingrulesarethesameasforX9.9-1.
X9.9-1 ANSIX9.9-1andX9.19basicprocedure.Thekey_identifierparametermustidentifyasingle-length
MACorasingle-lengthDATAkey.X9.9-1causestheMACtobecomputedfromallofthedata.Thetext
ispaddedonlyifthetextlengthisnotamultipleofeightbytes.Ifpaddingisrequired,thepadcharacter
X'00'isused.Thisisthedefaultvalue.
| Segmentingcontrol(One,optional)
FIRST Firstcall;thisisthefirstsegmentofdatafromtheapplicationprogram.
LAST Lastcall;thisisthelastdatasegment.
MIDDLE Middlecall;thisisanintermediatedatasegment.
ONLY Onlycall;segmentingisnotemployedbytheapplicationprogram.Thisisthedefaultvalue.
| MAClengthandpresentation(One,optional)
HEX-8 Generatesa4-byteMACvalueandpresentsitas8hexadecimalcharacters.
HEX-9 Generatesa4-byteMACvalueandpresentsitastwogroupsof4hexadecimalcharacterswithaspace
betweenthegroups.
MACLEN4 Generatesa4-byteMACvalue.Thisisthedefaultvalue.
MACLEN6 Generatesa6-byteMACvalue.
242 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MAC Generate (CSNBMGN)
Table60.KeywordsforMACGeneratecontrolinformation (continued)
Keyword Description
MACLEN8 Generatesan8-byteMACvalue.
chaining_vector
Direction: Input/Output Type: String
An 18-byte string that CCAuses as a system work area. Your application program must not change
the data in this string. The chaining vector permits data to be chained from one invocation call to
another.
On the first call, initialize this parameter as binary zeros.
mac
Direction: Output Type: String
The 8-byte or 9-byte field in which the verb returns the MAC value if the segmenting rule is ONLY or
LAST.Allocate an 8-byte field for MAC values of four bytes, six bytes, eight bytes, or HEX-8.Allocate
a 9-byte MAC field if you specify HEX-9 in the rule_array parameter.
Restrictions
It might seem intuitive that a DATAM key should also be usable for the MAC Generate verb, and a
DATAMV key for the MAC Verify verb, with the CPACF exploitation layer. However, this would violate the
security restrictions imposed by the user when the user creates a key of type DATAM or DATAMV.ADES
key that has been translated for use with the CPACF (see “CPACF support” on page 8) can be used with
CPACF DES encrypt and decrypt operations, an operation that is by definition not allowed for a DATAM or
DATAMV key type.Also note that by definition both through z/OS CCA-ICSF and in this S390 Linux CCA
access layer, a DATAkey of 16 bytes or 24 bytes in length is restricted from use with the X9.19OPT and
EMVMACD rule_array keyword specified MAC algorithms. The only available MAC algorithm for a 16-byte
or 24-byte DATAkey is the TDES-MAC algorithm.
Also note that the CPACF exploitation layer is activated only for MAC Generate or MAC Verify calls that
specify the ONLY rule_array keyword for segmenting control (this is the default segmenting control if no
segmenting control rule_array keyword is specified). The reason for this is that the intermediate MAC
context for normal CEX3C calls to MAC Generate and MAC Verify is protected by the adapter Master Key.
Because the same security cannot be provided for intermediate results from the host-based CPACF
exploitation layer (they are returned in the clear by the CPACF) the FIRST, MIDDLE, and LAST
segmenting control keywords will direct operations to the CEX3C.
Required commands
| This verb requires the MAC Generate command (offset X'0010') to be enabled in the active role.
Usage notes
None
Related information
The MAC Verify verb is described in “MAC Verify (CSNBMVR)” on page 245.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBMGNJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBMGNJ are shown here.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 243

MAC Generate (CSNBMGN)
Format
public native void CSNBMGNJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_identifier,
hikmNativeInteger text_length,
byte[] text,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] chaining_vector,
byte[] MAC);
244 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MAC Verify (CSNBMVR)
MAC Verify (CSNBMVR)
When the receiver gets a message, an application program calls the MAC Verify verb. This verb verifies a
4-byte, 6-byte, or 8-byte MessageAuthentication Code (MAC) for an application-supplied text string. This
verb verifies a MAC by generating another MAC and comparing it with the MAC received with the
message. This process takes place entirely within the secure module on the coprocessor. If the two codes
are the same, the message sent was the same one received.Areturn code indicates whether the MACs
are the same. The generated MAC never appears in storage and is not revealed outside the cryptographic
feature.
The MAC Verify verb can use any of the following methods to generate the MAC for authentication:
v TheANSI X9.9-1 single key algorithm, a single-length MAC verification or MAC generation key (or a
data-encrypting key), and the message text.
v TheANSI X9.19 optional double key algorithm, a double-length MAC verification or MAC generation key
and the message text.
v Using the Europay, MasterCard and Visa (EMV) padding rules.
The method used to verify the MAC should correspond with the method used to generate the MAC.
Host CPU acceleration: CPACF
For details about CPACF, see “CPACF support” on page 8.
Only keys with a key type of DATAcan be used successfully with the CPACF exploitation layer through
this verb. Specifically, a DATAkey has a CV (Control Vector) of all X'00' bytes for all active bytes of the CV
(eight bytes for 8-byte DES keys, 16 bytes for 16-byte DES keys, and 16 bytes for 24-byte DES keys).
Format
CSNBMVR(
return_code,
reason_code,
exit_data_length,
exit_data,
key_identifier,
text_length,
text,
rule_array_count,
rule_array,
chaining_vector,
mac )
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 14.
key_identifier
Direction: Input/Output Type: String
The 64-byte key label or internal key token that identifies a single-length or double-length MAC verify
key, a single-length or double-length MAC generation key, or a single-length DATAkey. The type of
key depends on the MAC process rule in the rule_array parameter.
text_length
Direction: Input Type: Integer
Chapter7.Verifyingdataintegrityandauthenticatingmessages 245

MAC Verify (CSNBMVR)
The length of the clear text you supply in the text parameter. If the text_length parameter is not a
multiple of eight bytes and if the ONLY or LAST keyword of the rule_array parameter is called, the text
is padded in accordance with the processing rule specified.
text
Direction: Input Type: String
The application-supplied text for which the MAC is verified.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0, 1, 2, or 3.
rule_array
Direction: Input Type: String
Zero to three keywords that provide control information to the verb. The keywords are described in
Table61. The keywords must be in 24 bytes of contiguous storage with each of the keywords
left-justified in its own 8-byte location and padded on the right with blanks. For example,
’X9.9-1 MIDDLE MACLEN4 ’
The order of the rule_array keywords is not fixed.
You can specify one of the MAC processing rules, and then choose one of the segmenting control
keywords and one of the MAC length keywords. The rule_array keywords are described in Table61.
Table61.KeywordsforMACVerifycontrolinformation
Keyword Description
| MACprocessrules(One,optional)
EMVMAC EMVpaddingrulewithasingle-lengthMACkey.Thekey_identifierparametermustidentifya
single-lengthMAC,MACVER,orDATAkey.Thetextisalwayspaddedwith1-8bytes,sothatthe
resultingtextlengthisamultipleofeightbytes.ThefirstpadcharacterisX'80'.Theremainingpad
charactersareX'00'.
EMVMACD EMVpaddingrulewithadouble-lengthMACkey.Thekey_identifierparametermustidentifya
double-lengthMACorMACVERkey.ThepaddingrulesarethesameasforEMVMAC.
TDES- ANSIX9.9-1procedureusingISO16609CBCmodetriple-DES(TDES)encryptionofthedata.Usesa
MAC double-lengthkey.
X9.9-1 ANSIX9.9-1andX9.19basicprocedure.Thekey_identifierparametermustidentifyasingle-length
MAC,MACVER,orDATAkey.X9.9-1causestheMACtobecomputedfromallthedata.Thetextis
paddedonlyifthetextlengthisnotamultipleofeightbytes.Ifpaddingisrequired,thepadcharacter
X'00'isused.Thisisthedefaultvalue.
X9.19OPT ANSIX9.19optionaldouble-lengthMACprocedure.Thekey_identifierparametermustidentifya
double-lengthMACorMACVERkey.ThepaddingrulesarethesameasforX9.9-1.
| Segmentingcontrol(Optional)
FIRST Firstcall;thisisthefirstsegmentofdatafromtheapplicationprogram.
LAST Lastcall;thisisthelastdatasegment.
MIDDLE Middlecall;thisisanintermediatedatasegment.
ONLY Onlycall;theapplicationprogramdoesnotemploysegmenting.Thisisthedefaultvalue.
| MAClengthandpresentation(Optional)
HEX-8 Verifiesa4-byteMACvaluerepresentedas8hexadecimalcharacters.
246 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MAC Verify (CSNBMVR)
Table61.KeywordsforMACVerifycontrolinformation (continued)
Keyword Description
HEX-9 Verifiesa4-byteMACvaluerepresentedastwogroupsof4hexadecimalcharacterswithaspace
characterbetweenthegroups.
MACLEN4 Verifiesa4-byteMACvalue.Thisisthedefaultvalue.
MACLEN6 Verifiesa6-byteMACvalue.
MACLEN8 Verifiesan8-byteMACvalue.
chaining_vector
Direction: Input/Output Type: String
An 18-byte string CCAuses as a system work area. Your application program must not change the
data in this string. The chaining vector permits data to be chained from one invocation call to another.
On the first call, initialize this parameter to binary zeros.
mac
Direction: Input Type: String
The 8-byte or 9-byte field that contains the MAC value you want to verify. The value in the field must
be left-justified and padded with zeros. If you specified the HEX-9 keyword in the rule_array
parameter, the input MAC is nine bytes in length.
Restrictions
It might seem intuitive that a DATAM key should also be usable for the MAC Generate verb, and a
DATAMV key for the MAC Verify verb, with the CPACF exploitation layer. However, this would violate the
security restrictions imposed by the user when the user creates a key of type DATAM or DATAMV.ADES
key that has been translated for use with the CPACF (see “CPACF support” on page 8) can be used with
CPACF DES encrypt and decrypt operations, an operation that is by definition not allowed for a DATAM or
DATAMV key type.Also note that by definition both through z/OS CCA-ICSF and in this S390 Linux CCA
access layer, a DATAkey of 16 bytes or 24 bytes in length is restricted from use with the X9.19OPT and
EMVMACD rule_array keyword specified MAC algorithms. The only available MAC algorithm for a 16-byte
or 24-byte DATAkey is the TDES-MAC algorithm.
Also note that the CPACF exploitation layer is activated only for MAC Generate or MAC Verify calls that
specify the ONLY rule_array keyword for segmenting control (this is the default segmenting control if no
segmenting control rule_array keyword is specified). The reason for this is that the intermediate MAC
context for normal CEX3CC calls to MAC Generate and MAC Verify is protected by the adapter Master
Key. Because the same security cannot be provided for intermediate results from the host-based CPACF
exploitation layer (they are returned in the clear by the CPACF) the FIRST, MIDDLE, and LAST
segmenting control keywords will direct operations to the CEX3C.
Required commands
| This verb requires the MAC Verify command (offset X'0011') to be enabled in the active role.
Usage notes
To verify a MAC in one call, specify the ONLY keyword on the segmenting rule keyword for the rule_array
parameter. For two or more calls, specify the FIRST keyword for the first input block, MIDDLE for
intermediate blocks (if any), and LAST for the last block.
For a given text string, the MAC resulting from the verification process is the same regardless of how the
text is segmented or how it was segmented when the original MAC was generated.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 247

MAC Verify (CSNBMVR)
Related information
The MAC Generate verb is described in “MAC Generate (CSNBMGN)” on page 241.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBMVRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBMVRJ are shown here.
Format
public native void CSNBMVRJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_identifier,
hikmNativeInteger text_length,
byte[] text,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] chaining_vector,
byte[] MAC);
248 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MDC Generate (CSNBMDG)
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 252 for detailed information.
Use this 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. This 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.
The user must enable the Generate MDC command with a Trusted Key Entry (TKE) workstation before
using this verb.
For a description of the MDC calculations, see “Modification Detection Code calculation” on page 493.
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: This 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: This verb can be used with a default key, or as a keyed-hash algorithm.Adefault 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.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 249

MDC Generate (CSNBMDG)
As with the default key, you must not alter the value of the MDC or chaining_vector variables between
calls.
Format
CSNBMDG(
return_code,
reason_code,
exit_data_length,
exit_data,
text_length,
text,
rule_array_count,
rule_array,
chaining_vector,
MDC )
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 14.
text_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the text variable. See
“Restrictions” on page 251.
text
Direction: Input Type: String
Apointer to a string variable containing the text for which the verb calculates the MDC value.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value can be 0, 1, or 2.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb.Akeyword specifies the method for calculating
the RSAdigital signature. Each keyword is left-justified in an 8-byte field and padded on the right with
blanks.All keywords must be in contiguous storage. The rule_array keywords are described in
Table62.
Table62.KeywordsforMDCGeneratecontrolinformation
Keyword Description
Segmentingandkeycontrol(One,optional)
ONLY Specifiesthatsegmentingisnotusedandthedefaultkeyisused.Thisisthedefault.
FIRST Specifiesthefirstsegmentoftext,anduseofthedefaultkey.
MIDDLE Specifiesanintermediatesegmentoftext,orthefirstsegmentoftextanduseofauser-supplied
key.
LAST Specifiesthelastsegmentoftext,orthatsegmentingisnotused,anduseofauser-suppliedkey.
Algorithmmode(One,optional)
MDC-2 Specifiestwoenciphermentsforeach8-byteblockusingMDCprocedures.Thisisthedefault.
250 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MDC Generate (CSNBMDG)
Table62.KeywordsforMDCGeneratecontrolinformation (continued)
Keyword Description
MDC-4 Specifiesfourenciphermentsforeach8-byteblockusingMDCprocedures.
PADMDC-2 Specifiestwoenciphermentsforeach8-byteblockusingPADMDCprocedures.
PADMDC-4 Specifiesfourenciphermentsforeach8-byteblockusingPADMDCprocedures.
chaining_vector
Direction: Input/Output Type: String
Apointer 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
Direction: Input/Output Type: String
Apointer 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.
Restrictions
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 a minimum of 16 bytes and a
multiple of eight 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.
Required commands
| In releases prior to CCA4.1.0 and for installations without CPACF support this verb requires the MDC
| Generate command (offset X'008A') to be enabled in the active role. This command is no longer required
| in CCA4.1.0 when CPACF clear-key function is available (KM, function 1), and enabled for CCAuse
| (environment variable CSU_HCPUACLR is set to '1', the default value).
The user must enable the Generate MDC command with a Trusted Key Entry (TKE) workstation before
using this verb.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBMDGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 251

MDC Generate (CSNBMDG)
The parameters for CSNBMDGJ are shown here.
Format
public native void CSNBMDGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger text_length,
byte[] text_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] chaining_vector,
byte[] MDC);
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 CCASupport 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 MDC Generate verb of the CCASupport 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:
Total text length (TTL)
The total number of text bytes processed to calculate a final MDC value
Running text length (RTL)
The total number of text bytes processed by all previous calls used to calculate a final MDC value
Carryover length (COL)
The number of text bytes that could not be processed in the previous call. The COLcan range from 0 -
15 bytes, and is stored in the chaining vector between calls.
New text length (NTL)
The carryover length plus the text length for the current call
Notes:
1. An intermediate MDC calculation always operates on eight bytes of text at a time.Any remaining text
that is not a multiple of eight bytes gets passed in the chaining vector as carryover text.
2. Acall 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 COLis calculated as text
length modulo 8, otherwise the COLequals the text length.Any carryover text bytes get passed in the
chaining vector as carryover text to the next segment call.
3. Acall 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 COLplus 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
252 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MDC Generate (CSNBMDG)
example, 16, 24, 32).As with FIRST, the remaining text bytes (NTLmodulo 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 NTLfor the LAST call is 19 bytes. If the
TTLis 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 NTLfor 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 RTLis greater than or equal to 16 and
v At least one MIDDLE segment is processed that has COLplus 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.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 253

MDC Generate (CSNBMDG)
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.
Scenario 2 (pre-Release 3.30)
Error type: Padding error related to segmenting.
Keywords affected:
v Algorithm PADMDC-2, PADMDC-4
v Segmenting and key control LAST
The MDC value is calculated incorrectly whenever:
v LAST text length is equal to 0 and
v TTLis greater than or equal to 16 and
v TTLmodulo 8 is equal to 0
Under the above conditions, 16 bytes of padding are incorrectly added to the text instead of the
required eight 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.
Scenario 3 (pre-Release 3.30)
Error type: Padding error, not segmenting related.
Keywords affected:
v Algorithm PADMDC-2, PADMDC-4
v Segmenting and key control ONLY, LAST
The MDC value is calculated incorrectly whenever:
v TTLis greater than or equal to 16 and
v TTLmodulo 8 is equal to 0
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:
PADMDC-2 or PADMDC-4
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 eight bytes of pad characters.
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.
Scenario 4 (pre-Release 3.30)
Error type: Padding error related to segmenting.
254 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MDC Generate (CSNBMDG)
Keywords affected:
v Algorithm PADMDC-2, PADMDC-4
v Segmenting and key control FIRST, MIDDLE
The MDC value is calculated incorrectly whenever:
v RTLis greater than or equal to 16 and
v LAST is called with COLplus text length greater than zero and less than 8
Under the above conditions, the text is padded with eight bytes more than is required.
Example:
PADMDC-2 or PADMDC-4
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:
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.
Scenario 5 (pre-Release 3.30)
Error type: Segmenting error, not padding related.
Keywords affected:
v Algorithm MDC-2, MDC-4, PADMDC-2, PADMDC-4
v Segmenting and key control MIDDLE without FIRST
The MDC value is calculated incorrectly whenever:
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:
MDC-2, MDC-4, PADMDC-2, or PADMDC-4
Chaining vector is set to hex zeros.
MDC value is set to a non-default key value (default key = X'5252525252525252 2525252525252525').
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:
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.
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.
Chapter7.Verifyingdataintegrityandauthenticatingmessages 255

MDC Generate (CSNBMDG)
Scenario 1 (Release 3.30 only)
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 RTLis greater than or equal to 16 and
v MIDDLE is called with COLplus 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:
MDC-2, MDC-4, PADMDC-2, or PADMDC-4
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.
Scenario 2 (Release 3.30 only)
Error type: Padding error related to segmenting.
Keywords affected:
v Algorithm PADMDC-2, PADMDC-4
v Segmenting and key control LAST
The MDC value is calculated incorrectly whenever:
v LAST text length is equal to 0 and
v TTLis greater than or equal to 16 and
v TTLmodulo 8 is equal to 0
Under the above conditions, 16 bytes of padding are added to the text instead of the required eight
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.
Scenario 3 (Release 3.30 only)
Error type: Padding error related to segmenting.
Keywords affected:
256 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

MDC Generate (CSNBMDG)
v Algorithm PADMDC-2, PADMDC-4
v Segmenting and key control LAST
The MDC value is calculated incorrectly whenever:
v TTLis greater than zero and less than 8
Under the above conditions, the text is incorrectly padded with 8 pad bytes less than required.
Example:
PADMDC-2 or PADMDC-4
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:
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
Chapter7.Verifyingdataintegrityandauthenticatingmessages 257

One-Way Hash (CSNBOWH)
One-Way Hash (CSNBOWH)
Use the One-Way Hash verb to generate a one-way hash on specified text.
These SHAbased hashing functions are supported with the CPACF exploitation layer: SHA-1, SHA-224,
SHA-256, SHA-384, SHA-512. For details about CPACF, see “CPACF support” on page 8.
Format
CSNBOWH(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
text_length,
text,
chaining_vector_length,
chaining_vector,
hash_length,
hash )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1 or 2.
rule_array
Direction: Input Type: String
These keywords provide control information to the verb. The optional chaining flag keyword indicates
whether calls to this verb are chained together logically to overcome buffer size limitations. Each
keyword is left-justified in an 8-byte field and padded on the right with blanks.All keywords must be in
contiguous storage. The rule_array keywords are described in Table63.
Table63.KeywordsforOne-WayHashcontrolinformation
Keyword Description
| Hashmethod(One,required)
MD5 HashalgorithmisMD5algorithm.UsethishashmethodforPKCS-1.0andPKCS-1.1.Lengthof
hashgeneratedis16bytes.
RPMD-160 HashalgorithmisRIPEMD-160.Lengthofhashgeneratedis20bytes.
SHA-1 HashalgorithmisSHA-1algorithm.Lengthofhashgeneratedis20bytes.
SHA-224 HashalgorithmisSHA-224algorithm.Lengthofhashgeneratedis20bytes.
SHA-256 HashalgorithmisSHA-256algorithm.Lengthofhashgeneratedis20bytes.
SHA-384 HashalgorithmisSHA-384algorithm.Lengthofhashgeneratedis20bytes.
SHA-512 HashalgorithmisSHA-512algorithm.Lengthofhashgeneratedis20bytes.
| Chainingflag(One,optional)
258 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

One-Way Hash (CSNBOWH)
Table63.KeywordsforOne-WayHashcontrolinformation (continued)
Keyword Description
FIRST Specifiesthisisthefirstcallinaseriesofchainedcalls.Intermediateresultsarestoredinthehash
field.
LAST Specifiesthisisthelastcallinaseriesofchainedcalls.
MIDDLE Specifiesthisisamiddlecallinaseriesofchainedcalls.Intermediateresultsarestoredinthe
hashfield.
ONLY Specifiesthisistheonlycallandthecallisnotchained.Thisisthedefault.
text_length
Direction: Input Type: Integer
The length of the text parameter in bytes.
Note: If you specify the FIRST or MIDDLE keyword, the text length must be a multiple of the block
size of the hash method. For MD5, RPMD-160, and SHA-1, this is a multiple of 64 bytes.
For ONLY and LAST, this verb performs the required padding according to the algorithm
specified.
text
Direction: Input Type: String
The application-supplied text on which this verb performs the hash.
chaining_vector_length
Direction: Input Type: Integer
The byte length of the chaining_vector parameter. This must be 128 bytes.
chaining_vector
Direction: Input/Output Type: String
This field is a 128-byte work area. Your application must not change the data in this string. The
chaining vector permits chaining data from one call to another.
hash_length
Direction: Input Type: Integer
The length of the supplied hash field in bytes.
Note: For SHA-1 and RPMD-160 this must be a minimum of 20 bytes. For MD5 this must be a
minimum of 16 bytes.
hash
Direction: Input/Output Type: String
This field contains the hash, left-justified. The processing of the rest of the field depends on the
implementation. If you specify the FIRST or MIDDLE keyword, this field contains the intermediate hash
value. Your application must not change the data in this field between the sequence of FIRST,
MIDDLE, and LAST calls for a specific message.
Restrictions
None
Chapter7.Verifyingdataintegrityandauthenticatingmessages 259

One-Way Hash (CSNBOWH)
Required commands
None
Usage notes
Although the algorithms accept zero bit length text, it is not supported for any hashing method.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBOWHJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBOWHJ are shown here.
Format
public native void CSNBOWHJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger text_length,
byte[] text,
hikmNativeInteger chaining_vector_length,
byte[] chaining_vector,
hikmNativeInteger hash_length,
byte[] hash );
260 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 8. Key storage mechanisms
This chapter describes how you can use key storage mechanisms and the associated key record verbs to
perform operations on key tokens and key records located inAES, DES, and PKAkey storage.A
key-token record consists of a key-token name (key label) and a key token of format null, internal, or
external. The operations to be performed are: creating, writing, reading, listing, and deleting key tokens or
key records.
The verbs described in this chapter include:
v “AES Key Record Create (CSNBAKRC)” on page 267
v “AES Key Record Delete (CSNBAKRD)” on page 269
v “AES Key Record List (CSNBAKRL)” on page 271
v “AES Key Record Read (CSNBAKRR)” on page 274
v “AES Key Record Write (CSNBAKRW)” on page 276
v “DES Key Record Create (CSNBKRC)” on page 278
v “DES Key Record Delete (CSNBKRD)” on page 280
v “DES Key Record List (CSNBKRL)” on page 282
v “DES Key Record Read (CSNBKRR)” on page 284
v “DES Key Record Write (CSNBKRW)” on page 286
v “PKAKey Record Create (CSNDKRC)” on page 288
v “PKAKey Record Delete (CSNDKRD)” on page 290
v “PKAKey Record List (CSNDKRL)” on page 292
v “PKAKey Record Read (CSNDKRR)” on page 295
v “PKAKey Record Write (CSNDKRW)” on page 297
v “Retained Key Delete (CSNDRKD)” on page 299
v “Retained Key List (CSNDRKL)” on page 301
Key labels and key-storage management
Use the verbs described in this section to manageAES, DES, and PKAkey storage. The CCAsoftware
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.
An independent key-storage system can be used to manage records forAES key records, DES key
records, and PKAkey records:
AES key storage Holds null and internalAES key tokens
DES key storage Holds null, external, and internal DES key tokens
PKAkey storage Holds null PKAkey tokens, and both internal and external public and
private PKAkey tokens
Private RSAkeys are generated and optionally retained within the coprocessor using the PKAKey
Generate verb. Depending on the other uses for coprocessor storage, between 75 and 150 keys can
normally be retained within the coprocessor.
Key storage must be initialized before any records are created. Before a key token can be stored in key
storage, a key-storage record must be created using theAES Key Record Create, DES Key Record
Create, or PKAKey Record Create verb.
©CopyrightIBMCorp.2007,2011 261

Use theAES Key Record Delete, DES Key Record Delete, or PKAKey Record Delete verb to delete a key
token from a key record, or to entirely delete the key record from key storage.
Use theAES Key Record List, DES Key Record List, or PKAKey Record List verb to determine the
existence of key records in key storage. These list verbs create a key-record-list file with information about
select key records. The wildcard character, represented by an asterisk (*), is used to obtain information
about multiple key records. The file can be read using conventional workstation-data-management
services.
Individual key tokens can be read using theAES Key Record Read, DES Key Record Read, and PKAKey
Record Read verbs or written using theAES Key Record Write, DES Key Record Write, and PKAKey
Record Write verbs.
Environment variables for the key storage file
These environment variables contain the name of the key storage file. There is one for each type:AES,
DES, and PKA.
CSUAESDS AES key storage file.
CSUDESDS DES key storage file.
CSUPKADS PKAkey storage file.
See also “Dual Support: Key storage interactions” on page 551.
Key-label content
Use a key label to identify a record in key storage managed by a CCAimplementation. 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.
Akey-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.Afirst 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 (inASCII 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 Aname token consists of 1 - 8 characters in the character setA- Z, 0 - 9, and three additional
characters relating to different character symbols in the various national language character sets as
listed in Table64.
Table64.Validsymbolsforthenametoken
ASCIIsystems EBCDICsystems USAgraphic(forreference)
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, eitherASCII or EBCDIC.
Notes:
1. Some CCAimplementations accept the characters a - z and fold these to their uppercase
equivalents,A- Z. For compatibility reasons, only use the uppercase alphabetic characters.
262 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

2. Some implementations internally transform the EBCDIC encoding of a key label to anASCII 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 wild card represented by an asterisk (*). (X'2A' inASCII; X'5C'
in EBCDIC). When a verb permits the use of a wild card, the wild card 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 wild
card.
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 are listed in Table65.
Table65.Keylabelsthatarenotvalid
Keylabelnotvalid Problemwithkeylabel
A/.B Aslashisanunacceptablecharacter
ABCDEFGH9 Nametokenisgreaterthan8characters
1111111.2.3.4.55555 Firstcharactercannotbenumeric
A1111111.2.3.4.55555.6.7.8 Numberofnametokensexceeds7
BANKSYS.XXXXX.*43*.D Numberofwildcardsexceeds1
A.B. Lastcharactercannotbeaperiod
Key storage with Linux for IBM System z, in contrast to z/OS for IBM
System z
Key storage for IBM z/OS and for Linux on the IBM platforms other than IBM System z, diverged in design
at their very inception.
Background information about master key management
| There are four types (or sets) of master keys (Symmetric DES,AES,Asymmetric RSA(PKA), andAPKA).
| There are three master key registers for each of the four types of master key. In other words, there are a
| total of twelve master key registers.
| TheAPKAmaster-key register set, introduced to CCAbeginning with Release 4.1.0, 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.
For each of the four types, there is a master key register in one of these three categories:
New master-key (NMK) register
This register holds a master key that is not yet usable for decrypting key tokens for normal
cryptographic operations.
The NMK register can be in one of these states:
EMPTY
No key parts have been loaded yet.
Chapter8.Keystoragemechanisms 263

PARTIALLY FULL
Some key parts have been loaded, but not the LAST key part. See “Master Key Process
(CSNBMKP)” on page 93.
FULL The LAST key part has been loaded, but the SET command has not yet been called. See
“Master Key Process (CSNBMKP)” on page 93.
Current master-key (CMK) register
This register holds a master key that can be used to decrypt internal key tokens for keys in use with
normal cryptographic operations. Internal key tokens are protected under the master key; the keys are
actually stored outside the adapter.
The CMK register can be in one of these states:
EMPTY
No valid key has yet been established with the SET command in the life of this adapter, or the
adapter has been re-initialized to clear the master key registers.
VALID
Amaster key has been loaded with the SET command.
Old master-key (OMK) register
This is the master key that previously has been the CMK, before the master key that is now in the
CMK register. The OMK register can also be used to decrypt internal key tokens, but for these keys a
warning with return code 0 and reason code 2 is returned, along with the results from the requested
cryptographic operation.
The OMK register can be in one of these states:
EMPTY
No valid key is in this register.
VALID
Amaster key that previously was in the CMK register has been shifted to the OMK register by the
SET command. The same invocation of the SET command also shifted the contents of the NMK
register into the CMK register.
SET command
The SET command is invoked with “Master Key Process (CSNBMKP)” on page 93. The SET command
performs these operations:
1. The master key from the CMK register is copied to the OMK register.
2. The master key from the FULLNMK register is copied to the CMK register.
3. The NMK register status is changed to EMPTY.
Key Storage on z/OS (RTNMK-focused)
Design point - Keys should be re-enciphered to a master key in the NMK register. This forces the following
process to be followed when changing the master key:
v Load all the master key parts for a NMK, such that the LAST key part has been loaded, but the SET
command has not been issued. Now the NMK register is in the FULLstate.
v Re-encipher all of (for example: CKDS) an existing key storage to a copy of that key storage that is not
online, using the RTNMK rule_array keyword of “Key Token Change (CSNBKTC)” on page 163 (forAES
or DES) or “PKAKey Token Change (CSNDKTC)” on page 385 (for PKA), creating CKDS-pending.
Keys in this copy are enciphered under the NMK register, and so are not usable for normal
cryptographic operations.
v Invoke the SET command for the NMK. See “SET command.” Now the master keys in the current
CKDS are enciphered under the OMK (because of the shift), and are usable.Also, the master keys in
the CKDS-pending are also usable because the NMK has now become the CMK.
v Delete the old CKDS and change CKDS-pending to be the normal CKDS, completing the process.
264 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key Storage for traditional IBM systems other than IBM System z
(RTCMK-focused: Linux, AIX®, Windows)
Design point - Keys should be re-enciphered to a master key in the CMK register. This forces the following
process to be followed when changing the master key:
v Load all the master key parts for a NMK, such that the LAST key part has been loaded, then issue the
SET command. Now the previous OMK is gone, the previous CMK is now the OMK, and the CMK
contains the newly-loaded value. See “SET command” on page 264.
v Re-encipher all of an existing CCAhost key storage data file's key tokens, which are enciphered under
the OMK, to be enciphered under the CMK. This is done using the RTCMK rule_arry keyword of “Key
Token Change (CSNBKTC)” on page 163 or “PKAKey Token Change (CSNDKTC)” on page 385.
– This immediately replaces operational keys with the re-enciphered version.
– The CCAkey storage file has a data structure with the verification pattern of the most recently SET
master key. The key storage implementation also allows writing external tokens into the key storage.
This means that external key tokens, and the internal key tokens encrypted under current master
key, will be allowed into the key storage.
It is impossible with current implementation to use RTNMK together with CCAkey storage.
v During the re-encipherment:
– Some of the keys in the CCAkey storage files are enciphered under the OMK (because of the shift)
and are usable
– Some of the keys in the CCAkey storage files are enciphered under the CMK, either because they
are new or because they have been re-enciphered.
– No new key tokens can be created with the key wrapped using the OMK.
Both types are usable for cryptographic operations.
Changing the master key for two or more adapters that have the same
master key, with shared CCA key storage
Because the verification pattern of the CMK is stored in a header in key storage, changing the master key
for a configuration of multiple adapters requires extra care. The master key verification pattern in key
storage has the following properties:
v It is checked once when a process starts.
v It is repopulated when the first CEX3C has its master key changed.
These two properties force the user to use the same process to change the master key for all CEX3Cs
after the first CEX3C. If the process exits (such as when the application completes), then the next time
that the application starts the key storage header will be checked and the master key verification pattern
will reflect the newly SET master key, which will cause a future attempt to set that same master key to a
second or third CEX3C to have a conflict with the key storage header. Therefore, using the same process
to change the master keys in all the CEX3C adapters is the only way to proceed if CCAkey storage is
being used.
There are several ways to change the master keys, most of which do not suffer from this limitation:
v ATKE can be used to change the master keys for all the CEX3C adapters in a group.
v An operator can directly change the master keys for a domain on a CEX3C from an IBM System z
management interface (physical access is needed).
v Auser application built to use the libcsulccamk.so library for this purpose, which can be programmed to:
1. Allocate a CEX3C by invoking “Cryptographic ResourceAllocate (CSUACRA)” on page 86.
2. Change the master key.
3. Deallocate each adapter in the group before exiting, by invoking “Cryptographic Resource
Deallocate (CSUACRD)” on page 88.
Chapter8.Keystoragemechanisms 265

v Note that the included utility, named panel.exe, is not designed to change the master keys for all the
cards in a group; this is a more sophisticated operation.
For details about panel.exe, see “The panel.exe utility” on page 553.
Key storage file ownership
The last user to access the key storage file owns it, due to the internals of the key storage functions. The
file is recreated after being compressed, and due to the file creation the owner is changed.
Having the set-group-id bit ( g+s ) on in the directory permission causes the file to be created with the
group owner the same as the directory group owner. The group read/write permissions on the file then
allow the other members of the group continued access to the file.
The Linux on IBM System z approach
Because the CCAkey storage design point for the Linux platform host release has always been
CMK-focused, this design point was taken forward for the Linux on IBM System z approach.At this time,
CCAhost key storage does not support nor ship with an additional utility to manage the 'store-in-pending'
approach to re-enciphering key tokens. This additional utility is necessary to work with use of the RTNMK
keyword for “Key Token Change (CSNBKTC)” on page 163 and “PKAKey Token Change (CSNDKTC)” on
page 385. Therefore, it is suggested that users wanting to make use of CCAhost key storage
management follow the 'RTCMK-focused' approach described in “Key Storage for traditional IBM systems
other than IBM System z (RTCMK-focused: Linux,AIX®, Windows)” on page 265.
However it is also desirable to provide as much host-support equivalence with the z/OS approach as
possible, given that the underlying system is running on a an System z platform and likely to collaborate
with z/OS software. Therefore, the RTNMK keyword is provided for “Key Token Change (CSNBKTC)” on
page 163 and “PKAKey Token Change (CSNDKTC)” on page 385 to allow users who have their own
utility or key storage management facility to manage key tokens using the method most familiar from z/OS:
v The key tokens to be enciphered should be passed directly (not by label) to “Key Token Change
(CSNBKTC)” on page 163 and “PKAKey Token Change (CSNDKTC)” on page 385 for re-encipherment,
and stored outside CCAhost key storage.
v When re-encipherment is complete and the “Master Key Process (CSNBMKP)” on page 93 SET'
command has been issued, the re-enciphered key tokens can be reintroduced to CCAhost key storage
if desired, using the standard mechanisms.
266 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

AES Key Record Create (CSNBAKRC)
AES Key Record Create (CSNBAKRC)
Use theAES Key Record Create verb to create a key-token record inAES key-storage. The new key
record can be a nullAES key-token or a valid internalAES key-token. It is identified by the key label
specified with the key_label parameter.
After creating anAES key-record, use any of the following verbs to add or update a key token in the
record:
v AES Key Record Delete
v AES Key Record Write
v Key Generate
v Key Token Change
| v Key Token Change2
v Symmetric Key Generate
v Symmetric Key Import
| v Symmetric Key Import2
Notes:
1. To delete a key record fromAES key-storage, use theAES Key Record Delete verb.
2. AES key records are stored in the external key-storage file defined by the CSUAESDS environment
variable.
Format
CSNBAKRC (
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array_count,
key_label,
key_token_length,
key_token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type:Array
| This parameter is ignored.
key_label
Direction: Input Type: String
Apointer to a string variable containing the key label of theAES key-record to be created.
key_token_length
Chapter8.Keystoragemechanisms 267

AES Key Record Create (CSNBAKRC)
Direction: Input Type: Integer
Apointer 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 nullAES key-token is created.
key_token
Direction: Input Type: String
Apointer to a string variable containing the key token being written toAES key-storage.
Restrictions
The record must have a unique label. Therefore, there cannot be another record in theAES key storage
file with the same label and a different key type.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBAKRCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBAKRCJ are shown here.
Format
public native void CSNBAKRCJ(
hikmNativeInteger return_code,
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 );
268 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

AES Key Record Delete (CSNBAKRD)
AES Key Record Delete (CSNBAKRD)
Use theAES Key Record Delete verb to perform one of the following tasks in theAES key storage file:
v Overwrite (delete) a key token or key tokens inAES key-storage, replacing the key token of each
selected record with a nullAES key-token.
v Delete an entire key record or key records, including the key label and the key token of each selected
record, fromAES 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 wild card (*) in the key label.
Note: AES key records are stored in the external key-storage file defined by the CSUAESDS environment
variable.
Format
CSNBAKRD (
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0 or 1.
rule_array
Direction: Input Type: String
Apointer to a string variable containing an array of keywords. The keywords are eight bytes in length
and must be left-aligned and padded on the right with space characters. The rule_array keywords are
described in Table66.
Table66.KeywordsforAESKeyRecordDeletecontrolinformation
Keyword Description
Task(One,optional)
TOKEN-DL DeletesakeytokenfromakeyrecordinAESkeystorage.Thisisthedefault.
LABEL-DL Deletesanentirekeyrecord,includingthekeylabel,fromAESkeystorage.
key_label
Direction: Input Type: String
Apointer to a string variable containing the key label of a key-token record or records inAES
key-storage. Use a wild card (*) in the key_label variable to identify multiple records in key storage.
Chapter8.Keystoragemechanisms 269

AES Key Record Delete (CSNBAKRD)
Restrictions
The record defined by the key_label must be unique.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBAKRDJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBAKRDJ are shown here.
Format
public native void CSNBAKRDJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_identifier );
270 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

AES Key Record List (CSNBAKRL)
AES Key Record List (CSNBAKRL)
TheAES Key Record List verb creates a key-record-list file containing information about specified key
records in key storage. Information listed includes whether record validation is correct, the type of key, and
the date and time the 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
wild card (*) in the key label.
Notes:
1. To list all the labels in key storage, specify the key_label parameter with *,&rbl;&rbl;*.*,&rbl;&rbl;*.*.*,
and so forth, up to a maximum of seven name tokens (*.*.*.*.*.*.*).
2. AES key records are stored in the external key-storage file defined by the CSUAESDS environment
variable.
This verb creates the key-record-list file and returns the name of the file and the length of the file name to
the calling application. This file has a header record, followed by 0 - n detail records, where n is the
number of key records with matching key-labels.
The file is kept in the /opt/IBM/CEX3C/keys/deslist directory (assuming the directory name was not
changed during installation). These list files are created under the ownership of the environment of the
user that requests the list service. Make sure the files created kept the same group ID as your installation
requires. This can also be achieved by setting the 'set-group-id-on-execution' bit on in this directory. See
the g+s flags in the chmod command for full details. Not doing this might cause errors to be returned on
key-record-list verbs.
Format
CSNBAKRL(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label,
dataset_name_length,
dataset_name,
security_server_name )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type:Array
Apointer to a string variable containing an array of keywords. This verb currently does not use
keywords.
key_label
Chapter8.Keystoragemechanisms 271

AES Key Record List (CSNBAKRL)
Direction: Input Type: String
Apointer to a string variable containing the key label of a key-token record in key storage. In a key
label, you can use a wild card (*) to identify multiple records in key storage.
dataset_name_length
Direction: Output Type: Integer
Apointer 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
Direction: Output Type: String
Apointer to a string variable containing the name of the file returned by the verb. The file contains the
AES key-record information. When the verb stores a key-record-list file, it overlays any older file with
the same name.
The file name returned by this verb is defined by the CSUAESLD environment variable.
This verb returns the file name as a fully qualified file specification (for example, /opt/IBM/CEX3C/keys/
KYRLTnnn.LST), where nnn is the numeric portion of the name. This value increases by one every
time that you use this verb. When this value reaches 999, it resets to 001.
security_server_name
Direction: Output Type: String
Apointer to a string variable. The information in this variable is not currently used, but the variable
must be declared.
Restrictions
None
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBAKRLJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBAKRLJ are shown here.
272 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

AES Key Record List (CSNBAKRL)
Format
public native void CSNBAKRLJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_label,
hikmNativeInteger data_set_name_length,
byte[] data_set_name,
byte[] security_server_name );
Chapter8.Keystoragemechanisms 273

AES Key Record Read (CSNBAKRR)
AES Key Record Read (CSNBAKRR)
Use theAES Key Record Read verb to read a key-token record fromAES 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.
Note: AES key records are stored in the external key-storage file defined by the CSUAESDS environment
variable.
Format
CSNBAKRR (
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label,
key_token_length,
key_token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type:Array
| This parameter is ignored.
key_label
Direction: Input Type: String
Apointer to a string variable containing the key label of the record to be read fromAES key-storage.
key_token_length
Direction: Input/Output Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_token variable. The
maximum length is 64.
key_token
Direction: Output Type: String
Apointer to a string variable containing the key token read fromAES key-storage. This variable must
be large enough to hold theAES key token being read. On completion, the key_token_length variable
contains the actual length of the token being returned.
Restrictions
None.
274 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

AES Key Record Read (CSNBAKRR)
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBAKRRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBAKRRJ are shown here.
Format
public native void CSNBAKRRJ(
hikmNativeInteger return_code,
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 );
Chapter8.Keystoragemechanisms 275

AES Key Record Write (CSNBAKRW)
AES Key Record Write (CSNBAKRW)
Use this verb to write a copy of anAES key-token from application storage intoAES key-storage. This
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.
AES key records are stored in the external key-storage file defined by the CSUAESDS environment
variable.
Note: Before using this verb, use the verb “AES Key Record Create (CSNBAKRC)” on page 267 to create
a key record in the key storage file.
Format
CSNBAKRW (
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label,
key_token_length,
key_token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0 or 1.
rule_array
Direction: Input Type:Array
Apointer to a string variable containing an array of keywords. The keywords are eight bytes in length
and must be left-aligned and padded on the right with space characters.
The rule_array keywords are described in Table67.
Table67.KeywordsforAESKeyRecordWritecontrolinformation
Keyword Description
Processingoption(One,optional)
CHECK SpecifiesthattherecordiswrittenonlyifarecordofthesamelabelinAESkey-storagecontainsa
nullkey-token.Thisisthedefault.
OVERLAY SpecifiesthattherecordisoverwrittenregardlessofthecurrentcontentoftherecordinAES
key-storage.
key_label
Direction: Input Type: String
276 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

AES Key Record Write (CSNBAKRW)
Apointer to a string variable containing the key label that identifies the record inAES key-storage
where the key token is to be written.
key_token_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_token variable. This
value must be 64.
key_token
Direction: Input Type: String
Apointer to a string variable containing theAES key-token to be written intoAES key-storage.
Restrictions
The record defined by the key_label parameter must be unique and must already exist in the key storage
file.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
You can use this verb with the key record create verb to write an initial record to key storage. Use it
following the Key Import and Key Generate verb to write an operational key imported or generated by
these verbs directly to the key storage file.
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBAKRWJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBAKRWJ are shown here.
Format
public native void CSNBAKRWJ(
hikmNativeInteger return_code,
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 );
Chapter8.Keystoragemechanisms 277

DES Key Record Create (CSNBKRC)
DES Key Record Create (CSNBKRC)
Use the DES Key Record Create verb to add a key record to the DES key storage file. The record
contains a key token set to binary zeros and is identified by the label passed in the key_label parameter.
The key label must be unique.
DES key records are stored in the external key-storage file defined by the CSUDESDS environment
variable.
Format
CSNBKRC(
return_code,
reason_code,
exit_data_length,
exit_data,
key_label )
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 14.
key_label
Direction: Input Type: String
The 64-byte label of a record in the DES key storage file that is the target of this verb. The created
record contains a key token set to binary zeros and has a key type of NULL.
Restrictions
The record must have a unique label. Therefore, there cannot be another record in the DES key storage
file with the same label and a different key type.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKRCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKRCJ are shown here.
278 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

DES Key Record Create (CSNBKRC)
Format
public native void CSNBKRCJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_label );
Chapter8.Keystoragemechanisms 279

DES Key Record Delete (CSNBKRD)
DES Key Record Delete (CSNBKRD)
Use the DES Key Record Delete verb to perform one of the following tasks in the DES key storage file:
v Replace the token in a key record with a null key token
v Delete an entire key record, including the key label, from the key storage file
DES key records are stored in the external key-storage file defined by the CSUDESDS environment
variable.
Format
CSNBKRD(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
The 8-byte keyword that defines the action to be performed. The rule_array keywords are described in
Table68.
Table68.KeywordsforDESKeyRecordDeletecontrolinformation
Keyword Description
Task(Onerequired)
TOKEN-DL DeletesakeytokenfromakeyrecordinDESkeystorage.
LABEL-DL Deletesanentirekeyrecord,includingthekeylabel,fromDESkeystorage.
key_label
Direction: Input Type: String
The 64-byte label of a record in the key storage file that is the target of this verb.
Restrictions
The record defined by the key_label must be unique.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
280 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

DES Key Record Delete (CSNBKRD)
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKRDJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKRDJ are shown here.
Format
public native void CSNBKRDJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_label );
Chapter8.Keystoragemechanisms 281

DES Key Record List (CSNBKRL)
DES Key Record List (CSNBKRL)
The DES Key Record List verb creates a key-record-list file containing information about specified key
records in key storage. Information listed includes whether record validation is correct, the type of key, and
the date and time the 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
wild card (*) in the key label.
Note: 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 (*.*.*.*.*.*.*).
This verb creates the key-record-list file and returns the name of the file and the length of the file name to
the calling application. This file has a header record, followed by 0 - n detail records, where n is the
number of key records with matching key-labels. The file is kept in the /opt/IBM/CEX3C/keys/deslist
directory (assuming the directory name was not changed during installation). These list files are created
under the ownership of the environment of the user that requests the list service. Make sure the files
created kept the same group ID as your installation requires. This can also be achieved by setting the
“set-group-id-on-execution” bit on in this directory. See the g+s flags in the chmod command for full
details. Not doing this might cause errors to be returned on key-record-list verbs.
DES key records are stored in the external key-storage file defined by the CSUDESDS environment
variable.
Format
CSNBKRL(
return_code,
reason_code,
exit_data_length,
exit_data,
key_label,
dataset_name_length,
dataset_name,
security_server_name )
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 14.
key_label
Direction: Input Type: String
The key_label parameter is a pointer to a string variable containing the key label of a key-token record
in key storage. In a key label, you can use a wild card (*) to identify multiple records in key storage.
dataset_name_length
Direction: Output Type: Integer
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
Direction: Output Type: String
282 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

DES Key Record List (CSNBKRL)
The dataset_name parameter is a pointer to a 64-byte string variable containing the name of the file
returned by the verb. The file contains the key-record information.
The verb returns the file name as a fully qualified file specification.
Note: When the verb stores a key-record-list file, it overlays any older file with the same name.
security_server_name
Direction: Output Type: String
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.
Restrictions
None
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKRLJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKRLJ are shown here.
Format
public native void CSNBKRLJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_label,
hikmNativeInteger data_set_name_length,
byte[] data_set_name,
byte[] security_server_name );
Chapter8.Keystoragemechanisms 283

DES Key Record Read (CSNBKRR)
DES Key Record Read (CSNBKRR)
Use the DES Key Record Read verb to copy an internal key token from the DES key storage file to
application storage. Other cryptographic services can then use the copied key token directly. The key
token can also be used as input to the token copying functions of Key Generate or Key Import verbs to
create additional NOCV keys.
DES key records are stored in the external key-storage file defined by the CSUDESDS environment
variable.
Format
CSNBKRR(
return_code,
reason_code,
exit_data_length,
exit_data,
key_label,
key_token )
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 14.
key_label
Direction: Input Type: String
The 64-byte label of a record in the DES key storage file. The internal key token in this record is
returned to the caller.
key_token
Direction: Output Type: String
The 64-byte internal key token retrieved from the DES key storage file.
Restrictions
The record defined by the key_label parameter must be unique and must already exist in the key storage
file.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKRRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKRRJ are shown here.
284 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

DES Key Record Read (CSNBKRR)
Format
public native void CSNBKRRJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_label,
byte[] key_token );
Chapter8.Keystoragemechanisms 285

DES Key Record Write (CSNBKRW)
DES Key Record Write (CSNBKRW)
Use the DES Key Record Write verb to copy an internal DES key token from application storage into the
DES key storage file. The key label must be unique and the record must already exist in the key storage
file.
DES key records are stored in the external key-storage file defined by the CSUDESDS environment
variable.
Note: Before you use this verb, use the DES Key Record Create verb (see “DES Key Record Create
(CSNBKRC)” on page 278) to create a key record in the key storage file.
Format
CSNBKRW(
return_code,
reason_code,
exit_data_length,
exit_data,
key_token,
key_label )
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 14.
key_token
Direction: Input/Output Type: String
The 64-byte internal key token that is written to the DES key storage file.
key_label
Direction: Input Type: String
The 64-byte label of a record in the DES key storage file that is the target of this verb. The record is
updated with the internal key token supplied in the key_token parameter.
Restrictions
The record defined by the key_label parameter must be unique and must already exist in the key storage
file.
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
You can use this verb with the key record create verb to write an initial record to key storage. Use it
following the Key Import and Key Generate verb to write an operational key imported or generated by
these verbs directly to the key storage file.
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
286 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

DES Key Record Write (CSNBKRW)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBKRWJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBKRWJ are shown here.
Format
public native void CSNBKRWJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] key_token,
byte[] key_label );
Chapter8.Keystoragemechanisms 287

PKA Key Record Create (CSNDKRC)
PKA Key Record Create (CSNDKRC)
This verb writes a new record to the PKAkey storage file.
PKAkey records are stored in the external key-storage file defined by the CSUPKADS environment
variable.
Format
CSNDKRC(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
label,
token_length,
token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type: String
This parameter is ignored.
label
Direction: Input Type: String
The label of the record to be created, 64-byte character string.
token_length
Direction: Input Type: Integer
The length of the field containing the token to be written to the PKAkey storage file. If zero is
specified, a null token will be added to the file. The maximum value of token_length is the maximum
length of a private RSAtoken.
token
Direction: Input Type: String
Data to be written to the PKAkey storage file if token_length is nonzero.An RSAprivate token in
either external or internal format, or an RSApublic token.
Restrictions
None
288 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Record Create (CSNDKRC)
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDKRCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDKRCJ are shown here.
Format
public native void CSNDKRCJ(
hikmNativeInteger return_code,
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 );
Chapter8.Keystoragemechanisms 289

PKA Key Record Delete (CSNDKRD)
PKA Key Record Delete (CSNDKRD)
Use PKAKey Record Delete to delete a record from the PKAkey storage file.
PKAkey records are stored in the external key-storage file defined by the CSUPKADS environment
variable.
Format
CSNDKRD(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
label )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 0 or 1.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left-justified in 8-byte fields and
padded on the right with blanks.All keywords must be in contiguous storage. The rule_array keywords
are described in Table69.
Table69.KeywordsforPKAKeyRecordDeletecontrolinformation
Keyword Description
| Deletionmode(One,optional).Specifieswhethertherecordistobedeletedentirelyorwhetheronlyitscontentsare
| tobeerased.
LABEL-DL SpecifiestherecordwillbedeletedfromthePKAkeystoragefileentirely.Thisisthedefaultdeletion
mode.
TOKEN-DL Specifiesonlythecontentsoftherecordaretobedeleted.TherecordwillstillexistinthePKAkey
storagefile,butwillcontainonlybinaryzeros.
label
Direction: Input Type: String
The label of the record to be deleted, a 64-byte character string.
Restrictions
None
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
290 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Record Delete (CSNDKRD)
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDKRDJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDKRDJ are shown here.
Format
public native void CSNDKRDJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_identifier );
Chapter8.Keystoragemechanisms 291

PKA Key Record List (CSNDKRL)
PKA Key Record List (CSNDKRL)
The PKAKey Record List verb creates a key-record-list file containing information about specified key
records in PKAkey-storage. Information includes whether record validation is correct, the type of key, and
the dates and times when the record was created and last updated.
Specify the key records to be listed using the key_label parameter. To identify multiple key records, use
the wild card (*) in a key label.
Note: 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 (*.*.*.*.*.*.*).
This verb creates the list file and returns the name of the file and the length of the file name to the calling
application. This verb also returns the name of the security server where the file is stored. The PKAKey
Record List file has a header record, followed by 0 - n detail records, where n is the number of key
records with matching key labels. The file is kept in the /opt/IBM/CEX3C/keys/pkalist directory (assuming
the directory name was not changed during installation). These list files are created under the ownership
of the environment of the user that requests the list verb. Make sure the files created kept the same group
ID as your installation requires. This can also be achieved by setting the “set-group-id-on-execution” bit on
in this directory. See the g+s flags in the chmod command for full details. Not doing this might cause
errors to be returned on key-record-list verbs.
PKAkey records are stored in the external key-storage file defined by the CSUPKADS environment
variable.
For information concerning the location of the key-record-list directory, refer to the IBM 4764 PCI-X
Cryptographic Coprocessor CCASupport Program Installation Manual.
Format
CSNDKRL(
return_code,
reason_code,
exit_data_length,
edit_data,
rule_array_count,
rule_array,
key_label,
dataset_name_length,
dataset_name,
security_server_name )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type:Array
| This parameter is ignored.
292 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Record List (CSNDKRL)
key_label
Direction: Output Type: String
The key_label parameter is a pointer to a string variable containing a key record in PKAkey-storage.
You can use a wild card (*) to identify multiple records in key storage.
dataset_name_length
Direction: Input Type: Integer
The dataset_name_length parameter is a pointer to an integer variable containing the number of bytes
of data returned in the dataset_name variable. The maximum returned length is 64 bytes.
dataset_name
Direction: Output Type: String
The dataset_name parameter is a pointer to a 64-byte string variable containing the name of the file
returned by the verb. The file contains the key-record information.
The verb returns the file name as a fully qualified file specification.
Note: When the verb stores a key-record-list file, it overlays any older file with the same name.
security_server_name
Direction: Output Type: String
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.
Restrictions
None
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDKRLJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDKRLJ are shown here.
Chapter8.Keystoragemechanisms 293

PKA Key Record List (CSNDKRL)
Format
public native void CSNDKRLJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_label,
hikmNativeInteger data_set_name_length,
byte[] data_set_name,
byte[] security_server_name );
294 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Record Read (CSNDKRR)
PKA Key Record Read (CSNDKRR)
Reads a record from the PKAkey storage file and returns the content of the record. This is true even
when the record contains a null PKAtoken.
PKAkey records are stored in the external key-storage file defined by the CSUPKADS environment
variable.
Format
CSNDKRR(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
label,
token_length,
token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type: String
This parameter is ignored.
label
Direction: Input Type: String
The label of the record to be read, a 64-byte character string.
token_length
Direction: Input/Output Type: Integer
The length of the area to which the record is to be returned. On successful completion of this verb,
token_length will contain the actual length of the record returned.
token
Direction: Output Type: String
Area into which the returned record will be written. The area should be at least as long as the record.
Restrictions
None
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Chapter8.Keystoragemechanisms 295

PKA Key Record Read (CSNDKRR)
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDKRRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDKRRJ are shown here.
Format
public native void CSNDKRRJ(
hikmNativeInteger return_code,
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 );
296 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Record Write (CSNDKRW)
PKA Key Record Write (CSNDKRW)
Writes over an existing record in the PKAkey storage file.
PKAkey records are stored in the external key-storage file defined by the CSUPKADS environment
variable.
Format
CSNDKRW(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
label,
token_length,
token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0 or 1.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left-justified in 8-byte fields and
padded on the right with blanks.All keywords must be in contiguous storage. The rule_array keywords
are described in Table70.
Table70.KeywordsforPKAKeyRecordWritecontrolinformation
Keyword Description
| Writemode(One,optional).Specifiesthecircumstancesunderwhichtherecordistobewritten.
CHECK SpecifiestherecordwillbewrittenonlyifarecordoftypeNULLwiththesamelabelexistsinthePKA
keystoragefile.Ifsucharecordexists,itisoverwritten.Thisisthedefaultcondition.
OVERLAY Specifiestherecordwillbeoverwrittenregardlessofthecurrentcontentoftherecord.Ifarecordwith
thesamelabelexistsinthePKAkeystoragefile,isoverwritten.
label
Direction: Input Type: String
The label of the record to be overwritten, a 64-byte character string.
token_length
Direction: Input Type: Integer
The length of the field containing the token to be written to the PKAkey storage file.
token
Chapter8.Keystoragemechanisms 297

PKA Key Record Write (CSNDKRW)
Direction: Input Type: String
The data to be written to the PKAkey storage file, which is an RSAprivate token in either external or
internal format, or an RSApublic token.
Restrictions
None
Required commands
| This verb requires the Key Test and Key Test2 command (offset X'001D') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDKRWJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDKRWJ are shown here.
Format
public native void CSNDKRWJ(
hikmNativeInteger return_code,
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 );
298 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Retained Key Delete (CSNDRKD)
Retained Key Delete (CSNDRKD)
Use this verb to delete a PKAkey-record currently retained within the cryptographic engine.
Both public and private keys can be retained within the cryptographic engine using verbs such as PKAKey
Generate and PKAPublic Key Register.Alist of retained keys can be obtained using the Retained Key
List verb.
IMPORTANT
Before using this verb, see the information about retained keys in “Using retained keys.”
Format
CSNDRKD(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type: String
| This parameter is ignored.
key_label
Direction: Input Type: String
Apointer to a string variable containing the key label of a PKAkey-record that has been retained
within the cryptographic engine. The use of a wild card in the key_label variable is not permitted.
Using retained keys
Retained key use is discouraged on the IBM System z platform because a retained key can exist only in
one CEX3C Cryptographic adapter, by definition.
v This has potential problems:
– The key cannot be exported, so it cannot be backed up.
– The key cannot be exported to another card in the same group, so operations concerning the
retained key cannot participate in load-balancing.
– There is an exception to the above points, in that keys generated in a deterministic fashion using
externally saved regeneration data (it is possible to save so-called 'regen data' securely) can be
recreated from that data or created in multiple cards across a card group.
Chapter8.Keystoragemechanisms 299

Retained Key Delete (CSNDRKD)
However, this is a very sophisticated topic, and is beyond the scope of this document.Also, the
complexity required to implement this properly, as well as the sophistication involved in its data
management, present formidable obstacles.
Retained key support is offered in this release, however. The following verbs work with retained keys:
v “PKAKey Generate (CSNDPKG)” on page 370 generates an RSAretained key. The same restrictions
that Integrated Cryptographic Service Facility (ICSF) has for retained key creation are implemented
here. These are:
– Notice that PKAKey Token Build will let you create 'key-mgmt' skeleton key tokens, and this is as
designed. You can still pass these to PKAKey Generate and have a key pair created. What is not
allowed is specifying that this 'key-mgmt' token is to be generated in PKAKey Generate as a
RETAIN key token: a retained key. Such an attempt will fail with error 12 reason code 3046.
– The maximum modulus size is 2048 bits.
– The usage flags are restricted to signature generation.
Specifically, key management usage for retained keys is not allowed because of the dangers of
losing your key encrypting key (kek) for important keys, when that kek exists only inside a single
adapter.
v “Retained Key List (CSNDRKL)” on page 301 lists the retained keys inside an adapter.
v “Retained Key Delete (CSNDRKD)” on page 299 deletes a retained key from adapter internal storage.
Restrictions
None
Required commands
| This verb requires the Retained Key Delete command (offset X'0203'') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDRKDJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDRKDJ are shown here.
Format
public native void CSNDRKDJ (
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_label );
300 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Retained Key List (CSNDRKL)
Retained Key List (CSNDRKL)
Use this verb to list the key labels of selected PKAkey 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 wild card
(*) 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 PKAkeys within the coprocessor, use the PKAKey Generate and the PKAPublic Key Register
verbs. To delete retained keys from the coprocessor, use the Retained Key Delete verb.
IMPORTANT
Before using this verb, see the information about retained keys in “Using retained keys” on page 299.
Format
CSNDRKL(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_label_mask,
retained_keys_count,
key_labels_count,
key_labels )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type:Array
| This parameter is ignored.
key_label_mask
Direction: Input Type: String
Apointer 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 wild card (*) to identify multiple key records retained within the
coprocessor.
retained_keys_count
Direction: Input/Output Type: Integer
Chapter8.Keystoragemechanisms 301

Retained Key List (CSNDRKL)
Apointer to an integer variable to receive the total number of retained-key records stored within the
coprocessor.
key_labels_count
Direction: Input/Output Type: Integer
Apointer 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
Direction: Output Type:Array
Apointer 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 PKAkey-record retained within
the coprocessor.
Restrictions
None
Required commands
| This verb requires the Retained Key List command (offset X'0230'') to be enabled in the active role.
Usage notes
None
Related information
See “Key storage with Linux for IBM System z, in contrast to z/OS for IBM System z” on page 263.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDRKLJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDRKLJ are shown here.
Format
public native void CSNDRKLJ (
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] key_label_mask,
hikmNativeInteger retained_keys_count,
hikmNativeInteger key_labels_count,
byte[] key_labels );
302 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 9. Financial services
The process of validating personal identities in a financial transaction system is called personal
authentication. The personal identification number (PIN) is the basis for verifying the identity of a customer
across financial industry networks. CCAprovides verbs to translate, verify, and generate PINs. You can
use the verbs to prevent unauthorized disclosures when organizations handle PINs.
The following verbs are described in this chapter:
v “Clear PIN Encrypt (CSNBCPE)” on page 312
v “Clear PIN Generate (CSNBPGN)” on page 315
v “Clear PIN GenerateAlternate (CSNBCPA)” on page 318
v “CVV Generate (CSNBCSG)” on page 322
v “CVV Verify (CSNBCSV)” on page 325
v “Encrypted PIN Generate (CSNBEPG)” on page 328
v “Encrypted PIN Translate (CSNBPTR)” on page 332
v “Encrypted PIN Verify (CSNBPVR)” on page 338
v “PIN Change/Unblock (CSNBPCU)” on page 342
v “Secure Messaging for Keys (CSNBSKY)” on page 348
v “Secure Messaging for PINs (CSNBSPN)” on page 351
v “Transaction Validation (CSNBTRV)” on page 355
How personal identification numbers (PINs) are used
Many people are familiar with PINs, which are used to access an automated teller machine (ATM). From
the system point of view, PINs are used primarily in financial networks to authenticate users. Typically, a
user is assigned a PIN and enters the PIN at automated teller machines (ATMs) to gain access to his or
her accounts. It is extremely important that the PIN be kept private so no one other than the account
owner can use it. CCAallows your applications to generate PINs, to verify supplied PINs, and to translate
PINs from one format or encryption key to another.
How VISA card verification values are used
The Visa International ServiceAssociation (VISA) and MasterCard International, Incorporated have
specified a cryptographic method to calculate a value that relates to the personal account number (PAN),
the card expiration date, and the service code. The VISAcard-verification value (CVV) and the MasterCard
card-verification code (CVC) can be encoded on either track 1 or track 2 of a magnetic striped card and
are used to detect forged cards. Because most online transactions use track-2, the CCAverbs generate
and verify the CVV2 by the track-2 method.
The VISACVV Generate verb calculates a 1-byte to 5-byte value through the DES-encryption of the PAN,
the card expiration date, and the service code using two data-encrypting keys or two MAC keys. The VISA
CVV Verify verb calculates the CVV by the same method, compares it to the CVV supplied by the
application (which reads the credit card's magnetic stripe) in the CVV_value, and issues a return code that
indicates whether the card is authentic.
2.TheVISACVVandtheMasterCardCVCrefertothesamevalue.CVVisusedheretomeanbothCVVandCVC.
©CopyrightIBMCorp.2007,2011 303

Translating data and PINs in networks
More and more data is being transmitted across networks where, for various reasons, the keys used on
one network cannot be used on another network. Encrypted data and PINs that are transmitted across
these boundaries must be “translated” securely from encryption under one key to encryption under another
key. For example, a traveler visiting a foreign city might want to use anATM to access an account at
home. The PIN entered at theATM might need to be encrypted at theATM and sent over one or more
financial networks to the traveler's home bank.At the home bank, the PIN must be verified before access
is allowed. On intermediate systems (between networks), applications can use the Encrypted PIN
Translate verb to re-encrypt a PIN block from one key to another. Running on CCA, such applications can
ensure that PINs never appear in the clear and that the PIN-encrypting keys are isolated on their own
networks.
Working with Europay-Mastercard-Visa Smart cards
|
| There are several verbs you can use in secure communications with Europay-Mastercard-Visa (EMV)
| smart cards. The processing capabilities are consistent with the specifications provided in these
| documents:
| v EMV 2000 Integrated Circuit Card Specification for Payment Systems Version 4.0 (EMV4.0) Book 2
| v Design Visa Integrated Circuit Card Specification Manual
| v Integrated Circuit Card Specification (VIS) 1.4.0 Corrections
| EMV smart cards include the following processing capabilities:
| v The Diversified Key Generate verb with rule-array options TDES-XOR, TDESEMV2, and TDESEMV4
| enables 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 enables secure incorporation of 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 enables secure incorporation of a PIN block into a message part.
| v PIN Change/Unblock verb enables encryption of a new PIN to send to a new EMV 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 PKAEncrypt enables validation of a digital signature created according to
| ISO 9796-2 standard by encrypting information that 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.
PIN verbs
You use the PIN verbs to generate, verify, and translate PINs. This section discusses the PIN verbs, as
well as the various PIN algorithms and PIN block formats supported by CCA. It also explains the use of
PIN-encrypting keys.
Generating a PIN
To generate personal identification numbers, call the Clear PIN Generate or Encrypted PIN Generate verb.
Using a PIN generation algorithm, data used in the algorithm, and the PIN generation key, the Clear PIN
Generate verb generates a clear PIN and a PIN verification value, or offset. Using a PIN generation
304 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

algorithm, data used in the algorithm, the PIN generation key, and an outbound PIN encrypting key, the
Encrypted PIN Generate verb generates and formats a PIN and encrypts the PIN block.
Encrypting a PIN
To format a PIN into a supported PIN block format and encrypt the PIN block, call the Clear PIN Encrypt
verb.
Generating a PIN validation value from an encrypted PIN block
To generate a clear VISAPIN validation value (PVV) from an encrypted PIN block, call the Clear PIN
GenerateAlternate verb. The PIN block can be encrypted under an input PIN-encrypting key (IPINENC) or
an output PIN encrypting key (OPINENC).
Verifying a PIN
To verify a supplied PIN, call the Encrypted PIN Verify verb. You supply the enciphered PIN, the
PIN-encrypting key that enciphers the PIN, and other data. You must also specify the PIN verification key
and PIN verification algorithm. The Encrypted PIN Verify verb generates a verification PIN. This verb
compares the two personal identification numbers and if they are the same, it verifies the supplied PIN.
Translating a PIN
To translate a PIN block format from one PIN-encrypting key to another or from one PIN block format to
another, call the Encrypted PIN Translate verb. You must identify the input PIN-encrypting key that
originally enciphered the PIN. You also need to specify the output PIN-encrypting key that you want the
verb to use to encipher the PIN. If you want to change the PIN block format, specify a different output PIN
block format from the input PIN block format.
Algorithms for generating and verifying a PIN
CCAsupports the following algorithms for generating and verifying personal identification numbers:
v IBM 3624 institution-assigned PIN
v IBM 3624 customer-selected PIN (through a PIN offset)
v IBM German Bank Pool PIN (verify through an institution key)
v VISAPIN through a VISAPIN validation value
v Interbank PIN
The algorithms are discussed in detail inAppendixE, “PIN formats and algorithms,” on page 477.
Using PINs on different systems
CCAallows you to translate different PIN block formats, which lets you use personal identification numbers
on different systems. CCAsupports the following formats:
v IBM 3624
v IBM 3621 (same as IBM 5906)
v IBM 4704 encrypting PINPAD format
v ISO 0 (same asANSI 9.8, VISA1, and ECI 1)
v ISO 1 (same as ECI 4)
v ISO 2
v VISA2
v VISA3
v VISA4
v ECI 2
Chapter9.Financialservices 305

v ECI 3
The algorithms are discussed in detail inAppendixE, “PIN formats and algorithms,” on page 477.
PIN-Encrypting keys
Aunique master key variant enciphers each type of key.
Note that the PIN block variant constant (PBVC) are not supported in this version of CCA.
Derived unique key per transaction algorithms
CCAsupportsANSI X9.24 derived unique key per transaction algorithms to generate PIN-encrypting keys
from user data. CCAsupports both single-length and double-length key generation. Keywords for
single-length and double-length key generation cannot be mixed.
Encrypted PIN Translate
The UKPTIPIN, IPKTOPIN, and UKPTBOTH keywords will cause the verb to generate single-length keys.
DUKPT-IP, DKPT-OP, and DUKPT-BH are the respective keywords to generate double-length keys. The
input_PIN_profile and output_PIN_profile parameters must supply the current key serial number when
these keywords are specified.
Encrypted PIN Verify
The UKPTIPIN keyword will cause the verb to verify single-length keys. DUKPT-IP is the keyword for
double-length key generation. The input_PIN_profile parameter must supply the current key serial number
when these keywords are specified.
ANSI X9.8 PIN restrictions
|
| Three new access control points have been added to implement the PIN-block processing restrictions of
| theANSI X9.8 standard implemented in CCA4.1.0. These access control points are available on the IBM
| z196 with the CEX3C feature. These access control points are disabled in the default role.ATKE
| Workstation is required to enable them.
| These are the three new access control points:
| v ANSI X9.8 PIN - Enforce PIN block restrictions (X'0350')
| v ANSI X9.8 PIN -Allow modification of PAN_01_0350 (X'0351')
| v ANSI X9.8 PIN -Allow onlyANSI PIN blocks_01_0350 (X'0352')
| These verbs are affected by the new access control points:
| v Clear PIN GenerateAlternate (CSNBCPA)
| v Encrypted PIN Translate (CSNBPTR)
| v Secure Messaging for PINs (CSNBSPN)
ANSI X9.8 PIN - Enforce PIN block restrictions
|
| WhenANSI X9.8 PIN - Enforce PIN block restrictions access control point is enable, the following
| restrictions will be enforced:
| v The Encrypted PIN Translate and Secure Messaging for PINs verbs will not accept IBM 3624 PIN
| format in the output profile parameter when the input profile parameter is not IBM 3624.
| v The Encrypted PIN Translate verb will not accept ISO-0 or ISO-3 formats in the input PIN profile unless
| ISO-0 or ISO-3 is in the output PIN profile.
| v The Encrypted PIN Translate and Secure Messaging for PINs verbs will not accept ISO-1 or ISO-2
| formats in the output profile parameter when the input profile parameter contains ISO-0, ISO-3, or
| VISA4.
306 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| v When the input profile parameter for the Encrypted PIN Translate and Secure Messaging for PINs verbs
| contains either ISO-0 or ISO-3 formats, the PAN within the decrypted PIN block will be extracted. This
| PAN must be the same as the PAN that was supplied as the input PAN parameter, and this PAN must
| be the same as the PAN supplied as the output PAN parameter.
| v The input PAN and output PAN parameters for the Encrypted PIN Translate and Secure Messaging for
| PINs verbs must be equivalent.
| v When the rule array for the Clear PIN GenerateAlternate verb contains VISA-PVV, the input PIN profile
| must contain ISO-0 or ISO-3 formats.
ANSI X9.8 PIN - Allow modification of PAN
|
| In order to enable theANSI X9.8 PIN -Allow modification of PAN access control point, theANSI X9.8 PIN
| - Enforce PIN block restrictions must also be enabled. TheANSI X9.8 PIN -Allow modification of PAN
| access control point cannot be enabled by itself.
| When theANSI X9.8 PIN -Allow modification of PAN access control point is enabled, the input PAN and
| output PAN parameters will be tested in the Encrypted PIN Translate and Secure Messaging for PINs
| verbs. The input PAN will be compared to the portions of the PAN that are recoverable from the decrypted
| PIN block. If the PANs are the same, the account number will be changed in the output PIN block.
ANSI X9.8 PIN - Allow only ANSI PIN blocks
|
| In order to enable theANSI X9.8 PIN -Allow onlyANSI PIN blocks access control point, theANSI X9.8
| PIN - Enforce PIN block restrictions must also be enabled. TheANSI X9.8 PIN -Allow onlyANSI PIN
| blocks access control point cannot be enabled by itself.
| When this access control point is enabled, the Encrypted PIN Translate verb will allow reformatting of the
| PIN block as shown in Table71.
|| Table71.ANSIX9.8PIN-AllowonlyANSIPINblocks
|||| Reformatto: ISOFormat0 ISOFormat1 ISOFormat3
| Reformatfrom:
|||| ISOFormat0 Reformatpermitted.ChangeofPAN Notpermitted Reformatpermitted.ChangeofPAN
|| notpermitted notpermitted.
|||| ISOFormat1 Reformatpermitted Reformat Reformatpermitted
| permitted
|||| ISOFormat3 Reformatpermitted.ChangeofPAN Notpermitted Reformatpermitted.ChangeofPAN
|| notpermitted. notpermitted.
|
|
The PIN profile
The PIN profile consists of the following:
v PIN block format (see “PIN block format” on page 308)
v Format control (see “Format control” on page 309)
v Pad digit (see “Pad digit” on page 310)
v Current Key Serial Number (for UKPT and DUKPT – see “Current key serial number” on page 310)
Table72 shows the format of a PIN profile.
Table72.FormatofaPINprofile
Bytes Description
0-7 PINblockformat
8-15 Formatcontrol
Chapter9.Financialservices 307

Table72.FormatofaPINprofile (continued)
Bytes Description
16-23 Paddigit
24-47 CurrentKeySerialNumber(forUKPTandDUKPT)
PIN block format
This keyword specifies the format of the PIN block. The 8-byte value must be left-justified and padded with
blanks. Refer to Table73 for a list of valid values.
Table73.FormatvaluesofPINblocks
FormatValue Description
ECI-2 EurochequeInternationalformat2
ECI-3 EurochequeInternationalformat3
ISO-0 ISOformat0,ANSIX9.8,VISA1,andECI1
ISO-1 ISOformat1andECI4
ISO-2 ISOformat2
ISO-3 ISOformat3
VISA-2 VISAformat2
VISA-3 VISAformat3
VISA-4 VISAformat4
3621 IBM3621and5906
3624 IBM3624
4704-EPP IBM4704encryptingPINpad
PIN block format and PIN extraction method keywords
In the Clear PIN GenerateAlternate, Encrypted PIN Translate, and Encrypted PIN Verify verbs, you can
specify a PIN extraction keyword for a given PIN block format. In the table below, the allowable PIN
extraction methods are listed for each PIN block format. The first PIN extraction method keyword listed for
a PIN block format is the default. Refer to Table74 for a list of valid values.
Table74.PINblockformatandPINextractionmethodkeywords
PINblock PINextraction Description
Format methodkeywords
ECI-2 PINLEN04 ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINLEN04format.
ECI-3 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
ISO-0 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
ISO-1 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
ISO-2 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
ISO-3 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
VISA-2 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
308 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table74.PINblockformatandPINextractionmethodkeywords (continued)
PINblock PINextraction Description
Format methodkeywords
VISA-3 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
VISA-4 PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
3621 PADDIGIT, ThePINextractionmethodkeywordsspecifyaPINextractionmethodforan
HEXDIGIT, IBM3621PINblockformat.Thefirstkeyword,PADDIGIT,isthedefaultPIN
PINLEN04to extractionmethodforthePINblockformat.
PINLEN12,
PADEXIST
3624 PADDIGIT, ThePINextractionmethodkeywordsspecifyaPINextractionmethodforan
HEXDIGIT, IBM3624PINblockformat.Thefirstkeyword,PADDIGIT,isthedefaultPIN
PINLEN04to extractionmethodforthePINblockformat.
PINLEN16,
PADEXIST
4704-EPP PINBLOCK ThePINextractionmethodkeywordsspecifyaPINextractionmethodfora
PINBLOCKformat.
| Enhanced PIN security mode
| An enhanced PIN security mode is available. This optional mode is selected by enabling the PTR
| Enhanced PIN Security (offset X'0313') access control point in the CEX2C or CEX3C default role. When
| active, this control point affects all PIN verbs that extract or format a PIN using a PIN-block format of
| 3621or 3624 with a PIN-extraction method of PADDIGIT.
| Table75 summarizes the verbs affected by the enhanced PIN security mode, and describes the effect that
| the mode has when the access control point is enabled.
|| Table75.VerbsaffectedbyenhancedPINsecuritymode
|| PIN-blockformatand PINprocessingchangeswhenEnhancedPIN
||| PIN-extractionmethod Affectedverbs SecurityModeenabled
||| ECI-2,3621,or3624 Clear PIN Generate Alternate ThePINLENnnkeywordintherule_arrayparameterfor
||| formatsANDPINLENnn Encrypted PIN Translate PINextractionmethodisnotallowediftheEnhanced
|| Encrypted PIN Verify PINSecurityModeisenabled.
| Note: Theverbwillfailwithreturncode8andreason
| codeX'7E0'.
||| 3621or3624format Clear PIN Generate Alternate PINextractiondeterminesthePINlengthbyscanning
||| andPADDIGIT Encrypted PIN Translate fromrighttoleftuntiladigit,notequaltothePADdigit,
|| Encrypted PIN Verify isfound.TheminimumPINlengthissetatfourdigits,so
|| PIN Change/Unblock scanningceasesonedigitpastthepositionofthefourth
| PINdigitintheblock.
||| 3621or3624format Clear PIN Encrypt PINformattingdoesnotexaminethePIN,intheoutput
||| andPADDIGIT Encrypted PIN Generate PINblock,toseeifitcontainsthePADdigit.
| Encrypted PIN Translate
||| 3621or3624format EncryptedPINTranslate Restrictedtonon-decimaldigitforPADdigit.
| andPADDIGIT
|
Format control
|
This keyword specifies whether there is any control on the user-supplied PIN format. The 8-byte value
must be left-justified and padded with blanks. The only permitted value is NONE, which indicates no
format control will be used.
Chapter9.Financialservices 309

Pad digit
Some PIN formats require the pad digit parameter. If the PIN format does not need a pad digit, the verb
ignores this parameter. Table76 shows the format of a pad digit. The PIN profile pad digit must be
specified in upper case.
Table76.Formatofapaddigit
Bytes Description
16-22 Sevenspacecharacters
23 Characterrepresentationofahexadecimalpaddigitoraspaceifapaddigitisnotneeded.Characters
mustbeoneofthefollowing:digits0-9,lettersA-F,orablank.
Each PIN format supports only a pad digit in a certain range. Table77 lists the valid pad digits for each
PIN block format.
Table77.PaddigitsforPINblockformats
PINBlockFormat OutputPINProfile InputPINProfile
ECI-2 Paddigitisnotused Paddigitisnotused
ECI-3 Paddigitisnotused Paddigitisnotused
ISO-0 F Paddigitisnotused
ISO-1 Paddigitisnotused Paddigitisnotused
ISO-2 Paddigitisnotused Paddigitisnotused
ISO-3 Paddigitisnotused Paddigitisnotused
VISA-2 0-9 Paddigitisnotused
VISA-3 0-F Paddigitisnotused
VISA-4 F Paddigitisnotused
3621 0-F 0-F
3624 0-F 0-F
4704-EPP F Paddigitisnotused
| The verb returns an error indicating that the PAD digit is not valid if all of these conditions are met:
| v The PTR Enhanced PIN Security (offset X'0313') access control point is enabled in the active role.
| v The output PIN profile specifies 3621 or 3624 as the PIN-block format.
| v The output PIN profile specifies a decimal digit (0 - 9) as the PAD digit.
Recommendations for the pad digit
IBM recommends you use a non-decimal pad digit in the range ofA- F when processing IBM 3624 and
IBM 3621 PIN blocks. If you use a decimal pad digit, the creator of the PIN block must ensure that the
calculated PIN does not contain the pad digit, or unpredictable results might occur.
For example, you can exclude a specific decimal digit from being in any calculated PIN by using the IBM
3624 calculation procedure and by specifying a decimalization table that does not contain the desired
decimal pad digit.
Current key serial number
The current key serial number is the concatenation of the initial key serial number (a 59-bit value) and the
encryption counter (a 21-bit value). The concatenation is an 80-bit (10-byte) value. Table78 on page 311
shows the format of the current key serial number.
310 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

When UKPT or DUKPT is specified, the PIN profile parameter is extended to a 48-byte field and must
contain the current key serial number.
Table78.FormatoftheCurrentKeySerialNumberField
Bytes Description
24-47 CharacterrepresentationofthecurrentkeyserialnumberusedtoderivetheinitialPINencryptingkey.It
isleftjustifiedandpaddedwith4blanks.
Chapter9.Financialservices 311

Clear PIN Encrypt (CSNBCPE)
Clear PIN Encrypt (CSNBCPE)
The Clear PIN Encrypt verb formats a PIN into one of the following PIN block formats and encrypts the
results. You can use this verb to create an encrypted PIN block for transmission. With the RANDOM
keyword, you can have the verb generate random PIN numbers.
Note: Aclear PIN is a sensitive piece of information. Ensure your application program and system design
provide adequate protection for any clear PIN value.
v IBM 3621 format
v IBM 3624 format
v ISO-0 format (same as theANSI X9.8, VISA-1, and ECI formats)
v ISO-1 format (same as the ECI-4 format)
v ISO-2 format
v ISO-3 format
v IBM 4704 encrypting PINPAD (4704-EPP) format
v VISA2 format
v VISA3 format
v VISA4 format
v ECI2 format
v ECI3 format
Format
CSNBCPE(
return_code,
reason_code,
exit_data_length,
exit_data,
PIN_encrypting_key_identifier,
rule_array_count,
rule_array,
clear_PIN,
PIN_profile,
PAN_data,
sequence_number
encrypted_PIN_block )
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 14.
PIN_encrypting_key_identifier
Direction: Input/Output Type: String
The 64-byte string containing an internal key token or a key label of an internal key token. The internal
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 usage bit set to 1.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. Valid
values are 0, 1, and 2.
rule_array
312 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Clear PIN Encrypt (CSNBCPE)
Direction: Input Type: String
Keywords that provide control information to the verb. The keyword is left-justified in an 8-byte field
and padded on the right with blanks.All keywords must be in contiguous storage. The rule_array
keywords are described in Table79
Table79.KeywordsforClearPINEncryptcontrolinformation
Keyword Description
| ProcessRule(Optional)
ENCRYPT Thisisthedefault.Useofthiskeywordisoptional.
RANDOM CausestheverbtogeneratearandomPINvalue.ThelengthofthePINisbasedonthevaluein
theclear_PINvariable.SetthevalueoftheclearPINtozeroanduseasmanydigitsasthe
desiredrandomPIN;padtheremainderoftheclearPINvariablewithspacecharacters.
clear_PIN
Direction: Input Type: String
A16-character string with the clear PIN. The value in this variable must be left-justified and padded on
the right with space characters.
PIN_profile
Direction: Input Type: String
A24-byte string containing three 8-byte elements with a PIN block format keyword, the format control
keyword, NONE, and a pad digit as required by certain formats. See “The PIN profile” on page 307 for
additional information.
PAN_data
Direction: Input Type: String
A12-byte PAN in character format. The verb uses this parameter if the PIN profile specifies the ISO-0,
ISO-3 or VISA-4 keyword for the PIN block format. Otherwise, ensure this parameter is a 12-byte
variable in application storage. The information in this variable will be ignored, but the variable must be
specified.
Note: When using the ISO-0 or ISO-3 keyword, use the 12 rightmost digits of the PAN data, excluding
the check digit. When using the VISA-4 keyword, use the 12 leftmost digits of the PAN data,
excluding the check digit.
sequence_number
Direction: Input Type: Integer
The 4-byte character integer. The verb currently ignores the value in this variable. For future
compatibility, the suggested value is 99999.
encrypted_PIN_block
Direction: Output Type: String
The field that receives the 8-byte encrypted PIN block.
Restrictions
The format control specified in the PIN profile must be NONE.
Required commands
| This verb requires the Clear PIN Encrypt command (offset X'00AF') to be enabled in the active role.
Chapter9.Financialservices 313

Clear PIN Encrypt (CSNBCPE)
| 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 PTR Enhanced PIN
| Security command (offset X'0313') in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCPEJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCPEJ are shown here.
Format
public native void CSNBCPEJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
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
);
314 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Clear PIN Generate (CSNBPGN)
Clear PIN Generate (CSNBPGN)
Use the Clear PIN Generate verb to generate a clear PIN, a PIN validation value (PVV), or an offset
according to an algorithm. You supply the algorithm or process rule using the rule_array parameter.
v IBM 3624 (IBM-PIN or IBM-PINO)
v VISAPIN validation value (VISA-PVV)
v Interbank PIN (INBK-PIN)
For guidance information about VISA, see their appropriate publications.
Format
CSNBPGN(
return_code,
reason_code,
exit_data_length,
exit_data,
PIN_generating_key_identifier,
rule_array_count,
rule_array,
PIN_length,
PIN_check_length,
data_array,
returned_result )
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 14.
PIN_generating_key_identifier
Direction: Input/Output Type: String
The 64-byte key label or internal key token that identifies the PIN generation (PINGEN) key.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
The process rule provides control information to the verb. The keyword is left-justified in an 8-byte field
and padded on the right with blanks. The rule_array keyword is described in Table80.
Table80.KeywordsforClearPINGeneratecontrolinformation
Keyword Description
| ProcessRule(One,required)
GBP-PIN TheIBMGermanBankPoolPIN,whichusestheinstitutionPINGENkeytogenerateaninstitution
PIN(IPIN).
IBM-PIN TheIBM3624PIN,whichisaninstitution-assignedPIN.ItdoesnotcalculatethePINoffset.
IBM-PINO TheIBM3624PINoffset,whichisacustomer-selectedPINandcalculatesthePINoffset(the
output).
INBK-PIN TheInterbankPINthatisgenerated.
Chapter9.Financialservices 315

Clear PIN Generate (CSNBPGN)
Table80.KeywordsforClearPINGeneratecontrolinformation (continued)
Keyword Description
VISA-PVV TheVISAPINvalidationvalue.InputisthecustomerPIN.
PIN_length
Direction: Input Type: Integer
The length of the PIN used for the IBM algorithms only, IBM-PIN or IBM-PINO. Otherwise, this
parameter is ignored. Specify an integer from 4 - 16.
PIN_check_length
Direction: Input Type: Integer
The length of the PIN offset used for the IBM-PINO process rule only. Otherwise, this parameter is
ignored. Specify an integer from 4 - 16.
Note: The PIN check length must be less than or equal to the integer specified in the PIN_length
parameter.
data_array
Direction: Input Type: String
Three 16-byte data elements required by the corresponding rule_array parameter. The data array
consists of three 16-byte fields or elements whose specification depends on the process rule. If a
process rule only requires one or two 16-byte fields, the rest of the data array is ignored by the verb.
Table81 describes the array elements.
Table81.ArrayelementsfortheClearPINGenerateverb
ArrayElement Description
Clear_PIN ClearuserselectedPINof4-12digitsof0-9.Left-justifiedandpaddedwithspaces.For
IBM-PINO,thisistheclearcustomerPIN(CSPIN).
Decimalization_table DecimalizationtableforIBMandGBPonly.Sixteendigitsof0-9.
Trans_sec_parm ForVISAonly,theleftmostsixteendigits.Elevendigitsofthepersonalaccountnumber
(PAN).Onedigitkeyindex.FourdigitsofcustomerselectedPIN.
ForInterbankonly,sixteendigits.Elevenrightmostdigitsofthepersonalaccountnumber
(PAN).Aconstantof6.Onedigitkeyselectorindex.ThreedigitsofPINvalidationdata.
Validation_data ValidationdataforIBMandIBMGermanBankPoolpaddedto16bytes.Onetosixteen
charactersofhexadecimalaccountdataleft-justifiedandpaddedontherightwithblanks.
Table82 lists the data array elements required by the process rule (rule_array parameter). The
numbers refer to the process rule's position within the array.
Table82.ArrayelementsforClearPINGenerate
ProcessRule IBM-PIN IBM-PINO GBP-PIN GBP-PINO VISA-PVV INBK-PIN
Decimalization_table 1 1 1 1
Validation_data 2 2 2 2
Clear_PIN 3 3
Trans_sec_parm 1 1
Note: Generate offset for GBP algorithm is equivalent to IBM offset generation with PIN_check_length
of 4 and PIN_length of 6.
returned_result
316 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Clear PIN Generate (CSNBPGN)
Direction: Output Type: String
The 16-byte generated output, left-justified, and padded on the right with blanks.
Restrictions
None
Required commands
| This verb requires the Clear PIN Generate - 3624 command (offset X'00A0') to be enabled in the active
| role.
Usage notes
If you are using the IBM 3624 PIN and IBM German Bank Pool PIN algorithms, you can supply an
unencrypted customer selected PIN to generate a PIN offset.
Related information
The algorithms are discussed in detail inAppendixE, “PIN formats and algorithms,” on page 477.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBPGNJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBPGNJ are shown here.
Format
public native void CSNBPGNJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
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
);
Chapter9.Financialservices 317

Clear PIN Generate Alternate (CSNBCPA)
Clear PIN Generate Alternate (CSNBCPA)
Use the Clear PIN GenerateAlternate verb to generate a clear VISAPVV (PIN validation value) from an
input encrypted PIN block or to produce a 3624 offset from a customer-selected encrypted PIN. The PIN
block can be encrypted under either an input PIN-encrypting key (IPINENC) or an output PIN-encrypting
key (OPINENC).
Format
CSNBCPA(
return_code,
reason_code,
exit_data_length,
exit_data,
PIN_encryption_key_identifier,
PIN_generation_key_identifier,
PIN_profile,
PAN_data,
encrypted_PIN_block,
rule_array_count,
rule_array,
PIN_check_length,
data_array,
returned_PVV )
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 14.
PIN_encryption_key_identifier
Direction: Input/Output Type: String
A64-byte string consisting of an internal token that contains an IPINENC or OPINENC key or the label
of an IPINENC or OPINENC key that is used to encrypt the PIN block. If you specify a label, it must
resolve uniquely to either an IPINENC or OPINENC key.
PIN_generation_key_identifier
Direction: Input/Output Type: String
A64-byte string that consists of an internal token that contains a PIN generation (PINGEN) key or the
label of a PINGEN key.
PIN_profile
Direction: Input Type: String
The three 8-byte character elements that contain information necessary to extract a PIN from a
formatted PIN block. The pad digit is needed to extract the PIN from a 3624 or 3621 PIN block in the
Clear PIN GenerateAlternate verb. See “The PIN profile” on page 307 for additional information.
PAN_data
Direction: Input Type: String
A12-byte field that contains 12 characters of PAN data. The personal account number recovers the
PIN from the PIN block if the PIN profile specifies ISO-0 or VISA-4 block formats. Otherwise it is
ignored, but you must specify this parameter.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit. For VISA-4, use
the leftmost 12 digits of the PAN, excluding the check digit.
encrypted_PIN_block
318 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Clear PIN Generate Alternate (CSNBCPA)
Direction: Input Type: String
An 8-byte field that contains the encrypted PIN that is input to the VISAPVV generation algorithm. The
verb uses the IPINENC or OPINENC key that is specified in the PIN_encryption_key_identifier
parameter to encrypt the block.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1 or 2. If the default extraction method for a PIN block format is desired, specify the
rule_array_count value as 1.
rule_array
Direction: Input Type: String
The process rule for the PIN generation algorithm. Specify IBM-PINO or VISA-PVV (the VISAPIN
verification value) in an 8-byte field, left-justified, and padded with blanks. The rule_array points to an
array of one or two 8-byte elements. The rule_array keywords are described in Table83.
|| Table83.KeywordsforClearPINGenerateAlternatecontrolinformation
|| Keyword Description
| PINcalculationmethod(Onerequired)
|| IBM-PINO ThiskeywordspecifiesuseoftheIBM3624PINOffsetcalculationmethod.
|| VISA-PVV ThiskeywordspecifiesuseoftheVISAPVVcalculationmethod.
| PINextractionmethod(Oneoptional)Seethetextfollowingthistable.
|
| If the PIN extraction method is provided, one of the PIN extraction method keywords shown in
| Table74 on page 308 can be specified for the given PIN block format. See “PIN block format and PIN
| extraction method keywords” on page 308 for additional information. If the default extraction method
| for a PIN block format is desired, specify the rule_array_count value as 1.
The PIN extraction methods operate as follows:
PINBLOCK
Specifies that the verb use one of the following:
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
Specifies that the verb use the pad value in the PIN profile to identify the end of the PIN.
HEXDIGIT
Specifies that the verb 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.
PINLENnn
Specifies that the verb use the length specified in the keyword, where nn can range from 04 -
16, to identify the PIN.
| The PINLENnn keywords are disabled for this verb by default. If these keywords are used,
| return code 8 with reason code 33 is returned. To enable them, the PTR Enhanced PIN
| Security command (bit X'0313') must be enabled using a TKE.
PADEXIST
Specifies that the verb use the character in the 16th position of the PIN block as the value of
the pad value.
PIN_check_length
Chapter9.Financialservices 319

Clear PIN Generate Alternate (CSNBCPA)
Direction: Input Type: Integer
The length of the PIN offset used only for the IBM-PINO process rule. Otherwise, this parameter is
ignored. Specify an integer from 4 - 16.
Note: The PIN check length must be less than or equal to the integer specified in the PIN_length
parameter.
data_array
Direction: Input Type: String
Three 16-byte elements. Table84 describes the format when IBM-PINO is specified. Table85
describes the format when VISA-PVV is specified.
Table84.ArrayelementsforClearPINGenerateAlternate,data_array(IBM-PINO)
Arrayelement Description
decimalization_table Thiselementcontainsthedecimalizationtableof16characters(0-9)thatareusedto
converthexadecimaldigits(X'0'-X'F')oftheencipheredvalidationdatatothedecimal
digits(X'0'-X'9').
validation_data Thiselementcontains1-16charactersofaccountdata.Thedatamustbeleftjustified
andpaddedontherightwithspacecharacters.
Reserved-3 Thisfieldisignored,butyoumustspecifyit.
Table85.ArrayelementsforClearPINGenerateAlternate,data_array(VISA-PVV)
Arrayelement Description
Trans_sec_parm ForVISA-PVVonly,theleftmosttwelvedigits.Elevendigitsofthepersonalaccount
number(PAN).Onedigitkeyindex.Therestofthefieldisignored.
Reserved-2 Thisfieldisignored,butyoumustspecifyit.
Reserved-3 Thisfieldisignored,butyoumustspecifyit.
returned_PVV
Direction: Output Type: Character
A16-byte area that contains the 4-byte PVV left-justified and padded with blanks.
Restrictions
None
Required commands
This 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 method:
||||
Rule-arraykeyword Offset Command
||| IBM-PINO X'00A4' ClearPINGenerateAlternate-3624Offset
||| VISA-PVV X'00BB' ClearPINGenerateAlternate-VISAPVV
|
| An enhanced PIN security mode, on the CEX2C, or CEX3C is available for extracting PINs from encrypted
| PIN blocks. This mode only applies when specifying a PIN-extraction method for an IBM 3621 or an IBM
| 3624 PIN-block. To do this, you must enable the PTR Enhanced PIN Security (offset X'0313') access
| control point in the default role. When activated, this mode limits checking of the PIN to decimal digits and
| a PIN length minimum of 4 is enforced. No other PIN-block consistency checking will occur.
320 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Clear PIN Generate Alternate (CSNBCPA)
| An enhanced PIN security mode on a CEX3C is available beginning with Release 4.1.0, to implement
| restrictions required by theANSI X9.8 PIN standard. The restrictions are to accept only a PIN_profile
| variable that contains a PIN-block format of ISO-0 or ISO-3. To enforce these restrictions, you must enable
| the following access control points in the default role:
| v ANSI X9.8 PIN - Enforce PIN block restrictions (X'0350')
| For more information, see “ANSI X9.8 PIN restrictions” on page 306.
| Note: Arole with offset X'0350' enabled also affects access control of the Encrypted PIN Translate and
| the Secure Messaging for PINs verbs.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCPAJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCPAJ are shown here.
Format
public native void CSNBCPAJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
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 );
Chapter9.Financialservices 321

CVV Generate (CSNBCSG)
CVV Generate (CSNBCSG)
Use the CVV Generate verb to generate a VISACard Verification Value (CVV) or MasterCard Card
Verification Code (CVC) as defined for track 2. This verb generates a CVV that is based on the information
that the PAN_data, the expiration_date, and the service_code parameters provide. This verb uses the
Key-Aand the Key-B keys to cryptographically process this information. Key-Aand Key-B can be
single-length DATAor MAC keys. If the requested CVV is shorter than 5 characters, the CVV is padded on
the right by space characters. The CVV is returned in the 5-byte variable that the CVV_value parameter
identifies. When you verify a CVV, compare the result to the value that the CVV_value supplies.
Format
CSNBCSG(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
PAN_data,
expiration_date,
service_code,
CVV_key_A_Identifier,
CVV_key_B_Identifier,
CVV_value )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0, 1, or 2.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left-justified in 8-byte fields and
padded on the right with blanks.All keywords must be in contiguous storage. The rule_array keywords
are described in Table86.
Table86.KeywordsforCVVGeneratecontrolinformation
Keyword Description
| PANdatalength(One,optional)
PAN-13 SpecifiesthatthelengthofthePANdatais13bytes.PAN-13isthedefaultvalue.
PAN-14 SpecifiesthatthelengthofthePANdatais14bytes.
PAN-15 SpecifiesthatthelengthofthePANdatais15bytes.
PAN-16 SpecifiesthatthelengthofthePANdatais16bytes.
PAN-17 SpecifiesthatthelengthofthePANdatais17bytes.
PAN-18 SpecifiesthatthelengthofthePANdatais18bytes.
PAN-19 SpecifiesthatthelengthofthePANdatais19bytes.
| CVVlength(One,optional)
322 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CVV Generate (CSNBCSG)
Table86.KeywordsforCVVGeneratecontrolinformation (continued)
Keyword Description
CVV-1 SpecifiesthattheCVVistobecomputedasonebyte,followedbyfourblanks.CVV-1isthedefault
value.
CVV-2 SpecifiesthattheCVVistobecomputedastwobytes,followedbythreeblanks.
CVV-3 SpecifiesthattheCVVistobecomputedasthreebytes,followedbytwoblanks.
CVV-4 SpecifiesthattheCVVistobecomputedasfourbytes,followedbyoneblank.
CVV-5 SpecifiesthattheCVVistobecomputedasfivebytes.
PAN_data
Direction: Input Type: String
The PAN_data parameter specifies an address that points to the place in application data storage that
contains personal account number (PAN) information in character form. The PAN is the account
number as defined for the track-2 magnetic-stripe standards. If the PAN-nn keyword is specified in the
rule_array, where nn is a value between 13 and 19, then nn number of characters are processed.
If you specify the PAN-nn keyword in the rule_array where nn is less than 16, the server might copy
16 bytes to a work area. Therefore, ensure that the verb can address 16 bytes of storage.
expiration_date
Direction: Input Type: String
The expiration_date parameter specifies an address that points to the place in application data storage
that contains the card expiration date in numeric character form in a 4-byte field. The application
programmer must determine whether the CVV will be calculated with the date form of YYMM or
MMYY.
service_code
Direction: Input Type: String
The service_code parameter specifies an address that points to the place in application data storage
that contains the service code in numeric character form in a 3-byte field. The service code is the
number that the track-2 magnetic-stripe standards define. The service code of '000' is supported.
CVV_key_A_Identifier
Direction: Input/Output Type: String
The CVV_key_A_Identifier parameter specifies an address that contains a 64-byte internal key token
or a key label of a single-length DATAor MAC key that decrypts information in the CCV process. The
internal key token contains the Key-Akey that encrypts information in the CVV process.
CVV_key_B_Identifier
Direction: Input/Output Type: String
The CVV_key_B_Identifier parameter specifies an address that contains a 64-byte internal key token
or a key label of a single-length DATAor MAC key that decrypts information in the CCV process. The
internal key token contains the Key-B key that decrypts information in the CVV process.
CVV_value
Direction: Output Type: String
The CVV_value parameter specifies an address that points to the place in application data storage
that will be used to store the computed 5-byte character output value.
Chapter9.Financialservices 323

CVV Generate (CSNBCSG)
Restrictions
None
Required commands
This verb requires the Generate CVV command (offset X'00DF') to be enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCSGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCSGJ are shown here.
Format
public native void CSNBCSGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] PAN_data,
byte[] expiration_date,
byte[] service_code,
byte[] key_a_id,
byte[] key_b_id,
byte[] generated_cvv);
324 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CVV Verify (CSNBCSV)
CVV Verify (CSNBCSV)
Use the CVV Verify verb to verify a VISACard Verification Value (CVV) or MasterCard Card Verification
Code (CVC) as defined for track 2. This verb generates a CVV based on the information the PAN_data,
the expiration_date, and the service_code parameters provide. This verb uses the Key-Aand the Key-B
keys to cryptographically process this information. If the requested CVV is shorter than 5 characters, the
CVV is padded on the right by space characters. The generated CVV is then compared to the value that
the CVV_value supplies for verification.
Format
CSNBCSV(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
PAN_data,
expiration_date,
service_code,
CVV_key_A_Identifier,
CVV_key_B_Identifier,
CVV_value )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0, 1, or 2.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left-justified in 8-byte fields and
padded on the right with blanks.All keywords must be in contiguous storage. The rule_array keywords
are described in Table87.
Table87.KeywordsforCVVVerifycontrolinformation
Keyword Description
| PANdatalength(One,optional)
PAN-13 SpecifiesthatthelengthofthePANdatais13bytes.PAN-13isthedefaultvalue.
PAN-14 SpecifiesthatthelengthofthePANdatais14bytes.
PAN-15 SpecifiesthatthelengthofthePANdatais15bytes.
PAN-16 SpecifiesthatthelengthofthePANdatais16bytes.
PAN-17 SpecifiesthatthelengthofthePANdatais17bytes.
PAN-18 SpecifiesthatthelengthofthePANdatais18bytes.
PAN-19 SpecifiesthatthelengthofthePANdatais19bytes.
| CVVlength(One,optional)
Chapter9.Financialservices 325

CVV Verify (CSNBCSV)
Table87.KeywordsforCVVVerifycontrolinformation (continued)
Keyword Description
CVV-1 SpecifiesthattheCVVistobecomputedasonebyte,followedbyfourblanks.CVV-1isthedefault
value.
CVV-2 SpecifiesthattheCVVistobecomputedastwobytes,followedbythreeblanks.
CVV-3 SpecifiesthattheCVVistobecomputedasthreebytes,followedbytwoblanks.
CVV-4 SpecifiesthattheCVVistobecomputedasfourbytes,followedbyoneblank.
CVV-5 SpecifiesthattheCVVistobecomputedasfivebytes.
PAN_data
Direction: Input Type: String
The PAN_data parameter specifies an address that points to the place in application data storage that
contains personal account number (PAN) information in character form. The PAN is the account
number as defined for the track-2 magnetic-stripe standards. If the PAN-nn keyword is specified in the
rule_array, where nn is a value between 13 and 19, then nn number of characters are processed.
If you specify the PAN-nn keyword in the rule_array where nn is less than 16, the server might copy
16 bytes to a work area. Therefore, ensure that the verb can address 16 bytes of storage.
expiration_date
Direction: Input Type: String
The expiration_date parameter specifies an address that points to the place in application data storage
that contains the card expiration date in numeric character form in a 4-byte field. The application
programmer must determine whether the CVV will be calculated with the date form of YYMM or
MMYY.
service_code
Direction: Input Type: String
The service_code parameter specifies an address that points to the place in application data storage
that contains the service code in numeric character form in a 3-byte field. The service code is the
number that the track-2 magnetic-stripe standards define. The service code of '000' is supported.
CVV_key_A_Identifier
Direction: Input/Output Type: String
The CVV_key_A_Identifier parameter specifies an address that contains a 64-byte internal key token
or a key label of a single-length DATA, MAC, or MACVER key that decrypts information in the CCV
process. The internal key token contains the Key-Akey that encrypts information in the CVV process.
CVV_key_B_Identifier
Direction: Input/Output Type: String
The CVV_key_B_Identifier parameter specifies an address that contains a 64-byte internal key token
or a key label of a single-length DATA, MAC, or MACVER key that decrypts information in the CCV
process. The internal key token contains the Key-B key that decrypts information in the CVV process.
CVV_value
Direction: Input Type: String
The CVV_value parameter specifies an address that contains the CVV value which will be compared
to the computed CVV value. This is a 5-byte field.
326 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CVV Verify (CSNBCSV)
Restrictions
None
Required commands
This verb requires the Verify CVV command (offset X'00E0') to be enabled in the active role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBCSVJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBCSVJ are shown here.
Format
public native void CSNBCSVJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] PAN_data,
byte[] expiration_date,
byte[] service_code,
byte[] key_a_id,
byte[] key_b_id,
byte[] generated_cvv);
Chapter9.Financialservices 327

Encrypted PIN Generate (CSNBEPG)
Encrypted PIN Generate (CSNBEPG)
The Encrypted PIN Generate verb 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 3621 format
v IBM 3624 format
v ISO-0 format (same as theANSI X9.8, VISA-1, and ECI-1 formats)
v ISO-1 format (same as the ECI-4 format)
v ISO-2 format
v ISO-3 format
v IBM 4704 encrypting PINPAD (4704-EPP) format
v VISA2 format
v VISA3 format
v VISA4 format
v ECI-2 format
v ECI-3 format
Format
CSNBEPG(
return_code,
reason_code,
exit_data_length,
exit_data,
PIN_generating_key_identifier,
outbound_PIN_encrypting_key_identifier
rule_array_count,
rule_array,
PIN_length,
data_array,
PIN_profile,
PAN_data,
sequence_number
encrypted_PIN_block )
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 14.
PIN_generating_key_identifier
Direction: Input/Output Type: String
The 64-byte internal key token or a key label of an internal key token in the DES key storage file. The
internal key token contains the PIN-generating key. The control vector must specify the PINGEN key
type and have the EPINGEN usage bit set to 1.
outbound_PIN_encrypting_key_identifier
Direction: Input Type: String
328 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Generate (CSNBEPG)
A64-byte internal key token or a key label of an internal key token in the DES key storage file. The
internal key token contains the 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 usage bit set to 1.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. Each keyword is left-justified in an 8-byte field
and padded on the right with blanks.All keywords must be in contiguous storage. The rule_array
keywords are described in Table88.
Table88.KeywordsforEncryptedPINGeneratecontrolinformation
Keyword Description
| Processingrule(One,required)
GBP-PIN ThiskeywordspecifiestheIBMGermanBankPoolInstitutionPINcalculationmethodistobeusedto
generateaPIN.
IBM-PIN ThiskeywordspecifiestheIBM3624PINcalculationmethodistobeusedtogenerateaPIN.
INBK-PIN ThiskeywordspecifiestheInterbankPINcalculationmethodistobeusedtogenerateaPIN.
PIN_length
Direction: Input Type: String
Ainteger defining the PIN length for those PIN calculation methods with variable length PINs;
otherwise, the variable should be set to zero.
data_array
Direction: Input Type: Integer
Three 16-byte 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 from 1 - 16 bytes in length, uppercase, left-justified, and padded on the right with space characters.
Table89 describes the array elements.
Table89.ArrayelementsforEncryptedPINGeneratedata_arrayparameter
Arrayelement Description
Decimalization_table DecimalizationtableforIBMandGBPonly.Sixteencharactersthatareusedtomapthe
hexadecimaldigits(X'0'-X'F')oftheencryptedvalidationdatatodecimaldigits(X'0'-X'9').
Trans_sec_parm ForInterbankonly,sixteendigits.Elevenrightmostdigitsofthepersonalaccountnumber
(PAN).Aconstantof6.Onedigitkeyselectorindex.ThreedigitsofPINvalidationdata.
Validation_data ValidationdataforIBMandIBMGermanBankPoolpaddedto16bytes.1-16charactersof
hexadecimalaccountdataleft-justifiedandpaddedontherightwithblanks.
Table90 on page 330 lists the data array elements required by the process rule (rule_array
parameter). The numbers refer to the process rule's position within the array.
Chapter9.Financialservices 329

Encrypted PIN Generate (CSNBEPG)
Table90.KeywordsforEncryptedPINGeneratecontrolinformation
Processrule IBM-PIN GBP-PIN INBK-PIN
Decimalization_table 1 1
Validation_data 2 2
Trans_sec_parm 1
PIN_profile
Direction: Input Type:Array
A24-byte string containing the PIN profile including the PIN block format. See “The PIN profile” on
page 307 for additional information.
PAN_data
Direction: Input Type: String
A12-byte string that contains 12 digits of PersonalAccount Number (PAN) data. The verb uses this
parameter if the PIN profile specifies the ISO-0, ISO- 3, or VISA-4 or keyword for the PIN block
format. Otherwise, ensure this parameter is a 4-byte variable in application storage. The information in
this variable will be ignored, but the variable must be specified.
Note: When using the ISO-0 or ISO-3 keyword, use the 12 rightmost digits of the PAN data, excluding
the check digit. When using the VISA-4 keyword, use the 12 leftmost digits of the PAN data,
excluding the check digit.
sequence_number
Direction: Input Type: Integer
The 4-byte string that contains the sequence number used by certain PIN block formats. The verb
uses this parameter if the PIN profile specifies the 3621 or 4704-EPP keyword for the PIN block
format. Otherwise, ensure this parameter is a 4-byte variable in application data storage. The
information in the variable will be ignored, but the variable must be declared. To enter a sequence
number, do the following:
v Enter 99999 to use a random sequence number that the service generates.
v For the 3621 PIN block format, enter a value in the range from 0 - 65,535.
v For the 4704-EPP PIN block format, enter a value in the range from 0 - 255.
encrypted_PIN_block
Direction: Output Type: String
The field where the verb returns the 8-byte encrypted PIN.
Restrictions
The format control specified in the PIN profile must be NONE.
Required commands
This 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.
||||
Rule-arraykeyword Offset Command
||| IBM-PIN X'00B0' EncryptedPINGenerate-3624
||| GBP-PIN X'00B1' EncryptedPINGenerate-GBP
||| INBK-PIN X'00B2' EncryptedPINGenerate-Interbank
|
330 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Generate (CSNBEPG)
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 PTR Enhanced PIN Security Mode command (offset X'0313') in the active
role.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBEPGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBEPGJ are shown here.
Format
public native void CSNBEPGJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
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
);
Chapter9.Financialservices 331

Encrypted PIN Translate (CSNBPTR)
Encrypted PIN Translate (CSNBPTR)
Use the Encrypted PIN Translate verb to re-encipher a PIN block from one PIN-encrypting key to another
and, optionally, to change the PIN block format, such as the pad digit or sequence number.
The unique-key-per-transaction key derivation for single and double-length keys is available for the
Encrypted PIN Translate verb. This support is available for the input_PIN_encrypting_key_identifier and the
output_PIN_encrypting_key_identifier parameters for both REFORMAT and TRANSLAT process rules. The
rule_array keyword determines which PIN keys are derived keys.
The Encrypted PIN Translate verb can be used for unique-key-per-transaction key derivation.
Format
CSNBPTR(
return_code,
reason_code,
exit_data_length,
exit_data,
input_PIN_encrypting_key_identifier,
output_PIN_encrypting_key_identifier,
input_PIN_profile,
PAN_data_in,
PIN_block_in,
rule_array_count,
rule_array,
output_PIN_profile,
PAN_data_out,
sequence_number,
PIN_block_out )
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 14.
input_PIN_encrypting_key_identifier
Direction: Input/Output Type: String
The input PIN-encrypting key (IPINENC) for the PIN_block_in parameter specified as a 64-byte
internal key token or a key label. If keyword UKPTOPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH is
specified in the rule_array parameter, the input_PIN_encrypting_key_identifier must specify a key
token or key label of a KEYGENKY with the UKPT usage bit enabled.
output_PIN_encrypting_key_identifier
Direction: Input/Output Type: String
The output PIN-encrypting key (OPINENC) for the PIN_block_out parameter specified as a 64-byte
internal key token or a key label. If keyword UKPTOPIN, UKPTBOTH, DUKPT-IP, or DUKPT-BH is
specified in the rule_array parameter, the output_PIN_encrypting_key_identifier must specify a key
token or key label of a KEYGENKY with the UKPT usage bit enabled.
input_PIN_profile
Direction: Input Type: String
The three 8-byte character elements that contain information necessary to either create a formatted
PIN block or extract a PIN from a formatted PIN block.Aparticular PIN profile can be either an input
PIN profile or an output PIN profile depending on whether the PIN block is being enciphered or
deciphered by the verb. See “The PIN profile” on page 307 for additional information.
332 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Translate (CSNBPTR)
If you choose the TRANSLAT processing rule or the REFORMAT processing rule in the rule_array
parameter, the input PIN profile and output PIN profile can have different PIN block formats. If you
specify UKPTIPIN/DUKPT-IP or UKPTBOTH/DUKPT-BH in the rule_array parameter, the
input_PIN_profile is extended to a 48-byte field and must contain the current key serial number. See
“The PIN profile” on page 307 for additional information.
The pad digit is needed to extract the PIN from a 3624 or 3621 PIN block in the Encrypted PIN
Translate verb with a process rule (rule_array parameter) of REFORMAT. If the process rule is
TRANSLAT, the pad digit is ignored.
| The PINLENnn keywords are disabled for this verb by default. If these keywords are used, return code
| 8 with reason code 33 is returned. To enable them, the PTR Enhanced PIN Security access control
| point (bit X'0313') must be enabled using a TKE.
PAN_data_in
Direction: Input Type: String
The personal account number (PAN) if the process rule (rule_array parameter) is REFORMAT and the
input PIN format is ISO-0, ISO-3 or VISA-4 only. Otherwise, this parameter is ignored. Specify 12
digits of account data in character format.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.
For VISA-4, use the leftmost 12 digits of the PAN, excluding the check digit.
PIN_block_in
Direction: Input Type: String
The 8-byte enciphered PIN block that contains the PIN to be translated.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, or 3.
rule_array
Direction: Input Type: String
The process rule for the verb is described in Table91.
Table91.KeywordsforEncryptedPINTranslatecontrolinformation
Keyword Description
| Processingrule(One,required)
REFORMAT ChangesthePINformat,thecontentsofthePINblock,andthePIN-encryptingkey.
TRANSLAT ChangesthePIN-encryptingkeyonly.ItdoesnotchangethePINformatandthecontentsofthe
PINblock.
PINblockformat See“PINblockformatandPINextractionmethodkeywords”onpage308foradditional
andPIN informationandalistofPINblockformatsandPINextractionmethodkeywords.
extraction Note: IfaPINextractionmethodisnotspecified,thefirstonelistedinTable74onpage308for
method(Optional) thePINblockformatwillbethedefault.
| DUKPTkeywords-Singlelengthkeyderivation(One,optional)
UKPTIPIN Theinput_PIN_encrypting_key_identifierisderivedasasinglelengthkey.The
input_PIN_encrypting_key_identifiermustbeaKEYGENKYkeywiththeUKPTusagebit
enabled.Theinput_PIN_profilemustbe48bytesandcontainthekeyserialnumber.
UKPTOPIN Theoutput_PIN_encrypting_key_identifierisderivedasasinglelengthkey.The
output_PIN_encrypting_key_identifiermustbeaKEYGENKYkeywiththeUKPTusagebit
enabled.Theoutput_PIN_profilemustbe48bytesandcontainthekeyserialnumber.
Chapter9.Financialservices 333

Encrypted PIN Translate (CSNBPTR)
Table91.KeywordsforEncryptedPINTranslatecontrolinformation (continued)
Keyword Description
UKPTBOTH Boththeinput_PIN_encrypting_key_identifierandtheoutput_PIN_encrypting_key_identifierare
derivedasasinglelengthkey.Boththeinput_PIN_encrypting_key_identifierandthe
output_PIN_encrypting_key_identifiermustbeKEYGENKYkeyswiththeUKPTusagebit
enabled.Boththeinput_PIN_profileandtheoutput_PIN_profilemustbe48bytesandcontain
therespectivekeyserialnumber.
| DUKPTkeywords-doublelengthkeyderivation(One,optional)
DUKPT-IP Theinput_PIN_encrypting_key_identifierisderivedasadoublelengthkey.The
input_PIN_encrypting_key_identifiermustbeaKEYGENKYkeywiththeUKPTusagebit
enabled.Theinput_PIN_profilemustbe48bytesandcontainthekeyserialnumber.
DUKPT-OP Theoutput_PIN_encrypting_key_identifierisderivedasadoublelengthkey.The
output_PIN_encrypting_key_identifiermustbeaKEYGENKYkeywiththeUKPTusagebit
enabled.Theoutput_PIN_profilemustbe48bytesandcontainthekeyserialnumber.
DUKPT-BH Boththeinput_PIN_encrypting_key_identifierandtheoutput_PIN_encrypting_key_identifierare
derivedasadoublelengthkey.Boththeinput_PIN_encrypting_key_identifierandthe
output_PIN_encrypting_key_identifiermustbeKEYGENKYkeyswiththeUKPTusagebit
enabled.Boththeinput_PIN_profileandtheoutput_PIN_profilemustbe48bytesandcontain
therespectivekeyserialnumber.
output_PIN_profile
Direction: Input Type: String
The three 8-byte character elements that contain information necessary to either create a formatted
PIN block or extract a PIN from a formatted PIN block.Aparticular PIN profile can be either an input
PIN profile or an output PIN profile, depending on whether the PIN block is being enciphered or
deciphered by the verb.
v If you choose the TRANSLAT processing rule in the rule_array parameter, the input_PIN_profile and
the output_PIN_profile must specify the same PIN block format.
v If you choose the REFORMAT processing rule in the rule_array parameter, the input PIN profile and
output PIN profile can have different PIN block formats.
v If you specify UKPTOPIN or UKPTBOTH in the rule_array parameter, the output_PIN_profile is
extended to a 48-byte field and must contain the current key serial number. See “The PIN profile”
on page 307 for additional information.
v If you specify DUKPT-OP or DUKPT-BH in the rule_array parameter, the output_PIN_profile is
extended to a 48-byte field and must contain the current key serial number. See “The PIN profile”
on page 307 for additional information.
PAN_data_out
Direction: Input Type: String
The personal account number (PAN) if the process rule (rule_array parameter) is REFORMAT and the
output PIN format is ISO-0, ISO-3, or VISA-4 only. Otherwise, this parameter is ignored. Specify 12
digits of account data in character format.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.
For VISA-4, use the leftmost 12 digits of the PAN, excluding the check digit.
sequence_number
Direction: Output Type: Integer
The sequence number if the process rule (rule_array parameter) is REFORMAT and the output PIN
block format is 3621 or 4704-EPP only. Specify the integer value 99999. Otherwise, this parameter is
ignored.
334 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Translate (CSNBPTR)
PIN_block_out
Direction: Input Type: String
The 8-byte output PIN block that is re-enciphered.
Restrictions
None
Required commands
This 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.
|||
Inputprofile Outputprofile
||| Rule-array formatcontrol formatcontrol
||||| keyword keyword keyword Offset Command
||||| TRANSLAT NONE NONE X'00B3' EncryptedPINTranslate-Translate
||||| REFORMAT NONE NONE X'00B7' EncryptedPINTranslate-Reformat
|
| This verb also requires the UKPT - PIN Verify_ PIN Translate command (offset X'00E1') to be enabled if
| you employ UKPT processing.
Note: Arole with offset X'00E1' enabled can also use the Encrypted PIN Verify verb with UKPT
processing.
| An enhanced PIN security mode is available for extracting PINs from a 3621 or 3624 encrypted PIN-block
| 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 PTR
| Enhanced PIN Security 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 PIN 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.0, 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 theANSI X9.8 PIN - Enforce PIN block restrictions command (offset X'0350') in the active role
| to apply additional restrictions to PIN processing implemented in CCA4.1.0, 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.
Chapter9.Financialservices 335

Encrypted PIN Translate (CSNBPTR)
| Note: Arole with offset X'0350' enabled also affects access control of the Clear PIN Generate
| Alternate and the Secure Messaging for PINs verbs.
| 2. Enable theANSI X9.8 PIN -Allow modification of PAN_01_0350 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 theANSI X9.8 PIN - Enforce PIN block restrictions command (offset X'0350') or theANSI X9.8
| PIN -Allow onlyANSI PIN blocks_01_0350 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: Arole with offset X'0351' enabled also affects access control of the Secure Messaging for PINs
| verbs.
| 3. Enable theANSI X9.8 PIN -Allow onlyANSI PIN blocks_01_0350 command (offset X'0352') in the
| active role to apply a more restrictive variation of theANSI X9.8 PIN - Enforce PIN block restrictions
| 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: Arole with offset X'0352' enabled also affects access control of the Secure Messaging for PINs
| verbs.
| For more information, see “ANSI X9.8 PIN restrictions” on page 306.
Usage notes
Some PIN block formats are known by several names. The following table shows the additional names.
Table92.AdditionalnamesforPINformats
PINformat Additionalname
ISO-0 ANSIX9.8,VISAformat1,ECIformat1
ISO-1 ECIformat4
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBPTRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBPTRJ are shown here.
336 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Translate (CSNBPTR)
Format
public native void CSNBPTRJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
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
);
Chapter9.Financialservices 337

Encrypted PIN Verify (CSNBPVR)
Encrypted PIN Verify (CSNBPVR)
Use the Encrypted PIN Verify verb to verify that one of the following customer selected trial PINs is valid:
v IBM 3624 (IBM-PIN)
v IBM 3624 PIN offset (IBM-PINO)
v IBM German Bank Pool (GBP-PIN)
v VISAPIN validation value (VISA-PVV)
v VISAPIN validation value (VISAPVV4)
v Interbank PIN (INBK-PIN)
The unique-key-par-transaction key derivation for single and double-length keys is available for the
input_PIN_encrypting_key_identifier parameter.
Format
CSNBPVR(
return_code,
reason_code,
exit_data_length,
exit_data,
input_PIN_encrypting_key_identifier,
PIN_verifying_key_identifier,
input_PIN_profile,
PAN_data,
encrypted_PIN_block,
rule_array_count,
rule_array,
PIN_check_length,
data_array )
Parameters
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see
“Parameters common to all verbs” on page 14.
input_PIN_encrypting_key_identifier
Direction: Input/Output Type: String
The 64-byte key label or internal key token containing the PIN-encrypting key (IPINENC) that
enciphers the PIN block. If keyword UKPTIPIN or DUKPT-IP is specified in the rule_array, the
input_PIN_encrypting_key_identifier must specify a key token or key label of a KEYGENKY with the
UKPT usage bit enabled.
PIN_verifying_key_identifier
Direction: Input/Output Type: String
The 64-byte key label or internal key token that identifies the PIN verify (PINVER) key.
input_PIN_profile
Direction: Input Type: String
The three 8-byte character elements that contain information necessary to either create a formatted
PIN block or extract a PIN from a formatted PIN block.Aparticular PIN profile can be either an input
PIN profile or an output PIN profile depending on whether the PIN block is being enciphered or
deciphered by the verb. If you specify UKPTIPIN in the rule_array parameter, the input_PIN_profile is
extended to a 48-byte field and must contain the current key serial number. See “The PIN profile” on
page 307 for additional information.
338 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Verify (CSNBPVR)
If you specify DUKPT-IP in the rule_array parameter, the input_PIN_profile is extended to a 48-byte
field and must contain the current key serial number. See “The PIN profile” on page 307 for additional
information.
The pad digit is needed to extract the PIN from a 3624 or 3621 PIN block in the Encrypted PIN Verify
verb.
| The PINLENnn keywords are disabled for this verb by default. If these keywords are used, return code
| 8 with reason code 33 is returned. To enable them, the PTR Enhanced PIN Security access control
| point (bit X'0313') must be enabled using a TKE workstation.
PAN_data
Direction: Input Type: String
The personal account number (PAN) is required for ISO-0, ISO-3 and VISA-4. Otherwise, this
parameter is ignored. Specify 12 digits of account data in character format.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.
For VISA-4, use the leftmost 12 digits of the PAN, excluding the check digit.
encrypted_PIN_block
Direction: Input Type: String
The 8-byte enciphered PIN block that contains the PIN to be verified.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1, 2, or 3.
rule_array
Direction: Input Type: String
The process rule for the PIN verify algorithm, described in Table93.
Table93.KeywordsforEncryptedPINVerifycontrolinformation
Keyword Description
| Algorithmvalue(One,required)
GBP-PIN TheIBMGermanBankPoolPIN.ItverifiesthePINenteredbythecustomerandcomparesthat
PINwiththeinstitutiongeneratedPINbyusinganinstitutionkey.
IBM-PIN TheIBM3624PIN,whichisaninstitution-assignedPIN.ItdoesnotcalculatethePINoffset.
IBM-PINO TheIBM3624PINoffset,whichisacustomer-selectedPINandcalculatesthePINoffset.
INBK-PIN TheInterbankPINverifyalgorithm.
VISA-PVV TheVISAPINverifyvalue.
VISAPVV4 TheVISAPINverifyvalue.Ifthelengthis4digits,normalprocessingforVISA-PVVwilloccur.
PINblock See“PINblockformatandPINextractionmethodkeywords”onpage308foradditionalinformation
formatandPIN andalistofPINblockformatsandPINextractionmethodkeywords.
extraction
| method ThePINLENnnkeywordsaredisabledforthisverbbydefault.Ifthesekeywordsareused,return
| (Optional) code8withreasoncode33isreturned.Toenablethem,thePTREnhancedPINSecurityaccess
| controlpoint(bitX'0313')mustbeenabledusingaTKEworkstation.
Note: IfaPINextractionmethodisnotspecified,thefirstonelistedinTable74onpage308for
thePINblockformatwillbethedefault.
DUKPTkeyword-singlelengthkeyderivation(Optional)
Chapter9.Financialservices 339

Encrypted PIN Verify (CSNBPVR)
Table93.KeywordsforEncryptedPINVerifycontrolinformation (continued)
Keyword Description
UKPTIPIN Theinput_PIN_encrypting_key_identifierisderivedasasinglelengthkey.The
input_PIN_encrypting_key_identifiermustbeaKEYGENKYkeywiththeUKPTusagebitenabled.
Theinput_PIN_profilemustbe48bytesandcontainthekeyserialnumber.
DUKPTkeyword-doublelengthkeyderivation(Optional)
DUKPT-IP Theinput_PIN_encrypting_key_identifieristobederivedusingtheDUKPTalgorithm.The
input_PIN_encrypting_key_identifiermustbeaKEYGENKYkeywiththeDUKPTusagebit
enabled.Theinput_PIN_profilemustbe48bytesandcontainthekeyserialnumber.
PIN_check_length
Direction: Input Type: String
The PIN check length for the IBM-PIN or IBM-PINO process rules only. Otherwise, it is ignored.
Specify the rightmost digits, 4 - 16, for the PIN to be verified.
data_array
Direction: Input Type: Integer
Three 16-byte elements required by the corresponding rule_array parameter. The data array consists
of three 16-byte fields whose specification depend on the process rule. If a process rule requires only
one or two 16-byte fields, the rest of the data array is ignored by the verb. Table94 describes the
array elements.
Table94.ArrayelementsforEncryptedPINVerifydata_arrayparameter
Arrayelement Description
Decimalization_table DecimalizationtableforIBMandGBPonly.Sixteendecimaldigitsof0-9.
PIN_offset OffsetdataforIBM-PINO.Onetotwelvenumericcharacters,0-9,left-justifiedand
paddedontherightwithblanks.ForIBM-PINO,thePINoffsetlengthisspecifiedin
thePIN_check_lengthparameter.ForIBM-PINandGBP-PIN,thefieldisignored.
Trans_sec_parm ForVISA,onlytheleftmosttwelvedigitsofthe16-bytefieldareused.Theseconsistof
therightmostelevendigitsofthepersonalaccountnumber(PAN)andaone-digitkey
index.Theremainingfourcharactersareignored.
ForInterbankonly,all16bytesareused.Theseconsistoftherightmostelevendigits
ofthePAN,aconstantofX'6',aone-digitkeyindex,andthreenumericdigitsofPIN
validationdata.
RPVV ForVISA-PVVonly,referencedPVV(fourbytes)thatisleft-justified.Therestofthe
fieldisignored.
Validation_data ValidationdataforIBMandGBPpaddedto16bytes.1-16charactersofhexadecimal
accountdataleft-justifiedandpaddedontherightwithblanks.
Table95 lists the data array elements required by the process rule (rule_array parameter). The
numbers refer to the process rule's position within the array.
Table95.Arrayelementsrequiredbytheprocessrule
Processrule IBM-PIN IBM-PINO GBP-PIN VISA-PVV INBK-PIN
Decimalization_table 1 1 1
Validation_data 2 2 2
PIN_offset 3 3 3
Trans_sec_parm 1 1
RPVV 2
340 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Encrypted PIN Verify (CSNBPVR)
Restrictions
None
Required commands
This verb requires the following commands to be enabled in the active role:
Rule-arraykeyword Offset Command
IBM-PIN,IBM-PINO X'00AB' EncryptedPINVerify-3624
GBP-PIN X'00AC' EncryptedPINVerify-GBP
VISA-PVV,VISAPVV4 X'00AD' EncryptedPINVerify-VISAPVV
INBK-PIN X'00AE' EncryptedPINVerify-Interbank
| This verb also requires the UKPT - PIN Verify_ PIN Translate command (offset X'00E1') to be enabled in
| the active role if you employ UKPT processing.
Note: Arole with offset X'00E1' enabled can also use the Encrypted PIN Translate verb with UKPT
processing.
| 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 four is enforced. No other PIN-block consistency checking will occur. To activate
| this mode, enable the PTR Enhanced PIN Security command (offset X'0313') in the active role.
Usage notes
None
Related information
The algorithms are discussed in detail inAppendixE, “PIN formats and algorithms,” on page 477.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBPVRJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBPVRJ are shown here.
Format
public native void CSNBPVRJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
byte[] PIN_encrypting_key_identifier,
byte[] PIN_verifying_key_identifier,
byte[] PIN_profile,
byte[] PAN_data,
byte[] encrypted_PIN_block,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger PIN_check_length,
byte[] data_array
);
Chapter9.Financialservices 341

PIN Change/Unblock (CSNBPCU)
PIN Change/Unblock (CSNBPCU)
The PIN Change/Unblock verb is used to generate a special PIN block to change the PIN accepted by an
integrated circuit card (smartcard). The special PIN block is based on the new PIN and the card-specific
diversified key and, optionally, on the current PIN of the smartcard. The new PIN block is encrypted with a
session key. The session key is derived in a two-step process. First, the card-specific diversified key (ICC
Master Key) is derived using the TDES-ENC algorithm of the Diversified Key Generate verb. The session
key is then generated according to the rule_array algorithm:
v TDES-XOR - XOR ICC Master Key with theApplication Transaction Counter (ATC)
v TDESEMV2 - use the EMV2000 algorithm with a branch factor of 2
v TDESEMV4 - use the EMV2000 algorithm with a branch factor of 4
The generating DKYGENKY cannot have replicated halves. The encryption_issuer_master_key_identifier is
a DKYGENKY that permits generation of a SMPIN key. The authentication_issuer_master_key_identifier is
also a DKYGENKY that permits generation of a double length MAC key.
The PIN block format is specified by the VISAICC Card specification: two mutually exclusive rule_array
keywords, VISAPCU1 and VISAPCU2. They refer to whether the current PIN is used in the generation of
the new PIN. For VISAPCU1, it is not used, for VISAPCU2 it is used.
Format
CSNBPCU(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
authentication_issuer_master_key_length,
authentication_issuer_master_key_identifier,
encryption_issuer_master_key_length,
encryption_issuer_master_key_identifier,
key_generation_data_length,
key_generation_data,
new_reference_PIN_key_length,
new_reference_PIN_key_identifier,
new_reference_PIN_block,
new_reference_PIN_profile,
new_reference_PIN_PAN__data,
current_reference_PIN_key_length,
current_reference_PIN_key_identifier,
current_reference_PIN_block,
current_reference_PIN_profile,
current_reference_PIN_PAN__data,
output_PIN_data_length,
output_PIN_data,
output_PIN_profile,
output_PIN_message_length,
output_PIN_message )
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 14.
rule_array_count
Direction: Input Type: Integer
342 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PIN Change/Unblock (CSNBPCU)
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1 or 2.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. The keywords are left-justified in an 8-byte field
and padded on the right with blanks. The keywords must be in contiguous storage. The rule_array
keywords are described in Table96.
Table96.KeywordsforPINChange/Unblockcontrolinformation
Keyword Description
| Algorithm(One,optional)
TDES-XOR TDESenciphercleardatatogeneratetheintermediate(card-unique)key,followedbyXORofthefinal
twobytesofeachkeywiththeATCcounter.Thisisthedefault.
TDESEMV2 SameprocessingasintheDiversifiedKeyGenerateverb.
TDESEMV4 SameprocessingasintheDiversifiedKeyGenerateverb.
| PINprocessingmethod(One,required)
VISAPCU1 FormthenewPINfromthenewreferencePINandtheintermediate(card-unique)keyonly.
VISAPCU2 FormthenewPINfromthenewreferencePIN,theintermediate(card-unique)keyandthecurrent
referencePIN.
authentication_issuer_master_key_length
Direction: Input Type: Integer
The length of the authentication_issuer_master_key_identifier parameter. Currently, the value must be
64.
authentication_issuer_master_key_identifier
Direction: Input/Output Type: String
The label name or internal token of a DKYGENKY key type that is to be used to generate the
card-unique diversified key. The control vector of this key must be a DKYL0 key that permits the
generation of a double-length MAC key (DMAC). This DKYGENKY might not have replicated key
halves.
encryption_issuer_master_key_length
Direction: Input Type: Integer
The length of the encryption_issuer_master_key_identifier parameter. Currently, the value must be 64.
encryption_issuer_master_key_identifier
Direction: Input/Output Type: String
The label name or internal token of a DKYGENKY key type that is to be used to generate the
card-unique diversified key and the secure messaging session key for the protection of the output PIN
block. The control vector of this key must be a DKYL0 key that permits the generation of a SMPIN key
type. This DKYGENKY might not have replicated key halves.
key_generation_data_length
Direction: Input Type: Integer
The length of the key_generation_data parameter. This value must be 10, 18, 26, or 34 bytes.
key_generation_data
Direction: Input Type: String
Chapter9.Financialservices 343

PIN Change/Unblock (CSNBPCU)
The data provided to generate the card-unique session key. For TDES-XOR, this consists of 8 or 16
bytes of data to be processed by TDES to generate the card-unique diversified key followed by a
16-bitATC counter to offset the card-unique diversified key to form the session key. For TDESEMV2
and TDESEMV4, this can be 10, 18, 26, or 34 bytes. See “Diversified Key Generate (CSNBDKG)” on
page 113 for more information.
new_reference_PIN_key_length
Direction: Input Type: Integer
The length of the new_reference_PIN_key_identifier parameter. Currently, the value must be 64.
new_reference_PIN_key_identifier
Direction: Input/Output Type: String
The label name or internal token of a PIN encrypting key that is to be used to decrypt the
new_reference_PIN_block. This must be an IPINENC or OPINENC key. If the label name is supplied,
the name must be unique in the DES key storage file.
new_reference_PIN_block
Direction: Input Type: String
This is an 8-byte field that contains the enciphered PIN block of the new PIN.
new_reference_PIN_profile
Direction: Input Type: String
This is a 24-byte field that contains three 8-byte elements with a PIN block format keyword, a format
control keyword (NONE), and a pad digit as required by certain formats.
new_reference_PIN_PAN_data
Direction: Input Type: String
This is a 12-byte field containing PAN in character format. This data might be needed to recover the
new reference PIN if the format is ISO-0, ISO-3, or VISA-4. If neither is used, this parameter might be
blanks.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit. For VISA-4, use
the leftmost 12 digits of the PAN, excluding the check digit.
current_reference_PIN_key_length
Direction: Input Type: Integer
The length of the current_reference_PIN_key_identifier parameter. For the current implementation, the
value must be 64. If the rule_array contains VISAPCU1, this value must be 0.
current_reference_PIN_key_identifier
Direction: Input/Output Type: String
The label name or internal token of a PIN encrypting key that is to be used to decrypt the
current_reference_PIN_block. This must be an IPINENC or OPINENC key. If the label name is
supplied, the name must be unique in the key storage. If the rule_array contains VISAPCU1, this value
is ignored.
current_reference_PIN_block
Direction: Input Type: String
This is an 8-byte field that contains the enciphered PIN block of the new PIN. If the rule_array
contains VISAPCU1, this value is ignored.
current_reference_PIN_profile
344 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PIN Change/Unblock (CSNBPCU)
Direction: Input Type: String
This is a 24-byte field that contains three 8-byte elements with a PIN block format keyword, a format
control keyword (NONE), and a pad digit as required by certain formats. If the rule_array contains
VISAPCU1, this value is ignored.
current_reference_PIN_PAN_data
Direction: Input Type: String
This is a 12-byte field containing PAN in character format. This data might be needed to recover the
new reference PIN if the format is ISO-0, ISO-3, or VISA-4. If neither is used, this parameter might be
blanks. If the rule_array contains VISAPCU1, this value is ignored.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit. For VISA-4, use
the leftmost 12 digits of the PAN, excluding the check digit.
output_PIN_data_length
Direction: Input Type: Integer
Currently this field is reserved. This value must be 0.
output_PIN_data
Direction: Input Type: String
This parameter is ignored.
output_PIN_profile
Direction: Input Type: String
This is a 24-byte field that contains three 8-byte elements with a PIN block format keyword
(VISAPCU1 or VISCPU2), a format control keyword (NONE), and eight bytes of spaces.
output_PIN_message_length
Direction: Input/Output Type: Integer
The length of the output_PIN_message field. Currently the value must be a minimum of 16.
output_PIN_message
Direction: Output Type: String
The reformatted PIN block with the new reference PIN enciphered under the SMPIN session key.
Restrictions
None
Required commands
This 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
| encrypting
|||| key-type Offset Command Comment
|||| OPINENC X'00BC' PINChange/Unblock-changeEMV Requiredifeitherthe
|| PINwithOPINENC new_reference_PIN_keyorthe
| current_reference_PIN_keyare
| permittedtobeanOPINENCkey
| type.
Chapter9.Financialservices 345

PIN Change/Unblock (CSNBPCU)
| PIN-block
| encrypting
|||| key-type Offset Command Comment
|||| IPINENC X'00BD' PINChange/Unblock-changeEMV Requiredifeitherthe
|| PINwithIPINENC new_reference_PIN_keyorthe
| current_reference_PIN_keyare
| permittedtobeanIPINENCkey
| 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 Diversified Key Generate - DKYGENKY - DALLcommand (offset X'0290') must also be
| enabled in the active role.
Note: Arole with offset X'0290' enabled can also use the Diversified Key Generate verb with a DALLkey.
| 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 PTR Enhanced PIN Security command (offset X'0313') in the active role.
Usage notes
There are additional access points for this verb.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBPCUJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBPCUJ are shown here.
346 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PIN Change/Unblock (CSNBPCU)
Format
public native void CSNBPCUJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger authenticationMasterKeyLength,
byte[] authenticationMasterKey,
hikmNativeInteger issuerMasterKeyLength,
byte[] issuerMasterKey,
hikmNativeInteger keyGenerationDataLength,
byte[] keyGenerationData,
hikmNativeInteger newRefPinKeyLength,
byte[] newRefPinKey,
byte[] newRefPinBlock,
byte[] newRefPinProfile,
byte[] newRefPanData,
hikmNativeInteger currentRefPinKeyLength,
byte[] currentRefPinKey,
byte[] currentRefPinBlock,
byte[] currentRefPinProfile,
byte[] currentRefPanData,
hikmNativeInteger outputPinDataLength,
byte[] outputPinData,
byte[] outputPinProfile,
hikmNativeInteger outputPinMessageLength,
byte[] outputPinMessage);
Chapter9.Financialservices 347

Secure Messaging for Keys (CSNBSKY)
Secure Messaging for Keys (CSNBSKY)
The Secure Messaging for Keys verb will encrypt a text block including a clear key value decrypted from
an internal or external DES token. The text block is normally a "Value" field of a secure message TLV
(Tag/Length/Value) element of a secure message. TLV is defined in ISO/IEC 7816-4.
Format
CSNBSKY(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
input_key_identifier,
key_encrypting_key_identifier,
secmsg_key_identifier,
text_length,
clear_text,
initialization_vector,
key_offset,
key_offset_field_length,
enciphered_text,
output_chaining_vector )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0 or 1.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. The processing method is the encryption mode
used to encrypt the message. The rule_array keywords are described in Table97.
Table97.KeywordsforSecureMessagingforKeyscontrolinformation
Keyword Description
| Encipheringmode(One,optional)
TDES-CBC UseCBCmodetoencipherthemessage(default).
TDES-ECB UseEBCmodetoencipherthemessage.
input_key_identifier
Direction: Input/Output Type: String
The internal token, external token, or key label of an internal token of a double length DES key. The
key is recovered in the clear and placed in the text to be encrypted. The control vector of the DES key
must not prohibit export.
key_encrypting_key_identifier
Direction: Input/Output Type: String
348 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Secure Messaging for Keys (CSNBSKY)
If the input_key_identifier is an external token, this parameter is the internal token or the key label of
the internal token of IMPORTER or EXPORTER. If it is not, it is a null token. If a key label is specified,
the key label must be unique.
secmsg_key_identifier
Direction: Input/Output Type: String
The internal token or key label of a secure message key for encrypting keys. This key is used to
encrypt the updated clear_text containing the recovered DES key.
text_length
Direction: Input Type: Integer
The length of the clear_text parameter. Length must be a multiple of eight. Maximum length is 4K.
clear_text
Direction: Input Type: String
Clear text that contains the recovered DES key at the offset specified and is then encrypted.Any
padding or formatting of the message must be done by the caller on input.
initialization_vector
Direction: Input Type: String
The 8-byte supplied string for the TDES-CBC mode of encryption. The initialization_vector is XORed
with the first eight bytes of clear_text before encryption. This field is ignored for TDES-ECB mode.
key_offset
Direction: Input Type: Integer
The offset within the clear_text parameter at key_offset where the recovered clear input_key_identifier
value is to be placed. The first byte of the clear_text field is offset 0.
key_offset_field_length
Direction: Input Type: Integer
The length of the field within clear_text parameter at key_offset where the recovered clear
input_key_identifier value is to be placed. Length must be a multiple of eight and is equal to the key
length of the recovered key. The key must fit entirely within the clear_text.
enciphered_text
Direction: Output Type: String
The field where the enciphered text is returned. The length of this field must be at least as long as the
clear_text field.
output_chaining_vector
Direction: Output Type: String
This field contains the last eight bytes of enciphered text and is used as the initialization_vector for the
next encryption call if data needs to be chained for TDES-CBC mode. No data is returned for
TDES-ECB.
Restrictions
None
Required commands
This verb requires the Secure Messaging for Keys command (offset X'0273') to be enabled in the active
role.
Chapter9.Financialservices 349

Secure Messaging for Keys (CSNBSKY)
Usage notes
Keys appear in the clear only within the secure boundary of the cryptographic coprocessor, and never in
host storage.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBSKYJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBSKYJ are shown here.
Format
public native void CSNBSKYJ (
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] input_key_indentifier,
byte[] key_encrypting_key,
byte[] session_key,
hikmNativeInteger text_length,
byte[] clear_text,
byte[] initialization_vector,
hikmNativeInteger key_offset,
hikmNativeInteger key_offset_field_length,
byte[] cipher_text,
byte[] output_chaining_value);
350 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Secure Messaging for PINs (CSNBSPN)
Secure Messaging for PINs (CSNBSPN)
The Secure Messaging for PINs verb will encrypt a text block including a clear PIN block recovered from
an encrypted PIN block. The input PIN block will be reformatted if the block format in the input_PIN_profile
is different from the block format in the output_PIN_profile. The clear PIN block will only be self encrypted
if the SELFENC keyword is specified in the rule_array. The text block is normally a "Value" field of a
secure message TLV (Tag/Length/Value) element of a secure message. TLV is defined in ISO/IEC 7816-4.
Format
CSNBSPN(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
input_PIN_block,
PIN_encrypting_key_identifier,
input_PIN_profile,
input_PAN_data,
secmsg_key_identifier,
output_PIN_profile,
output_PAN_data,
text_length,
clear_text,
initialization_vector,
PIN_offset,
PIN_offset_field_length,
enciphered_text,
output_chaining_vector )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0, 1, or 2.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. The processing method is the algorithm used to
create the generated key. The keywords are left justified and padded on the right with blanks. The
rule_array keywords are described in Table98.
Table98.KeywordsforSecureMessagingforPINscontrolinformation
Keyword Description
| Encipheringmode(One,optional)
TDES-CBC UseCBCmodetoencipherthemessage(default).
TDES-ECB UseEBCmodetoencipherthemessage.
| PINencryption(One,optional)
CLEARPIN RecoveredclearinputPINblock(mightbereformatted)isplacedintheclearin
themessageforencryptionwiththesecuremessagekey(default).
Chapter9.Financialservices 351

Secure Messaging for PINs (CSNBSPN)
Table98.KeywordsforSecureMessagingforPINscontrolinformation (continued)
Keyword Description
SELFENC RecoveredclearinputPINblock(mightbereformatted)isself-encryptedand
thenplacedinthemessageforencryptionwiththesecuremessagekey.
input_PIN_block
Direction: Input Type: String
The 8-byte input PIN block that is to be recovered in the clear and, perhaps, reformatted and then
placed in the clear_text to be encrypted.
PIN_encrypting_key_identifier
Direction: Input/Output Type: String
The internal token or key label of the internal token of the PIN encrypting key used in encrypting the
input_PIN_block. The key must be an IPINENC key.
input_PIN_profile
Direction: Input Type: String
The three 8-byte character elements that contain information necessary to extract the PIN from a
formatted PIN block. The valid input PIN formats are ISO-0, ISO-1, ISO-2, and ISO-3. See “The PIN
profile” on page 307 for additional information.
input_PAN_data
Direction: Input Type: String
The 12 digit personal account number (PAN) if the input PIN format is ISO-0 or ISO-3. Otherwise, the
parameter is ignored.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.
secmsg_key_identifier
Direction: Input/Output Type: String
The internal token or key label of an internal token of a secure message key for encrypting PINs. This
key is used to encrypt the updated clear_text.
output_PIN_profile
Direction: Input Type: String
The three 8-byte character elements that contain information necessary to create a formatted PIN
block. If reformatting is not required, the input_PIN_profile and the output_PIN_profile must specify the
same PIN block format. Output PIN block formats supported are ISO-0, ISO-1, ISO-2, and ISO-3.
output_PAN_data
Direction: Input Type: String
The 12 digit personal account number (PAN) if the output PIN format is ISO-0 or ISO-3. Otherwise,
this parameter is ignored.
For ISO-0 or ISO-3, use the rightmost 12 digits of the PAN, excluding the check digit.
text_length
Direction: Input Type: Integer
The length of the clear_text parameter that follows. Length must be a multiple of eight. Maximum
length is 4K.
clear_text
352 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Secure Messaging for PINs (CSNBSPN)
Direction: Input Type: String
Clear text that contains the recovered and/or reformatted/encrypted PIN at offset specified and then
encrypted.Any padding or formatting of the message must be done by the caller on input.
initialization_vector
Direction: Input Type: String
The 8-byte supplied string for the TDES-CBC mode of encryption. The initialization_vector is XORed
with the first eight bytes of clear_text before encryption. This field is ignored for TDES-ECB mode.
PIN_offset
Direction: Input Type: Integer
The offset within the clear_text parameter where the reformatted PIN block is to be placed. The first
byte of the clear_text field is offset 0.
PIN_offset_field_length
Direction: Input Type: Integer
The length of the field within clear_text parameter at PIN_offset where the recovered clear
input_PIN_block value is to be placed. The PIN block might be self-encrypted if requested by the
rule_array. Length must be eight. The PIN block must fit entirely within the clear_text.
enciphered_text
Direction: Output Type: String
The field where the enciphered text is returned. The length of this field must be at least as long as the
clear_text field.
output_chaining_vector
Direction: Output Type: String
This field contains the last eight bytes of enciphered text and is used as the initialization_vector for the
next encryption call if data needs to be chained for TDES-CBC mode. No data is returned for
TDES-ECB.
Restrictions
None
Required commands
This verb requires the Secure Messaging for PINs command (offset X'0274') to be enabled in the active
role.
| Beginning with Release 4.1.0, 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 theANSI X9.8 PIN - Enforce PIN block restrictions command (offset X'0350') in the active role
| to apply additional restrictions to PIN processing implemented in CCA4.1.0, 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.
Chapter9.Financialservices 353

Secure Messaging for PINs (CSNBSPN)
| Note: Arole with offset X'0350' enabled also affects access control of the Clear PIN Generate
| Alternate and the Encrypted PIN Translate verbs.
| 2. Enable theANSI X9.8 PIN -Allow modification of PAN_01_0350 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 theANSI X9.8 PIN - Enforce PIN block restrictions command (offset X'0350') or theANSI X9.8
| PIN -Allow onlyANSI PIN blocks_01_0350 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: Arole with offset X'0351' enabled also affects access control of the Encrypted PIN Translate
| verbs.
| 3. Enable theANSI X9.8 PIN -Allow onlyANSI PIN blocks_01_0350 command (offset X'0352') in the
| active role to apply a more restrictive variation of theANSI X9.8 PIN - Enforce PIN block restrictions
| 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: Arole with offset X'0352' enabled also affects access control of the Encrypted PIN Translate
| verbs.
| For more information, see “ANSI X9.8 PIN restrictions” on page 306.
Usage notes
Keys appear in the clear only within the secure boundary of the cryptographic coprocessors, and never in
host storage.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBSPNJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBSPNJ are shown here.
Format
public native void CSNBSPNJ (
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
byte[] in_PIN_blk,
byte[] in_PIN_enc_key_id,
byte[] in_PIN_profile,
byte[] in_PAN_data,
byte[] secmsg_key,
byte[] out_PIN_profile,
byte[] out_PAN_data,
hikmNativeInteger text_length,
byte[] clear_text,
byte[] initialization_vector,
hikmNativeInteger PIN_offset,
hikmNativeInteger PIN_offset_field_length,
byte[] cipher_text,
byte[] output_chaining_value);
354 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Transaction Validation (CSNBTRV)
Transaction Validation (CSNBTRV)
The Transaction Validation verb supports the generation and validation ofAmerican Express card security
codes (CSC). This verb generates and verifies transaction values based on information from the
transaction and a cryptographic key. You select the validation method, and either the generate or verify
mode, through rule_array keywords.
For theAmerican Express process, the control vector supplied with the cryptographic key must indicate a
MAC or MACVER class key. The key can be single or double length. DATAM and DATAMV keys are not
supported. The MAC generate control vector bit must be on (bit 20) if you request CSC generation and
MAC verify bit (bit 21) must be on if you request verification.
Format
CSNBTRV(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
transaction_key_identifier_length,
transaction_key_identifier,
transaction_info_length,
transaction_info,
validation_values_length,
validation_values )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1 or 2.
rule_array
Direction: Input Type: String
Keywords that provide control information to the verb. The keywords are left-justified in an 8-byte field
and padded on the right with blanks. The keywords must be in contiguous storage. The rule_array
keywords are described in Table99.
Table99.KeywordsforTransactionValidationcontrolinformation
Keyword Description
| AmericanExpresscardsecuritycodes(One,required)
CSC-3 3-digitcardsecuritycode(CSC)locatedonthesignaturepanel.VERIFYimplied.Thisisthedefault.
CSC-4 4-digitcardsecuritycode(CSC)locatedonthesignaturepanel.VERIFYimplied.
CSC-5 5-digitcardsecuritycode(CSC)locatedonthesignaturepanel.VERIFYimplied.
CSC-345 Generate5-byte,4-byte,or3-bytevalueswhengivenanaccountnumberandanexpirationdate.
GENERATEimplied.
| Operation(One,optional)
VERIFY Specifiesverificationofthevaluepresentedinthevalidationvaluesvariable.
Chapter9.Financialservices 355

Transaction Validation (CSNBTRV)
Table99.KeywordsforTransactionValidationcontrolinformation (continued)
Keyword Description
GENERATE Specifiesgenerationofthevaluepresentedinthevalidationvaluesvariable.
transaction_key_identifier_length
Direction: Input Type: Integer
The length of the transaction_key_identifier parameter.
transaction_key_identifier
Direction: Input Type: String
The label name or internal token of a MAC or MACVER class key. The key can be single or double
length.
transaction_info_length
Direction: Input Type: Integer
The length of the transaction_info parameter. For theAmerican Express CSC codes, the length must
be 19.
transaction_info
Direction: Input Type: String
ForAmerican Express, this is a 19-byte field containing the concatenation of the 4-byte expiration data
(in the format YYMM) and the 15-byteAmerican Express account number. Provide the information in
character format.
validation_values_length
Direction: Input/Output Type: Integer
The length of the validation_values parameter. Maximum value for this field is 64.
validation_values
Direction: Input Type: String
This variable containsAmerican Express CSC values. The data is output for GENERATE and input for
VERIFY. See Table100.
Table100.ValuesforTransactionValidationvalidation_valuesparameter
Operation Elementdescription
GENERATEandCSC-345 5555544444333where:
55555 = CSC 5 value
4444 = CSC 4 value
333 = CSC 3 value
VERIFYandCSC-3 333=CSC3value
VERIFYandCSC-4 4444=CSC4value
VERIFYandCSC-5 55555=CSC5value
Restrictions
None
356 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Transaction Validation (CSNBTRV)
Required commands
This verb requires the listed commands to be enabled in the active role, depending on the operation and
card security code specified:
||
Cardsecuritycode
|||| Operationkeyword keyword Offset Command
|||| GENERATE CSC-345 X'0291' TransactionValidation-Generate
|||| VERIFY CSC-3 X'0292' TransactionValidation-VerifyCSC-3
||| CSC-4 X'0293' TransactionValidation-VerifyCSC-4
||| CSC-5 X'0294' TransactionValidation-VerifyCSC-5
|
Usage notes
There are additional access control points for this verb.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNBTRVJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNBTRVJ are shown here.
Format
public native void CSNBTRVJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger transaction_key_length,
byte[] transaction_key,
hikmNativeInteger transaction_info_length,
byte[] transaction_info,
hikmNativeInteger validation_values_length,
byte[] validation_values);
Chapter9.Financialservices 357

Transaction Validation (CSNBTRV)
358 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 10. Using digital signatures
This chapter describes the verbs that support using digital signatures to authenticate messages.
v “Digital Signature Generate (CSNDDSG)” on page 360
v “Digital Signature Verify (CSNDDSV)” on page 364
©CopyrightIBMCorp.2007,2011 359

Digital Signature Generate (CSNDDSG)
Digital Signature Generate (CSNDDSG)
| This verb generates a digital signature using an RSAor ECC private key. This verb supports the following
| methods:
| v ANSI X9.30 (ECDSA)
| v ANSI X9.31 (RSA)
| v ISO 9796-1 (RSA)
| v RSADSI PKCS 1.0 and 1.1 (RSA)
| v Padding on the left with zeros (RSA)
| Note: The maximum signature length is 512 bytes (4096 bits).
The input text should have been previously hashed using either the One-Way Hash verb or the MDC
Generate verb. If the signature formatting algorithm specifiesANSI X9.31, you must specify the hash
algorithm used to hash the text (SHA-1 or RPMD-160). See “Formatting hashes and keys in public-key
cryptography” on page 513.
You select the method of formatting the text through the rule_array parameter.
| If the PKA_private_key_identifier specifies an RSAprivate key, you select the method of formatting the text
| through the rule_array parameter. If the PKA_private_key_identifier specifies an ECC private key, the ECC
| signature generated is according toANSI X9.30.
Note: For PKCS the message digest and the message-digest algorithm identifier are combined into an
ASN.1 value of type DigestInfo, which is BER-encoded to give an octet string D (see Table101 on
page 361). D is the text string supplied in the hash variable.
Format
CSNDDSG(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
PKA_private_key_identifier_length,
PKA_private_key_identifier,
hash_length,
hash,
signature_field_length,
signature_bit_length,
signature_field )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 0, 1, 2, or 3.
rule_array
Direction: Input Type: String
360 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Digital Signature Generate (CSNDDSG)
Keywords that provide control information to the verb.Akeyword specifies the method for calculating
the digital signature. Each keyword is left-justified in an 8-byte field and padded on the right with
blanks.All keywords must be in contiguous storage. The rule_array keywords are described in
Table101.
Table101.KeywordsforDigitalSignatureGeneratecontrolinformation
Keyword Description
| Digitalsignatureformattingmethod(One,optionalandnotvalidwithECDSAkeyword.)
ISO-9796 CalculatethedigitalsignatureonthehashaccordingtoISO-9796-1.Anyhashmethodisallowed.
Thisisthedefault.
PKCS-1.0 CalculatethedigitalsignatureontheBER-encodedASN.1valueofthetypeDigestInfocontaining
thehashaccordingtotheRSADataSecurity,Inc.PublicKeyCryptographyStandards#1block
type00.ThetextmusthavebeenhashedandBER-encodedbeforeinputtothisservice.
PKCS-1.1 CalculatethedigitalsignatureontheBER-encodedASN.1valueofthetypeDigestInfocontaining
thehashaccordingtotheRSADataSecurity,Inc.PublicKeyCryptographyStandards#1block
type01.ThetextmusthavebeenhashedandBER-encodedbeforeinputtothisservice.
ZERO-PAD FormatthehashbypaddingitontheleftwithbinaryzerostothelengthoftheRSAkeymodulus.
Anysupportedhashfunctionisallowed.
X9.31 FormataccordingtotheANSIX9.31standard.Theinputtextmusthavebeenpreviouslyhashed
withoneofthehashalgorithmsspecifiedbelow.
| Hashmethodspecification(One,optional.ValidonlywithX9.31digital-signaturehashformattingmethod.)
RPMD-160 HashtheinputtextusingtheRIPEMD-160hashmethod.
SHA-1 HashtheinputtextusingtheSHA-1hashmethod.
SHA-256 HashtheinputtextusingtheSHA-256hashmethod.
SHA-384 HashtheinputtextusingtheSHA-384hashmethod.
SHA-512 HashtheinputtextusingtheSHA-512hashmethod.
| Tokenalgorithm(One,optional)
|| ECDSA GenerateanECCdigitalsignature.ThiskeywordwasintroducedwithCCA4.1.0.Whenspecified,
| thisistheonlykeywordpermittedintherule_array.
|| RSA GenerateanRSAdigitalsignature.Thisisthedefault.ThiskeywordwasintroducedwithCCA
| 4.1.0.
PKA_private_key_identifier_length
Direction: Input Type: Integer
| The length of the PKA_private_key_identifier field. The maximum size is 3500 bytes.
PKA_private_key_identifier
Direction: Input Type: String
| An internal token or label of the RSAprivate key or retained key. If the signature format is X9.31, the
| modulus of the RSAkey must have a minimum length of 1024 bits or greater. If the signature
| algorithm is ECDSA, this parameter must be a token or label of an ECC private key.
hash_length
Direction: Input Type: Integer
| The length of the hash parameter in bytes. It must be the exact length of the text to sign. The
| maximum size is 512 bytes. If you specify ZERO-PAD in the rule_array parameter, the length is
| restricted to 36 bytes unless the RSAkey is a signature only key, then the maximum length is 512
| bytes.
Chapter10.Usingdigitalsignatures 361

Digital Signature Generate (CSNDDSG)
| On the IBM Eserver zSeries® 990 and subsequent releases, the hash length limit is controlled by a
| new access control point. Only RSAkey management keys are affected by this access control point.
| The limit for RSAsignature use only keys is 512 bytes. This new access control point is always
| disabled in the default role. You must have a TKE workstation to enable it.
hash
Direction: Input Type: String
The application-supplied text on which to generate the signature. The input text must have been
previously hashed, and for PKCS formatting, it must be BER-encoded as previously described. For
X9.31, the hash algorithms must have been either SHA-1 or RIPEMD-160. See the rule_array
parameter for more information.
signature_field_length
|| Direction: Input/Output Type: Integer
| The length in bytes of the signature_field to contain the generated digital signature. The maximum size
| is 512 bytes.
| For RSA, this must be at least the RSAmodulus size (rounded up to a multiple of 32 bytes for the
| X9.31 signature format, or one byte for all other signature formats).
| For RSA, this field is updated with the minimum byte length of the digital signature.
| For ECDSAsignature algorithm, R concatenated with S is the digital signature. The maximum output
| value will be 1042 bits (131 bytes). The size of the signature is determined by the size of P. Both R
| and S will have size P. For prime curves, the maximum size is 2 * 521 bits. For Brainpool curves, the
| maximum size is 2 * 512 bits.
signature_bit_length
Direction: Output Type: Integer
| The bit length of the digital signature generated. For ISO-9796 this is 1 less than the modulus length.
| For other RSAprocessing methods, this is the modulus length.
signature_field
Direction: Output Type: String
The digital signature generated is returned in this field. The digital signature is in the low-order bits
(right-justified) of a string whose length is the minimum number of bytes that can contain the digital
signature. This string is left-justified within the signature_field.Any unused bytes to the right are
undefined.
Restrictions
Although ISO-9796 does not require the input hash to be an integral number of bytes in length, this verb
requires you to specify the hash_length in bytes.
X9.31 requires the RSAtoken to have a minimum modulus bit length of 1024 bits, and the length must
also be a multiple of 256 bits (or 32 bytes).
The length of the hash parameter in bytes. It must be the exact length of the text to sign. The maximum
size is 256 bytes. If you specify ZERO-PAD in the rule_array parameter, the length is restricted to 36 bytes
unless the RSAkey is a signature only key, then the maximum length is 256 bytes.
The hash length limit is controlled by an access control point. If OFF (disabled), the maximum hash length
limit for ZERO-PAD is the modulus length of the PKAprivate key. If ON (enabled), the maximum hash
length limit for ZERO-PAD is 36 bytes. Only RSAkey management keys are affected by this access
control point. The limit for RSAsignature use only keys is 256 bytes. This new access control point is
always disabled in the Default role. You must have a TKE workstation to enable it.
362 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Digital Signature Generate (CSNDDSG)
Required commands
| This verb requires the Digital Signature Generate command (offset X'0100') to be enabled in the active
| role.
| With the use of the DSG ZERO-PAD unrestricted hash length command (offset X'030C'), the hash-length
| restriction does not apply when using ZERO-PAD formatting.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDDSGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDDSGJ are shown here.
Format
public native void CSNDDSGJ
( hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger 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 );
Chapter10.Usingdigitalsignatures 363

Digital Signature Verify (CSNDDSV)
Digital Signature Verify (CSNDDSV)
| This verb verifies a digital signature using an RSAor ECC public key. This verb verifies digital signatures
| generated with these methods:
| v ANSI X9.30 (ECDSA)
| v ANSI X9.31 (RSA)
| v ISO 9796-1 (RSA)
| v RSADSI PKCS 1.0 and 1.1 (RSA)
| v Padding on the left with zeros (RSA)
| This verb can use the RSAor ECC public key, depending on the digital signature algorithm used to
| generate the signature.
| This verb can also use the public keys that are contained in trusted blocks, regardless of whether the
| block also contains rules to govern its use when generating or exporting keys with the Remote Key Export
| verb. The format of the trusted block enables Digital Signature Verify to distinguish it from other RSAkey
| tokens, and therefore no special rule array keyword or other parameters are required in order to indicate
| that the trusted block is being used. However, if the Digital Signature Generate verb is used with the
| TPK-ONLY keyword in the rule_array, an error will occur if the PKA_public_key_identifier does not contain
| a trusted block.
Input text should have been previously hashed. You can use the One-Way Hash verb. See also
“Formatting hashes and keys in public-key cryptography” on page 513.
Note: The maximum signature length is 256 bytes (2048 bits).
Format
CSNDDSV(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
PKA_public_key_identifier_length,
PKA_public_key_identifier,
hash_length,
hash,
signature_field_length,
signature_field )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 0, 1, 2, or 3.
rule_array
Direction: Input Type: String
364 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Digital Signature Verify (CSNDDSV)
Keywords that provide control information to the verb.Akeyword specifies the method to use to verify
the digital signature. Each keyword is left-justified in an 8-byte field and padded on the right with
blanks.All keywords must be in contiguous storage. The rule_array keywords are described in
Table102.
Table102.KeywordsforDigitalSignatureVerifycontrolinformation
Keyword Description
| Digitalsignatureformattingmethod(OptionalandnotvalidwithECDSAkeyword.)
ISO-9796 VerifythedigitalsignatureonthehashaccordingtoISO-9796-1.Anyhashmethodisallowed.This
isthedefault.
PKCS-1.0 VerifythedigitalsignatureontheBER-encodedASN.1valueofthetypeDigestInfoasspecifiedin
theRSADataSecurity,Inc.PublicKeyCryptographyStandards#1blocktype00.Thetextmust
specifyBERencodedhashtext.
PKCS-1.1 VerifythedigitalsignatureontheBER-encodedASN.1valueofthetypeDigestInfoasspecifiedin
theRSADataSecurity,Inc.PublicKeyCryptographyStandards#1blocktype01.Thetextmust
specifyBERencodedhashtext.
ZERO-PAD FormatthehashbypaddingitontheleftwithbinaryzerostothelengthofthePKAkeymodulus.
Anysupportedhashfunctionisallowed.
X9.31 FormataccordingtoANSIX9.31standard.
| Trustedpublickeyrestriction(Optional.NotvalidwithECDSAkeyword.Validonlywithtrustedblocks.See
| “Trustedblocks”onpage444.)
TPK-ONLY Permitstheuseofonlypublickeyscontainedintrustedblocks.Byspecifyingthiskeyword,theuse
ofregularCCARSAkeytokensisrejectedandonlytheuseofa(trusted)publickeysuppliedby
thePKA_public_key_identifierparametercanbeusedtoverifythedigitalsignature,thusassuringa
sensitivesignatureverificationoperationislimitedtotrustedpublickeys.
IfTPK-ONLYisspecified,thePKA_public_key_identifierparametermustidentifyatrustedblock
thatcontainstwosectionsafterthetrustedblocktokenheader:(1)trustedblocktrustedRSApublic
key(sectionX'11'),and(2)trustedblockinformation(sectionX'14').SectionX'14'isrequiredforall
trustedblocks.SectionX'11'containsthetrustedpublickey,anditsusagerulesmustindicateit
canbeusedindigitalsignatureoperations.
| Tokenalgorithm(One,optional)
|| ECDSA VerifyanECCdigitalsignature.ThiskeywordwasintroducedwithCCA4.1.0.Whenspecified,this
| istheonlykeywordpermittedintherule_array.
|| RSA VerifyanRSAdigitalsignature.Thisisthedefault.ThiskeywordwasintroducedwithCCA4.1.0.
PKA_public_key_identifier_length
Direction: Input Type: Integer
| The length of the PKA_public_key_identifier field containing the public key token or label. The
| maximum size is 3500 bytes.
PKA_public_key_identifier
Direction: Input Type: String
| Atoken or label of the RSApublic key or internal trusted block. If the signature algorithm is ECDSA,
| this must be a token label or an ECC public key.
hash_length
Direction: Input Type: Integer
| The length of the hash parameter in bytes. It must be the exact length of the text that was signed. The
| maximum size is 512 bytes.
hash
Chapter10.Usingdigitalsignatures 365

Digital Signature Verify (CSNDDSV)
Direction: Input Type: String
The application-supplied text on which the supplied signature was generated. The text must have been
previously hashed and, for PKCS formatting, BER-encoded as previously described.
signature_field_length
Direction: Input Type: Integer
| The length in bytes of the signature_field parameter. The maximum size is 512 bytes.
signature_field
Direction: Input Type: String
This field contains the digital signature to verify. The digital signature is in the low-order bits
(right-justified) of a string whose length is the minimum number of bytes that can contain the digital
signature. This string is left-justified within the signature_field.
Restrictions
The ability to recover a message from a signature (which ISO-9796 allows but does not require) is not
supported.
The exponent of the RSApublic key must be odd.
Although ISO-9796 does not require the input hash to be an integral number of bytes in length, this
service requires you to specify the hash_length in bytes.
X9.31 requires the RSAtoken to have a minimum modulus bit length of 1024, and the length must also be
a multiple of 256 bits (or 32 bytes).
Required commands
| This verb requires the Digital Signature Verify command (offset X'0101') to be enabled in the active role.
Usage notes
None
Related information
Trusted Block Create (CSNDTBC), Remote Key Export (CSNDRKX)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDDSVJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDDSVJ are shown here.
366 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Digital Signature Verify (CSNDDSV)
Format
public native void CSNDDSVJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger PKA_public_key_identifier_length,
byte[] PKA_public_key_identifier,
hikmNativeInteger hash_length,
byte[] hash,
hikmNativeInteger signature_field_length,
byte[] signature_field );
Chapter10.Usingdigitalsignatures 367

Digital Signature Verify (CSNDDSV)
368 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Chapter 11. Managing PKA cryptographic keys
This chapter describes the verbs that generate and manage PKAkeys.
v “PKAKey Generate (CSNDPKG)” on page 370
v “PKAKey Import (CSNDPKI)” on page 374
v “PKAKey Token Build (CSNDPKB)” on page 377
v “PKAKey Token Change (CSNDKTC)” on page 385
v “PKAKey Translate (CSNDPKT)” on page 388
v “PKAPublic Key Extract (CSNDPKX)” on page 392
| v “Remote Key Export (CSNDRKX)” on page 394
| v “Trusted Block Create (CSNDTBC)” on page 403
©CopyrightIBMCorp.2007,2011 369

PKA Key Generate (CSNDPKG)
PKA Key Generate (CSNDPKG)
| Use the PKAKey Generate verb to generate RSAkeys for use on the cryptographic coprocessor or other
| CCAsystems, or ECC keys for use on the CEX3C. Input to the PKAKey Generate verb is either a
| skeleton key token that has been built by the PKAKey Token Build verb, or a valid internal token. In the
| case of a valid internal token, the PKAKey Generate verb will generate a key with the same modulus
| length and the same exponent.
| Input to the PKAKey Generate verb is either a skeleton key token that has been built by the PKAKey
| Token Build verb, or a valid internal token. In the case of a valid internal token, the verb will generate a
| key with the same modulus length and the same exponent. In the case of a valid internal ECC token, PKA
| Key Generate will generate a key based on the curve type and size. Internal tokens with a X'09' section
| are not supported.
RSAkey generation requires the following information in the input skeleton token:
| v Size of the modulus in bits. The modulus for Modulus-Exponent format keys is between 512 and 1024
| bits in length. The CRT modulus is between 512 and 4096 bits in length. The modulus for the
| variable-length Modulus-Exponent format is between 512 and 4096 bits in length.
RSAkey generation has the following restrictions:
v For Modulus-Exponent, there are restrictions on modulus, public exponent, and private exponent.
v For CRT, there are restrictions on dp, dq, U, and public exponent.
See the Key value structure in “PKAKey Token Build (CSNDPKB)” on page 377 for a summary of
restrictions.
| ECC key generation requires this information in the skeleton token:
| v The key type: ECC
| v The type of curve: Prime or Brainpool
| v The size of p in bits: 192, 224, 256, 384 or 521 for Prime curves and 160, 192, 224, 256, 320, 384, or
| 512 for Brainpool curves
| v Key usage information
| v Optionally, application associated data
| The generated ECC private key will be returned in one of the following forms:
| v Clear key
| v Encrypted key enciphered under the APKA-MK
| v Encrypted key enciphered by a transport key
Format
CSNDPKG(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
regeneration_data_length,
regeneration_data,
skeleton_key_identifier_length,
skeleton_key_identifier,
transport_key_identifier,
generated_key_token_length,
generated_key_token )
370 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Generate (CSNDPKG)
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1 or 2.
rule_array
Direction: Input Type: String
Akeyword that provides control information to the verb.Akeyword is left-justified in an 8-byte field and
padded on the right with blanks. The rule_array keywords are described in Table103.
Table103.KeywordsforPKAKeyGeneratecontrolinformation
Keyword Description
| Privatekeyencryption(One,required)
CLEAR Returntheprivatekeyincleartext.Theprivatekeyincleartextisanexternaltoken.
MASTER Enciphertheprivatekeyunderthemasterkey.
RETAIN Retainstheprivatekeywithinthecryptographicengineandreturnsthepublickey.Thisisonly
validforRSAsignaturekeys.Becauseofthis,theRETAINkeywordisnotsupportedfor:
v AskeletontokenwithaX'09'sectionprovided.
v AnECCtoken.
Beforeusingthiskeyword,seetheinformationaboutretainedkeysin“Usingretainedkeys”on
page299.
Note: Takespecialnoticeonthetypesofskeletonkeytokensthatcanbepassed.ThePKA
KeyTokenBuildverbwill,ofcourse,letyoucreatemanymoretypesofskeletonkeytokens
thancanbeusedtogenerateretainedkeys,becausethisistheminorityofsupportedfunction.
| XPORT EncipherstheprivatekeyundertheIMPORTERorEXPORTERkey-encrypting-keyidentifiedby
| thetransport_key_identifierparameter.ValidonlyforRSAkeys.IgnoredforECCkeys.
Regenerationdataoption(One,optional)
|| ITER-38 Force38iterationsoftestsforprimality,asrequiredbyANSIX9.31fortheMiller-Rabinprimality
| tests.Thisoptionproducesamoresecurekey,butitislaborintensive.Thiskeywordisinvalid
| forECCkeygeneration.ThiskeywordwasintroducedwithCCA4.1.0.
regeneration_data_length
Direction: Input Type: Integer
| The regeneration_data_length parameter must be 0 for ECC tokens. For RSAtokens, the
| regeneration_data_length can be nonzero. If it is nonzero, it must be between 8 and 512 bytes
| inclusive.
regeneration_data
Direction: Input Type: String
This field points to a string variable containing a string used as the basis for creating a particular
public-private key pair in a repeatable manner.
skeleton_key_identifier_length
Direction: Input Type: Integer
| The length of the skeleton_key_identifier parameter in bytes. The maximum allowed value is 3500
| bytes.
Chapter11.ManagingPKAcryptographickeys 371

PKA Key Generate (CSNDPKG)
skeleton_key_identifier
Direction: Input Type: String
| The application-supplied skeleton key token generated by PKAKey Token Build, or the label of the
| token that contains the required modulus length and public exponent for RSAkey generation, or the
| required curve type and bit length for ECC key generation.
| If RETAIN was specified and the skeleton_key_identifier is a label, the label must match the private
| key name of the key. For RSAkeys, the skeleton_key_identifier parameter must contain a token that
| specifies a modulus length in the range 512 - 4096 bits.
transport_key_identifier
Direction: Input Type: String
A64-byte field to contain a DES key identifier. This field must be binary zeros, unless the XPORT rule
is specified. For XPORT rule, this is an IMPORTER or EXPORTER key or the label of an IMPORTER
or EXPORTER key that is used to encrypt the generated key. If you specify a label, it must resolve
uniquely to either an IMPORTER or EXPORTER key. Valid only for RSAkeys.
generated_key_token_length
Direction: Input/Output Type: Integer
| The length of the generated key token. The field is checked to ensure that it is at least equal to the
| token being returned. The maximum size is 3500 bytes. On output, this field is updated with the actual
| token length.
generated_key_token
Direction: Input/Output Type: String
| The internal token or label of the generated RSAor ECC key. If a label is specified in the
| generated_key_token parameter, the generated_key_token_length returned to the application will be
| the same as the input length. If a label is specified in the generated_key_token parameter, a record
| must already exist in the PKAkey storage file with this same label or the service will fail.
Restrictions
| 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 CCAsupport a CRT form of the RSAprivate key; check the
| product-specific literature. The IBM implementations support an optimized RSAprivate key (a key in
| Chinese Remainder Theorem format). The formats vary between versions.
| v See “PKAkey tokens” on page 48 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 withANSI 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 PKAkey-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.0.
| v ECC key tokens are not supported in releases before Release 4.1.0.
Required commands
| This verb requires the PKAKey Generate command (offset X'0103') to be enabled in the active role.
| With the CLEAR rule-array keyword, enable PKAKey Generate - Clear (offset X'0205' in the hardware.
372 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Generate (CSNDPKG)
| To generate ECC keys with the CLEAR rule-array keyword, this verb requires the Generate ECC keys in
| the clear command (offset X'0326') to be enabled in the active role.
To generate keys based on the value supplied in the regeneration_data variable, you must enable one of
these commands:
| v When not using the RETAIN keyword, enable the PKAKey Generate - Permit Regeneration Data
| command (offset X'027D').
| v When using the RETAIN keyword, enable the PKAKey Generate - Permit Regeneration Data Retain
| command (offset X'027E').
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKGJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKGJ are shown here.
Format
public native void CSNDPKGJ (
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger 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 );
Chapter11.ManagingPKAcryptographickeys 373

PKA Key Import (CSNDPKI)
PKA Key Import (CSNDPKI)
| This verb imports an external PKAor ECC private key token. (This consists of a PKAor ECC private key
| and public key.) The secret values of the key can be clear or encrypted under a limited-authority DES
| importer key.
This verb can also import a clear PKAkey. The PKAKey Token Build verb creates a clear PKAkey token.
Output of this verb is a CCAinternal token of the RSAprivate key.
Format
CSNDPKI(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
source_key_identifier_length,
source_key_identifier,
importer_key_identifier,
target_key_identifier_length,
target_key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 0 or 1.
rule_array
|| Direction: Input Type: String
| The rule_array parameter is a pointer to a string variable containing a keyword. The keyword is 8
| bytes in length and must be left-aligned and padded on the right with space characters. The rule_array
| keywords are described in Table104.
|| Table104.KeywordsforPKAKeyImportcontrolinformation
|| Keyword Description
| Tokentype(One,optional)
|| ECC SpecifiesthatthekeybeingimportedisanECCkey.ThiskeywordwasintroducedwithCCA
| 4.1.0.
|| RSA SpecifiesthatthekeybeingimportedisanRSAkeyoratrustedblock.Thisisthedefault.This
| keywordwasintroducedwithCCA4.1.0.
|
| source_key_identifier_length
Direction: Input Type: Integer
| The length of the source_key_identifier parameter. The maximum size is 3500 bytes.
source_key_identifier
374 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Import (CSNDPKI)
|| Direction: Input Type: String
| Contains an external token or label of a PKAprivate key, without section identifier X'14' (Trusted Block
| Information), or the trusted block in external form as produced by the Trusted Block Create verb with
| theACTIVATE keyword.
| If a PKAprivate key without the section identifier X'14' is passed in:
| v There are no qualifiers.Aretained key can not be used.
| v The key token must contain both public-key and private-key information. The private key can be in
| cleartext or it can be enciphered. ECC tokens must contain a private key in cleartext.
| v This is the output of the PKAKey Generate (CSNDPKG) verb or the PKAKey Token Build
| (CSNDPKB) verb.
| v If encrypted, the key was created on another platform.
| If a PKAprivate key with the section identifier X'14' is passed in:
| v This verb will be used to encipher the MAC key within the trusted block under the PKAmaster key
| instead of the IMP-PKAkey-encrypting key.
| v The importer_key_identifier must contain an IMP-PKAKEK.
importer_key_identifier
Direction: Input/Output Type: String
ADES internal token or the label of an IMP-PKAkey. This is a limited authority key-encrypting key. It
is ignored for clear tokens.
target_key_identifier_length
Direction: Input/Output Type: Integer
| The length of the target_key_identifier parameter. The maximum size 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
| field.
target_key_identifier
Direction: Input/Output Type: String
| This field contains the internal token or label of the imported PKAprivate key or a trusted block. If a
| label is specified on input, a PKAkey storage record with this label must exist. The PKAkey storage
| record with this label will be overwritten with the imported key unless the existing record is a retained
| key. If the record is a retained key, the import will fail.Aretained key record cannot be overwritten. If
| no label is specified on input, this field should be set to binary zeros on input.
Restrictions
This verb imports RSAkeys of up to 2048 bits. However, the hardware configuration sets the limits on the
modulus size of keys for digital signatures and key management; thus, the key can be successfully
imported but fail when used if the limits are exceeded.
The importer_key_identifier parameter is a limited-authority key-encrypting key.
CRT form tokens with a private section ID of X'05' cannot be imported.
Required commands
| This verb requires the PKAKey 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 PKAKey Import - Import an
| External Trusted Key Block to internal form command (offset X'0311').
Chapter11.ManagingPKAcryptographickeys 375

PKA Key Import (CSNDPKI)
Usage notes
This verb imports keys of any modulus size up to 2048 bits. However, the hardware configuration sets the
limits on the modulus size of keys for digital signatures and key management; thus, the key can be
successfully imported but fail when used if the limits are exceeded.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKIJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKIJ are shown here.
Format
public native void CSNDPKIJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger source_key_token_length,
byte[] source_key_token,
byte[] transport_key_identifier,
hikmNativeInteger target_key_identifier_length,
byte[] target_key_identifier
);
376 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Token Build (CSNDPKB)
PKA Key Token Build (CSNDPKB)
| Use this verb to build external PKAkey tokens containing unenciphered private RSAor ECC keys. You
| can use this token as input to the PKAKey Import verb to obtain an operational internal token containing
| an enciphered private key. This verb builds a skeleton token that you can use as input to the PKAKey
| Generate verb (see Table103 on page 371). You can also input to this verb a clear unenciphered public
| RSAor ECC key and return the public key in a token format that other PKAverbs can use directly.
| This verb is used to create the following:
| v Askeleton_key_token for use with the PKAKey Generate verb.
| v Akey token with a public key that has been obtained from another source.
| v Akey token with a clear private-key and the associated public key.
| v Akey token for an RSAprivate key in optimized Chinese Remainder Theorem (CRT) format.
| v An RSAtoken with X'09' section identifier using the RSAMEVAR keyword to obtain a token for a key in
| Modulus-Exponent format that is variable length.
| ECC key generation requires this information in the skeleton token:
| v The key type: ECC
| v The type of curve: Prime or Brainpool
| v The size of p in bits: 192, 224, 256, 384 or 521 for Prime curves and 160, 192, 224, 256, 320, 384, or
| 521 for Brainpool curves
| v Key usage information
| v Optionally, application associated data
Format
CSNDPKB(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_value_structure_length,
key_value_structure,
private_key_name_length,
private_key_name,
| customer_data_length,
| customer_data,
reserved_2_length,
reserved_2,
reserved_3_length,
reserved_3,
reserved_4_length,
reserved_4,
reserved_5_length,
reserved_5,
key_token_length,
key_token )
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 14.
rule_array_count
Direction: Input Type: Integer
Chapter11.ManagingPKAcryptographickeys 377

PKA Key Token Build (CSNDPKB)
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1, 2, or 3.
rule_array
Direction: Input Type: String
One or two keywords that provide control information to the verb. The keywords must be in contiguous
storage with each of the keywords left-justified in its own 8-byte location and padded on the right with
blanks. The rule_array keywords are described in Table105.
Table105.KeywordsforPKAKeyTokenBuildcontrolinformation
Keyword Description
| Keytype(One,required)
|| ECC-PAIR ThiskeywordindicatesbuildingatokencontainingbothpublicandprivateECCkeyinformation.
| Theparameterkey_value_structureidentifiestheinputkeyvalues,ifsupplied.
|| ECC-PUBL ThiskeywordindicatesbuildingatokencontainingpublicECCkeyinformation.Theparameter
| key_value_structureidentifiestheinputvalues,ifsupplied.
RSA-CRT ThiskeywordindicatesbuildingatokencontaininganRSAprivatekeyintheoptimizedChinese
RemainderTheorem(CRT)format.Theparameterkey_value_structureidentifiestheinputkey
values,ifsupplied.
RSA-PRIV ThiskeywordindicatesbuildingatokencontainingbothpublicandprivateRSAkeyinformation.
Theparameterkey_value_structureidentifiestheinputkeyvalues,ifsupplied.
RSA-PUBL ThiskeywordindicatesbuildingatokencontainingpublicRSAkeyinformation.Theparameter
key_value_structureidentifiestheinputvalues,ifsupplied.
|| RSAMEVAR ThiskeywordindicatesRSA-ModulusExponent-Variant(RSAMEVAR),atypeX'09'keytokenfor
| RSA,namedVAR_OPK.
| Note: KeytokenscreatedwiththiskeytypecannotbepassedtothePKAKeyGenerateverbfor
| creatingRETAIN(retained)keys.
| Keyusagecontrol(One,optional)
|| KEY-MGMT IndicatesthatanRSAorECCprivatekeycanbeusedinboththeSymmetricKeyImportandthe
| DigitalSignatureGenerateverbs.
| Note: KeytokenscreatedwiththiskeyusagecannotbepassedtothePKAKeyGenerateverb
| forcreatingRETAIN(retained)keys.
|| KM-ONLY IndicatesthatanRSAorECCprivatekeycanbeusedonlyinsymmetrickeydistribution.
| Note: KeytokenscreatedwiththiskeyusagecannotbepassedtothePKAKeyGenerateverb
| forcreatingRETAIN(retained)keys.
|| SIG-ONLY IndicatesthatanRSAorECCprivatekeycannotbeusedinsymmetrickeydistribution.Thisisthe
| default.
| Note: OnlyaskeletontokencreatedfromPKAKeyTokenBuildwiththiskeyusagetypecanbe
| passedtoPKAKeyGeneratetocreateaRETAIN(retained)key.
| Translatecontrol(One,optional)
|| NO-XLATE TheRSAorECCkeycannotbeusedasakey-encrypting-keyfor“PKAKeyTranslate(CSNDPKT)”
| onpage388.
| Note: Useofthiskeyworddoesnotmatterwhencreatingaskeletonkeytokenforalaterretained
| keygenerationoperation.ItisredundanttothenecessarySIG-ONLYkeyword.
|| XLATE-OK TheRSAorECCkeycanbeusedasakey-encrypting-keyfor“PKAKeyTranslate(CSNDPKT)”on
| page388.
| Note: KeytokenscreatedwiththiskeywordcannotbepassedtothePKAKeyGenerateverbfor
| creatingRETAIN(retained)keys.
key_value_structure_length
Direction: Input Type: Integer
378 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Token Build (CSNDPKB)
This is a segment of contiguous storage containing a variable number of input clear key values. The
length depends on the key type parameter in the rule_array and on the actual values input. The length
is in bytes. For maximum values, see Table106.
|| Table106.PKAKeyTokenBuild-Keyvaluestructurelengthmaximumvalues
|| Keytype Keyvaluestructuremaximumvalue
|| ECC-PAIR 207
|| ECC-PUBL 139
|| RSA-CRT,RSAMEVAR 3500
|| RSA-PRIV 648
|| RSA-PUBL 520
|
key_value_structure
Direction: Input Type: String
This is a segment of contiguous storage containing a variable number of input clear key values and
the lengths of these values in bits or bytes, as specified. The structure elements are ordered, of
variable length, and the input key values must be right-justified within their respective structure
elements and padded on the left with binary zeros. If the leading bits of the modulus are zeros, do not
count them in the length. Table107 defines the structure and contents as a function of key type.
Table107.PKAKeyTokenBuild-Keyvaluestructureelements
Length
Offset (bytes) Description
| Keyvaluestructure(ECC-PAIR)
000 001 Curvetype:
X'00' Primecurve
X'01' Brainpoolcurve
||| 001 001 ReservedX'00'
||| 002 002 Lengthofpinbits
|| X'00A0' Brainpoolp-160
|| X'00C0' PrimeP-192,BrainpoolP-192
|| X'00E0' PrimeP-224,BrainpoolP-224
|| X'0100' PrimeP-256,BrainpoolP-256
|| X'0140' BrainpoolP-320
|| X'0180' PrimeP-384,BrainpoolP-384
|| X'0200' BrainpoolP-512
|| X'0209' PrimeP-521
||| 004 002 ddd-thisfieldisthelengthoftheprivatekeydinbytes.Thisvaluecanbezeroifthe
| keytokenisusedasaskeletonkeytokeninthePKAKeyGenerateverb.The
| maximumvalueis66bytes.
||| 006 002 xxx-thisfieldisthelengthofthepublickeyQinbytes.Thisvaluecanbezeroifthe
| keytokenisusedasaskeletonkeytokeninthePKAKeyGenerateverb.The
| maximumvalueis133bytes,whichincludesonebytetoindicateifthevalueis
| compressed.
||| 008 ddd Privatekey,d
||| 008+ddd xxx Publickey,Q
| Keyvaluestructure(ECC-PUBL)
000 001 Curvetype:
X'00' Primecurve
X'01' Brainpoolcurve
||| 001 001 ReservedX'00'
Chapter11.ManagingPKAcryptographickeys 379

PKA Key Token Build (CSNDPKB)
Table107.PKAKeyTokenBuild-Keyvaluestructureelements (continued)
Length
Offset (bytes) Description
||| 002 002 Lengthofpinbits
|| X'00A0' Brainpoolp-160
|| X'00C0' PrimeP-192,BrainpoolP-192
|| X'00E0' PrimeP-224,BrainpoolP-224
|| X'0100' PrimeP-256,BrainpoolP-256
|| X'0140' BrainpoolP-320
|| X'0180' PrimeP-384,BrainpoolP-384
|| X'0200' BrainpoolP-512
|| X'0209' PrimeP-521
||| 004 002 xxx-thisfieldisthelengthofthepublickeyQinbytes.Thisvaluecanbezeroifthe
| keytokenisusedasaskeletonkeytokeninthePKAKeyGenerateverb.The
| maximumvalueis133bytes,whichincludesonebytetoindicateifthevalueis
| compressed.
||| 006 xxx Publickey,Q
Keyvaluestructure(OptimizedRSA,ChineseRemainderTheoremformat,RSA-CRT)
000 002 Moduluslengthinbits(512-2048).Thisisrequired.
002 002 Modulusfieldlengthinbytes,“nnn.”Thisvaluecanbezeroifthekeytokenisused
asaskeleton_key_tokeninthePKAKeyGenerateverb.Thisvaluemustnotexceed
256.
004 002 Publicexponentfieldlengthinbytes,“eee.”Thisvaluecanbezeroifthekeytokenis
usedasaskeleton_key_tokeninthePKAKeyGenerateverb.
006 002 Reserved,binaryzero.
008 002 Lengthoftheprimenumber,p,inbytes,“ppp.”Thisvaluecanbezeroifthekey
tokenisusedasaskeleton_key_tokeninthePKAKeyGenerateverb.Maximumsize
ofp+qis256bytes.
010 002 Lengthoftheprimenumber,q,inbytes,“qqq.”Thisvaluecanbezeroifthekey
tokenisusedasaskeleton_key_tokeninthePKAKeyGenerateverb.Maximumsize
ofp+qis256bytes.
012 002 Lengthofd ,inbytes,“rrr.”Thisvaluecanbezeroifthekeytokenisusedasa
p
skeleton_key_tokeninthePKAKeyGenerateverb.Maximumsizeofd +d is256
p q
bytes.
014 002 Lengthofd ,inbytes,“sss.”Thisvaluecanbezeroifthekeytokenisusedasa
q
skeleton_key_tokeninthePKAKeyGenerateverb.Maximumsizeofd +d is256
p q
bytes.
016 002 LengthofU,inbytes,“uuu.”Thisvaluecanbezeroifthekeytokenisusedasa
skeleton_key_tokeninthePKAKeyGenerateverb.MaximumsizeofUis256bytes.
018 nnn Modulus,n.
018+nnn eee Publicexponent,e.Thisisanintegersuchthat1<e<n.emustbeodd.Whenyou
arebuildingaskeleton_key_tokentocontrolthegenerationofanRSAkeypair,the
publickeyexponentcanbeoneofthefollowingvalues:3,65537(216+1),or0to
indicatethatafullrandomexponentshouldbegenerated.Theexponentfieldcanbe
anull-lengthfieldiftheexponentvalueis0.
018+nnn+ ppp Primenumber,p.
eee
018+nnn+ qqq Primenumber,q.
eee+ppp
018+nnn+ rrr d =dmod(p-1).
p
eee+ppp+
qqq
380 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Token Build (CSNDPKB)
Table107.PKAKeyTokenBuild-Keyvaluestructureelements (continued)
Length
Offset (bytes) Description
018+nnn+ sss d =dmod(q-1).
q
eee+ppp+
qqq+rrr
018+nnn+ uuu U=q–1mod(p).
eee+ppp+
qqq+rrr+
sss
| Keyvaluestructure(RSAprivate,RSAprivatevariable,orRSApublic)
000 002 Moduluslengthinbits.Thisisrequired.Whenbuildingaskeletontoken,themodulus
lengthinbitsmustbegreaterthanorequalto512bits.
002 002 Modulusfieldlengthinbytes,“XXX.”Thisvaluecanbezeroifyouareusingthekey
tokenasaskeletoninthePKAKeyGenerateverb.Thisvaluemustnotexceed256
whentheRSA-PUBLkeywordisusedandmustnotexceed128whentheRSA-PRIV
keywordisused.
ThisverbcanbuildakeytokenforapublicRSAkeywitha2048-bitmoduluslength
oritcanbuildakeytokenfora1024-bitmoduluslengthprivatekey.
004 002 Publicexponentfieldlengthinbytes,“YYY.”Thisvaluemustnotexceed256when
theRSA-PUBLkeywordisusedandmustnotexceed128whentheRSA-PRIV
keywordisused.Thisvaluecanbezeroifyouareusingthekeytokenasaskeleton
tokeninthePKAKeyGenerateverb.Inthiscase,arandomexponentisgenerated.
Toobtainafixed,predeterminedpublickeyexponent,youcansupplythisfieldand
thepublicexponentasinputtothePKAKeyGenerateverb.
006 002 Privateexponentfieldlengthinbytes,“ZZZ.”Thisfieldcanbezero,indicatingthat
privatekeyinformationisnotprovided.Thisvaluemustnotexceed128bytes.This
valuecanbezeroifyouareusingthekeytokenasaskeletontokeninthePKAKey
Generateverb.
008 XXX Modulus,n.Thisisanintegersuchthat1<n<22048.Thenistheproductofpandq
forprimespandq.
008+XXX YYY RSApublicexponent,e.Thisisanintegersuchthat1<e<n.emustbeodd.When
youarebuildingaskeleton_key_tokentocontrolthegenerationofanRSAkeypair,
thepublickeyexponentcanbeoneofthefollowingvalues:3,65537(216+1),or0to
indicatethatafullrandomexponentshouldbegenerated.Theexponentfieldcanbe
anull-lengthfieldiftheexponentvalueis0.
008+XXX+ ZZZ RSAsecretexponentd.Thisisanintegersuchthat1<d<n.Thevalueofdise-1
YYY mod(p-1)(q-1).YouneednotspecifythisvalueifyouspecifyRSA-PUBLinthe
rule_arrayparameter.
Notes:
1. All length fields are in binary.
2. All binary fields (exponent, lengths, modulus, and so on) are stored with the high-order byte field
first. This integer number is right-justified within the key structure element field.
| 3. You must supply all values in the structure to create a token containing an RSAor ECC private key
| for input to the PKAKey Import verb.
private_key_name_length
Direction: Input Type: Integer
The length can be 0 or 64.
private_key_name
Chapter11.ManagingPKAcryptographickeys 381

PKA Key Token Build (CSNDPKB)
Direction: Input Type: EBCDIC character
This field contains the name of a private key. The name must conform to CCAkey label syntax rules.
That is, allowed characters are alphanumeric, national (@, #, $) or period (.). The first character must
be alphabetic or national. The name is folded to upper case and converted toASCII characters.ASCII
is the permanent form of the name because the name should be independent of the platform. The
name is then cryptographically coupled with clear private key data before encryption of the private key.
Because of this coupling, the name can never change after the key token is imported. The parameter
is valid only with key type RSA-CRT.
| customer_data_length
|| Direction: Input Type: Integer
| Length in bytes of the customer_data parameter. This parameter is valid only for a key type of
| ECC-PAIR, and must be set to 0 for all other key types.
| customer_data
|| Direction: Input Type: String
| The customer_data parameter identifies a string variable containing the associated data that will be
| placed following the IBM associated data in the token. The associated data is data whose integrity, but
| not whose confidentiality, is protected by a key wrap mechanism. The customer_data can be used to
| bind usage control information.
| This parameter is valid only for a key type of ECC-PAIR.
reserved_2_length
Direction: Input Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_2
Direction: Input Type: String
The reserved_2 parameter identifies a string that is reserved. The verb ignores it.
reserved_3_length
Direction: Input Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_3
Direction: Input Type: String
The reserved_3 parameter identifies a string that is reserved. The verb ignores it.
reserved_4_length
Direction: Input Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_4
Direction: Input Type: String
The reserved_4 parameter identifies a string that is reserved. The verb ignores it.
reserved_5_length
Direction: Input Type: Integer
Length in bytes of a reserved parameter. You must set this variable to 0.
reserved_5
382 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Token Build (CSNDPKB)
Direction: Input Type: String
The reserved_5 parameter identifies a string that is reserved. The verb ignores it.
key_token_length
Direction: Input/Output Type: Integer
| Length of the returned key token. The verb checks the field to ensure that it is at least equal to the
| size of the token to return. On return from this verb, this field is updated with the exact length of the
| key_token created. On input, a size of 3500 bytes is sufficient to contain the largest key_token
| created.
key_token
Direction: Output Type: String
The returned key token containing an unenciphered private or public key. The private key is in an
external form that can be exchanged with different CCAPKAsystems. You can use the public key
token directly in appropriate CCAsignature verification or key management services.
Restrictions
None
Required commands
None
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKBJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKBJ are shown here.
Chapter11.ManagingPKAcryptographickeys 383

PKA Key Token Build (CSNDPKB)
Format
public native void CSNDPKBJ
( hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger key_values_structure_length,
byte[] key_values_structure,
hikmNativeInteger key_name_length,
byte[] key_name,
| hikmNativeInteger customer_data_length,
| byte[] customer_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 );
384 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Token Change (CSNDKTC)
PKA Key Token Change (CSNDKTC)
| The PKAKey Token Change verb changes PKAkey tokens (RSAor ECC) or trusted block key tokens,
| from encipherment under oldASYM-MK orAPKA-MK, to encipherment under the currentASYM-MK or
| APKA-MK master key.
| v For RSAkey tokens - Key tokens must be private internal PKAkey tokens in order to be changed by
| this verb. PKAprivate keys encrypted under the Key Management Master Key (KMMK) cannot be
| reenciphered using this services unless the KMMK has the same value as the Signature Master Key
| (SMK).
| v For trusted block key tokens - Trusted block key tokens must be internal.
| v For ECC key tokens - Key tokens must be private internal ECC key tokens encrypted under the
| APKA-MK.
Format
CSNDKTC(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
key_identifier_length,
key_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
| Apointer to an integer variable containing the number of elements in the rule_array variable. This
| value must be 1 or 2.
rule_array
Direction: Input Type: String
The process rule for the verb. The keyword must be in eight bytes of contiguous storage, left-justified,
and padded on the right with blanks. The rule_array keywords are described in Table108.
Table108.KeywordsforPKAKeyTokenChangecontrolinformation
Keyword Description
| Tokentype(One,optional)
|| ECC SpecifiesthatthekeybeingchangedisanECCkey.ThiskeywordwasintroducedwithCCA4.1.0.
|| RSA SpecifiesthatthekeybeingchangedisanRSAkeyoratrustedblock.Thisisthedefault.This
| keywordwasintroducedwithCCA4.1.0.
| Reenciphermentmethod(One,required)
Chapter11.ManagingPKAcryptographickeys 385

PKA Key Token Change (CSNDKTC)
Table108.KeywordsforPKAKeyTokenChangecontrolinformation (continued)
Keyword Description
| RTCMK Ifthekey_identifierisanRSAkeytoken,theverbwillchangeanRSAprivatekeyfromencipherment
| withtheoldASYM-MKtoenciphermentwiththecurrentASYM-MK.
| Ifthekey_identifierisatrustedblocktoken,theverbwillchangethetrustedblock'sembeddedMAC
| keyfromenciphermentwiththeoldASYM-MKtoenciphermentwiththecurrentASYM-MK.
| Ifthekey_identifierisanECCkeytoken,theverbwillchangeanECCprivatekeyfromencipherment
| withtheoldAPKA-MKtoenciphermentwiththecurrentAPKA-MK.
| RTNMK Re-enciphersaprivate(internal)RSAorECCkeytothenewmasterkey.
Akeyencipheredunderthenewmasterkeyisnotusable.Itisexpectedthattheuserwillusethis
keyword(RTNMK)totakeapreparatorystepinre-encipheringanexternalkeystorethattheymanage
themselvestoanewmaster-key,beforethesetoperationhasoccurred.Notealsothatthenew
master-keyregistermustbefull;itmusthavehadthelastkeypartloadedandthereforenotbeempty
orpartiallyfull(partiallyfullmeansthatoneormorekeypartshavebeenloadedbutnotthelastkey
part).
The'SET'operationmakesthenewmaster-keyoperational,movingittothecurrentmaster-key
register,andthecurrentmaster-keyisdisplacedintotheoldmaster-keyregister.Whenthishappens,
allthekeysthatwerere-encipheredtothenewmaster-keyarenowusable,becausethenew
master-keyisnot'new'anymore,itis'current'.
BecausetheRTNMKkeywordisaddedprimarilyforsupportofexternallymanagedkeystorage(see
“KeyStorageonz/OS(RTNMK-focused)”onpage264,itisnotvalidtopassakey_identiferwhenthe
RTNMKkeywordisused.Onlyafullinternalkeytoken(encryptedunderthecurrentmaster-key)can
bepassedforre-enciphermentwiththeRTNMKkeyword.WhenakeyLABELispassedalongwiththe
RTNMKkeyword,theerrorreturncode8withreasoncode63willbereturned.
Formoreinformation,see“KeystoragewithLinuxforIBMSystemz,incontrasttoz/OSforIBM
Systemz”onpage263.
key_identifier_length
Direction: Input Type: Integer
| The length of the key_identifier parameter. The maximum size is 3500 bytes.
key_identifier
Direction: Input/Output Type: String
| Contains an internal key token of an internal RSAor ECC key, or trusted block key. If the key token is
| an RSAkey token, the private key within the token is securely reenciphered under the current
| ASYM-MK. If the key token is a trusted block key token, the MAC key within the token is securely
| re-enciphered under the current ASYM-MK. If the key token is an ECC key token, the private key
| within the token is securely re-enciphered under the current APKA-MK.
Restrictions
None
Required commands
| This verb requires the PKAKey Token Change RTCMK command (offset X'0102') to be enabled in the
| active role.
Usage notes
None
386 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Token Change (CSNDKTC)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDKTCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDKTCJ are shown here.
Format
public native void CSNDKTCJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger key_label_length,
byte[] key_label );
Chapter11.ManagingPKAcryptographickeys 387

PKA Key Translate (CSNDPKT)
PKA Key Translate (CSNDPKT)
The PKAKey Translate verb translates PKAkey tokens from encipherment under the oldAsymmetric-Keys
Master Key to encipherment under the currentAsymmetric-Keys Master Key. This verb changes only
Private Internal PKAKey Tokens.
The source CCARSAkey token must be wrapped with a transport key encrypting key (KEK). The XLATE
bit must also be turned on in the key usage byte of the source token. The source token is unwrapped
using the specified source transport KEK. The target key token will be wrapped with the specified target
transport KEK. Existing information in the target token is overwritten.
There are restrictions on which type key can be used for the source and target transport key tokens.
These restrictions are enforced by access control points.
There are restrictions on which rule can be used. These restrictions are enforced by access control points.
Format
CSNDPKT(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
source_key_identifier_length,
source_key_identifier,
source_transport_key_identifier_length,
source_transport_key_identifier,
target_transport_key_identifier_length,
target_transport_key_identifier,
target_key_token_length,
target_key_token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type: String
The process rule for the verb. The keyword must be in eight bytes of contiguous storage, left-justified,
and padded on the right with blanks. The rule_array keywords are described in Table109.
Table109.KeywordsforPKAKeyTranslatecontrolinformation
Keyword Description
| SmartcardFormat(One,required)
SCVISA ThiskeywordindicatestranslatingthekeyintothesmartcardVisaproprietaryformat.
SCCOMME ThiskeywordindicatestranslatingthekeyintothesmartcardModulus-Exponentformat.
388 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Translate (CSNDPKT)
Table109.KeywordsforPKAKeyTranslatecontrolinformation (continued)
Keyword Description
SCCOMCRT ThiskeywordindicatestranslatingthekeyintothesmartcardChineseRemainderTheorem
format.
source_key_identifier_length
Direction: Input Type: Integer
The length of the source_key_identifier parameter. The maximum size is 3500 bytes.
source_key_identifier
Direction: Input Type: String
This field contains either a key label identifying an RSAprivate key, or an external public-private key
token. The private key must be wrapped with a key encrypting key.
source_transport_key_identifier_length
Direction: Input Type: Integer
Length in bytes of the source_transport_key_identifier parameter. This value must be 64.
source_transport_key_identifier
Direction: Input/Output Type: String
This field contains an internal token or label of a DES key-encrypting key. This key is used to unwrap
the input RSAkey token specified with parameter source_key_identifier. See “Usage notes” on page
390 for details on the type of transport key that can be used.
target_transport_key_identifier_length
Direction: Input Type: Integer
Length in bytes of the target_transport_key_identifier parameter. This value must be 64.
target_transport_key_identifier
Direction: Input/Output Type: String
This field contains an internal token or label of a DES key-encrypting key. This key is used to wrap the
output RSAkey returned with parameter target_key_token. See “Usage notes” on page 390 for details
on the type of transport key that can be used.
target_key_token_length
Direction: Input Type: Integer
Length in bytes of the target_key_token parameter. 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
Direction: Output Type: String
This field contains the RSAkey in the smartcard format specified in the rule_array parameter, and is
protected by the key-encrypting key specified in the target_transport_key parameter. This is not a CCA
token, and cannot be stored in the key storage.
Restrictions
CCARSAME tokens will not be translated to the SCCOMCRT format. CCARSACRT tokens will not be
translated to the SCCOMME format. SCVISAsupports only Modulus-Exponent (ME) keys.
Chapter11.ManagingPKAcryptographickeys 389

PKA Key Translate (CSNDPKT)
Required commands
This verb requires the following commands to be enabled in the active role based on the keyword:
||||
Rule-arraykeyword Offset Command
||| SCVISA X'0318' PKAKeyTranslate-fromCCARSAtoSCVisaFormat
||| SCCOMME X'0319' PKAKeyTranslate-fromCCARSAtoSCMEFormat
||| SCCOMCRT X'031A' PKAKeyTranslate-fromCCARSAtoSCCRTFormat
|
These commands must also be enabled to allow the key type combinations shown in this table:
|||
Sourcetransport Targettransport
|||| keytype keytype Offset Command
|||| EXPORTER EXPORTER X'031B' PKAKeyTranslate-fromsourceEXPKEKtotarget
| EXPKEK
|||| IMPORTER EXPORTER X'031C' PKAKeyTranslate-fromsourceIMPKEKtotarget
| EXPKEK
|||| IMPORTER IMPORTER X'031D' PKAKeyTranslate-fromsourceIMPKEKtotargetIMP
| KE
|||| EXPORTER IMPORTER N/A Thiskeytypecombinationisnotallowed.
|
Usage notes
There are access control points that control use of the format rule_array keys and the type of transport
keys that can be used.All of these access control points are enabled in the default role.
PKAKey Translate - from CCARSAto SCVISAFormat
PKAKey Translate - from CCARSAto SC ME Format
PKAKey Translate - from CCARSAto SC CRT Format
PKAKey Translate - from source EXP KEK to target EXP KEK
PKAKey Translate - from source IMP KEK to target EXP KEK
PKAKey Translate - from source IMP KEK to target IMP KEK
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKTJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKTJ are shown here.
390 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Key Translate (CSNDPKT)
Format
public native void CSNDPKTJ (
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger 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 );
Chapter11.ManagingPKAcryptographickeys 391

PKA Public Key Extract (CSNDPKX)
PKA Public Key Extract (CSNDPKX)
Use the PKAPublic Key Extract verb to extract a PKApublic key token from a supplied PKAinternal or
external private key token. This verb performs no cryptographic verification of the PKAprivate token. You
can verify the private token by using it in a verb such as Digital Signature Generate.
Format
CSNDPKX(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
source_key_indentifier_length,
source_key_identifier,
target_public_key_token_length,
target_public_key_token )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type: String
This parameter is ignored.
source_key_identifier_length
Direction: Input Type: Integer
| The length of the source_key_identifier parameter. The maximum size is 3500 bytes. When the
| source_key_identifier parameter is a key label, this field specifies the length of the label.
source_key_identifier
Direction: Input/Output Type: String
| The internal or external token of a PKAprivate key or the label of a PKAprivate key. This can be the
| input or output from the PKAKey Import or PKAKey Generate verbs. This verb supports:
| v RSAprivate key token formats supported on the CEX2C or CEX3C. If the source_key_identifier
| specifies a label for a private key that has been retained within a CEX2C, this verb extracts only the
| public key section of the token.
| v ECC private key token formats supported on the CEX3C.
target_public_key_token_length
Direction: Input/Output Type: Integer
The length of the target_public_key_token parameter. The maximum size is 2500 bytes. On output,
this field will be updated with the actual byte length of the target_public_key_token.
target_public_key_token
392 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PKA Public Key Extract (CSNDPKX)
Direction: Output Type: String
This field contains the token of the extracted PKApublic key.
Restrictions
None
Required commands
None
Usage notes
This verb extracts the public key from the internal or external form of a private key. However, it does not
check the cryptographic validity of the private token.
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDPKXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDPKXJ are shown here.
Format
public native void CSNDPKXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger source_key_identifier_length,
byte[] source_key_identifier,
hikmNativeInteger target_key_token_length,
byte[] target_key_token
);
Chapter11.ManagingPKAcryptographickeys 393

Remote Key Export (CSNDRKX)
Remote Key Export (CSNDRKX)
This verb is used as a method of secured transport of DES keys using asymmetric techniques from a
security module (for example, the CEX3C) to a remote device such as anAutomated 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 403. Remote Key Export 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.
This 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.
This is a high-level description of the remaining processing steps for generate and export.
Processing 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. XORs 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 395.
Processing steps for export operation: The verb performs these steps for the export operation:
1. If the selected rule contains a transport key rule reference subsection, verifies that the rule ID in the
transport key rule reference subsection matches the rule ID in the token identified by the
transport_key_identifier parameter, provided that the token is an RKX key-token.
2. Verifies that the length of the transport key variant in the transport key variant subsection of the
selected rule is greater than or equal to the length of the key identified by the transport_key_identifier
parameter.
3. Verifies that the key token identified by the importer_key_identifier parameter is of key type
IMPORTER, if the source_key_identifier parameter identifies an external CCADES key-token.
4. Recovers the clear value of the source key, K, identified by the source_key_identifier parameter.
5. Verifies that the length of key K is between the export key minimum length and export key maximum
length specified in the common export key parameters subsection of the selected rule.
6. XORs 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.
7. Uses the public key in the trusted block to verify the digital signature embedded in the certificate
variable if the certificate_length variable is greater than zero.Any necessary certificate objects are
located with information from the certificate_parms variable. Returns an error if the signature
verification fails.
8. XORs the transport key variant with the clear value of the transport key (recovered in the previous
step) if the selected rule contains a transport key variant subsection and the output key variant length
is greater than zero.Adjusts the result to have valid DES key parity.
394 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Remote Key Export (CSNDRKX)
9. Continues with “Final processing steps common to generate and export operations.”
Final processing steps common to generate and export operations:
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.
v Of “Processing for generate operation” on page 394 Step 2 or Step 6 into an RKX key-token, if the
flag indicates to return an RKX key-token.
v Using the resulting key from “Processing for generate operation” on page 394 Step 6 into a CCA
DES key-token and returns it in the token identified by the sym_encrypted_key_identifier parameter,
if the flag indicates to return a CCADES key-token.
2. Encrypts the key result from “Processing for generate operation” on page 394 Step 2 or Step 6 with
the format specified, if the asymmetric encrypted output key format flag of the selected rule indicates to
output an asymmetric encrypted key.
3. Returns the computed key-check value as determined by the 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.
Format
CSNDRKX(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
trusted_block_identifier_length,
trusted_block_identifier,
certificate_length,
certificate,
certificate_parms_length,
certificate_parms,
transport_key_identifier_length,
transport_key_identifier,
rule_id_length,
rule_id,
importer_key_identifier_length,
importer_key_identifier,
source_key_identifier_length,
source_key_identifier,
asym_encrypted_key_length,
asym_encrypted_key,
sym_encrypted_key_identifier_length,
sym_encrypted_key_identifier,
extra_data_length,
extra_data,
key_check_parameters_length,
key_check_parameters,
key_check_value_length,
key_check_value )
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 14.
rule_array_count
Direction: Input Type: Integer
Chapter11.ManagingPKAcryptographickeys 395

Remote Key Export (CSNDRKX)
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 0.
rule_array
Direction: Input Type: String
| This parameter is ignored.
trusted_block_identifier_length
Direction: Input Type: Integer
Apointer 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
Direction: Input Type: String
Apointer 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. It is used to validate the
public-key certificate and to define the rules for key generation and key export.
certificate_length
Direction: Input Type: Integer
Apointer 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
Direction: Input Type: String
Apointer 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
BER encoded by pre-pending these bytes:
X'30213009 06052B0E 03021A05 000 414'
See “PKCS #1 formats” on page 513.
certificate_parms_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the certificate_parms
variable. The length must be 36 bytes if the certificate_length variable is 0, else the length must be 0.
certificate_parms
Direction: Input Type: String
396 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Remote Key Export (CSNDRKX)
Apointer 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 Table110.
Table110.KeywordsforRemoteKeyExportcertificate_parmsparameter
Offset Length
(bytes) (bytes) Description
0 4 Offsetofmodulus
4 4 Lengthofmodulus
8 4 Offsetofpublicexponent
12 4 Lengthofpublicexponent
16 4 Offsetofdigitalsignature
20 4 Lengthofdigitalsignature
| 24 1 Identifierforhashalgorithm.Thefollowingvaluesaredefined:
|| Identifier Hashalgorithm
|| X'01' SHA-1
|| X'02' MD5(Currentlynotsupported)
|| X'03' RIPEMD-160(Currentlynotsupported)
||| 25 1 Identifierfordigitalsignaturehashformattingmethodused.Thefollowingvaluesare
| defined:
|| Identifier Hashformattingmethod
|| X'01' PKCS-1.0
|| X'02' PKCS-1.1
|| X'03' X9.31(Currentlynotsupported)
|| X'04' ISO-9796(Currentlynotsupported)
|| X'05' ZERO-PAD(Currentlynotsupported)
26 2 Reserved,mustbebinaryzeros
28 4 Offsetoffirstbyteofcertificatedatahashedtocomputethedigitalsignature
32 4 Lengthofcertificatedatahashedtocomputethedigitalsignature
Note: The modulus, exponent, and signature values can have bit lengths that are not multiples of 8;
each of these values is right-justified and padded on the left with binary zeroes to make it an
even number of bytes in length.
transport_key_identifier_length
Direction: Input Type: Integer
Apointer 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.
transport_key_identifier
Direction: Input Type: String
Apointer 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 CCADES 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 but must be declared.
If this parameter points to a CCADES key-token:
v The token must be of key type IMPORTER or EXPORTER.
Chapter11.ManagingPKAcryptographickeys 397

Remote Key Export (CSNDRKX)
v If the source_key_identifier parameter identifies an internal CCADES key-token, the token must be
of key type EXPORTER.
rule_id_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the rule_id variable. The
length must be eight bytes.
rule_id
Direction: Input Type: String
Apointer 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
Direction: Input Type: Integer
Apointer 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.
importer_key_identifier
Direction: Input Type: String
Apointer 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.
This 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 CCADES key-token.
source_key_identifier_length
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the source_key_identifier
variable. The length must be 0 or 64 bytes.
source_key_identifier
Direction: Input Type: String
Apointer to a string variable containing a DES key-token or a label of a 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 CCADES key-token.
v It is a single-length or double-length internal CCADES key-token.
v It is a single-length, double-length, or triple-length RKX key-token.
Notes:
1. If the key token is a CCADES 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
Direction: Input/Output Type: Integer
398 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Remote Key Export (CSNDRKX)
Apointer 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
Direction: Output Type: String
Apointer 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
Direction: Input/Output Type: Integer
Apointer 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 a minimum of 64 bytes.
sym_encrypted_key_identifier
Direction: Output Type: String
Apointer to a string variable. On input, the sym_encrypted_key_identifier variable must contain either
a key label of a CCADES key-token record or an RKX key-token record, or be filled with binary zeros.
On output, the verb produces a CCADES 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 CCADES key-token:
1. If a common export key parameters subsection (X'0003') is present in the selected rule, the
control vector (CV) is copied from the subsection into the output CCADES 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 XORed with the transport key variant from the subsection.
Otherwise, the key is multiply enciphered under the transport key XORed with binary zero
3. XORs 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
Direction: Input Type: Integer
Apointer 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
Chapter11.ManagingPKAcryptographickeys 399

Remote Key Export (CSNDRKX)
Direction: Input Type: String
Apointer 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
Direction: Input Type: Integer
Apointer to an integer variable containing the number of bytes of data in the key_check_parameters
variable. The length must be 0.
key_check_parameters
Direction: Input Type: String
Reserved for future use.
key_check_value_length
Direction: Input/Output Type: Integer
Apointer 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
Direction: Output Type: String
Apointer 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 493 and
“Modification Detection Code calculation” on page 493. 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. Avalue of 0, 1, or 2 is considered insufficient space to hold the output encrypted result, and the
verb returns an error.
2. Avalue of 3 returns the leftmost three bytes of the encrypted result if the
key_check_value_length variable is 3 or greater. Otherwise, an error is returned.
3. Avalue of 4 - 8 returns the leftmost four bytes of the encrypted result if the
key_check_value_length variable is 4 or greater. Otherwise, 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. Otherwise, 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
a minimum of 16 bytes and a multiple of eight 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.
Restrictions
1. AES keys are not supported by this verb.
2. Keys with a modulus length greater than 2048 bits are not supported in releases before Release 3.30.
3. The maximum public exponent is 17 bits for any key that has a modulus greater than 2048 bits.
400 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Remote Key Export (CSNDRKX)
Required commands
| This verb requires the Remote Key Export - Generate or export a key for use by a non-CCAnode
| command (offset X'0312') to be enabled in the active role.
| The verb also requires the Key Generate - SINGLE-R command (offset X'00DB') to be enabled to replicate
| a single-length source key (either from a CCADES 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 CCADES 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.
| 3. The token identified by the source_key_identifier parameter is single length, and is either a CCADES
| key-token or an RKX key-token.
| To enable the use of key-encrypting-keys with the NOCV option for export, this verb requires the NOCV
| KEK usage for export-related functions command (offset X'0300') to be enabled in the active role.
| To enable the use of key-encrypting-keys with the NOCV option for import, this verb requires the NOCV
| KEK usage for import-related functions command (offset X'030A') to be enabled in the active role.
Note: Arole with X'00DB' enabled can also use the Key Generate verb with the SINGLE-R key-length
keyword.
Usage notes
None
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDRKXJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDRKXJ are shown here.
Chapter11.ManagingPKAcryptographickeys 401

Remote Key Export (CSNDRKX)
Format
public native void CSNDRKXJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger trusted_block_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 export_key_kek_length,
byte[] export_key_kek_identifier,
hikmNativeInteger export_key_length,
byte[] export_key_identifier,
hikmNativeInteger asym_encrypted_key_length,
byte[] asym_encrypted_key,
hikmNativeInteger sym_encrypted_key_length,
byte[] sym_encrypted_key,
hikmNativeInteger extra_data_length,
byte[] extra_data,
hikmNativeInteger key_check_parameters_length,
byte[] key_check_parameters,
hikmNativeInteger key_check_length,
byte[] key_check_value
);
402 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Trusted Block Create (CSNDTBC)
Trusted Block Create (CSNDTBC)
The verb creates an external trusted block under dual control.Atrusted block is an extension of CCAPKA
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 444.
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 Trusted Block Create - Create a Trusted Key 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 Trusted Block Create -Activate an Inactive Trusted
| Key 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 “PKA
Key Import (CSNDPKI)” on page 374 to import an active external trusted block into the desired node. The
imported internal trusted block can then be used as input to “Remote Key Export (CSNDRKX)” on page
394 in order to generate or export DES keys.
Creating 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.
This 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 TDES 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-PKAkey. 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-PKAkey.
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.
Creating an active external trusted block: To create an active external trusted block, use a
rule_array_count of 1 and a rule_array keyword ofACTIVE. 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
Chapter11.ManagingPKAcryptographickeys 403

Trusted Block Create (CSNDTBC)
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-PKAkey.
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.
Format
CSNDTBC(
return_code,
reason_code,
exit_data_length,
exit_data,
rule_array_count,
rule_array,
input_block_identifier_length,
input_block_identifier,
transport_key_identifier,
trusted_block_identifier_length,
trusted_block_identifier )
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 14.
rule_array_count
Direction: Input Type: Integer
Apointer to an integer variable containing the number of elements in the rule_array variable. This
value must be 1.
rule_array
Direction: Input Type:Array
Apointer to a string variable containing an array of keywords. The keywords are eight bytes in length
and must be left-aligned and padded on the right with space characters. The rule_array keywords are
described in Table111.
Table111.KeywordsforTrustedBlockCreatecontrolinformation
Keyword Description
Operation(Onerequired)
INACTIVE Createanexternaltrustedblock,basedontheinput_block_identifiervariable,andsettheactiveflagto
0.ThismakesthetrustedblockunusableinanyotherCCAservices.
ACTIVE Createanexternaltrustedblock,basedonthetokenidentifiedbytheinput_block_identifierparameter,
andchangetheactiveflagfrom0to1.ThismakesthetrustedblockusableinotherCCAservices
input_block_identifier_length
Direction: Input Type: Integer
404 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Trusted Block Create (CSNDTBC)
Apointer to an integer variable containing the number of bytes in the input_block_identifier variable.
The maximum length is 3500 bytes.
input_block_identifier
Direction: Input Type: String
Apointer 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 444. 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.
transport_key_identifier
Direction: Input Type: String
Apointer to a string variable containing an operational CCADES key-token or the key label of an
operational CCADES key-token record. The key token must be of type IMP-PKA.
An IMP-PKAkey 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.
Note: An IMP-PKAcontrol vector can be built using “Control Vector Generate (CSNBCVG)” on page
102 with a key type of IMPORTER and a rule_array keyword of IMPORT.
trusted_block_identifier_length
Direction: Input/Output Type: Integer
Apointer 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
Direction: Output Type: String
Apointer to a string variable containing a trusted block token or a label of a trusted block token
returned by the verb.
Restrictions
1. AES keys are not supported by this verb.
2. Keys with a modulus length greater than 2048 bits are not supported in releases before Release 3.30.
Required commands
The verb requires the following commands to be enabled in the active role based on the keyword specified
for the operation rule:
rule_array
keyword Offset Command
INACTIVE X'030F' TrustedBlockCreate-CreateaTrustedKeyBlockinInactiveform
ACTIVE X''0310' TrustedBlockCreate-ActivateanInactiveTrustedKeyBlock
Usage notes
None
Chapter11.ManagingPKAcryptographickeys 405

Trusted Block Create (CSNDTBC)
JNI version
This verb has a Java Native Interface (JNI) version, which is named CSNDTBCJ. See “Building Java
applications to use with the CCAJNI” on page 16.
The parameters for CSNDTBCJ are shown here.
Format
public native void CSNDTBCJ(
hikmNativeInteger return_code,
hikmNativeInteger reason_code,
hikmNativeInteger exit_data_length,
byte[] exit_data,
hikmNativeInteger rule_array_count,
byte[] rule_array,
hikmNativeInteger input_block_length,
byte[] input_block_identifier,
byte[] transport_key_identifier,
hikmNativeInteger trusted_blokc_length,
byte[] trusted_blokc_identifier);
406 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix A. Return codes and reason codes
This appendix 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 14.
Return codes
Areturn code provides a general indication of the results of verb processing.Areturn code can have the
values shown in Table112.
Table112.Returncodevalues
Hexvalue Decimal Description
value
00 00 Thisreturncodeindicatesanormalcompletionofverbprocessing.Toprovideadditional
information,therearealsononzeroreasoncodesassociatedwiththisreturncode.
04 04 Thisreturncodeisawarningindicatingtheverbcompletedprocessing;however,an
unusualeventoccurred.Theeventismostlikelyrelatedtoaproblemcreatedbythe
userorisanormaloccurrencebasedonthedatasuppliedtotheverb.
08 08 Thisreturncodeindicatestheverbprematurelystoppedprocessing.Generally,the
applicationprogrammerneedstoinvestigatethesignificanceoftheassociatedreason
codetodeterminetheoriginoftheproblem.Insomecases,duetotransientconditions,
retryingtheverbmightproducedifferentresults.
0C 12 Thisreturncodeindicatestheverbprematurelystoppedprocessing.Eithera
coprocessorisnotavailableoraprocessingerroroccurred.Thereasonismostlikely
relatedtoaprobleminthesetupofthehardwareorintheconfigurationofthesoftware.
10 16 Thisreturncodeindicatestheverbprematurelystoppedprocessing.Aprocessingerror
occurred.Iftheseerrorspersist,arepairofthecoprocessorhardwareoracorrectionto
thecoprocessorsoftwaremightberequired.
Note: If an application receives a return code greater than 4, an error occurred. In the case of an error,
assume any output variables other than the return code and reason code are not valid, unless
otherwise indicated in the description of verb processing.
Reason codes
Areason code details the results of verb processing. Every reason code is associated with a single return
code.Anonzero reason code can be associated with a zero return code.
User Defined Extensions (UDX) return reason codes in the range of 20480 (X'5000') - 24575 (X'5FFF').
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.
©CopyrightIBMCorp.2007,2011 407

Reason codes that accompany return code 0
Reason codes that accompany return code 0 are listed in Table113.
Table113.Reasoncodesforreturncode0
Return
code Reason code
Decimal Decimal (Hex) Description
0 000(000) Theverbcompletedprocessingsuccessfully.
0 002(002) Oneormorebytesofakeydonothaveoddparity.
0 008(008) Novalueispresenttobeprocessed.
0 151(097) ThekeytokensuppliestheMAClengthorMACLEN4isthedefaultforkey
tokensthatcontainMACorMACVERkeys.
0 701(2BD) Anewmaster-keyvaluehasduplicatethirds.
0 702(2BE) Aprovidedmaster-keypartdoesnothaveoddparity.
0 2013(7DD) ThePendingChangeBuffer(PCB)isempty.Thisreturncodeandreason
codepairappliesonlytoIBMSystemz.
0 3010(BC2) Thiscardiscurrentlydisabled.Acardisplacedinthisstatesothatitcan
bemovedfromonepieceofhardwaretoanother,whilekeepingitssecret
keysandmasterkeysintact.Normally,whenacardhasbeenmoveda
'tamper'eventisrecordedandallsecretsareerased.ATKEworkstationis
typicallyrequiredtoputacardinthisstateandtoremoveitfromthisstate
afterthecardisinstalledonthenewhardware.Thisreturncodeandreason
codepairappliesonlytoIBMSystemz.
0 10001(2711) Akeyencryptedundertheoldmasterkeywasused.
Reason codes that accompany return code 4
Reason codes that accompany return code 4 are listed in Table114.
Table114.Reasoncodesforreturncode4
Return
code Reason code
Decimal Decimal (Hex) Description
4 001(001) Theverificationtestfailed.
4 013(00D) Thekeytokenhasaninitializationvectorandtheinitialization_vector
parametervalueisnonzero.Theverbusesthevalueinthekeytoken.
4 016(010) Therule_arrayandtherule_array_countaretoosmalltocontainthe
completeresult.
4 017(011) TherequestedIDisnotpresentinanyprofileinthespecifiedcryptographic
hardwarecomponent.
4 019(013) ThefinancialPINinaPINblockisnotverified.
4 158(09E) Theverbdidnotprocessanykeyrecords.
4 166(0A6) Thecontrol-vectorisnotvalidbecauseofparitybits,anti-variantbits,
inconsistentKEKbitsorbecausebits59-62arenotzero.
4 179(0B3) Thecontrol-vectorkeywordsintherule_arrayareignored.
4 283(11B) Thecoprocessorbatteryislow.
4 287(11F) ThePIN-blockformatisnotconsistent.
408 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table114.Reasoncodesforreturncode4 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
4 429(1AD) Thedigitalsignatureisnotverified.Theverbcompleteditsprocessing
normally.
4 1024(400) Sufficientshareshavebeenprocessedtocreateanewmasterkey.
4 2039(7F7) Atleastonecontrolvectorbitcannotbeparsed.
4 2042(7FA) Thesuppliedpassphraseisnotvalid.
Reason codes that accompany return code 8
Reason codes that accompany return code 8 are listed in Table115.
Table115.Reasoncodesforreturncode8
Return
code Reason code
Decimal Decimal (Hex) Description
8 012(00C) Thetoken-validationvalueinanexternalkeytokenisnotvalid.
8 022(016) TheIDnumberintherequestfieldisnotvalid.
8 023(017) Anaccesstothedataareaisoutsidethedata-areaboundary.
8 024(018) Themasterkeyverificationpatternisnotvalid.
8 025(019) Thevaluethatthetext_lengthparameterspecifiesisnotvalid.
8 026(01A) ThevalueofthePINisnotvalid.
8 029(01D) Thetoken-validationvalueinaninternalkeytokenisnotvalid.
8 030(01E) Norecordwithamatchingkeylabelisinkeystorage.
8 031(01F) ThecontrolvectordoesnotspecifyaDATAkey.
8 032(020) Akeylabelformatisnotvalid.
8 033(021) Arule_arrayorotherparameterspecifiesakeywordthatisnotvalid.
8 034(022) Arule_arraykeywordcombinationisnotvalid.
8 035(023) Arule_array_countisnotvalid.
8 036(024) Theactioncommandmustbespecifiedintherule_array.
8 037(025) Theobjecttypemustbespecifiedintherule_array.
8 039(027) Acontrolvectorviolationoccurred.Checkallcontrolvectorsemployedwith
theverb.Forsecurityreasons,nodetailisprovided.
8 040(028) Theservicecodedoesnotcontainnumericalcharacterdata.
8 041(029) Thekeywordsuppliedwiththekey_formparameterisnotvalid.
8 042(02A) Theexpirationdateisnotvalid.
8 043(02B) Thekeywordsuppliedwiththekey_lengthorthekey_token_length
parameterisnotvalid.
8 044(02C) Arecordwithamatchingkeylabelalreadyexistsinkeystorage.
8 045(02D) Theinputcharacterstringcannotbefoundinthecodetable.
8 046(02E) Thecard-validationvalue(CVV)isnotvalid.
AppendixA.Returncodesandreasoncodes 409

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 047(02F) Asourcekeytokenisunusablebecauseitcontainsdatathatisnotvalidor
isundefined.
8 048(030) Oneormorekeyshasamasterkeyverificationpatternthatisnotvalid.
8 049(031) Akey-token-version-numberfoundinakeytokenisnotsupported.
8 050(032) Thekey-serial-numberspecifiedintherule_arrayisnotvalid.
8 051(033) Thevaluethatthetext_lengthparameterspecifiesisnotamultipleofeight
bytes.
8 054(036) Thevaluethatthepad_characterparameterspecifiesisnotvalid.
8 055(037) Theinitializationvectorinthekeytokenisenciphered.
8 056(038) ThemasterkeyverificationpatternintheOCVisnotvalid.
8 058(03A) Theparityoftheoperatingkeyisnotvalid.
8 059(03B) Controlinformation(forexample,theprocessingmethodorthepad
character)inthekeytokenconflictswiththatintherule_array.
8 060(03C) AcryptographicrequestwiththeFIRSTorMIDDLEkeywordsandatext
lengthlessthaneightbytesisnotvalid.
8 061(03D) Thekeywordsuppliedwiththekey_typeparameterisnotvalid.
8 062(03E) Thesourcekeyisnotpresent.
8 063(03F) Akeytokenhasaninvalidtokenheader(forexample,notaninternal
token).
8 064(040) TheRSAkeyisnotpermittedtoperformtherequestedoperation.Likely
causeiskeydistributionusageisnotenabledforthekey.
8 065(041) Thekeytokenfailedconsistencychecking.
8 066(042) Therecoveredencryptionblockfailedvalidationchecking.
8 067(043) RSAencryptionfailed.
8 068(044) RSAdecryptionfailed.
8 072(048) Thevaluethatthesizeparameterspecifiesisnotvalid(toosmall,toolarge,
negative,orzero).
8 085(055) Thedateorthetimevalueisnotvalid.
8 090(05A) Accesscontrolcheckingfailed.SeetheRequiredCommandsdescriptions
forthefailingverb.
8 091(05B) Thetimethatwassentinyourlogonrequestwasmorethanfiveminutes
differentfromtheclockinthesecuremodule.
8 092(05C) Theuserprofileisexpired.
8 093(05D) Theuserprofilehasnotyetreacheditsactivationdate.
8 094(05E) Theauthenticationdata(forexample,passphrase)isexpired.
8 095(05F) Accesstothedataisnotauthorized.
8 096(060) Anerroroccurredreadingorwritingthesecureclock.
8 100(064) ThePINlengthisnotvalid.
8 101(065) ThePINchecklengthisnotvalid.Itmustbeintherangefrom4tothePIN
lengthinclusive.
8 102(066) Thevalueofthedecimalizationtableisnotvalid.
410 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 103(067) Thevalueofthevalidationdataisnotvalid.
8 104(068) Thevalueofthecustomer-selectedPINisnotvalidorthePINlengthdoes
notmatchthevaluesuppliedwiththePIN_lengthparameterordefinedby
thePIN-blockformatspecifiedinthePINprofile.
8 105(069) Thevalueofthetransaction_securityparameterisnotvalid.
8 106(06A) ThePIN-blockformatkeywordisnotvalid.
8 107(06B) Theformatcontrolkeywordisnotvalid.
8 108(06C) Thevalueortheplacementofthepaddingdataisnotvalid.
8 109(06D) Theextractionmethodkeywordisnotvalid.
8 110(06E) ThevalueofthePANdataisnotnumericcharacterdata.
8 111(06F) Thesequencenumberisnotvalid.
8 112(070) ThePINoffsetisnotvalid.
8 114(072) ThePVVvalueisnotvalid.
8 116(074) TheclearPINvalueisnotvalid.Forexample,digitsotherthan0-9were
found.
8 120(078) Anoriginordestinationidentifierisnotvalid.
8 121(079) Thevalueoftheinbound_keyorsource_keyparameterisnotvalid.
8 122(07A) Thevalueoftheinbound_KEK_countoroutbound_countparameterisnot
valid.
8 125(07D) APKA92-encryptedkeyhavingthesameEnvironmentIdentifier(EID)as
thelocalnodecannotbeimported.
||| 8 129(081) Requiredrule-arraykeywordnotfound.
8 153(099) Thetextlengthexceedsthesystemlimits.
8 154(09A) Thekeytokenthekey_identifierparameterspecifiesisnotaninternal
key-tokenorakeylabel.
8 155(09B) Thevaluethatthegenerated_key_identifierparameterspecifiesisnotvalid
oritisnotconsistentwiththevaluethatthekey_formparameterspecifies.
8 156(09C) Akeywordisnotvalidwiththespecifiedparameters.
8 157(09D) Thekey-tokentypeisnotspecifiedintherule_array.
8 159(09F) Thekeywordsuppliedwiththeoptionparameterisnotvalid.
8 160(0A0) Thekeytypeandthekeylengtharenotconsistent.
8 161(0A1) Thevaluethatthedataset_name_lengthparameterspecifiesisnotvalid.
8 162(0A2) Theoffsetvalueisnotvalid.
8 163(0A3) Thevaluethatthedataset_nameparameterspecifiesisnotvalid.
8 164(0A4) Thestartingaddressoftheoutputareafallsinsidetheinputarea.
8 165(0A5) Thecarry_over_character_countspecifiedinthechainingvectorisnotvalid.
8 168(0A8) AhexadecimalMACvaluecontainscharactersthatarenotvalidorthe
MAC,onarequestorreplyfailed,becausetheusersessionkeyinthehost
andtheadaptercarddonotmatch.
AppendixA.Returncodesandreasoncodes 411

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 169(0A9) SpecifictoMDCGenerate,indicatesthatthelengthofthetextsuppliedis
notcorrect,eithernotlongenoughforthealgorithmparametersusedornot
thecorrectmultiple(mustbemultipleofeightbytes).
8 170(0AA) Specialauthorizationthroughtheoperatingsystemisrequiredtousethis
verb.
8 171(0AB) Thecontrol_array_countvalueisnotvalid.
8 175(0AF) Thekeytokencannotbeparsedbecausenocontrolvectorispresent.
8 180(0B4) Akeytokenpresentedforparsingisnull.
8 181(0B5) Thekeytokenisnotvalid.Thefirstbyteisnotvalidoranincorrecttoken
typewaspresented.
8 183(0B7) Thekeytypeisnotconsistentwiththekeytypeofthecontrolvector.
8 184(0B8) Aninputpointerisnull.
8 185(0B9) AdiskI/Oerroroccurred:perhapsthefileisin-use,doesnotexist,andso
forth.
8 186(0BA) Thekey-typefieldinthecontrolvectorisnotvalid.
8 187(0BB) TherequestedMAClength(MACLEN4,MACLEN6,MACLEN8)isnot
consistentwiththecontrolvector(key-A,key-B).
8 191(0BF) TherequestedMAClength(MACLEN6,MACLEN8)isnotconsistentwith
thecontrolvector(MAC-LN-4).
8 192(0C0) Akey-storagerecordcontainsarecordvalidationvaluethatisnotvalid.
8 204(0CC) Amemoryallocationfailed.Thiscanoccurinthehostandinthe
coprocessor.Tryclosingotherhosttasks.Iftheproblempersists,contact
theIBMsupportcenter.
8 205(0CD) TheX9.23cipheringmethodisnotconsistentwiththeuseofthe
CONTINUEkeyword.
8 323(143) ThecipheringmethodtheDecipherverbuseddoesnotmatchtheciphering
methodtheEncipherverbused.
8 335(14F) Eitherthespecifiedcryptographichardwarecomponentortheenvironment
cannotimplementthisfunction.
8 340(154) Oneoftheinputcontrolvectorshasoddparity.
8 343(157) Eitherthedatablockorthebufferfortheblockistoosmalloravariable
hascausedanattempttocreateaninternaldatastructurethatistoolarge.
8 374(176) Lessdatawassuppliedthanexpectedorlessdataexiststhanwas
requested.
8 377(179) Akey-storageerroroccurred.
8 382(17E) Atime-limitviolationoccurred.
8 385(181) Thecryptographichardwarecomponentreportedthatthedatapassedas
partofacommandisnotvalidforthatcommand.
8 387(183) ThecryptographichardwarecomponentreportedthattheuserIDorroleID
isnotvalid.
8 393(189) Thecommandwasnotprocessedbecausetheprofilecannotbeused.
8 394(18A) Thecommandwasnotprocessedbecausetheexpirationdatewas
exceeded.
412 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 397(18D) Thecommandwasnotprocessedbecausetheactiveprofilerequiresthe
usertobeverifiedfirst.
8 398(18E) ThecommandwasnotprocessedbecausethemaximumPINorpassword
failurelimitisexceeded.
8 407(197) ThereisaPIN-blockconsistency-check-error.
||| 8 439(1B7) Keycannotbecompletedbecauseallrequiredkeypartshavenotyetbeen
| accumulated,orkeyisalreadycomplete.
||| 8 441(1B9) Keypartcannotbeaddedbecausekeyiscomplete.
8 442(1BA) DESkeyswithreplicatedhalvesarenotallowed.
8 605(25D) Thenumberofoutputbytesisgreaterthanthenumberthatispermitted.
8 703(2BF) Anewmaster-keyvalueisoneoftheweakDESkeys.
8 704(2C0) Anewmasterkeycannothavethesamemasterkeyversionnumberasthe
currentmaster-key.
8 705(2C1) Bothexporterkeysspecifythesamekey-encryptingkey.
8 706(2C2) Padcountindeciphereddataisnotvalid.
8 707(2C3) Themaster-keyregistersarenotinthestaterequiredfortherequested
function.
8 714(2CA) Areservedparametermustbeanullpointeroranexpectedvalue.
8 715(2CB) Aparameterthatmusthaveavalueofzeroisnotvalid.
8 718(2CE) ThehashvalueofthedatablockinthedecryptedRSA-OAEPblockdoes
notmatchthehashofthedecrypteddatablock.
8 719(2CF) Theblockformat(BT)fieldinthedecryptedRSA-OAEPblockdoesnot
havethecorrectvalue.
8 720(2D0) Theinitialbyte(I)inthedecryptedRSA-OAEPblockdoesnothaveavalid
value.
8 721(2D1) TheVfieldinthedecryptedRSA-OAEPdoesnothavethecorrectvalue.
8 752(2F0) Thekey-storagefilepathisnotusable.
8 753(2F1) Openingthekey-storagefilefailed.
8 754(2F2) Aninternalcalltothekey_testcommandfailed.
8 756(2F4) Creationofthekey-storagefilefailed.
8 760(2F8) AnRSA-keymoduluslengthinbitsorinbytesisnotvalid.
8 761(2F9) AnRSA-keyexponentlengthisnotvalid.
8 762(2FA) Alengthinthekeyvaluestructureisnotvalid.
8 770(302) ThePKAkeytokenhasafieldthatisnotvalid.
8 771(303) Theuserisnotloggedon.
8 772(304) Therequestedroledoesnotexist.
8 773(305) Therequestedprofiledoesnotexist.
8 774(306) Theprofilealreadyexists.
8 775(307) Thesupplieddataisnotreplaceable.
8 776(308) TherequestedIDisalreadyloggedon.
AppendixA.Returncodesandreasoncodes 413

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 777(309) Theauthenticationdataisnotvalid.
8 778(30A) Thechecksumfortheroleisinerror.
8 779(30B) Thechecksumfortheprofileisinerror.
8 780(30C) Thereisanerrorintheprofiledata.
8 781(30D) Thereisanerrorintheroledata.
8 782(30E) Thefunction-control-vectorheaderisnotvalid.
8 783(30F) Thecommandisnotpermittedbythefunction-control-vectorvalue.
8 784(310) Theoperationyourequestedcannotbeperformedbecausetheuserprofile
isinuse.
8 785(311) Theoperationyourequestedcannotbeperformedbecausetheroleisin
use.
8 1025(401) Theregisteredpublickeyorretainedprivatekeynamealreadyexists.
8 1026(402) Thekeyname(registeredpublickeyorretainedprivatekey)doesnotexist.
8 1027(403) Environmentidentifierdataisalreadyset.
8 1028(404) Masterkeysharedataisalreadyset.
8 1029(405) ThereisanerrorintheEnvironmentIdentifier(EID)data.
8 1030(406) Thereisanerrorinusingthemasterkeysharedata.
8 1031(407) Thereisanerrorinusingregisteredpublickeyorretainedprivatekeydata.
8 1032(408) Thereisanerrorinusingregisteredpublickeyhashdata.
8 1033(409) Thepublickeyhashwasnotregistered.
8 1034(40A) Thepublickeywasnotregistered.
8 1035(40B) Thepublickeycertificatesignaturewasnotverified.
8 1037(40D) Thereisamasterkeysharesdistributionerror.
8 1038(40E) Thepublickeyhashisnotmarkedforcloning.
8 1039(40F) Theregisteredpublickeyhashdoesnotmatchtheregisteredhash.
8 1040(410) Themasterkeyshareencipheringkeyfailedencipher.
8 1041(411) Themasterkeyshareencipheringkeyfaileddecipher.
8 1042(412) Themasterkeysharedigitalsignaturegeneratefailed.
8 1043(413) Themasterkeysharedigitalsignatureverifyfailed.
8 1044(414) ThereisanerrorinreadingVPDdatafromtheadapter.
8 1045(415) Encryptingthecloninginformationfailed.
8 1046(416) Decryptingthecloninginformationfailed.
8 1047(417) Thereisanerrorloadingthenewmasterkeyfromthemasterkeyshares.
8 1048(418) Thecloneinformationhasoneormoresectionsthatarenotvalid.
8 1049(419) Themasterkeyshareindexisnotvalid.
8 1050(41A) Thepublic-keyencrypted-keyisrejectedbecausetheEnvironmentIdentifier
(EID)withthekeyisthesameastheEIDforthisnode.
8 1051(41B) Theprivatekeyisrejectedbecausethekeyisnotflaggedforusein
master-keycloning.
414 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 1052(41C) Thetokenidentifierofthetrustedblock'sheadersectionisintherange
X'20'-X'FF'.Checkthetokenidentifierofthetrustedblock.
8 1053(41D) Theactiveflaginthetrustedblock’strustedblocksectionX'14'isnot
disabled.UsetheTrustedBlockCreateverbtocreateaninactive/external
trustedblock.
8 1054(41E) Thetokenidentifierofthetrustedblock’sheadersectionisnotX'1E'
(external).UsetheTrustedBlockCreateverbtocreateaninactive/external
trustedblock.
8 1055(41F) Theactiveflagofthetrustedblock’strustedblocksectionX'14'isnot
enabled.UsetheTrustedBlockCreateverbtocreateanactive/external
trustedblock.
| 8 1056(420) Thetokenidentifierofthetrustedblock’sheadersectionisnotX'1F'
| (internal).UsethePKAKeyImportverbtoimportthetrustedblock.
8 1057(421) ThetrustedblockrulesectionX'12'ruleIDdoesnotmatchinputparameter
ruleID.Verifythatthetrustedblockusedhastherulesectionspecified.
8 1058(422) Thetrustedblockcontainsavaluethatistoosmallortoolarge.
8 1059(423) Atrustedblockparameterthatmusthaveavalueofzero(oragroupingof
bitssettozero)isinvalid.
8 1060(424) Thetrustedblockpublickeysectionfailedconsistencychecking.
8 1061(425) Thetrustedblockcontainsextraneoussectionsorsubsections(TLVs).
Checkthetrustedblockforundefinedsectionsorsubsections.
8 1062(426) Thetrustedblockcontainsmissingsectionsorsubsections(TLVs).Check
thetrustedblockforrequiredsectionsandsubsectionsapplicabletothe
verbinvoked.
8 1063(427) Thetrustedblockcontainsduplicatesectionsorsubsections(TLVs).Check
thetrustedblock’ssectionsandsubsectionsforduplicates.Multiplerule
sectionsareallowed.
8 1064(428) Thetrustedblockexpirationdatehasexpired(ascomparedtotheIBM
4764clock).Validatetheexpirationdateinthetrustedblock’strusted
informationsection’sActivationandExpirationDateTLVobject
8 1065(429) Thetrustedblockexpirationdateisatadatepriortotheactivationdate.
Validatetheexpirationdateinthetrustedblock’strustedinformation
section’sActivationandExpirationDateTLVobject.
8 1066(42A) Thetrustedblockpublickeymoduluslengthinbitsisnotconsistentwiththe
bytelength.Thebitlengthmustbelessthanorequaltobytelength*8and
greaterthan(bytelength-1)*8.
8 1067(42B) Thetrustedblockpublickeymoduluslengthinbitsexceedsthemaximum
allowedbitlength,asdefinedbytheFunctionControlVector.
8 1068(42C) OneormoretrustedblocksectionsorTLVobjectscontaineddatathatis
invalid(anexamplewouldbeinvalidlabeldatainlabelsectionX'13').
8 1069(42D) TrustedblockverificationwasattemptedbyaverbotherthanCSNDDSV,
CSNDKTC,CSNDPKI,CSNDRKX,orCSNDTBC.
8 1070(42E) ThetrustedblockruleIDcontainedwithinarulesectionhasinvalid
characters.
8 1071(42F) Thesourcekey'slengthorCVdoesnotmatchwhatisexpectedbytherule
sectioninthetrustedblockthatwasselectedbytheruleIDinputparameter.
AppendixA.Returncodesandreasoncodes 415

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 1072(430) Theactivationdataisnotvalid.Validatetheactivationdatainthetrusted
block’strustedinformationsection’sActivationandExpirationDateTLV
object.
8 1073(431) Thesource-keylabeldoesnotmatchthetemplateintheexportkeyDES
tokenparametersTLVobjectoftheselectedtrustedblockrulesection.
8 1074(432) Thecontrol-vectorvaluespecifiedinthecommonexportkeyparameters
TLVobjectintheselectedrulesectionofthetrustedblockcontainsa
controlvectorthatisnotvalid.
8 1075(433) Thesource-keylabeltemplateintheexportkeyDEStokenparametersTLV
objectintheselectedrulesectionofthetrustedblockcontainsalabel
templatethatisnotvalid.
||| 8 1077(435) Keywrappingoptioninputerror.
||| 8 1078(436) KeywrappingSecurityRelevantDataItem(SRDI)error.
8 1100(44C) Thereisageneralhardwaredevicedriverexecutionerror.
8 1101(44D) Thereisahardwaredevicedriverparameterthatisnotvalid.
8 1102(44E) Thereisahardwaredevicedrivernon-validbufferlength.
8 1103(44F) Thehardwaredevicedriverhastoomanyopens.Thedevicecannotopen
now.
8 1104(450) Thehardwaredevicedriverisdeniedaccess.
8 1105(451) Thehardwaredevicedriverdeviceisbusyandcannotperformtherequest
now.
8 1106(452) Thehardwaredevicedriverbufferistoosmallandthereceiveddatais
truncated.
8 1107(453) Thehardwaredevicedriverrequestisinterruptedandtherequestis
aborted.
8 1108(454) Thehardwaredevicedriverdetectedasecuritytamperevent.
8 2036(7F4) Thecontentsofachainingvectorarenotvalid.Ensurethechainingvector
wasnotmodifiedbyyourapplicationprogram.
8 2038(7F6) NoRSAprivatekeyinformationisprovided.
8 2041(7F9) Adefaultcardenvironmentvariableisnotvalid.
8 2050(802) ThecurrentkeyserialnumberfieldinthePINprofilevariableisnotvalid
(nothexadecimalortoomanyonebits).
8 2051(803) Thereisanon-validmessagelengthintheOAEP-decodedinformation.
8 2053(805) NomessagefoundintheOAEP-decodeddata.
8 2054(806) Thereisanon-validRSAEncipheredKeycryptogram:OAEPoptional
encodingparametersfailedvalidation.
8 2055(807) TheRSApublickeyistoosmalltoencrypttheDESkey.
8 2062(80E) Theactiveroledoesnotpermityoutochangethecharacteristicofa
double-lengthkeyinthekey_Part_Importparameter.
8 2065(811) Thespecifiedkeytokenisnotnull.
8 2089(829) Theverbcontainsmultiplekeywordsorparametersthatindicatethe
algorithmtobeused,andatleastoneofthesespecifiesadifferent
algorithmfromtheothers.
416 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 2093(82D) SpecifictoIBMSystemz-anAESkeyisencryptedunderaDESmaster
key,whichisnotacceptablefortherequestedoperation.
8 2095(82F) Thekey_formisincompatiblewiththekey_type.
8 2097(831) Thekey_lengthisincompatiblewiththekey_type.
8 2098(832) EitherakeybitlengththatwasnotvalidwasfoundinanAESkeytoken
(lengthnot128,192,or256bits)oraversionX'01'DEStokenhada
token-marksfieldthatwasnotvalid.
8 2099(832) InvalidencryptedkeylengthintheAEStoken,whenanencryptedkeyis
present.
||| 8 2110(83E) Invalidwrappingtype.
||| 8 2111(83F) Controlvectorenhancedbit(bit56)conflictswithkeywrappingkeyword.
||| 8 2113(841) Akeytokencontainsinvalidpayload.
||| 8 2114(842) Clear-keybitlengthisoutofrange.
||| 8 2115(843) Inputkeytokencannothaveakeypresentwhenimportingthefirstkeypart;
| skeletonkeytokenisrequired.
8 3001(BB9) TheRSA-OAEPblockcontainsaPINblockandtheverbdidnotrequest
PINBLOCKprocessing.
8 3002(BBA) SpecifictoIBMSystemz-UDXalreadyauthorized.
8 3005(BBD) SpecifictoIBMSystemz-UDXnotinUDXAuthorizationTable(UAT).
8 3006(BBE) SpecifictoIBMSystemz-UDXnotauthorized.
8 3007(BBF) SpecifictoIBMSystemz-FailedtoobtainsemaphorethatguardstheUAT.
8 3009(BC1) SpecifictoIBMSystemz-UDXPasswordhashmismatch.
8 3013(BC5) Thelongitudinalredundancycheck(LRC)checksumintheAESkey-token
doesnotmatchtheLRCchecksumoftheclearkey.
8 3047(BE7) Aclearkeywasprovidedwhenasecurekeywasrequired.
8 6000(1770) Thespecifieddeviceisalreadyallocated.
8 6001(1771) Nodeviceisallocated.
8 6002(1772) Thespecifieddevicedoesnotexist.
8 6003(1773) Thespecifieddeviceisanimpropertype.
8 6013(177D) Thelengthofthecryptographicresourcenameisnotvalid.
8 6014(177E) Thecryptographicresourcenameisnotvalidordoesnotrefertoa
coprocessorthatisavailableinthesystem.
8 10028(272C) SpecifictoIBMSystemz-Invalidcontrolvectorinkeytokensupplied.
8 10036(2734) SpecifictoIBMSystemz-Invalidcontrolvectors(L-R)inkeytoken
supplied.
8 10044(273C) SpecifictoIBMSystemz-Thekey_typeparameterandtheCVkeytypefor
thesuppliedkeytokendonotmatch.
8 10056(2748) SpecifictoIBMSystemz-Thekey_typeparametercontainsTOKEN,which
isinvalidfortherequestedoperation.
8 10124(278C) SpecifictoIBMSystemz-Thekeyidcannotbeexportedbecauseof
prohibitexportrestrictioninthetokensupplied.
AppendixA.Returncodesandreasoncodes 417

Table115.Reasoncodesforreturncode8 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
8 10128(2790) SpecifictoIBMSystemz-TheNOCV-KEKrule_arraykeyworddoesnot
applyinthiscase.
8 10129(2791) SpecifictoIBMSystemz-TheNOCV-KEKimporterkeyortransportkeyis
notallowedintheRemoteKeyExportoperationrequested.
Reason codes that accompany return code 12
Reason codes that accompany return code 12 are listed in Table116.
Table116.Reasoncodesforreturncode12
Return
code Reason code
Decimal Decimal (Hex) Description
12 097(061) Filespaceinkeystorageisinsufficienttocompletetheoperation.
12 196(0C4) Thedevicedriver,thesecurityserver,orthedirectoryserverisnotinstalled
orisnotactive.Filepermissionsarenotvalidforyourapplication.
12 197(0C5) Thereisakey-storagefileI/Oerrororthefileisnotfound.
12 206(0CE) Thekey-storagefileisnotvalidorthemaster-keyverificationfailed.There
isanunlikely,butpossible,synchronizationproblemwiththeMasterKey
Processverb.
12 207(0CF) Theverificationmethodflagsintheprofilearenotvalid.
12 319(13F) PassedtotheCVVVerifyorCVVGenerateverb,theVerbUniquedata
correspondstoaPANlengthof19,buttheoveralllengthiswrong.This
indicatesthatthehostcodeisoutofdate.
12 324(144) Thereisinsufficientmemoryavailabletoprocessyourrequest,either
memoryinthehostcomputerormemoryinsidethecoprocessorincluding
theflashEPROMusedtostorekeys,profiles,andotherapplicationdata.
12 338(152) Thiscryptographichardwaredevicedriverisnotinstalledorisnot
responding,ortheCCAcodeisnotloadedinthecoprocessor.
12 764(2FC) Themasterkeysarenotloadedand,therefore,akeycannotberecovered
orenciphered.
12 768(300) Oneormorepathsforkey-storagedirectoryoperationsareimproperly
specified.
12 769(301) Aninternalerrorhasoccurredwiththeparameterstoacryptographic
algorithm.
12 2007(7D7) ThechangetypeinthePendingChangeBufferisnotrecognized.
12 2015(7DF) Thedomainstoredinthedomainmaskdoesnotmatchwhatwasincluded
asthedomainintheCPRB.
12 2017(7E1) Theoperationisattemptingtocall'SET'foramasterkey,buthaspassed
aninvalidMasterKeyVerificationPattern.
12 2021(7E5) ThecardisdisabledintheTKEpath.
12 2037(7F5) Invaliddomainspecified.
12 2045(7FD) TheCCAsoftwareisunabletoclaimasemaphore.Thesystemmightbe
shortofresources.
418 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table116.Reasoncodesforreturncode12 (continued)
Return
code Reason code
Decimal Decimal (Hex) Description
12 2046(7FE) TheCCAsoftwareisunabletolistallthekeys.Thelimitof500,000keys
mighthavebeenreached.
12 2073(819) TKEcommandreceivedwhenTKEdisabled.
12 2074(81A) CPRBversionisincorrect.Anincorrectcontrolstructurewaspassedfrom
thehosttothecard.
12 2101(835) TheAESflagsintheFunctionControlVectorareinvalid.
12 3046(BE6) Thewrongusagewasattemptedinanoperationwitharetainedkey.
Reason codes that accompany return code 16
Reason codes that accompany return code 16 are listed in Table117.
Table117.Reasoncodesforreturncode16
Return
code Reason code
Decimal Decimal (Hex) Description
16 099(063) Anunrecoverableerroroccurredinthesecurityserver;contacttheIBM
supportcenter.
16 336(150) Anerroroccurredinacryptographichardwareorsoftwarecomponent.
16 337(151) Adevicesoftwareerroroccurred.
16 339(153) Asystemerroroccurredintheinterprocesscommunicationroutine.
16 444(1BC) Theverb-unique-datahasaninvalidlength.
16 556(22C) Therequestparameterblockfailedconsistencychecking.
16 708(2C4) Thecryptographicengineisreturninginconsistentdata.
16 709(2C5) Cryptographicengineinternalerror.Couldnotaccessthemaster-keydata.
16 710(2C6) Anunrecoverableerroroccurredwhileattemptingtoupdatemaster-keydata
items.
16 712(2C8) Anunexpectederroroccurredinthemaster-keymanager.
16 800(320) AproblemoccurredininternalSHAoperationprocessing.
16 2022(7E6) TKE-relatedinternalfileopenerror.
16 2047(7FF) Unabletotransferrequestdatafromhosttocoprocessor.
16 2057(809) Internalerror:memoryallocationfailure.
16 2058(80A) Internalerror:unexpectedreturncodefromOAEProutines.
16 2059(80B) Internalerror:OAEPSHA-1requestfailure.
16 2061(80D) InternalerrorinCSNDSYI,OAEP-decode:encipheredmessagetoolong.
16 2063(80F) Thereplymessagetoolongfortherequestor'scommandreplybuffer.
16 2107(83B) Internalfilesfailedverificationcheckwhenloadingfromencryptedstorage.
AppendixA.Returncodesandreasoncodes 419

420 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix B. Key token formats
| For debugging purposes, this appendix provides the formats for:
| v “AES internal key token”
| v “Token Validation Value” on page 422
| v “DES internal key token” on page 423
| v “DES external key token” on page 424
| v “DES null key token” on page 425
| v “RSApublic key token” on page 426
| v “RSAprivate external key token” on page 426
| v “RSAprivate internal key token” on page 430
| v “ECC key token” on page 436
| v “PKAnull key token” on page 439
| v “HMAC key token” on page 439
| v “Trusted blocks” on page 444
AES internal key token
|
Table118 shows the format for anAES internal key token.
CCAAES 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.
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 anAES 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.
AllAES keys are DATAkeys. If the flag byte indicates a control vector (CV) is present, it must be all binary
zeros.An all-zero CV represents the CV value of anAES DATAkey. If a key is present without a control
vector in a key token, that is accepted and the key is interpreted as anAES DATAkey. TheAES internal
key-token is the structure used to holdAES keys that are either encrypted with theAES master-key, or in
cleartext format.
Table118.AESInternalkeytokenformat,versionX'04'
Bytes Description
0 X'01'(flagindicatingthisisaninternalkeytoken)
1-3 Implementation-dependentbytes,mustbeX'000000'.
4 Keytokenversionnumber,X'04'
5 Reserved(X'00')
6 Flagbyte.See“AESinternalkey-tokenflagbyte”onpage422.
7 Longitudinalredundancycheck(LRC)checksumofclear-keyvalue(LRCistheXORofeachbyteinthe
clear-keyvalue).
©CopyrightIBMCorp.2007,2011 421

Key token formats
Table118.AESInternalkeytokenformat,versionX'04' (continued)
Bytes Description
8-15 Masterkeyverificationpattern(MKVP)
Containsthemaster-keyverificationpatternoftheAESmaster-keyusedtoencryptthekeycontainedin
thetoken,orbinaryzerosifthetokendoesnotcontainakeyorthekeyisintheclear.TheMKVPis
calculatedastheleftmosteightbytesoftheSHA-256hashofthestringformedbypre-pendingthebyte
X'01'tothecleartextmaster-keyvalue.
16-47 Keyvalue,ifpresent.Containseither:
v A256-bitencrypted-keyvalue.Theclearkeyvalueispaddedontherightwithbinaryzeros,andthe
entire256-bitvalueisencryptedundertheAESmaster-keyusingAESCBCmodewithan
initializationvectorofbinaryzeros.
v A128-bit,192-bit,or256-bitclear-keyvalueleft-justifiedandpaddedontherightwithbinaryzerosfor
theentire256-bitfield.
48-55 ControlVector(CV)
ThisvaluemustbebinaryzerosforallAESkeytokensthathaveacontrolvectorpresent.
56-57 Clear-keybitlength
Anintegerspecifyingthelengthinbitsoftheclear-keyvalue.Ifnokeyispresentinacompletedtoken,
thislengthiszero.Inaskeletontoken,thisisthelengthofthekeytobecreatedinthetokenwhen
usedasinputtotheKeyGenerateverb.
58-59 Encrypted-keybytelength
Anintegerspecifyingthelengthinbytesoftheencrypted-keyvalue.Thisvalueiszeroifthetokendoes
notcontainakeyorthekeyisintheclear.
60-63 Tokenvalidationvalue(TVV).
AES internal key-token flag byte
|
Table119 shows the format for anAES internal key token flag byte.
Table119.AESinternalkey-tokenflagbyte
Bits(MSB...LSB)1 Description
1xxxxxxx KeyisencryptedundertheAESmaster-key(ignoredifnokeypresent).
0xxxxxxx Keyisintheclear(ignoredifnokeypresent).
x1xxxxxx Controlvector(CV)ispresent.
xx1xxxxx NokeyandnoMKVPpresent.
xx0xxxxx Encryptedorclearkeypresent,MKVPpresentifkeyisencrypted.
Note: Allundefinedbitsarereservedandmustbe0.
Token Validation Value
CCAuses the Token Validation Value (TVV) to verify that a token is valid. The TVV prevents a key token
that is not valid or that is overlaid from being accepted by CCA. It provides a checksum to detect a
corruption in the key token.
When an CCAverb generates a key token, it generates a TVV and stores the TVV in bytes 60-63 of the
key token. When an application program passes a key token to a verb, CCAchecks the TVV. To generate
the TVV, CCAperforms a twos complementADD operation (ignoring carries and overflow) on the key
token, operating on four bytes at a time, starting with bytes 0-3 and ending with bytes 56-59.
422 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Format of the clear key token
Table120 shows the format for a clear internal key token.
Table120.Internalclearkeytokenformat
Bytes Description
0 X'01'(flagindicatingthisisaninternalkeytoken)
1-3 Implementation-dependentbytes(X'000000'forICSF)
4 Keytokenversionnumber(X'00'orX'01')
5 Reserved(X'00')
6 Flagbyte
Bit MeaningWhenSetOn
0 Encryptedkeyandmasterkeyverificationpattern(MKVP)arepresent.Thiswillbeofffor
clearkeys.
1 Controlvector(CV)valueinthistokenhasbeenappliedtothekey.Thiswillbeoffforclear
keys.
2-7 reserved
7-15 Reserved(X'00')
16-23 Asingle-lengthkey,thelefthalfofadouble-lengthkey,orPartAofatriple-lengthkey.
24-31 X'0000000000000000'ifasingle-lengthkey,therighthalfofadouble-lengthoperationalkey,orPartB
ofatriple-lengthoperationalkey.
32-47 Reservedforclearkeytokens(X'00's')
48-55 X'0000000000000000'ifasingle-lengthkeyordouble-lengthkey,orPartCofatriple-length
operationalkey.
56-58 Reserved(X'000000')
59bits0 B'00'reserved
and1
59bits2
Value Description
and3
B'00' Indicatessingle-lengthkey(version0only).
B'01' Indicatesdouble-lengthkey(version1only).
B'10' Indicatestriple-lengthkey(version1only).
59bits4-7 B'0000'
60-63 Tokenvalidationvalue(TVV).
DES internal key token
|
Table121 shows the format for a DES internal key token.
Table121.DESinternalkeytokenformat
Bytes Description
0 X'01'(flagindicatingthisisaninternalkeytoken)
1-3 Implementation-dependentbytes(X'000000'forICSF)
4 Keytokenversionnumber(X'00'orX'01')
5 Reserved(X'00')
AppendixB.Keytokenformats 423

Key token formats
Table121.DESinternalkeytokenformat (continued)
Bytes Description
6 Flagbyte
Bit MeaningWhenSetOn
0 Encryptedkeyandmasterkeyverificationpattern(MKVP)arepresent.
1 Controlvector(CV)valueinthistokenhasbeenappliedtothekey.
2 Keyisusedfornocontrolvector(NOCV)processing.Validfortransportkeysonly.
3 KeyisanANSIkey-encryptingkey(AKEK).
4 AKEKisadouble-lengthkey(16bytes).
Note: Whenbit3isonandbit4isoff,AKEKisasingle-lengthkey(eightbytes).
5 AKEKispartiallynotarized.
6 KeyisanANSIpartialkey.
7 Exportprohibited.
7 Reserved(X'00')
8-15 Masterkeyverificationpattern(MKVP)
16-23 Asingle-lengthkey,thelefthalfofadouble-lengthkey,orPartAofatriple-lengthkey.Thevalueis
encryptedunderthemasterkey.
24-31 X'0000000000000000'ifasingle-lengthkey,therighthalfofadouble-lengthoperationalkey,orPartB
ofatriple-lengthoperationalkey.Therighthalfofthedouble-lengthkeyorPartBofthetriple-length
keyisencryptedunderthemasterkey.
32-39 Thecontrolvector(CV)forasingle-lengthkeyorthelefthalfofthecontrolvectorforadouble-length
key.
40-47 X'0000000000000000'ifasingle-lengthkeyortherighthalfofthecontrolvectorforadouble-length
operationalkey.
48-55 X'0000000000000000'ifasingle-lengthkeyordouble-lengthkey,orPartCofatriple-length
operationalkey.PartCofatriple-lengthkeyisencryptedunderthemasterkey.
56-58 Reserved(X'000000')
59bits0
Value Description
and1
B'10' IndicatesKEK.
B'00' IndicatesDESforDATAkeysorthesystemdefaultalgorithmforaKEK.
B'01' IndicatesDESforaKEK.
59bits2
Value Description
and3
B'00' Indicatessingle-lengthkey(version0only).
B'01' Indicatesdouble-lengthkey(version1only).
B'10' Indicatestriple-lengthkey(version1only).
59bits4-7 B'0000'
60-63 Tokenvalidationvalue(TVV).
Note: AKEKs are not supported by this version of CCA. Key tokens from other CCAsystems, however,
could have theAKEK flag bits set in a key token.
DES external key token
Table122 shows the format for a DES external key token.
Table122.DESexternalkeytokenformat
Bytes Description
0 X'02'(flagindicatinganexternalkeytoken)
1 Reserved(X'00')
424 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table122.DESexternalkeytokenformat (continued)
Bytes Description
2-3 Implementation-dependentbytes(X'0000'forCCA)
4 Keytokenversionnumber(X'00'orX'01')
5 Reserved(X'00')
6 Flagbyte
Bit MeaningWhenSetOn
0 Encryptedkeyispresent.
1 Controlvector(CV)valuehasbeenappliedtothekey.
Otherbitsarereservedandarebinaryzeros.
7 Reserved(X'00')
8-15 Reserved(X'0000000000000000')
16-23 Single-lengthkeyorlefthalfofadouble-lengthkey,orPartAofatriple-lengthkey.Thevalueis
encryptedunderatransportkey.
24-31 X'0000000000000000'ifasingle-lengthkeyorrighthalfofadouble-lengthkey,orPartBofa
triple-lengthkey.Therighthalfofadouble-lengthkeyorPartBofatriple-lengthkeyisencrypted
underatransport(key-encryptingkey)forexportorimport.
32-39 Controlvector(CV)forsingle-lengthkeyorlefthalfofCVfordouble-lengthkey
40-47 X'0000000000000000'ifsingle-lengthkeyorrighthalfofCVfordouble-lengthkey
48-55 X'0000000000000000'ifasingle-lengthkey,double-lengthkey,orPartCofatriple-lengthkey.
56-58 Reserved(X'000000')
59bits0 B'00'
and1
59bits2
Value Description
and3
B'00' Indicatessingle-lengthkey(version0only).
B'01' Indicatesdouble-lengthkey(version1only).
B'10' Indicatestriple-lengthkey(version1only).
59bits4-7 B'0000'
60-63 Tokenvalidationvalue(see“TokenValidationValue”onpage422foradescription).
DES null key token
Table123 shows the format for a DES null key token.
Table123.DESnullkeytokenformat
Bytes Description
0 X'00'(flagindicatingthisisanullkeytoken).
1-15 Reserved(settobinaryzeros).
16-23 Single-lengthencryptedkey,lefthalfofdouble-lengthencryptedkey,orPartAoftriple-length
encryptedkey.
24-31 X'0000000000000000'ifasingle-lengthencryptedkey,therighthalfofdouble-lengthencryptedkey,or
PartBoftriple-lengthencryptedkey.
32-39 X'0000000000000000'ifasingle-lengthencryptedkeyordouble-lengthencryptedkey.
40-47 Reserved(settobinaryzeros).
48-55 PartCofatriple-lengthencryptedkey.
56-63 Reserved(settobinaryzeros).
AppendixB.Keytokenformats 425

Key token formats
RSA public key token
An RSApublic key token contains the following sections:
v Arequired token header, starting with the token identifier X'1E'
v Arequired RSApublic key section, starting with the section identifier X'04'
Table124 presents the format of an RSApublic key token.All length fields are in binary.All binary fields
(exponents, lengths, and so on) are stored with the high-order byte first (left, low-address, S/390 format).
Table124.RSAPublicKeyTokenformat
Offset(Decimal) Lengthinbytes Description
TokenHeader(Required)
000 001 Tokenidentifier.X'1E'indicatesanexternaltoken.
001 001 Version,X'00'.
002 002 Lengthofthekeytokenstructure.
004 004 Ignored.Shouldbe0.
RSAPublicKeySection(Required)
000 001 X'04',sectionidentifier,RSApublickey.
001 001 X'00',version.
002 002 Sectionlength,12+xxx+yyy
004 002 Reservedfield.
006 002 RSApublickeyexponentfieldlengthinbytes,“xxx”.
008 002 Publickeymoduluslengthinbits.
010 002 RSApublickeymodulusfieldlengthinbytes,“yyy”.
012 xxx Publickeyexponent(thisisgenerallya1,3,or64-256-bytequantity),
namede.emustbeoddand1<e<n.(Frequently,thevalueofeis216+
1).
Note: YoucanimportanRSApublickeyhavinganexponentvaluedtotwo
(2).SuchapublickeycancorrectlyvalidateanISO9796-1digitalsignature.
However,thecurrentproductimplementationdoesnotgenerateanRSAkey
withapublicexponentvaluedtotwo(aRabinkey).
12+xxx yyy Modulus,n.
RSA private external key token
An RSAprivate external key token contains the following sections:
v Arequired PKAtoken header starting with the token identifier X'1E'
v Arequired RSAprivate key section starting with one of the following section identifiers:
| – X'02' indicates a Modulus-Exponent format RSAprivate key section (not optimized) with modulus
| length of up to 1024 bits.
| – X'06' indicates a Modulus-Exponent internal format RSAprivate key section (not optimized) with
| modulus length of up to 1024 bits for use with the CEX3C.
– X'08' indicates an optimized Chinese Remainder Theorem format private key section with modulus
bit length of up to 2048 bits for use with the CEX3C.
v Arequired RSApublic key section, starting with the section identifier X'04'
v An optional private key name section, starting with the section identifier X'10'
426 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table125 presents the basic record format of an RSAprivate external key token.All length fields are in
binary.All binary fields (exponents, lengths, and so on) are stored with the high-order byte first (left,
low-address, S/390 format).All binary fields (exponents, modulus, and so on) in the private sections of
tokens are right-justified and padded with zeros to the left.
Table125.RSAprivateexternalkeytokenbasicrecordformat
Offset(Decimal) Lengthinbytes Description
TokenHeader(Required)
000 001 Tokenidentifier.X'1E'indicatesanexternaltoken.Theprivatekeyis
eitherincleartextorencipheredwithatransportkey-encryptingkey.
001 001 Version,X'00'.
002 002 Lengthofthekeytokenstructure.
004 004 Ignored.Shouldbezero.
RSAPrivateKeySection(Required)
v For1024-bitModulus-Exponentformat,referto“RSAprivatekeytoken,1024-bitModulus-Exponentexternal
format”
v For2048-bitChineseRemainderTheoremformat,referto“RSAprivatekeytoken,2048-bitChineseRemainder
Theoremexternalformat”onpage428
RSAPublicKeySection(Required)
000 001 X'04',sectionidentifier,RSApublickey.
001 001 X'00',version.
002 002 Sectionlength,12+xxx.
004 002 Reservedfield.
006 002 RSApublickeyexponentfieldlengthinbytes,“xxx”.
008 002 Publickeymoduluslengthinbits.
010 002 RSApublickeymodulusfieldlengthinbytes,whichiszeroforaprivate
token.
Note: InanRSAprivatekeytoken,thisfieldshouldbezero.TheRSA
privatekeysectioncontainsthemodulus.
012 xxx Publickeyexponent,e(thisisgenerallya1,3,or64-256-bytequantity).
emustbeoddand1<e<n.(Frequently,thevalueofeis216+1(=
65,537).
Note: YoucanimportanRSApublickeyhavinganexponentvaluedto
two(2).SuchapublickeycancorrectlyvalidateanISO9796-1digital
signature.However,thecurrentproductimplementationdoesnotgenerate
anRSAkeywithapublicexponentvaluedtotwo(aRabinkey).
PrivateKeyName(Optional)
000 001 X'10',sectionidentifier,privatekeyname.
001 001 X'00',version.
002 002 Sectionlength,X'0044'(68decimal).
004 064 Privatekeyname(inASCII),left-justified,paddedwithspacecharacters
(X'20').Anaccesscontrolsystemcanusetheprivatekeynametoverify
thecallingapplicationisentitledtousethekey.
RSA private key token, 1024-bit Modulus-Exponent external format
This RSAprivate key token and the external X'02' token is supported on the CEX3C. Table126 on page
428 shows the format.
AppendixB.Keytokenformats 427

Key token formats
Table126.RSAprivatekeytoken,1024-bitModulus-Exponentexternalformat
Offset(Decimal) Lengthinbytes Description
000 001 X'02',sectionidentifier,RSAprivatekey,Modulus-Exponentformat
(RSA-PRIV)
001 001 X'00',version.
002 002 LengthoftheRSAprivatekeysectionX'016C'(364decimal).
004 020 SHA-1hashvalueoftheprivatekeysubsectioncleartext,offset28tothe
sectionend.Thishashvalueischeckedafteranencipheredprivatekeyis
decipheredforuse.
024 004 Reserved;settobinaryzero.
028 001 Keyformatandsecurity:
Value Description
X'00' UnencryptedRSAprivatekeysubsectionidentifier.
X'82' EncryptedRSAprivatekeysubsectionidentifier.
029 001 Reserved,binaryzero.
030 020 SHA-1hashoftheoptionalkey-namesection.Ifthereisnokey-name
section,then20bytesofX'00'.
050 004 Keyuseflagbits.
Bit MeaningWhenSetOn
0 Keymanagementusagepermitted.
1 Signatureusagenotpermitted.
Allotherbitsreserved,settobinaryzero.
054 006 Reserved;settobinaryzero.
060 024 Reserved;settobinaryzero.
084 Startoftheoptionally-encryptedsecuresubsection.
084 024 Randomnumber,confounder.
108 128 Private-keyexponent,d.d=e-1mod((p-1)(q-1)),and1<d<nwhereeis
thepublicexponent.
Endoftheoptionally-encryptedsubsection;theconfounderfieldandtheprivate-keyexponentfield
areencipheredforkeyconfidentialitywhenthekeyformatandsecurityflags(offset28)indicate
theprivatekeyisenciphered.Theyareencipheredunderadouble-lengthtransportkeyusingthe
ede2algorithm.
236 128 Modulus,n.n=pqwherepandqareprimeand1<n<21024.
RSA private key token, 2048-bit Chinese Remainder Theorem external
format
This RSAprivate key token is supported on the CEX3C. Table127 shows the format.
Table127.RSAprivatekeytoken,2048-bitChineseRemainderTheoremexternalformat
Offset(Dec) Lengthinbytes Description
000 001 X'08',sectionidentifier,RSAprivatekey,CRTformat(RSA-CRT)
001 001 X'00',version.
002 002 LengthoftheRSAprivate-keysection,132+ppp+qqq+rrr+sss+uuu
+xxx+nnn.
004 020 SHA-1hashvalueoftheprivatekeysubsectioncleartext,offset28tothe
endofthemodulus.
428 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table127.RSAprivatekeytoken,2048-bitChineseRemainderTheoremexternalformat (continued)
Offset(Dec) Lengthinbytes Description
024 004 Reserved;settobinaryzero.
028 001 Keyformatandsecurity:
Value Description
X'40' UnencryptedRSAprivate-keysubsectionidentifier,Chinese
RemainderTheoremformat.
X'42' EncryptedRSAprivate-keysubsectionidentifier,Chinese
RemainderTheoremformat.
029 001 Reserved;settobinaryzero.
030 020 SHA-1hashoftheoptionalkey-namesectionandanyfollowingoptional
sections.Iftherearenooptionalsections,then20bytesofX'00'.
050 004 Keyuseflagbits.
Bit MeaningWhenSetOn
0 Keymanagementusagepermitted.
1 Signatureusagenotpermitted.
Allotherbitsreserved,settobinaryzero.
054 002 Lengthofprimenumber,p,inbytes:"ppp."
056 002 Lengthofprimenumber,q,inbytes:"qqq."
058 002 Lengthofd ,inbytes:"rrr."
p
060 002 Lengthofd ,inbytes:"sss."
q
062 002 LengthofU,inbytes:"uuu."
064 002 Lengthofmodulus,n,inbytes:"nnn."
066 004 Reserved;settobinaryzero.
070 002 Lengthofpaddingfield,inbytes:"xxx."
072 004 Reserved,settobinaryzero.
076 016 Reserved,settobinaryzero.
092 032 Reserved;settobinaryzero.
124 Startoftheoptionally-encryptedsecuresubsection.
124 008 Randomnumber,confounder.
132 ppp Primenumber,p.
132+ppp qqq Primenumber,q
132+ppp+qqq rrr d =dmod(p-1)
p
132+ppp+qqq sss d =dmod(q-1)
q
+rrr
132+ppp+qqq uuu U=q–1mod(p).
+rrr+sss
132+ppp+qqq xxx X'00'paddingoflengthxxxbytessuchthatthelengthfromthestartofthe
+rrr+sss+uuu randomnumberabovetotheendofthepaddingfieldisamultipleof
eightbytes.
Endoftheoptionally-encryptedsecuresubsection;allofthefieldsstartingwiththeconfounder
fieldandendingwiththevariablelengthpadfieldareencipheredforkeyconfidentialitywhenthe
keyformat-and-securityflags(offset28)indicatetheprivatekeyisenciphered.Theyare
encipheredunderadouble-lengthtransportkeyusingtheTDES(CBCouterchaining)algorithm.
AppendixB.Keytokenformats 429

Key token formats
Table127.RSAprivatekeytoken,2048-bitChineseRemainderTheoremexternalformat (continued)
Offset(Dec) Lengthinbytes Description
132+ppp+qqq nnn Modulus,n.n=pqwherepandqareprimeand1<n<22048.
+rrr+sss+uuu
+xxx
RSA private internal key token
|
An RSAprivate internal key token contains the following sections:
v Arequired PKAtoken header, starting with the token identifier X'1F'
v Basic record format of an RSAprivate internal key token.All length fields are in binary.All binary fields
(exponents, lengths, and so on) are stored with the high-order byte first (left, low-address, S/390
format).All binary fields (exponents, modulus, and so on) in the private sections of tokens are
right-justified and padded with zeros to the left.
Table128 shows the format.
Table128.RSAprivateinternalkeytokenbasicrecordformat
Offset
(Decimal) Lengthinbytes Description
TokenHeader(Required)
000 001 Tokenidentifier.X'1F'indicatesaninternaltoken.Theprivatekeyis
encipheredwithaPKAmasterkey.
001 001 Version,X'00'.
002 002 Lengthofthekeytokenstructureexcludingtheinternalinformation
section.
004 004 Ignored;shouldbezero.
RSAPrivateKeySectionandSecuredSubsection(Required)
v For1024-bitX'02'Modulus-Exponentformat,referto“RSAprivatekeytoken,1024-bitModulus-Exponentinternal
formatforcryptographiccoprocessorfeature”onpage431
v For1024-bitX'06'Modulus-Exponentformat,referto“RSAprivatekeytoken,1024-bitModulus-Exponentinternal
formatforCEX3C”onpage432
v For2048-bitX'08'ChineseRemainderTheoremformat,referto“RSAprivatekeytoken,2048-bitChinese
RemainderTheoreminternalformat”onpage433
RSAPublicKeySection(Required)
000 001 X'04',sectionidentifier,RSApublickey.
001 001 X'00',version.
002 002 Sectionlength,12+xxx.
004 002 Reservedfield.
006 002 RSApublickeyexponentfieldlengthinbytes,“xxx”.
008 002 Publickeymoduluslengthinbits.
010 002 RSApublickeymodulusfieldlengthinbytes,whichiszeroforaprivate
token.
012 xxx Publickeyexponent(thisisgenerallya1,3,or64-256-bytequantity),e.
emustbeoddand1<e<n.(Frequently,thevalueofeis216+1(=
65,537).
Note: YoucanimportanRSApublickeyhavinganexponentvaluedto
two(2).SuchapublickeycancorrectlyvalidateanISO9796-1digital
signature.However,thecurrentproductimplementationdoesnot
generateanRSAkeywithapublicexponentvaluedtotwo(aRabinkey).
430 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table128.RSAprivateinternalkeytokenbasicrecordformat (continued)
Offset
(Decimal) Lengthinbytes Description
PrivateKeyName(Optional)
000 001 X'10',sectionidentifier,privatekeyname.
001 001 X'00',version.
002 002 Sectionlength,X'0044'(68decimal).
004 064 Privatekeyname(inASCII),left-justified,paddedwithspacecharacters
(X'20').Anaccesscontrolsystemcanusetheprivatekeynametoverify
thecallingapplicationisentitledtousethekey.
InternalInformationSection(Required)
000 004 Eyecatcher'PKTN'.
004 004 PKAtokentype.
Bit MeaningWhenSetOn
0 RSAkey.
2 Privatekey.
3 Publickey.
4 Privatekeynamesectionexists.
5 Privatekeyunenciphered.
6 Blindinginformationpresent.
7 Retainedprivatekey.
008 004 Addressoftokenheader.
012 002 Totallengthoftotalstructureincludingthisinformationsection.
014 002 Countofnumberofsections.
016 016 PKAmasterkeyhashpattern.
032 001 Domainofretainedkey.
033 008 Serialnumberofprocessorholdingretainedkey.
041 007 Reserved.
RSA private key token, 1024-bit Modulus-Exponent internal format for
cryptographic coprocessor feature
Table129 shows the format of the RSAprivate key token, 1024-bit Modulus-Exponent internal format for
cryptographic coprocessor feature.
Table129.RSAprivateinternalkeytoken,1024-bitModulus-Exponentformatforcryptographiccoprocessorfeature
Offset
(Decimal) Lengthinbytes Description
000 001 X'02',sectionidentifier,RSAprivatekey.
001 001 X'00',version.
002 002 LengthoftheRSAprivatekeysectionX'016C'(364decimal).
004 020 SHA-1hashvalueoftheprivatekeysubsectioncleartext,offset28tothe
sectionend.Thishashvalueischeckedafteranencipheredprivatekey
isdecipheredforuse.
024 004 Reserved;settobinaryzero.
028 001 Keyformatandsecurity:
X'02' RSAprivatekey.
AppendixB.Keytokenformats 431

Key token formats
Table129.RSAprivateinternalkeytoken,1024-bitModulus-Exponentformatforcryptographiccoprocessor
feature (continued)
Offset
(Decimal) Lengthinbytes Description
029 001 Formatofexternalkeyfromwhichthistokenwasderived:
Value Description
X'21' Externalprivatekeywasspecifiedintheclear.
X'22' Externalprivatekeywasencrypted.
030 020 SHA-1hashofthekeytokenstructurecontentsthatfollowthepublickey
section.Ifnosectionsfollow,thisfieldissettobinaryzeros.
050 001 Keyuseflagbits.
Bit MeaningWhenSetOn
0 Keymanagementusagepermitted.
1 Signatureusagenotpermitted.
Allotherbitsreserved,settobinaryzero.
051 009 Reserved;settobinaryzero.
060 048 ObjectProtectionKey(OPK)encryptedunderaPKAmasterkey—canbe
undertheSignatureMasterKey(SMK)orKeyManagementMasterKey
(KMMK)dependingonkeyuse.
108 128 Secretkeyexponentd,encryptedundertheOPK.d=e-1mod((p-1)(q-1))
236 128 Modulus,n.n=pqwherepandqareprimeand1<n<21024.
RSA private key token, 1024-bit Modulus-Exponent internal format for
CEX3C
Table130 shows the format for the RSAprivate key token, 1024-bit Modulus-Exponent internal format for
CEX3C.
Table130.RSAprivateinternalkeytoken,1024-bitModulus-ExponentformatforCEX3C
Offset
(Decimal) Lengthinbytes Description
000 001 X'06',sectionidentifier,RSAprivatekeyModulus-Exponentformat
(RSA-PRIV).
001 001 X'00',version.
002 002 LengthoftheRSAprivatekeysectionX'0198'(408decimal)+rrr+iii+
xxx.
004 020 SHA-1hashvalueoftheprivatekeysubsectioncleartext,offset28toand
includingthemodulusatoffset236.
024 004 Reserved;settobinaryzero.
028 001 Keyformatandsecurity:
X'02' RSAprivatekey.
029 001 Formatofexternalkeyfromwhichthistokenwasderived:
X'21' Externalprivatekeywasspecifiedintheclear.
X'22' Externalprivatekeywasencrypted.
X'23' Privatekeywasgeneratedusingregenerationdata.
X'24' Privatekeywasrandomlygenerated.
030 020 SHA-1hashoftheoptionalkey-namesectionandanyfollowingoptional
sections.Iftherearenooptionalsections,thisfieldissettobinaryzeros.
432 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table130.RSAprivateinternalkeytoken,1024-bitModulus-ExponentformatforCEX3C (continued)
Offset
(Decimal) Lengthinbytes Description
050 004 Keyuseflagbits.
Bit MeaningWhenSetOn
0 Keymanagementusagepermitted.
1 Signatureusagenotpermitted.
Allotherbitsreserved,settobinaryzeros.
054 006 Reserved;settobinaryzero.
060 048 ObjectProtectionKey(OPK)encryptedundertheAsymmetricKeys
MasterKeyusingtheede3algorithm.
108 128 Privatekeyexponentd,encryptedundertheOPKusingtheede5
algorithm.d=e-1mod((p-1)(q-1)),and1<d<nwhereeisthepublic
exponent.
236 128 Modulus,n.n=pqwherepandqareprimeand2512<n<21024.
364 016 Asymmetric-KeysMasterKeyhashpattern.
380 020 SHA-1hashvalueoftheblindinginformationsubsectioncleartext,offset
400totheendofthesection.
400 002 Lengthoftherandomnumberr,inbytes:rrr.
402 002 Lengthoftherandomnumberr–1,inbytes:iii.
404 002 Lengthofthepaddingfield,inbytes:xxx.
406 002 Reserved;settobinaryzeros.
408 Startoftheencryptedblindingsubsection
408 rrr Randomnumberr(usedinblinding).
408+rrr iii Randomnumberr–1(usedinblinding).
408+rrr+iii xxx X'00'paddingoflengthxxxbytessuchthatthelengthfromthestartof
theencryptedblindingsubsectiontotheendofthepaddingfieldisa
multipleofeightbytes.
Endoftheencryptedblindingsubsection;allofthefieldsstartingwiththerandomnumberrand
endingwiththevariablelengthpadfieldareencryptedundertheOPKusingTDES(CBCouter
chaining)algorithm.
RSA private key token, 2048-bit Chinese Remainder Theorem internal
format
This RSAprivate key token is supported on the CEX3C. Table131 shows the format.
Table131.RSAprivateinternalkeytoken,2048-bitChineseRemainderTheoreminternalformat
Offset(Decimal) Lengthinbytes Description
000 001 X'08',sectionidentifier,RSAprivatekey,CRTformat(RSA-CRT)
001 001 X'00',version.
002 002 LengthoftheRSAprivate-keysection,132+ppp+qqq+rrr+sss+
uuu+ttt+iii+xxx+nnn.
004 020 SHA-1hashvalueoftheprivate-keysubsectioncleartext,offset28to
theendofthemodulus.
024 004 Reserved;settobinaryzero.
AppendixB.Keytokenformats 433

Key token formats
Table131.RSAprivateinternalkeytoken,2048-bitChineseRemainderTheoreminternalformat (continued)
Offset(Decimal) Lengthinbytes Description
028 001 Keyformatandsecurity:
X'08' EncryptedRSAprivate-keysubsectionidentifier,Chinese
RemainderTheoremformat.
029 001 Keyderivationmethod:
Value Description
X'21' Externalprivatekeywasspecifiedintheclear.
X'22' Externalprivatekeywasencrypted.
X'23' Privatekeywasgeneratedusingregenerationdata.
X'24' Privatekeywasrandomlygenerated.
030 020 SHA-1hashoftheoptionalkey-namesectionandanyfollowing
sections.Iftherearenooptionalsections,then20bytesofX'00'.
050 004 Keyuseflagbits:
Bit MeaningWhenSetOn
0 Keymanagementusagepermitted.
1 Signatureusagenotpermitted.
Allotherbitsreserved,settobinaryzero.
054 002 Lengthofprimenumber,p,inbytes:"ppp."
056 002 Lengthofprimenumber,q,inbytes:"qqq."
058 002 Lengthofd ,inbytes:"rrr."
p
060 002 Lengthofd ,inbytes:"sss."
q
062 002 LengthofU,inbytes:"uuu."
064 002 Lengthofmodulus,n,inbytes:"nnn."
066 002 Lengthoftherandomnumberr,inbytes:"ttt."
068 002 Lengthoftherandomnumberr–1,inbytes:"iii."
070 002 Lengthofpaddingfield,inbytes:"xxx."
072 004 Reserved,settobinaryzero.
076 016 Asymmetric-KeysMasterKeyhashpattern.
092 032 ObjectProtectionKey(OPK)encryptedundertheAsymmetric-Keys
MasterKeyusingtheTDES(CBCouterchaining)algorithm.
124 Startoftheencryptedsecuresubsection,encryptedundertheOPKusingTDES(CBCouter
chaining).
124 008 Randomnumber,confounder.
132 ppp Primenumber,p.
132+ppp qqq Primenumber,q
132+ppp+qqq rrr d =dmod(p-1)
p
132+ppp+qqq sss d =dmod(q-1)
q
+rrr
132+ppp+qqq uuu U=q–1mod(p).
+rrr+sss
132+ppp+qqq ttt Randomnumberr(usedinblinding).
+rrr+sss+uuu
132+ppp+qqq iii Randomnumberr–1(usedinblinding).
+rrr+sss+uuu
+ttt
434 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table131.RSAprivateinternalkeytoken,2048-bitChineseRemainderTheoreminternalformat (continued)
Offset(Decimal) Lengthinbytes Description
132+ppp+qqq xxx X'00'paddingoflengthxxxbytessuchthatthelengthfromthestartof
+rrr+sss+uuu theconfounderatoffset124totheendofthepaddingfieldisa
+ttt+iii multipleofeightbytes.
Endoftheencryptedsecuresubsection;allofthefieldsstartingwiththeconfounderfieldand
endingwiththevariablelengthpadfieldareencryptedundertheOPKusingTDES(CBCouter
chaining)forkeyconfidentiality.
132+ppp+qqq nnn Modulus,n.n=pqwherepandqareprimeand1<n<22048.
+rrr+sss+uuu
+ttt+iii+xxx
RSA variable Modulus-Exponent token
Table132 describes the fields in the new variable length Modulus-Exponent token. Currently, only the
external form of the token will be used. There are no blinding values for the token. The latest level
hardware makes this unnecessary.
Table132.RSAvariableModulus-Exponenttokenformat
Num Newversion'09' Length
ber IfExternalKey field IfInternalKey inbytes
1 '09' sectionId '09' 1
2 '00' version '00' 1
3 132+dLength+nLength+padLength sectionLength 132+dLength+nLength+ 2
padLength
4 Hashoverfields7-endofsection sha1Hash Hashoverfields7-endofsection 20
(clearvalues)
5 8+dLength+padLength encrypted 8+dLength+padLength 2
sectionLength
6 Thisisactuallyareservedfield,nota pad '0000' 2
pad'0000'
7 '82' encrypted external key or keyFormat '02'encryptedoperationalkey 1
'00' clear external key
8 '00' pedigree '21','22','23',or'24'as'06'token 1
9 Hashoversectionswhichfollowthe sha1Key Hashoversectionswhichfollowthe 20
publickeysection,or'00' NameHash publickeysection,or'00'
10 ’02’indicatesthatthekeyistranslatable keyUsageFlag sameasin'06' 1
11 '00' reserved1 '00' 1
12 Binaryzeroes OPK 8byteconfounder+40-byte 48
(5-part)DESkey,encryptedwith
thePKAmasterkey
13 Binaryzeroes mkHashPattern 16byteMKVP 16
14 Lengthofprivateexponent dLength Lengthofprivateexponent 2
15 Lengthofmodulus nLength Lengthofmodulus 2
16 LengthrequiredtopaddLengthtoa padLength LengthrequiredtopaddLengthto 2
multipleof8 amultipleof8
17 '0000' reserved2 '0000' 2
AppendixB.Keytokenformats 435

Key token formats
Table132.RSAvariableModulus-Exponenttokenformat (continued)
Num Newversion'09' Length
ber IfExternalKey field IfInternalKey inbytes
18 Randomvalue-encrypteddata(with confounder encrypteddata(with5-partOPK) 8
PKAMK)beginshere beginshere
19 <dfollows,then 1
pad,thenn>
ECC key token
|
| Table133 shows the format of an ECC key token.
|| Table133.ECCkeytokenformat
| Offset
||| (Decimal) Lengthinbytes Description
||| 000 001 Tokenidentifier
|| X'00' Null
|| X'1E' Externaltoken
|| X'1F' Internaltoken;theprivatekeyisprotectedbythemasterkey
||| 001 001 X'00',version.
||| 002 002 Lengthofthekeytokenstructureexcludingtheinternalinformation
| section.
||| 004 004 Ignored;shouldbezero.
| ECCtokenprivatesection
||| 000 001 X'20',sectionidentifier,ECCprivatekey
||| 001 001 X'00',version.
||| 002 002 Sectionlength.
||| 004 001 WrappingMethod:Thisvalueindicatesthewrappingmethodusedto
| protectthedataintheencryptedsection.Itisnotthemethodusedto
| protecttheObjectProtectionKey(OPK).
|| X'00' Clear–sectionisunencrypted.
|| X'01' AESKW
|| X'02' CBCWrap-Other
||| 005 001 HashusedforWrapping
|| X'01' SHA224
|| X'02' SHA256
|| X'04' Reserved
|| X'08' Reserved
||| 006 002 Reservedbinaryzero
||| 008 001 KeyUsage:
|| X'C0' Keyagreement
|| X'80' Bothsignaturegenerationandkeyagreement
|| X'00' Signaturegenerationonly
|| X'02' Translateallowed
| Thetwohigh-orderbitsindicatepermittedkeyusageinthedecryptionof
| symmetrickeysandinthegenerationofdigitalsignatures.Thebitinthe
| secondnibbleindicatesifthekeyistranslatable.Akeyistranslatableifit
| canbere-encryptedfromonekeyencryptingkeytoanother.
436 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
| Table133.ECCkeytokenformat (continued)
| Offset
||| (Decimal) Lengthinbytes Description
||| 009 001 Curvetype:
|| X'00' Primecurve
|| X'01' Brainpoolcurve
||| 010 001 Keyformatandsecurityflag.
| ExternalToken:
|| X'40' UnencryptedECCprivatekeyidentifier
|| X'42' EncryptedECCprivatekeyidentifier
| Internaltoken:
|| X'08' EncryptedECCprivatekeyidentifier
||| 011 001 Reservedbinaryzero
||| 012 002 Lengthofpinbits
|| X'00A0' Brainpoolp-160
|| X'00C0' PrimeP-192,BrainpoolP-192
|| X'00E0' PrimeP-224,BrainpoolP-224
|| X'0100' PrimeP-256,BrainpoolP-256
|| X'0140' BrainpoolP-320
|| X'0180' PrimeP-384,BrainpoolP-384
|| X'0200' BrainpoolP-512
|| X'0209' PrimeP-521
||| 014 002 IBMassociateddatalength.Thelengthofthisfieldmustbegreaterthan
| orequalto16.
||| 016 008 Externaltoken:Reservedbinaryzero.
| InternalToken:MKVP
||| 024 048 Externaltoken:Reservedbinaryzero.
| InternalToken:ObjectProtectionKey(OPK),ICV(IntegrityCheckvalue),
| 8byteconfounderanda256-bitAESkeyusedwiththeAESKWalgorithm
| toencrypttheECCprivatekey.
| TheOPKisencryptedbytheAESmasterkeyusingAESKWaswell.
| ExampleformatforOPKdatapassedtoAESKW:
| v 8bytes=A6A6A6A6A6A60000
| v 40bytes=Confounder(8)/Key(32)
||| 072 002 Associateddatalength,aa
||| 074 002 Lengthofformattedsectioninbytes,bb
||| 076 aa Associateddata.See“AssociateddataformatforECCprivatekeytoken”
| onpage438.
||| 076+aa Startofformatted Ifthissectionisintheclear,itcontainsprivatekeyd.
| section
| Ifthissectionisencrypted,itcontainstheAESKWwrappedpayload.
||| 076+aa bb FormattedsectionwhichincludesPrivatekeyd.See“AESKWwrapped
| payloadformatforECCprivatekeytoken”onpage439.
|| 076+aa+bb Endofformattedsection
| ECCtokenpublicsection
||| 000 001 X'21',sectionidentifier,ECCpublickey
||| 001 001 X'00',version.
||| 002 001 Sectionlength.
AppendixB.Keytokenformats 437

Key token formats
| Table133.ECCkeytokenformat (continued)
| Offset
||| (Decimal) Lengthinbytes Description
||| 004 004 Reservedbinaryzero
||| 008 001 Curvetype:
|| X'00' Primecurve
|| X'01' Brainpoolcurve
||| 009 001 Reservedbinaryzero
||| 010 002 Lengthofpinbits
|| X'00A0' Brainpoolp-160
|| X'00C0' PrimeP-192,BrainpoolP-192
|| X'00E0' PrimeP-224,BrainpoolP-224
|| X'0100' PrimeP-256,BrainpoolP-256
|| X'0140' BrainpoolP-320
|| X'0180' PrimeP-384,BrainpoolP-384
|| X'0200' BrainpoolP-512
|| X'0209' PrimeP-521
||| 012 002 Thisfieldisthelengthofthepublickeyqvalueinbytes,themaximum
| valuecouldbeupto133bytes,cc.Thevalueincludesthekeymaterial
| lengthandonebytetoindicateifthekeymaterialiscompressedor
| uncompressed.
||| 014 cc PublicKey,qfield
|
Associated data format for ECC private key token
|
| Table134 shows the format of associated data for an ECC private key token in the clear.Associated data
| is data whose integrity but not confidentiality is protected by a key wrap mechanism.
|| Table134.AssociateddataformatforECCprivatekeytoken
| Offset
||| (Decimal) Lengthinbytes Description
||| 000 001 Associateddataversion.0forECC
||| 001 001 LengthofKeylabel,kl
||| 002 002 IBMassociateddatalength,16+kl+xxx
||| 004 002 IBMextendedassociateddatalength,xxx
||| 006 001 Userdefinableassociateddatalength,yyy.Userdefinablelengthsare0-
| 100bytes.
||| 007 001 Curvetype
||| 008 002 Lengthofpinbits
||| 010 001 Usageflag
||| 011 001 Formatandsecurityflag
||| 012 004 Reserved
||| 016 kl Keylabel(optional)
||| 016+kl xxx IBMextendedassociateddata
||| 016+kl+xxx User-definableassociateddata
|
438 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
AESKW wrapped payload format for ECC private key token
|
| Table135 defines the contents of theAESKW payload. Data will be copied into this format, then encrypted
| with the OPK according to theAESKW specification, and the result will be stored in the encrypted data
| section.
|| Table135.AESKWwrappedpayloadformatforECCprivatekeytoken
| Offset
||| (Decimal) Lengthinbytes Description
||| 000 006 ICV('A6'....)
||| 006 001 Lengthofpaddinginbits
||| 007 001 Lengthofthehashoftheassociateddatainbytes,ii
||| 008 004 Hashoptions
||| 012 ii Hashofassociateddata
||| 012+ii mm Keydata
||| 012+ii+mm 0-7 Paddingtoamultipleof8bytes
|
|
PKA null key token
Table136 shows the format for a PKAnull key token.
Table136.PKAnullkeytokenformat
Bytes Description
0 X'00'Tokenidentifier(indicatesthatthisisanullkeytoken).
1 Version,X'00'.
2-3 X'0008'Lengthofthekeytokenstructure.
4-7 Ignored(shouldbezero).
HMAC key token
|
| HMAC key tokens have two formats, “HMAC variable-length symmetric key token” and “HMAC symmetric
| null key token” on page 443.
HMAC variable-length symmetric key token
|
| Table137 shows the format of the HMAC variable-length symmetric key-token.An HMAC token is used by
| the HMAC Generate(CSNBHMG) and HMAC Verify(CSNBHMV) verbs to generate and verify keyed hash
| MessageAuthentication Codes.
|| Table137.HMACvariable-lengthsymmetrickey-token,versionX'05'(CCA4.1.0orlater)
| Length
||| Offset(bytes) (bytes) Description
| Header
||| 000 01 Tokenidentifier:
|| Value Description
|| X'00' Internalkey-token
|| X'01' Externalkey-token
||| 001 01 Reserved,binaryzero.
AppendixB.Keytokenformats 439

Key token formats
| Table137.HMACvariable-lengthsymmetrickey-token,versionX'05'(CCA4.1.0orlater) (continued)
| Length
||| Offset(bytes) (bytes) Description
||| 002 02 Lengthinbytesoftheoveralltokenstructure.
| 54+kl+iead+uad+TLVlengths+((pl+7)/8)
||| 004 01 Tokenversionnumber(X'05').
||| 005 03 Reserved,binaryzero.
| Endofheader
| Wrappinginformationsection(alldatarelatedtowrappingthetoken)
||| 008 01 Keymaterialstate:
|| Value Description
|| X'00' Nokeypresent(internalorexternal)
|| X'01' Keyisclear(internal)
|| X'02' KeyisencryptedunderaKEK(external)
|| X'03' Keyisencryptedunderthemasterkey(internal)
||| 009 01 Keyverificationpattern(KVP)type:
|| Value Description
|| X'00' NoKVP
|| X'01' AES-MK(8leftmostbytesofSHA-256hash(X'01'||clearAESMK))
|| X'02' KEKverificationpattern
| Note: Key-wrappingmethodX'03'(PKOAEP2)hasnoKVP.
||| 010 16 KVP.
| Valueisleftjustifiedinthefieldandpaddedontherightwithbinaryzeros.
| Note: Forkey-wrappingmethodX'03'(PKOAEP2),thisvalueisfilledwithbinary
| zeros.
||| 026 01 Encryptedsectionkey-wrappingmethod:
|| Value Description
|| X'00' Clearkey
|| X'02' AESKW
|| X'03' PKOAEP2
||| 027 01 Hashalgorithmusedforwrapping.
| Forclearkeywrappingmethod(X'00'atoffset26):
|| X'00' Clearkey(nohash)
| ForAESKWwrappingmethod(X'02'atoffset26):
|| X'02' SHA-256
| ForPKOAEP2wrappingmethod(X'03'atoffset26):
|| Value Description
|| X'01' SHA-1
|| X'02' SHA-256
|| X'04' SHA-384
|| X'08' SHA-512
||| 028 02 Reserved,binaryzero.
| Endofwrappinginformationsection
| AESKWcomponents:(1)associateddataand(2)optionalclearkeyorencryptedAESKWpayload.
| Associateddatasection
||| 030 01 Associateddatasectionversion(X'01').
440 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
| Table137.HMACvariable-lengthsymmetrickey-token,versionX'05'(CCA4.1.0orlater) (continued)
| Length
||| Offset(bytes) (bytes) Description
||| 031 01 Reserved,binaryzero.
||| 032 02 Lengthinbytesoftheassociateddata.
| 24+kl+iead+uad+TLVlengths
||| 034 01 Lengthinbytesofthekeylabel:kl(0or64).
||| 035 01 LengthinbytesoftheIBMextendedassociateddata:iead(0).
||| 036 01 Lengthinbytesoftheuser-definableassociateddata:uad(0-255).
||| 037 01 Reserved,binaryzero.
||| 038 02 Lengthinbitsofthepayload:pl.
| Validvaluesare0whennokeyispresent,80-2048whenkeyisclear,and464-
| 2432whenkeyisencrypted.
||| 040 01 Reserved,binaryzero.
||| 041 01 Typeofalgorithmforwhichthekeycanbeused.
|| X'03' HMAC
||| 042 02 Keytype:
|| X'0002' MAC
||| 044 01 Key-usagefieldscount:kuf(2).
||| 045 02 Key-usagefield1.
| High-orderbyte:
|| Value Description
|| B'1xxxxxxx' Keycanbeusedforgenerate.
|| B'0xxxxxxx' Keycannotbeusedforgenerate.
|| B'x1xxxxxx' Keycanbeusedforverify.
|| B'x0xxxxxx' Keycannotbeusedforverify.
| Allunusedbitsarereservedandmustbezero.
| Low-orderbyte:
|| Value Description
|| B'xxxx1xxx' Thekeycanbeusedonlyinuser-definedextensions(UDXs).
|| B'xxxx0xxx' ThekeycanbeusedinUDXsandCCA.
|| B'xxxxxuuu' ReservedforUDXs,whereuuuareUDX-definedbits.
| Allunusedbitsarereservedandmustbezero.
AppendixB.Keytokenformats 441

Key token formats
| Table137.HMACvariable-lengthsymmetrickey-token,versionX'05'(CCA4.1.0orlater) (continued)
| Length
||| Offset(bytes) (bytes) Description
||| 047 02 Key-usagefield2.
| High-orderbyte:
|| Value Description
|| B'1xxxxxxx' SHA-1hashmethodisallowedforthekey.
|| B'0xxxxxxx' SHA-1hashmethodisnotallowedforthekey.
|| B'x1xxxxxx' SHA-224hashmethodisallowedforthekey.
|| B'x0xxxxxx' SHA-224hashmethodisnotallowedforthekey.
|| B'xx1xxxxx' SHA-256hashmethodisallowedforthekey.
|| B'xx0xxxxx' SHA-256hashmethodisnotallowedforthekey.
|| B'xxx1xxxx' SHA-384hashmethodisallowedforthekey.
|| B'xxx0xxxx' SHA-384hashmethodisnotallowedforthekey.
|| B'xxxx1xxx' SHA-512hashmethodisallowedforthekey.
|| B'xxxx0xxx' SHA-512hashmethodisnotallowedforthekey.
| Allunusedbitsarereservedandmustbezero.
| Low-orderbyte:Allbitsarereservedandmustbezero.
||| 049 01 Key-managementfieldscount:kmf(2).
||| 050 02 Key-managementfield1.
| High-orderbyte:
|| Value Description
|| B'1xxxxxxx' Allowexportusingsymmetrictransportkey.
|| B'0xxxxxxx' Prohibitexportusingsymmetrictransportkey.
|| B'x1xxxxxx' Allowexportusingunauthenticatedasymmetrictransportkey.
|| B'x0xxxxxx' Prohibitexportusingunauthenticatedasymmetrictransportkey.
|| B'xx1xxxxx' Allowexportusingauthenticatedasymmetrictransportkey.
|| B'xx0xxxxx' Prohibitexportusingauthenticatedasymmetrictransportkey.
|| B'xxx1xxxx' AllowexporttoTR-31format.
|| B'xxx0xxxx' ProhibitexporttoTR-31format.
|| B'xxxx1xxx' Allowexportinrawformat.
|| B'xxxx0xxx' Prohibitexportinrawformat.
| Allunusedbitsarereservedandmustbezero.
| Low-orderbyte:
|| Value Description
|| B'1xxxxxxx' ProhibitexportusingaDEStransportkey.
|| B'0xxxxxxx' AllowexportusingaDEStransportkey.
|| B'x1xxxxxx' ProhibitexportusinganAEStransportkey.
|| B'x0xxxxxx' AllowexportusinganAEStransportkey.
|| B'xxxx1xxx' ProhibitexportusinganRSAtransportkey.
|| B'xxxx0xxx' AllowexportusinganRSAtransportkey.
|| B'xxxxx1xx' KeycannotbederivedusinganECCkey.
|| B'xxxxx0xx' KeycanbederivedusinganECCkey.
| Allunusedbitsarereservedandmustbezero.
442 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
| Table137.HMACvariable-lengthsymmetrickey-token,versionX'05'(CCA4.1.0orlater) (continued)
| Length
||| Offset(bytes) (bytes) Description
||| 052 02 Key-managementfield2.
| High-orderbyte:
|| Value Description
|| B'11xxxxxx' Key,ifpresent,isincomplete.Keyrequiresatleast2moreparts.
|| B'10xxxxxx' Key,ifpresent,isincomplete.Keyrequiresatleast1moreparts.
|| B'01xxxxxx' Key,ifpresent,isincomplete.Keycanbecompletedorhavemore
| partsadded.
|| B'00xxxxxx' Key,ifpresent,iscomplete.Nomorepartscanbeadded.
| Allunusedbitsarereservedandmustbezero.
| Low-orderbyte:
| Allbitsarereservedandmustbezero.
||| 054 kl Optionalkeylabel.
||| 054+kl iead IBMextendedassociateddata.
||| 054+kl+iead uad User-definableassociateddata.
| Endofassociateddatasection
| OptionalclearkeyorencryptedAESKWpayload
||| 054+kl+iead+ (pl+7)/8 Clearkeyorencryptedwrapped/encodedpayload.
| uad
| EndofoptionalclearkeyorencryptedAESKWpayload
||| 054+kl+iead+ EndofAESKWcomponents
| uad+(pl+7)/8
| UnencryptedAESKWpayload(Thisdatawillneverappearintheclearoutsideofthecryptographiccoprocessor)
||| 000 6 Integritycheckvalue.Sixbyteconstant:X'A6A6A6A6A6A6'.
||| 006 1 Lengthofthepaddinginbits:pb
||| 007 1 Lengthofthehashtheassociateddatainbytes:32
||| 008 4 Hashoptions
||| 012 hoh-4 Hashoftheassociateddata
||| 008+hoh (pl/8)- Keydataandpadding(keydataisleftjustified).
| 8-hoh
||| pl/8 plisthebitlengthofthepayload
| Note: Allnumbersareinbigendianformat.
|
HMAC symmetric null key token
|
| Table138 shows the format of the HMAC symmetric null key token.
|| Table138.HMACsymmetricnullkeytokenformat
| Length
||| Offset(bytes) (bytes) Description
| Header
||| 0 1 X'00'Tokenidentifier,whichindicatesthatthisisanullkeytoken.
||| 1 1 X'00'Version
AppendixB.Keytokenformats 443

Key token formats
| Table138.HMACsymmetricnullkeytokenformat (continued)
| Length
||| Offset(bytes) (bytes) Description
||| 2-3 2 X'0008'Lengthofthekeytokenstructure.
||| 4.-7 4 Ignored(zero).
|
|
Trusted blocks
Akey token is a data structure that contains information about a key and usually contains a key or keys.
| Atrusted block is an extension of CCAkey tokens using new section identifiers.Atrusted block was
| introduced to CCAbeginning with Release 3.25. Trusted blocks are an integral part of a remote
| key-loading process. See “Remote key loading” on page 34.
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 CCAnode'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 CCAnode.
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 CCAmaster key. DES keys and PKAprivate-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).
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 CCAPKAkey tokens, occur in
no prescribed order.
As with other CCAkey-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-PKAtransport key. The MAC key is used to calculate an ISO 16609 CBC
mode TDES 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 PKAmaster key. The MAC key is used to calculate a TDES MAC of the trusted block contents.A
PKAmaster-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 PKAKey Import verb.
Note: Trusted blocks do not contain a private key section.
Trusted block organization
| Atrusted block is a concatenation of a header followed by an unordered set of sections. Some elements
| are required, while others are optional. The data structures of these sections are summarized in Table139.
Table139.Trustedblocksectionsandtheiruse
Section Reference Usage
Header Table140onpage446 Trustedblocktokenheader
X'11' Table141onpage447 Trustedblockpublickey
444 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table139.Trustedblocksectionsandtheiruse (continued)
Section Reference Usage
X'12' Table142onpage448 Trustedblockrule
X'13' Table149onpage455 Trustedblockname(keylabel)
X'14' Table150onpage455 Trustedblockinformation
X'15' Table154onpage457 Trustedblockapplication-defineddata
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 PKAKey
Import verb
Following the token header of a trusted block is an unordered set of sections.Atrusted 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 RSApublic 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')
Atrusted block can have zero or more rule sections.
1. Atrusted block with no rule sections can be used by the PKAKey Token Change and PKAKey
Import verbs.Atrusted block with no rule sections can also be used by the Digital Signature Verify
verb, provided there is an RSApublic 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 CCADES 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 CCAkeys. 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 Arequired 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. CCAdoes 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
AppendixB.Keytokenformats 445

Key token formats
used to calculate an ISO 16609 CBC mode TDES 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-PKAkey-encrypting key.An internal
trusted block has its MAC key enciphered under a variant of the PKAmaster 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
Trusted block sections
|
At the beginning of every trusted block is a trusted block header. The header contains the following
information:
v Atoken identifier, which specifies if the token contains an external or internal key-token
v Atoken version number to allow for future changes
v Alength in bytes of the trusted block, including the length of the header
The trusted block header is defined in Table140.
Table140.Trustedblockheaderformat
Offset(bytes) Length(bytes) Description
000 001 Tokenidentifier(aflagthatindicatestokentype)
Value Description
X'1E' Externaltrustedblocktoken
X'1F' Internaltrustedblocktoken
001 001 Tokenversionnumber(X'00').
002 002 Lengthofthekey-tokenstructureinbytes.
004 004 Reserved,binaryzero.
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.Asubsection 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.Asection 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'). Section X'14' has two subsections, (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 topics.
446 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Trusted block section X'11'
Trusted block section X'11' contains the trusted RSApublic 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 Table141.
Table141.TrustedblocktrustedRSApublickeysection(X'11')
Offset(bytes) Length(bytes) Description
000 001 Sectionidentifier:
X'11' TrustedblocktrustedRSApublickey
001 001 Sectionversionnumber(X'00').
002 002 Sectionlength(16+xxx+yyy).
004 002 Reserved,mustbebinaryzero.
006 002 RSApublickeyexponentfieldlengthinbytes,xxx.
008 002 RSApublickeymoduluslengthinbits.
010 002 RSApublickeymodulusfieldlengthinbytes,yyy.
012 xxx Publickeyexponent,e(thisfieldlengthistypically1,3,or64-512bytes).emust
beoddand1≤e<n.(eisfrequentlyvaluedto3or216+1(=65537),otherwisee
isofthesameorderofmagnitudeasthemodulus).
Note: Althoughthecurrentproductimplementationdoesnotgeneratesucha
publickey,youcanimportanRSApublickeyhavinganexponentvaluedtotwo
(2).Suchapublickey(aRabinkey)cancorrectlyvalidateanISO9796-1digital
signature.
012+xxx yyy RSApublickeymodulus,n.n=pq,wherepandqareprimeand2512≤n<24096.
Thefieldlengthis64-512bytes.
Note: Keyswithamodulusgreaterthan2048bitsarenotsupportedinreleases
beforeRelease3.30.
012+xxx+yyy 004 Flags:
Value
Description
X'00000000'
Trustedblockpublickeycanbeusedindigitalsignatureoperationsonly
X'80000000'
Trustedblockpublickeycanbeusedinbothdigitalsignatureandkey
managementoperations
X'C0000000'
Trustedblockpublickeycanbeusedinkeymanagementoperationsonly
Note: See“Numberrepresentationintrustedblocks”onpage446.
Trusted block section X'12'
Trusted block section X'12' contains information that defines a rule.Atrusted block can have zero or more
rule sections.
1. Atrusted block with no rule sections can be used by the PKAKey Token Change and PKAKey Import
verbs.Atrusted block with no rule sections can be used by the Digital Signature Verify verb, provided
there is an RSApublic 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 CCADES key-token
AppendixB.Keytokenformats 447

Key token formats
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 theATM vendor. It is used to verify the digital signature
on public-key certificates for specific individualATMs.
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 that can have multiple sections. Section X'12' is optional.
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 Table142.
Table142.Trustedblockrulesection(X'12')
Offset(bytes) Length Description
(bytes)
000 001 Sectionidentifier:
X'12' Trustedblockrule
001 001 Sectionversionnumber(X'00').
002 002 Sectionlengthinbytes(20+yyy).
004 008 RuleID(inASCII).
An8-bytecharacterstringthatuniquelyidentifiestherulewithinthetrustedblock.
ValidASCIIcharactersare:A-Z,a-z,0-9,-(hyphen),and_(underscore),left
justifiedandpaddedontherightwithspacecharacters.
012 004 Flags(undefinedflagbitsarereservedandmustbezero).
Value Description
X'00000000' Generatenewkey
X'00000001' Exportexistingkey
016 001 Generatedkeylength.
Lengthinbytesofkeytobegeneratedwhenflagsvalue(offset012)issetto
generateanewkey;otherwiseignorethisvalue.Validvaluesare8,16,or24;
returnanerrorifnotvalid.
017 001 Key-checkalgorithmidentifier(allothersarereservedandmustnotbeused):
Value Description
X'00' Donotcomputekey-checkvalue.Setthekey_check_value_length
variabletozero.
X'01' Encryptan8-byteblockofbinaryzeroswiththekey.See“Encryptzeros
DES-keyverificationalgorithm”onpage493.
X'02' ComputetheMDC-2hashofthekey.See“ModificationDetectionCode
calculation”onpage493.
448 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table142.Trustedblockrulesection(X'12') (continued)
Offset(bytes) Length Description
(bytes)
018 001 Symmetricencryptedoutputkeyformatflag(allothervaluesarereservedand
mustnotbeused).
Returntheindicatedsymmetrickey-tokenusingthesym_encrypted_key_identifier
parameter.
Value Description
X'00' ReturnanRKXkey-tokenencryptedunderavariantoftheMACkey.
Note: Thiskeyformatispermittedwhentheflagsvalue(offset012)is
settoeither:
1. Generateanewkey
2. Exportanexistingkey
X'01' ReturnaCCADESkey-tokenencryptedunderatransportkey.
Note: Thiskeyformatisnotpermittediftheflagsvalue(offset012)is
settogenerateanewkey;itisonlypermittedwhenexportinganexisting
key.
019 001 Asymmetricencryptedoutputkeyformatflag(allothervaluesarereservedand
mustnotbeused).
Returntheindicatedasymmetrickey-tokenintheasym_encrypted_keyvariable.
Value Description
X'00' Donotreturnanasymmetrickey.Settheasym_encrypted_key_length
variabletozero.
X'01' OutputinPKCS-1.2format.
X'02' OutputinRSA-OAEPformat.
020 yyy Rulesectionsubsections(tag-length-valueobjects).Aseriesofzero-fiveobjects
inTLVformat.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'12' subsections: Section X'12' has five rule subsections (tag-length-value
objects) defined. These subsections are summarized in Table143.
Table143.SummaryoftrustedblockX'12'subsections
Rule TLVobject Optionalorrequired Comments
subsection
tag
X'0001' Transport Optional ContainsvarianttobeXORedintothecleartexttransportkey.
keyvariant
X'0002' Transport Optional;requiredto ContainstheruleIDfortherulethatmusthavebeenusedto
keyrule useanRKXkey-token createthetransportkey.
reference asatransportkey
X'0003' Common Optionalforkey Containstheexportkeyandsourcekeyminimumand
exportkey generation;requiredfor maximumlengths,anoutputkeyvariantlengthandvariant,a
parameters keyexportofan CVlength,andaCVtobeXORedwiththecleartexttransport
existingkey keytocontrolusageofthekey.
X'0004' Sourcekey Optional;requiredifthe ContainstheruleIDfortheruleusedtocreatethesource
reference sourcekeyisanRKX key.
key-token Note: Includeallrulesthatwilleverbeneededwhena
trustedblockiscreated.Arulecannotbeaddedtoatrusted
blockafterithasbeencreated.
AppendixB.Keytokenformats 449

Key token formats
Table143.SummaryoftrustedblockX'12'subsections (continued)
Rule TLVobject Optionalorrequired Comments
subsection
tag
X'0005' Exportkey Optional;usedfor Containsmasklength,mask,andCVtemplatetolimitthe
CCAtoken exportofCCADESkey usageoftheexportedkey.Alsocontainsthetemplatelength
parameters tokensonly andtemplatethatdefineswhichsourcekeylabelsare
allowed.
Thekeytypeofasourcekeyinputparametercanbe
"filtered"byusingtheexportkeyCVlimitmask(offset005)
andlimittemplate(offset005+yyy)inthissubsection.
Note: See “Number representation in trusted blocks” on page 446.
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 XORed into the cleartext transport key.
This subsection is defined in Table144.
Table144.Transportkeyvariantsubsection(X'0001')oftrustedblockrulesection(X'12')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0001' TransportkeyvariantTLVobject
002 002 Subsectionlengthinbytes(8+nnn).
004 001 Subsectionversionnumber(X'00').
005 002 Reserved,mustbebinaryzero.
007 001 Lengthofvariantfieldinbytes(nnn).
Thislengthmustbegreaterthanorequaltothelengthofthetransportkeythatis
identifiedbythetransport_key_identifierparameter.Ifthevariantislongerthanthe
key,truncateitontherighttothelengthofthekeypriortouse.
008 nnn Transportkeyvariant.
XORthisvariantintothecleartexttransportkey,provided:(1)thelengthofthe
variantfieldvalue(offset007)isnotzero,and(2)thesymmetricencryptedoutput
keyformatflag(offset018insectionX'12')isX'01'.
Note: Atransportkeyisnotusedwhenthesymmetricencryptedoutputkeyisin
RKXkey-tokenformat.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'12' subsection X'0002'
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.
This subsection is defined in Table145 on page 451.
450 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table145.Transportkeyrulereferencesubsection(X'0002')oftrustedblockrulesection(X'12')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0002' TransportkeyrulereferenceTLVobject
002 002 Subsectionlengthinbytes(14).
004 001 Subsectionversionnumber(X'00').
005 001 Reserved,mustbebinaryzero.
006 008 RuleID.
ContainstheruleidentifierfortherulethatmusthavebeenusedtocreatetheRKX
key-tokenusedasthetransportkey.
TheRuleIDisan8-bytestringofASCIIcharacters,leftjustifiedandpaddedonthe
rightwithspacecharacters.AcceptablecharactersareA-Z,a-z,0-9,-(X'2D'),
and_(X'5F').Allothercharactersarereservedforfutureuse.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'12' subsection X'0003'
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 CCADES 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 XORed with the cleartext
transport key.
This subsection is defined in Table146.
Table146.Commonexportkeyparameterssubsection(X'0003')oftrustedblockrulesection(X'12')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0003' CommonexportkeyparametersTLVobject
002 002 Subsectionlengthinbytes(12+xxx+yyy).
004 001 Subsectionversionnumber(X'00').
005 002 Reserved,mustbebinaryzero.
007 001 Flags(mustbesettobinaryzero).
008 001 Exportkeyminimumlengthinbytes.Lengthmustbe0,8,16,or24.
Alsoappliestothesourcekey.Notapplicableforkeygeneration.
009 001 Exportkeymaximumlengthinbytes(yyy).Lengthmustbe0,8,16,or24.
Alsoappliestothesourcekey.Notapplicableforkeygeneration.
010 001 Outputkeyvariantlengthinbytes(xxx).
Validvaluesare0or8-255.Ifgreaterthan0,thelengthmustbeatleastaslong
asthelongestkeyevertobeexportedusingthisrule.Ifthevariantislongerthan
thekey,truncateitontherighttothelengthofthekeypriortouse.
Note: Theoutputkeyvariant(offset011)isnotusedifthislengthiszero.
AppendixB.Keytokenformats 451

Key token formats
Table146.Commonexportkeyparameterssubsection(X'0003')oftrustedblockrulesection(X'12') (continued)
Offset(bytes) Length(bytes) Description
011 xxx Outputkeyvariant.
Thevariantcanbeanyvalue.XORthisvariantintothecleartextvalueoftheoutput
key.
011+xxx 001 CVlengthinbytes(yyy).
v Ifthelengthisnot0,8,or16,returnanerror.
v Ifthelengthis0,andifthesourcekeyisaCCADESkey-token,preservethe
CVinthesymmetricencryptedoutputiftheoutputistobeintheformofaCCA
DESkey-token.
v Ifanonzerolengthislessthanthelengthofthekeyidentifiedbythe
source_key_identifierparameter,returnanerror.
v Ifthelengthis16,andiftheCV(offset012+xxx)isvaluedto16bytesofX'00'
(ignoringthekey-partbit),then:
1. IgnoreallCVbitdefinitions
2. IfCCADESkey-tokenformat,settheflagbyteofthesymmetricencrypted
outputkeytoindicateaCVvalueispresent.
3. Ifthesourcekeyiseightbytesinlength,donotreplicatethekeyto16bytes
012+xxx yyy CV.(See“Controlvectortable”onpage463.)
PlacethisCVintotheoutputexportedkey-token,providedthatthesymmetric
encryptedoutputkeyformatselected(offset018inrulesection)isCCADES
key-token.
v Ifthesymmetricencryptedoutputkeyformatflag(offset018insectionX'12')
indicatesreturnanRKXkey-token(X'00'),thenignorethisCV.Otherwise,XOR
thisCVintothecleartexttransportkey.
v XORtheCVofthesourcekeyintothecleartexttransportkeyiftheCVlength
(offset011+xxx)issetto0.Ifatransportkeytoencryptasourcekeyhasequal
leftandrightkeyhalves,returnanerror.Replicatethekeyhalvesofthekey
identifiedbythesource_key_identifierparameterwheneveralloftheseconditions
aremet:
| 1. TheKeyGenerate-SINGLE-Rcommand(offsetX'00DB')isenabledinthe
| activerole
2. TheCVlength(offset011+xxx)is16,andbothCVhalvesarenonzero
3. Thesource_key_identifierparameter(containedineitheraCCADES
key-tokenorRKXkey-token)identifiesan8-bytekey
4. Thekey-formbits(40-42)ofthisCVdonotindicateasingle-lengthkey(are
notsettozero)
5. Key-formbit40ofthisCVdoesnotindicatethekeyistohaveguaranteed
uniquehalves(isnotsetto1).See“KeyFormBits,'fff'”onpage468.
Note: Atransportkeyisnotusedwhenthesymmetricencryptedoutputkeyisin
RKXkey-tokenformat.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'12' subsection X'0004'
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.
This subsection is defined in Table147 on page 453.
452 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Table147.Sourcekeyrulereferencesubsection(X'0004')oftrustedblockrulesection(X'12')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0004' SourcekeyrulereferenceTLVobject
002 002 Subsectionlengthinbytes(14).
004 001 Subsectionversionnumber(X'00').
005 001 Reserved,mustbebinaryzero.
006 008 RuleID.
Ruleidentifierfortherulethatmusthavebeenusedtocreatethesourcekey.
TheRuleIDisan8-bytestringofASCIIcharacters,leftjustifiedandpaddedonthe
rightwithspacecharacters.AcceptablecharactersareA-Z,a-z,0-9,-(X'2D'),
and_(X'5F').Allothercharactersarereservedforfutureuse.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'12' subsection X'0005'
Subsection X'0005' of the trusted block rule section (X'12') is the export key CCAtoken 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 CCADES
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.
This subsection is defined in Table148.
Table148.ExportkeyCCAtokenparameterssubsection(X'0005')oftrustedblockrulesection(X'12')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0005' ExportkeyCCAtokenparametersTLVobject
002 002 Subsectionlengthinbytes(8+yyy+yyy+zzz).
004 001 Subsectionversionnumber(X'00').
005 002 Reserved,mustbebinaryzero.
007 001 Flags(mustbesettobinaryzero).
008 001 ExportkeyCVlimitmasklengthinbytes(yyy).
DonotuseCVlimitsifthisCVlimitmasklength(yyy)iszero.UseCVlimitsif
yyyisnonzero,inwhichcaseyyy:
v Mustbe8or16
v Mustnotbelessthantheexportkeyminimumlength(offset008insubsection
X'0003')
v Mustbeequalinlengthtotheactualsourcekeylengthofthekey
Example:Anexportkeyminimumlengthof16andanexportkeyCVlimitmask
lengthof8returnsanerror.
AppendixB.Keytokenformats 453

Key token formats
Table148.ExportkeyCCAtokenparameterssubsection(X'0005')oftrustedblockrulesection(X'12') (continued)
Offset(bytes) Length(bytes) Description
009 yyy ExportkeyCVlimitmask(doesnotexistifyyy=0).
See“Control-vector-basebitmaps”onpage465
IndicateswhichCVbitstocheckagainstthesourcekeyCVlimittemplate(offset
009+yyy).
Examples:AmaskofX'FF'meanscheckallbitsinabyte.AmaskofX'FE'
ignorestheparitybitinabyte.
009+yyy yyy ExportkeyCVlimittemplate(doesnotexistifyyy=0).
SpecifiestherequiredvaluesforthoseCVbitsthatarecheckedbasedonthe
exportkeyCVlimitmask(offset009).(See“Control-vector-basebitmaps”on
page465.)
TheexportkeyCVlimitmaskandtemplatehavethesamelength,yyy.Thisis
becausethesetwovariablesworktogethertorestricttheacceptableCVsfor
CCADESkeytokenstobeexported.Thechecksworkasfollows:
1. Ifthelengthofthekeytobeexportedislessthanyyy,returnanerror
2. LogicalANDtheCVforthekeytobeexportedwiththeexportkeyCVlimit
mask
3. ComparetheresulttotheexportkeyCVlimittemplate
4. Returnanerrorifthecomparisonisnotequal
Examples:AnexportkeyCVlimitmaskofX'FF'forCVbyte1(keytype)along
withanexportkeyCVlimittemplateofX'3F'(keytypeCVARENC)forbyte1
filtersoutallkeytypesexceptCVARENCkeys.
Note: Usingthemaskandtemplatetopermitmultiplekeytypesispossible,but
cannotconsistentlybeachievedwithonerulesection.Forexample,settingbit10
to1inthemaskandthetemplatepermitsPINprocessingkeysandcryptographic
variableencryptingkeys,andonlythosekeys.However,amasktopermit
PIN-processingkeysandkey-encryptingkeys,andonlythosekeys,isnot
possible.Inthiscase,multiplerulesectionsarerequired,onetopermit
PIN-processingkeysandtheothertopermitkey-encryptingkeys.
009+yyy+yyy 001 Sourcekeylabeltemplatelengthinbytes(zzz).
Validvaluesare0and64.Returnanerrorifthelengthis64andasourcekey
labelisnotprovided.
010+yyy+yyy zzz Sourcekeylabeltemplate(doesnotexistifzzz=0).
Ifakeylabelisidentifiedbythesource_key_identifierparameter,verifythatthe
keylabelnamematchesthistemplate.Ifthecomparisonfails,returnanerror.
Thesourcekeylabeltemplatemustconformtothefollowingrules:
v Thekeylabeltemplatemustbe64bytesinlength
v ThefirstcharactercannotbeintherangeX'00'-X'1F',norcanitbeX'FF'
v Thefirstcharactercannotbenumeric(X'30'-X'39')
v Akeylabelnameisterminatedbyaspacecharacter(X'20')ontherightand
mustbepaddedontherightwithspacecharacters
v Theonlyspecialcharacterspermittedare#,$,@,and*(X'23',X'24',X'40',
andX'2A')
v ThewildcardX'2A'(*)ispermittedonlyasthefirstcharacter,thelastcharacter,
ortheonlycharacterinthetemplate
v Onlyalphanumericcharacters(a-z,A-Z,0-9),thefourspecialcharacters
(X'23',X'24',X'40',andX'2A'),andthespacecharacter(X'20')areallowed
Note: See “Number representation in trusted blocks” on page 446.
454 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
Trusted block section X'13'
Trusted block section X'13'
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 CCAkeys. 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 Table149.
Table149.Trustedblockkeylabel(name)section(X'13')
Offset Length(bytes) Description
(bytes)
000 001 Sectionidentifier:
X'13' Trustedblockname(keylabel)
001 001 Sectionversionnumber(X'00').
002 002 Sectionlengthinbytes(68).
004 064 Name(keylabel).
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'14'
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
defined in Table150.
Table150.Trustedblockinformationsection(X'14')
Offset Length(bytes) Description
(bytes)
000 001 Sectionidentifier:
X'14' Trustedblockinformation
001 001 Sectionversionnumber(X'00').
002 002 Sectionlengthinbytes(10+xxx).
004 002 Reserved,binaryzero.
006 004 Flags:
Value Description
X'00000000' Trustedblockisintheinactivestate
X'00000001' Trustedblockisintheactivestate
010 xxx Informationsectionsubsections(tag-length-valueobjects).
OneortwoobjectsinTLVformat.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'14' subsections: Section X'14' has two information subsections
(tag-length-value objects) defined. These subsections are summarized in Table151 on page 456.
AppendixB.Keytokenformats 455

Key token formats
Table151.Summaryoftrustedblockinformationsubsections
Rule TLVobject Optionalor Comments
subsection required
tag
X'0001' Protection Required Containstheencrypted8-byteconfounderandtriple-length
information (24-byte)MACkey,theISO-16609TDESCBCMACvalue,andthe
MKVPofthePKAmasterkey(computedusingMDC4).
X'0002' Activationand Optional Containsflagsindicatingwhetherornotthecoprocessoristo
expiration validatedates,andcontainstheactivationandexpirationdatesthat
dates areconsideredvalidforthetrustedblock.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'14' subsection X'0001'
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 TDES CBC MAC value, and the MKVP of the PKAmaster key (computed using
MDC4).
This subsection is defined in Table152.
Table152.Protectioninformationsubsection(X'0001')oftrustedblockinformationsection(X'14')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0001' TrustedblockinformationTLVobject
002 002 Subsectionlengthinbytes(62).
004 001 Subsectionversionnumber(X'00'.
005 001 Reserved,mustbebinaryzero.
006 032 EncryptedMACkey.
Containstheencrypted8-byteconfounderandtriple-length(24-byte)MACkeyin
thefollowingformat:
Offset Description
00-07 Confounder
08-15 Leftkey
16-23 Middlekey
24-31 Rightkey
038 008 MAC.
ContainstheISO-16609TDESCBCMessageAuthenticationCodevalue.
046 016 MKVP.
ContainsthePKAmaster-keyverificationpattern,computedusingMDC4,whenthe
trustedblockisininternalform,otherwisecontainsbinaryzero.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'14' subsection X'0002'
456 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Key token formats
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.
This subsection is defined in Table153.
Table153.Activationandexpirationdatessubsection(X'0002')oftrustedblockinformationsection(X'14')
Offset(bytes) Length(bytes) Description
000 002 Subsectiontag:
X'0002' ActivationandexpirationdatesTLVobject
002 002 Subsectionlengthinbytes(16).
004 001 Subsectionversionnumber(X'00').
005 001 Reserved,mustbebinaryzero.
006 002 Flags:
Value Description
X'0000' Thecoprocessordoesnotcheckdates.
X'0001' Thecoprocessorchecksdates.
Comparetheactivationdate(offset008)andtheexpirationdate(offset
012)tothecoprocessor'sinternalreal-timeclock.Returnanerrorifthe
coprocessordateisbeforetheactivationdateoraftertheexpirationdate.
008 004 Activationdate.
Containsthefirstdatethatthetrustedblockcanbeusedforgeneratingorexporting
keys.FormatofthedateisYYMDD,where:
YY Big-endianyear(returnanerrorifgreaterthan9999)
MM Month(returnanerrorifanyvalueotherthanX'01'-X'0C')
DD Dayofmonth(returnanerrorifanyvalueotherthanX'01'-X'1F'.Daymust
bevalidforgivenmonthandyear,includingleapyears).
Returnanerroriftheactivationdateisaftertheexpirationdateorisnotvalid.
012 004 Expirationdate.
Containsthelastdatethatthetrustedblockcanbeused.Sameformatas
activationdate(offset008).Returnanerrorifdateisnotvalid.
Note: See “Number representation in trusted blocks” on page 446.
Trusted block section X'15'
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 CCAin any way.
Section X'15' is optional. No multiple sections are allowed. It has no subsections defined. This section is
defined in Table154.
Table154.Trustedblockapplication-defineddatasection(X'15')
Offset Length(bytes) Description
(bytes)
000 001 Sectionidentifier:
X'15' Application-defineddata
001 001 Sectionversionnumber(X'00').
AppendixB.Keytokenformats 457

Key token formats
Table154.Trustedblockapplication-defineddatasection(X'15') (continued)
Offset Length(bytes) Description
(bytes)
002 002 Sectionlength(6+xxx)
004 002 Applicationdatalength
Thevalueofxxxmustbebetween0andN,whereNdoesnotcausetheoverall
lengthofthetrustedblocktoexceeditsmaximumsizeof3500bytes.
006 xxx Application-defineddata
Couldbeusedtoholdapublic-keycertificateforthetrustedpublickey.
Note: See “Number representation in trusted blocks” on page 446.
458 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix C. Key forms and types used in the Key Generate
verb
The Key Generate verb is the most complex of all the CCAverbs. This appendix provides examples of the
key forms and key types used in the Key Generate verb.
Generating an operational key
To generate an operational key, choose one of the following methods:
v For operational keys, call the Key Generate (CSNBKGN) verb. Table26 on page 126 and Table27 on
page 126 show the key type and key form combinations for a single key and for a key pair.
v For data-encrypting keys, call the Random Number Generate (CSNBRNG) verb and specify the form
parameter as ODD. Then pass the generated value to the Clear Key Import (CSNBCKI) verb or the
Multiple Clear Key Import (CSNBCKM) verb. The DATAkey type is now in operational form.
You cannot generate a PIN verification (PINVER) key in operational form because the originator of the PIN
generation (PINGEN) key generates the PINVER key in exportable form, which is sent to you to be
imported.
Generating an importable key
To generate an importable key form, call the Key Generate (CSNBKGN) verb.
If you want a DATA, MAC, PINGEN, DATAM, or DATAC key type in importable form, obtain it directly by
generating a single key. If you want any other key type in importable form, request a key pair where either
the first or second key type is importable (IM). Discard the generated key form that you do not need.
Generating an exportable key
To generate an exportable key form, call the Key Generate (CSNBKGN) verb.
If you want a DATA, MAC, PINGEN, DATAM, or DATAC key type in exportable form, obtain it directly by
generating a single key. If you want any other key type in exportable form, request a key pair where either
the first or second key type is exportable (EX). Discard the generated key form that you do not need.
Examples of single-length keys in one form only
Key Key
Form 1
OP DATA Encipher or Decipher data. Use Data Key Export or Key Export
to send encrypted key to another cryptograpic partner. Then
communicate the ciphertext.
OP MAC MAC Generate. Because no MACVER key exists, there is no
secure communication of the MAC with another cryptographic
partner.
IM DATA Key Import, and then Encipher or Decipher. Then Key Export
to communicate ciphertext and key with another cryptographic
partner.
EX DATA You can send this key to a cryptographic partner, but you
can do nothing with it directly. Use it for the key
distribution service. The partner could then use Key Import
to get it in operational form, and use it as in OP DATA
above.
©CopyrightIBMCorp.2007,2011 459

Examples of OPIM single-length, double-length, and triple-length keys
in two forms
The first two letters of the key form indicate the form that key type 1 parameter is in, and the second two
letters indicate the form that key type 2 parameter is in.
Key Type Type
Form 1 2
OPIM DATA DATA Use the OP form in Encipher. Use Key Export with the
OP form to communicate ciphertext and key with
another cryptographic partner. Use Key Import at a
later time to use Encipher or Decipher with the same
key again.
OPIM MAC MAC Single-length MAC Generate key. Use the OP form in
MAC Generate. You have no corresponding verb MACVER key,
but you can call the MAC Verify verb with
the MAC key directly. Use the Key Import verb
and then compute the MAC again using the MAC Verify
verb, which compares the MAC
it generates with the MAC supplied with the message
and issues a return code indicating whether they
compare.
Examples of OPEX single-length, double-length, and triple-length keys
in two forms
Key Type Type
Form 1 2
OPEX DATA DATA Use the OP form in Encipher. Send the EX form and
the ciphertext to another cryptographic partner.
OPEX MAC MAC Single-length MAC generation key. Use the OP form in
both MAC Generate and MAC Verify. Send the
EX form to a cryptographic partner to be used in the
MAC Generate or MAC Verify verbs.
OPEX MAC MACVER Single-length MAC generation and MAC verification
keys. Use the OP form in MAC Generate. Send the EX
form to a cryptographic partner where it will be put
into Key Import, and then MAC Verify, with the
message and MAC that you have also transmitted.
OPEX PINGEN PINVER Use the OP form in Clear PIN Generate. Send the
EX form to a cryptographic partner where it is put
into Key Import, and then Encrypted PIN Verify,
along with an IPINENC key.
OPEX IMPORTER EXPORTER
Use the OP form in Key Import or Key Generate.
Send the EX form to a cryptographic partner where
it is used in Key Export, Data Key Export, or Key Generate,
or put in the CCA key storage file.
OPEX EXPORTER IMPORTER
Use the OP form in Key Export, Data Key Export,
or Key Generate. Send the EX form to a cryptographic
partner where it is put into the CCA Key storage file
or used in Key Import or Key Generate.
When you and your partner have the OPEX IMPORTER EXPORTER, OPEX EXPORTER IMPORTER
pairs of keys in “Examples of OPEX single-length, double-length, and triple-length keys in two forms”
installed, you can start key and data exchange.
460 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Examples of IMEX single-length and double-length keys in two forms
Key Type Type
Form 1 2
IMEX DATA DATA Use the Key Import verb to import
IM form and use the OP form in Encipher. Send
the EX form to a cryptographic partner.
IMEX MAC MACVER Use the Key Import verb to import
the IM form and use the OP form in MAC Generate.
Send the EX form to a cryptographic
partner who can verify the MAC.
IMEX IMPORTER EXPORTER Use the Key Import verb to import
the IM form and send the EX form to a
cryptographic partner. This establishes a new
IMPORTER/EXPORTER key between you and your
partner.
IMEX PINGEN PINVER Use the Key Import verb to import
the IM form and send the EX form to a
cryptographic partner. This establishes a new
PINGEN/PINVER key between you and your partner.
Examples of EXEX single-length and double-length keys in two forms
For the keys shown in the following list, you are providing key distribution services for other nodes in your
network, or other cryptographic partners. Neither key type can be used in your installation.
Key Type Type
Form 1 2
EXEX DATA DATA Send the first EX form to a cryptographic
EXEX MAC MACVER partner with the corresponding IMPORTER and
EXEX IMPORTER EXPORTER send the second EX form to another
EXEC OPINENC IPINENC cryptographic partner with the corresponding
IMPORTER. This exchange establishes a key
between two partners.
AppendixC.KeyformsandtypesusedintheKeyGenerateverb 461

462 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix D. Control vectors and changing control vectors
with the Control Vector Translate verb
This appendix contains a control vector table, which displays the default value of the control vector
associated with each type of key. This appendix also describes how to change control vectors with the
Control Vector Translate verb.
Control vector table
| Note: The control vectors descriptions here build on the descriptions used for earlier IBM products
| supporting CCA, each in turn: 4765, 4764, 4758, and TSS.
The master key enciphers all keys operational on your system.Atransport key enciphers keys distributed
off your system. Before a master key or transport key enciphers a key, CCAXORs both halves of the
master key or transport key with a control vector. The same control vector is XORed to the left and right
half of a master key or transport key.
Also, if you are entering a key part, CCAXORs each half of the key part with a control vector before
placing the key part into the key storage file.
Each type of CCAkey (except the master key) has either one or two unique control vectors associated
with it. The master key or transport key CCAXORs with the control vector depending on the type of key
the master key or transport key is enciphering. For double-length keys, a unique control vector exists for
each half of a specific key type. For example, there is a control vector for the left half of an input
PIN-encrypting key, and a control vector for the right half of an input PIN-encrypting key.
If you are entering a cleartext key part, CCAXORs the key part with the unique control vector(s)
associated with the key type. CCAalso enciphers the key part with two master key variants for a key part.
One master key variant enciphers the left half of the key part and another master key variant enciphers
the right half of the key part. CCAcreates the master key variants for a key part by XORing the master
key with the control vectors for key parts. These procedures protect key separation.
Table155 displays the default value of the control vector associated with each type of key. Some key
types do not have a default control vector. For keys that are double-length, CCAenciphers using a unique
control vector on each half.
Table155.Defaultcontrolvectorvalues
KeyType ControlVectorValue(Hex)Value ControlVectorValue(Hex)Value
forSingle-lengthKeyorLeftHalf forRightHalfofDouble-lengthKey
ofDouble-lengthKey
AES 0000000000000000 0000000000000000
AESTOKEN 0000000000000000 0000000000000000
CIPHER 0003710003000000
CIPHER(doublelength) 0003710003410000 0003710003210000
CVARDEC 003F420003000000
CVARENC 003F480003000000
CVARPINE 003F410003000000
CVARXCVL 003F440003000000
CVARXCVR 003F470003000000
*DATA 0000000000000000
©CopyrightIBMCorp.2007,2011 463

Table155.Defaultcontrolvectorvalues (continued)
KeyType ControlVectorValue(Hex)Value ControlVectorValue(Hex)Value
forSingle-lengthKeyorLeftHalf forRightHalfofDouble-lengthKey
ofDouble-lengthKey
DATAC 0000710003410000 0000710003210000
*DATAMgenerationkey(external) 00004D0003410000 00004D0003210000
*DATAMkey(internal) 00054D0003000000 00054D0003000000
*DATAMVMACverificationkey 0000440003410000 0000440003210000
(external)
*DATAMVMACverificationkey 0005440003000000 0005440003000000
(internal)
*DATAXLAT 0006710003000000
DECIPHER 0003500003000000
DECIPHER(double-length) 0003500003410000 0003500003210000
DKYGENKY 0071440000034100 0071440003210000
DKYL0 ThiscontrolvectorhastheDKYL0setbydefault.
DKYL1 0072440000034100 0071440003210000
DKYL2 0074440000034100 0071440003210000
DKYL3 0077440000034100 0071440003210000
DKYL4 0078440000034100 0071440003210000
DKYL5 007B440000034100 0071440003210000
DKYL6 007D440000034100 0071440003210000
DKYL7 007E440000034100 0071440003210000
ENCIPHER 0003600003000000
ENCIPHER(double-length) 0003600003410000 0003600003210000
*EXPORTER 00417D0003410000 00417D0003210000
IKEYXLAT 0042420003410000 0042420003210000
*IMP-PKA 0042050003410000 0042050003210000
*IMPORTER 00427D0003410000 00427D0003210000
*IPINENC 00215F0003410000 00215F0003210000
*MAC 00054D0003000000
MAC(double-length) 00054D0003410000 00054D0003210000
*MACVER 0005440003000000
MACVER(double-length) 0005440003410000 0005440003210000
OKEYXLAT 0041420003410000 0041420003210000
*OPINENC 0024770003410000 0024770003210000
*PINGEN 00227E0003410000 00227E0003210000
*PINVER 0022420003410000 0022420003210000
SECMSGwithSMPINset 000A500003410000 000A500003210000
SECMSGwithSMKEYset 000A600003410000 000A600003210000
Note: The external control vectors for DATAC, DATAM MAC generation, and DATAMV MAC verification
keys are also referred to as data compatibility control vectors.
464 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Control-vector-base bit maps
Figure5.Controlvectorbasebitmap(commonbitsandkey-encryptingkeys)
AppendixD.ControlvectorsandchangingcontrolvectorswiththeControlVectorTranslateverb 465

Figure6.Controlvectorbasebitmap(dataoperationkeys)
466 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Figure7.Controlvectorbasebitmap(PINprocessingkeysandcryptographicvariable-encryptingkeys)
AppendixD.ControlvectorsandchangingcontrolvectorswiththeControlVectorTranslateverb 467

Control-Vector Base Bits
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
MostSignificantBit LeastSignificantBit
Key Generating Keys
KEYGENKY
00000000 01010011 0E..000P 00000000 00000011 fff0K00P 00000000 00000000
CLR8-ENC
UKPT
DKYGENKY
00000000 0111vvvP 0E0vvvvP 00000000 00000011 fff0K00P 00000000 00000000
Key-form
000 DKYSubtype0 0001 DDATA
001 DKYSubtype1 0010 DMAC
010 DKYSubtype2 0011 DMV
011 DKYSubtype3 0100 DIMP
100 DKYSubtype4
0101 DEXP
101 DKYSubtype5
0110 DPVR
110 DKYSubtype6
111 DKYSubtype7 1000 DMKEY
1001 DMPIN
1111 DALL
Figure8.Controlvectorbasebitmap(keygeneratingkeys)
Key Form Bits, 'fff'
The key form bits, 40-42, and for a double-length key, bits 104-106, are designated 'fff' in the preceding
illustration. These bits can have the following values:
Value Description
000 Single length key
010 Double length key, left half
001 Double length key, right half
The following values could exist in some CCAimplementations:
Value Description
110 Double-length key, left half, halves guaranteed unique
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 (eight 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:
468 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Bits8-11 MainKeyType
0000 Dataoperationkeys
0010 PINkeys
0011 Cryptographicvariable-encryptingkeys
0100 Key-encryptingkeys
0101 Key-generatingkeys
0111 Diversifiedkey-generatingkeys
v The key subtype bits (bits 12 - 14). Set bits 12 - 14 to one of the following values:
Note: For Diversified Key Generating Keys, the subtype field specifies the hierarchical level of the
DKYGENKY. If the subtype is nonzero, the DKYGENKY can generate only another
DKYGENKY key with the hierarchy level decremented by one. If the subtype is zero, the
DKYGENKY can generate only the final diversified key (a non-DKYGENKY key) with the
key type specified by the usage bits.
Bits12-14 KeySubtype
DataOperationKeys
000 Compatibilitykey(DATA)
001 Confidentialitykey(CIPHER,DECIPHER,orENCIPHER)
010 MACkey(MACorMACVER)
101 Securemessagingkeys
Key-EncryptingKeys
000 Transport-sendingkeys(EXPORTERandOKEYXLAT)
001 Transport-receivingkeys(IMPORTERandIKEYXLAT)
PINKeys
001 PIN-generatingkey(PINGEN,PINVER)
000 InboundPIN-blockdecryptingkey(IPINENC)
010 OutboundPIN-blockencryptingkey(OPINENC)
CryptographicVariable-EncryptingKeys
111 Cryptographicvariable-encryptingkey(CVAR....)
DiversifiedKeyGeneratingKeys
000 DKYSubtype0
001 DKYSubtype1
010 DKYSubtype2
011 DKYSubtype3
100 DKYSubtype4
101 DKYSubtype5
110 DKYSubtype6
111 DKYSubtype7
2. For key-encrypting keys, set the following bits:
v The key-generating usage bits (gks, bits 18 - 20). Set the gks bits to B'111' to indicate 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 Figure5). Without any of the gks bits set to 1, the Key Generate verb cannot use
AppendixD.ControlvectorsandchangingcontrolvectorswiththeControlVectorTranslateverb 469

the associated key-encrypting key. The Key Token Build verb can set the gks bits to 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 the ‘i’bit is set to 1, the
| associated key-encrypting key can be used in the Data Key Import, Key Import, Data Key Export,
| and Key Export verbs. If the ‘x’bit is set to 1, the associated key-encrypting key can be used in the
| Key Translate and Key Translate2 verbs.
v The key-form bits (fff, bits 40 - 42). The key-form bits indicate how the key was generated and how
the control vector participates in multiple-enciphering. To indicate the parts can 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 8 on page 471.
3. For MAC and MACVER keys, set the following bits:
v The MAC control bits (bits 20 and 21). For a MAC-generate key, set bits 20 and 21 to B'11'. For a
MAC-verify key, set bits 20 and 21 to B'01'.
v The key-form bits (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'.
4. 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:
Bits0-3 CalculationMethodKeyword Description
0000 NO-SPEC Akeywiththiscontrolvectorcanbeused
withanyPINcalculationmethod.
0001 IBM-PINorIBM-PINO Akeywiththiscontrolvectorcanbeused
onlywiththeIBMPINorPINOffset
calculationmethod.
0010 VISA-PVV Akeywiththiscontrolvectorcanbeused
onlywiththeVISA-PVVcalculation
method.
0100 GBP-PINorGBP-PINO Akeywiththiscontrolvectorcanbeused
onlywiththeGermanBankingPoolPIN
orPINOffsetcalculationmethod.
0011 INBK-PIN Akeywiththiscontrolvectorcanbeused
onlywiththeInterbankPINcalculation
method.
v The prohibit-offset bit (o, bit 37) to restrict operations to the PIN value. If set to 1, this bit prevents
operation with the IBM 3624 PIN Offset calculation method and the IBM German Bank Pool PIN
Offset calculation method.
5. For PINGEN, IPINENC, and OPINENC keys, set bits 18 - 22 to indicate whether the key can be used
with the following verbs:
ServiceAllowed BitName Bit
ClearPINGenerate CPINGEN 18
EncryptedPINGenerateAlternate EPINGENA** 19
EncryptedPINGenerate EPINGEN 20forPINGEN
19forOPINENC
ClearPINGenerateAlternate CPINGENA 21forPINGEN
20forIPINENC
EncryptedPINVerify EPINVER 19
ClearPINEncrypt CPINENC 18
470 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

ServiceAllowed BitName Bit
**EPINGENAisnolongersupported,althoughthebitretainsthisdefinitionforcompatibilityThereisno
EncryptedPinGenerateAlternateverb.
6. For the IPINENC (inbound) and OPINENC (outbound) PIN-block ciphering keys, do the following:
v Set the TRANSLAT bit (t, bit 21) to 1 to permit the key to be used in the PIN Translate verb. The
Control Vector Generate verb can set the TRANSLAT bit to 1 when you supply the TRANSLAT
keyword.
v Set the REFORMAT bit (r, bit 22) to 1 to permit the key to be used in the PIN Translate verb. The
Control Vector Generate verb can set the REFORMAT bit and the TRANSLAT bit to 1 when you
supply the REFORMAT keyword.
7. For the cryptographic variable-encrypting keys (bits 18 - 22), set the variable-type bits (bits 18 - 22) to
one of the following values:
Bits18-22 GenericKeyType Description
00000 CVARPINE UsedintheEncryptedPINGenerate
AlternateverbtoencryptaclearPIN.
00010 CVARXCVL UsedintheControlVectorTranslateverb
todecrypttheleftmaskarray.
00011 CVARXCVR UsedintheControlVectorTranslateverb
todecrypttherightmaskarray.
8. For key-generating keys, set the following bits:
v For KEYGENKY, set bit 18 for UKPT usage and bit 19 for CLR8-ENC usage.
v For DKYGENKY, bits 12–14 will specify the hierarchical level of the DKYGENKY key. If the subtype
CV bits are nonzero, the DKYGENKY can generate only another DKYGENKY key with the
hierarchical level decremented by one. If the subtype CV bits are zero, the DKYGENKY can
generate only the final diversified key (a non-DKYGENKY key) with the key type specified by
usage bits.
To specify the subtype values of the DKYGENKY, keywords DKYL0, DKYL1, DKYL2, DKYL3,
DKYL4, DKYL5, DKYL6, and DKYL7 will be used.
v For DKYGENKY, bit 18 is reserved and must be zero.
v Usage bits 18-22 for the DKYGENKY key type are defined as follows. They will be encoded as the
final key type that the DKYGENKY key generates.
Bits19-22 Keyword Usage
0001 DDATA DATA,DATAC,singleordoublelength
0010 DMAC MAC,DATAM
0011 DMV MACVER,DATAMV
0100 DIMP IMPORTER,IKEYXLAT
0101 DEXP EXPORTER,OKEYXLAT
0110 DPVR PINVER
1000 DMKEY Securemessagekeyforencryptingkeys
1001 DMPIN SecuremessagekeyforencryptingPINs
1111 DALL Allkeytypescanbegeneratedexcept
DKYGENKYandKEYGENKYkeys.
UsageoftheDALLkeywordiscontrolled
byaseparateaccesscontrolpoint.
9. For secure messaging keys, set the following bits:
AppendixD.ControlvectorsandchangingcontrolvectorswiththeControlVectorTranslateverb 471

v Set bit 18 to 1 if the key will be used in the secure messaging for PINs service. Set bit 19 to 1 if
the key will be used in the secure messaging for keys service.
10. For all keys, set the following bits:
v The export bit (E, bit 17). If set to 0, the export bit prevents a key from being exported. By setting
this bit to 0, you can prevent the receiver of a key from exporting or translating the key for use in
another cryptographic subsystem.After this bit is set to 0, it cannot be set to 1 by any service other
than Control Vector Translate. The Prohibit Export verb can reset the export bit.
v The key-part bit (K, bit 44). Set the key-part bit to 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 0. The Control Vector Generate verb can set the
key-part bit to 1 when you supply the KEY-PART keyword.
v The anti-variant bits (bit 30 and bit 38). Set bit 30 to 0 and bit 38 to 1. Many cryptographic systems
have implemented a system of variants where a 7-bit value is XORed 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 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.
v For secure messaging keys, usage bit 18 on will enable the encryption of keys in a secure
message and usage bit 19 on will enable the encryption of PINs in a secure message.
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 control information (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 cryptographic engine.
The tests consist of evaluating four logic expressions, the results of which must be a string of binary zeros.
The expressions operate bitwise 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 and reason
code (8/39). See Figure9. 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
Amask array consists of seven 8-byte elements:A , B ,A , B ,A , B , and B . You choose the values of
1 1 2 2 3 3 4
the array elements such that each of the following four expressions evaluates to a string of binary zeros.
(See Figure9 on page 474.) Set the A bits to the value 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:
C is the control vector associated with the left half of the KEK.
1
472 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

C is the control vector associated with the source key or selected source-key half/halves.
2
C is the control vector associated with the target key or selected target-key half/halves.
3
1. (C XORA ) logical-AND B
1 1 1
This expression tests whether the KEK used to encipher the key meets your criteria for the desired
translation.
2. (C XORA ) logical-AND B
2 2 2
This expression tests whether the control vector associated with the source key meets your criteria for
the desired translation.
3. (C XORA ) logical-AND B
3 3 3
This expression tests whether the control vector associated with the target key meets your criteria for
the desired translation.
4. (C XOR C ) logical-AND B
2 3 4
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 (key type
CVARENC). Use two different keys so 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 parameter and the array_key_right parameter identify the
internal keys for deciphering the mask arrays. The array_key_left parameter must have a key type of
CVARXCVLand the array_key_right parameter must have a key type of CVARXCVR. The cryptographic
process deciphers the arrays and compares the results; for the service to continue, the deciphered arrays
must be equal. If the results are not equal, the service returns the return and reason code for data that is
not valid (8/385).
Use the Key Generate verb to create the key pairs CVARENC-CVARXCVLand CVARENC-CVARXCVR.
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 will be enciphered.After enciphering the mask array, you
should destroy the enciphering key. The CVARXCVLand CVARXCVR keys are generated for, or imported
into, the node where the Control Vector Translate verb will be performed.
If using the BOTH keyword to process both halves of a double-length key, remember that bits 41, 42, 104,
and 105 are different in the left and right halves of the CCAcontrol vector and must be ignored in your
mask-array tests (that is, make the corresponding B and/or B bits equal to zero).
2 3
When the control vectors pass the masking tests, the verb does the following:
v Deciphers the source key. In the decipher process, the service uses a key that is formed by the XOR 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 XOR 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.
AppendixD.ControlvectorsandchangingcontrolvectorswiththeControlVectorTranslateverb 473

Forexpression
1:KEKCV 0 1 0 1 … 0 1 0 1 … ControlVector
2:SourceCV UnderTest
3:TargetCV
Exclusive-OR
SetTestedPositions
A_Values 0 0 1 1 … 0 0 1 1 … totheValuethat
theControlVector
MustMatch
Intermediate 0 1 1 0 … 0 1 1 0 …
Result
Logical-AND
Setto1
0 0 0 0 … 1 1 1 1 …
B_Values ThosePositions
tobeTested
ReportaControlVector
FinalResult 0 0 0 0 … 0 1 1 0 … Violationifany
BitPositionis1
ForExpression 0 1 0 1 … 0 1 0 1 …
SourceControlVector
4:SourceCV
Exclusive-OR
TargetCV 0 0 1 1 … 0 0 1 1 … TargetControlVector
Intermediate 0 1 1 0 … 0 1 1 0 …
Result
Logical-AND
Setto1
B_Values 0 0 0 0 … 1 1 1 1 … ThosePositions
tobeTested
ReportaControlVector
FinalResult 0 0 0 0 .... 0 1 1 0 …
Violationifany
bitPositionis1
Figure9.ControlVectorTranslateverbmask_arrayprocessing
Selecting the key-half processing mode
Use the Control Vector Translate verb to change a control vector associated with a key. rule_array
keywords determine which key halves are processed in the call, as shown in Figure10 on page 475.
474 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

KeywordSINGLE KeywordRIGHT KeywordBOTH
SourceKey LEFT RIGHT LEFT RIGHT LEFT RIGHT
Process CHANGE-CV Copy CHANGE-CV CHANGE-CV CHANGE-CV
(Unchanged)
TargetKey LEFT RIGHT LEFT RIGHT LEFT RIGHT
Figure10.ControlVectorTranslateverb
Keyword Description
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.
Asingle 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 B , B , and B .
1 2 3
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. Ensure bits 40-42 of mask
array B are set to B'111'.
4
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 Acontrol 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 CCAkey from a
system that supports only a single-length key, for example when processing PIN keys or
key-encrypting keys received from non-CCAsystems.
AppendixD.ControlvectorsandchangingcontrolvectorswiththeControlVectorTranslateverb 475

To prevent the verb from ensuring 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
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'), bit 3 in byte 59 will be set to B'1' to indicate this is a double-length DATAkey.
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 will be encrypted by an unmodified transport key (no control vector or variant is
used). In a CCAsystem, an inbound PIN encrypting key 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 will be the source key key-token.
Second, 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.
Then call the Control Vector Translate verb and specify a rule_array keyword of LEFT. The mask arrays
can be constructed as follows:
v A is set to the value of the KEK's control vector, most likely the value of an IMPORTER key, perhaps
1
with the NO-EXPORT bit set. B is set to eight bytes of X'FF' so all bits of the KEK's control vector will
1
be tested.
v A is set to eight bytes of X'00', the (null) value of the source key control vector. B is set to eight bytes
2 2
of X'FF' so all bits of the source-key “control vector” will be tested.
v A is set to the value of the target key's left-half control vector. B is set to X'FFFF FFFF FF9F FFFF'.
3 3
This will cause 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 B is set to eight bytes of X'00' so no comparison is made between the source and target control
4
vectors.
476 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix E. PIN formats and algorithms
| This appendix describes the personal identification number (PIN) notation, PIN block formats, PIN
| extraction rules, and PIN algorithms.
For PIN calculation procedures, see IBM Common CryptographicArchitecture: CryptographicApplication
Programming Interface Reference.
PIN notation
This section describes various PIN block formats. The following notations describe the contents of PIN
blocks:
P = A4-bit decimal digit that is one digit of the PIN value.
C = A4-bit hexadecimal control value. The valid values are X'0', X'1', and X'2'.
L = A4-bit hexadecimal value that specifies the number of PIN digits. This value ranges from 4 - 12,
inclusive.
F = A4-bit field delimiter of value X'F'.
f = A4-bit delimiter filler that is either P or F, depending on the length of the PIN.
D = A4-bit decimal padding value.All pad digits in the PIN block have the same value.
X = A4-bit hexadecimal padding value.All pad digits in the PIN block have the same value.
x = A4-bit hexadecimal filler that is either P or X, depending on the length of the PIN.
R = A4-bit hexadecimal random digit. The sequence of R digits can each take a different value.
r = A4-bit random filler that is either P or R, depending on the length of the PIN.
Z = A4-bit hexadecimal zero (X'0').
z = A4-bit zero filler that is either P or Z, depending on the length of the PIN.
S = A4-bit hexadecimal digit that constitutes one digit of a sequence number.
A= A4-bit decimal digit that constitutes one digit of a user-specified constant.
PIN block formats
This section describes the PIN block formats and assigns a code to each format.
ANSI X9.8
This format is also named ISO format 0, VISAformat 1, VISAformat 4, and ECI format 1.
P1 = CLPPPPffffffffFF
P2 = ZZZZAAAAAAAAAAAA
PIN Block = P1 XOR P2
where C = X’0’
L = X’4’ to X’C’
Programming Note: The rightmost 12 digits (excluding the check digit) in P2 are the rightmost 12 digits
of the account number for all formats except VISAformat 4. For VISAformat 4, the
rightmost 12 digits (excluding the check digit) in P2 are the leftmost 12 digits of the
account number.
©CopyrightIBMCorp.2007,2011 477

ISO Format 1
This format is also named ECI format 4.
PIN Block = CLPPPPrrrrrrrrRR
where C = X’1’
L = X’4’ to X’C’
ISO Format 2
PIN Block = CLPPPPffffffffFF
where C = X’2’
L = X’4’ to X’C’
ISO Format 3
An ISO-3 PIN-block format is equivalent to theANSI X9.8, VISA-1, and ECI-1 PIN-block formats in length.
APIN 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/R│P/R│P/R│P/R│P/R│P/R│P/R│P/R│ R │ R │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
Intermediate PIN-Block = IPB
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ 0 │ 0 │ 0 │ 0 │PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
PAN Block
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ │ │ │ │ P │ P │P/R│P/R│P/R│P/R│P/R│P/R│P/R│P/R│ R │ R │
│ 3 │ L │ P │ P │XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│XOR│
│ │ │ │ │PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│PAN│
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
PIN Block = IPB XOR PAN Block
Figure11.ISO-3PIN-blockformat
where:
3 Is the value X'3' for ISO-3.
L Is the length of the PIN, which is a 4-bit value from X'4' - X'C'.
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/R Is a PIN digit or pad value.APIN digit has a 4-bit value from X'0' - X'9'.Apad 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 the random value X'A' - X'F' for the pad value.
PAN Is twelve 4-bit digits that represent one of the following:
v The rightmost 12 digits of the primary account-number (excluding the check digit) if the format
of the PIN block is ISO-3,ANSI X9.8, VISA-1, or ECI-1.
v The leftmost 12 digits of the primary account-number (excluding the check digit) if the format of
the PIN block is VISA-4.
478 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Each PAN digit has a value from X'0' - X'9'.
The PIN block is the result of XORing the 64-bit IPB with the 64-bit PAN block.
Example:
L = 6, PIN = 123456, Personal Account Number = 111222333444555
36123456AFBECDDC : IPB
0000222333444555 : PAN block for ISO-3 (ANSI X9.8, VISA-1, ECI-1) format
361216759CFA8889 : PIN block for ISO-3 (ANSI X9.8, VISA-1, ECI-1) format
VISA Format 2
PIN Block = LPPPPzzDDDDDDDDD
where L = X’4’ to X’6’
VISA Format 3
This format specifies that the PIN length can be 4-12 digits, inclusive. The PIN starts from the leftmost
digit and ends by the delimiter (‘F’), and the remaining digits are padding digits.
An example of a 6-digit PIN:
PIN Block = PPPPPPFXXXXXXXXX
IBM 3624 Format
This format requires the program to specify the delimiter, X, for determining the PIN length.
PIN Block = PPPPxxxxxxxxXXXX
IBM 3621 Format
This format requires the program to specify the delimiter, X, for determining the PIN length.
PIN Block = SSSSPPPPxxxxxxxx
ECI Format 2
This format defines the PIN to be 4 digits.
PIN Block = PPPPRRRRRRRRRRRR
ECI Format 3
PIN Block = LPPPPzzRRRRRRRRR
where L = X’4’ to X’6’
PIN extraction rules
This section describes the PIN extraction rules for the Encrypted PIN Verify and Encrypted PIN Translate
verbs.
Encrypted PIN Verify verb
This verb extracts the customer-entered PIN from the input PIN block according to the following rules:
v If the input PIN block format isANSI X9.8, ISO format 0, VISAformat 1, VISAformat 4, ECI format 1,
ISO format 1, ISO format 2, ISO format 3, VISAformat 2, IBM Encrypting PINPAD format, or ECI format
3, the verb extracts the PIN according to the length specified in the PIN block.
v If the input PIN block format is VISAformat 3, the specified delimiter (padding) determines the PIN
length. The search starts at the leftmost digit in the PIN block. If the input PIN block format is 3624, the
AppendixE.PINformatsandalgorithms 479

specification of a PIN extraction method for the 3624 is supported through rule_array keywords. If no
PIN extraction method is specified in the rule_array, the specified delimiter (padding) determines the
PIN length.
v If the input PIN block format is 3621, the specification of a PIN extraction method for the 3621 is
supported through rule_array keywords. If no PIN extraction method is specified in the rule_array, the
specified delimiter (padding) determines the PIN length.
v If the input PIN block format is ECI format 2, the PIN is the leftmost 4 digits.
For the VISAalgorithm, if the extracted PIN length is less than 4, the verb sets a reason code that
indicates verification failed. If the length is greater than or equal to 4, the verb uses the leftmost 4 digits as
the referenced PIN.
For the IBM German Banking Pool algorithm, if the extracted PIN length is not 4, the verb sets a reason
code that indicates verification failed.
For the IBM 3624 algorithm, if the extracted PIN length is less than the PIN check length, the verb sets a
reason code that indicates verification failed.
Clear PIN Generate Alternate verb
This verb extracts the customer-entered PIN from the input PIN block according to the following rules:
v This verb supports the specification of a PIN extraction method for the 3624 and 3621 PIN block
formats through the use of the rule_array keyword. The rule_array points to an array of one or two
8-byte elements. The first element in the rule_array specifies the PIN calculation method. The second
element in the rule_array (if specified) indicates the PIN extraction method. Refer to the “Clear PIN
GenerateAlternate (CSNBCPA)” on page 318 for an explanation of PIN extraction method keywords.
Encrypted PIN Translate verb
This verb extracts the customer-entered PIN from the input PIN block according to the following rules:
v If the input PIN block format isANSI X9.8, ISO format 0, VISAformat 1, VISAformat 4, ECI format 1,
ISO format 1, ISO format 2, ISO format 3, VISAformat 2, IBM Encrypting PINPAD format, or ECI format
3 and, if the specified PIN length is less than 4, the verb sets a reason code to reject the operation. If
the specified PIN length is greater than 12, the operation proceeds to normal completion with
unpredictable contents in the output PIN block. Otherwise, the verb extracts the PIN according to the
specified length.
v If the input PIN block format is VISAformat 3, the specified delimiter (padding) determines the PIN
length. The search starts at the leftmost digit in the PIN block. If the input PIN block format is 3624, the
specification of a PIN extraction method for the 3624 is supported through rule_array keywords. If no
PIN extraction method is specified in the rule_array, the specified delimiter (padding) determines the
PIN length.
v If the input PIN block format is 3621, the specification of a PIN extraction method for the 3621 is
supported through rule_array keywords. If no PIN extraction method is specified in the rule_array, the
specified delimiter (padding) determines the PIN length.
v If the input block format is ECI format 2, the PIN is always the leftmost 4 digits.
If the maximum PIN length allowed by the output PIN block is shorter than the extracted PIN, only the
leftmost digits of the extracted PIN that form the allowable maximum length are placed in the output PIN
block. The PIN length field in the output PIN block, it if exists, specifies the allowable maximum length.
IBM PIN algorithms
This section describes the IBM PIN generation algorithms, IBM PIN offset generation algorithm, and IBM
PIN verification algorithms.
480 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

3624 PIN Generation algorithm
This algorithm generates an n-digit PIN based on account-related data or person-related data, namely the
validation data. The assigned PIN length parameter specifies the length of the generated PIN.
The algorithm requires the following input parameters:
v A64-bit validation data
v A64-bit decimalization table
v A4-bit assigned PIN length
v A128-bit PIN-generation key
The service uses the PIN generation key to encipher the validation data. Each digit of the enciphered
validation data is replaced by the digit in the decimalization table whose displacement from the leftmost
digit of the table is the same as the value of the digit of the enciphered validation data. The result is an
intermediate PIN. The leftmost n digits of the intermediate PIN are the generated PIN, where n is specified
by the assigned PIN length.
Figure12 illustrates the 3624 PIN generation algorithm.
Validation Data
PIN E
Multiple
Generation D
Encryption
Key E
Decimalization Digit
Table Replacement
Assigned PIN Length
Intermediate PIN
Generated PIN
Figure12.3624PINgenerationalgorithm
German Banking Pool PIN Generation algorithm
This algorithm generates a 4-digit PIN based on account-related data or person-related data, namely the
validation data.
The algorithm requires the following input parameters:
v A64-bit validation data
v A64-bit decimalization table
v A128-bit PIN-generation key
AppendixE.PINformatsandalgorithms 481

The validation data is enciphered using the PIN generation key. Each digit of the enciphered validation
data is replaced by the digit in the decimalization table whose displacement from the leftmost digit of the
table is the same as the value of the digit of enciphered validation data. The result is an intermediate PIN.
The rightmost 4 digits of the leftmost 6 digits of the intermediate PIN are extracted. The leftmost digit of
the extracted 4 digits is checked for zero. If the digit is zero, the digit is changed to one; otherwise, the
digit remains unchanged. The resulting four digits is the generated PIN.
Figure13 illustrates the German Banking Pool (GBP) PIN generation algorithm.
Validation Data
PIN E
Multiple
Generation D
Encryption
Key E
Decimalization Digit
Table Replacement
6 Digits
Intermediate PIN
4 Digits
A P P P
Z P P P
(Generated PIN)
If A = 0, then Z = 1;otherwise, Z = A.
Figure13.GBPPINgenerationalgorithm
PIN Offset Generation algorithm
To allow the customer to select his own PIN, a PIN offset is used by the IBM 3624 and GBP PIN
generation algorithms to relate the customer-selected PIN to the generated PIN.
The PIN offset generation algorithm requires two parameters in addition to those used in the 3624 PIN
generation algorithm. They are a customer-selected PIN and a 4-bit PIN check length. The length of the
customer-selected PIN is equal to the assigned-PIN length, n.
The 3624 PIN generation algorithm described in the previous section is performed. The offset data value is
the result of subtracting (modulo 10) the leftmost n digits of the intermediate PIN from the
customer-selected PIN. The modulo 10 subtraction ignores borrows. The rightmost m digits of the offset
data form the PIN offset, where m is specified by the PIN check length. Note that n cannot be less than m.
To generate a PIN offset for a GBP PIN, m is set to 4 and n is set to 6.
482 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Figure14 illustrates the PIN offset generation algorithm.
Validation Data
PIN E
Multiple
Generation D
Encryption
Key E
Decimalization Digit
Table Replacement
Assigned PIN Length
Intermediate PIN
Customer
Selected PIN
A
B
Subtraction
modulo 10
A - B,
where B is leftmost
n digits of the
intermediate PIN
Assigned PIN Length
Offset Data
PIN Offset
PIN Check Length
Figure14.PIN-Offsetgenerationalgorithm
3624 PIN Verification algorithm
This algorithm generates an intermediate PIN based on the specified validation data.Apart of the
intermediate PIN is adjusted by adding an offset data.Apart of the result is compared with the
corresponding part of the customer-entered PIN.
The algorithm requires the following input parameters:
v A64-bit validation data
v A64-bit decimalization table
AppendixE.PINformatsandalgorithms 483

v A128-bit PIN-verification key
v A4-bit PIN check length
v An offset data
v Acustomer-entered PIN
The rightmost m digits of the offset data form the PIN offset, where m is the PIN check length.
1. The validation data is enciphered using the PIN verification key. Each digit of the enciphered validation
data is replaced by the digit in the decimalization table whose displacement from the leftmost digit of
the table is the same as the value of the digit of enciphered validation data.
2. The leftmost n digits of the result is added (modulo 10) to the offset data value, where n is the length
of the customer-entered PIN. The modulo 10 addition ignores carries.
3. The rightmost m digits of the result of the addition operation form the PIN check number. The PIN
check number is compared with the rightmost m digits of the customer-entered PIN. If they match, PIN
verification is successful; otherwise, verification is unsuccessful.
When a nonzero PIN offset is used, the length of the customer-entered PIN is equal to the assigned PIN
length.
Figure15 illustrates the PIN verification algorithm.
484 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Validation Data
PIN E
Multiple
Verification D
Encryption
Key E
Decimalization Digit
Table Replacement
Intermediate PIN
Offset Data
Length of CE PIN
B, the leftmost
A
n digits of the
intermediate
PIN
Addition
modulo 10
CE PIN
PIN Check
Length
Length of CE PIN
A + B
=? PIN CN
PIN Check Length
PIN CN:PIN Check Number
CE PIN:Customer-entered PIN
Figure15.PINverificationalgorithm
German Banking Pool PIN Verification algorithm
This algorithm generates an intermediate PIN based on the specified validation data.Apart of the
intermediate PIN is adjusted by adding an offset data.Apart of the result is extracted. The extracted value
might or might not be modified before it compares with the customer-entered PIN.
The algorithm requires the following input parameters:
AppendixE.PINformatsandalgorithms 485

v A64-bit validation data
v A64-bit decimalization table
v A128-bit PIN verification key
v An offset data
v Acustomer-entered PIN
The rightmost 4 digits of the offset data form the PIN offset.
1. The validation data is enciphered using the PIN verification key. Each digit of the enciphered validation
data is replaced by the digit in the decimalization table whose displacement from the leftmost digit of
the table is the same as the value of the digit of enciphered validation data.
2. The leftmost 6 digits of the result is added (modulo 10) to the offset data. The modulo 10 addition
ignores carries.
3. The rightmost 4 digits of the result of the addition (modulo 10) are extracted.
4. The leftmost digit of the extracted value is checked for zero. If the digit is zero, the digit is set to one;
otherwise, the digit remains unchanged. The resulting four digits are compared with the
customer-entered PIN. If they match, PIN verification is successful; otherwise, verification is
unsuccessful.
Figure16 illustrates the GBP PIN verification algorithm.
486 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Validation Data
PIN E
Multiple
Verification D
Encryption
Key E
Decimalization Digit
Table Replacement
Intermediate PIN
Offset Data
6 Digits
B, the leftmost
6 digits of the A
intermediate PIN
Addition
modulo 10
CE PIN
4 Digits 6 Digits
A + B
=? A P P P
4 Digits
If A = 0, then Z = 1;
otherwise, Z = A
Z P P P
CE PIN:Customer-entered PIN
Figure16.GBPPINverificationalgorithm
VISA PIN algorithms
The VISAPIN verification algorithm performs a multiple encipherment of a value, called the transformed
security parameter (TSP), and a extraction of a 4-digit PIN verification value (PVV) from the ciphertext.
The calculated PVV is compared with the referenced PVV and stored on the plastic card or data base. If
they match, verification is successful.
AppendixE.PINformatsandalgorithms 487

PVV Generation algorithm
The algorithm generates a 4-digit PIN verification value (PVV) based on the transformed security
parameter (TSP).
The algorithm requires the following input parameters:
v A64-bit TSP
v A128-bit PVV generation key
1. Amultiple encipherment of the TSP using the double-length PVV generation key is performed.
2. The ciphertext is scanned from left to right. Decimal digits are selected during the scan until four
decimal digits are found. Each selected digit is placed from left to right according to the order of
selection. If four decimal digits are found, those digits are the PVV.
3. If, at the end of the first scan, less than four decimal digits have been selected, a second scan is
performed from left to right. During the second scan, all decimal digits are skipped and only
non-decimal digits can be processed. Non-decimal digits are converted to decimal digits by subtracting
10. The process proceeds until four digits of PVV are found.
Figure17 illustrates the PVV generation algorithm.
TSP
PGKL E
PGKR D
PGKL E
Encipherment Result
Scan the result from left to
right to select 4 digits
4-digit PVV
PGK = PVV Generation Key
= PGKL PGKR
Figure17.PVVgenerationalgorithm
Programming Note: For VISAPVV algorithms, the leftmost 11 digits of the TSP are the personal account
number (PAN), the leftmost 12th digit is a key table index to select the PVV
generation key, and the rightmost 4 digits are the PIN. The key table index should
have a value between 1 and 6, inclusive.
488 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PVV Verification algorithm
The algorithm requires the following input parameters:
v A64-bit TSP
v A16-bit referenced PVV
v A128-bit PVV verification key
APVV is generated using the PVV generation algorithm, except a PVV verification key rather than a PVV
generation key is used. The generated PVV is compared with the referenced PVV. If they match,
verification is successful.
Interbank PIN Generation algorithm
The Interbank PIN calculation method consists of the following steps:
1. Let X denote the transaction_security parameter element converted to an array of 16 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' - 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.
AppendixE.PINformatsandalgorithms 489

490 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix F. Cryptographic algorithms and processes
This appendix provides processing details for the following aspects of the CCAdesign:
v “Cryptographic key-verification techniques”
v “Modification Detection Code calculation” on page 493
v “Ciphering methods” on page 494
v “MAC calculation methods” on page 502
v “RSAkey-pair generation” on page 504
v “Multiple decipherment and encipherment” on page 504
v “PKA92 key format and encryption process” on page 511
v “Formatting hashes and keys in public-key cryptography” on page 513
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 “CCADES-key verification algorithm” on page 492
v “Encrypt zeros DES-key verification algorithm” on page 493
Master-key verification algorithms
| The CEX3C and CEX2C implementations employ triple-length DES and PKAmaster keys (three DES
| keys) that are internally represented in 24 bytes (168 bits). Beginning with Release 3.30, the CEX2C
| implementation employs anAES master key represented in 32 bytes (256 bits). Beginning with Release
| 4.1.0, the CAAemploys anAPKAmaster key represented in 32 bytes (256 bits). 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. For theAES master key, the SHA-256 verification method is
| used.
The CEX3C and CEX2C employ several verification pattern generation methods.
SHA-1 based master-key verification method
ASHA-1 hash algorithm is calculated on the quantity X'01' prepended to the 24-byte register contents. The
resulting 20-byte hash value is used in the following ways:
| v The Key Test and Key Test2 verb2 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 ASHA-1 based master-key verification pattern stored in a two-byte or an eight-byte master-key
verification pattern field in a key token 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 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 = MK ⊕ e (MK )
first-part C first-part
v MKVP = MK ⊕ e (MK )
second-part IR second-part
where:
v e (Y) is the DES encoding of Y using x as a key
x
©CopyrightIBMCorp.2007,2011 491

v ⊕ represents the bitwise XOR function
Version X'00' internal CCADES key tokens use this eight-byte master-key verification pattern.
SHA-256 based master-key verification method
ASHA-256 hash algorithm is calculated on the quantity X'01' prepended to the 24-byte register contents
ForAES, there will be verification patterns for both theAES master key and forAES 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 forAES 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.
| This value is truncated to eight bytes because this is the length allocated for the verification in several
| CCAstructures andAPIs. For example, theAES key token has eight bytes for the MKVP, and the Key Test
| and Key Test2 verbs have an eight-byte parameter for the verification pattern.
Asymmetric master key MDC-based verification method
The verification pattern for the asymmetric 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 RSAprivate key sections X'06' and X'08' use this 16-byte master-key version number.
Key-token verification patterns
The verification pattern techniques used in the several types of CCAkey 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 RSAkey 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 CCAverification method first creates a random number.Aone-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: Aone-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 “Key
Test (CSNBKYT)” on page 143.
492 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

The CCADES key verification algorithm does the following:
1. Sets KKR′ = KKR XOR RN
2. Sets K1 = X'4545454545454545'
3. Sets X1 = DES encoding of KKL using key K1
4. Sets K2 = X1 XOR KKL
5. Sets X2 = DES encoding of KKR′ using key K2
6. Sets VP = X2 XOR 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 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 DEAencodes 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 and Key
| Test2 verbs.
For a single-length key, the key DEAencodes an 8-byte, all-zero-bits value.
For a double-length key, the key DEAtriple-encodes an 8-byte, all-zero-bits value. The left half (high-order
half) key encodes the zero-bit value, this result is DEAdecoded by the right key half, and that result is
DEAencoded 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 Table156.All versions use the MDC-1 calculation.
Table156.VersionsoftheMDCcalculationmethod
Keyword VersionoftheMDCcalculation
MDC-2,PADMDC-2 Specifiestwoenciphermentsforeach8-byteinputdatablock.Theseversions
usetheMDC-2calculationproceduredescribedinTable157onpage494.
MDC-4,PADMDC-4 Specifiesfourenciphermentsforeach8-byteinputdatablock.Theseversions
usetheMDC-4calculationproceduredescribedinTable157onpage494.
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.Alength of zero is allowed.
v If the total supplied text is a minimum of 16 bytes in length, pad bytes are appended to make the text
length equal to the next-higher multiple of eight 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'.
AppendixF.Cryptographicalgorithmsandprocesses 493

v The last pad byte is set to a binary value equal to the count of all appended pad bytes (X'01' - X'10').
Use the resulting pad text in the Table157. The MDC Generate verb uses these MDC calculation
methods. See “MDC Generate (CSNBMDG)” on page 249 for more information.
Table157.MDCcalculationprocedures
Calculation Procedure
MDC-1 MDC-1(KD1, KD2, IN1, IN2, OUT1, OUT2);
Set KD1mod := set KD1 bit 1 to B’1’ and bit 2 to B’0’ (bits 0-7)
Set KD2mod := set KD2 bit 1 to B’0’ and bit 2 to B’1’ (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) DESencryptionofplaintextXusingkeyK
|| Concatenationoperation
XOR Exclusive-ORoperation
:= Assignmentoperation
T8<1> First8-byteblockoftext
T8<2> Second8-byteblockoftext
KD1,KD2 64-bitquantities
IN1,IN2 64-bitquantities
OUT1,OUT2 64-bitquantities
n Numberof8-byteblocks
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 CCADES keys
v Triple-encrypting and triple-decrypting RSAprivate keys with several processes
v Deriving keys, hashing data, generating CVV values, and so forth
494 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

The Encipher and Decipher verbs describe how you can request encryption or decryption of application
data. See the following topic: “General data-encryption processes” 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 “Triple-DES ciphering algorithms” on page 498 and “Ciphering methods” on page 494, which describe
how CCADES 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 eight bytes in length. Two widely used methods for
enciphering general data are defined in theseANSI standards:
v ANSI X3.106 cipher block chaining (CBC)
v ANSI X9.23
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 CEX3C and CEX2C, you can use the triple-DES algorithm in addition to the classical
single-DES algorithm. In the subsequent descriptions of the CBC method andANSI 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 Figure18 where “left key” and “right key” refer to the two halves of a
double-length DES key.
Cleartext, 8 bytes Ciphertext, 8 bytes
────────┬───────── ─────────┬─────────
│ │
(cid:14) (cid:14)
┌───────────────────┐ ┌───────────────────┐
│ │ │ │
Left key──────(cid:6)│ Encipher │ Left key──────(cid:6)│ Decipher │
│ │ │ │
└─────────┬─────────┘ └─────────┬─────────┘
│ │
(cid:14) (cid:14)
┌───────────────────┐ ┌───────────────────┐
│ │ │ │
Right key─────(cid:6)│ Decipher │ Right key─────(cid:6)│ Encipher │
│ │ │ │
└─────────┬─────────┘ └─────────┬─────────┘
│ │
(cid:14) (cid:14)
┌───────────────────┐ ┌───────────────────┐
│ │ │ │
Left key──────(cid:6)│ Encipher │ Left key──────(cid:6)│ Decipher │
│ │ │ │
└─────────┬─────────┘ └─────────┬─────────┘
│ │
(cid:14) (cid:14)
Ciphertext Cleartext
Figure18.Triple-DESdataencryptionanddecryption
AppendixF.Cryptographicalgorithmsandprocesses 495

ANSI X3.106 Cipher Block Chaining (CBC) method
ANSI standard X3.106 defines four modes of operation for ciphering. One of these modes, Cipher Block
Chaining (CBC), defines the basic method for ciphering multiple 8-byte data strings. Figure19 and
Figure20 on page 497 show CBC using the Encipher and Decipher verbs.Aplaintext data string that must
be a multiple of eight bytes is processed as a series of 8-byte blocks. The ciphered result from processing
an 8-byte block is XORed 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 XORed with the first block of eight bytes. When you call the Encipher or Decipher verb, specify
the INITIAL or CONTINUE keywords. If you specify the INITIAL keyword, the default, the initialization
vector from the verb parameter is XORed with the first eight bytes of data. If you specify the CONTINUE
keyword, the OCV identified by the chaining_vector parameter is XORed with the first eight bytes of data.
┌──────────────┐
│Verb parameter│
└──────┬───────┘
│
┌──────(cid:14)───────┐ (cid:17)────── Plaintext from application program ────────────(cid:6)
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ vector │ │ Data (1,8) │ │ Data (9,16) │ │Data (N*8─7,N*8)│
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│INITIAL │ │ │
│keyword │ │ │
(cid:14) ┌───┐ ┌─(cid:14)─┐ ┌─(cid:14)─┐ ┌─(cid:14)─┐
or───(cid:6)ICV├──────(cid:6)XOR│ ┌──────(cid:6)XOR│ ┌ ─ ───(cid:6)XOR│
(cid:18) └───┘ └─┬─┘ │ └─┬─┘ └─┬─┘
│CONTINUE │ │ │ │
│keyword ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐
│ │ Encipher │ │ │ Encipher │ │ Encipher │
│ └─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘
│ │ │ │ │ ┌───┐
│ ├─────────┘ ├────── ─ ┘ ├─────────────(cid:6)OCV│
│ │ │ │ └─┬─┘
│ ┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐ │
│ │ Data (1,8) │ │ Data (9,16) │ │Data (N*8─7,N*8)│ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ (cid:17)───────── Ciphertext to application program ──────────(cid:6) │
│ ┌────────(cid:14)──────┐
└──────────────────────────────────────────────────────────────┤Chaining vector│
└───────────────┘
Figure19.EncipheringusingtheANSIX3.106CBCmethod
496 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

┌──────────────┐
│Verb parameter│
└──────┬───────┘
│
┌──────(cid:14)───────┐ (cid:17)──────── Ciphertext from application program ─────────(cid:6)
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ vector │ │ Data (1,8) │ │ Data (9,16) │ │Data (N*8─7,N*8)│
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│ │ │ │ ┌───┐
│ ├─────────┐ ├────── ─ ┐ ├─────────────(cid:6)OCV│
│ │ │ │ │ └─┬─┘
│ ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐ │
│ │ Decipher │ │ │ Decipher │ │ Decipher │ │
│INITIAL └─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘ │
│keyword │ │ │ │ │
(cid:14) ┌───┐ ┌─(cid:14)─┐ │ ┌─(cid:14)─┐ ┌─(cid:14)─┐ │
or───(cid:6)ICV├──────(cid:6)XOR│ └──────(cid:6)XOR│ └ ─ ───(cid:6)XOR│ │
(cid:18) └───┘ └─┬─┘ └─┬─┘ └─┬─┘ │
│CONTINUE │ │ │ │
│keyword │ │ │ │
│ ┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐ │
│ │ Data (1,8) │ │ Data (9,16) │ │Data (N*8─7,N*8)│ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ (cid:17)──────── Plaintext to application program ────────────(cid:6) │
│ ┌────────(cid:14)──────┐
└──────────────────────────────────────────────────────────────┤Chaining vector│
└───────────────┘
Figure20.DecipheringusingtheCBCmethod
ANSI X9.23 cipher block chaining
ANSI X9.23 defines an enhancement to the basic cipher block chaining (CBC) mode ofANSI X3.106 so
that the system can process data with a length that is not an exact multiple of eight bytes. TheANSI 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 Figure21 on page 498. 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 Figure22 on page 498.
The output chaining vector can be used as feedback with this method in the same way as with the X3.106
method.
TheANSI X9.23 method requires the caller to supply an initialization vector, and it does not allow
specification of a pad character.
Note: TheANSI 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.
AppendixF.Cryptographicalgorithmsandprocesses 497

┌──────────────┐
│Verb parameter│
└──────┬───────┘
│
┌──────(cid:14)───────┐ (cid:17)── Plaintext from application program ───(cid:6)
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────┬─────┬─────┐
│ vector │ │ Data (1,8) │ │Data (N*8─7,N*8)│ │Data│ Pad │Count│
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └────┴──┬──┴─────┘
│ │ │ │
│ ┌─(cid:14)─┐ ┌─(cid:14)─┐ ┌─(cid:14)─┐
└───────────────(cid:6)XOR│ ┌ ─ ───(cid:6)XOR│ ┌──────(cid:6)XOR│
└─┬─┘ └─┬─┘ │ └─┬─┘
│ │ │ │ │
│ │ │ │
┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐
│ Encipher │ │ Encipher │ │ │ Encipher │
└─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘
│ │ │ │
├────── ─ ┘ ├─────────┘ │
│ │ │
┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐
│ Data (1,8) │ │Data (N*8─7,N*8)│ │ Last block │
└────────────────┘ └────────────────┘ └────────────────┘
(cid:17)─────── Ciphertext to application program ────────────(cid:6)
Figure21.EncipheringusingtheANSIX9.23method
┌──────────────┐
│Verb parameter│
└──────┬───────┘
│
┌──────(cid:14)───────┐ (cid:17)──────── Ciphertext from application program ─────────(cid:6)
│Initialization│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ vector │ │ Data (1,8) │ │Data (N*8─7,N*8)│ │ Last block │
└──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│ │ │ │
│ ├────── ─ ┐ ├─────────┐ │
│ │ │ │ │
│ ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐ │ ┌─────(cid:14)─────┐
│ │ Decipher │ │ Decipher │ │ │ Decipher │
│ └─────┬─────┘ │ └─────┬─────┘ │ └─────┬─────┘
│ │ │ │ │
│ ┌─(cid:14)─┐ │ ┌─(cid:14)─┐ │ ┌─(cid:14)─┐
└───────────────(cid:6)XOR│ └ ─ ───(cid:6)XOR│ └──────(cid:6)XOR│
└─┬─┘ └─┬─┘ └─┬─┘
│ │ │
┌───────(cid:14)────────┐ ┌───────(cid:14)────────┐ ┌────┬──(cid:14)──┬─────┐
│ Data (1,8) │ │Data (N*8─7,N*8)│ │Data│ Pad │Count│
└────────────────┘ └────────────────┘ └────┴─────┴─────┘
(cid:17)─── Plaintext to application program ────(cid:6)
Figure22.DecipheringusingtheANSIX9.23method
Triple-DES ciphering algorithms
Atriple-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 e-d-e
scheme without feedback.
498 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

TDES CBC
Encryption of general data, and RSAsection type X'08' CRT-format private keys and OPK keys,
employs the scheme depicted in Figure23 and Figure24 on page 500. This is often referred to as
“outer CBC mode.”
This CCAsupports double-length DES keys for triple-DES data encryption using the Encipher and
Decipher verbs. The triple-length asymmetric master key is used to CBC encrypt CRT-format OPK
keys.
EDEx / DEDx
CCAemploys EDEx processes for encrypting several of the RSAprivate 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 Figure25
on page 501 and Figure26 on page 502. K1, K2, and K3 are true keys while “K4” and “K5” are
initialization vectors. See Figure25 on page 501 and Figure26 on page 502.
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
│ T1(cid:17)64(cid:6) │ T2(cid:17)64(cid:6) │ T3(cid:17)64(cid:6) │ │ Tn(cid:17)64(cid:6) │
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘
(cid:14) (cid:14) (cid:14) (cid:14)
┌───┐ ┌───┐ ┌───┐ ┌───┐
IV─(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌──//───(cid:6)│XOR│
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
Ka─(cid:6)│ e │ │ Ka─(cid:6)│ e │ │ Ka─(cid:6)│ e │ │ Ka─(cid:6)│ e │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
Kb─(cid:6)│ d │ │ Kb─(cid:6)│ d │ │ Kb─(cid:6)│ d │ │ Kb─(cid:6)│ d │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
Kc─(cid:6)│ e │ │ Kc─(cid:6)│ e │ │ Kc─(cid:6)│ e │ │ Kc─(cid:6)│ e │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
├────┘ ├────┘ ├────┘ │
(cid:14) (cid:14) (cid:14) (cid:14)
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
│ S1(cid:17)64(cid:6) │ S2(cid:17)64(cid:6) │ S3(cid:17)64(cid:6) │ │ Sn(cid:17)64(cid:6) │
└─────────────┴─────────────┴─────────────┴/┴─────────────┘
For 2-key triple-DES, Kc = Ka
Figure23.Triple-DESCBCencryptionprocess
AppendixF.Cryptographicalgorithmsandprocesses 499

┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
│ S1(cid:17)64(cid:6) │ S2(cid:17)64(cid:6) │ S3(cid:17)64(cid:6) │ │ Sn(cid:17)64(cid:6) │
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘
├────┐ ├────┐ ├────┐ │
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
Kc─(cid:6)│ d │ │ Kc─(cid:6)│ d │ │ Kc─(cid:6)│ d │ │ Kc─(cid:6)│ d │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
Kb─(cid:6)│ e │ │ Kb─(cid:6)│ e │ │ Kb─(cid:6)│ e │ │ Kb─(cid:6)│ e │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
Ka─(cid:6)│ d │ │ Ka─(cid:6)│ d │ │ Ka─(cid:6)│ d │ │ Ka─(cid:6)│ d │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
IV─(cid:6)│XOR│ └─────(cid:6)│XOR│ └─────(cid:6)│XOR│ └──//───(cid:6)│XOR│
└─┬─┘ └─┬─┘ └─┬─┘ └─┬─┘
(cid:14) (cid:14) (cid:14) (cid:14)
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
│ T1(cid:17)64(cid:6) │ T2(cid:17)64(cid:6) │ T3(cid:17)64(cid:6) │ │ Tn(cid:17)64(cid:6) │
└─────────────┴─────────────┴─────────────┴/┴─────────────┘
For 2-key triple-DES, Kc = Ka
Figure24.Triple-DESCBCdecryptionprocess
500 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
EDE2 EDE3 EDE5 │ T1<64> │ T2<64> │ T3<64> │ │ Tn<64> │
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘
(cid:14) (cid:14) (cid:14) (cid:14)
┌───┐ ┌───┐ ┌───┐ ┌───┐
0 0 K4 IVa─(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌──//───(cid:6)│XOR│
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
K1 K1 K1 Ka─(cid:6)│ e │ │ Ka─(cid:6)│ e │ │ Ka─(cid:6)│ e │ │ Ka─(cid:6)│ e │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
├────┘ ├────┘ ├────┘ │
├────┐ ├────┐ ├────┐ │
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
K2 K2 K2 Kb─(cid:6)│ d │ │ Kb─(cid:6)│ d │ │ Kb─(cid:6)│ d │ │ Kb─(cid:6)│ d │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
0 0 0 IVb─(cid:6)│XOR│ └─────(cid:6)│XOR│ └─────(cid:6)│XOR│ └──//───(cid:6)│XOR│
└─┬─┘ └─┬─┘ └─┬─┘ └─┬─┘
(cid:14) (cid:14) (cid:14) (cid:14)
┌───┐ ┌───┐ ┌───┐ ┌───┐
0 0 K5 IVc─(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌──//───(cid:6)│XOR│
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
K1 K3 K3 Kc─(cid:6)│ e │ │ Kc─(cid:6)│ e │ │ Kc─(cid:6)│ e │ │ Kc─(cid:6)│ e │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
├────┘ ├────┘ ├────┘ │
(cid:14) (cid:14) (cid:14) (cid:14)
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
│ S1<64> │ S2<64> │ S3<64> │ │ Sn<64> │
└─────────────┴─────────────┴─────────────┴/┴─────────────┘
Figure25.EDEalgorithm
AppendixF.Cryptographicalgorithmsandprocesses 501

┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
EDE2 EDE3 EDE5 │ S1<64> │ S2<64> │ S3<64> │ │ Sn<64> │
└──────┬──────┴──────┬──────┴──────┬──────┴/┴──────┬──────┘
├────┐ ├────┐ ├────┐ │
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
K1 K3 K3 Kc─(cid:6)│ d │ │ Kc─(cid:6)│ d │ │ Kc─(cid:6)│ d │ │ Kc─(cid:6)│ d │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
0 0 K5 IVc─(cid:6)│XOR│ └─────(cid:6)│XOR│ └─────(cid:6)│XOR│ └──//───(cid:6)│XOR│
└─┬─┘ └─┬─┘ └─┬─┘ └─┬─┘
(cid:14) (cid:14) (cid:14) (cid:14)
┌───┐ ┌───┐ ┌───┐ ┌───┐
0 0 0 IVb─(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌─────(cid:6)│XOR│ ┌──//───(cid:6)│XOR│
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
K2 K2 K2 Kb─(cid:6)│ e │ │ Kb─(cid:6)│ e │ │ Kb─(cid:6)│ e │ │ Kb─(cid:6)│ e │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
├────┘ ├────┘ ├────┘ │
├────┐ ├────┐ ├────┐ │
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
K1 K1 K1 Ka─(cid:6)│ d │ │ Ka─(cid:6)│ d │ │ Ka─(cid:6)│ d │ │ Ka─(cid:6)│ d │
└─┬─┘ │ └─┬─┘ │ └─┬─┘ │ └─┬─┘
(cid:14) │ (cid:14) │ (cid:14) │ (cid:14)
┌───┐ │ ┌───┐ │ ┌───┐ │ ┌───┐
0 0 K4 IVa─(cid:6)│XOR│ └─────(cid:6)│XOR│ └─────(cid:6)│XOR│ └──//───(cid:6)│XOR│
└─┬─┘ └─┬─┘ └─┬─┘ └─┬─┘
(cid:14) (cid:14) (cid:14) (cid:14)
┌─────────────┬─────────────┬─────────────┬/┬─────────────┐
│ T1<64> │ T2<64> │ T3<64> │ │ Tn<64> │
└─────────────┴─────────────┴─────────────┴/┴─────────────┘
Figure26.DEDprocess
MAC calculation methods
Four variations of DES-based message authentication can be used by the MAC Generate and MAC Verify
verbs:
v “ANSI X9.9 MAC”
v “ANSI X9.19 Optional Procedure 1 MAC” on page 503
v “EMV MAC” on page 503
v “ISO 16609 TDES MAC” on page 503
ANSI X9.9 MAC
The Financial Institution (Wholesale) MessageAuthentication Standard (ANSI 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.3
Figure27 on page 503 shows the MAC calculation for binary data. In this figure, KEY is a 64-bit key, and
T - T are 64-bit data blocks of text. If T is less than 64 bits long, binary zeros are appended to the right
1 n n
of T . Data blocks T ...T are DES CBC-encrypted with all output discarded except for the final output
n 1 n
block, O .
n
3.TheANSIX9.9standarddefinesfiveoptions.TheMACGenerateandMACVerifyverbsimplementoption1,binarydata.
502 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

ANSI X9.19 Optional Procedure 1 MAC
The Financial Institution (Retail) MessageAuthentication Standard,ANSI X9.19 Optional Procedure 1
(ISO/IEC 9797-1,Algorithm 3) specifies additional processing of the 64-bit O MAC value. The CCA
n
“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
ANSI X9.9 andANSI X9.19 Optional Procedure 1 (ISO/IEC 9797-1,Algorithm 3), except for padding added
to the end of the message.Append one byte of X'80' to the original message. Then append additional
bytes, as required, of X'00' to form an extended message, which is a multiple of eight bytes in length.
In the X9.9 and X9.19 Optional Procedure 1 standards, the leftmost 32 bits (4 bytes) of O are taken as
n
the MAC. In the EMV standards, the MAC value is between four and eight bytes in length. CCAprovides
support for the leftmost four, six, and eight bytes of MAC value.
T T T T
1 2 n-1 n
XOR XOR XOR
KEY Enc KEY Enc KEY Enc KEY Enc
O O O O
1 2 n-1 n
(OCV)
ANSI X9.9 MAC
(and to decipher and
encipher for ANSI X9.19)
Figure27.MACcalculationmethod
ISO 16609 TDES 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 TDES
MAC method. The ISO 16609 TDES MAC method corresponds to ISO/IEC 9797-1, algorithm 1 using
T-DEA(ANSI X9.52:1998). ISO/FDIS 16609 identifies this method as one of the recommended ways to
generate a MAC using symmetric techniques.
The ISO 16609 TDES MAC method uses a double-length DES key and operates on data blocks that are a
multiple of eight bytes. If the last input data block is not a multiple of eight bytes, binary zeros are
appended to the right of the block.ACBC mode triple-DES (TDES) 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.
AppendixF.Cryptographicalgorithmsandprocesses 503

RSA key-pair generation
RSAkey-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 withANSI 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 The Rabin-Miller Probabilistic Primality Test is iterated 8 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 theANSI 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.
1. For each key generation, and for any size of key, the PKAmanager 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 random number in two ways, but with the CCASupport Program only
one way is used, namely, the PRNG method. The PKAmanager 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 PKAmanager requests.An RSAkey is generated from
random information obtained from two cascaded SHA-1 PRNGs.
3. An RSAkey is based on one or more 24-byte seeds from the RNG manager source, depending on the
dynamic mix of tasks running inside the coprocessor.
There exists a system RNG manager (ANSI X9.31 compliant) that is used as the source for pseudo
random numbers. The PKAmanager also has a PRNG that is DSAcompliant for generating primes. The
PKAmanager 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.
Multiple decipherment and encipherment
This section explains multiple encipherment and decipherment and their equations.
CCAuses multiple encipherment whenever it enciphers a key under a key-encrypting key such as the
master key or the transport key and in triple-DES encipherment for data privacy. Multiple encipherment is
superior to single encipherment because multiple encipherment increases the work needed to “break” a
key. CCAprovides extra protection for a key by enciphering it under an enciphering key multiple times
rather than once. The multiple encipherment method for keys enciphered under a key-encrypting key uses
a double-length (128-bit) key split into two 64-bit halves. Like single encipherment, multiple encipherment
uses a DES based on the electronic code book (ECB) mode of encipherment.
Keys can either be double-length or single-length depending on the installation and their cryptographic
function. When a single-length key is encrypted under a double-length key, multiple encipherment is
performed on the key. In the multiple encipherment method, the key is encrypted under the left half of the
enciphering key. The result is then decrypted under the right half of the enciphering key. Finally, this result
is encrypted under the left half of the enciphering key again.
504 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

When a double-length key is encrypted with multiple encipherment, the method is similar, except CCA
uses two enciphering keys. One enciphering key encrypts each half of the double-length key.
Double-length keys active on the system have two master key variants used when enciphering them.
Multiple encipherment and decipherment is not only used to protect or retrieve a cryptographic key, but
they are also used to protect or retrieve 64-bit data in the area of PIN applications. For example, the
following two sections use a double-length *KEK as an example to cipher a single-length key even though
the same algorithms apply to cipher 64-bit data by a double-length PIN-related cryptographic key.
CCAalso supports triple-DES encipherment for data privacy using double-length and triple-length DATA
keys. For this procedure the data is first enciphered using the first DATAkey. The result is then deciphered
using the second DATAkey. This second result is then enciphered using the third DATAkey when a
triple-length key is provided or reusing the first DATAkey when a double-length key is provided.
Note that an asterisk (*) preceding the key means the key is double-length. Notations in this chapter have
the following meaning:
v eK(x), where x is enciphered under K
v dK(y) represents plaintext, where K is the key and y is the ciphertext
Therefore, dK(eK(x)) equals x for any 64-bit key K and any 64-bit plaintext x.
When a key (*K) to be protected is double-length, two double-length *KEKs are used. One *KEK is used
for protecting the left half of the key (*K); another is for the right half. Multiple encipherment is used with
the appropriate *KEK for protecting each half of the key.
Multiple encipherment of single-length keys
The multiple encipherment of a single-length key (K) using a double-length *KEK is defined as follows:
e*KEK(K) = eKEKL(dKEKR(eKEKL(K)))
where KEKLis the left 64 bits of *KEK and KEKR is the right 64 bits of *KEK.
Figure28 illustrates the definition.
AppendixF.Cryptographicalgorithmsandprocesses 505

K
KEKL E
KEKR D
KEKL E
e*KEK(K)
Figure28.Multipleenciphermentofsingle-lengthkeys
Multiple decipherment of single-length keys
The multiple encipherment of an encrypted single-length key (Y = e*KEK(K)) using a double-length *KEK
is defined as follows:
d*KEK(Y) = dKEKL(eKEKR(dKEKL(Y)))
= d*KEK(e*KEK(K))
= K
where KEKLis the left 64 bits of *KEK and KEKR is the right 64 bits of *KEK.
Figure29 illustrates the definition.
506 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

e*KEK(K)
KEKL D
KEKR E
KEKL D
K
Figure29.Multipledeciphermentofsingle-lengthkeys
Multiple encipherment of double-length keys
The multiple encipherment of a double-length key (*K) using two double-length *KEKs, *KEKa, and *KEKb
is defined as follows:
e*KEKa(KL) || e*KEKb(KR) =
eKEKaL(dKEKaR(eKEKaL(KL))) ||
eKEKbL(dKEKbR(eKEKbL(KR)))
where:
v KLis the left 64 bits of *K
v KR is the right 64 bits of *K
v KEKaLis the left 64 bits of *KEKa
v KEKaR is the right 64 bits of *KEKa
v KEKbLis the left 64 bits of *KEKb
v KEKbR is the right 64 bits of *KEKb
v || means concatenation
Figure30 illustrates the definition.
AppendixF.Cryptographicalgorithmsandprocesses 507

KL KR
KEKaL E KEKbL E
KEKaR D KEKbR D
KEKaL E KEKbL E
e*KEKa(KL) e*KEKb(KR)
Figure30.Multipleenciphermentofdouble-lengthkeys
Multiple decipherment of double-length keys
The multiple decipherment of an encrypted double-length key, *Y = e*KEKa(KL) || e*KEKb(KR), using two
double-length *KEKs, *KEKa, and *KEKb, is defined as follows:
D*KEKa(YL) || d*KEKb(YR)
= dKEKaL(eKEKaR(dKEKaL(YL))) ||
dKEKbL(eKEKbR(dKEKbL(YR)))
= d*KEKa(e*KEKa(KL)) ||
d*KEKb(e*KEKb(KR))
= *K
where
v YLis the left 64 bits of *Y
v YR is the right 64 bits of *Y
v KEKaLis the left 64 bits of *KEKa
v KEKaR is the right 64 bits of *KEKa
v KEKbLis the left 64 bits of *KEKb
v KEKbR is the right 64 bits of *KEKb
v || means concatenation
Figure31 illustrates the definition.
508 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

YL = e*KEKa(KL) YR = e*KEKb(KR)
KEKaL D KEKbL D
KEKaR E KEKbR E
KEKaL D KEKbL D
KL KR
Figure31.Multipledeciphermentofdouble-lengthkeys
Multiple encipherment of triple-length keys
The multiple encipherment of a triple-length key (**K) using two double-length *KEKs, *KEKa, and *KEKb
is defined as follows:
e*KEKa(KL) || e*KEKb(KM) || e*KEKa(KR) =
eKEKaL(dKEKaR(eKEKaL(KL))) ||
eKEKbL(dKEKbR(eKEKbL(KM))) ||
eKEKaL(dKEKaR(eKEKaL(KR)))
where:
v KLis the left 64 bits of **K
v KM is the next 64 bits of **K
v KR is the right 64 bits of **K
v KEKaLis the left 64 bits of *KEKa
v KEKaR is the right 64 bits of *KEKa
v KEKbLis the left 64 bits of *KEKb
v KEKbR is the right 64 bits of *KEKb
v || means concatenation
Figure32 on page 510 illustrates the definition.
AppendixF.Cryptographicalgorithmsandprocesses 509

YL = e*KEKa(KL) YM = e*KEKb(KM) YR = e*KEKa(KR)
KEKaL D KEKbL D KEKaL D
KEKaR E KEKbR E KEKaR E
KEKaL D KEKbL D KEKaL D
KL KM KR
Figure32.Multipleenciphermentoftriple-lengthkeys
Multiple decipherment of triple-length keys
The multiple decipherment of an encrypted triple-length key **Y = e*KEKa(KL) || e*KEKb(KM) ||
e*KEKa(KR), using two double-length *KEKs, *KEKa, and *KEKb, is defined as follows:
d*KEKa(YL) || d*KEKb(YM) || d*KEKa(YR)
= dKEKaL(eKEKaR(dKEKaL(YL))) ||
dKEKbL(eKEKbR(dKEKbL(YM))) ||
dKEKaL(eKEKaR(dKEKaL(YR)))
= d*KEKa(e*KEKa(KL)) ||
d*KEKb(e*KEKb(KM)) ||
d*KEKa(e*KEKa(KR))
= **K
where:
v YLis the left 64 bits of **Y
v YM is the next 64 bits of **Y
v YR is the right 64 bits of **Y
v KEKaLis the left 64 bits of *KEKa
v KEKaR is the right 64 bits of *KEKa
v KEKbLis the left 64 bits of *KEKb
v KEKbR is the right 64 bits of *KEKb
v || means concatenation
Figure33 on page 511 illustrates the definition.
510 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

KL KM KR
KEKaL E KEKbL E KEKaL E
KEKaR D KEKbR D KEKaR D
KEKaL E KEKbL E KEKaL E
e*KEKa(KL) e*KEKb(KM) e*KEKa(KR)
Figure33.Multipledeciphermentoftriple-lengthkeys
PKA92 key format and encryption process
The Symmetric Key Generate and the Symmetric Key Import verbs optionally support a PKA92 method of
encrypting a DES key with an RSApublic key. This format is adapted from the IBM Transaction Security
System (TSS) 4753 and 4755 product's implementation of “PKA92”. The verbs do not create or accept the
complete PKA92AS key token as defined for the TSS products. Rather, the verbs support only the actual
RSA-encrypted portion of a TSS PKA92 key token, the AS External Key Block.
Forming an external key block - The PKA96 implementation forms anAS External Key Block by
RSA-encrypting a key block using a public key. The key block is formed by padding the key record
detailed in Table158 with zero bits on the left, high-order end of the key record. The process completes
the key block with three sub-processes: masking, overwriting, and RSAencrypting.
Table158.PKA96clearDESkeyrecord
Offset(Bytes) Length(Bytes) Description
Zero-bitpaddingtoformastructureaslongasthelengthofthepublickeymodulus.Theimplementationconstrains
thepublickeymodulustoamultipleof64bitsintherangeof512-1024bits.Notethatgovernmentexportorimport
regulationscanimposelimitsonthemoduluslength.Themaximumlengthisvalidatedbyacheckagainstavaluein
theFunctionControlVector.
000 005 Headerandflags:X'0100000000.'
005 016 EnvironmentIdentifier(EID),encodedinASCII.
021 008 ControlvectorbasefortheDESkey.
029 008 RepeatoftheCVdataatoffset021.
037 008 Thesingle-lengthDESkeyorthelefthalfofadouble-lengthDESkey.
045 008 Therighthalfofadouble-lengthDESkeyorarandomnumber.Thisvalueis
locallydesignated"K."
AppendixF.Cryptographicalgorithmsandprocesses 511

Table158.PKA96clearDESkeyrecord (continued)
Offset(Bytes) Length(Bytes) Description
053 008 Randomnumber,"IV."
061 001 Endingbyte,X'00.'
Masking Sub-process - Create a mask by CBC encrypting a multiple of eight bytes of binary zeros using K
as the key and IV as the initialization vector as defined in the key record at offsets 45 and 53. XOR the
mask with the key record and call the result PKR.
Overwriting Sub-process - Set the high-order bits of PKR to B'01' and set the low-order bits to B'0110'.
XOR K and IV and write the result at offset 45 in PKR.
Write IV at offset 53 in PKR. This causes the masked and overwritten PKR to have IV at its original
position.
Encrypting Sub-process - RSAencrypt the overwritten PKR masked key record using the public key of the
receiving node.
Recovering a key from an external key block - Recover the encrypted DES key from anAS External
Key Block by performing decrypting, validating, unmasking, and extraction sub-processes.
Decrypting Sub-process - RSAdecrypt theAS External Key Block using an RSAprivate key and call the
result of the decryption PKR. The private key must be usable for key management purposes.
Validating Sub-process - Verify the high-order two bits of the PKR record are valued to B'01' and the
low-order four bits of the PKR record are valued to B'0110'.
Unmasking Sub-process - Set IV to the value of the eight bytes at offset 53 of the PKR record. Note that
there is a variable quantity of padding prior to offset 0. See Table158 on page 511.
Set K to the XOR of IV and the value of the eight bytes at offset 45 of the PKR record.
Create a mask equal in length to the PKR record by CBC encrypting a multiple of eight bytes of binary
zeros using K as the key and IV as the initialization vector. XOR the mask with PKR and call the result the
key record.
Copy K to offset 45 in the PKR record.
Extraction Sub-process. Confirm that:
v The four bytes at offset 1 in the key record 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, the Environment Identifier (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.
512 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Formatting hashes and keys in public-key cryptography
The Digital Signature Generate and Digital Signature Verify verbs support several methods for formatting a
hash and, in some cases, a descriptor for the hashing method, into a bit-string to be processed by the
cryptographic algorithm. This section discusses theANSI X9.31 and PKCS #1 methods. The ISO 9796-1
method can be found in the ISO standard.
This section also describes the PKCS #1, version 1, 1.5, and 2.0, methods for placing a key in a bit string
for RSAciphering as part of a key exchange.
ANSI X9.31 hash format
WithANSI X9.31, the string that is processed by the RSAalgorithm 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'32' RIPEMD-128
X'33' SHA-1
X'34' SHA-256 (Release 3.30.05 or later)
v The final byte is X'CC'.
PKCS #1 formats
Version 2.0 of the PKCS #1 standard 4 defines methods for formatting keys and hashes prior to RSA
encryption of the resulting data structures. The earlier versions of the PKCS #1 standard defined block
types 0, 1, and 2, but in the current standard that terminology is dropped.
CCAimplemented these processes using the terminology of the Version 2.0 standard:
v For formatting keys for secured transport CSNDSYX, CSNDSYG, CSNDSYI):
– RSAES-OAEP, the preferred method for key-encipherment 5 when exchanging DATAkeys between
systems. Keyword PKCSOAEP is used to invoke this formatting technique. The P parameter
described in the standard is not used and its length is set to zero.
– RSAES-PKCS1-v1_5, is an older method for formatting keys. Keyword PKCS-1.2 is used to invoke
this formatting technique.
v For formatting hashes for digital signatures (CSNDDSG and CSNDDSV):
– RSASSA-PKCS1-v1_5, the newer name for the block-type 1 format. Keyword PKCS-1.1 is used to
invoke this formatting technique.
– The PKCS #1 specification no longer discusses use of block-type 0. Keyword PKCS-1.0 is used to
invoke this formatting technique. Use of block-type 0 is discouraged.
4.PKCSstandardscanberetrievedfromhttp://www.rsasecurity.com/rsalabs/pkcs.
5.ThePKA92methodandthemethodincorporatedintotheSETstandardareotherexamplesoftheOptimalAsymmetricEncryption
Padding(OAEP)technique.TheOAEPtechniqueisattributedtoBellareandRogaway.
AppendixF.Cryptographicalgorithmsandprocesses 513

Using the terminology from older versions of the PKCS #1 standard, block types 0 and 1 are used to
format a hash and block type 2 is used to format a DES key. The blocks consist of the following (“||”
means concatenation):
v X'00' || BT || PS || X'00' || D
v
v 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 RSAkey, and is bytes of X'00' for block type 0, X'FF' for block type 1, and random and
non-X'00' for block type 2. The length of PS must be a minimum of eight bytes.
D Is the key, or the concatenation of the BER-encoded hash identifier and the hash value.
You can create the BER encoding of an MD5 or SHA-1 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'
514 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix G. Access control points and verbs
| This appendix gives details about theAccess Control Points (ACPs) used by the verbs in this document.
| ACPs are also referred to as commands.
Important: By default, you should disable commands. Do not enable anACP unless you know why you
are enabling it.
For instructions on how to enable and disable theseACPs using the TKE workstation, see z/OS
Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation User’s Guide.
For systems that do not use the optional TKE workstation, mostACPs (current and new) are enabled in
the DEFAULT role with the appropriate licensed internal code on the CEX3C.
| Note that each domain in the CEX3C (with hardware enforced access permissions) starts out with its own
| DEFAULT role with the defaultACP values as shown. However, it is possible to use the TKE to change
| ACP values in the DEFAULT role or to define other roles. The role to which a user is assigned determines
| theACPs available to that user. Full coverage of TKE use for configuration is outside the scope of this
| document. For details, see z/OS Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation User’s
| Guide.
Table159 lists the CCAACPs. The name of eachACP is given as it appears on the panels of the TKE
user interface. Note that the group names are also given to aid locating theACPs. The table includes the
following columns:
ACP number
The hexadecimal offset, orACP code, for the command. Offsets between X'0000' and X'FFFF' that are
not listed in this table are reserved.
| Name ofACP from TKE interface
| The name of theACP as it appears on the TKE interface
Verb name
The names of the verbs that require thatACP to be enabled; for example, the Encipher (CSNBENC)
verb fails without permission to use the EncipherACP.
Entry point
The entry-point name of the verb.
Initial setting
Whether theACP is ON or OFF by default.
Usage
Usage recommendations for theACP. The abbreviations in this column are explained at the end of the
table.
See the Restrictions, Required commands, or Usage notes sections at the end of each verb description
for access control information.
|| Table159.AccessControlPointsandcorrespondingCCAverbs
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
| 0001GROUP:ISPFServices
| Note: ThisgroupnamereferstoISPF,az/OSfeature.AlthoughISPFisnotrelevanttoLinuxonIBMSystemz,itislistedhereas
| shownontheTKEpanelstoavoidconfusion.
|||||| X'0018' LoadFirstDESMasterKeyPart MasterKeyProcess† CSNBMKP ON SC,
| SEL
©CopyrightIBMCorp.2007,2011 515

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'0019' CombineDESMasterKeyParts MasterKeyProcess† CSNBMKP ON SC,
| SEL
|||||| X'001A' SetDESMasterKey MasterKeyProcess† CSNBMKP ON SC,
| SEL
|||||| X'0032' ClearNewDESMasterKeyRegister MasterKeyProcess† CSNBMKP ON O,SUP
|||||| X'0053' LoadFirstRSAMasterKeyPart MasterKeyProcess† CSNBMKP ON SC,
| SEL
|||||| X'0054' CombineRSAMasterKeyParts MasterKeyProcess† CSNBMKP ON SC,
| SEL
|||||| X'0057' SetRSAMasterKey MasterKeyProcess† CSNBMKP ON SC,
| SEL
|||||| X'0060' ClearNewRSAMasterKeyRegister MasterKeyProcess† CSNBMKP ON SC,
| SEL
|||||| X'0124' ClearNewAESMasterKey MasterKeyProcess† CSNBMKP ON O,SUP
| (Rel.
| 4.0or
| later)
|||||| X'0125' LoadFirstAESMasterKeyPart MasterKeyProcess† CSNBMKP ON O,SUP
| (Rel.
| 4.0or
| later)
|||||| X'0126' CombineAESMasterKeyParts MasterKeyProcess† CSNBMKP ON O,SUP
| (Rel.
| 4.0or
| later)
|||||| X'0128' SetAESMasterKey MasterKeyProcess† CSNBMKP ON O,SUP
| (Rel.
| 4.0or
| later)
|||||| X'031F' ClearNewECCMasterKey MasterKeyProcess CSNBMKP ON O(Rel
| 4.1.0or
| later)
|||||| X'0320' LoadFirstECCMasterKeyPart MasterKeyProcess CSNBMKP ON O(Rel
| 4.1.0or
| later)
|||||| X'0321' CombineECCMasterKeyParts MasterKeyProcess CSNBMKP ON O(Rel
| 4.1.0or
| later)
|||||| X'0322' SetECCMasterKey MasterKeyProcess CSNBMKP ON O(Rel
| 4.1.0or
| later)
|||||| X'0326' GenerateECCkeysintheclear PKAKeyGenerate CSNDPKG ON O(Rel
| 4.1.0or
| later)
| 0002GROUP:APICryptographicServices
|||||| X'000E' Encipher-DES Encipher CSNBENC ON O
|||||| X'000F' Decipher-DES Decipher CSNBDEC ON O
|||||| X'0010' MACGenerate MACGenerate CSNBMGN ON O
|||||| X'0011' MACVerify MACVerify CSNBMVR ON O
|||||| X'0012' KeyImport KeyImport CSNBKIM ON O
|||||| X'0013' KeyExport KeyExport CSNBKEX ON O
|||||| X'001B' KeyPartImport-firstkeypart KeyPartImport† CSNBKPI ON SC,
| SEL
516 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'001C' KeyPartImport-middleandlast KeyPartImport† CSNBKPI ON SC,
| SEL
|||||| X'001D' KeyTestandKeyTest2 Key Test CSNBKYT ON R
|| Key Test2 CSNBKYT2
|| Key Test Extended CSNBKYTX
|| Key Storage Initialization CSNBKSI
|| 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
|| 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
|| 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'001E' ReencipherCKDS KeyTokenChange CSNBKTC ON O(Rel
|| Note: TheTKEnameforthisACPrefersto 4.1.0or
|| z/OSkeystorage(CKDS).Howeverz/OS later)
| keystorageisnotimpacted.ThisACP
| referstoaserviceforLinux,seeverbfor
| details.
|||||| X'001F' KeyTranslate KeyTranslate CSNBKTR ON O
|||||| X'0040' DiversifiedKeyGenerate-CLR8-ENC DiversifiedKeyGenerate‡ CSNBDKG ON O,SEL
|||||| X'0041' DiversifiedKeyGenerate-TDES-ENC DiversifiedKeyGenerate‡ CSNBDKG ON O,SEL
|||||| X'0042' DiversifiedKeyGenerate-TDES-DEC DiversifiedKeyGenerate‡ CSNBDKG ON O,SEL
|||||| X'0043' DiversifiedKeyGenerate-SESS-XOR DiversifiedKeyGenerate‡ CSNBDKG ON O,SEL
|||||| X'0044' DiversifiedKeyGenerate-Singlelengthor DiversifiedKeyGenerate‡ CSNBDKG ON SC,
|| samehalves SEL
|||||| X'0045' DiversifiedKeyGenerate-TDES-XOR DiversifiedKeyGenerate‡ CSNBDKG ON O,SEL
|||||| X'0046' DiversifiedKeyGenerate- DiversifiedKeyGenerate‡ CSNBDKG ON O,SEL
| TDESEMV2/TDESEMV4
|||||| X'008A' MDCGenerate MDCGenerate CSNBMDG OFF R
|||||| X'008C' KeyGenerate-OPIM_OPEX_IMEX_etc. KeyGenerate‡ CSNBKGN ON O
|||||| X'008E' KeyGenerate-OP_IM_EX Key Generate‡ CSNBKGN ON R
|| Random Number Generate CSNBRNG
|||||| X'0090' DESKeyTokenChange KeyTokenChange CSNBKTC ON R
|||||| X'00A0' ClearPINGenerate-3624 ClearPINGenerate CSNBPGN ON O
|||||| X'00A1' ClearPINGenerate-GBP ClearPINGenerate CSNBPGN ON O(Rel
| 4.1.0or
| later)
|||||| X'00A2' ClearPINGenerate-VISAPVV ClearPINGenerate CSNBPGN ON O(Rel
| 4.1.0or
| later)
|||||| X'00A3' ClearPINGenerate-Interbank ClearPINGenerate CSNBPGN ON O(Rel
| 4.1.-or
| later)
|||||| X'00A4' ClearPINGenerateAlternate-3624Offset ClearPINGenerateAlternate† CSNBCPA ON O
|||||| X'00AB' EncryptedPINVerify-3624 EncryptedPINVerify† CSNBPVR ON O
AppendixG.Accesscontrolpointsandverbs 517

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'00AC' EncryptedPINVerify-GBP EncryptedPINVerify† CSNBPVR ON O
|||||| X'00AD' EncryptedPINVerify-VISAPVV EncryptedPINVerify† CSNBPVR ON O
|||||| X'00AE' EncryptedPINVerify-Interbank EncryptedPINVerify† CSNBPVR ON O
|||||| X'00AF' ClearPINEncrypt ClearPINEncrypt CSNBCPE ON O
|||||| X'00B0' EncryptedPINGenerate-3624 EncryptedPINGenerate† CSNBEPG ON O
|||||| X'00B1' EncryptedPINGenerate-GBP EncryptedPINGenerate† CSNBEPG ON O
|||||| X'00B2' EncryptedPINGenerate-Interbank EncryptedPINGenerate† CSNBEPG ON O
|||||| X'00B3' EncryptedPINTranslate-Translate EncryptedPINTranslate† CSNBPTR ON O
|||||| X'00B7' EncryptedPINTranslate-Reformat EncryptedPINTranslate† CSNBPTR ON O
|||||| X'00BB' ClearPINGenerateAlternate-VISAPVV ClearPINGenerateAlternate† CSNBCPA ON O
|||||| X'00BC' PINChange/Unblock-changeEMVPIN PINChange/Unblock† CSNBPCU ON O
| withOPINENC
|||||| X'00BD' PINChange/Unblock-changeEMVPIN PINChange/Unblock† CSNBPCU ON O
| withIPINENC
|||||| X'00C3' ClearKeyImport/MultipleClearKeyImport Clear Key Import CSNBCKI ON SC
||| -DES Multiple Clear Key Import CSNBCKM
||||| X'00C4' SecureKeyImport-DES_OP Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
|| serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'00CD' ProhibitExport ProhibitExport CSNBPEX ON O
|||||| X'00D6' ControlVectorTranslate ControlVectorTranslate CSNBCVT ON SC
|||||| X'00D7' KeyGenerate-OPIM_OPEX_IMEX_etc. KeyGenerate‡ CSNBKGN ON SC,
|| extended SUP
|||||| X'00DA' CryptographicVariableEncipher CryptographicVariableEncipher CSNBCVE ON NRP,O,
| SUP
|||||| X'00DB' KeyGenerate-SINGLE-R Key Generate‡ CSNBKGN ON NR,SC
|| Remote Key Export‡ CSNDRKX
||||| X'00DC' SecureKeyImport-DES_IM Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
|| serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'00DF' GenerateCVV CVVGenerate CSNBCSG ON O
|||||| X'00E0' VerifyCVV CVVVerify CSNBCSV ON O
|||||| X'00E1' UKPT-PINVerify_PINTranslate Encrypted PIN Translate† CSNBPTR ON O
|| Encrypted PIN Verify† CSNBPVR
|||||| X'00E4' HMACGenerate-SHA-1 HMACGenerate CSNBHMG ON O(Rel
| 4.1.0or
| later)
|||||| X'00E5' HMACGenerate-SHA-224 HMACGenerate CSNBHMG ON O(Rel
| 4.1.0or
| later)
|||||| X'00E6' HMACGenerate-SHA-256 HMACGenerate CSNBHMG ON O(Rel
| 4.1.0or
| later)
|||||| X'00E7' HMACGenerate-SHA-384 HMACGenerate CSNBHMG ON O(Rel
| 4.1.0or
| later)
|||||| X'00E8' HMACGenerate-SHA-512 HMACGenerate CSNBHMG ON O(Rel
| 4.1.0or
| later)
518 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'00E9' RestrictKeyAttribute-ExportControl RestrictKeyAttribute CSNBRKA ON O(Rel
| 4.1.0or
| later)
|||||| X'00EA' KeyGenerate2-OP_EX_IM KeyGenerate2 CSNBKGN2 ON O(Rel
| 4.1or
| later)
|||||| X'00EB' KeyGenerate2-OPOP_OPIM_OPEX_etc. KeyGenerate2 CSNBKGN2 ON O(Rel
| 4.1.0or
| later)
|||||| X'00F0' SymmetricKeyTokenChange2 KeyTokenChange2 CSNBKTC2 ON O(Rel
| 4.1.0or
| later)
|||||| X'00F1' SymmetricKeyTokenChange2-RTCMK KeyTokenChange2 CSNBKTC2 ON O(Rel
| 4.1.0or
| later)
||||| X'00F2' SecureKeyImport2-HMAC_OP Note: ThisACPisincludedforTKEreferenceonly,the ON O(Rel
|| serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'00F4' SymmetricKeyImport2- SymmetricKeyImport CSNDSYI ON O(Rel
|| HMAC_PKCSOAEP 4.1.0or
| later)
|||||| X'00F5' SymmetricKeyExport- SymmetricKeyExport CSNDSYX ON O(Rel
|| HMAC_PKCSOAEP 4.1.0or
| later)
|||||| X'00F7' HMACVerify-SHA-1 HMACVerify CSNBHMV ON O(Rel
| 4.1.0or
| later)
|||||| X'00F8' HMACVerify-SHA-224 HMACVerify CSNBHMV ON O(Rel
| 4.1.0or
| later)
|||||| X'00F9' HMACVerify-SHA-256 HMACVerify CSNBHMV ON O(Rel
| 4.1or
| later)
|||||| X'00FA' HMACVerify-SHA-384 HMACVerify CSNBHMV ON O(Rel
| 4.1.0or
| later)
|||||| X'00FB' HMACVerify-SHA-512 HMACVerify CSNBHMV ON O(Rel
| 4.1.0or
| later)
|||||| X'0100' DigitalSignatureGenerate DigitalSignatureGenerate CSNDDSG ON O,SC
|||||| X'0101' DigitalSignatureVerify DigitalSignatureVerify CSNDDSV ON O
|||||| X'0102' PKAKeyTokenChangeRTCMK PKAKeyTokenChange CSNDKTC ON O
|||||| X'0103' PKAKeyGenerate PKAKeyGenerate† CSNDPKG ON O,SUP
|||||| X'0104' PKAKeyImport PKAKeyImport CSNDPKI ON O,SUP
|||||| X'0105' SymmetricKeyExport-DES_PKCS-1.2 SymmetricKeyExport CSNDSYX ON SC
|||||| X'0106' SymmetricKeyImport-DES_PKCS-1.2 SymmetricKeyImport† CSNDSYI ON O
|||||| X'0109' DataKeyImport DataKeyImport CSNBDKM ON O
|||||| X'010A' DataKeyExport DataKeyExport CSNBDKX ON O
||||| X'010B' SETBlockCompose Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
|| serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
AppendixG.Accesscontrolpointsandverbs 519

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
||||| X'010C' SETBlockDecompose Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
|| serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'010D' SymmetricKeyGenerate-DES_PKA92 SymmetricKeyGenerate† CSNDSYG ON SC
||||| X'0116' AccessControlManager-Readrole Note: ThisACPisincludedforreferenceonly.The ON (Rel
|| serviceimpactedisavailableonlyforIBMSystemx, 4.1.0or
|| IBMSystemp,orusingtheTKEinterface. later)
|||||| X'011E' PKAEncrypt PKAEncrypt CSNDPKE ON O,SEL
|||||| X'011F' PKADecrypt PKADecrypt CSNDPKD ON SC,
| SEL
||||| X'0121' SETBlockDecompose-PINExtension Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
||| IPINENC serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
||||| X'0122' SETBlockDecompose-PINExtension Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
||| OPINENC serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'0129' MultipleClearKeyImport/MultipleSecure MultipleClearKeyImport CSNBCKM ON SC
|| KeyImport-AES (Rel.
| 4.0or
| later)
|||||| X'012A' SymmetricAlgorithmEncipher-secureAES SymmetricAlgorithmEncipher† CSNBSAE ON O(Rel.
|| keys 4.0or
| later)
|||||| X'012B' SymmetricAlgorithmDecipher-secure SymmetricAlgorithmDecipher† CSNBSAD ON O(Rel.
|| AESkeys 4.0or
| later)
|||||| X'012C' SymmetricKeyGenerate-AES_ SymmetricKeyGenerate CSNDSYG ON SC
|| PKCSOAEP_PKCS-1.2 (Rel.
| 4.0or
| later)
|||||| X'012D' SymmetricKeyGenerate-AES_ SymmetricKeyGenerate CSNDSYG ON SC
|| ZERO-PAD (Rel.
| 4.0or
| later)
|||||| X'012E' SymmetricKeyImport-AES_ SymmetricKeyImport CSNDSYI ON O(Rel.
|| PKCSOAEP_PKCS-1.2 4.0or
| later)
|||||| X'012F' SymmetricKeyImport-AES_ZERO-PAD SymmetricKeyImport CSNDSYI ON O(Rel.
| 4.0or
| later)
|||||| X'0130' SymmetricKeyExport-AES_ SymmetricKeyExport CSNDSYX ON SC
|| PKCSOAEP_PKCS-1.2 (Rel.
| 4.0or
| later)
|||||| X'0131' SymmetricKeyExport-AES_ZERO-PAD SymmetricKeyExport CSNDSYX ON SC
| (Rel.
| 4.0or
| later)
||||| X'0139' Symmetrictokenwrapping-internal Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
||| enhancedmethod serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
||||| X'013A' Symmetrictokenwrapping-internaloriginal Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
||| method serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
520 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
||||| X'013B' Symmetrictokenwrapping-external Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
||| enhancedmethod serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
||||| X'013C' Symmetrictokenwrapping-external Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
||| originalmethod serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'013D' DiversifiedKeyGenerate-Allowwrapping DiversifiedKeyGenerate CSNBDKG ON O(Rel
|| overridekeywords 4.1.0or
| later)
|||||| X'013E' SymmetricKeyGenerate-Allowwrapping SymmetricKeyGenerate CSNDSYG ON O(Rel
|| overridekeywords 4.1.0or
| later)
|||||| X'0140' KeyPartImport-Allowwrappingoverride KeyPartImport CSNBKPI ON O(Rel
|| keywords 4.1.0or
| later)
|||||| X'0141' MultipleClearKeyImport-Allowwrapping MultipleClearKeyImport CSNBCKM ON O(Rel
|| overridekeywords 4.1.0or
| later)
|||||| X'0144' SymmetricKeyImport-Allowwrapping SymmetricKeyImport CSNDSYI ON O(Rel
|| overridekeywords 4.1.0or
| later)
|||||| X'0146' CKDSConversion2-Allowwrapping KeyTokenChange CSNBKTC ON (Rel
|| overridekeywords 4.1.0or
|| Note: TheTKEnameforthisACPrefersto later)
| z/OSkeystorage(CKDS).Howeverz/OS
| keystorageisnotimpacted.ThisACP
| referstoaserviceforLinux,seeverbfor
| details.
|||||| X'0147' CKDSConversion2-Convertfrom KeyTranslate2 CSNBKTR2 ON (Rel
|| enhancedtooriginal 4.1.0or
|| Note: TheTKEnameforthisACPrefersto later)
| z/OSkeystorage(CKDS).Howeverz/OS
| keystorageisnotimpacted.ThisACP
| referstoaserviceforLinux,seeverbfor
| details.
|||||| X'0149' KeyTranslate2 KeyTranslate2 CSNBKTR2 ON (Rel
| 4.1.0or
| later)
|||||| X'014A' KeyTranslate2-Allowwrappingoverride KeyTranslate2 CSNBKTR2 ON (Rel
|| keywords 4.1.0or
| later)
|||||| X'014B' KeyTranslate2-AllowuseofREFORMAT KeyTranslate2 CSNBKTR2 ON O(Rel
| 4.1.0or
| later)
|||||| X'014C' CKDSConversion2-Allowuseof KeyTokenChange CSNBKTC ON O(Rel
|| REFORMAT 4.1.0or
|| Note: TheTKEnameforthisACPrefersto later)
| z/OSkeystorage(CKDS).Howeverz/OS
| keystorageisnotimpacted.ThisACP
| referstoaserviceforLinux,seeverbfor
| details.
|||||| X'0203' RetainedKeyDelete RetainedKeyDelete CSNDRKD ON O,SEL
|||||| X'0204' PKAKeyGenerate-Clone PKAKeyGenerate† CSNDPKG ON O(Rel
| 4.1.0or
| later)
|||||| X'0205' PKAKeyGenerate-Clear PKAKeyGenerate† CSNDPKG ON O,SUP
AppendixG.Accesscontrolpointsandverbs 521

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'0230' RetainedKeyList RetainedKeyList CSNDRKL ON O
|||||| X'0235' SymmetricKeyImport-DES_PKA92KEK SymmetricKeyImport† CSNDSYI ON O
|||||| X'023C' SymmetricKeyGenerate-DES_ SymmetricKeyGenerate† CSNDSYG ON O,SC
| ZERO-PAD
|||||| X'023D' SymmetricKeyImport-DES_ZERO-PAD SymmetricKeyImport† CSNDSYI ON O,SC
|||||| X'023E' SymmetricKeyExport-DES_ZERO-PAD SymmetricKeyExport† CSNDSYX ON O,SC
|||||| X'023F' SymmetricKeyGenerate-DES_PKCS-1.2 SymmetricKeyGenerate† CSNDSYG ON O,SC
||||| X'0240' AuthorizeUDX Note: ThisACPisincludedforreferenceonly.The ON (Rel
|| serviceimpactedisavailableonlyforIBMSystemx, 4.1.0or
|| IBMSystemp,orusingtheTKEinterface. later)
|||||| X'0241' PKAKeyTokenChangeRTNMK PKAKeyTokenChange CSNDKTC ON O(Rel
| 4.1.0or
| later)
|||||| X'0273' SecureMessagingforKeys SecureMessagingforKeys CSNBSKY ON O
|||||| X'0274' SecureMessagingforPINs SecureMessagingforPINs CSNBSPN ON O
|||||| X'0275' DATAMKeyManagementControl Diversified Key Generate CSNBDKG ON O(Rel
||| Data Key Import CSNBDKM 4.1.0or
||| Data Key Export CSNBDKX later)
|| Key Export CSNBKEX
|| Key Generate CSNBKGN
|| Key Import CSNBKIM
|||||| X'0276' KeyExport-Unrestricted KeyExport CSNBKEX ON O,SC
|||||| X'0277' DataKeyExport-Unrestricted DataKeyExport CSNBDKX ON O,SC
|||||| X'0278' KeyPartImport-ADD-PART KeyPartImport† CSNBKPI ON SC,
| SEL
|||||| X'0279' KeyPartImport-COMPLETE KeyPartImport† CSNBKPI ON SC,
| SEL
|||||| X'027A' KeyPartImport-Unrestricted KeyPartImport CSNBKPI ON O,SC
|||||| X'027B' KeyImport-Unrestricted KeyImport CSNBKIM ON O,SC
|||||| X'027C' DataKeyImport-Unrestricted DataKeyImport CSNBDKM ON O,SC
|||||| X'027D' PKAKeyGenerate-PermitRegeneration PKAKeyGenerate† CSNDPKG ON O,NRP,
|| Data SC
|||||| X'027E' PKAKeyGenerate-PermitRegeneration PKAKeyGenerate† CSNDPKG ON O,NRP,
|| DataRetain SC
|||||| X'0290' DiversifiedKeyGenerate-DKYGENKY- Diversified Key Generate‡ CSNBDKG OFF O,SC
||| DALL PIN Change/Unblock‡ CSNBPCU
|||||| X'0291' TransactionValidation-Generate TransactionValidation† CSNBTRV ON O,SEL
|||||| X'0292' TransactionValidation-VerifyCSC-3 TransactionValidation† CSNBTRV ON O
|||||| X'0293' TransactionValidation-VerifyCSC-4 TransactionValidation† CSNBTRV ON O
|||||| X'0294' TransactionValidation-VerifyCSC-5 TransactionValidation† CSNBTRV ON O
|||||| X'0295' SymmetricKeyEncipher/Decipher- EnablesCPACFkeytranslationfor N/A ON O
|| EncryptedDESkeys DESkeys.
|||||| X'0296' SymmetricKeyEncipher/Decipher- EnablesCPACFkeytranslationfor N/A ON O
|| EncryptedAESkeys AESkeys.
|||||| X'0297' KeyPartImport2-Loadfirstkeypart_ KeyPartImport2 CSNBKPI2 ON O(Rel
|| require3keyparts 4.1.0or
| later)
|||||| X'0298' KeyPartImport2-Loadfirstkeypart_ KeyPartImport2 CSNBKPI2 ON O(Rel
|| require2keyparts 4.1.0or
| later)
522 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'0299' KeyPartImport2-Loadfirstkeypart_ KeyPartImport2 CSNBKPI2 ON O(Rel
|| require1keyparts 4.1.0or
| later)
|||||| X'029A' KeyPartImport2-Addsecondof3ormore KeyPartImport2 CSNBKPI2 ON O(Rel
|| keyparts 4.1.0or
| later)
|||||| X'029B' KeyPartImport2-Addlastrequiredkey KeyPartImport2 CSNBKPI2 ON O(Rel
|| part 4.1.0or
| later)
|||||| X'029C' KeyPartImport2-Addoptionalkeypart KeyPartImport2 CSNBKPI2 ON O(Rel
| 4.1.0or
| later)
|||||| X'029D' KeyPartImport2-Completekey KeyPartImport2 CSNBKPI2 ON SEL(Rel
| 4.1.0or
| later)
|||||| X'0300' NOCVKEKusageforexport-related Data Key Export CSNBDKX ON O(Rel
|||| functions Key Export CSNBKEX 4.1.0or
||| Key Generate CSNBKGN later)
|| Remote Key Export CSNDRKX
|
|||||| X'0301' ProhibitExportExtended ProhibitExportExtended CSNBPEXX ON O
||||| X'0303' PCFCKDSconversionutility Note: ThisACPisincludedforTKEreferenceonly,the ON (Rel
|| serviceimpactedisavailableonly(forIBMSystemz)on 4.1.0or
|| z/OS. later)
|||||| X'0309' KeyPartImport-RETRKPR KeyPartImport CSNBKPI ON O(Rel
| 4.1.0or
| later)
|||||| X'030A' NOCVKEKusageforimport-related Data Key Import CSNBDKM ON O(Rel
|||| functions Key Import CSNBKIM 4.1.0or
||| Key Generate CSNBKGN later)
|| Remote Key Export CSNDRKX
|||||| X'030C' DSGZERO-PADunrestrictedhashlength DigitalSignatureGenerate CSNDDSG OFF O,SC
|||||| X'030F' TrustedBlockCreate-CreateaTrusted TrustedBlockCreate CSNDTBC ON O,SUP
|| KeyBlockinInactiveform (Rel.
| 4.0or
| later)
|||||| X'0310' TrustedBlockCreate-ActivateanInactive TrustedBlockCreate CSNDTBC ON O,SUP
|| TrustedKeyBlock (Rel.
| 4.0or
| later)
|||||| X'0311' PKAKeyImport-ImportanExternal PKAKeyImport CSNDPKI ON O,SEL
|| TrustedKeyBlocktointernalform (Rel.
| 4.0or
| later)
|||||| X'0312' RemoteKeyExport-Generateorexporta RemoteKeyExport CSNDRKX ON O,SEL
|| keyforusebyanon-CCAnode (Rel.
| 4.0or
| later)
|||||| X'0313' PTREnhancedPINSecurity Clear PIN Generate Alternate CSNBCPA OFF O,SC,
||| Clear PIN Encrypt CSNBCPE SEL
||| Encrypted PIN Generate CSNBEPG (Rel.
||| Encrypted PIN Translate CSNBPTR 4.0or
||| Encrypted PIN Verify CSNBPVR later)
|| PIN Change/Unblock CSNBPCU
AppendixG.Accesscontrolpointsandverbs 523

| Table159.AccessControlPointsandcorrespondingCCAverbs (continued)
|||||| ACP NameofACPfromTKEinterface Verbname Entrypoint Initial Usage
|| number setting
| (hex)
|||||| X'0318' PKAKeyTranslate-fromCCARSAtoSC PKAKeyTranslate CSNDPKT ON O(Rel.
|| VisaFormat 4.0or
| later)
|||||| X'0319' PKAKeyTranslate-fromCCARSAtoSC PKAKeyTranslate CSNDPKT ON O(Rel.
|| MEFormat 4.0or
| later)
|||||| X'031A' PKAKeyTranslate-fromCCARSAtoSC PKAKeyTranslate CSNDPKT ON O(Rel.
|| CRTFormat 4.0or
| later)
|||||| X'031B' PKAKeyTranslate-fromsourceEXPKEK PKAKeyTranslate CSNDPKT ON O(Rel.
|| totargetEXPKEK 4.0or
| later)
|||||| X'031C' PKAKeyTranslate-fromsourceIMPKEK PKAKeyTranslate CSNDPKT ON O(Rel.
|| totargetEXPKEK 4.0or
| later)
|||||| X'031D' PKAKeyTranslate-fromsourceIMPKEK PKAKeyTranslate CSNDPKT ON O(Rel.
|| totargetIMPKEK 4.0or
| later)
|||||| X'0350' ANSIX9.8PIN-EnforcePINblock Clear PIN Generate Alternate CSNBCPA OFF O,R
|||| restrictions Encrypted PIN Translate CSNBPTR (Rel
||| Secure Messaging for PINs CSNBSPN 4.1.0or
| later)
|||||| X'0351' ANSIX9.8PIN-Allowmodificationof Encrypted PIN Translate CSNBPTR OFF O,SC
|||| PAN_01_0350 Secure Messaging for PINs CSNBSPN (Rel
| 4.1.0or
| later)
|||||| X'0352' ANSIX9.8PIN-AllowonlyANSIPIN Encrypted PIN Translate CSNBPTR OFF O,SC
|||| blocks_01_0350 Secure Messaging for PINs CSNBSPN (Rel
| 4.1.0or
| later)
| Thefollowingcodesareusedinthistable:
|| ID Initialdefault.
|| O Usageofthiscommandisoptional;enableitasrequiredforauthorizedusage.
|| R Enablingthiscommandisrecommended.
|| NR Enablingthiscommandisnotrecommended.
|| NRP Enablingthiscommandisnotrecommendedforproduction.
|| SC Usageofthiscommandrequiresspecialconsideration.
|| SEL Usageofthiscommandisnormallyrestrictedtooneormoreselectedroles.
|| SUP Thiscommandisnormallyrestrictedtooneormoresupervisoryroles.
|| † Thisverbperformsmorethanonefunction,asdeterminedbythekeywordintherule_arrayparameteroftheverbcall.
| Notallfunctionsoftheverbrequirethecommandinthisrow.
|| ‡ Thisverbdoesnotalwaysrequirethecommandinthisrow.Useasdeterminedbythecontrolvectorforthekeyandthe
| actionbeingperformed.
|
524 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

|
TKE Version 6.0 and higher
The TKE workstation allows you to enable or disable verb access control points. For systems that do not
use the optional TKE workstation, most access control points (current and new) are enabled in the
DEFAULT Role with the appropriate licensed internal code on the CEX3C. For more information about the
TKE workstation, see z/OS Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation User’s
Guide.
| You must have a TKE V6.0 or higher workstation in order to see supported CEX3C features. They are not
| seen when using earlier TKE workstations. TKE Version 4.0 through TKE Version 6.0 can access CEX2C
| features.
Use of particular cryptographic or key management verb functions with the CEX3C are controlled through
access control points. Most of these are enabled in the DEFAULT role.
New TKE users and non-TKE users have almost all access control points enabled.
Note: Access control points DKYGENKY-DALLand DSG ZERO-PAD unrestricted hash length are always
disabled in the DEFAULT role for all customers (TKE and non-TKE).ATKE workstation is required
to enable these access control points.
| For CCARelease 4.1.0, there are new access control points for these verbs:
| v Clear PIN GenerateAlternate (CSNBCPA) - EnforceANSI X9.8 PIN Rules (offset X'0350')
| v Encrypted PIN Translate (CSNBPTR)
| – ANSI X9.8 PIN - Enforce PIN block restrictions (offset X'0350')
| – ANSI X9.8 PIN -Allow modification of PAN_01_0350 (offset X'0351')
| – ANSI X9.8 PIN -Allow onlyANSI PIN blocks_01_0350 (offset X'0352')
| v Secure Messaging for PINs (CSNBSPN)
| – ANSI X9.8 PIN - Enforce PIN block restrictions (offset X'0350')
| – ANSI X9.8 PIN -Allow modification of PAN_01_0350 (offset X'0351')
| – ANSI X9.8 PIN -Allow onlyANSI PIN blocks_01_0350 (offset X'0352')
AppendixG.Accesscontrolpointsandverbs 525

526 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix H. Sample verb call routines
| This appendix contains sample verb call routines for both C and Java.
IMPORTANT
The user must load the Symmetric Master Key before the verb calls will complete successfully,
otherwise return code 12 reason code 764 will be returned.
To illustrate the practical application of CCAverb calls, this appendix describes the sample routines
included with the RPM.Asample in C, and one in Java is included.
The sample routines generate a MessageAuthentication Code (MAC) on a text string, and then verifies
the MAC. To accomplish this, the routine:
v Calls the Key Generate (CSNBKGN or CSNBKGNJ) verb to create a MAC/MACVER key pair.
v Calls the MAC Generate (CSNBMGN or CSNBMGNJ) verb to generate a MAC on a text string with the
MAC key.
v Calls the MAC Verify (CSNBMVR or CSNBMVRJ) verb to verify the text string MAC with the MACVER
key.
As you review the sample routines shown in Figure34 on page 528 and Figure35 on page 533, refer to
the chapters in this book for descriptions of the called verbs and their parameters. These verbs are listed
in Table160.
Table160.Verbscalledbythesampleroutines
Verb EntrypointnameforCandJavaversions
KeyGenerate CSNBKGNorCSNBKGNJ
MACGenerate CSNBMGNorCSNBMGNJ
MACVerify CSNBMVRorCSNBMVRJ
Sample program in C
This sample code, which consists of a C program (mac.c) and a makefile (makefile.Inx), can be found in
the /opt/IBM/CEX3C/samples directory. For reference, a copy of the sample routine is shown in Figure34
on page 528.
©CopyrightIBMCorp.2007,2011 527

/*********************************************************************/
/* */
/* Module Name: mac.c */
/* */
/* DESCRIPTIVE NAME: Cryptographic Coprocessor Support Program */
/* C language source code example */
/* */
/*-------------------------------------------------------------------*/
/* */
/* Licensed Materials - Property of IBM */
/* */
/* (C) Copyright IBM Corp. 1997-2001 All Rights Reserved */
/* */
/* US Government Users Restricted Rights - Use duplication or */
/* disclosure restricted by GSA ADP Schedule Contract with IBM Corp. */
/* */
/*-------------------------------------------------------------------*/
/* */
/* NOTICE TO USERS OF THE SOURCE CODE EXAMPLES */
/* */
/* The source code examples provided by IBM are only intended to */
/* assist in the development of a working software program. The */
/* source code examples do not function as written: additional */
/* code is required. In addition, the source code examples may */
/* not compile and/or bind successfully as written. */
/* */
/* International Business Machines Corporation provides the source */
/* code examples, both individually and as one or more groups, */
/* "as is" without warranty of any kind, either expressed or */
/* implied, including, but not limited to the implied warranties of */
/* merchantability and fitness for a particular purpose. The entire */
/* risk as to the quality and performance of the source code */
/* examples, both individually and as one or more groups, is with */
/* you. Should any part of the source code examples prove defective, */
/* you (and not IBM or an authorized dealer) assume the entire cost */
/* of all necessary servicing, repair or correction. */
/* */
/* IBM does not warrant that the contents of the source code */
/* examples, whether individually or as one or more groups, will */
/* meet your requirements or that the source code examples are */
/* error-free. */
/* */
/* IBM may make improvements and/or changes in the source code */
/* examples at any time. */
/* */
/* Changes may be made periodically to the information in the */
/* source code examples; these changes may be reported, for the */
/* sample code included herein, in new editions of the examples. */
/* */
/* References in the source code examples to IBM products, programs, */
/* or services do not imply that IBM intends to make these */
/* available in all countries in which IBM operates. Any reference */
/* to the IBM licensed program in the source code examples is not */
/* intended to state or imply that IBM’s licensed program must be */
/* used. Any functionally equivalent program may be used. */
/* */
Figure34.Syntax,sampleroutineinC(Part1of4)
528 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

/*-------------------------------------------------------------------*/
/* */
/* This example program: */
/* */
/* 1) Calls the Key_Generate verb (CSNBKGN) to create a MAC (message */
/* authentication code) key token and a MACVER key token. */
/* */
/* 2) Calls the MAC_Generate verb (CSNBMGN) using the MAC key token */
/* from step 1 to generate a MAC on the supplied text string */
/* (INPUT_TEXT). */
/* */
/* 3) Calls the MAC_Verify verb (CSNBMVR) to verify the MAC for the */
/* same text string, using the MACVER key token created in */
/* step 1. */
/* */
/*********************************************************************/
#include <studio.h>
#include <string.h>
#ifdef _AIX
#include <csufincl.h>
#elif __WINDOWS__
#include "csunincl.h"
#else
#include "csulincl.h" /* else linux */
#endif
/* Defines */
#define KEY_FORM "OPOP"
#define KEY_LENGTH "SINGLE "
#define KEY_TYPE_1 "MAC "
#define KEY_TYPE_2 "MACVER "
#define INPUT_TEXT "abcdefhgijklmn0987654321"
#define MAC_PROCESSING_RULE "X9.9-1 "
#define SEGMENT_FLAG "ONLY "
#define MAC_LENGTH "HEX-9 "
#define MAC_BUFFER_LENGTH 10
void main()
{
static long return_code;
static long reason_code;
static unsigned char key_form[4];
static unsigned char key_length[8];
static unsigned char mac_key_type[8];
static unsigned char macver_key_type[8];
static unsigned char kek_key_id_1[64];
static unsigned char kek_key_id_2[64];
static unsigned char mac_key_id[64];
static unsigned char macver_key_id[64];
static long text_length;
static unsigned char text[26];
static long rule_array_count;
static unsigned char rule_array[3][8]; /* Max 3 rule array elements */
static unsigned char chaining_vector[18];
static unsigned char mac_value[MAC_BUFFER_LENGTH];
/* Print a banner */
printf("Cryptographic Coprocessor Support Program example program.\n");
Figure34.Syntax,sampleroutineinC(Part2of4)
AppendixH.Sampleverbcallroutines 529

/* Set up initial values for Key_Generate call */
return_code = 0;
reason_code = 0;
memcpy (key_form, KEY_FORM, 4); /* OPOP key pair */
memcpy (key_length, KEY_LENGTH, 8); /* Single-length keys */
memcpy (mac_key_type, KEY_TYPE_1, 8); /* 1st token, MAC key type */
memcpy (macver_key_type, KEY_TYPE_2, 8); /* 2nd token, MACVER key type */
memset (kek_key_id_1, 0x00, sizeof(kek_key_id_1)); /* 1st KEK not used */
memset (kek_key_id_2, 0x00, sizeof(kek_key_id_2)); /* 2nd KEK not used */
memset (mac_key_id, 0x00, sizeof(mac_key_id)); /* Init 1st key token */
memset (macver_key_id, 0x00, sizeof(macver_key_id)); /* Init 2nd key token */
/* Generate a MAC/MACVER operational key pair */
CSNBKGN(&return_code,
&reason_code,
NULL, /* exit_data_length */
NULL, /* exit_data */
key_form,
key_length,
mac_key_type,
macver_key_type,
kek_key_id_1,
kek_key_id_2,
mac_key_id,
macver_key_id);
/* Check the return/reason codes. Terminate if there is an error. */
if (return_code != 0 || reason_code != 0) {
printf ("Key_Generate failed: "); /* Print failing verb */
printf ("return_code = %ld, ", return_code); /* Print return code */
printf ("reason_code = %ld.\n", reason_code); /* Print reason code */
return;
}
else
printf ("Key_Generate successful.\n");
/* Set up initial values for MAC_Generate call */
return_code = 0;
reason_code = 0;
text_length = sizeof (INPUT_TEXT) - 1; /* Length of MAC text */
memcpy (text, INPUT_TEXT, text_length); /* Define MAC input text */
rule_array_count = 3; /* 3 rule array elements */
memset (rule_array, ’ ’, sizeof(rule_array)); /* Clear rule array */
memcpy (rule_array[0], MAC_PROCESSING_RULE, 8); /* 1st rule array element */
memcpy (rule_array[1], SEGMENT_FLAG, 8); /* 2nd rule array element */
memcpy (rule_array[2], MAC_LENGTH, 8); /* 3rd rule array element */
memset (chaining_vector, 0x00, 18); /* Clear chaining vector */
memset (mac_value, 0x00, sizeof(mac_value)); /* Clear MAC value */
Figure34.Syntax,sampleroutineinC(Part3of4)
530 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

/* Generate a MAC based on input text */
CSNBMGN ( &return_code,
&reason_code,
NULL, /* exit_data_length */
NULL, /* exit_data */
mac_key_id, /* Output from Key Generate */
&text_length,
text,
&rule_array_count,
&rule_array[0][0],
chaining_vector,
mac_value);
/* Check the return/reason codes. Terminate if there is an error. */
if (return_code != 0 || reason_code != 0) {
printf ("MAC Generate Failed: "); /* Print failing verb */
printf ("return_code = %ld, ", return_code); /* Print return code */
printf ("reason_code = %ld.\n", reason_code); /* Print reason code */
return;
}
else {
printf ("MAC_Generate successful.\n");
printf ("MAC_value = %s\n", mac_value); /* Print MAC value (HEX-9) */
}
/* Set up initial values for MAC_Verify call */
return_code = 0;
reason_code = 0;
rule_array_count = 1; /* 1 rule array element */
memset (rule_array, ’ ’, sizeof(rule_array));/* Clear rule array */
memcpy (rule_array[0], MAC_LENGTH, 8); /* Rule array element */
/* (use default Ciphering */
/* Method and Segmenting */
/* Control) */
memset (chaining_vector, 0x00, 18); /* Clear the chaining vector */
/* Verify MAC value */
CSNBMVR (&return_code,
&reason_code,
NULL, /* exit_data_length */
NULL, /* exit_data */
macver_key_id, /* Output from Key_Generate */
&text_length, /* Same as for MAC_Generate */
text, /* Same as for MAC_Generate */
&rule_array_count,
&rule_array[0][0],
chaining_vector,
mac_value); /* Output from MAC_Generate */
/* Check the return/reason codes. Terminate if there is an error. */
if (return_code != 0 || reason_code != 0) {
printf ("MAC_Verify failed: "); /* Print failing verb */
printf ("return_code = %ld, ", return_code); /* Print return code */
printf ("reason_code = %ld.\n", reason_code); /* Print reason code */
return;
}
else /* No error occurred */
printf ("MAC_Verify successful.\n");
}
Figure34.Syntax,sampleroutineinC(Part4of4)
AppendixH.Sampleverbcallroutines 531

Sample program in Java
Before running this program, review the information about the JNI interface in “Building Java applications
to use with the CCAJNI” on page 16.
This sample code consists of a Java program named mac.java. For reference, a copy of the sample
routine is shown in Figure35 on page 533.Another sample program named RNG.java is included with the
distribution at the same location, but is not copied here because it is a very simple JNI reference exercise
to call the Random Number Generate verb.
The default distribution location of the sample code is:
Operating system Default distribution location
Novell SUSE Linux /opt/IBM/CEX3C/samples
Red Hat Linux /opt/IBM/CEX3C/samples
Invoke the following command from the directory that contains the sample source code to compile the
program:
javac -classpath /opt/IBM/CEX3C/cnm/HIKM.zip mac.java
Notes:
1. The classpath option points to the HIKM.zip file because the hikmNativeInteger class is in this file.
2. The path shown for the HIKM.zip file is the default distribution location of that file.
When it is compiled, you can run the sample Java program from the directory that contains the compiled
output, with these commands.
For a Red Hat Linux system:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64
/opt/ibm/java-i386-60/jre/bin/java -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:. mac
For a Novell SUSE Linux system:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64
java -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:. mac
Notes:
1. The path shown for the HIKM.zip file is the default distribution location of that file.
2. The libcsulcca.so library for Linux also contains the C support for the CCAJava Native Interface (JNI).
532 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

/*********************************************************************/
/* */
/* Module Name: mac.java */
/* */
/* DESCRIPTIVE NAME: Cryptographic Coprocessor Support Program */
/* JNI example code */
/* */
/*-------------------------------------------------------------------*/
/* */
/* Licensed Materials - Property of IBM */
/* */
/* Copyright IBM Corp. 2010 All Rights Reserved */
/* */
/* US Government Users Restricted Rights - Use duplication or */
/* disclosure restricted by GSA ADP Schedule Contract with IBM Corp. */
/* */
/*-------------------------------------------------------------------*/
/* */
/* NOTICE TO USERS OF THE SOURCE CODE EXAMPLES */
/* */
/* The source code examples provided by IBM are only intended to */
/* assist in the development of a working software program. The */
/* source code examples do not function as written: additional */
/* code is required. In addition, the source code examples may */
/* not compile and/or bind successfully as written. */
/* */
/* International Business Machines Corporation provides the source */
/* code examples, both individually and as one or more groups, */
/* "as is" without warranty of any kind, either expressed or */
/* implied, including, but not limited to the implied warranties of */
/* merchantability and fitness for a particular purpose. The entire */
/* risk as to the quality and performance of the source code */
/* examples, both individually and as one or more groups, is with */
/* you. Should any part of the source code examples prove defective, */
/* you (and not IBM or an authorized dealer) assume the entire cost */
/* of all necessary servicing, repair or correction. */
/* */
/* IBM does not warrant that the contents of the source code */
/* examples, whether individually or as one or more groups, will */
/* meet your requirements or that the source code examples are */
/* error-free. */
/* */
/* IBM may make improvements and/or changes in the source code */
/* examples at any time. */
/* */
/* Changes may be made periodically to the information in the */
/* source code examples; these changes may be reported, for the */
/* sample code included herein, in new editions of the examples. */
/* */
/* References in the source code examples to IBM products, programs, */
/* or services do not imply that IBM intends to make these */
/* available in all countries in which IBM operates. Any reference */
/* to the IBM licensed program in the source code examples is not */
/* intended to state or imply that IBM’s licensed program must be */
/* used. Any functionally equivalent program may be used. */
Figure35.Syntax,sampleroutineinJava(Part1of4)
AppendixH.Sampleverbcallroutines 533

/*-------------------------------------------------------------------*/
/* */
/* This example program: */
/* */
/* 1) Calls the Key_Generate verb (CSNBKGNJ) to create a MAC (message*/
/* authentication code) key token and a MACVER key token. */
/* */
/* 2) Calls the MAC_Generate verb (CSNBMGNJ) using the MAC key token */
/* from step 1 to generate a MAC on the supplied text string */
/* (INPUT_TEXT). */
/* */
/* 3) Calls the MAC_Verify verb (CSNBMVRJ) to verify the MAC for the */
/* same text string, using the MACVER key token created in */
/* step 1. */
/* */
/*********************************************************************/
import java.io.*;
public class mac
{
static final String KEY_FORM = "OPOP";
static final String KEY_LENGTH = "SINGLE ";
static final String KEY_TYPE_1 = "MAC ";
static final String KEY_TYPE_2 = "MACVER ";
static final String INPUT_TEXT = "abcdefhgijklmnopqrstuvwx";
static final String MAC_PROCESSING_RULE = "X9.9-1 ";
static final String SEGMENT_FLAG = "ONLY ";
static final String MAC_LENGTH = "HEX-9 ";
public static void main (String args[])
{
byte [] ByteExitData = new byte [4];
byte [] Byte_key_form = new byte [4];
byte [] Byte_key_length = new byte [8];
byte [] Byte_mac_key_type = new byte [8];
byte [] Byte_macver_key_type = new byte [8];
byte [] Byte_mac_value = new byte [10];
byte [] Byte_chaining_vector = new byte [18];
byte [] Byte_rule_array = new byte [24];
byte [] Byte_text = new byte [26];
byte [] Byte_kek_key_id_1 = new byte [64];
byte [] Byte_kek_key_id_2 = new byte [64];
byte [] Byte_mac_key_id = new byte [64];
byte [] Byte_macver_key_id = new byte [64];
try
{
//setup to pause on non-zero return/reason code
//and require enter key to continue
BufferedReader stdin = new BufferedReader(new InputStreamReader(System.in));
hikmNativeInteger IntReturncode = new hikmNativeInteger(0);
hikmNativeInteger IntReasoncode = new hikmNativeInteger(0);
hikmNativeInteger IntExitDataLength = new hikmNativeInteger(0);
/* Print beginning banner */
System.out.println("\nCryptographic Coprocessor Support Program JAVA example program.\n");
Figure35.Syntax,sampleroutineinJava(Part2of4)
534 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

/* Set up initial values for Key_Generate call */
Byte_key_form = new String(KEY_FORM).getBytes(); /* OPOP key pair */
Byte_key_length = new String(KEY_LENGTH).getBytes();/* Single-length keys */
Byte_mac_key_type = new String(KEY_TYPE_1).getBytes();/* 1st token, MAC key type */
Byte_macver_key_type = new String(KEY_TYPE_2).getBytes();/* 2nd token, MACVER key type */
/* Generate a MAC/MACVER operational key pair */
new HIKM().CSNBKGNJ (IntReturncode,
IntReasoncode,
IntExitDataLength,
ByteExitData,
Byte_key_form,
Byte_key_length,
Byte_mac_key_type,
Byte_macver_key_type,
Byte_kek_key_id_1,
Byte_kek_key_id_2,
Byte_mac_key_id,
Byte_macver_key_id);
if ( 0 != IntReturncode.getValue() || 0 != IntReasoncode.getValue() )
{
System.out.println ("\nKey Generate Failed"); /* Print failing verb. */
System.out.println ("Return_code = " + IntReturncode.getValue()); /* Print return code. */
System.out.println ("Reason_code = " + IntReasoncode.getValue()); /* Print reason code. */
System.out.println ("Press ENTER to continue..."); /* Print Pause message */
stdin.readLine();
}
else
{
System.out.println ("Key_Generate successful.");
}
/* Set up initial values for MAC_Generate call */
IntReturncode = new hikmNativeInteger(0);
IntReasoncode = new hikmNativeInteger(0);
IntExitDataLength = new hikmNativeInteger(0);
hikmNativeInteger Int_rule_array_count = new hikmNativeInteger(3);
hikmNativeInteger Int_text_length = new hikmNativeInteger(24);
Byte_text = new String (INPUT_TEXT).getBytes(); /*Define MAC input text */
byte [] temp_array = new String (MAC_PROCESSING_RULE).getBytes(); /*1st rule array element*/
System.arraycopy( temp_array, 0, Byte_rule_array, 0, temp_array.length); /*1st rule array element*/
temp_array = new String(SEGMENT_FLAG).getBytes(); /*2nd rule array element*/
System.arraycopy( temp_array, 0, Byte_rule_array, 8, temp_array.length); /*2nd rule array element*/
temp_array = new String(MAC_LENGTH).getBytes(); /*3rd rule array element*/
System.arraycopy( temp_array, 0, Byte_rule_array, 16, temp_array.length);/*3rd rule array element*/
/* Generate a MAC based on input text */
new HIKM().CSNBMGNJ (IntReturncode,
IntReasoncode,
IntExitDataLength,
ByteExitData,
Byte_mac_key_id,
Int_text_length,
Byte_text,
Int_rule_array_count,
Byte_rule_array,
Byte_chaining_vector,
Byte_mac_value);
Figure35.Syntax,sampleroutineinJava(Part3of4)
AppendixH.Sampleverbcallroutines 535

if ( 0 != IntReturncode.getValue() || 0 != IntReasoncode.getValue() )
{
System.out.println ("\nMAC Generate Failed"); /* Print failing verb. */
System.out.println ("Return_code = " + IntReturncode.getValue()); /* Print return code. */
System.out.println ("Reason_code = " + IntReasoncode.getValue()); /* Print reason code. */
System.out.println ("Press ENTER to continue..."); /* Print Pause message */
stdin.readLine();
}
else
{
System.out.println ("MAC_Generate successful.");
System.out.println ("MAC_value = [" + new String(Byte_mac_value) + "]");
}
/* Set up initial values for MAC_Verify call */
IntReturncode = new hikmNativeInteger(0);
IntReasoncode = new hikmNativeInteger(0);
IntExitDataLength = new hikmNativeInteger(0);
Byte_rule_array = new String (MAC_LENGTH).getBytes(); /* Rule array element */
Int_rule_array_count = new hikmNativeInteger(1);
new HIKM().CSNBMVRJ (IntReturncode,
IntReasoncode,
IntExitDataLength,
ByteExitData,
Byte_macver_key_id,
Int_text_length,
Byte_text,
Int_rule_array_count,
Byte_rule_array,
Byte_chaining_vector,
Byte_mac_value);
if ( 0 != IntReturncode.getValue() || 0 != IntReasoncode.getValue() )
{
System.out.println ("\nMAC_Verify Failed"); /* Print failing verb. */
System.out.println ("Return_code = " + IntReturncode.getValue()); /* Print return code. */
System.out.println ("Reason_code = " + IntReasoncode.getValue()); /* Print reason code. */
System.out.println ("Press ENTER to continue..."); /* Print Pause message */
stdin.readLine();
}
else
{
System.out.println ("MAC_Verify successful.");
}
}
catch (Exception anException)
{
System.out.println(anException);
}
/* Print ending banner */
System.out.println("\nCryptographic Coprocessor Support Program JAVA example program finished.\n");
}//end main
}//end mac class
Figure35.Syntax,sampleroutineinJava(Part4of4)
536 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix I. Initial system set up tips
This appendix contains tips to help you set up your system for the first time.
| The name of the CCA4.1.0 RPM is: csulcca-4.1.0-maintenance level.s390x.rpm, where maintenance
| level is a number representing the current maintenance level.
| In order to use the full set of CCARelease 4.1.0 functions, a CEX3C feature is required. This feature must
| have a CCAcode level of 4.1.0 for RPM platform target s390x. This CEX3C feature is available with IBM
| System z10 model GA3 and higher models.Alimited set of CCARelease 4.1.0 and 4.0.0 functions can be
| used with a CEX2C feature.
Consult the README.linz file in the /opt/IBM/CEX3C/doc/ directory for this information:
v Release-specific information, if there is any
v Pointers to helpful tools
Installing and loading the cryptographic device driver
The cryptographic device driver 'zcrypt' is already included in the regular kernel package shipped with your
Linux distribution. The cryptographic device driver is provided as a single kernel module named z90crypt.
For information on how to load and configure the cryptographic device driver refer to the documentation
provided with your Linux distribution, and Device Drivers, Features, and Commands, SC33-8411. Because
there are some versions of this book that are for a specific Linux kernel, make sure that you refer to the
book that goes with your specific Linux kernel level.
| Note: Unload of the device driver is complicated slightly because the catcher.exe daemon is always
| running, to be ready to receive TKE requests. Unloading the device driver normally or in
| preparation for a reload requires stopping the catcher.exe daemon. This can be done with the
| service management script /etc/init.d/CSUTKEcat using the 'stop' argument, or by using the 'ps'
| command to find the PID for the daemon, and then using the 'kill -9 <PID>'command to kill it.
| After reloading the device driver (using modprobe or other method) you may restart the catcher.exe
| daemon (re-enabling TKE access) using the '/etc/init.d/CSUTKEcat start' command.
zcrypt device driver usage
The zcrypt driver supports kernel parameter:
domain
An integer argument that sets the domain index forAP devices. If not set or set to -1, the domain
index with the maximum number of devices will be used. You have to make sure that the selected
domain contains at least one CEX3C adapter.
The poll_thread parameter is no longer used. If you are running Linux in an LPAR on an IBM System z10
EC or later,AP interrupts are used instead of the polling thread. The polling thread is disabled whenAP
interrupts are available.
Depending on the Linux distribution being used, it is possible to display zcrypt information using the
lszcrypt command.Also, the chzcrypt command enables and disables the cryptographic cards. See Device
Drivers, Features, and Commands, SC33-8411. Because there are some versions of this book that are for
a specific Linux kernel, make sure that you refer to the book that goes with your specific Linux kernel
level.
©CopyrightIBMCorp.2007,2011 537

High resolution polling timer
The zcrypt driver can run with or without the polling thread. When running with the polling thread, one
CPU without an outstanding workload is constantly polling the cryptographic cards for finished
cryptographic requests. The polling thread sleeps when no cryptographic requests are being processed.
This mode utilizes the cryptographic cards as much as possible at the cost of blocking one CPU. Without
the polling thread, the cryptographic cards are polled at a much lower rate. This could result in higher
latency and reduced throughput for cryptographic requests.
The high resolution polling timer is available for some Linux distributions. This timer can be used to set the
polling frequency to be larger than 100 Hz. See the chzcrypt command in Device Drivers, Features, and
Commands, SC33-8411. Be aware that setting a value larger than 100 Hz is not valid ifAP interrupts are
used.
The sysfs interface
The zcrypt cryptographic driver utilizes the device model introduced with the Linux 2.6 kernel series. It
introduces a new bus named "AP" which can be found under /sys/bus/ap.
The following attributes are defined atAP bus level:
/sys/bus/ap/ap_domain Read-only attribute representing the domain index used for allAP devices.
/sys/bus/ap/ap_interrupts Read-only attribute indicating whetherAP adapter interrupts are used.A
value of 1 means thatAP adapter interrupts are used.Avalue of 0 means
that they are not used.
/sys/bus/ap/config_time Read-write attribute representing the interval in seconds for re-scanning
theAP bus for new or gone devices.
/sys/bus/ap/drivers_autoprobe
This attribute controls whether a bus can bind devices by default,
indicated by a value of 1. If not (value of 0), the bus initializes the device
and does nothing else.
/sys/bus/ap/drivers_probe This attribute controls whether a bus (its ID is given as input) can attempt
to bind a driver to this device.Avalue of 1 is 'yes' and a value of 0 is 'no'.
/sys/bus/ap/poll_thread Read-write attribute indicating whether a polling thread is to be used to
increase cryptographic performance. By writing 0 or 1 to this attribute the
poll thread can be disabled or enabled.
/sys/bus/ap/poll_timeout Read-write attribute representing the interval (in nanoseconds) for polling
timeout on theAP bus.
/sys/bus/ap/uevent File for storing uevents. Every time that theAP bus detects a device
addition or removal, a new uevent is generated. If there is a udev rule, it
can catch this event and perform appropriate actions.
For each cryptographic adapter a new directory in /sys/bus/ap/devices is created using the following
naming convention: cardxx where xx is the device index for each device. The valid device index range is
hex X'00' to X'3f'. For example, device X'1a' can be found under /sys/bus/ap/devices/card1a. Within
each device directory the following attributes can be found:
depth Read-only attribute representing the input queue length for this device.
hwtype Read-only attribute representing the hardware type for this device. The following values
are defined:
3 PCICC cards
4 PCICAcards
538 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

5 PCIXCC cards
6 CEX2Acards
7 CEX2C cards
8 CEX3Acards
9 CEX3C cards
modalias Read-only attribute representing an internally used device bus-ID.
online Read-write attribute representing the online status for thisAP device. Writing 0 or 1 to this
attribute sets this device offline or online.
request_count
Read-only attribute representing the number of requests already processed by this device.
type Read-only attribute representing the type of this device. The following types are defined:
v PCICC
v PCICA
v PCIXCC_MCL2
v PCIXCC_MCL3
v CEX2A
v CEX2C
v CEX3A
v CEX3C
Running secure key under a z/VM guest
| In order to use the CEX3C feature under z/VM versions 6.1, and 5.4, you need to apply theseAPAR fixes:
APAR number Description
VM64656 Introduces CEX3C support.
|| VM64727 Fixes problem with shared coprocessors.
VM64793 Introduces protected key CPACF support.
To get secure key running under a z/VM guest, a directory control statement (CRYPTOAPDED) for a
given VM guest needs to be used. This require that theAP's with this domain are owned by the LPAR.
There is no virtualization done by z/VM.
For secure key, z/VM does not virtualize theAP's. TheAP's need to be dedicated, which is done by the
user statement:
CRYPTO DOMAIN 12 APDED 5 7
This statement dedicatesAP's 5 and 7 for domain 12 to one Linux guest.
For clear key, z/VM does a virtualization for theAP's, which is done by the user statement:
CRYPTO APVIRT
The domain must have one or moreAP's for this. If available, an accelerator is used. If not, a coprocessor
is taken. The guest always sees only one card regardless of how many cards are owned by the LPAR.
This requires that the cards are made available to the LPAR in which VM is running. The domain andAPs
must be defined in the LPAR profile.
Note that the CCAdoes not use and can not handle the clear key settings.
AppendixI.Initialsystemsetuptips 539

540 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix J. CCA installation instructions
This appendix contains CAARelease 4.0.0 and later installation, configuration, and uninstallation
instructions.
|
Before you begin
| In this section, these terms are used to describe CCARPMs, referring to several different versions:
|| CCA4.x CCA4.0.0, CCA4.1.0, and subsequent versions.
|| CCA3.x Any CCAversion 3 release.
Before you begin the CCAinstallation, review these points:
v Ensure that you are using supported hardware. See “Hardware requirements” on page xvii.
v Ensure that your Linux distribution has the zcrypt device driver support. For details, see “Installing and
loading the cryptographic device driver” on page 537.
v If you are going to use the Java Native Interface (JNI), see “Building Java applications to use with the
CCAJNI” on page 16 for supported Java levels and installation instructions.
v If you plan on maintaining a dual install environment alongside the legacy xcryptolinz RPM originally
released to support the CEX2C, take note of these facts:
| – The CEX3C CCA4.x RPMs support CEX2C access, includingAES (for up-to-date CEX2C firmware)
| and all functions formerly available for the CEX2C. It is recommended to use the latest CEX3C CCA
| 4.x library for all CEX*C access.
– The new TKE catcher daemon supports managing CEX2C as well as CEX3C.
– You are advised to pay special attention toAppendixK, “Coexistence of CEX3C and CEX2C
features,” on page 549 and particular the section “Dual Support: Key storage interactions” on page
551.
Download and install the RPM
| The CCARPM contains files, samples, and groups. The latest CCARPM as of this publication is a
| packaged build of CCA4.1.0 for RPM platform target s390x. The CCARPM has a naming convention of
| csulcca-4.1.0-maintenance level.s390x.rpm, where maintenance level is a number representing the
| current maintenance level.
To download the RPM, complete these steps:
1. Point your Web browser at this location:
http://www.ibm.com/security/cryptocards
2. Locate the box on the left side labeled Cryptocards.
3. Click the PCIe Cryptographic Coprocessor link from the Cryptocards box.
4. The Cryptocards box will be updated with a submenu underneath the PCIe Cryptographic
Coprocessor name.
5. Find the Software download link on this submenu and click it.
6. The main page will be updated with information on downloading host software for various platforms.
7. On this page, find the heading Obtaining CCAsoftware for System z servers running Linux.
8. In the paragraph underneath this heading will be the links to download:
v The README file for the RPM.
v The RPM itself that installs the host code.
©CopyrightIBMCorp.2007,2011 541

Files in the RPM
These files are included in the RPM:
/etc/profile.d/csulcca.sh
Environment variables are created in this file, customers should read for up-to-date information.
The key storage environment variables are added here. See “Environment variables for the key
storage file” on page 262.
/etc/profile.d/csulcca.csh
Environment variables are created in this file, customers should read for up-to-date information.
The key storage environment variables are added here. See “Environment variables for the key
storage file” on page 262.
Note: /etc/profile.d/csulcca.sh and /etc/profile.d/csulcca.csh are exactly the same in what they
do, but have syntax differences. Only one of these two files is used, depending on the
configuration of the particular user running an application.
/etc/init.d/CSUTKEcat
/etc/rc.d/rc2.d/S14CSUTKEcat
Link to: /etc/init.d/CSUTKEcat
/etc/rc.d/rc3.d/S14CSUTKEcat
Link to: /etc/init.d/CSUTKEcat
/etc/rc.d/rc5.d/S14CSUTKEcat
Link to: /etc/init.d/CSUTKEcat
/opt/IBM/CEX3C/bin/TKECM.dat
/opt/IBM/CEX3C/bin/acpoints.dat
/opt/IBM/CEX3C/bin/catcher.exe
/opt/IBM/CEX3C/bin/panel.exe
Utility: run with no arguments for usage
/opt/IBM/CEX3C/bin/ivp.e
Utility: run with no arguments for install verification
/opt/IBM/CEX3C/bin/profile.perl
/opt/IBM/CEX3C/doc/README.linz
| /opt/IBM/CEX3C/doc/license.txt
| /opt/IBM/CEX3C/include/csulincl.h
/opt/IBM/CEX3C/include/HIKM.h
/opt/IBM/CEX3C/doc/hikmNativeInteger.html
/opt/IBM/CEX3C/cnm/HIKM.zip
/opt/IBM/CEX3C/cnm/HIKMMK.zip
/usr/lib64/libcsulcca.so
Link to: /usr/lib64/libcsulcca.so.4
| /usr/lib64/libcsulcca.so.4
| Link to: /usr/lib64/libcsulcca.so.4.1.0
| /usr/lib64/libcsulcca.so.4.1.0
| /usr/lib64/libcsulccamk.so
Link to: /usr/lib64/libcsulccamk.so.4
542 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| /usr/lib64/libcsulccamk.so.4
| Link to: /usr/lib64/libcsulccamk.so.4.1.0
| /usr/lib64/libcsulccamk.so.4.1.0
| /opt/IBM/CEX3C/keys/README.keys
Samples in the RPM
These samples are included in the RPM:
/opt/IBM/CEX3C/samples/mac.c
C code sample
/opt/IBM/CEX3C/samples/makefile.lnx
Used to build mac.c
/opt/IBM/CEX3C/samples/mac.java
Java code sample
/opt/IBM/CEX3C/samples/RNG.java
Java code sample
Groups in the RPM
These groups are created for the purpose of loading master keys. They are added during RPM installation
| as updates to /etc/groups. See Table161 on page 546.
v cca_admin
v cca_clrmk
v cca_lfmkp
v cca_cmkp
v cca_setmk
Install and configure the RPM
| Use the following steps to install and configure the CCA4.1.0 RPM.
1. Copy the RPM to the host where it will be installed. For example, /root/ on your host image.
2. Login to the host as root. Change to the directory where the RPM is located by issuing these
commands:
<login to host>
cd /root/
3. Install the RPM by issuing the following:
rpm -i <rpm name>
Notes:
a. If this is an upgrade you can use rpm -Uvh
b. If you are installing the RPM on a Novell SUSE distribution of Linux, it is possible that you might
receive the following warning messages because of an unsupported groupadd option.
groupadd: You are using an undocumented option (-f)!
groupadd: You are using an undocumented option (-f)!
groupadd: You are using an undocumented option (-f)!
groupadd: You are using an undocumented option (-f)!
groupadd: You are using an undocumented option (-f)!
No action on your part is needed. The installation proceeds with another call if this happens.
4. Reboot the host by issuing the following command:
shutdown -r now
AppendixJ.CCAinstallationinstructions 543

This is necessary because of the defaults added to /etc/profile.d/csulcca.sh and
/etc/profile.d/csulcca.csh for using CCAmust be propagated to all user login sessions.
5. Login to the host as root. Change to the directory where the RPM binaries are installed by issuing the
following command:
<login as root to host>
cd /opt/IBM/CEX3C/bin/
6. Verify that at least one card is present and active:
a. Ensure that the device driver is loaded by issuing the following command:
lsmod
You should see the module z90crypt loaded. If it is not loaded, verify the contents of the kernel
modules directory by issuing the following command:
ls /lib/modules/<Linux kernel version>/kernel/drivers/s390/crypto/
You should see z90crypt.ko. If there is just z90crypt.ko then load it with the following:
modprobe z90crypt
Notes:
1) This works if you have only one domain assigned to the LPAR (or z/VM guest using a
dedicated CEX3C card). If more than one domain is available, you need the domain
parameter in the modprobe command to assign a domain (or use the lowest one).
2) Novell SUSE Linux uses its own start script, rcz90crypt, to do all the work. Settings can be
specified using YaST.
Note: If you do not see any of these kernel modules, or if there are any errors reported from the
call to modprobe, contact IBM Service.
b. When you are sure that the device driver is loaded, run one of the RPM-installed utilities to verify
accessibility by running the following command:
/opt/IBM/CEX3C/bin/ivp.e
This will health check all active cards.
/opt/IBM/CEX3C/bin/panel.exe -x
This will show the serial numbers and master key register states of all active cards running CCA
that are visible to this Linux host. The total number of active cards and any errors will also be
reported.
Notes:
1) To be able to use /opt/IBM/CEX3C/panel.exe the user must be either root or a member of the
'cca_admin' group (the owner of /usr/lib64/libcsulccamk.so).
2) If there is not at least one active card at this point, double check earlier steps and, if
necessary, involve IBM service because the rest of the setup is designed around having
active cards.
| 3) Unload of the device driver requires killing the catcher.exe program, and then restarting it
| when the driver is reloaded. See the note in “Installing and loading the cryptographic device
| driver” on page 537 for specific instructions.
7. Master key load - This procedure is for using the Linux on System z nativeAPI or the utility
(panel.exe) to load the master keys for the active cards.
If you want to use TKE instead, refer to a TKE manual, such as the IBM Redbooks® publication
Exploiting S/390 Hardware Cryptography with Trusted Key Entry for proper use.After completing this
step using the TKE procedure, go to Step 8 on page 547.
a. Setup the groups for the users who will be loading the master keys to the cards. Each part of the
load process is owned by a different Linux group created by the RPM install procedure, and
verified in the host library implementing theAPI allowing master key processing. To complete a
544 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

specific step the user must have membership in the proper group. There are a couple ways to
change group membership depending on your Linux distribution.Athird option is to create the
users specifically for these roles.
If a user does not have the proper group membership for a particular master key operation, the
error X'0008005a' is returned and an error message is printed to the system log.
Note: To be able to use /opt/IBM/CEX3C/panel.exe the user must be either root or a member of
the 'cca_admin' group (the owner of /usr/lib64/libcsulccamk.so).
1) Group membership for Red Hat (and Fedora) based Linux distributions
a) Use the 'groups' command to see a list of the user's current group membership:
groups <user name>
---output is
<user name> : <grouplist>
<grouplist> is a single-space separated list
b) <grouplist> must be passed along with the new group to the 'usermod' command as a
"comma" separated list, followed by the <user name>. For example, if you wanted to add
'cca_lfmkp' membership to user 'admin', you would use the following commands:
groups admin
---output:
admin : admin bin daemon sys wheel
usermod -G admin,bin,daemon,sys,wheel,cca_lfmkp admin
---output:
[none if successful]
Note: Ensure the user logs out and logs back in, otherwise the group membership in the
active session will not be updated.
2) Group membership for Novell SUSE-based Linux distributions:
a) Use the 'usermod' command to add membership for a specific group for a specific user.
For example, if you wanted to add 'cca_lfmkp' membership to user 'admin' you would use
the following commands
usermod -A cca_lfmkp admin
Note: Ensure the user logs out and logs back in, otherwise the group membership in the
active session will not be updated.
3) Create users for each role with correct group memberships (Same calls for Red Hat, Fedora,
and Novell SUSE)
a) Create user cca_user, which will own default key storage by issuing the following:
useradd -g cca_admin -d /home/cca_user -m cca_user
This creates the user with primary group cca_admin and a new home directory.
passwd cca_user
This sets the new user's password.
b) Create user cca_lfmkp by issuing the following:
useradd -g cca_admin -d /home/cca_lfmkp -G
cca_admin,cca_lfmkp -m cca_lfmkp
AppendixJ.CCAinstallationinstructions 545

This creates the user with primary group cca_admin, secondary group cca_lfmkp, and a
new home directory.
passwd cca_lfmkp
This sets the new user's password.
c) Create user cca_cmkp by issuing the following:
useradd -g cca_admin -d /home/cca_cmkp -G
cca_admin,cca_cmkp -m cca_cmkp
This creates the user with primary group cca_admin, secondary group cca_cmkp, and a
new home directory.
passwd cca_cmkp
This sets the new user's password.
d) Create user cca_clrmk by issuing the following:
useradd -g cca_admin -d /home/cca_clrmk -G
cca_admin,cca_clrmk -m cca_clrmk
This creates the user with primary group cca_admin, secondary group cca_clrmk, and a
new home directory.
passwd cca_clrmk
This sets the new user's password.
e) Create user cca_setmk
useradd -g cca_admin -d /home/cca_setmk -G
cca_admin,cca_setmk -m cca_setmk
This creates the user with primary group cca_admin, secondary group cca_setmk, and a
new home directory.
passwd cca_setmk
This sets the new user's password.
b. Add group membership privileges to users based on their required function.
Table161.CCAgroups
GroupName Description
cca_admin Alluserswhowillrunpartofthemasterkeyloadprocessmustbeinthisgroupbecausethelibrary
itselfisownedbyroot.cca_admin,withnopermissionsfor'world'asaprotectivemeasure.
Reasonsforthisseparategroupalsoincludeallowingoneownerof/usr/lib64/libcsulccamk.so,
andallowinguseofpanel.exewithoutallowinganyofthemasterkeyprocessingcalls.
cca_lfmkp TheusertoLOADthefirstkeypartmustbeinthisgroup.
cca_cmkp TheuserstoLOADthemiddleandlastkeypartsmustbeinthisgroup.
cca_clrmk Thenewmaster-keyregistercanbeCLEARedusingthesameMasterKeyProcesscallincasea
mistakewasmadeenteringakeypart(usethekeyverificationpatternstocheckforthis).To
performtheclear,theusermustbeamemberofthisgroup.
546 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Table161.CCAgroups (continued)
GroupName Description
cca_setmk TheusertocallSETafterthelastkeyparthasbeensuccessfullyloadedmustbeamemberofthis
Linuxgroup.
| c. Load FIRST, MIDDLE (optional), and LAST key parts for theAES, SYM,ASYM, andAPKAmaster
| keys and then call SET for each master key. This step can be done using the panel.exe utility
| provided or by writing your own application to call the Master Key Process (CSNBMKP) verb
| directly. The application must link with the correct library (installed to /usr/lib64/libcsulccamk.so
| by the RPM), and must be executed at each step by a user with the appropriate group
| memberships. The utility supports scripted as well as prompt-driven access.
| Repeat this step for each configured adapter. See “Changing the master key for two or more
| adapters that have the same master key, with shared CCAkey storage” on page 265.
| For details about panel.exe, see “The panel.exe utility” on page 553.
| Note: Loading master key parts modifies state information inside the card. For example you
| cannot load a 'FIRST' master key part twice in a row without clearing the new master-key
| register in between attempts. The same goes for setting the 'LAST' register.Any number of
| 'MIDDLE' parts can be loaded - with each call changing the contents of the new
| master-key register. Similarly a 'SET' operation changes the state of the 'new' register back
| to 'empty', while updating the 'current' register.
8. Key storage initialization - To perform this step, see “Using panel.exe for key storage initialization”
on page 555. See also “Dual Support: Key storage interactions” on page 551.
9. Key storage re-encipher when changing the master key - To perform this step, see “Using
panel.exe for key storage reencipher when changing the master key” on page 556.
10. If you are going to be using Central ProcessorAssist for Cryptographic Functions (CPACF), it must
be configured. See “CPACF support” on page 8.
Uninstall the RPM
| Use the following steps to uninstall the CCARelease 4.1.0 RPM:
| 1. Uninstall any RPMs that depend on the CCARPM. If you try to uninstall the CCARPM and dependent
| RPMs are still installed, the uninstall RPM command will fail and list the names of dependent RPMs.
| Therefore, you can skip to Step 2 and come back to this step if Step 2 fails for that reason.
2. Uninstall the CCARPM.
a. You have to use the full name. You can find the name by issuing the following command:
rpm -qa | grep csulcca
b. Login as root. You have to be root to uninstall the RPM.
c. Uninstall the RPM with the following command:
rpm -e <rpm name>
Notes:
a. If you created any users with one of the groups created by the RPM install as their primary (note
that the RPM install does NOT create any users, just groups) then the un-install process will not be
able to remove those groups. Just delete those users/groups yourself after uninstall or remove
such users before the uninstall of the RPM. This will remove any potential security holes.
b. Card master keys (and other state information) are untouched by the host-side uninstall of the
RPM.
c. Key storage files are not deleted by the uninstall.All default and nondefault key storage files will be
left as is. If you reinstall or install an upgraded package and load any new cards with the same
AppendixJ.CCAinstallationinstructions 547

master keys you will still be able to use your old key storage (old cards will still have the old keys,
see Step 7b on page 546 of “Install and configure the RPM” on page 543).
548 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

|
Appendix K. Coexistence of CEX3C and CEX2C features
This appendix discusses trade-offs when configuring CEX2C features together with CEX3C features
available to the same Linux instance.
| These terms are used to describe CCARPMs, referring to several different versions:
|| CCA4.x CCA4.0.0, CCA4.1.0, and subsequent releases.
|| CCA3.x Any CCAversion 3 release.
Legacy support
|
| These are legacy support considerations.
| v The latest CCA4.x RPM will supersede and replace earlier RPMs if installed in the default manner. It is
| NOT recommended to manually alter installation in order to run newer versions of CCA4.x RPMs in
| parallel with older versions. This configuration is not supported.
| v Running the latest CCA4.x RPM in parallel with the IBM 3.x RPM and an IBM Crypto Express2
| (CEX2C) feature in coprocessor mode configured to the same system image is a supported
| configuration. See “Concurrent installations.”
| v CCA4.x RPMs include support for interaction with the CEX2C feature in coprocessor mode. See “Dual
| Support: TKE catcher can run in only one instance” on page 552.
Concurrent installations
|
| These are background considerations for installation of the CEX3C and CEX2C RPM alongside the
| previously released RPM for the CEX2C.
| 1. The libcsulcca.so and libcsulsapi.so libraries for CCA4.x and CCA3.x have many symbols with the
| same names.An application cannot deterministically link with both libraries. The first library in the link
| statement is what will be used for all symbols that can be resolved there, after that the second library
| will be examined.At this point, either the linker will not allow link to continue, by throwing an error on
| the duplicate symbols, or will produce a hybrid-linked application. Either case will give the user the
| wrong answer.
| Anew or updated library cannot itself resolve this kind of conflict because:
| v There is no way to have a default set of symbols or card support in an updated host library. The link
| operation is a fundamental step in building the customer application and outside the control of the
| library or library installation process.
| v One way to resolve name collisions is to change all of the function names in the new library.
| However, this would have greatly impacted the customer's ability to port applications forward, and
| this option was rejected.
| 2. The key storage environment variables in the default user profile (/etc/profile.d/csulcca.sh and
| /etc/profile.d/csulcca.csh) are changed at installation time to point to the /opt/IBM/CEX3C/keys/
| path, where before the path contained /*/4764/*. There is one set of environment variables for a profile.
| The user can overcome this by setting a local profile in their home profile file that sets the environment
| variables back to the 4764 version. See “Dual Support: Key storage interactions” on page 551.
| 3. See “Interaction between the 'default card' and use of Protected Key CPACF” on page 11 for a
| concurrency and CPACF.
| CEX3C and CEX2C co-installation toleration
| The CCA4.x RPMs all support accessing the CEX2C feature as well as the CEX3C feature, with the first
| CEX3C becoming the 'default' adapter. This can be changed using environment variables. See
| “Environment variables that affect CPACF usage” on page 8. Using CCA4.x is your best option for
| accessing a CEX2C feature as well as a CEX3C feature going forward, even in a CEX2C-only installation.
©CopyrightIBMCorp.2007,2011 549

| Installing the csulcca RPM over an existing xcryptolinz RPM: During installation the new csulcca
| RPM will look for and rearrange the xcryptolinz RPM pieces that conflict with the new RPM. These consist
| of a few soft links and some profile settings.
| Your old key storage will not be accessed, deleted or modified; it will also not be migrated.As long as the
| appropriate master keys are set in the CEX3C to be the same as the equivalent master keys in the
| CEX2C, the old key storage can be simply used by the new host library. There is a set of environment
| variables that control where key storage is found. See “Environment variables for the key storage file” on
| page 262.
| The csulcca RPM does not replace the xcryptolinz RPM, the csulcca RPM will live alongside it, in order to
| ease the transition process.
| Temporary toleration approach to avoid re-linking applications: Because the new RPM has a new
| name for the CCAhost library, it is necessary to re-link your application with the new library. There is a
| quick method for toleration if this is not immediately possible. Create soft links in /usr/lib64/ from the
| new libraries to the names of the libraries that existed before:
| 1. IMPORTANT Delete or move the old libraries first.
| 2. Create a soft link of libcsulcca.so.4.1.0 or libcsulcca.so.4.0.0 to libcsulsapi.so, libcsulsecy.so,
| libds30.so and libcsulcall.
| 3. Create a soft link of libcsulccamk.so.4.1.0 or libcsulccamk.so.4.0.0 to libcsulmkapi.so
| 4. Run the ldconfig command.
| Uninstalling the xcryptolinz RPM: This task is not impacted by the changes the csulcca RPM makes
| when it is installed.
| Re-installing the xcryptolinz RPM with the csulcca RPM installed:
|
| IMPORTANT
| This is not a supported operation. The csulcca RPM cannot detect this scenario to try to recover the
|| csulcca package function.
|
|
| Difficulties noted above for the coexistence scenario make supporting consistent operation of the csulcca
| RPM while allowing reinstall of the xcryptolinz RPM impossible. The xcryptolinz RPM install will create
| TKE daemon soft links pointing to the old TKE daemon (which cannot communicate with CEX3C adapters)
| and corrupt the standard profile settings updated for the csulcca install.
| If a refresh of the xcryptolinz RPM is truly needed, choose one of these three methods:
| 1. By uninstalling and installing:
| a. Uninstall the csulcca RPM first, in order to have a clean system image. The key storage file will be
| left intact.
| b. Install the xcryptolinz RPM.
| c. Reinstall the csulcca RPM so that the updated function is back in place.
| 2. By using tools and copying files:
| a. Use the rpm2cpio and cpio tools to extract only the files needed from the xcryptolinz RPM.
| b. Copy the needed files into place manually.
| 3. By using soft links and environment variables:
| a. Create the soft links from the new RPM host libraries to the old library names. See “Temporary
| toleration approach to avoid re-linking applications.”
| b. Point the new RPM host library at your old key storage file using the environment variables, which
| can be done on a per-process basis.
550 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

| See “Environment variables for the key storage file” on page 262 for a discussion about the environment
| variables that are used to specify the name of the key storage files.
| Fixing the csulcca RPM install after installing xcryptolinzGAon top of it: It is possible to simply
| recover the csulcca RPM install state with these two procedures. It is recommended that you subsequently
| reboot the system image. Perform these steps (as root):
| 1. Run this command:
| /opt/IBM/CEX3C/bin/profile.perl delete
| This will remove the environment variables added to /etc/profile by the xcryptolinzGARPM. If you
| need those variables set in a particular application space, set them in startup scripts for the application
| that needs them. Because these variables are positioned at the end of /etc/profile, they disable the
| csulcca RPM configuration.
| 2. Delete startup file links by issuing these commands:
| rm -f /etc/init.d/rc2.d/S16TKEcat
| rm -f /etc/init.d/rc3.d/S16TKEcat
| rm -f /etc/init.d/rc5.d/S16TKEcat
| These startup files cause the wrong TKE catcher daemon to be loaded, which cannot communicate
| with CEX3C adapters. The new TKE catcher daemon can work with both CEX2C and CEX3C
| adapters, so it is preferred for all systems with co-install of the xcryptolinzGARPM and the csulcca
| RPM.
| Caveats:
| v Be very careful with setting Master Keys and allowing other accesses. The older libraries will not detect
| the difference between a CEX2C and a CEX3C, and will attempt to access the new cards if allocated by
| the user.
| v It is best to use a concurrent environment as a temporary aid to a porting effort, the result of which is
| an application that can use the card it desires allocated through the new CEX*C library.
Dual Support: Key storage interactions
|
| The following factors together should be considered, and managed carefully for user installations:
| v In all the CCA4.x RPMs, the environment variables described in “Environment variables for the key
| storage file” on page 262 have the same names. The purpose is to ease application porting efforts.
| v The recommended method to accomplish coexistence of the two CCApackages for porting or debug
| environments is the installation of the CCA4.x RPMs on top of an existing xcryptolinz RPM installation.
| This installation will change how the environment variables are defined for any user performing login
| after the CCA4.x RPM installation, such that the environment variables will point to the new location.
| v Therefore, legacy applications that have not defined their own key storage environments (those using
| the default profile location) will now be using the new key storage file defined for the CCA4.x RPMs.
| These are likely consequences the next time that the legacy application starts:
| – The legacy application will not be able to find its existing keys.
| – The legacy application may corrupt key storage for applications using the new CCA4.x RPM location
| for key storage.
| Solution
| The application developer should ensure that legacy applications are started using the definitions for the
| key storage environment variables that they require.
| v The environment variables were placed in file /etc/profile by the xcryptolinz RPM installation (look for
| the LINZCRYPT section). They were defined as follows:
| – CSUDESLD=/opt/IBM/4764/keys/deslist
| – CSUDESDS=/opt/IBM/4764/keys/des.key
| – CSUPKALD=/opt/IBM/4764/keys/pkalist
| – CSUPKADS=/opt/IBM/4764/keys/pka.key
AppendixK.CoexistenceofCEX3CandCEX2Cfeatures 551

| – LD_LIBRARY_PATH=/usr/lib64
| – CNM_CLASSPATH=/opt/IBM/CEX3C/cnm/
| – CSUSRDI=$HOME/srdidata
| v There are several ways to ensure that your application is started with these environment variables
| instead of the defaults. One straightforward way is to complete the following steps:
| 1. Manually export the definitions using the command export.
| 2. Check that they are set correctly using the commands: env or printenv.
| 3. Manually start the application that needs the special environment.
| You can useAES key storage functions with a CEX2C feature only if you have installed the CCA4.*
| RPMs. This is because the environment variables CSUAESLD and CSUAESDS are necessary forAES
| key storage, but they did not ship with the CCA3.* RPMs. These environment variables are defined as
| follows:
| v CSUAESLD=/opt/IBM/CEX3C/keys/aeslist
| v CSUAESDS=/opt/IBM/CEX3C/keys/aes.key
Dual Support: TKE catcher can run in only one instance
|
| The Trusted Key Entry (TKE) catcher daemon is used to interface with the TKE workstation. This daemon
| listens on a single port for management communication. This port number has not changed for the CEX3C
| release. Therefore, the new daemon supports TKE management communication to both the CEX2C and
| CEX3C adapters. Special steps are taken in the install/uninstall and daemon management for the CEX3C
| release to ensure that the new daemon is running when it is available.
| You must have a TKE V6.0 or higher workstation in order to see supported CEX3Cs. They are not seen
| when using TKE V5 workstations. For more information about the TKE workstation, see z/OS
| Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation User’s Guide.
552 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Appendix L. Utilities
This appendix describes two utilities used in this document:
ivp.e
This utility is used to verify installation, when run without arguments.
This utility can also be used to tell you whether your cards are CEX3C or CEX2C, by calling the
Cryptographic Facility Query verb for all available adapters.
panel.exe
This utility provides a Linux native mechanism for administering and initializing certain characteristics
of active cryptographic coprocessors. It is intended as a basic administration tool for Linux-only IBM
System z configurations, where a Trusted Key Entry (TKE) solution is not available.
For mixed z/OS and Linux configurations, it is recommended that administration be accomplished
using the z/OS TSO panels as described in the z/OS ICSFAdministrator's Guide. The utility is
installed by the Linux for System z Cryptographic Coprocessor install package or RPM to this path in
the Linux system:
/opt/IBM/CEX3C/bin/panel.exe
The panel.exe utility
The panel.exe utility is installed by the Linux for IBM System z Cryptographic Coprocessor install package
or RPM to this path in the Linux system:
/opt/IBM/CEX3C/bin/panel.exe
| The panel.exe utility numbers cards from card0 to card63, while verbs such as Cryptographic Resource
| Allocate number cards from CRP01 to CRP64, and therefore card0 corresponds to CRP01, card1
| corresponds to CRP02, and so forth.
panel.exe syntax
Precise usage information can be obtained by running the panel.exe utility with no arguments on the Linux
shell command line. This is an example output:
| Panel usage ([-k,-a <num>,-o,-g][-?,-x,-m,-l,-s,-c,-q,-t,-f,-i,-r,-p,-n]
| >> [CC] Arg >> arg must precede non-[CC] args
| [CC] -k: Can TKE administer a card?
| [CC] -a <num>: use non-default card
| <num> is the card number [0 - 63]
| [CC] -o: Disable output to stdout:
| [CC] -g <level>: Set the log level:
| <level> can be NONE, TRANSACTIONS, NONZERO,
| ALL, DEBUG, and FUNCTIONS
|
| >> non-[CC] Args >>: (all are mutually exclusive)
|
|
| ---BASIC ADMIN---
|
| -? , -h: Usage
|
| -x: List crypto resources (and basic status)
| -m: List CPACF (local CPU crypto) resources
|
| ---MASTER KEY (MK)---
|
| To LOAD a Master Key (MK) PART:
| -l (for interactive)
| OR====>
| -l -t [A|S|E|P] -p [F|M|L] KEYPART
©CopyrightIBMCorp.2007,2011 553

| where: -t [A|S|E|P] is which MK: A=ASYM, S=SYM, E=AES P=APKA
| where: -p [F|M|L] is the part: F=FIRST, M=MIDDLE, L=LAST
| where: KEYPART is string in hex 2* size of key
| (recall: 2 text chars = 1 binary Byte)
| To SET a Master Key:
| -s (for interactive)
| OR====>
| -s -t [A|S|E|P]
| where: -t [A|S|E|P] is which MK: A=ASYM, S=SYM, E=AES P=APKA
| To CLEAR a Master Key ’New’ Register:
| -c (for interactive)
| OR====>
| -c -t [A|S|E|P]
| where: -t [A|S|E|P] is which MK: A=ASYM, S=SYM, E=AES P=APKA
| To QUERY a Master Key Verification Pattern:
| -q (for interactive)
| OR====>
| -q -t [A|S|E|P] -r [N|C|O]
| where: -t [A|S|E|P] is which MK: A=ASYM, S=SYM, E=AES P=APKA
| where: -r [N|C|O] is which register: N=NEW, C=CURRENT, O=OLD
| ---KEY STORAGE---
|
| To INIT a KEY STORAGE file:
| -t <type> -f <file> -i
| To REENCipher KEY STORAGE:
| -t <type> -f <file> -r
| To LIST a KEY STORAGE:
| -t <type> -f <file> -p
| where:
| <type> can be AES , DES , PKA
| <file> is the fully qualified name of a key storage file
|
| ---RETAINED KEYS---
|
| To LIST RETAINED KEYS (this domain ONLY):
| -n
Note: For security reasons, only a root user (real user id equal to '0') is allowed to use panel.exe to load
master key parts or to clear previously loaded master key parts. This is enforced at the shared
library level in the implementation of the Master Key Process verb, not in the utility itself.
Additionally, only the user who created a set of key storage files or the 'root' user will be able to
take actions with respect to those key storage files, based on Linux file system permissions.
panel.exe functions
The panel.exe utility can be used to:
v Determine if a TKE is currently able to administer a specific active coprocessor
v List the labels and key types for all the keys in a designated key storage file.
v List the labels for all of the retained keys (RSAprivate keys stored in the adapter) in the current domain
of the CEX*C.
v List the coprocessors currently active in the Linux system and their master key status
v Load master key parts to the coprocessor
v Set a master key that was loaded to the coprocessor. Note that panel.exe, is not designed to change
the master keys for all the cards in a group; this is a more sophisticated operation.
v Clear master key parts which were previously loaded to the coprocessor but not yet 'set' or confirmed
(used for when a mistake in entering master key parts has been detected)
v List serial numbers and master key register states of all active cards running CCAthat are visible to this
Linux host. The total number of active cards and any errors will also be reported.
v Query the master key verification pattern for any master-key register in the current domain
v Initialize a local host key storage file. See “Using panel.exe for key storage initialization” on page 555.
554 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

v Re-encipher a local host key storage file (use this when the master key has been changed to ensure
currency with key storage). See “Using panel.exe for key storage reencipher when changing the master
key” on page 556.
v List available CPACF functions, and whether they are supported in the current system image.
The panel.exe utility does not support access control point manipulation or more sophisticated
administration. Refer to “Trusted Key Entry support” on page 38 for that functionality.
Using panel.exe for key storage initialization
Each application using CCAtypically creates key objects that are stored in the host, protected by the
master key stored inside the card. Perform these steps for key storage initialization.
1. The default locations for the files are setup by the RPM in environment variables added in the new
profile files /etc/profile.d/csulcca.sh and /etc/profile.d/csulcca.csh during installation. Key
storage is unsupported without a master key loaded, so Master key load (Step 7 on page 544) must
be completed before this step. The utility panel.exe can be used to initialize both the default key
storage and any separate key storage you might want to set up. The full topic is too lengthy for this
explanation (see the key storage discussions elsewhere in this manual, including the verb “Key
Storage Initialization (CSNBKSI)” on page 90). In brief, an application can specify a particular key
storage location. That nondefault key storage can be initialized now (or later) by using panel.exe or
with a program using the Key Storage Initialization verb.
For details about panel.exe, see “The panel.exe utility” on page 553.
If you are planning to use both the CEX2C and CEX3C in the same environment, see the information
about the key storage environment variable in “Concurrent installations” on page 549.
2. The key storage environment variables in the default user profile (/etc/profile.d/csulcca.sh) are
changed at installation time to point to the /opt/IBM/CEX3C/keys/ path, where before the path
contained /*/4764/*. There is one set of environment variables for a profile. The user can override this
by setting a local profile in their home profile file that sets the environment variables back to the 4764
version.
3. Key storage ownership
The default key storage files are actually partially created (but not fully initialized) during the master
key load process. This means the ownership and permissions of those files might have to be changed
for them to be fully initialized by the user associated with the application that will use the key storage
files.
Because of the mutually exclusive nature of the master key admin groups, there can be some
harmless access errors reported to the system log during master key load. The example users created
previously in Master key load Step 7a3 on page 545 will avoid this and not need to fix key storage
ownership because they were all created with the primary group set to 'cca_admin' (the -g argument to
useradd). By doing this, the first master key load creates the key storage files with group set to
'cca_admin' and subsequent users all have membership in that group. You still might want to fix the
owner of default key storage at the end to be 'root', but the group membership solves the access
issue.
Typically 'root' will need to fix the ownership and permissions. We recommend that the owner of key
storage be 'root', and that the group be 'cca_admin' ('cca_admin' group is created during the RPM
install process). We recommend that the permissions be set to 660, which is rw for owner (root), rw for
group (cca_admin), and <none> for 'everyone', for security. Then add the application user to the group
'cca_admin' with the appropriate procedure detailed in Master key load Step 7a on page 544.
RECALL: To be able to use /opt/IBM/CEX3C/panel.exe the user must be either root OR a member of
the 'cca_admin' group (the owner.group of /usr/lib64/libcsulccamk.so). The reasons for the separate
'cca_admin' group are to allow one owner of /usr/lib64/libcsulccamk.so, and to allow use of the
executable without allowing any of the master key processing calls.
4. Key storage initialization with panel.exe (default)
AppendixL.Utilities 555

a. Ensure permissions to the default location (/opt/IBM/CEX3C/keys/) allow your user to perform this
operation.
b. Initialize key storage (DES is where DES key tokens will be kept,AES is whereAES key tokens
will be kept, PKAis for all the RSApublic/private internal key tokens, andAPKAis forAPKAkey
tokens).
/opt/IBM/CEX3C/bin/panel.exe -t AES -i
/opt/IBM/CEX3C/bin/panel.exe -t DES -i
/opt/IBM/CEX3C/bin/panel.exe -t PKA -i
5. Key storage initialization with panel.exe (non-default)
a. Ensure that you are using the account that will use the key storage. If you are not, you will have to
fix its ownership and permissions later.
b. Initialize both types of key storage (DES is where DES key tokens will be kept,AES is whereAES
key tokens will be kept, PKAis for all the RSApublic/private internal key tokens). Use a different
name forAES, DES, and PKA, because the second initialization would overwrite the first if different
names are not used. The file name passed is expected to be the full or relative path and will
actually be the core of the filename, because more than one file is created using the stem you
provide. To initializeAES, DES and PKAstorage, use the following commands:
/opt/IBM/CEX3C/bin/panel.exe -t AES -f <AES file name> -i
/opt/IBM/CEX3C/bin/panel.exe -t DES -f <DES file name> -i
/opt/IBM/CEX3C/bin/panel.exe -t PKA -f <PKA file name> -i
For example, if you entered the following commands:
/opt/IBM/CEX3C/bin/panel.exe -t AES -f /tmp/a -i
/opt/IBM/CEX3C/bin/panel.exe -t DES -f /tmp/d -i
/opt/IBM/CEX3C/bin/panel.exe -t PKA -f /tmp/p -i
These files would be created:
/tmp/a
/tmp/a.NDX
/tmp/d
/tmp/d.NDX
/tmp/p
/tmp/p.NDX
Using panel.exe for key storage reencipher when changing the master
key
Because all the key tokens are protected by the master key for the domain, a preexisting key storage must
be re-enciphered when the master key is changed. If the example group scheme is used this is very
simple because the key storage files will be owned by the group 'cca_admin' and the user making the
reencipher call will also be in group 'cca_admin'. If this is not the case then, after changing the master key,
the owner of key storage will need to log in and drive the reencipher. This can be done programmatically
(using several verbs) or with /opt/IBM/CEX3C/panel.exe. Of course, as noted, the user of panel.exe must
also be a member of 'cca_admin' because of ownership of /usr/lib64/libcsulccamk.so.
Perform these steps for key storage reencipher when changing the master key.
1. To re-encipher default key storage with panel.exe use:
/opt/IBM/CEX3C/bin/panel.exe -t AES -r
/opt/IBM/CEX3C/bin/panel.exe -t DES -r
/opt/IBM/CEX3C/bin/panel.exe -t PKA -r
2. To reencipher non-default key storage with panel.exe use:
556 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

/opt/IBM/CEX3C/bin/panel.exe -t AES -f <AES file name> -r
/opt/IBM/CEX3C/bin/panel.exe -t DES -f <DES file name> -r
/opt/IBM/CEX3C/bin/panel.exe -t PKA -f <PKA file name> -r
AppendixL.Utilities 557

558 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Accessibility
Accessibility features help users who have a disability, such as restricted mobility or limited vision, to use
information technology products successfully.
Documentation accessibility
The Linux on System z publications are inAdobe Portable Document Format (PDF) and should be
compliant with accessibility standards. If you experience difficulties when you use the PDF file and want to
request a Web-based format for this publication, use the Reader Comment Form in the back of this
publication, send an email to eservdoc@de.ibm.com, or write to:
IBM Deutschland Research & Development GmbH
Information Development
Department 3248
Schoenaicher Strasse 220
71032 Boeblingen
Germany
In the request, be sure to include the publication number and title.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information
in any way it believes appropriate without incurring any obligation to you.
IBM and accessibility
See the IBM HumanAbility andAccessibility Center for more information about the commitment that IBM
has to accessibility at
www.ibm.com/able
©CopyrightIBMCorp.2007,2011 559

560 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

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
USA
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual
Property Department in your country or send inquiries, in writing, to:
IBM World TradeAsia Corporation
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: INTERNATIONALBUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OFANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FORAPARTICULAR 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 publication. IBM
may make improvements and/or changes in the product(s) and/or the 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:
IBM Corporation
Mail Station P300
2455 South Road
©CopyrightIBMCorp.2007,2011 561

Poughkeepsie, NY 12601-5400
USA
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 information and all licensed material available for it are provided by
IBM under terms of the IBM CustomerAgreement, IBM International Program LicenseAgreement, 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.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
Programming interface information
This book documents intended Programming Interfaces that allow the customer to write programs to obtain
the services of the Common CryptographicArchitecture.
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.Acurrent 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 ofAdobe 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.
562 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

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.
Notices 563

564 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Index
Numerics AESKeyRecordList(CSNBAKRL) (continued)
requiredcommands 272
3621PINblockformat 308,479
AESKeyRecordRead(CSNBAKRR) 274
3624PINblockformat 308,479
format 274
4700-PAD 497
JNIversion 275
4704-EPPPINblockformat 308
parameters 274
4764CryptoExpress2feature xv
relatedinformation 275
4765CryptoExpress3feature xv
requiredcommands 274
restrictions 274
A AESKeyRecordWrite(CSNBAKRW) 276
format 276
aboutthisdocument xv JNIversion 277
accesscontrol 12 parameters 276
accesscontrolpoint(ACP) 515 relatedinformation 277
accesscontrolpoints requiredcommands 277
CPACF 9 restrictions 277
accesscontrolverbs 515 AESkeystorage 90,261
accesscontrol, AESmasterkey 25,128
description 7 AESNMK 69
accessibility 559 AESOMK 70
ACP AESPKAMasterKey(APKA-MK) 47
remotekeyloading 34 AESverb 40
ACTIVE 404 AES-MK 25,94,145,150
adapterID AESDATA 123
coprocessor 63 AESDATAkeytype 27
adapterserialnumber 66,67,68,70,71 AESKW 128
ADAPTER1 59 AESKWwrappedpayload 439
ADD-PART 136,137,139 AESKWwrapping 24
ADJUST 105,145,151 AESTOKEN 122,123
adpter AESTOKENkeytype 27
pendingchange 66 algorithm 36
AES 122,156,164,179,198,201,205 3624PINgeneration 481
AESCMK 70 3624PINverification 483
AESencryptionalgorithm 222,228 DES 19,36
AESinternalkey-token ECDSA 47
flagbyte 422 GBPPINgeneration 481
AESkey 9 GBPPINverification 485
managing 99 GBP-PIN 339
translation 9 IBM-PIN 339
AESKeyRecordCreate(CSNBAKRC) 267 IBM-PINO 339
format 267 InterbankPINgeneration 489
JNIversion 268 PINoffsetgeneration 482
parameters 267 PIN,detailed 480
relatedinformation 268 PIN,general 37
requiredcommands 268 PKA 47
restrictions 268 PVVgeneration 488
AESKeyRecordDelete(CSNBAKRD) 269 PVVverification 489
format 269 RSA 47
JNIversion 270 VISAPIN 487
parameters 269 VISA-PVV 319,339
relatedinformation 270 VISAPVV4 339
requiredcommands 270 AMEX-CSC 102,157,170
restrictions 270 AMEX-CSCkeysubtype 28
AESKeyRecordList(CSNBAKRL) 271 ANSI9.9-1algorithm 233
format 271 ANSIX3.106 495
JNIversion 272 ANSIX3.106(CBC) 496
parameters 271 ANSIX9.102 24
relatedinformation 272 ANSIX9.19 241
©CopyrightIBMCorp.2007,2011 565

ANSIX9.19optionaldoubleMACprocedure 233 block_sizeparameter
ANSIX9.19OptionalProcedure1MAC 503 SymmetricAlgorithmDecipherverb 223
ANSIX9.23 495 SymmetricAlgorithmEncipherverb 229
ANSIX9.23cipherblockchaining 497 Byte*
ANSIX9.23padding 213 description 17
ANSIX9.23processingrule 211,215,219
Decipher 213
C
Encipher 217
ANSIX9.24 22,176 c-variable_encrypting_key_identifierparameter
ANSIX9.30 360,364 CryptographicVariableEncipherverb 107
ANSIX9.31 360,361,364,365 calculationmethod
ANSIX9.31hashformat 513 MACpaddingmethod 502
ANSIX9.8 xv,336 MessageAuthenticationCode(MAC) 502
ANSIX9.8PINblockformat 477 ModificationDetectionCode(MDC) 493
ANSIX9.8PINrestriction 306 X9.19method 502
ANSIX9.9MAC 502 callableservice 12
ANSIX9.9-1 241 CBCprocessingrule 212,215,219,223,228
ANSIX9.9 102,157,170 Decipher 213
ANSIX9.9keysubtype 28 Encipher 217
ANY 102,157,170 SymmetricAlgorithmDecipher 221
ANYkeysubtype 28 SymmetricAlgorithmEncipher 226
ANY-MAC 102,157,170 CCA
ANY-MACkeysubtype 28 functions 19
APARfixes overview 19
z/VM xviii,539 CCAaccesscontrol 5
APKACMK 71 CCAAPI 3,7
APKANMK 71 CCAAPIbuilddate 61,62
APKAOMK 71 CCAAPIversion 61,62
APKA-MK 47,94,145,152,386 CCAapplication
applicationprograms compile 16
servicerequest 7 Java 16
array_key_left_identifierparameter link 16
ControlVectorTranslateverb 104 CCADES-keyverification 492
array_key_right_identifierparameter CCAdescription 5
ControlVectorTranslateverb 104 CCAerrorlog 63
asym_encrypted_keyparameter CCAfunctionaloverview 4
RemoteKeyExportverb 399 CCAinstallation 541
asym_encrypted_key_lengthparameter CCAlibrary 7,11
RemoteKeyExportverb 398 access 16
ASYM-MK 25,47,94,95,145,150,386 location 7
asymmetricCMKstatus 62 CCAmanagement 3
asymmetrickeysmasterkey 25 CCAmasterkey 6
asymmetricNMKstatus 62 establishing 6
asymmetricOMKstatus 62 CCAnodesandresourcecontrolverb 57
authenticatingmessages 233 CCAnodesandresourcecontrolverbs 40
authentication 3,36 CCAprogramming 3,12
authentication_issuer_master_key_identifierparameter CCARPM
PINChange/Unblockverb 343 configure 543
authentication_issuer_master_key_lengthparameter download 541
PINChange/Unblockverb 343 files 542
AutomatedTellerMachine(ATM) 34 groups 543
samples 543
uninstall 547
B
CCAsampleprogram 527
baseCCAservices 65 C 527
batteryindicator 63 Java 532
battery-backedRAM CCAservices
size 63 base 65
Bellare-Rogaway 513 CCAsoftwaresupport 4
blockchaining 211 CCAsystemsetup 537
CCAverb 3,40,55
566 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CCAverbdescription 6 clearkey 10,11,150,211
CentralProcessorAssistforCryptographicFunctions definition 30
(CPACF) xvi,xviii,8,539 protecting 211
certificateparameter ClearKeyImport(CSNBCKI) 100
RemoteKeyExportverb 396 format 100
certificate_lengthparameter JNIversion 100
RemoteKeyExportverb 396 parameters 100
certificate_parmsparameter requiredcommands 100
RemoteKeyExportverb 396 ClearPINEncrypt(CSNBCPE) 312
certificate_parms_lengthparameter format 312
RemoteKeyExportverb 396 JNIversion 314
CEX2C xv,xvi,xvii,xviii,31,47,48,58,61,549 parameters 312
CEX2Ccoprocessors 5 requiredcommands 313
CEX3C xv,xvi,xvii,xviii,3,5,9,10,11,31,38,47, restrictions 313
48,58,61,66,86,166,265,306,539,549 ClearPINGenerate(CSNBPGN) 315
dataprotection 19 format 315
chain_dataparameter JNIversion 317
SymmetricAlgorithmDecipherverb 224 parameters 315
SymmetricAlgorithmEncipherverb 229 relatedinformation 317
chain_data_lengthparameter requiredcommands 317
SymmetricAlgorithmDecipherverb 224 usagenotes 317
SymmetricAlgorithmEncipherverb 229 ClearPINGenerateAlternate(CSNBCPA) 318
chaining_vectorparameter extractionrules 480
Decipherverb 215 format 318
Encipherverb 219 JNIversion 321
HMACGenerateverb 236 parameters 318
HMACVerifyverb 239 requiredcommands 320
MACGenerateverb 243 clear_keyparameter
MACVerifyverb 247 ClearKeyImportverb 100
MDCGenerateverb 251 MultipleClearKeyImportverb 180
One-WayHashverb 259 clear_key_bit_lengthparameter
chaining_vector_lengthparameter KeyGenerate2verb 129
HMACGenerateverb 236 KeyTokenBuild2verb 160
HMACVerifyverb 239 clear_key_lengthparameter
One-WayHashverb 259 MultipleClearKeyImportverb 180
changingcontrolvectors 472 clear_key_valueparameter
CHECK 276,297 KeyTokenBuild2verb 160
ChineseRemainderTheorem 183,372,377,378,380, clear_master_keyparameter
389,426,427,428,430,433 KeyStorageInitializationverb 91
CIPHER 102,114,117,123,133,155,170 clear_PINparameter
cipherblockchaining 22 ClearPINEncryptverb 313
cipherblockchaining(CBC) 211 clear_textparameter
CipherBlockChaining(CBC) 107 Decipherverb 215
CIPHERkeytype 27 Encipherverb 218
CIPHERkeys SecureMessagingforKeysverb 349
definition 26 SecureMessagingforPINsverb 352
cipher_textparameter CLEARPIN 351
Decipherverb 214 cleartextparameter
Encipherverb 220 SymmetricAlgorithmDecipherverb 225
Cipher-BlockChaining(CBC)mode xv SymmetricAlgorithmEncipherverb 229
cipheringmethods 494 cleartext_lengthparameter
ciphertext 107 SymmetricAlgorithmDecipherverb 224
deciphering 211 SymmetricAlgorithmEncipherverb 229
ciphertextparameter CLR-A128 144
CryptographicVariableEncipherverb 108 CLR-A192 144
SymmetricAlgorithmDecipherverb 224 CLR-A256 144
SymmetricAlgorithmEncipherverb 230 CLR8-ENC 102,103,114,157,170
ciphertext_lengthparameter CLRAES 155
SymmetricAlgorithmDecipherverb 224 CLRAESkeytype 27
SymmetricAlgorithmEncipherverb 229 CLRDES 156
CLEAR 371 CLRDESkeytype 27
Index 567

CMK 264 ControlVectorGenerate(CSNBCVG) (continued)
CMKstatus 61 keytype 102
coexistence 549 parameters 102
commands usagenotes 103
description 7 controlvectorkeywordcombinations 29
CommonCryptographicArchitecture(CCA) controlvectorlength 74
description xv,xvi controlvectortable 463
commonparameters 14 ControlVectorTranslate(CSNBCVT) 104,472
COMPLET 137 format 104
COMPLETE 136,137,139 JNIversion 106
concurrentinstallations 549 parameters 104
contactIBM xx requiredcommands 105
continueprocessingrule 215,219,223,228 usagenotes 105
controlinformation controlvectors,changing 472
forClearPINEncrypt 313 control_vectorparameter
forClearPINGenerate 315 ControlVectorGenerateverb 103
forControlVectorGenerate 102 KeyTokenBuildverb 157
forControlVectorTranslate 105 KeyTokenParseverb 171
forCVVGenerate 322 Control-vector-basebitmaps 465
forCVVVerify 325 coprocessor
forDecipher 215 batteryindicator 63
forDigitalSignatureGenerate 361 CCAerrorlog 63
forDigitalSignatureVerify 365 intrusionlatch 63
forDiversifiedKeyGenerate 114 lastfivecommands 64
forEncipher 219 numberof 62
forEncryptedPINGenerate 329 power-supplyvoltage 64
forKeyPartImport 137 radiation 64
forKeyTest 144 tampering 64
forKeyTestExtended 151 temperature 64
forKeyTokenChange2 166 coprocessoradapterID 63
forMACGenerate 242 coprocessorcertification 6
forMACVerify 246 coprocessorEClevel 63
forMDCGenerate 250 coprocessorpartnumber 63
forMultipleClearKeyImport 179 coprocessorresourceselection 86,88
forOne-WayHash 258 coprocessorserialnumber 63
forPINChange/Unblock 343 CPACF xvi,xviii,8,10,11,87,213,218,241,245,
forPKADecrypt 182 539
forPKAEncrypt 185 accesscontrolpoints 9
forPKAKeyGenerate 371 clearkey 9
forPKAKeyImport 374 defaultcard 11
forPKAKeyRecordDelete 290 disablingforclearkey 8
forPKAKeyRecordWrite 297 disablingforprotectedkey 9
forPKAKeyTokenBuild 378 environmentvariable 8
forSecureMessagingforKeys 348 illustration 10
forSecureMessagingforPINs 351 preparationatstartup 11
forSymmetricAlgorithmDecipher 222 protectedkey 9
forSymmetricAlgorithmEncipher 227 usingprotectedkey 11
forSymmetricKeyExport 198 CPACFfunctions 11
forSymmetricKeyGenerate 201 CPACFserviceaction 10
forsymmetrickeyimport 208 CPINENC 102,157,170
forSymmetricKeyImport 205 CPINGEN 102,157,170
forTransactionValidation 355 CPINGENA 102,157,170
forTrustedBlockCreate 404 CryptoExpress2feature xv,xvi
controlvector 23,74,102,104,113,115,123,124, CryptoExpress3feature xv
133,155,169,189,213 cryptographicdevicedriver
definition 19,25 installing 537
description 463 cryptographicengine 5
value 463 CryptographicFacilityQuery(CSUACFQ) xviii,31,32,
ControlVectorGenerate(CSNBCVG) 29,102 58,72
format 102 format 58
JNIversion 103 informationreturned 60
568 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

CryptographicFacilityQuery(CSUACFQ) (continued) CSNBCSVJ 327
JNIversion 83 CSNBCVE(CryptographicVariableEncipher) 107
parameters 59 CSNBCVEJ 108
requiredcommands 83 CSNBCVG(ControlVectorGenerate) 102
restrictions 83 CSNBCVGJ 103
CryptographicFacilityVersion(CSUACFV) 84 CSNBCVT(ControlVectorTranslate) 104
format 84 CSNBCVTJ 106
JNIversion 84 CSNBDEC(Decipher) 213
parameters 84 CSNBDECJ 216
restrictions 84 CSNBDKG(DiversifiedKeyGenerate) 113
cryptographickey CSNBDKGJ 116
function 19 CSNBDKM(DataKeyImport) 111
CryptographicResourceAllocate(CSUACRA) 8,31, CSNBDKMJ 112
86 CSNBDKX(DataKeyExport) 109
format 86 CSNBDKXJ 110
JNIversion 87 CSNBENC(Encipher) 217
parameters 86 CSNBENCJ 220
scope 32 CSNBEPG(EncryptedPINGenerate) 328
usagenotes 87 CSNBEPGJ 331
CryptographicResourceDeallocate(CSUACRD) 8, CSNBHMG(HMACGenerate) 235
31,88 CSNBHMGJ 237
format 88 CSNBHMV(HMACVerify) 238
JNIversion 89 CSNBHMVJ 240
parameters 88 CSNBKEX(KeyExport) 117
scope 32 CSNBKEXJ 118
usagenotes 89 CSNBKGN(KeyGenerate) 120
cryptographicservicesaccesslayer 7 CSNBKGN2(KeyGenerate2) 128
CryptographicUnitSupportProgram(CUSP) CSNBKGN2J 132
Decipher 213 CSNBKGNJ 127
Encipher 217 CSNBKIM(KeyImport) 133
CryptographicVariableEncipher(CSNBCVE) 107 CSNBKIMJ 135
format 107 CSNBKPI(KeyPartImport) 136
JNIversion 108 CSNBKPI2(KeyPartImport2) 139
parameters 107 CSNBKPI2J 141
requiredcommands 108 CSNBKPIJ 138
restrictions 108 CSNBKRC(DESKeyRecordCreate) 278
CSC-3 355,356 CSNBKRCJ 278
CSC-345 355,356 CSNBKRD(DESKeyRecordDelete) 280
CSC-4 355,356 CSNBKRDJ 281
CSC-5 355,356 CSNBKRL(DESKeyRecordList) 282
CSNBAKRC(AESKeyRecordCreate) 267 CSNBKRLJ 283
CSNBAKRCJ 268 CSNBKRR(DESKeyRecordRead) 284
CSNBAKRD(AESKeyRecordDelete) 269 CSNBKRRJ 284
CSNBAKRDJ 270 CSNBKRW(DESKeyRecordWrite) 286
CSNBAKRL(AESKeyRecordList) 271 CSNBKRWJ 287
CSNBAKRLJ 272 CSNBKSI(KeyStorageInitialization) 90
CSNBAKRR(AESKeyRecordRead) 274 CSNBKSIJ 91
CSNBAKRRJ 275 CSNBKTB(KeyTokenBuild) 155
CSNBAKRW(AESKeyRecordWrite) 276 CSNBKTB2(KeyTokenBuild2) 159
CSNBAKRWJ 277 CSNBKTB2J 162
CSNBCKI(ClearKeyImport) 100 CSNBKTBJ 157
CSNBCKIJ 100 CSNBKTC(KeyTokenChange) 163
CSNBCKM(MultipleClearKeyImport) 179 CSNBKTC2(KeyTokenChange2) 166
CSNBCKMJ 181 CSNBKTC2J 167
CSNBCPA(ClearPINGenerateAlternate) 318 CSNBKTCJ 165
CSNBCPAJ 321 CSNBKTP(KeyTokenParse) 169
CSNBCPE(ClearPINEncrypt) 312 CSNBKTPJ 172
CSNBCPEJ 314 CSNBKTR(KeyTranslate) 173
CSNBCSG(CVVGenerate) 322 CSNBKTR2(KeyTranslate2) 175
CSNBCSGJ 324 CSNBKTR2J 177
CSNBCSV(CVVVerify) 325 CSNBKTRJ 174
Index 569

CSNBKYT(KeyTest) 143 CSNDPKBJ 383
CSNBKYT2(KeyTest2) 147 CSNDPKD(PKADecrypt) 182
CSNBKYT2J 149 CSNDPKDJ 184
CSNBKYTJ 146 CSNDPKE(PKAEncrypt) 185
CSNBKYTX(KeyTestExtended) 150 CSNDPKEJ 187
CSNBKYTXJ 153 CSNDPKG(PKAKeyGenerate) 370
CSNBMDG(MDCGenerate) 249 CSNDPKGJ 373
CSNBMDGJ 251 CSNDPKI(PKAKeyImport) 374
CSNBMGN(MACGenerate) 241 CSNDPKIJ 376
CSNBMGNJ 243 CSNDPKT(PKAKeyTranslate) 388
CSNBMKP(MasterKeyProcess) 93 CSNDPKTJ 390
CSNBMKPJ 96 CSNDPKX(PKAPublicKeyExtract) 392
CSNBMVR(MACVerify) 245 CSNDPKXJ 393
CSNBMVRJ 248 CSNDRKD(RetainedKeyDelete) 299
CSNBOWH(One-WayHash) 258 CSNDRKDJ 300
CSNBOWHJ 260 CSNDRKL(RetainedKeyList) 301
CSNBPCU(PINChange/Unblock) 342 CSNDRKLJ 302
CSNBPCUJ 346 CSNDRKX(RemoteKeyExport) 394
CSNBPEX(ProhibitExport) 188 CSNDRKXJ 401
CSNBPEXJ 188 CSNDSYG(SymmetricKeyGenerate) 201
CSNBPEXX(ProhibitExportExtended) 189 CSNDSYGJ 204
CSNBPEXXJ 189 CSNDSYI(SymmetricKeyImport) 205
CSNBPGN(ClearPINGenerate) 315 CSNDSYI2(SymmetricKeyImport2) 208
CSNBPGNJ 317 CSNDSYI2J 210
CSNBPTR(EncryptedPINTranslate) 332 CSNDSYIJ 207
CSNBPTRJ 336 CSNDSYX(SymmetricKeyExport) 198
CSNBPVR(EncryptedPINVerify) 338 CSNDSYXJ 200
CSNBPVRJ 341 CSNDTBC(TrustedBlockCreate) 403
CSNBRKA(RestrictKeyAttribute) 195 CSNDTBCJ 406
CSNBRKAJ 196 CSU_DEFAULT_ADAPTER 31,87,89
CSNBRNG(RandomNumberGenerate) 191 CSU_HCPUACLR 8,251
CSNBRNGJ 191 affectedverbs 8
CSNBRNGL(RandomNumberGenerateLong) 193 CSU_HCPUAPRT 8,9
CSNBRNGLJ 194 affectedverbs 9
CSNBSAD(SymmetricAlgorithmDecipher) 221 CSUACFQ(CryptographicFacilityQuery) 58
CSNBSADJ 225 CSUACFQJ 83
CSNBSAE(SymmetricAlgorithmEncipher) 226 CSUACFV(CryptographicFacilityVersion) 84
CSNBSAEJ 230 CSUACFVJ 85
CSNBSKY(SecureMessagingforKeys) 348 CSUACRA(CryptographicResourceAllocate) 86
CSNBSKYJ 350 CSUACRAJ 87
CSNBSPN(SecureMessagingforPINs) 351 CSUACRD(CryptographicResourceDeallocate) 88
CSNBSPNJ 354 CSUACRDJ 89
CSNBTRV(TransactionValidation) 355 CSUAESDS 262,267,269,271,274,276,552
CSNBTRVJ 357 CSUAESLD 272,552
CSNDDSG(DigitalSignatureGenerate) 360 CSUARNT(RandomNumberTests) 97
CSNDDSGJ 363 CSUARNTJ 98
CSNDDSV(DigitalSignatureVerify) 364 CSUCACHE 8
CSNDDSVJ 366 CSUDESDS 262,278,280,282,284,286
CSNDKRC(PKAKeyRecordCreate) 288 CSUPKADS 262,288,290,292,295,297
CSNDKRCJ 289 current_reference_PIN_blockparameter
CSNDKRD(PKAKeyRecordDelete) 290 PINChange/Unblockverb 344
CSNDKRDJ 291 current_reference_PIN_key_identifierparameter
CSNDKRL(PKAKeyRecordList) 292 PINChange/Unblockverb 344
CSNDKRLJ 293 current_reference_PIN_key_lengthparameter
CSNDKRR(PKAKeyRecordRead) 295 PINChange/Unblockverb 344
CSNDKRRJ 296 current_reference_PIN_PAN_dataparameter
CSNDKRW(PKAKeyRecordWrite) 297 PINChange/Unblockverb 345
CSNDKRWJ 298 current_reference_PIN_profileparameter
CSNDKTC(PKAKeyTokenChange) 385 PINChange/Unblockverb 344
CSNDKTCJ 387 CUSPprocessingrule 215,219
CSNDPKB(PKAKeyTokenBuild) 377
570 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

customer_dataparameter datakey (continued)
PKAKeyTokenBuildverb 382 import 111
customer_data_lengthparameter importing 100
PKAKeyTokenBuildverb 382 re-encipher 109
CV 156,170 DataKeyExport(CSNBDKX) 109
CVARDEC 102,123,124,155,170 format 109
CVARDECkeytype 27 JNIversion 109
CVARENC 102,107,123,124,155,170 parameters 109
CVARENCkeytype 27 requiredcommands 109
CVARPINE 102,123,155,170 restrictions 109
CVARPINEkeytype 27 DataKeyImport(CSNBDKM) 111
CVARXCVL 102,104,123,155,170 format 111
CVARXCVLkeytype 27 JNIversion 112
CVARXCVR 102,104,123,155,170 parameters 111
CVARXCVRkeytype 27 requiredcommands 111
CVVGenerate(CSNBCSG) 322 restrictions 111
format 322 usagenotes 111
JNIversion 324 DATAkeysubtype 28
parameters 322 DATAkeytype 27
requiredcommands 324 dataparameter
CVVVerify(CSNBCSV) 325 DiversifiedKeyGenerateverb 115
format 325 data_arrayparameter
JNIversion 327 ClearPINGenerateAlternateverb 320
parameters 325 ClearPINGenerateverb 316
requiredcommands 327 EncryptedPINGenerateverb 329
CVV_key_A_Identifierparameter EncryptedPINVerifyverb 340
CVVGenerateverb 323 data_lengthparameter
CVVVerifyverb 326 DiversifiedKeyGenerateverb 115
CVV_key_B_Identifierparameter data_structureparameter
CVVGenerateverb 323 PKADecryptverb 183
CVVVerifyverb 326 PKAEncryptverb 186
CVV_valueparameter data_structure_lengthparameter
CVVGenerateverb 323 PKADecryptverb 183
CVVVerifyverb 326 PKAEncryptverb 186
CVV-1 323,326 data-encryptingkey
CVV-2 323,326 definition 25
CVV-3 323,326 generating 459
CVV-4 323,326 length 25
CVV-5 323,326 DATAC 25,102,114,117,133,155,170,459
CVVKEY-A 102,157,170 DATACkeytype 27
CVVKEY-Akeysubtype 28 DATAM 26,102,114,117,118,123,133,155,170,
CVVKEY-B 102,157,170 459
CVVKEY-Bkeysubtype 28 DATAMkeytype 27
DATAMV 102,114,117,123,133,155,170
DATAMVkeytype 27
D
dataset_nameparameter
DALL 102,157,170 AESKeyRecordListverb 272
data DESKeyRecordListverb 282
decipher 36 PKAKeyRecordListverb 293
deciphering 213 dataset_name_lengthparameter
encipher 36 AESKeyRecordListverb 272
enciphering 217 DESKeyRecordListverb 282
protecting 211 PKAKeyRecordListverb 293
DATA 102,111,114,117,120,122,123,133,155, DATAXLAT 123
157,170,173,179,198,201,205,213,459 DATAXLATkeytype 27
dataconfidentiality 3 date 65
dataintegrity 3 dayoftheweek 66
managing 36 DDATA 102,157,170
verifying 233 de-allocatingacoprocessorresource 88
datakey DECIPHER 102,117,123,133,155,170
export 109 Decipher(CSNBDEC) 213
Index 571

Decipher(CSNBDEC) (continued) DESKeyRecordWrite(CSNBKRW) (continued)
format 214 restrictions 286
JNIversion 215 DESkeystorage 90,261
parameters 214 DESkeytoken 107
requiredcommands 215 DESkey-storageinitialization 90
restrictions 215 DESNMK 67,68,69,70,71
DECIPHERkeytype 27 DESOMK 67,68,69,70,72
Decipherprocessingrule 213 DESverb 40
defaultcard 11 devicekey 6
DES 156,164,179,198,201,205 DEXP 102,157,170
DESalgorithm 19,36,211 digitalsignature 3
DESCMK 67,68,69,70,71 using 360
DEScryptographickeyverb 100 DigitalSignatureGenerate(CSNDDSG) 360
DEScryptography 19 format 360
DESencryption JNIversion 363
56-bit 65 parameters 360
triple 212 requiredcommands 362
DESencryptionalgorithm 215 restrictions 362
DESencryptionalgorithmprocessingrule 219 digitalsignatureverb 48
DESengine 7 DigitalSignatureVerify(CSNDDSV) 364
DESexternalkeytokenformat 424 format 364
DEShardwareversion 62 JNIversion 366
DESinternalkeytokenformat 421 parameters 364
DESkey 9 relatedinformation 366
managing 99 requiredcommands 366
questionable 95 restrictions 366
translation 9 DIMP 102,157,170
DESkeyflow 20 directoryserver 7
DESKeyRecordCreate(CSNBKRC) 278 DiversifiedKeyGenerate(CSNBDKG) 113
format 278 format 113
JNIversion 278 JNIversion 116
parameters 278 parameters 113
relatedinformation 278 requiredcommands 115
requiredcommands 278 usagenotes 116
restrictions 278 DKYGENKY 102,114,115,123,155,170
DESKeyRecordDelete(CSNBKRD) 280 DKYGENKYkeytype 27
format 280 DKYL0 102,157,170
JNIversion 281 DKYL1 102,157,170
parameters 280 DKYL2 102,157,170
relatedinformation 281 DKYL3 102,157,170
requiredcommands 280 DKYL4 102,157,170
restrictions 280 DKYL5 102,157,170
DESKeyRecordList(CSNBKRL) 282 DKYL6 102,157,170
format 282 DKYL7 102,157,170
JNIversion 283 DMAC 102,157,170
parameters 282 DMKEY 102,157,170
relatedinformation 283 DMPIN 102,157,170
requiredcommands 283 DMV 102,157,170
DESKeyRecordRead(CSNBKRR) 284 DOUBLE 102,122,157,170,202
format 284 doublelengthkey 22,23
JNIversion 284 double-lengthkey
parameters 284 multipledecipherment 508
relatedinformation 284 multipleencipherment 507
requiredcommands 284 using 27
restrictions 284 DPVR 102,157,170
DESKeyRecordWrite(CSNBKRW) 286 DUKPT-BH 334
format 286 DUKPT-IP 334,340
JNIversion 286 DUKPT-OP 334
parameters 286 dynamicRAM(DRAM)memory
relatedinformation 286 size 63
requiredcommands 286
572 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

E EncryptedPINVerify(CSNBPVR) (continued)
format 338
EClevel
JNIversion 341
coprocessor 63
parameters 338
ECBprocessingrule 223,228
relatedinformation 341
ECC 374,385
requiredcommands 341
ECCkey 360,364
encrypted_PIN_blockparameter
ECCkeytoken 436
ClearPINEncryptverb 313
associateddata 438,439
ClearPINGenerateAlternateverb 318
ECC-PAIR 378,379
EncryptedPINGenerateverb 330
ECC-PUBL 378,379
EncryptedPINVerifyverb 339
ECDSA xv,47,360,361,362,364,365
encryptionalgorithmprocessingrule
ECDSAalgorithm 47
AES 222,228
ECI-1 336
DES 215,219
ECI-2PINblockformat 308,479
encryption_issuer_master_key_identifierparameter
ECI-3PINblockformat 308,479
PINChange/Unblockverb 343
ECI-4 336
encryption_issuer_master_key_lengthparameter
editionnotice ii
PINChange/Unblockverb 343
electroniccodebook(ECB) 211,504
ENH-ONLY 102,115,156,157,164,170,176,180,
ElectronicCodeBook(ECB)
202,206
SymmetricAlgorithmDecipher 221
entrypoint 12
SymmetricAlgorithmEncipher 226
entrypointname
EllipticCurveCryptography(ECC) xv,15,25,91
prefix 12
keytoken 47,48,49,51,90,263,360,361,364,
entry-pointnames 12
370,371,374,377,378
EnvironmentIdentifier(EID) 65
EllipticCurveDigitalSignatureAlgorithm(ECDSA) xv,
environmentvariable 542
47,361,362,365
CSU_DEFAULT_ADAPTER 31,87,89
EMV2000 114
CSU_HCPUACLR 8,251
EMVMACsmartcardstandard 503
CSU_HCPUAPRT 8
EMVMAC 242,246
CSUAESDS 262,269,271,274,276,552
EMVMACD 242,246
CSUAESLD 272,552
ENC-ZERO 143,145,150
CSUCACHE 8
ENCIPHER 102,117,123,133,155,170
CSUDESDS 262,267,278,280,282,284,286
Encipher(CSNBENC) 217
CSUPKADS 262,288,290,292,295,297
format 218
keystorage 549,551
JNIversion 220
list 551
parameters 218
PATH 16
requiredcommands 220
EPINGEN 102,157,170
restrictions 220
EPINGENA 102,157,170
ENCIPHERkeytype 27
EPINGENAkeysubtype 28
Encipherprocessingrule 217
EPINVER 102,157,170
enciphered_textparameter
Europaypaddingrule 241
SecureMessagingforKeysverb 349
EVEN 191,193
SecureMessagingforPINsverb 353
evenparity 136,191,193
encryptzerosDES-keyverification 493
EX 121,202
encryptedkey
EXkeyform 459
definition 30
EXEX 102,121,157,170
EncryptedPINGenerate(CSNBEPG) 328
EXEXkeyform 461
format 328
exit_dataparameter 14
JNIversion 331
exit_data_lengthparameter 14
parameters 328
expiration_dateparameter
requiredcommands 330
CVVGenerateverb 323
restrictions 330
CVVVerifyverb 326
EncryptedPINTranslate(CSNBPTR) 306,332
EXPORT 102,157,170
extractionrules 480
exportablekey
format 332
generating 459
JNIversion 336
exportablekeyform
parameters 332
definition 20
requiredcommands 335
value 120
usagenotes 336
EXPORTER 102,117,123,133,155,170,173
EncryptedPINVerify(CSNBPVR) 306,338
extractionrules 479
Index 573

exporterkeyencryptingkey generating_key_identifierparameter
anyDESkey 117 DiversifiedKeyGenerateverb 115
EXPORTERkeytype 27 GermanBankingPoolPINalgorithm 481
exporterkey-encryptingkey 26,109 GET-UDX 60,66,73
exporter_key_identifierparameter
DataKeyExportverb 109
H
KeyExportverb 118
EXTERNAL 156,157,170 hardwarerequirements xvii
externalkey 150 HardwareSecurityModule(HSM) 34
externalkeytoken 15,21,51,444 hashalgorithm 10
DES 424 hashformatting 513
PKA hashparameter
RSAprivate 427 DigitalSignatureGenerateverb 362
verbs 22 DigitalSignatureVerifyverb 365
extra_dataparameter One-WayHashverb 259
RemoteKeyExportverb 399 hashpattern 74,76,78,81
extra_data_lengthparameter hash_lengthparameter
RemoteKeyExportverb 399 DigitalSignatureGenerateverb 361
extractionrules,PIN 479 DigitalSignatureVerifyverb 365
One-WayHashverb 259
HashedMessageAuthenticationcode(HMAC) xv
F
hashing 37
files hashingfunctions 37
hikmNativeInteger.html 17 hashingverb 40
keystorage 33 HCPUACLR 86,88
financialservicesverb 303 HCPUAPRT 86,88
FIPS-RNT 97 HEX-8 242,246
FIRST 136,137,139,236,239,242,246,250,259 HEX-9 242,247
flashEPROMmemory HEXDIGIT 319
size 63 HEXDIGITPINextractionmethodkeyword 308
formparameter highresolutionpollingtimer 538
RandomNumberGenerateverb 191 hikmNativeInteger
formatcontrol 309 description 17
formats hikmNativeInteger.htmlfile 17
PIN 37 HMAC 128,140,147,159,160,166,167,195,198,
formattinghashesandkeys 513 208,235,238
functionaloverview,CCA 4 HMACalgorithm 23
HMACGenerate(CSNBHMG) 235
format 235
G
JNIversion 237
GBP-PIN 102,157,170,329,339 parameters 235
GBP-PINalgorithm 339 relatedinformation 237
GBP-PINO 102,157,170 requiredcommands 236
GENERATE 143,145,147,150,160,356 restrictions 236
generated_key_identifierparameter HMACkey 128,131
DiversifiedKeyGenerateverb 115 HMACkeytoken 439
generated_key_identifier_1parameter HMACkeytype 27
KeyGenerateverb 125 HMACkeys
KeyGenerate2verb 131 definition 26
generated_key_identifier_1_lengthparameter HMACverb 40
KeyGenerate2verb 130 HMACVerify(CSNBHMV 238
generated_key_identifier_2parameter format 238
KeyGenerateverb 125 JNIversion 240
KeyGenerate2verb 131 parameters 238
generated_key_identifier_2_lengthparameter relatedinformation 240
KeyGenerate2verb 131 requiredcommands 239
generated_key_tokenparameter usagenotes 240
PKAKeyGenerateverb 372 HMACVERkeytype 27
generated_key_token_lengthparameter hostCPUacceleration 213,218,241,245
PKAKeyGenerateverb 372 howtousethisdocument xviii
574 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

I input_block_identifier_lengthparameter
TrustedBlockCreateverb 404
IBM
input_KEK_identifierparameter
contacting xx
KeyTranslate2verb 176
IBM3624 315,338
input_KEK_key_identifierparameter
IBM4764CryptoExpress2feature xvii
KeyTranslateverb 173
IBM4765CryptoExpress3feature xvii
input_KEK_lengthparameter
IBMGBP 338
KeyTranslate2verb 176
IBM-PIN 102,157,170,329,339
input_key_identifierparameter
IBM-PINalgorithm 339
SecureMessagingforKeysverb 348
IBM-PINO 102,157,170,319,339
input_key_lengthparameter
IBM-PINOalgorithm 339
KeyTranslate2verb 176
ICVselectionprocessingrule
input_key_tokenparameter
continue 215,219,223,228
KeyTranslateverb 173
initial 215,219,223,228
KeyTranslate2verb 176
IEKYXLATkeytype 27
input_PAN_dataparameter
IKEYXLAT 26,102,117,123,133,155,170,173
SecureMessagingforPINsverb 352
IM 121,202
input_PIN_blockparameter
IMkeyform 459
SecureMessagingforPINsverb 352
IMEX 102,121,157,170
input_PIN_encrypting_key_identifierparameter
IMEXkeyform 461
EncryptedPINTranslateverb 332
IMIM 102,121,157,170
EncryptedPINVerifyverb 338
IMP-PKA 117
input_PIN_profileparameter
IMP-PKAkeytype 27
EncryptedPINTranslateverb 332
IMPORT 102,157,170
EncryptedPINVerifyverb 338
importablekey
SecureMessagingforPINsverb 352
generating 459
input/output(I/O)parameter 13
importablekeyform
InterbankPIN 45,305,315,338
definition 20
intermediatePIN-block(IPB) 478
value 120
INTERNAL 156,157,160,170
IMPORTER 102,111,117,123,133,155,170,173
internalkeytoken 15,51
IMPORTERkeytype 27
AES 421
importerkey-encryptingkey 26
clear 423
importer_key_identifierparameter
definition 21
DataKeyImportverb 111
DES 421,423
KeyImportverb 134
PKA
PKAKeyImportverb 375
RSAprivate 430,431,432,436,438,439
RemoteKeyExportverb 398
intrusionlatch 63
importer_key_identifier_lengthparameter
IPB(intermediatePIN-block) 478
RemoteKeyExportverb 398
IPINENC 102,117,123,133,155,170
INACTIVE 404
IPINENCkeytype 27,332
INBKPIN 315
IPSprocessingrule 215,219
INBK-PIN 102,157,170,329,338,339
ISO16609TDESMAC 503
InformationProtectionSystem(IPS)
ISO9796 365
Decipher 213
ISO9796-1 360,364
Encipher 217
ISOformat0 307,477
initialprocessingrule 215,219,223,228
ISOformat1 307,478
initialization_vectorparameter
ISOformat2 478
CryptographicVariableEncipherverb 107
ISOformat3 478
Decipherverb 214
ISOformat3 307
Encipherverb 218
ISO-0PINblockformat 308,477
SecureMessagingforKeysverb 349
ISO-1PINblockformat 308,478
SecureMessagingforPINsverb 353
ISO-2PINblockformat 308,478
SymmetricAlgorithmDecipherverb 224
ISO-3PINblockformat 308,478
SymmetricAlgorithmEncipherverb 229
ISO-9796 361
initialization_vector_lengthparameter
ITER-38 371
SymmetricAlgorithmDecipherverb 224
ivp.e xviii
SymmetricAlgorithmEncipherverb 229
command 553
initializingkeystorage 90
utility 31,553
input_block_identifierparameter
TrustedBlockCreateverb 405
Index 575

J key (continued)
separation 19
Java
single-length 459,460
datatypes 17
symmetricmasterkey 25
entrypointnames 17
translated 10,11
supportedversions 16
transport 26
JavaBytecode 17
triplelengthDES 23
running 17
type 25
Javainteraction 3
VISAPVV 318
JavaNativeInterface(JNI) xvi,16
wrapping 10,23
Bytecode 17
KEY 156,170
JNI xvi
keycache 8
keycache,hostside 8
K keyencryptingkey 120,133,173,175,189,394
distribution 34
KAT 97 exporter 117
KDFinCounterMode 23 new 9
kek_key_identifierparameter keyencryptingkeyvariant
KeyTestExtendedverb 153 definition 20
KEK_key_identifierparameter keyexport 195
ControlVectorTranslateverb 104 KeyExport(CSNBKEX) 117
ProhibitExportExtendedverb 189 format 117
KEK_key_identifier_1parameter JNIversion 118
KeyGenerateverb 124 parameters 117
KEK_key_identifier_2parameter requiredcommands 118
KeyGenerateverb 124 restrictions 118
key usagenotes 118
AESmasterkey 25 keyform 120,124,459
asymmetricmasterkey 25 combinationsforakeypair 126
CIPHER 26 combinationswithkeytype 126
clear 10,11,30 definition 20
controlvector 19,25 exportable 20
datakey importable 20
export 109 operational 20
importing 100 value 120
re-enciphering 109 keyformbits 468
data-encrypting 25 keyformats 421
DECIPHER 26 keyformatting 513
doublelength 22 keyfunctions 11
double-length 460,461 KeyGenerate(CSNBKGN) 120
ENCIPHER 26 format 120
encrypted 30,128 JNIversion 127
exporterkey-encrypting 26 parameters 120
form 20 requiredcommands 125
generating usagenotes 126
encrypted 120 using 459
HMAC 26 KeyGenerate2(CSNBKGN2) 128
importerkey-encrypting 26 format 128
key-encrypting 26 JNIversion 132
MAC 26 parameters 128
master 10 requiredcommands 131
multipledecipherment/encipherment 504 restrictions 131
NOCVImportersandExporters 26 usagenotes 131
pair 460,461 keygeneratingkey 113
parity 100 definition 27
PIN 26 keyidentifier 11,15
PIN-encryptingkey 332 definition 51
protected 10,11 PKA 50
protecting 211 keyidentifierparameter
re-encipher 133 ClearKeyImportverb 100
re-enciphering 117 KeyImport(CSNBKIM) 133
576 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

KeyImport(CSNBKIM) (continued) KeyTest2(CSNBKYT2) (continued)
format 133 JNIversion 148
JNIversion 135 parameters 147
parameters 133 requiredcommands 148
requiredcommands 134 restrictions 148
restrictions 134 usagenotes 148
usagenotes 134 keytoken 11,15,23,109,111,113,115,117,123,
keylabel 7,15,51,107,117,261,262 133,155,159,169,175,179,189,195,198,208,
keylength 74 238,267,403,444
keymanagement 3,34 AES 421
PKA 49 definition 21
keypair 126 DES
keypairgeneration 504 external 421,424
keypart 93,94,150 internal 421
KeyPartImport(CSNBKPI) 136 null 421,425
format 136 DESinternal 423
JNIversion 138 ECC 436,438,439
parameters 136 EllipticCurveCryptography(ECC) 47,48,49,51,
requiredcommands 138 90,263,360,361,364,370,371,374,377,378
restrictions 138 external 15,21
KeyPartImport2(CSNBKPI2) 139 HMAC 439
format 139 internal 15,21,51
JNIversion 141 null 22
parameters 139 operational 15
requiredcommands 141 PKA 48
restrictions 141 null 439
usagenotes 141 RSA1024-bitmodulus-exponentprivate
keypartregister 73 external 428
keypartregisterhash 74 RSA1024-bitprivateinternal 431,432,436,
keyrecord 33,90 438,439
caching 8 RSA2048-bitChineseRemainderTheorem
keyrule 144 privateexternal 428
keystorage 7,8,93,117,136,173,261,265,549, RSA2048-bitChineseRemainderTheorem
551 privateinternal 433
environmentvariables 262 RSAprivate 426,427,428
LinuxonIBMSystemz 263 RSAprivateexternal 427
keystoragefile 33,266,553 RSAprivateinternal 430
KeyStorageInitialization(CSNBKSI) 90 RSApublic 426
format 90 variableModulus-Exponent 435
JNIversion 91 PKAexternal 52
parameters 90 verbs 21
requiredcommands 91 KeyTokenBuild(CSNBKTB) 29,155
restrictions 91 format 155
keysubtype JNIversion 157
list 28 parameters 155
specifiedbyrule_array 28 usagenotes 157
KeyTest(CSNBKYT) 143 KeyTokenBuild2(CSNBKTB2) 159
format 144 format 159
JNIversion 146 JNIversion 162
parameters 144 parameters 159
requiredcommands 145 restrictions 161
usagenotes 146 KeyTokenChange(CSNBKTC) 163
KeyTestExtended(CSNBKYTX) 150 format 163
format 151 JNIversion 165
JNIversion 153 parameters 163
parameters 151 requiredcommands 164
requiredcommands 153 KeyTokenChange2(CSNBKTC2) 166
restrictions 153 format 166
usagenotes 153 JNIversion 167
KeyTest2(CSNBKYT2) 147 parameters 166
format 147 requiredcommands 167
Index 577

KeyTokenChange2(CSNBKTC2) (continued) key_identifierparameter
restrictions 167 ClearKeyImportverb 100
KeyTokenParse(CSNBKTP) 169 Decipherverb 214
format 169 DiversifiedKeyGenerateverb 115
JNIversion 172 Encipherverb 218
parameters 169 HMACGenerateverb 236
usagenotes 171 HMACVerifyverb 239
KeyTranslate(CSNBKTR) 173 KeyPartImportverb 137
format 173 KeyTestExtendedverb 152
JNIversion 174 KeyTestverb 145
parameters 173 KeyTest2verb 148
requiredcommands 173 KeyTokenChangeverb 164
restrictions 173 KeyTokenChange2verb 167
KeyTranslate2(CSNBKTR2) 175 MACGenerateverb 241
format 175 MACVerifyverb 245
JNIversion 177 MultipleClearKeyImportverb 180
parameters 175 PKAKeyTokenChangeverb 386
requiredcommands 177 ProhibitExportverb 188
restrictions 177 RestrictKeyAttributeverb 196
keytranslationcache 10 SymmetricAlgorithmDecipherverb 223
keytype 15,19,102,124,133,155,459 SymmetricAlgorithmEncipherverb 228
list 27 key_identifier_lengthparameter
keytype1 460,461 HMACGenerateverb 236
keytype2 460,461 HMACVerifyverb 239
keyverificationpattern 93,143,147 KeyTest2verb 148
keywrapping 128,175 KeyTokenChange2verb 167
AES 22 MultipleClearKeyImportverb 180
definition 22 PKAKeyTokenChangeverb 386
DES 22 RestrictKeyAttributeverb 195
electroniccodebook 22 SymmetricAlgorithmDecipherverb 223
enhancedCBC 23 SymmetricAlgorithmEncipherverb 228
key_check_parametersparameter key_labelparameter
RemoteKeyExportverb 400 AESKeyRecordCreateverb 267
key_check_parameters_lengthparameter AESKeyRecordDeleteverb 269
RemoteKeyExportverb 400 AESKeyRecordListverb 271
key_check_valueparameter AESKeyRecordReadverb 274
RemoteKeyExportverb 400 AESKeyRecordWriteverb 276
key_check_value_lengthparameter DESKeyRecordCreateverb 278
RemoteKeyExportverb 400 DESKeyRecordDeleteverb 280
key_encrypting_key_identifierparameter DESKeyRecordListverb 282
KeyTest2verb 148 DESKeyRecordReadverb 284
RestrictKeyAttributeverb 196 DESKeyRecordWriteverb 286
SecureMessagingforKeysverb 348 PKAKeyRecordListverb 293
SymmetricKeyGenerateverb 202 RetainedKeyDeleteverb 299
key_encrypting_key_identifier_1parameter key_label_maskparameter
KeyGenerate2verb 130 RetainedKeyListverb 301
key_encrypting_key_identifier_1_lengthparameter key_labelsparameter
KeyGenerate2verb 130 RetainedKeyListverb 302
key_encrypting_key_identifier_2parameter key_labels_countparameter
KeyGenerate2verb 130 RetainedKeyListverb 302
key_encrypting_key_identifier_2_lengthparameter key_lengthparameter
KeyGenerate2verb 130 KeyGenerateverb 121
key_encrypting_key_identifier_lengthparameter key_nameparameter
KeyTest2verb 148 KeyTokenBuild2verb 161
RestrictKeyAttributeverb 196 SymmetricKeyImportverb 209
key_formparameter key_name_1parameter
KeyGenerateverb 120 KeyGenerate2verb 129
key_generation_dataparameter key_name_1_lengthparameter
PINChange/Unblockverb 343 KeyGenerate2verb 129
key_generation_data_lengthparameter key_name_2parameter
PINChange/Unblockverb 343 KeyGenerate2verb 130
578 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

key_name_2_lengthparameter KEY-ENC 144,150
KeyGenerate2verb 130 KEY-ENCD 144,150
key_name_lengthparameter key-encryptingkey 26
KeyTokenBuild2verb 161 description 26
SymmetricKeyImportverb 209 exporter 109
key_offsetparameter key-halfprocessing 474
SecureMessagingforKeysverb 349 KEY-KM 144,150
key_offset_field_lengthparameter KEY-MGMT 378
SecureMessagingforKeysverb 349 KEY-NKM 144,150
key_parmsparameter KEY-OKM 144,150
SymmetricAlgorithmDecipherverb 223 KEY-PART 102,157,170
SymmetricAlgorithmEncipherverb 228 key-storageinitialization 90
key_parms_lengthparameter key-tokenverificationpatterns 492
SymmetricAlgorithmDecipherverb 223 key-verification 491
SymmetricAlgorithmEncipherverb 228 Keyed-HashMessageAuthenticationCode(HMAC)
key_partparameter generating 235
KeyPartImportverb 137 verifying 238
MasterKeyProcessverb 94 KEYGENKY 102,103,114,123,155,170
key_storage_descriptionparameter KEYGENKYkeytype 27
KeyStorageInitializationverb 91 KEYIDENT 223,228
key_storage_description_lengthparameter KEYLN16 102,122,157,170,202
KeyStorageInitializationverb 91 KEYLN24 122,202
key_storage_file_nameparameter KEYLN32 122,202
KeyStorageInitializationverb 91 KEYLN8 102,122,157,170,202
key_storage_file_name_lengthparameter keyvalueparameter
KeyStorageInitializationverb 90 PKAEncryptverb 186
key_tokenparameter keyvalue_lengthparameter
AESKeyRecordCreateverb 268 PKAEncryptverb 185
AESKeyRecordReadverb 274 keywordcombinations 29
AESKeyRecordWriteverb 277 KM-ONLY 378
DESKeyRecordReadverb 284
DESKeyRecordWriteverb 286
L
KeyTokenBuildverb 155
KeyTokenParseverb 169 labelparameter
PKAKeyTokenBuildverb 383 PKAKeyRecordCreateverb 288
key_token_lengthparameter PKAKeyRecordDeleteverb 290
AESKeyRecordCreateverb 267 PKAKeyRecordReadverb 295
AESKeyRecordReadverb 274 PKAKeyRecordWriteverb 297
AESKeyRecordWriteverb 277 LABEL-DL 269,280,290
PKAKeyTokenBuildverb 383 LAST 136,137,139,236,239,242,246,250,259
key_typeparameter legacysupport 549
ControlVectorGenerateverb 102 Linux
KeyExportverb 117 distributionssupported xvii
KeyImportverb 133 mixedconfigurations 553
KeyTokenBuildverb 155 LMTD-KEK 102,157,170
KeyTokenParseverb 169 LMTD-KEKkeysubtype 28
key_type_1parameter loadingamasterkey 93
KeyGenerateverb 123 local_enciphered_key_identifierparameter
KeyGenerate2verb 129 SymmetricKeyGenerateverb 203
key_type_2parameter local_enciphered_key_identifier_lengthparameter
KeyGenerateverb 124 SymmetricKeyGenerateverb 203
KeyGenerate2verb 129
key_valueparameter
KeyTokenBuildverb 157 M
KeyTokenParseverb 171
MAC 26,37,102,114,117,122,123,129,133,155,
key_value_structureparameter
160,170,459
PKAKeyTokenBuildverb 379
lengthkeywords 242,246
key_value_structure_lengthparameter
managing 36
PKAKeyTokenBuildverb 378
MACGenerate(CSNBMGN) 241
KEY-CLR 144,160,223,228
format 241
KEY-CLRD 144
JNIversion 243
Index 579

MACGenerate(CSNBMGN) (continued) MasterCardcard-verificationcode(CVC) 38,303
parameters 241 MasterCardpaddingrule 241
relatedinformation 243 masterkey_verify_parmparameter
requiredcommands 243 KeyTokenBuildverb 157
restrictions 243 MD5 36,258
MACkeytype 27 MDCGenerate(CSNBMDG) 249
MACkeys format 250
definition 26 JNIversion 251
macparameter parameters 250
HMACGenerateverb 236 relatedinformation 252
HMACVerifyverb 239 requiredcommands 251
MACGenerateverb 243 restrictions 251
MACVerifyverb 247 MDCkeyedhash 252
MACVerify(CSNBMVR) 245 MDCparameter
format 245 MDCGenerateverb 251
JNIversion 248 MDC-2 250
methods 245 MDC-4 143,145,150,251
parameters 245 message
relatedinformation 247 authenticating 233
requiredcommands 247 messageauthentication
restrictions 247 definition 36
usagenotes 247 MessageAuthenticationCode(MAC) 36
mac_lengthparameter description 233
HMACGenerateverb 236 generating 233,241
HMACVerifyverb 239 verifying 233,245
MACD 118,133 MessageAuthenticationCode(MAC)calculation
MACLEN4 242,247 method 502
MACLEN6 242,247 micropocessorchipoperatingspeed 63
MACLEN8 243,247 MIDDLE 136,137,139,236,239,242,246,250,259
MACVER 26,37,102,114,117,122,123,129,133, MIN1PART 140
155,170 MIN2PART 140
MACVERkeytype 27 MIN3PART 140
maskarraypreparation 472 minibootfirmwareversion 63
mask_array_leftparameter MIXED 102,157,170
ControlVectorTranslateverb 104 MKVPparameter
mask_array_rightparameter KeyTokenParseverb 171
ControlVectorTranslateverb 105 modesofoperation 211
MASTER 371 ModificationDetectionCode(MDC) 36,233,249,493
masterkey 6,10,133,553 generate 234
changing 265 verify 234
possibleeffectoninternalkeytokens 21 modular-exponentiationengine 7
encipheredkey 133 Modulus-Exponentformat 183,378,388,389,426,
establishing 6 427,431,432,435
masterkeyloading 93 MRP 185
masterkeymanagement 263 multi-coprocessorfunctions 31
MasterKeyProcess(CSNBMKP) 17,93 multiple
format 93 decipherment 504
JNIversion 96 encipherment 504
parameters 93 MultipleClearKeyImport(CSNBCKM) 179
QuestionableDESkeys 95 format 179
requiredcommands 95 JNIversion 180
restriction 16,17 parameters 179
restrictions 94 requiredcommands 180
masterkeyregister 93 usagenotes 180
masterkeyvariant multiprocessing 7
definition 19
masterkeyverification 144
N
master_key_verification_patternparameter
KeyTokenParseverb 171 new_reference_PIN_blockparameter
master-keyloading 90 PINChange/Unblockverb 344
master-keyverification 491
580 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

new_reference_PIN_key_identifierparameter operationalkey (continued)
PINChange/Unblockverb 344 generating 459
new_reference_PIN_key_lengthparameter operationalkeyform
PINChange/Unblockverb 344 definition 20
new_reference_PIN_PAN_dataparameter value 120
PINChange/Unblockverb 344 operationalkeytoken 15
new_reference_PIN_profileparameter operationalprivatekey 47
PINChange/Unblockverb 344 OPEX 102,121,157,170
NISTFIPSPUB140-1 97 OPEXkeyform 460
NISTstandardSP800-108 23,24 OPIM 102,121,157,170
NMK 263 OPIMkeyform 460
NMKstatus 61 OPINENC 102,117,123,133,155,170
nokey 10 OPINENCkeytype 27,332
NO-CV 156,170 OPK,objectprotectionkey 455
no-exportbit 117 OPOP 121,128
NO-KEY 156,160,170 OPOPkeyform 460
NO-SPEC 102,157,170 opt_parameter1parameter
NO-XLATE 378 RestrictKeyAttributeverb 196
NO-XPORT 102,157,170 opt_parameter1_lengthparameter
NOADJUST 105,145,151 RestrictKeyAttributeverb 196
NOCV 20,118,134 opt_parameter2parameter
NOCVImportersandExporters 26 RestrictKeyAttributeverb 196
NOEX-SYM 160,195 opt_parameter2_lengthparameter
NOEXAASY 160,195 RestrictKeyAttributeverb 196
NOEXPORT 195 optional_dataparameter
NOEXUASY 160,195 SymmetricAlgorithmDecipherverb 225
non-repudiation 3 SymmetricAlgorithmEncipherverb 230
NOOFFSET 102,157,170 optional_data_lengthparameter
NOT-KEK 102,157,170 SymmetricAlgorithmDecipherverb 225
NOT-KEKkeysubtype 28 SymmetricAlgorithmEncipherverb 230
Notices 561 otherdocumentation xix
nullkeytoken 51,115,133 outbound_PIN_encrypting_key_identifierparameter
definition 22 EncryptedPINGenerateverb 328
format 425,439 outputchainingvalue(OCV) 496
numberofactivecoprocessors 62 outputchainingvector(OCV)
description 212
output_chaining_vectorparameter
O
SecureMessagingforKeysverb 349
OAEP 513 SecureMessagingforPINsverb 353
objectprotectionkey(OPK) 455 output_KEK_identifierparameter
OCV(outputchainingvalue) 496 KeyTranslate2verb 176
ODD 191,193 output_KEK_key_identifierparameter
oddparity 120,136,151,191,193 KeyTranslateverb 173
OKEYXLAT 26,102,117,123,133,155,170,173 output_KEK_lengthparameter
OKEYXLATkeytype 27 KeyTranslate2verb 176
OMK 264 output_key_lengthparameter
OMKstatus 61 KeyTranslate2verb 176
One-WayHash(CSNBOWH) 258 output_key_tokenparameter
format 258 KeyTranslateverb 173
JNIversion 260 KeyTranslate2verb 177
parameters 258 output_PAN_dataparameter
usagenotes 260 SecureMessagingforPINsverb 352
ONLY 236,239,242,246,250,259 output_PIN_dataparameter
OP 121,128,202 PINChange/Unblockverb 345
OPkeyform 459 output_PIN_data_lengthparameter
operatingspeed PINChange/Unblockverb 345
micropocessorchip 63 output_PIN_encrypting_key_identifierparameter
operatingsystemfirmwarename 62 EncryptedPINTranslateverb 332
operatingsystemfirmwareversion 63 output_PIN_messageparameter
operationalkey 128,179,188,394 PINChange/Unblockverb 345
distribution 34
Index 581

output_PIN_message_lengthparameter personalidentificationnumber(PIN)
PINChange/Unblockverb 345 3624PINgenerationalgorithm 481
output_PIN_profileparameter 3624PINverificationalgorithm 483
EncryptedPINTranslateverb 334 algorithmvalue 319,339
PINChange/Unblockverb 345 algorithms 37,305,315
SecureMessagingforPINsverb 352 blockformat 305,332
overlappedprocessingrestrictions 7 ClearPINGenerateAlternateverb 318
OVERLAY 276,297 ClearPINGenerateverb 315
definition 37
description 303
P
detailedalgorithms 480
paddigit 310 encrypting 305
format 310 encryptingkey 306,332
pad_characterparameter extractionrules 479
Encipherverb 219 formats 37
PADDIGIT 319 GBPPINverificationalgorithm 485
PADDIGITPINextractionmethodkeyword 308 generating 304,305,315
paddingmethod 217 fromencryptedPINblock 305
PADEXIST 319 GermanBankingPoolPINalgorithm 481
PADEXISTPINextractionmethodkeyword 308 InterbankPINgenerationalgorithm 489
PADMDC-2 251 keys 26
PADMDC-4 251 managing 37
pairofkeys 460,461 PINoffsetgenerationalgorithm 482
PAN_dataparameter PVVgenerationalgorithm 488
ClearPINEncryptverb 313 PVVverificationalgorithm 489
ClearPINGenerateAlternateverb 318 translating 305
CVVGenerateverb 323 translationof,innetworks 304
CVVVerifyverb 326 translationverb 332
EncryptedPINGenerateverb 330 using 303
EncryptedPINVerifyverb 339 verificationverb 338
PAN_data_inparameter verifying 305,338
EncryptedPINTranslateverb 333 VISAPINalgorithm 487
PAN_data_outparameter PIN 102,157,170
EncryptedPINTranslateverb 334 PINblock 305
PAN-13 322,325 PINblockformat
PAN-14 322,325 3621 479
PAN-15 322,325 3624 479
PAN-16 322,325 additionalnames 336
PAN-17 322,325 ANSIX9.8 477
PAN-18 322,325 detail 477
PAN-19 322,325 ECI-2 479
panel.exe xviii,11 ECI-3 479
authorization 554 ISO-1 478
functions 553 ISO-2 478
functionsnotsupported 555 PINextractionmethodkeywords 308
utility 25,31,32,58,266,542,544,546,547,553, values 308
554,555,556 VISA-2 479
parityofkey 100 VISA-3 479
EVEN PINChange/Unblock(CSNBPCU) 342
formparameter 191 format 342
ODD JNIversion 346
formparameter 191 parameters 342
partnumber requiredcommands 345
coprocessor 63 usagenotes 346
PATH 16 PINkeysubtype 28
pendingchangestoredinadapter 66 PINkeys 26
pendingchangeuserID 66 PINnotation 477
personalaccountnumber(PAN) 38 PINprofile 307
forEncryptedPINTranslate 333 description 332,338
forEncryptedPINVerify 339 PINvalidationvalue(PVV) 305,315
PINverb 304
582 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

PIN_block_inparameter PKAinternalkeytoken 51
EncryptedPINTranslateverb 333 PKAkey 182,185
PIN_block_outparameter PKAkeyalgorithm 47
EncryptedPINTranslateverb 335 PKAKeyGenerate(CSNDPKG) 370
PIN_check_lengthparameter format 370
ClearPINGenerateAlternateverb 319 JNIversion 373
ClearPINGenerateverb 316 parameters 371
EncryptedPINVerifyverb 340 requiredcommands 372
PIN_encrypting_key_identifierparameter restrictions 372
ClearPINEncryptverb 312 PKAkeyidentifier 50
SecureMessagingforPINsverb 352 PKAKeyImport(CSNDPKI) 374
PIN_encryption_key_identifierparameter format 374
ClearPINGenerateAlternateverb 318 JNIversion 376
PIN_generating_key_identifierparameter parameters 374
ClearPINGenerateverb 315 requiredcommands 375
EncryptedPINGenerateverb 328 restrictions 375
PIN_generation_key_identifierparameter usagenotes 375
ClearPINGenerateAlternateverb 318 PKAkeylabel 50
PIN_lengthparameter PKAkeymanagement 49
ClearPINGenerateverb 316 PKAkeymanagementverb 48
EncryptedPINGenerateverb 329 PKAKeyRecordCreate(CSNDKRC) 288
PIN_offsetparameter format 288
SecureMessagingforPINsverb 353 JNIversion 289
PIN_offset_field_lengthparameter parameters 288
SecureMessagingforPINsverb 353 relatedinformation 289
PIN_profileparameter requiredcommands 288
ClearPINEncryptverb 313 PKAKeyRecordDelete(CSNDKRD) 290
ClearPINGenerateAlternateverb 318 format 290
EncryptedPINGenerateverb 330 JNIversion 291
PIN_verifying_key_identifierparameter parameters 290
EncryptedPINVerifyverb 338 relatedinformation 291
PIN-encryptingkey 332 requiredcommands 290
PINBLOCK 319 PKAKeyRecordList(CSNDKRL) 292
PINBLOCKPINextractionmethodkeyword 308 format 292
PINGEN 102,117,123,133,155,170,459 JNIversion 293
PINGENkey 459 parameters 292
PINGENkeytype 27 relatedinformation 293
PINLENnn 319 requiredcommands 293
PINLEN04PINextractionmethodkeyword 308 PKAKeyRecordRead(CSNDKRR) 295
PINLEN12PINextractionmethodkeyword 308 format 295
PINVER 102,117,123,133,155,170 JNIversion 296
PINVERkey 459 parameters 295
PINVERkeytype 27 relatedinformation 296
PKACMK 67,68,69,70,72 requiredcommands 295
PKAcryptographickey 369 PKAKeyRecordWrite(CSNDKRW) 297
PKAcryptography 47 format 297
PKADecrypt(CSNDPKD) 182 JNIversion 298
format 182 parameters 297
JNIversion 184 relatedinformation 298
parameters 182 requiredcommands 298
requiredcommands 183 PKAkeystorage 90,261
restrictions 183 PKAkeystoragefile 33
usagenotes 183 PKAkeytoken 48,50
PKAEncrypt(CSNDPKE) 185 external 52
format 185 recordformat
JNIversion 187 RSA1024-bitmodulus-exponentprivate
parameters 185 external 428
requiredcommands 186 RSA1024-bitprivateinternal 431,432,436,
restrictions 186 438,439
usagenotes 186 RSA2048-bitChineseRemainderTheorem
PKAexternalkeytoken 51,52 privateexternal 428
Index 583

PKAkeytoken (continued) PKCS1.1 360,361,364,365
recordformat (continued) PKCS-1.2 182,185,199,202,205
RSA2048-bitChineseRemainderTheorem PKCS-PAD
privateinternal 433 SymmetricAlgorithmDecipher 221
RSAprivate 426,427,428 SymmetricAlgorithmEncipher 226
RSAprivateexternal 427 PKCS-PADprocessingrule 223,228
RSAprivateinternal 430 PKCSOAEP 199,202,205
RSApublic 426 PKOAEP2 199,208
variableModulus-Exponent 435 plaintext
PKAKeyTokenBuild(CSNDPKB) 377 encipher 107
format 377 enciphering 211
JNIversion 383 encrypt 107
parameters 377 plaintextparameter
PKAKeyTokenChange(CSNDKTC) 385 CryptographicVariableEncipherverb 107
format 385 POSTfirmwareversion 62
JNIversion 386 power-supplyvoltage 64
parameters 385 privacy 36
requiredcommands 386 privateexternalkeytoken
PKAkeytokenidentifier 49 RSA 427
PKAkeytokensections 48 privateinternalkeytoken
PKAKeyTranslate(CSNDPKT) 388 RSA 430,431,432,436,438,439
format 388 privatekeytoken
JNIversion 390 RSA 426,427,428
parameters 388 private_key_nameparameter
requiredcommands 389 PKAKeyTokenBuildverb 381
restrictions 389 private_key_name_lengthparameter
usagenotes 390 PKAKeyTokenBuildverb 381
PKAmasterkey 47 problems,reporting xx
PKANMK 67,68,69,70,72 procedurecall 12
PKAnullkeytoken 51 processingamasterkey 93
PKAOMK 67,68,69,71,72 processingoverlap 7
PKAPublicKeyExtract(CSNDPKX) 392 processingrule
format 392 ANSIX9.23 211,215,219
JNIversion 393 CBC 212,215,219,223,228
parameters 392 CUSP 212,215,219
usagenotes 393 Decipher 213,215
PKAverb 48,52 description 211
PKA_enciphered_keyvalueparameter ECB 212,223,228
PKADecryptverb 183 Encipher 217,219
PKAEncryptverb 186 GBP-PIN 315
PKA_enciphered_keyvalue_lengthparameter IBM-PIN 315
PKADecryptverb 182 IBM-PINO 315
PKAEncryptverb 186 INBK-PIN 315
PKA_key_identifierparameter IPS 212,215,219
PKADecryptverb 183 PKCS-PAD 212,223,228
PKAEncryptverb 186 recommendationsforEncipher 219
PKA_key_identifier_lengthparameter SymmetricAlgorithmDecipher 221,222
PKADecryptverb 183 SymmetricAlgorithmEncipher 226,227
PKAEncryptverb 186 VISA-PVV 315
PKA_private_key_identifierparameter profile
DigitalSignatureGenerateverb 361 description 7
PKA_private_key_identifier_lengthparameter ProhibitExport(CSNBPEX) 188
DigitalSignatureGenerateverb 361 format 188
PKA_public_key_identifierparameter JNIversion 188
DigitalSignatureVerifyverb 365 parameters 188
PKA_public_key_identifier_lengthparameter requiredcommands 188
DigitalSignatureVerifyverb 365 ProhibitExportExtended(CSNBPEXX) 189
PKA92 201,205 format 189
PKA92keyformatandencryptionprocess 511 JNIversion 189
PKCS#1formats 513 parameters 189
PKCS1.0 360,361,364,365 requiredcommands 189
584 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

ProhibitExportExtended(CSNBPEXX) (continued) RemoteKeyExport(CSNDRKX) (continued)
restrictions 189 restrictions 400
protectedkey 10,11 remotekeyloading
pseudonym 12 ACP 34
publickeycryptography 47 definition 34
publickeytoken newexample 35
RSA 426 oldexample 35
reservedparameter
ControlVectorGenerateverb 103
Q
KeyTest2verb 148
QPENDING 60,66 KeyTokenBuild2verb 161
questionableDESkey 95 reserved_2parameter
KeyTokenParseverb 171
PKAKeyTokenBuildverb 382
R reserved_2_lengthparameter
PKAKeyTokenBuildverb 382
radiation 64
reserved_3parameter
RANDOM 191,193
KeyTokenParseverb 171
randomnumber 191,193
PKAKeyTokenBuildverb 382
RandomNumberGenerate(CSNBRNG) 191
reserved_3_lengthparameter
format 191
PKAKeyTokenBuildverb 382
JNIversion 191
reserved_4parameter
parameters 191
KeyTokenParseverb 171
requiredcommands 191
PKAKeyTokenBuildverb 382
RandomNumberGenerateLong(CSNBRNGL) 193
reserved_4_lengthparameter
format 193
PKAKeyTokenBuildverb 382
JNIversion 194
reserved_5parameter
parameters 193
KeyTokenParseverb 171
RandomNumberTests(CSUARNT) 97
PKAKeyTokenBuildverb 382
format 97
reserved_5_lengthparameter
JNIversion 98
PKAKeyTokenBuildverb 382
parameters 97
reserved_6parameter
random_numberparameter
KeyTokenParseverb 171
KeyTestExtendedverb 152
reserved_lengthparameter
KeyTestverb 145
KeyTest2verb 148
RandomNumberGenerateLongverb 194
KeyTokenBuild2verb 161
RandomNumberGenerateverb 191
resource_nameparameter
random_number_lengthparameter
CryptographicResourceAllocateverb 87
RandomNumberGenerateLongverb 194
CryptographicResourceDeallocateverb 89
reasoncode 407
resource_name_lengthparameter
reasoncodes
CryptographicResourceAllocateverb 87
withreturncode0 408
CryptographicResourceDeallocateverb 89
withreturncode12 418
RestrictKeyAttribute(CSNBRKA) 195
withreturncode16 419
format 195
withreturncode4 408
JNIversion 196
withreturncode8 409
parameters 195
reason_code 15
requiredcommands 196
reason_codeparameter 14
restrictions 196
recommendationsforEncipherprocessingrule 219
usagenotes 196
recordchaining 212
RETAIN 371
REFORMAT 102,157,164,170,175,333
retainedkey 299
regeneration_dataparameter
RetainedKeyDelete(CSNDRKD) 299
PKAKeyGenerateverb 371
format 299
regeneration_data_lengthparameter
JNIversion 300
PKAKeyGenerateverb 371
parameters 299
relatedpublications xx
relatedinformation 300
remotekeydistribution 34
requiredcommands 300
RemoteKeyExport(CSNDRKX) 394
RetainedKeyList(CSNDRKL) 301
format 395
format 301
JNIversion 401
JNIversion 302
parameters 395
parameters 301
requiredcommands 401
Index 585

RetainedKeyList(CSNDRKL) (continued) RSAMEVAR 378
relatedinformation 302 RTCMK 163,166,265,385,386
requiredcommands 302 RTNMK 164,167,264,265,266,385,386
retained_keys_countparameter rule_arrayelement
RetainedKeyListverb 301 lastfivecommands 64
RETRKPR 137 securityAPIreturncode 64
returncode 407 rule_arrayparameter 15
return_code 15 AESKeyRecordCreateverb 267
return_codeparameter 14 AESKeyRecordDeleteverb 269
returned_PVVparameter AESKeyRecordListverb 271
ClearPINGenerateAlternateverb 320 AESKeyRecordReadverb 274
returned_resultparameter AESKeyRecordWriteverb 276
ClearPINGenerateverb 316 ClearPINEncryptverb 312
revisionhistory xv ClearPINGenerateAlternateverb 319
RIPEMD-160 36 ClearPINGenerateverb 315
RKXkeytoken 177 ControlVectorGenerateverb 102
role ControlVectorTranslateverb 105
DEFAULT 7 CryptographicFacilityQueryverb 59
description 7 CryptographicResourceAllocateverb 86
roleidentifier 61,62 CryptographicResourceDeallocateverb 88
RPMD-160 258,361 CVVGenerateverb 322
RSA 361,365,374,385 CVVVerifyverb 325
RSA1024-bitprivateinternalkeytoken 431,432,436, Decipherverb 214
438,439 DESKeyRecordDeleteverb 280
RSAalgorithm 47 DigitalSignatureGenerateverb 360
RSAhardwareversion 62 DigitalSignatureVerifyverb 364
RSAkey 182,185,201,205,208,360,364,370 DiversifiedKeyGenerateverb 114
RSAkeygeneration 504 Encipherverb 219
RSAkeytokensections 51 EncryptedPINGenerateverb 329
RSAkey-pairgeneration 504 EncryptedPINTranslateverb 333
RSAprivateexternalChineseRemainderTheoremkey EncryptedPINVerifyverb 339
token 428 HMACGenerateverb 235
RSAprivateexternalkeytoken 427 HMACVerifyverb 238
RSAprivateexternalModulus-Exponentkeytoken 428 KeyGenerate2verb 128
RSAprivateinternalChineseRemainderTheoremkey KeyPartImportverb 136
token 433 KeyStorageInitializationverb 90
RSAprivateinternalkeytoken 431 KeyTestExtendedverb 151
RSAprivatetoken 426,427,428 KeyTestverb 144
RSApublictoken 426 KeyTest2verb 147
RSAvariableModulus-Exponenttoken 435 KeyTokenBuildverb 156
RSA_enciphered_keyparameter KeyTokenBuild2verb 159
SymmetricKeyExportverb 199 KeyTokenChangeverb 163
SymmetricKeyGenerateverb 203 KeyTokenChange2verb 166
SymmetricKeyImportverb 206,209 KeyTokenParseverb 170
RSA_enciphered_key_lengthparameter KeyTranslate2verb 175
SymmetricKeyExportverb 199 MACGenerateverb 242
SymmetricKeyGenerateverb 203 MACVerifyverb 246
SymmetricKeyImportverb 206,208 MasterKeyProcessverb 94
RSA_private_key_identifierparameter MDCGenerateverb 250
SymmetricKeyImportverb 206,209 MultipleClearKeyImportverb 179
RSA_private_key_identifier_lengthparameter One-WayHashverb 258
SymmetricKeyImportverb 206,209 PINChange/Unblockverb 343
RSA_public_key_identifierparameter PKADecryptverb 182
SymmetricKeyExportverb 199 PKAEncryptverb 185
SymmetricKeyGenerateverb 203 PKAKeyGenerateverb 371
RSA_public_key_identifier_lengthparameter PKAKeyImportverb 374
SymmetricKeyExportverb 199 PKAKeyRecordCreateverb 288
SymmetricKeyGenerateverb 202 PKAKeyRecordDeleteverb 290
RSA-CRT 378,380 PKAKeyRecordListverb 292
RSA-PRIV 378 PKAKeyRecordReadverb 295
RSA-PUBL 378 PKAKeyRecordWriteverb 297
586 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

rule_arrayparameter (continued) rule_array_countparameter (continued)
PKAKeyTokenBuildverb 378 MasterKeyProcessverb 93
PKAKeyTokenChangeverb 385 MDCGenerateverb 250
PKAKeyTranslateverb 388 MultipleClearKeyImportverb 179
PKAPublicKeyExtractverb 392 One-WayHashverb 258
RandomNumberGenerateLongverb 193 PINChange/Unblockverb 342
RandomNumberTestsverb 97 PKADecryptverb 182
RemoteKeyExportverb 396 PKAEncryptverb 185
RestrictKeyAttributeverb 195 PKAKeyGenerateverb 371
RetainedKeyDeleteverb 299 PKAKeyImportverb 374
RetainedKeyListverb 301 PKAKeyRecordCreateverb 288
SecureMessagingforKeysverb 348 PKAKeyRecordDeleteverb 290
SecureMessagingforPINsverb 351 PKAKeyRecordListverb 292
SymmetricAlgorithmDecipherverb 222 PKAKeyRecordReadverb 295
SymmetricAlgorithmEncipherverb 227 PKAKeyRecordWriteverb 297
SymmetricKeyExportverb 198 PKAKeyTokenBuildverb 377
SymmetricKeyGenerateverb 201 PKAKeyTokenChangeverb 385
SymmetricKeyImportverb 205,208 PKAKeyTranslateverb 388
TransactionValidationverb 355 PKAPublicKeyExtractverb 392
TrustedBlockCreateverb 404 RandomNumberGenerateLongverb 193
rule_array_countparameter 15 RandomNumberTestsverb 97
AESKeyRecordCreateverb 267 RemoteKeyExportverb 395
AESKeyRecordDeleteverb 269 RestrictKeyAttributeverb 195
AESKeyRecordListverb 271 RetainedKeyDeleteverb 299
AESKeyRecordReadverb 274 RetainedKeyListverb 301
AESKeyRecordWriteverb 276 SecureMessagingforKeysverb 348
ClearPINEncryptverb 312 SecureMessagingforPINsverb 351
ClearPINGenerateAlternateverb 319 SymmetricAlgorithmDecipherverb 222
ClearPINGenerateverb 315 SymmetricAlgorithmEncipherverb 227
ControlVectorGenerateverb 102 SymmetricKeyExportverb 198
ControlVectorTranslateverb 105 SymmetricKeyGenerateverb 201
CryptographicFacilityQueryverb 59 SymmetricKeyImportverb 205,208
CryptographicResourceAllocateverb 86 TransactionValidationverb 355
CryptographicResourceDeallocateverb 88 TrustedBlockCreateverb 404
CVVGenerateverb 322 rule_idparameter
CVVVerifyverb 325 RemoteKeyExportverb 398
Decipherverb 214
DESKeyRecordDeleteverb 280
S
DigitalSignatureGenerateverb 360
DigitalSignatureVerifyverb 364 sampleverbcalls 527,532
DiversifiedKeyGenerateverb 113 SCCOMCRT 389
Encipherverb 219 SCCOMME 388
EncryptedPINGenerateverb 329 SCVISA 388
EncryptedPINTranslateverb 333 SECMSG 102,103,155,170
EncryptedPINVerifyverb 339 SECMSGkeytype 27
HMACGenerateverb 235 secmsg_key_identifierparameter
HMACVerifyverb 238 SecureMessagingforKeysverb 349
KeyGenerate2verb 128 SecureMessagingforPINsverb 352
KeyPartImportverb 136 secureelectronictransaction(SET)services 65
KeyStorageInitializationverb 90 securemessaging 38
KeyTestExtendedverb 151 SecureMessagingforKeys(CSNBSKY) 348
KeyTestverb 144 format 348
KeyTest2verb 147 JNIversion 350
KeyTokenBuildverb 156 parameters 348
KeyTokenBuild2verb 159 requiredcommands 349
KeyTokenChangeverb 163 usagenotes 349
KeyTokenChange2verb 166 SecureMessagingforPINs(CSNBSPN) 351
KeyTokenParseverb 170 format 351
KeyTranslate2verb 175 JNIversion 354
MACGenerateverb 242 parameters 351
MACVerifyverb 246 requiredcommands 353
Index 587

SecureMessagingforPINs(CSNBSPN) (continued) sizeofbattery-backedRAM 63
usagenotes 354 sizeofdynamicRAM(DRAM)memory 63
SecureSocketsLayer(SSL) 36 sizeofflashEPROMmemory 63
securityAPI 7,12 skeleton_key_identifierparameter
securityAPIprogramming 12 PKAKeyGenerateverb 372
securityAPIreturncode skeleton_key_identifier_lengthparameter
rule_arrayelement 64 PKAKeyGenerateverb 371
securityserver 7,9 SMKEY 102,103,114,157,170
security_server_nameparameter SMPIN 102,103,114,157,170
AESKeyRecordListverb 272 SNA-SLE 497
DESKeyRecordListverb 283 source_key_identifierparameter
PKAKeyRecordListverb 293 DataKeyExportverb 109
seedparameter KeyExportverb 117
RandomNumberGenerateLongverb 193 KeyImportverb 133
seed_lengthparameter PKAKeyImportverb 374
RandomNumberGenerateLongverb 193 PKAKeyTranslateverb 389
segmenting PKAPublicKeyExtractverb 392
controlkeywords 242,246 RemoteKeyExportverb 398
selectingacoprocessorresource 86,88 SymmetricKeyExportverb 199
SELFENC 352 source_key_identifier_lengthparameter
sequence_numberparameter PKAKeyImportverb 374
ClearPINEncryptverb 313 PKAKeyTranslateverb 389
EncryptedPINGenerateverb 330 PKAPublicKeyExtractverb 392
EncryptedPINTranslateverb 334 RemoteKeyExportverb 398
sequencesofverbs 39 SymmetricKeyExportverb 199
serialnumber source_key_tokenparameter
adapter 66,67,68,70,71 ControlVectorTranslateverb 104
coprocessor 63 DataKeyImportverb 111
servicerequest 7 ProhibitExportExtendedverb 189
service_codeparameter source_transport_key_identifierparameter
CVVGenerateverb 323 PKAKeyTranslateverb 389
CVVVerifyverb 326 source_transport_key_identifier_lengthparameter
SESS-XOR 114,115 PKAKeyTranslateverb 389
SETcommand 264 SSLsupport 36
SHA-1 36,143,145,150,160,199,235,238,258, STATAES 59
361 STATAPKA 59
SHA-1engine 7 STATCARD 31,59,62
SHA-224 160,235,238,258 STATCCA 59,61,84
SHA-256 143,145,147,150,160,199,235,238,258, STATCCAE 59,61
361 STATDIAG 59,63
SHA-384 160,199,235,238,258,361 STATEID 59,65
SHA-512 160,199,235,238,258,361 STATEXPT 59,65
SHA2VP1 147 STATICSA 60,68,74
shortblocks 217 STATICSAoperationalkeyparts
SIG-ONLY 378 outputdataformat 74
signature_bit_lengthparameter STATICSB 70,78
DigitalSignatureGenerateverb 362 STATICSBoperationalkeyparts
signature_fieldparameter outputdataformat 78
DigitalSignatureGenerateverb 362 STATICSE 60,71,76
DigitalSignatureVerifyverb 366 STATICSEoperationalkeyparts
signature_field_lengthparameter outputdataformat 76
DigitalSignatureGenerateverb 362 STATICSF 60
DigitalSignatureVerifyverb 366 STATICSX 60,67,81
SIGSEGVerror 10 STATICSXoperationalkeyparts
SINGLE 102,122,157,170,202 outputdataformat 81
single-lengthkey STATKPR 60,66,73
multipledecipherment 506 STATKPRoperationalkeyparts
multipleencipherment 505 outputdataformat 73
purpose 459,460 STATKPRL 60,66,73
using 27 STATMOFN 59
SINGLE-R 122,202
588 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

sym_encrypted_key_identifierparameter target_key_identifierparameter
RemoteKeyExportverb 399 DataKeyExportverb 109
sym_encrypted_key_identifier_lengthparameter DataKeyImportverb 111
RemoteKeyExportverb 399 KeyExportverb 118
SYM-MK 25,47,93,94,95,145,150 KeyImportverb 134
SymmetricAlgorithmDecipher(CSNBSAD) 221 PKAKeyImportverb 375
format 222 SymmetricKeyImportverb 206,209
JNIversion 225 target_key_identifier_lengthparameter
parameters 222 PKAKeyImportverb 375
requiredcommands 225 SymmetricKeyImportverb 206,209
restrictions 225 target_key_tokenparameter
SymmetricAlgorithmDecipherprocessingrule 221 ControlVectorTranslateverb 105
SymmetricAlgorithmEncipher(CSNBSAE) 226 KeyTokenBuild2verb 161
format 227 PKAKeyTranslateverb 389
JNIversion 230 target_key_token_lengthparameter
parameters 227 KeyTokenBuild2verb 161
requiredcommands 230 PKAKeyTranslateverb 389
restrictions 230 target_keyvalueparameter
SymmetricAlgorithmEncipherprocessingrule 226 PKADecryptverb 183
symmetricCMKstatus 61 target_keyvalue_lengthparameter
symmetrickey 34 PKADecryptverb 183
maximummodulussize 65 target_public_key_tokenparameter
SymmetricKeyEncipher/Decipher-EncryptedAES PKAPublicKeyExtractverb 392
keys 9 target_public_key_token_lengthparameter
SymmetricKeyEncipher/Decipher-EncryptedDES PKAPublicKeyExtractverb 392
keys 9 target_transport_key_identifierparameter
SymmetricKeyExport(CSNDSYX) 198 PKAKeyTranslateverb 389
format 198 target_transport_key_identifier_lengthparameter
JNIversion 200 PKAKeyTranslateverb 389
parameters 198 TDES 498
requiredcommands 200 TDESencryption 65
usagenotes 200 TDES-CBC 348,351
SymmetricKeyGenerate(CSNDSYG) 201 TDES-DEC 114
format 201 TDES-ECB 348,351
JNIversion 204 TDES-ENC 114
parameters 201 TDES-MAC 242,246
requiredcommands 203 TDES-XOR 114,343
usagenotes 204 TDESEMV2 114,343
SymmetricKeyImport(CSNDSYI) 205 TDESEMV4 114,343
format 205 temperature 64
JNIversion 207 terminology xvii
parameters 205 textparameter
requiredcommands 206 HMACGenerateverb 236
restrictions 206 HMACVerifyverb 239
usagenotes 207 MACGenerateverb 242
SymmetricKeyImport2(CSNDSYI2) 208 MACVerifyverb 246
format 208 MDCGenerateverb 250
JNIversion 210 One-WayHashverb 259
parameters 208 text_lengthparameter
requiredcommands 209 CryptographicVariableEncipherverb 107
restrictions 209 Decipherverb 214
usagenotes 209 Encipherverb 218
symmetrickeysmasterkey 25 HMACGenerateverb 236
symmetricNMKstatus 61 HMACVerifyverb 239
symmetricOMKstatus 62 MACGenerateverb 241
sysfsinterface xviii,31,32,538 MACVerifyverb 245
MDCGenerateverb 250
One-WayHashverb 259
T
SecureMessagingforKeysverb 349
tableofcontents ii SecureMessagingforPINsverb 352
tampering 64 timeofday 66
Index 589

TIMEDATE 59,65 TrustedBlockCreate(CSNDTBC) (continued)
TKEaccess 66 requiredcommands 405
TKEworkstation xvii,7,25,47 restrictions 405
TKESTATE 60,66 trustedblockintegrity 445
TOKEN 117,118,123,129,133,145,150 trustedblocksections 444
TOKENkeytype 27 TrustedKeyEntry(TKE) 47,525,553
tokenparameter overview 38
PKAKeyRecordCreateverb 288 trusted_block_identifierparameter
PKAKeyRecordReadverb 295 RemoteKeyExportverb 396
PKAKeyRecordWriteverb 297 TrustedBlockCreateverb 405
TokenValidationValue(TVV) 422 trusted_block_identifier_lengthparameter
token_dataparameter RemoteKeyExportverb 396
KeyTokenBuild2verb 161 TrustedBlockCreateverb 405
token_data_lengthparameter typesofkeys 25
KeyTokenBuild2verb 161
token_lengthparameter
U
PKAKeyRecordCreateverb 288
PKAKeyRecordReadverb 295 UKPT 102,103,157,170
PKAKeyRecordWriteverb 297 format 310
TOKEN-DL 269,280,290 UKPTBOTH 334
TPK-ONLY 365 UKPTIPIN 333,340
trademarks 562 UKPTOPIN 333
trailingshortblocks 217 ule_id_lengthparameter
TransactionValidation(CSNBTRV) 355 RemoteKeyExportverb 398
format 355 USE-CV 156
JNIversion 357 USECONFG 114,137,164,176,179,202,206
parameters 355 userID
requiredcommands 356 pendingchange 66
usagenotes 357 user_associated_dataparameter
transaction_infoparameter KeyTokenBuild2verb 161
TransactionValidationverb 356 user_associated_data_1parameter
transaction_info_lengthparameter KeyGenerate2verb 130
TransactionValidationverb 356 user_associated_data_1_lengthparameter
transaction_key_identifierparameter KeyGenerate2verb 130
TransactionValidationverb 356 user_associated_data_2parameter
transaction_key_identifier_lengthparameter KeyGenerate2verb 130
TransactionValidationverb 356 user_associated_data_2_lengthparameter
TRANSLAT 102,157,170,333 KeyGenerate2verb 130
translatedkey 10,11 user_associated_data_lengthparameter
transportkey 20,26,111,394,444 KeyTokenBuild2verb 161
transportkeyvariant UTCtimeofday 66
definition 20 utilities
transport_key_identifierparameter ivp.e 31,553
PKAKeyGenerateverb 372 panel.exe 11,25,31,32,58,266,542,544,546,
RemoteKeyExportverb 397 547,553,554,555,556
TrustedBlockCreateverb 405 PKAKeyTokenBuild 377
transport_key_identifier_lengthparameter
RemoteKeyExportverb 397
triple-DES 498 V
triple-DESencryption 212
validation_valuesparameter
Triple-DESencryption 65
TransactionValidationverb 356
triple-lengthkeys
validation_values_lengthparameter
multipleencipherment 509
TransactionValidationverb 356
mutipledecipherment 510
variableModulus-Exponenttoken
trustedblock 35,403,444
RSA 435
numberrepresentation 446
variabletypes 13
sectionformat 446
verb
TrustedBlockCreate(CSNDTBC) 403
accesscontrol 40,515
format 404
AES 40
JNIversion 405
AESKeyRecordCreate(CSNBAKRC) 267
parameters 404
AESKeyRecordDelete(CSNBAKRD) 269
590 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

verb (continued) verb (continued)
AESKeyRecordList(CSNBAKRL) 271 KeyTokenBuild(CSNBKTB) 155
AESKeyRecordRead(CSNBAKRR) 274 KeyTokenBuild2(CSNBKTB2) 159
AESKeyRecordWrite(CSNBAKRW) 276 KeyTokenChange(CSNBKTC) 163
CCA 40,55 KeyTokenChange2(CSNBKTC2) 166
CCAnode 40 KeyTokenParse(CSNBKTP) 169
CCAnodesandresourcecontrol 57 KeyTranslate(CSNBKTR) 173
ClearKeyImport(CSNBCKI) 100 KeyTranslate2(CSNBKTR2) 175
ClearPINEncrypt(CSNBCPE) 312 MACGenerate(CSNBMGN) 241
ClearPINGenerate(CSNBPGN) 315 MACVerify(CSNBMVR) 245
ClearPINGenerateAlternate(CSNBCPA) 318 MasterKeyProcess(CSNBMKP) 93
commonparameters 13,14 MDCGenerate(CSNBMDG) 249
ControlVectorGenerate(CSNBCVG) 102 MultipleClearKeyImport(CSNBCKM) 179
ControlVectorTranslate(CSNBCVT) 104 One-WayHash(CSNBOWH) 258
CryptographicFacilityQuery(CSUACFQ) 58,60 parameterlist 12
CryptographicFacilityVersion(CSUACFV) 84 parameters 13
CryptographicResourceAllocate(CSUACRA) 86 PINChange/Unblock(CSNBPCU) 342
CryptographicResourceDeallocate(CSUACRD) 88 PKA 47,48,52
CryptographicVariableEncipher(CSNBCVE) 107 PKADecrypt(CSNDPKD) 182
CVVGenerate(CSNBCSG) 322 PKAEncrypt(CSNDPKE) 185
CVVVerify(CSNBCSV) 325 PKAKeyGenerate(CSNDPKG) 370
DataKeyExport(CSNBDKX) 109 PKAKeyImport(CSNDPKI) 374
DataKeyImport(CSNBDKM) 111 PKAkeymanagement 48
Decipher(CSNBDEC) 213 PKAKeyRecordCreate(CSNDKRC) 288
definition 12,19 PKAKeyRecordDelete(CSNDKRD) 290
DES 40 PKAKeyRecordList(CSNDKRL) 292
DEScryptographickey 100 PKAKeyRecordRead(CSNDKRR) 295
DESKeyRecordCreate(CSNBKRC) 278 PKAKeyRecordWrite(CSNDKRW) 297
DESKeyRecordDelete(CSNBKRD) 280 PKAKeyTokenBuild(CSNDPKB) 377
DESKeyRecordList(CSNBKRL) 282 PKAKeyTokenChange(CSNDKTC) 385
DESKeyRecordRead(CSNBKRR) 284 PKAKeyTranslate(CSNDPKT) 388
DESKeyRecordWrite(CSNBKRW) 286 PKAPublicKeyExtract(CSNDPKX) 392
description 13 prefix 12
digitalsignature 48 ProhibitExport(CSNBPEX) 188
DigitalSignatureGenerate(CSNDDSG) 360 ProhibitExportExtended(CSNBPEXX) 189
DigitalSignatureVerify(CSNDDSV) 364 RandomNumberGenerate(CSNBRNG) 191
DiversifiedKeyGenerate(CSNBDKG) 113 RandomNumberGenerateLong(CSNBRNGL) 193
Encipher(CSNBENC) 217 RandomNumberTests(CSUARNT) 97
EncryptedPINGenerate(CSNBEPG) 328 relatedinformation 14
EncryptedPINTranslate(CSNBPTR) 332 RemoteKeyExport(CSNDRKX) 394
EncryptedPINVerify(CSNBPVR) 338 requiredcommands 14
entrypointname 12 RestrictKeyAttribute(CSNBRKA) 195
financialservices 303 restrictions 14
format 13 RetainedKeyDelete(CSNDRKD) 299
hashing 40 RetainedKeyList(CSNDRKL) 301
HMAC 40 SecureMessagingforKeys(CSNBSKY) 348
HMACGenerate(CSNBHMG) 235 SecureMessagingforPINs(CSNBSPN) 351
HMACVerify(CSNBHMV) 238 sequence 39
input/output(I/O)parameter 13 SymmetricAlgorithmDecipher(CSNBSAD) 221
JNIversion 14 SymmetricAlgorithmEncipher(CSNBSAE) 226
KeyExport(CSNBKEX) 117 SymmetricKeyExport(CSNDSYX) 198
KeyGenerate(CSNBKGN) 120 SymmetricKeyGenerate(CSNDSYG) 201
KeyGenerate2(CSNBKGN2) 128 SymmetricKeyImport(CSNDSYI) 205
KeyImport(CSNBKIM) 133 SymmetricKeyImport2(CSNDSYI2) 208
KeyPartImport(CSNBKPI) 136 TransactionValidation(CSNBTRV) 355
KeyPartImport2(CSNBKPI2) 139 TrustedBlockCreate(CSNDTBC) 403
keystorage 261 usagenotes 14
KeyStorageInitialization(CSNBKSI) 90 variabletypes 13
KeyTest(CSNBKYT) 143 verb_datafield 66,67,68,70,71
KeyTestExtended(CSNBKYTX) 150 verb_dataparameter
KeyTest2(CSNBKYT2) 147 CryptographicFacilityQueryverb 72
Index 591

verb_dataparameter (continued) Z
forCryptographicFacilityQuery 72
z/OS
verb_data_lengthparameter
mixedconfigurations 553
CryptographicFacilityQueryverb 72
z/VM xviii
verbs
z/VMguest 539
PIN 304
z10modelGA3 48
verificationparttern 74
z196 47
verificationpattern 93,143,150,265,491
zcrypt
verification_patternparameter
installing 537
KeyTestExtendedverb 152
ZERO-PAD 182,185,199,202,205,361,365
KeyTestverb 145
KeyTest2verb 148
verification_pattern_lengthparameter
KeyTest2verb 148
VERIFY 143,145,147,150,160,355,356
version_dataparameter
CryptographicFacilityVersionverb 84
version_data_lengthparameter
CryptographicFacilityVersionverb 84
Visa(EMV)paddingrule 241
VISAcard-verificationvalue(CVV) 38,303
VISAPVV 315
VISAPVVkey 318
VISA-1 336
VISA-2PINblockformat 308,479
VISA-3PINblockformat 308,479
VISA-4PINblockformat 308
VISA-PVV 102,157,170,319,339
VISA-PVValgorithm 319,339
VISAPCU1 343
VISAPCU2 343
VISAPVV4 339
VISAPVV4algorithm 339
W
Website xv
whoshouldusethisdocument xvi
WRAP-ECB 102,115,137,156,157,164,170,176,
179,202,206
WRAP-ENH 102,114,137,156,157,164,170,176,
179,202,206
WRAPMTHD 59
wrappingkey 10
X
X3.106(CBC)method 496
X9.19OPT 242,246
X9.31 361,365
X9.31hashformat 513
X9.9-1 242,246
X9.9-1keyword 242,246
XLATE 102,157,170
XLATE-OK 378
XPORT 371
XPORT-OK 102,157,170
XPRT-SYM 160
XPRTAASY 160
XPRTUASY 160
592 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

Readers’ Comments — We'd Like to Hear from You
LinuxforSystemz
SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide
PublicationNo. SC33-8294-02
Weappreciateyourcommentsaboutthispublication.Pleasecommentonspecificerrorsoromissions,accuracy,
organization,subjectmatter,orcompletenessofthisbook.Thecommentsyousendshouldpertaintoonlythe
informationinthismanualorproductandthewayinwhichtheinformationispresented.
Fortechnicalquestionsandinformationaboutproductsandprices,pleasecontactyourIBMbranchoffice,yourIBM
businesspartner,oryourauthorizedremarketer.
WhenyousendcommentstoIBM,yougrantIBManonexclusiverighttouseordistributeyourcommentsinany
wayitbelievesappropriatewithoutincurringanyobligationtoyou.IBMoranyotherorganizationswillonlyusethe
personalinformationthatyousupplytocontactyouabouttheissuesthatyoustateonthisform.
Comments:
Thankyouforyoursupport.
Submityourcommentsusingoneofthesechannels:
v Sendyourcommentstotheaddressonthereversesideofthisform.
v Sendyourcommentsviaemailto:eservdoc@de.ibm.com
IfyouwouldlikearesponsefromIBM,pleasefillinthefollowinginformation:
Name Address
CompanyorOrganization
PhoneNo. Emailaddress

Readers’ Comments — We'd Like to Hear from You (cid:2)(cid:3)(cid:4)(cid:5) CutorFold
AlongLine
SC33-8294-02
FoldandTape Pleasedonotstaple FoldandTape
_________________________________________________________________________________________
NOPOSTAGE
NECESSARY
IFMAILEDINTHE
UNITEDSTATES
BUSINESS REPLY MAIL
FIRST-CLASSMAIL PERMITNO.40 ARMONK,NEWYORK
POSTAGEWILLBEPAIDBYADDRESSEE
IBMDeutschlandResearch&DevelopmentGmbH
InformationDevelopment
Department3248
SchoenaicherStrasse220
71032Boeblingen
Germany
_________________________________________________________________________________________
FoldandTape Pleasedonotstaple FoldandTape
CutorFold
SC33-8294-02 AlongLine
___________________________________________________________________________________________________

(cid:2)(cid:3)(cid:4)(cid:5)
ProductNumber:
PrintedinUSA
SC33-8294-02
