Files

drjones 82b86331e0 Add markdown exports

2026-05-19 19:13:06 -07:00

1.2 MiB

Raw Blame History

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

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

Keywords for Remote Key Export certificate_parms parameter . . . . . . . . . . . . . 397
Keywords for Trusted Block Create control information . . . . . . . . . . . . . . . . 404
Return code values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Reason codes for return code 0. . . . . . . . . . . . . . . . . . . . . . . . . 408
Reason codes for return code 4. . . . . . . . . . . . . . . . . . . . . . . . . 408
Reason codes for return code 8. . . . . . . . . . . . . . . . . . . . . . . . . 409
Reason codes for return code 12 . . . . . . . . . . . . . . . . . . . . . . . . 418
Reason codes for return code 16 . . . . . . . . . . . . . . . . . . . . . . . . 419
AES Internal key token format, version X'04' . . . . . . . . . . . . . . . . . . . . 421
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

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.
The CCAlibrary verifies that a CEX3C is available for key translation. If not, then the standard ‘no-available-device’error will be returned.
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.
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.
At this point, either a fresh key-t has been obtained, or a key-t was found in RAM cache for the operation.
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
An eligible CCAverb call (see lists in “Access control points that affect CPACF protected key operations” on page 9) comes into the CCAlibrary.
No CEX3C is necessary, so no check for availability or Cryptographic ResourceAllocate (CSUACRA) call will be implied.
The CCAlibrary prepares an appropriate CPACF clear key (key-c) structure using the clear key passed to the CCAverb (key-v).
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:
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.
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

Add the path to the java/javac executable to the user's PATH environment variable, so that they can call the command without preconditions.
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 .java to compile the program: javac -classpath /opt/IBM/CEX3C/cnm/HIKM.zip .java Notes:
The classpath option points to the HIKM.zip file because the hikmNativeInteger class and JNI verb front end classes are in this file.
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 .java, issue this command: javac -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:/opt/IBM/CEX3C/cnm/HIKMMK.zip .java Notes:
The classpath option points to the HIKM.zip file because the hikmNativeInteger class and JNI verb front end classes are in this file.
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.
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 .class to run the program: java -classpath /opt/IBM/CEX3C/cnm/HIKM.zip:..class Notes:
See “Building the Java Byte code” for notes on the HIKM.zip classpath.
Notice that '.' (period) is added to the class path so that Java can find .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:..class Notes:

See “Building the Java Byte code” on page 17 for notes on the HIKM.zip classpath.
Notice that '.' (period) is added to the class path so that Java can find .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: | eMK(*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: | eKEK(KL) || eKEK(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: | eKEK(*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: | eMK(K) = eAESKWMK(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:

Anexampleof“anyservice”isCSNBENC.
Thesecombinationsexcludeverbsthatcanbeusedontheirown;forexample,KeyExportorencode,orusing theKeyGenerateverbtogenerateanexportablekey.
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:

The fields will be returned in the order given.
Output data will overwrite the input data in the verb_data field, and set the verb_data_length field to the output value.
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.
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:

The fields will be returned in the order given, however the *_ID fields should be used for verification.
The verb_data_length parameter will indicate the total size at the bottom of the table describing the verb_data.
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:

The fields will be returned in the order given, however the *_ID fields should be used for verification.
The verb_data_length parameter will indicate the total size at the bottom of the table describing the verb_data.
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:

The fields will be returned in the order given, however the *_ID fields should be used for verification.
The verb_data_length parameter will indicate the total size at the bottom of the table describing the verb_data.
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

When the KEYGENKY key type is coded, either CLR8-ENC or UKPT must be specified in rule_array.
When the SECMSG key_type is coded, either SMKEY or SMPIN must be specified in the rule_array.
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:

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.
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:
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.
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.
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.
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

Releases earlier than Release 3.20 do not support theADJUST and NOADJUST parity adjustment keywords.
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:

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.
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:

Acleartext key consisting of only the key bytes, not contained in a key token.
Acleartext key contained in an internalAES key-token.
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:
The algorithm identifier keywordAES, which is the only symmetric algorithm currently supported.
An optional processing rule using keyword CBC (the default), ECB, or PKCS-PAD, which selects the decryption mode.
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.
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:
For an ICV selection of INITIAL, a 16-byte initialization vector of your choosing and a 32-byte chain data buffer.
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:
Verifies theAES key-token for keyword KEYIDENT.
Verifies that the ciphertext length is a multiple of the block size.
Deciphers the inputAES key if the key is encrypted (MKVP was present in token).
Deciphers the ciphertext with theAES clear key according to the encryption mode specified.
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:

Acleartext key consisting of only the key bytes, not contained in a key token.
Acleartext key contained in an internalAES key-token.
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:
The algorithm identifier keywordAES, which is the only symmetric algorithm currently supported.
An optional processing rule using keyword CBC (the default), ECB, or PKCS-PAD, which selects the encryption mode.
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.
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:
For an ICV selection of INITIAL, a 16-byte initialization vector of your choosing and a 32-byte chain data buffer.
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:
Verifies theAES key-token for keyword KEYIDENT.
Deciphers the inputAES key if the key is encrypted (MKVP was present in token).
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:

On the first call to the verb, place the non-null key into the MDC variable.
Ensure that the chaining_vector variable is set to null (18 bytes of X'00').
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:

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.
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.
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:

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.
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:

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
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:

The master key from the CMK register is copied to the OMK register.
The master key from the FULLNMK register is copied to the CMK register.
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:

Allocate a CEX3C by invoking “Cryptographic ResourceAllocate (CSUACRA)” on page 86.
Change the master key.
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:

To delete a key record fromAES key-storage, use theAES Key Record Delete verb.
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:

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 (......*).
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:

The Enhanced PIN security mode command is enabled in the active role.
The output PIN profile specifies 3621 or 3624 as the PIN-block format.
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:

All length fields are in binary.
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:

Generates a random value for the generated key, K. The generated key length specified by the selected rule determines the key length.
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.
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:
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.
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.
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.
Recovers the clear value of the source key, K, identified by the source_key_identifier parameter.
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.
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.
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.
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:

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.
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.
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:

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.
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:

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.
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
XORs the CV in the token with the encrypted result from the previous step.
Stores the previous result in the token and updates the TVV. v If the output is an (external) RKX key-token:
Encrypts the key using a variant of the trusted block MAC key.
Builds the token with the encrypted key and the rule_id variable.
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

Avalue of 0, 1, or 2 is considered insufficient space to hold the output encrypted result, and the verb returns an error.
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.
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
AES keys are not supported by this verb.
Keys with a modulus length greater than 2048 bits are not supported in releases before Release 3.30.
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

AES keys are not supported by this verb.
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:

Create an inactive external trusted block
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.

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

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.
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:

Generateanewkey
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:

IgnoreallCVbitdefinitions
IfCCADESkey-tokenformat,settheflagbyteofthesymmetricencrypted outputkeytoindicateaCVvalueispresent.
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
TheCVlength(offset011+xxx)is16,andbothCVhalvesarenonzero
Thesource_key_identifierparameter(containedineitheraCCADES key-tokenorRKXkey-token)identifiesan8-bytekey
Thekey-formbits(40-42)ofthisCVdonotindicateasingle-lengthkey(are notsettozero)
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:

Ifthelengthofthekeytobeexportedislessthanyyy,returnanerror
LogicalANDtheCVforthekeytobeexportedwiththeexportkeyCVlimit mask
ComparetheresulttotheexportkeyCVlimittemplate
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:

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

(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.
(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.
(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.
(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.

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

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.
The leftmost 6 digits of the result is added (modulo 10) to the offset data. The modulo 10 addition ignores carries.
The rightmost 4 digits of the result of the addition (modulo 10) are extracted.
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

Amultiple encipherment of the TSP using the double-length PVV generation key is performed.
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.
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
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:

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.
Encrypt X with the double-length PINGEN (or PINVER) key to get 16 hexadecimal digits (64 bits).
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.
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.

Compute the SHA-256 hash of the string formed by prepending the byte X'01' to the cleartext key value.
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:

Sets KKR′ = KKR XOR RN
Sets K1 = X'4545454545454545'
Sets X1 = DES encoding of KKL using key K1
Sets K2 = X1 XOR KKL
Sets X2 = DES encoding of KKR′ using key K2
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, T8, 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, T8, 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 (N8─7,N8)│ └──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │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 (N8─7,N8)│ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ (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 (N8─7,N8)│ └──────┬───────┘ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │ │ │ │ ┌───┐ │ ├─────────┐ ├────── ─ ┐ ├─────────────(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 (N8─7,N8)│ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ (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 (N8─7,N8)│ │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 (N8─7,N8)│ │ 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 (N8─7,N8)│ │ 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 (N8─7,N8)│ │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.

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.

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.

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: eKEK(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 eKEK(K) Figure28.Multipleenciphermentofsingle-lengthkeys Multiple decipherment of single-length keys The multiple encipherment of an encrypted single-length key (Y = eKEK(K)) using a double-length KEK is defined as follows: dKEK(Y) = dKEKL(eKEKR(dKEKL(Y))) = dKEK(eKEK(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: eKEKa(KL) || eKEKb(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 eKEKa(KL) eKEKb(KR) Figure30.Multipleenciphermentofdouble-lengthkeys Multiple decipherment of double-length keys The multiple decipherment of an encrypted double-length key, Y = eKEKa(KL) || eKEKb(KR), using two double-length KEKs, KEKa, and KEKb, is defined as follows: DKEKa(YL) || dKEKb(YR) = dKEKaL(eKEKaR(dKEKaL(YL))) || dKEKbL(eKEKbR(dKEKbL(YR))) = dKEKa(eKEKa(KL)) || dKEKb(eKEKb(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 = eKEKa(KL) YR = eKEKb(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: eKEKa(KL) || eKEKb(KM) || eKEKa(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 = eKEKa(KL) YM = eKEKb(KM) YR = eKEKa(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 = eKEKa(KL) || eKEKb(KM) || eKEKa(KR), using two double-length KEKs, KEKa, and KEKb, is defined as follows: dKEKa(YL) || dKEKb(YM) || dKEKa(YR) = dKEKaL(eKEKaR(dKEKaL(YL))) || dKEKbL(eKEKbR(dKEKbL(YM))) || dKEKaL(eKEKaR(dKEKaL(YR))) = dKEKa(eKEKa(KL)) || dKEKb(eKEKb(KM)) || dKEKa(eKEKa(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 eKEKa(KL) eKEKb(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

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:

The classpath option points to the HIKM.zip file because the hikmNativeInteger class is in this file.

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:

The path shown for the HIKM.zip file is the default distribution location of that file.

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 '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:

Point your Web browser at this location: http://www.ibm.com/security/cryptocards

Locate the box on the left side labeled Cryptocards.

Click the PCIe Cryptographic Coprocessor link from the Cryptocards box.

The Cryptocards box will be updated with a submenu underneath the PCIe Cryptographic Coprocessor name.

Find the Software download link on this submenu and click it.

The main page will be updated with information on downloading host software for various platforms.

On this page, find the heading Obtaining CCAsoftware for System z servers running Linux.

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.

Copy the RPM to the host where it will be installed. For example, /root/ on your host image.

Login to the host as root. Change to the directory where the RPM is located by issuing these commands: cd /root/

Install the RPM by issuing the following: rpm -i 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.

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: 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//kernel/drivers/s390/crypto/ You should see z90crypt.ko. If there is just z90crypt.ko then load it with the following: modprobe z90crypt Notes:

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).

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:

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).

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.

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).

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 ---output is : is a single-space separated list b) must be passed along with the new group to the 'usermod' command as a "comma" separated list, followed by the . 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.

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.

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 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 ,-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 : use non-default card | is the card number [0 - 63] | [CC] -o: Disable output to stdout: | [CC] -g : Set the log 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 -f -i | To REENCipher KEY STORAGE: | -t -f -r | To LIST a KEY STORAGE: | -t -f -p | where: | can be AES , DES , PKA | 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.

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.

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.

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

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 -i /opt/IBM/CEX3C/bin/panel.exe -t DES -f -i /opt/IBM/CEX3C/bin/panel.exe -t PKA -f -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.

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

To reencipher non-default key storage with panel.exe use: 556 LinuxforSystemz: SecureKeySolutionwiththeCommonCryptographicArchitectureApplicationProgrammer'sGuide

/opt/IBM/CEX3C/bin/panel.exe -t AES -f -r /opt/IBM/CEX3C/bin/panel.exe -t DES -f -r /opt/IBM/CEX3C/bin/panel.exe -t PKA -f -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

1.2 MiB Raw Blame History Unescape Escape

SecureKey Programming

1.2 MiB

Raw Blame History