z/os icsf application programmer's guidefile/csfb400_icsf_apg_hcr77c1.pdf · derive session key...

z/OS

Cryptographic ServicesIntegrated Cryptographic Service FacilityApplication Programmer's GuideVersion 2 Release 3

SC14-7508-07

IBM

NoteBefore using this information and the product it supports, read the information in Notices on page 1301.

This edition applies to ICSF FMID HCR77C1 and Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequentreleases and modifications until otherwise indicated in new editions.

Last updated: January 24, 2018

Copyright IBM Corporation 1997, 2018.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . xvii

Tables . . . . . . . . . . . . . . . xix

About this information . . . . . . . xxviiWho should use this information . . . . . . xxviiHow to use this information . . . . . . . . xxviiWhere to find more information . . . . . . . xxix

Related Publications . . . . . . . . . . xxixIBM Crypto Education . . . . . . . . . xxix

How to send your comments to IBM xxxiIf you have a technical problem . . . . . . . xxxi

Summary of changes . . . . . . . xxxiiiSummary of changes for Cryptographic Supportfor z/OS V2R1 - z/OS V2R3 (FMID HCR77C1) . xxxiiiChanges made in Cryptographic Support forz/OS V2R1 - z/OS V2R3 (FMID HCR77C1) . . xxxiiiChanges made in Cryptographic Support forz/OS V2R1 - z/OS V2R2 (FMID HCR77C0) . . . xxxvChanges made in Cryptographic Support forz/OS V1R13 - z/OS V2R2 (FMID HCR77B1) asupdated April 2016 . . . . . . . . . . xxxviiChanges made in Cryptographic Support forz/OS V1R13 - z/OS V2R2 (FMID HCR77B1) . . xxxviiiChanges made in Enhanced Cryptographic Supportfor z/OS V1R13 - z/OS V2R1 (FMID HCR77B0) . . xl

Part 1. IBM programming . . . . . . 1

Chapter 1. Introducing programming forICSF . . . . . . . . . . . . . . . . 3ICSF callable services naming conventions . . . . 3Callable service syntax . . . . . . . . . . . 3

Callable services with ALET parameters . . . . 5Rules for defining parameters and attributes. . . 5Parameter definitions . . . . . . . . . . 7Invocation requirements . . . . . . . . . 9Security considerations . . . . . . . . . 10

Performance considerations . . . . . . . . . 10Special secure mode . . . . . . . . . . . 10Compliance mode . . . . . . . . . . . . 11

Compliant-tagged key tokens . . . . . . . 11Using the callable services . . . . . . . . . 11

When the call succeeds . . . . . . . . . 12When the call does not succeed. . . . . . . 12

Linking a program with the ICSF callable services 13

Chapter 2. Introducing CCA symmetrickey cryptography and using symmetrickey callable services. . . . . . . . . 15Functions of symmetric cryptographic keys. . . . 15

Key separation . . . . . . . . . . . . 16Master key variant for fixed-length tokens . . . 16Transport key variant for fixed-length tokens . . 16Key forms . . . . . . . . . . . . . . 17Key token . . . . . . . . . . . . . . 18Key wrapping . . . . . . . . . . . . 19Payload format . . . . . . . . . . . . 20Types of keys . . . . . . . . . . . . . 20

Key strength and wrapping of key . . . . . . 27Key strength and key wrapping access controlpoints . . . . . . . . . . . . . . . 28DES master key . . . . . . . . . . . . 29

DK PIN methods support . . . . . . . . . 29DK Deterministic PIN Generate (CSNBDDPGand CSNEDDPG) . . . . . . . . . . . 29DK Migrate PIN (CSNBDMP and CSNEDMP) . . 30DK PAN Modify in Transaction (CSNBDPMTand CSNEDPMT) . . . . . . . . . . . 30DK PAN Translate (CSNBDPT and CSNEDPT) . 30DK PIN Change (CSNBDPC and CSNEDPC) . . 30DK PIN Verify (CSNBDPV and CSNEDPV). . . 30DK PRW Card Number Update (CSNBDPNUand CSNEDPNU) . . . . . . . . . . . 30DK PRW CMAC Generate (CSNBDPCG andCSNEDPCG) . . . . . . . . . . . . . 30DK Random PIN Generate (CSNBDRPG andCSNEDRPG) . . . . . . . . . . . . . 30DK Regenerate PRW (CSNBDRP and CSNEDRP) 30

Generating and managing symmetric keys . . . . 31Key Generator Utility Program . . . . . . . 31Common Cryptographic Architecture DES KeyManagement Services . . . . . . . . . . 31Common Cryptographic Architecture AES KeyManagement Services . . . . . . . . . . 35Common Cryptographic Architecture HMAC KeyManagement Services . . . . . . . . . . 36ECC Diffie-Hellman key agreement models. . . 37Improved remote key distribution . . . . . . 38Diversifying keys . . . . . . . . . . . 51Callable services for managing the CKDS . . . 52Callable Services that support Secure SocketsLayer (SSL) . . . . . . . . . . . . . 54

Enciphering and deciphering data . . . . . . . 54Encoding and Decoding Data (CSNBECO,CSNEECO, CSNBDCO, and CSNEDCO). . . . . 55Translating Ciphertext (CSNBCTT2 or CSNBCTT3and CSNECTT2 or CSNECTT3). . . . . . . . 55Managing data integrity and message authentication 56

Message authentication code processing . . . . 56Hashing functions . . . . . . . . . . . 58

Managing personal authentication . . . . . . . 59Verifying credit card data. . . . . . . . . 60

EMV simplification services . . . . . . . . . 62Derive ICC Master Key callable service(CSNBDCM and CSNEDCM) . . . . . . . 63

Copyright IBM Corp. 1997, 2018 iii

Derive Session Key callable service (CSNBDSKand CSNEDSK) . . . . . . . . . . . . 63EMV Scripting callable service (CSNBESC andCSNEESC). . . . . . . . . . . . . . 63EMV Transaction (ARQC/ARPC) callable service(CSNBEAC and CSNEEAC) . . . . . . . . 64EMV Verification callable service (CSNBEVF andCSNEEVF). . . . . . . . . . . . . . 65Generate Issuer Master Key callable service(CSNBGIM and CSNEGIM) . . . . . . . . 65

ANSI TR-31 key block support . . . . . . . . 65TR-31 Export Callable Service (CSNBT31X andCSNET31X) . . . . . . . . . . . . . 66TR-31 Import Callable Service (CSNBT31I andCSNET31I) . . . . . . . . . . . . . 66TR-31 Parse Callable Service (CSNBT31P andCSNET31P) . . . . . . . . . . . . . 66TR-31 Optional Data Read Callable Service(CSNBT31R and CSNET31R) . . . . . . . 66TR-31 Optional Data Build Callable Service(CSNBT31O and CSNET31O) . . . . . . . 66

Secure messaging . . . . . . . . . . . . 67Trusted Key Entry (TKE) support . . . . . . . 67Utilities. . . . . . . . . . . . . . . . 67

Character/Nibble Conversion Callable Services(CSNBXBC and CSNBXCB) . . . . . . . . 68Code Conversion Callable Services (CSNBXEAand CSNBXAE) . . . . . . . . . . . . 68Cryptographic Usage Statistic (CSFSTAT andCSFSTAT6) . . . . . . . . . . . . . 68ICSF Query Algorithm Callable Service (CSFIQA) 68ICSF Query Facility Callable Service (CSFIQF) . . 68ICSF Query Facility2 Callable Service (CSFIQF2) 68X9.9 Data Editing Callable Service (CSNB9ED) . 68

Typical sequences of ICSF callable services . . . . 69Key forms and types used in the Key Generatecallable service . . . . . . . . . . . . . 69

Generating an operational key . . . . . . . 69Generating an importable key . . . . . . . 70Generating an exportable key . . . . . . . 70Examples of single-length keys in one form only 70Examples of OPIM single-length, double-length,and triple-length keys in two forms . . . . . 71Examples of OPEX single-length, double-length,and triple-length keys in two forms . . . . . 71Examples of IMEX single-length anddouble-length keys in two forms . . . . . . 72Examples of EXEX single-length anddouble-length keys in two forms . . . . . . 72

Using the Ciphertext Translate2 callable service . . 72Summary of callable services . . . . . . . . 73

Chapter 3. Introducing CCA PKAcryptography and using PKA callableservices . . . . . . . . . . . . . . 87PKA key algorithms . . . . . . . . . . . 87PKA keys . . . . . . . . . . . . . . . 87

Master keys . . . . . . . . . . . . . 87Operational private keys . . . . . . . . . 88

Key strength and wrapping of key . . . . . . 88

Key strength and key wrapping access controlpoints . . . . . . . . . . . . . . . 89RSA private key tokens . . . . . . . . . 90

PKA callable services . . . . . . . . . . . 90Callable services supporting digital signatures . . 90Callable services for PKA key management . . . 91Callable services to manage the Public Key DataSet (PKDS) . . . . . . . . . . . . . 91Callable services for working with retainedprivate keys . . . . . . . . . . . . . 93Callable services for Secure Electronic Transaction(SET) . . . . . . . . . . . . . . . 94

PKA key tokens . . . . . . . . . . . . . 94X.509 certificates . . . . . . . . . . . . . 95PKA key management . . . . . . . . . . . 95Security and integrity of the token. . . . . . . 96Key identifier for PKA key token . . . . . . . 97

Key label . . . . . . . . . . . . . . 97Key token . . . . . . . . . . . . . . 97

Summary of the PKA callable services . . . . . 98

Chapter 4. Introducing PKCS #11 andusing PKCS #11 callable services . . 101PKCS #11 services . . . . . . . . . . . . 101Attribute list. . . . . . . . . . . . . . 103Handles . . . . . . . . . . . . . . . 104

Part 2. CCA callable services . . . 105

Chapter 5. Managing symmetriccryptographic keys . . . . . . . . . 107Clear Key Import (CSNBCKI and CSNECKI) . . . 108

Format . . . . . . . . . . . . . . 108Parameters . . . . . . . . . . . . . 108Usage notes . . . . . . . . . . . . . 109Access control points . . . . . . . . . . 109Required hardware . . . . . . . . . . 110

Control Vector Generate (CSNBCVG andCSNECVG) . . . . . . . . . . . . . . 110

Format . . . . . . . . . . . . . . 110Parameters . . . . . . . . . . . . . 111Usage notes . . . . . . . . . . . . . 115Required hardware . . . . . . . . . . 115

Control Vector Translate (CSNBCVT andCSNECVT) . . . . . . . . . . . . . . 115

Format . . . . . . . . . . . . . . 116Parameters . . . . . . . . . . . . . 116Restrictions . . . . . . . . . . . . . 118Usage notes . . . . . . . . . . . . . 118Access control point . . . . . . . . . . 119Required hardware . . . . . . . . . . 119

Cryptographic Variable Encipher (CSNBCVE andCSNECVE) . . . . . . . . . . . . . . 119


Data Key Export (CSNBDKX and CSNEDKX) . . 122

iv z/OS ICSF Application Programmer's Guide

Format . . . . . . . . . . . . . . 122Parameters . . . . . . . . . . . . . 122Restrictions . . . . . . . . . . . . . 123Usage notes . . . . . . . . . . . . . 124Access control points . . . . . . . . . . 124Required hardware . . . . . . . . . . 124

Data Key Import (CSNBDKM and CSNEDKM) . . 125Format . . . . . . . . . . . . . . 125Parameters . . . . . . . . . . . . . 125Restrictions . . . . . . . . . . . . . 126Usage notes . . . . . . . . . . . . . 127Access control points . . . . . . . . . . 127Required hardware . . . . . . . . . . 127

Derive ICC MK (CSNBDCM and CSNEDCM) . . 128Format . . . . . . . . . . . . . . 128Parameters . . . . . . . . . . . . . 129Usage notes . . . . . . . . . . . . . 134Cryptographic services used by Derive ICC MK 134Access control points . . . . . . . . . . 134Required hardware . . . . . . . . . . 134

Derive Session Key (CSNBDSK and CSNEDSK) 135Format . . . . . . . . . . . . . . 135Parameters . . . . . . . . . . . . . 136Usage notes . . . . . . . . . . . . . 141Cryptographic services used by Derive SessionKey . . . . . . . . . . . . . . . 141Access control points . . . . . . . . . . 141Required hardware . . . . . . . . . . 141

Diversified Key Generate (CSNBDKG andCSNEDKG) . . . . . . . . . . . . . . 142


Diversified Key Generate2 (CSNBDKG2 andCSNEDKG2) . . . . . . . . . . . . . 149


ECC Diffie-Hellman (CSNDEDH and CSNFEDH) 155Format . . . . . . . . . . . . . . 156Parameters . . . . . . . . . . . . . 156Restrictions . . . . . . . . . . . . . 162Usage notes . . . . . . . . . . . . . 162Access control points . . . . . . . . . . 163Required hardware . . . . . . . . . . 164

Generate Issuer MK (CSNBGIM and CSNEGIM) 164Format . . . . . . . . . . . . . . 165Parameters . . . . . . . . . . . . . 165Usage notes . . . . . . . . . . . . . 170Cryptographic services used by Generate IssuerMK. . . . . . . . . . . . . . . . 170Access control points . . . . . . . . . . 170Required hardware . . . . . . . . . . 170

Key Encryption Translate (CSNBKET andCSNEKET) . . . . . . . . . . . . . . 171

Format . . . . . . . . . . . . . . 171

Parameters . . . . . . . . . . . . . 171Usage notes . . . . . . . . . . . . . 173Access control points . . . . . . . . . . 174Required hardware . . . . . . . . . . 174

Key Export (CSNBKEX and CSNEKEX) . . . . 174Format . . . . . . . . . . . . . . 175Parameters . . . . . . . . . . . . . 175Restrictions . . . . . . . . . . . . . 177Usage notes . . . . . . . . . . . . . 177Access control points . . . . . . . . . . 177Required hardware . . . . . . . . . . 178

Key Generate (CSNBKGN and CSNEKGN) . . . 179Format . . . . . . . . . . . . . . 179Parameters . . . . . . . . . . . . . 179Restrictions . . . . . . . . . . . . . 186Usage notes . . . . . . . . . . . . . 186Usage notes - Key type and key formcombinations . . . . . . . . . . . . 186Access control points . . . . . . . . . . 188Required hardware . . . . . . . . . . 189

Key Generate2 (CSNBKGN2 and CSNEKGN2) . . 190Format . . . . . . . . . . . . . . 191Parameters . . . . . . . . . . . . . 191Usage notes . . . . . . . . . . . . . 197Access control points . . . . . . . . . . 201Required hardware . . . . . . . . . . 202

Key Import (CSNBKIM and CSNEKIM) . . . . 202Format . . . . . . . . . . . . . . 203Parameters . . . . . . . . . . . . . 203Restrictions . . . . . . . . . . . . . 205Usage notes . . . . . . . . . . . . . 205Access control points . . . . . . . . . . 206Required hardware . . . . . . . . . . 206

Key Part Import (CSNBKPI and CSNEKPI) . . . 207Format . . . . . . . . . . . . . . 207Parameters . . . . . . . . . . . . . 207Restrictions . . . . . . . . . . . . . 210Usage notes . . . . . . . . . . . . . 210Access control points . . . . . . . . . . 210Required hardware . . . . . . . . . . 210Related information . . . . . . . . . . 211

Key Part Import2 (CSNBKPI2 and CSNEKPI2) . . 211Format . . . . . . . . . . . . . . 211Parameters . . . . . . . . . . . . . 212Usage notes . . . . . . . . . . . . . 214Access control points . . . . . . . . . . 214Required hardware . . . . . . . . . . 214

Key Test (CSNBKYT and CSNEKYT) . . . . . 215Format . . . . . . . . . . . . . . 216Parameters . . . . . . . . . . . . . 216Restrictions . . . . . . . . . . . . . 218Usage notes . . . . . . . . . . . . . 218Access control points . . . . . . . . . . 219Required hardware . . . . . . . . . . 219

Key Test2 (CSNBKYT2 and CSNEKYT2) . . . . 219Format . . . . . . . . . . . . . . 220Parameters . . . . . . . . . . . . . 220Usage notes . . . . . . . . . . . . . 224Access control point . . . . . . . . . . 224Required hardware . . . . . . . . . . 225

Key Test Extended (CSNBKYTX and CSNEKYTX) 226

Contents v


Key Token Build (CSNBKTB and CSNEKTB) . . . 230Format . . . . . . . . . . . . . . 230Parameters . . . . . . . . . . . . . 230Restrictions . . . . . . . . . . . . . 236Usage notes . . . . . . . . . . . . . 236Required hardware . . . . . . . . . . 238

Key Token Build2 (CSNBKTB2 and CSNEKTB2) 238Format . . . . . . . . . . . . . . 238Parameters . . . . . . . . . . . . . 239Usage notes . . . . . . . . . . . . . 243Required hardware . . . . . . . . . . 271

Key Translate (CSNBKTR and CSNEKTR) . . . . 271Format . . . . . . . . . . . . . . 271Parameters . . . . . . . . . . . . . 271Restrictions . . . . . . . . . . . . . 273Usage notes . . . . . . . . . . . . . 273Access control points . . . . . . . . . . 273Required hardware . . . . . . . . . . 273

Key Translate2 (CSNBKTR2 and CSNEKTR2). . . 274Format . . . . . . . . . . . . . . 275Parameters . . . . . . . . . . . . . 275Restrictions . . . . . . . . . . . . . 280Usage notes . . . . . . . . . . . . . 280Access control points . . . . . . . . . . 280Required hardware . . . . . . . . . . 281

Multiple Clear Key Import (CSNBCKM andCSNECKM) . . . . . . . . . . . . . . 282


Multiple Secure Key Import (CSNBSKM andCSNESKM) . . . . . . . . . . . . . . 285


PKA Decrypt (CSNDPKD and CSNFPKD). . . . 291Format . . . . . . . . . . . . . . 291Parameters . . . . . . . . . . . . . 292Restrictions . . . . . . . . . . . . . 294Authorization . . . . . . . . . . . . 294Usage notes . . . . . . . . . . . . . 295Access control points . . . . . . . . . . 295Required hardware . . . . . . . . . . 295

PKA Encrypt (CSNDPKE and CSNFPKE) . . . . 297Format . . . . . . . . . . . . . . 297Parameters . . . . . . . . . . . . . 297Restrictions . . . . . . . . . . . . . 300Usage notes . . . . . . . . . . . . . 300Access control point . . . . . . . . . . 300Required hardware . . . . . . . . . . 301

Prohibit Export (CSNBPEX and CSNEPEX) . . . 302


Prohibit Export Extended (CSNBPEXX andCSNEPEXX) . . . . . . . . . . . . . . 304


Random Number Generate (CSNBRNG,CSNERNG, CSNBRNGL and CSNERNGL) . . . 306


Remote Key Export (CSNDRKX and CSNFRKX) 310Format . . . . . . . . . . . . . . 310Parameters . . . . . . . . . . . . . 311Usage notes . . . . . . . . . . . . . 318Access control points . . . . . . . . . . 318Required hardware . . . . . . . . . . 319

Restrict Key Attribute (CSNBRKA and CSNERKA) 320Format . . . . . . . . . . . . . . 320Parameters . . . . . . . . . . . . . 320Access control points . . . . . . . . . . 324Required hardware . . . . . . . . . . 324

Secure Key Import (CSNBSKI and CSNESKI) . . . 325Format . . . . . . . . . . . . . . 325Parameters . . . . . . . . . . . . . 325Usage notes . . . . . . . . . . . . . 327Access control points . . . . . . . . . . 327Required hardware . . . . . . . . . . 328

Secure Key Import2 (CSNBSKI2 and CSNESKI2) 328Format . . . . . . . . . . . . . . 329Parameters . . . . . . . . . . . . . 329Usage notes . . . . . . . . . . . . . 332Access control points . . . . . . . . . . 332Required hardware . . . . . . . . . . 333

Symmetric Key Export (CSNDSYX and CSNFSYX) 333Format . . . . . . . . . . . . . . 334Parameters . . . . . . . . . . . . . 334Usage notes . . . . . . . . . . . . . 337Access control points . . . . . . . . . . 337Required hardware . . . . . . . . . . 338

Symmetric Key Export with Data (CSNDSXD andCSNFSXD) . . . . . . . . . . . . . . 339


Symmetric Key Generate (CSNDSYG andCSNFSYG) . . . . . . . . . . . . . . 343

Format . . . . . . . . . . . . . . 344Parameters . . . . . . . . . . . . . 344Usage notes . . . . . . . . . . . . . 348

vi z/OS ICSF Application Programmer's Guide

Access control points . . . . . . . . . . 348Required hardware . . . . . . . . . . 349

Symmetric Key Import (CSNDSYI and CSNFSYI) 350Format . . . . . . . . . . . . . . 350Parameters . . . . . . . . . . . . . 351Restrictions . . . . . . . . . . . . . 353Usage notes . . . . . . . . . . . . . 354Access control points . . . . . . . . . . 354Required hardware . . . . . . . . . . 354

Symmetric Key Import2 (CSNDSYI2 andCSNFSYI2) . . . . . . . . . . . . . . 355


Trusted Block Create (CSNDTBC and CSNFTBC) 361Format . . . . . . . . . . . . . . 361Parameters . . . . . . . . . . . . . 361Usage notes . . . . . . . . . . . . . 364Access control points . . . . . . . . . . 364Required hardware . . . . . . . . . . 364

TR-31 Export (CSNBT31X and CSNET31X) . . . 365Format . . . . . . . . . . . . . . 365Parameters . . . . . . . . . . . . . 365Restrictions . . . . . . . . . . . . . 370Usage notes . . . . . . . . . . . . . 370Access control points . . . . . . . . . . 371Required hardware . . . . . . . . . . 379

TR-31 Import (CSNBT31I and CSNET31I) . . . . 379Format . . . . . . . . . . . . . . 379Parameters . . . . . . . . . . . . . 380Restrictions . . . . . . . . . . . . . 386Usage notes . . . . . . . . . . . . . 386Access control points . . . . . . . . . . 387Required hardware . . . . . . . . . . 392

TR-31 Optional Data Build (CSNBT31O andCSNET31O) . . . . . . . . . . . . . . 393

Format . . . . . . . . . . . . . . 393Parameters . . . . . . . . . . . . . 394Restrictions . . . . . . . . . . . . . 396Usage notes . . . . . . . . . . . . . 396Required hardware . . . . . . . . . . 396

TR-31 Optional Data Read (CSNBT31R andCSNET31R) . . . . . . . . . . . . . . 396


TR-31 Parse (CSNBT31P and CSNET31P) . . . . 400Format . . . . . . . . . . . . . . 400Parameters . . . . . . . . . . . . . 400Restrictions . . . . . . . . . . . . . 403Usage notes . . . . . . . . . . . . . 403Required hardware . . . . . . . . . . 403

Unique Key Derive (CSNBUKD and CSNEUKD) 403Format . . . . . . . . . . . . . . 404Parameters . . . . . . . . . . . . . 404Restrictions . . . . . . . . . . . . . 411

Usage notes . . . . . . . . . . . . . 411Access control points . . . . . . . . . . 412Required hardware . . . . . . . . . . 412

Chapter 6. Protecting data . . . . . . 415Modes of operation . . . . . . . . . . . 415

Electronic Code Book (ECB) Mode . . . . . 416Cipher Block Chaining (CBC) Mode . . . . . 416Cipher Feedback (CFB) Mode . . . . . . . 416Output Feedback (OFB) Mode . . . . . . . 416Galois/Counter Mode (GCM) . . . . . . . 416Triple DES Encryption . . . . . . . . . 417

Ciphertext Translate2 (CSNBCTT2, CSNBCTT3,CSNECTT2, CSNECTT3) . . . . . . . . . 418

Choosing between CSNBCTT2 and CSNBCTT3 418Format . . . . . . . . . . . . . . 418Parameters . . . . . . . . . . . . . 419Usage notes . . . . . . . . . . . . . 425Access control points . . . . . . . . . . 429Required hardware . . . . . . . . . . 430

Decipher (CSNBDEC or CSNBDEC1 andCSNEDEC or CSNEDEC1) . . . . . . . . . 430

Choosing between CSNBDEC and CSNBDEC1 431Format . . . . . . . . . . . . . . 432Parameters . . . . . . . . . . . . . 432Restrictions . . . . . . . . . . . . . 436Usage notes . . . . . . . . . . . . . 436Access control point . . . . . . . . . . 436Required hardware . . . . . . . . . . 436

Decode (CSNBDCO and CSNEDCO) . . . . . 437Considerations . . . . . . . . . . . . 437Format . . . . . . . . . . . . . . 437Parameters . . . . . . . . . . . . . 437Required hardware . . . . . . . . . . 438

Encipher (CSNBENC or CSNBENC1 andCSNEENC or CSNEENC1) . . . . . . . . . 439

Choosing between CSNBENC and CSNBENC1 440Format . . . . . . . . . . . . . . 441Parameters . . . . . . . . . . . . . 441Restrictions . . . . . . . . . . . . . 445Usage notes . . . . . . . . . . . . . 445Access control point . . . . . . . . . . 446Required hardware . . . . . . . . . . 446

Encode (CSNBECO and CSNEECO) . . . . . . 446Considerations . . . . . . . . . . . . 446Format . . . . . . . . . . . . . . 447Parameters . . . . . . . . . . . . . 447Required hardware . . . . . . . . . . 448

Symmetric Algorithm Decipher (CSNBSAD orCSNBSAD1 and CSNESAD or CSNESAD1) . . . 448

Choosing between CSNBSAD and CSNBSAD1or CSNESAD and CSNESAD1. . . . . . . 448Format . . . . . . . . . . . . . . 449Parameters . . . . . . . . . . . . . 450Usage notes . . . . . . . . . . . . . 455Access control point . . . . . . . . . . 455Required hardware . . . . . . . . . . 455

Symmetric Algorithm Encipher (CSNBSAE orCSNBSAE1 and CSNESAE or CSNESAE1). . . . 456

Choosing between CSNBSAE and CSNBSAE1 orCSNESAE and CSNESAE1 . . . . . . . . 456

Contents vii

Format . . . . . . . . . . . . . . 456Parameters . . . . . . . . . . . . . 457Usage notes . . . . . . . . . . . . . 462Access control point . . . . . . . . . . 462Required hardware . . . . . . . . . . 462

Symmetric Key Decipher (CSNBSYD or CSNBSYD1and CSNESYD or CSNESYD1). . . . . . . . 463

Choosing between CSNBSYD and CSNBSYD1 465Format . . . . . . . . . . . . . . 465Parameters . . . . . . . . . . . . . 466Usage notes . . . . . . . . . . . . . 472Access control points . . . . . . . . . . 472Required hardware . . . . . . . . . . 473Related information . . . . . . . . . . 474

Symmetric Key Encipher (CSNBSYE or CSNBSYE1and CSNESYE or CSNESYE1) . . . . . . . . 474

Choosing between CSNBSYE and CSNBSYE1 475Format . . . . . . . . . . . . . . 476Parameters . . . . . . . . . . . . . 476Usage notes . . . . . . . . . . . . . 483Access control points . . . . . . . . . . 483Required hardware . . . . . . . . . . 483Related information . . . . . . . . . . 484

Chapter 7. Verifying data integrity andauthenticating messages . . . . . . 487How MACs are used . . . . . . . . . . . 487How hashing functions are used . . . . . . . 489

How MDCs are used . . . . . . . . . . 489HMAC Generate (CSNBHMG or CSNBHMG1 andCSNEHMG or CSNEHMG1) . . . . . . . . 489

Choosing between CSNBHMG and CSNBHMG1 489Format . . . . . . . . . . . . . . 490Parameters . . . . . . . . . . . . . 490Access control points . . . . . . . . . . 493Required hardware . . . . . . . . . . 494

HMAC Verify (CSNBHMV or CSNBHMV1 andCSNEHMV or CSNEHMV1) . . . . . . . . 494

Choosing between CSNBHMV and CSNBHMV1 494Format . . . . . . . . . . . . . . 495Parameters . . . . . . . . . . . . . 495Access control points . . . . . . . . . . 498Required hardware . . . . . . . . . . 498

MAC Generate (CSNBMGN or CSNBMGN1 andCSNEMGN or CSNEMGN1) . . . . . . . . 499

Choosing between CSNBMGN and CSNBMGN1 499Format . . . . . . . . . . . . . . 500Parameters . . . . . . . . . . . . . 500Usage notes . . . . . . . . . . . . . 503Access control point . . . . . . . . . . 503Required hardware . . . . . . . . . . 503Related information . . . . . . . . . . 504

MAC Generate2 (CSNBMGN2, CSNBMGN3,CSNEMGN2, and CSNEMGN3) . . . . . . . 504

Choosing between CSNBMGN2 andCSNBMGN3. . . . . . . . . . . . . 504Format . . . . . . . . . . . . . . 504Parameters . . . . . . . . . . . . . 505Usage notes . . . . . . . . . . . . . 508Access control points . . . . . . . . . . 508Required hardware . . . . . . . . . . 508

MAC Verify (CSNBMVR or CSNBMVR1 andCSNEMVR or CSNEMVR1) . . . . . . . . 509

Choosing between CSNBMVR and CSNBMVR1 509Format . . . . . . . . . . . . . . 510Parameters . . . . . . . . . . . . . 510Usage notes . . . . . . . . . . . . . 513Access control point . . . . . . . . . . 513Required hardware . . . . . . . . . . 513Related information . . . . . . . . . . 514

MAC Verify2 (CSNBMVR2, CSNBMVR3,CSNEMVR2, and CSNEMVR3) . . . . . . . 514

Choosing between CSNBMVR2 andCSNBMVR3 . . . . . . . . . . . . . 514Format . . . . . . . . . . . . . . 515Parameters . . . . . . . . . . . . . 515Usage notes . . . . . . . . . . . . . 518Access control points . . . . . . . . . . 518Required hardware . . . . . . . . . . 518

MDC Generate (CSNBMDG or CSNBMDG1 andCSNEMDG or CSNEMDG1) . . . . . . . . 519

Choosing between CSNBMDG and CSNBMDG1 519Format . . . . . . . . . . . . . . 520Parameters . . . . . . . . . . . . . 520Usage notes . . . . . . . . . . . . . 523Required hardware . . . . . . . . . . 523

One-Way Hash Generate (CSNBOWH orCSNBOWH1 and CSNEOWH or CSNEOWH1) . . 524


Symmetric MAC Generate (CSNBSMG orCSNBSMG1 and CSNESMG or CSNESMG1) . . . 529

Choosing between CSNBSMG and CSNBSMG1or CSNESMG and CSNESMG1 . . . . . . 529Format . . . . . . . . . . . . . . 530Parameters . . . . . . . . . . . . . 530Usage notes . . . . . . . . . . . . . 534Required hardware . . . . . . . . . . 534

Symmetric MAC Verify (CSNBSMV or CSNBSMV1and CSNESMV or CSNESMV1) . . . . . . . 534

Choosing between CSNBSMV and CSNBSMV1or CSNESMV and CSNESMV1 . . . . . . 534Format . . . . . . . . . . . . . . 535Parameters . . . . . . . . . . . . . 535Usage notes . . . . . . . . . . . . . 538Required hardware . . . . . . . . . . 538

Chapter 8. Financial services . . . . 541How Personal Identification Numbers (PINs) areused . . . . . . . . . . . . . . . . 541How VISA card verification values are used . . . 542Translating data and PINs in networks . . . . . 542Working with EuropayMasterCardVisa smartcards . . . . . . . . . . . . . . . . 542PIN callable services . . . . . . . . . . . 543

Generating a PIN . . . . . . . . . . . 543Encrypting a PIN . . . . . . . . . . . 543Generating a PIN Validation Value (PVV) froman encrypted PIN block . . . . . . . . . 543Verifying a PIN. . . . . . . . . . . . 544

viii z/OS ICSF Application Programmer's Guide

Translating a PIN . . . . . . . . . . . 544Algorithms for generating and verifying a PIN 544Using PINs on different systems . . . . . . 544PIN-encrypting keys . . . . . . . . . . 544

ANSI X9.8 PIN restrictions . . . . . . . . . 545ANSI X9.8 PIN - Enforce PIN block restrictions 546ANSI X9.8 PIN - Allow modification of PAN 546ANSI X9.8 PIN - Allow only ANSI PIN blocks 546ANSI X9.8 PIN Use stored decimalizationtables only . . . . . . . . . . . . . 547

The PIN profile. . . . . . . . . . . . . 547PIN block format . . . . . . . . . . . 548Enhanced PIN security mode . . . . . . . 550Format control . . . . . . . . . . . . 550Pad digit . . . . . . . . . . . . . . 551Current key serial number . . . . . . . . 552Decimalization tables . . . . . . . . . . 552

Format preserving encryption . . . . . . . . 552Authentication Parameter Generate (CSNBAPGand CSNEAPG) . . . . . . . . . . . . 557


Clear PIN Encrypt (CSNBCPE and CSNECPE) . . 561Format . . . . . . . . . . . . . . 562Parameters . . . . . . . . . . . . . 562Restrictions . . . . . . . . . . . . . 564Usage notes . . . . . . . . . . . . . 564Access control point . . . . . . . . . . 564Required hardware . . . . . . . . . . 565

Clear PIN Generate (CSNBPGN and CSNEPGN) 565Format . . . . . . . . . . . . . . 565Parameters . . . . . . . . . . . . . 566Usage notes . . . . . . . . . . . . . 568Access control points . . . . . . . . . . 569Required hardware . . . . . . . . . . 569Related information . . . . . . . . . . 569

Clear PIN Generate Alternate (CSNBCPA andCSNECPA) . . . . . . . . . . . . . . 570


CVV Key Combine (CSNBCKC and CSNECKC) 575Format . . . . . . . . . . . . . . 575Parameters . . . . . . . . . . . . . 575Restrictions . . . . . . . . . . . . . 578Usage notes . . . . . . . . . . . . . 578Access control points . . . . . . . . . . 579Required hardware . . . . . . . . . . 580

EMV Scripting Service (CSNBESC and CSNEESC) 580Format . . . . . . . . . . . . . . 581Parameters . . . . . . . . . . . . . 581Usage notes . . . . . . . . . . . . . 590Cryptographic services used by EMV ScriptingService . . . . . . . . . . . . . . 590Access control points . . . . . . . . . . 591Required hardware . . . . . . . . . . 591

EMV Transaction (ARQC/ARPC) Service(CSNBEAC and CSNEEAC) . . . . . . . . 592

Format . . . . . . . . . . . . . . 592Parameters . . . . . . . . . . . . . 593Usage notes . . . . . . . . . . . . . 599Cryptographic services used by EMVTransaction (ARQC/ARPC) Service . . . . . 599Access control points . . . . . . . . . . 599Required hardware . . . . . . . . . . 599

EMV Verification Functions (CSNBEVF andCSNEEVF) . . . . . . . . . . . . . . 600

Format . . . . . . . . . . . . . . 600Parameters . . . . . . . . . . . . . 601Usage notes . . . . . . . . . . . . . 605Cryptographic services used by EMVVerification Functions . . . . . . . . . 605Access control points . . . . . . . . . . 605Required hardware . . . . . . . . . . 606

Encrypted PIN Generate (CSNBEPG andCSNEEPG) . . . . . . . . . . . . . . 606


Encrypted PIN Translate (CSNBPTR andCSNEPTR) . . . . . . . . . . . . . . 612


Encrypted PIN Translate Enhanced (CSNBPTREand CSNEPTRE) . . . . . . . . . . . . 618


Encrypted PIN Verify (CSNBPVR and CSNEPVR) 627Format . . . . . . . . . . . . . . 627Parameters . . . . . . . . . . . . . 627Usage notes . . . . . . . . . . . . . 631Access control points . . . . . . . . . . 631Required hardware . . . . . . . . . . 632Related information . . . . . . . . . . 632

Field Level Decipher (CSNBFLD and CSNEFLD) 632Format . . . . . . . . . . . . . . 633Parameters . . . . . . . . . . . . . 633Usage notes . . . . . . . . . . . . . 639Access control points . . . . . . . . . . 640Required hardware . . . . . . . . . . 640Related information . . . . . . . . . . 640

Field Level Encipher (CSNBFLE and CSNEFLE) 641Format . . . . . . . . . . . . . . 642Parameters . . . . . . . . . . . . . 642Usage notes . . . . . . . . . . . . . 648Access control points . . . . . . . . . . 649Required hardware . . . . . . . . . . 649

Contents ix

Related information . . . . . . . . . . 650FPE Decipher (CSNBFPED and CSNEFPED) . . . 651


FPE Encipher (CSNBFPEE and CSNEFPEE) . . . 659Format . . . . . . . . . . . . . . 660Parameters . . . . . . . . . . . . . 661Usage notes . . . . . . . . . . . . . 667Access control points . . . . . . . . . . 667Required hardware . . . . . . . . . . 668

FPE Translate (CSNBFPET and CSNEFPET) . . . 668Format . . . . . . . . . . . . . . 669Parameters . . . . . . . . . . . . . 669Usage notes . . . . . . . . . . . . . 677Access control points . . . . . . . . . . 677Required hardware . . . . . . . . . . 677

PIN Change/Unblock (CSNBPCU and CSNEPCU) 677Format . . . . . . . . . . . . . . 678Parameters . . . . . . . . . . . . . 679Usage notes . . . . . . . . . . . . . 683Access control points . . . . . . . . . . 683Required hardware . . . . . . . . . . 684

Recover PIN from Offset (CSNBPFO andCSNEPFO) . . . . . . . . . . . . . . 684


Secure Messaging for Keys (CSNBSKY andCSNESKY) . . . . . . . . . . . . . . 688


Secure Messaging for PINs (CSNBSPN andCSNESPN) . . . . . . . . . . . . . . 692


SET Block Compose (CSNDSBC and CSNFSBC) 697Format . . . . . . . . . . . . . . 698Parameters . . . . . . . . . . . . . 698Restrictions . . . . . . . . . . . . . 702Usage notes . . . . . . . . . . . . . 702Access control point . . . . . . . . . . 702Required hardware . . . . . . . . . . 702

SET Block Decompose (CSNDSBD and CSNFSBD) 703Format . . . . . . . . . . . . . . 703Parameters . . . . . . . . . . . . . 704Restrictions . . . . . . . . . . . . . 708Usage notes . . . . . . . . . . . . . 708Access control points . . . . . . . . . . 708Required hardware . . . . . . . . . . 708

Transaction Validation (CSNBTRV and CSNETRV) 709


VISA CVV Service Generate (CSNBCSG andCSNECSG) . . . . . . . . . . . . . . 713


VISA CVV Service Verify (CSNBCSV andCSNECSV) . . . . . . . . . . . . . . 718


Chapter 9. Financial services for DKPIN methods. . . . . . . . . . . . 723Weak PIN table. . . . . . . . . . . . . 723DK PIN methods . . . . . . . . . . . . 723DK Deterministic PIN Generate (CSNBDDPG andCSNEDDPG) . . . . . . . . . . . . . 724


DK Migrate PIN (CSNBDMP and CSNEDMP) . . 731Format . . . . . . . . . . . . . . 731Parameters . . . . . . . . . . . . . 732Usage notes . . . . . . . . . . . . . 737Access control points . . . . . . . . . . 737Required hardware . . . . . . . . . . 737

DK PAN Modify in Transaction (CSNBDPMT andCSNEDPMT) . . . . . . . . . . . . . 738


DK PAN Translate (CSNBDPT and CSNEDPT) . . 745Format . . . . . . . . . . . . . . 746Parameters . . . . . . . . . . . . . 746Usage notes . . . . . . . . . . . . . 752Access control points . . . . . . . . . . 752Required hardware . . . . . . . . . . 752

DK PIN Change (CSNBDPC and CSNEDPC) . . . 753Format . . . . . . . . . . . . . . 753Parameters . . . . . . . . . . . . . 754Usage notes . . . . . . . . . . . . . 764Access control points . . . . . . . . . . 764Required hardware . . . . . . . . . . 764

DK PIN Verify (CSNBDPV and CSNEDPV) . . . 765Format . . . . . . . . . . . . . . 765Parameters . . . . . . . . . . . . . 765Usage notes . . . . . . . . . . . . . 768Access control points . . . . . . . . . . 768

x z/OS ICSF Application Programmer's Guide

Required hardware . . . . . . . . . . 769DK PRW Card Number Update (CSNBDPNU andCSNEDPNU) . . . . . . . . . . . . . 769


DK PRW CMAC Generate (CSNBDPCG andCSNEDPCG) . . . . . . . . . . . . . 776


DK Random PIN Generate (CSNBDRPG andCSNEDRPG) . . . . . . . . . . . . . 780


DK Regenerate PRW (CSNBDRP and CSNEDRP) 787Format . . . . . . . . . . . . . . 787Parameters . . . . . . . . . . . . . 788Usage notes . . . . . . . . . . . . . 793Access control points . . . . . . . . . . 793Required hardware . . . . . . . . . . 793

Chapter 10. Using digital signatures 795Signature algorithms and formatting methods . . 795Digital Signature Generate (CSNDDSG andCSNFDSG) . . . . . . . . . . . . . . 795

Format . . . . . . . . . . . . . . 796Parameters . . . . . . . . . . . . . 796Restrictions . . . . . . . . . . . . . 800Authorization . . . . . . . . . . . . 800Usage notes . . . . . . . . . . . . . 801Access control points . . . . . . . . . . 801Required hardware . . . . . . . . . . 802

Digital Signature Verify (CSNDDSV andCSNFDSV) . . . . . . . . . . . . . . 803


Chapter 11. Managing PKAcryptographic keys . . . . . . . . . 813PKA Key Generate (CSNDPKG and CSNFPKG) 813


PKA Key Import (CSNDPKI and CSNFPKI) . . . 819Format . . . . . . . . . . . . . . 819

Parameters . . . . . . . . . . . . . 820Restrictions . . . . . . . . . . . . . 822Usage notes . . . . . . . . . . . . . 822Access control points . . . . . . . . . . 823Required hardware . . . . . . . . . . 823

PKA Key Token Build (CSNDPKB and CSNFPKB) 823Format . . . . . . . . . . . . . . 825Parameters . . . . . . . . . . . . . 825Usage notes . . . . . . . . . . . . . 835Required hardware . . . . . . . . . . 835

PKA Key Token Change (CSNDKTC andCSNFKTC) . . . . . . . . . . . . . . 835


PKA Key Translate (CSNDPKT and CSNFPKT) . . 839Format . . . . . . . . . . . . . . 839Parameters . . . . . . . . . . . . . 839Restrictions . . . . . . . . . . . . . 843Access control points . . . . . . . . . . 843Required hardware . . . . . . . . . . 844

PKA Public Key Extract (CSNDPKX andCSNFPKX) . . . . . . . . . . . . . . 845


Public Infrastructure Certificate (CSNDPIC andCSNFPIC) . . . . . . . . . . . . . . 847

Format . . . . . . . . . . . . . . 847Parameters . . . . . . . . . . . . . 848Access control point . . . . . . . . . . 854Required hardware . . . . . . . . . . 854

Retained Key Delete (CSNDRKD and CSNFRKD) 854Format . . . . . . . . . . . . . . 855Parameters . . . . . . . . . . . . . 855Usage notes . . . . . . . . . . . . . 856Access control point . . . . . . . . . . 856Required hardware . . . . . . . . . . 856

Retained Key List (CSNDRKL and CSNFRKL) . . 857Format . . . . . . . . . . . . . . 857Parameters . . . . . . . . . . . . . 857Usage notes . . . . . . . . . . . . . 859Access control points . . . . . . . . . . 860Required hardware . . . . . . . . . . 860

Chapter 12. Key data set management 861Metadata for key data set records . . . . . . 861CKDS Key Record Create (CSNBKRC andCSNEKRC) . . . . . . . . . . . . . . 863


CKDS Key Record Create2 (CSNBKRC2 andCSNEKRC2) . . . . . . . . . . . . . . 865

Format . . . . . . . . . . . . . . 865Parameters . . . . . . . . . . . . . 865

Contents xi

Restrictions . . . . . . . . . . . . . 867Usage notes . . . . . . . . . . . . . 867Required hardware . . . . . . . . . . 867

CKDS Key Record Delete (CSNBKRD andCSNEKRD) . . . . . . . . . . . . . . 867


CKDS Key Record Read (CSNBKRR andCSNEKRR) . . . . . . . . . . . . . . 869

Format . . . . . . . . . . . . . . 869Parameters . . . . . . . . . . . . . 869Restrictions . . . . . . . . . . . . . 870Required hardware . . . . . . . . . . 870

CKDS Key Record Read2 (CSNBKRR2 andCSNEKRR2) . . . . . . . . . . . . . . 870

Format . . . . . . . . . . . . . . 871Parameters . . . . . . . . . . . . . 871Restrictions . . . . . . . . . . . . . 873Usage Notes. . . . . . . . . . . . . 873Access control points . . . . . . . . . . 873Required hardware . . . . . . . . . . 873

CKDS Key Record Write (CSNBKRW andCSNEKRW) . . . . . . . . . . . . . . 874


CKDS Key Record Write2 (CSNBKRW2 andCSNEKRW2) . . . . . . . . . . . . . 876


Coordinated KDS Administration (CSFCRC andCSFCRC6) . . . . . . . . . . . . . . 878


ICSF Multi-Purpose Service (CSFMPS andCSFMPS6) . . . . . . . . . . . . . . 882

Format . . . . . . . . . . . . . . 883Parameters . . . . . . . . . . . . . 883Required hardware . . . . . . . . . . 885

Key Data Set List (CSFKDSL and CSFKDSL6) . . 886Format . . . . . . . . . . . . . . 886Parameters . . . . . . . . . . . . . 887Usage Notes. . . . . . . . . . . . . 898Required hardware . . . . . . . . . . 899

Key Data Set Metadata Read (CSFKDMR andCSFKDMR6). . . . . . . . . . . . . . 899


Key Data Set Metadata Write (CSFKDMW andCSFKDMW6) . . . . . . . . . . . . . 906


Key Data Set Record Retrieve (CSFRRT andCSFRRT6) . . . . . . . . . . . . . . 912

Format . . . . . . . . . . . . . . 912Parameters . . . . . . . . . . . . . 912Usage Notes. . . . . . . . . . . . . 914Required hardware . . . . . . . . . . 914

Key Data Set Update (CSFKDU and CSFKDU6) 914Format . . . . . . . . . . . . . . 914Parameters . . . . . . . . . . . . . 915Usage Notes. . . . . . . . . . . . . 917Required hardware . . . . . . . . . . 917

PKDS Key Record Create (CSNDKRC andCSNFKRC) . . . . . . . . . . . . . . 917


PKDS Key Record Delete (CSNDKRD andCSNFKRD) . . . . . . . . . . . . . . 919

Format . . . . . . . . . . . . . . 920Parameters . . . . . . . . . . . . . 920Restrictions . . . . . . . . . . . . . 921Required hardware . . . . . . . . . . 921

PKDS Key Record Read and PKDS Key RecordRead2 (CSNDKRR or CSNDKRR2 and CSNFKRRor CSNFKRR2) . . . . . . . . . . . . . 921

Format . . . . . . . . . . . . . . 922Parameters . . . . . . . . . . . . . 922Required hardware . . . . . . . . . . 923

PKDS Key Record Write (CSNDKRW andCSNFKRW) . . . . . . . . . . . . . . 924


Chapter 13. Utilities. . . . . . . . . 927Character/Nibble Conversion (CSNBXBC andCSNBXCB) . . . . . . . . . . . . . . 927


Code Conversion (CSNBXEA and CSNBXAE) . . 929Format . . . . . . . . . . . . . . 929Parameters . . . . . . . . . . . . . 929Usage notes . . . . . . . . . . . . . 931Required hardware . . . . . . . . . . 931

Cryptographic Usage Statistic (CSFSTAT andCSFSTAT6) . . . . . . . . . . . . . . 931


xii z/OS ICSF Application Programmer's Guide

ICSF Query Algorithm (CSFIQA and CSFIQA6) 933Format . . . . . . . . . . . . . . 933Parameters . . . . . . . . . . . . . 933Usage notes . . . . . . . . . . . . . 937Required hardware . . . . . . . . . . 937

ICSF Query Facility (CSFIQF and CSFIQF6) . . . 937Format . . . . . . . . . . . . . . 938Parameters . . . . . . . . . . . . . 938Usage notes . . . . . . . . . . . . . 969Required hardware . . . . . . . . . . 970

ICSF Query Facility2 (CSFIQF2 and CSFIQF26) . . 970Format . . . . . . . . . . . . . . 970Parameters . . . . . . . . . . . . . 971Required hardware . . . . . . . . . . 974

SAF ACEE Selection (CSFACEE and CSFACEE6) 974Format . . . . . . . . . . . . . . 974Parameters . . . . . . . . . . . . . 974Usage notes . . . . . . . . . . . . . 975Required hardware . . . . . . . . . . 976

X9.9 Data Editing (CSNB9ED) . . . . . . . . 976Format . . . . . . . . . . . . . . 976Parameters . . . . . . . . . . . . . 976Usage notes . . . . . . . . . . . . . 977Required hardware . . . . . . . . . . 978

Chapter 14. Trusted interfaces . . . . 979PCI Interface (CSFPCI and CSFPCI6) . . . . . 979


Key Token Wrap (CSFWRP and CSFWRP6) . . . 985Format . . . . . . . . . . . . . . 985Parameters . . . . . . . . . . . . . 985Usage notes . . . . . . . . . . . . . 987Access control points . . . . . . . . . . 987Required hardware . . . . . . . . . . 987

Part 3. PKCS #11 callable services 989

Chapter 15. Using PKCS #11 tokensand objects . . . . . . . . . . . . 991PKCS #11 Derive multiple keys (CSFPDMK andCSFPDMK6). . . . . . . . . . . . . . 991

Format . . . . . . . . . . . . . . 992Parameters . . . . . . . . . . . . . 992Authorization . . . . . . . . . . . . 998Usage Notes. . . . . . . . . . . . . 998

PKCS #11 Derive key (CSFPDVK and CSFPDVK6) 999Format . . . . . . . . . . . . . . 1000Parameters . . . . . . . . . . . . . 1000Authorization . . . . . . . . . . . . 1005Usage Notes . . . . . . . . . . . . 1005

PKCS #11 Get attribute value (CSFPGAV andCSFPGAV6) . . . . . . . . . . . . . 1006

Format . . . . . . . . . . . . . . 1006Parameters . . . . . . . . . . . . . 1006Authorization . . . . . . . . . . . . 1008Usage Notes . . . . . . . . . . . . 1008

PKCS #11 Generate key pair (CSFPGKP andCSFPGKP6) . . . . . . . . . . . . . 1009


PKCS #11 Generate secret key (CSFPGSK andCSFPGSK6). . . . . . . . . . . . . . 1011


PKCS #11 Generate Keyed MAC (CSFPHMG andCSFPHMG6) . . . . . . . . . . . . . 1014


PKCS #11 Verify Keyed MAC (CSFPHMV andCSFPHMV6) . . . . . . . . . . . . . 1019


PKCS #11 One-Way Hash, Sign, or Verify(CSFPOWH and CSFPOWH6) . . . . . . . 1023

Format . . . . . . . . . . . . . . 1024Parameters . . . . . . . . . . . . . 1024Authorization . . . . . . . . . . . . 1030Usage notes . . . . . . . . . . . . 1030

PKCS #11 Private Key Sign (CSFPPKS andCSFPPKS6) . . . . . . . . . . . . . . 1031


PKCS #11 Public Key Verify (CSFPPKV andCSFPPKV6) . . . . . . . . . . . . . 1033


PKCS #11 Pseudo-Random Function (CSFPPRFand CSFPPRF6) . . . . . . . . . . . . 1036


PKCS #11 Set Attribute Value (CSFPSAV andCSFPSAV6) . . . . . . . . . . . . . . 1039


PKCS #11 Secret Key Decrypt (CSFPSKD andCSFPSKD6) . . . . . . . . . . . . . 1042


Contents xiii

PKCS #11 Secret Key Encrypt (CSFPSKE andCSFPSKE6) . . . . . . . . . . . . . . 1047


PKCS #11 Token Record Create (CSFPTRC andCSFPTRC6). . . . . . . . . . . . . . 1054


PKCS #11 Token Record Delete (CSFPTRD andCSFPTRD6) . . . . . . . . . . . . . 1058


PKCS #11 Token Record List (CSFPTRL andCSFPTRL6) . . . . . . . . . . . . . . 1060


PKCS #11 Unwrap Key (CSFPUWK andCSFPUWK6) . . . . . . . . . . . . . 1064


PKCS #11 Wrap Key (CSFPWPK and CSFPWPK6) 1069Format . . . . . . . . . . . . . . 1069Parameters . . . . . . . . . . . . . 1070Authorization . . . . . . . . . . . . 1072Usage Notes . . . . . . . . . . . . 1072

Chapter 16. Using the PKCS #11 keystructure callable services . . . . . 1075PKCS #11 Private Key Structure Decrypt(CSFPPD2 and CSFPPD26) . . . . . . . . 1076


PKCS #11 Private Key Structure Sign (CSFPPS2and CSFPPS26) . . . . . . . . . . . . 1078


PKCS #11 Public Key Structure Encrypt (CSFPPE2and CSFPPE26) . . . . . . . . . . . . 1081


PKCS #11 Public Key Structure Verify (CSFPPV2and CSFPPV26) . . . . . . . . . . . . 1084

Format . . . . . . . . . . . . . . 1084Parameters . . . . . . . . . . . . . 1084Authorization . . . . . . . . . . . . 1086

Usage notes . . . . . . . . . . . . 1086

Part 4. Appendixes . . . . . . . 1087

Appendix A. ICSF and cryptographiccoprocessor return and reasoncodes . . . . . . . . . . . . . . 1089Return codes and reason codes . . . . . . . 1089

Obtaining a dump for ICSF reason codes . . . 1089Return codes . . . . . . . . . . . . 1090Reason codes for return code 0 (0) . . . . . 1090Reason codes for return code 4 (4) . . . . . 1092Reason codes for return code 8 (8) . . . . . 1095Reason codes for return code C (12) . . . . 1136Reason codes for return code 10 (16) . . . . 1149

Appendix B. Key token formats . . . 1151Master key verification pattern (MKVP) . . . . 1151Null key tokens . . . . . . . . . . . . 1151Symmetric key tokens . . . . . . . . . . 1152

Token validation value (fixed-length symmetrictokens) . . . . . . . . . . . . . . 1152AES internal fixed-length key token . . . . 1152DES fixed-length key token . . . . . . . 1153External RKX DES key token . . . . . . . 1156

Variable-length symmetric key token formats . . 1157Variable-length symmetric key token . . . . 1157Variable-length symmetric null key token . . 1178

PKA key tokens . . . . . . . . . . . . 1178PKA key token sections . . . . . . . . 1179Integrity of PKA private key sectionscontaining an encrypted RSA key . . . . . 1180Number representation in PKA key tokens 1181Trusted blocks . . . . . . . . . . . . 1199

Appendix C. Control vectors andchanging control vectors with theCVT callable service . . . . . . . . 1215DES control vector table . . . . . . . . . 1215

Specifying a control-vector-base value . . . . 1219Changing control vectors with the Control VectorTranslate callable service . . . . . . . . . 1224

Providing the control information for testingthe control vectors . . . . . . . . . . 1224Mask array preparation . . . . . . . . 1224Selecting the key-half processing mode . . . 1226When the target key token CV is null . . . . 1228Control Vector Translate example . . . . . 1228

Appendix D. Coding examples . . . 1229C . . . . . . . . . . . . . . . . . 1229COBOL . . . . . . . . . . . . . . . 1232High Level Assembler . . . . . . . . . . 1234PL/I . . . . . . . . . . . . . . . . 1236

Appendix E. Cryptographicalgorithms and processes . . . . . 1241PIN formats and algorithms . . . . . . . . 1241

xiv z/OS ICSF Application Programmer's Guide

PIN Notation . . . . . . . . . . . . 1241PIN block formats . . . . . . . . . . 1241PIN extraction rules . . . . . . . . . . 1243IBM PIN algorithms . . . . . . . . . . 1244VISA PIN algorithms . . . . . . . . . 1250

Cipher processing rules . . . . . . . . . 1252CBC and ANSI INCITS 106 . . . . . . . 1252ANSI X9.23 and IBM 4700 . . . . . . . . 1253CUSP . . . . . . . . . . . . . . 1254The Information Protection System (IPS) . . . 1254PKCS padding method . . . . . . . . . 1255

Wrapping methods for symmetric key tokens 1257ECB wrapping of DES keys (Original method) 1257CBC wrapping of AES keys . . . . . . . 1257Enhanced CBC wrapping of DES keys(Enhanced method) . . . . . . . . . . 1257Wrapping key derivation for enhancedwrapping of DES keys . . . . . . . . . 1258Variable length token (AESKW method) . . . 1259

PKA92 key format and encryption process . . . 1259Formatting hashes and keys in public-keycryptography . . . . . . . . . . . . . 1261

ANSI X9.31 hash format . . . . . . . . 1261PKCS #1 formats . . . . . . . . . . . 1262

Visa, MasterCard, and EMV-related smart cardformats and processes . . . . . . . . . . 1263

Deriving the smart-card-specific authenticationcode . . . . . . . . . . . . . . . 1263Constructing the PIN-block for transporting anEMV smart-card PIN . . . . . . . . . 1263Deriving the CCA TDES-XOR session key . . 1264Deriving the EMV TDESEMVn tree-basedsession key . . . . . . . . . . . . . 1264PIN-block self-encryption . . . . . . . . 1265

Key test verification pattern algorithms . . . . 1265DES algorithm (single-length anddouble-length keys) . . . . . . . . . . 1265SHAVP1 algorithm . . . . . . . . . . 1265SHA-256 algorithm . . . . . . . . . . 1266

Appendix F. EBCDIC and ASCIIdefault conversion tables. . . . . . 1267

Appendix G. Access control pointsand callable services . . . . . . . 1269

Appendix H. Impact of compliancemode on callable services . . . . . 1291

Appendix I. Accessibility . . . . . . 1297Accessibility features . . . . . . . . . . 1297Consult assistive technologies . . . . . . . 1297Keyboard navigation of the user interface . . . 1297Dotted decimal syntax diagrams . . . . . . 1297

Notices . . . . . . . . . . . . . 1301Terms and conditions for product documentation 1303IBM Online Privacy Statement . . . . . . . 1304Policy for unsupported hardware . . . . . . 1304Minimum supported hardware . . . . . . . 1304Trademarks . . . . . . . . . . . . . 1305

Glossary . . . . . . . . . . . . . 1307

Index . . . . . . . . . . . . . . 1319

Contents xv

xvi z/OS ICSF Application Programmer's Guide

Figures

1. Overview of trusted block contents . . . . 402. Simplified RKX key-token structure . . . . 443. Trusted block creation . . . . . . . . . 444. Exporting keys using a trusted block . . . . 455. Generating keys using a trusted block. . . . 486. Typical flow of callable services for remote key

export . . . . . . . . . . . . . . 497. PKA Key Management . . . . . . . . . 968. Key Token Build2 keyword combinations for

AES CIPHER keys . . . . . . . . . . 2439. Key Token Build2 keyword combinations for

AES MAC keys . . . . . . . . . . . 24610. Key_Token_Build2 keyword combinations for

HMAC MAC keys . . . . . . . . . . 24811. Key Token Build2 keyword combinations for

AES EXPORTER keys . . . . . . . . . 25112. Key Token Build2 keyword combinations for

AES IMPORTER keys . . . . . . . . . 25413. Key Token Build2 keyword combinations for

AES DKYGENKY keys . . . . . . . . 257

14. Key Token Build2 keyword combinations forAES PINCALC keys . . . . . . . . . 262

15. Key Token Build2 keyword combinations forAES PINPROT keys . . . . . . . . . 264

16. Key Token Build2 keyword combinations forAES PINPRW keys. . . . . . . . . . 267

17. Key Token Build2 keyword combinations forAES SECMSG keys . . . . . . . . . 269

18. Control Vector Translate Callable ServiceMask_Array Processing . . . . . . . . 1226

19. Control Vector Translate Callable Service 122720. 3624 PIN Generation Algorithm . . . . . 124521. GBP PIN Generation Algorithm . . . . . 124622. PIN-Offset Generation Algorithm . . . . 124723. PIN Verification Algorithm. . . . . . . 124924. GBP PIN Verification Algorithm . . . . . 125025. PVV Generation Algorithm . . . . . . 1251

Copyright IBM Corp. 1997, 2018 xvii

xviii z/OS ICSF Application Programmer's Guide

Tables

1. ICSF Callable Services Naming Conventions 32. Standard Return Code Values From ICSF

Callable Services . . . . . . . . . . . 73. Descriptions of DES key types and service

usage . . . . . . . . . . . . . . 234. Descriptions of AES key types and service

usage . . . . . . . . . . . . . . 255. Descriptions of HMAC key types and service

usage . . . . . . . . . . . . . . 266. Descriptions of Clear key types and service

usage . . . . . . . . . . . . . . 277. AES EXPORTER strength required for

exporting an HMAC key under an AESEXPORTER . . . . . . . . . . . . 27

8. Minimum RSA modulus length to adequatelyprotect an AES key . . . . . . . . . . 28

9. Combinations of the callable services . . . . 6910. Summary of ICSF callable services . . . . . 7311. AES EXPORTER strength required for

exporting an HMAC key under an AESEXPORTER . . . . . . . . . . . . 88

12. Minimum RSA modulus length to adequatelyprotect an AES key . . . . . . . . . . 88

13. Summary of PKA key token sections . . . . 9514. Summary of PKA callable services . . . . . 9815. Summary of PKCS #11 callable services 10116. Summary of PKCS #11 callable services that

offer a fast-path alternative . . . . . . . 10317. Clear Key Import required hardware 11018. Rule array keywords for Control Vector

Generate . . . . . . . . . . . . . 11219. Keywords for Control Vector Translate 11820. Control Vector Translate required hardware 11921. Cryptographic Variable Encipher required

hardware . . . . . . . . . . . . . 12122. Required access control points for Data Key

Export . . . . . . . . . . . . . . 12423. Data Key Export required hardware . . . . 12424. Required access control points for Data Key

Import . . . . . . . . . . . . . . 12725. Data Key Import required hardware . . . . 12726. Rule array keywords for Derive ICC MK 13027. Derive ICC MK: Key requirements . . . . 13128. Derive ICC MK: Key type and key usage

attributes of the generated keys . . . . . 13229. Derive ICC MK required hardware . . . . 13430. Rule array keywords for Derive Session Key 13731. Derive Session Key: Key requirements 13832. Derive Session Key: Attributes of the key

generated . . . . . . . . . . . . . 13933. Derive Session Key required hardware 14134. Rule Array Keywords for Diversified Key

Generate . . . . . . . . . . . . . 14435. Required access control points for Diversified

Key Generate . . . . . . . . . . . 14736. Diversified Key Generate required hardware 148

37. Rule array keywords for Diversified KeyGenerate2 . . . . . . . . . . . . . 151

38. Summary of input generating key tokens,input generated key tokens, and outputgenerated key tokens . . . . . . . . . 153

39. Required access control points for DiversifiedKey Generate2 . . . . . . . . . . . 154

40. Diversified Key Generate2 required hardware 15541. Keywords for ECC Diffie-Hellman . . . . 15742. Valid key bit lengths and minimum curve

size required for the supported output keytypes. . . . . . . . . . . . . . . 163

43. ECC Diffie-Hellman required hardware 16444. Rule array keywords for Generate Issuer MK 16645. Generate Issuer MK: Attributes of the

generated key . . . . . . . . . . . 16846. Generate Issuer MK required hardware 17047. Keywords for Key Encryption Translate 17248. Required access control points for Key

Encryption Translate . . . . . . . . . 17449. Key Encryption Translate required hardware 17450. Required access control points for Key Export 17851. Key export required hardware . . . . . . 17852. Key Form values for the Key Generate

callable service . . . . . . . . . . . 18053. Key Length values for the Key Generate

callable service . . . . . . . . . . . 18154. Key lengths for DES keys . . . . . . . 18255. Key lengths for AES keys . . . . . . . 18356. Key Generate Valid Key Types and Key

Forms for a Single Key . . . . . . . . 18657. Key Generate Valid Key Types and Key

Forms for a Key Pair . . . . . . . . . 18758. Required access control points for Key

Generate . . . . . . . . . . . . . 18859. Key generate required hardware . . . . . 18960. Keywords for Key Generate2 Control

Information . . . . . . . . . . . . 19261. Keywords and associated algorithms for

key_type_1 parameter. . . . . . . . . 19462. Keywords and associated algorithms for

key_type_2 parameter. . . . . . . . . 19463. Key Generate2 valid key type and key form

for one AES or HMAC key . . . . . . . 19864. Key Generate2 Valid key type and key forms

for two AES or HMAC keys . . . . . . 19965. Valid key pairs that can be generated and

their required access points . . . . . . . 20066. Key type and key form keywords for AES

keys - DK PIN methods . . . . . . . . 20067. AES KEK strength required for generating an

HMAC key under an AES KEK . . . . . 20168. Required access control points for Key

Generate2 . . . . . . . . . . . . . 20169. Key Generate2 required hardware. . . . . 20270. Required access control points for Key Import 206

Copyright IBM Corp. 1997, 2018 xix

71. Key import required hardware . . . . . . 20672. Keywords for Key Part Import Control

Information . . . . . . . . . . . . 20873. Required access control points for Key Part

Import . . . . . . . . . . . . . . 21074. Key Part Import required hardware . . . . 21075. Keywords for Key Part Import2 Control

Information . . . . . . . . . . . . 21376. Required access control points for Key Part

Import2 . . . . . . . . . . . . . 21477. Key Part Import2 required hardware 21578. Keywords for Key Test Control Information 21779. Key Test required hardware. . . . . . . 21980. Keywords for Key Test2 Control Information 22181. Length of the verification pattern for each

algorithm supported . . . . . . . . . 22482. Required access control points for Key Test2 22483. Key Test2 required hardware . . . . . . 22584. Keywords for Key Test Extended Control

Information . . . . . . . . . . . . 22785. Key Test Extended required hardware 22986. Key type keywords for Key Token Build 23187. Keywords for Key Token Build Control

Information . . . . . . . . . . . . 23288. Key types and field lengths for AES keys 23589. Control Vector Generate and Key Token Build

Control Vector Keyword Combinations . . . 23790. Keywords for Key Token Build2 Control

Information . . . . . . . . . . . . 24091. Rule array keywords for AES CIPHER keys 24492. Rule array keywords for AES MAC keys 24693. Rule array keywords for HMAC MAC keys 24994. Rule array keywords for AES EXPORTER

keys . . . . . . . . . . . . . . 25295. Rule array keywords for AES IMPORTER

keys . . . . . . . . . . . . . . 25596. Rule array keywords for AES DKYGENKY

keys . . . . . . . . . . . . . . 25897. Meaning of service_data parameter when

DKYUSAGE specified. . . . . . . . . 26098. Rule array keywords for AES PINCALC keys 26299. Rule array keywords for AES PINPROT keys 265

100. Rule array keywords for AES PINPRW keys 267101. Rule array keywords for AES SECMSG keys 270102. Key Translate required hardware . . . . . 273103. Key Translate2 Access Control Points 280104. Key Translate2 required hardware . . . . 281105. Keywords for Multiple Clear Key Import

Rule Array Control Information . . . . . 283106. Required access control points for Multiple

Clear Key Import . . . . . . . . . . 284107. Multiple Clear Key Import required hardware 285108. Keywords for Multiple Secure Key Import

Rule Array Control Information . . . . . 287109. Required access control points for Multiple

Secure Key Import . . . . . . . . . . 289110. Multiple Secure Key Import required

hardware . . . . . . . . . . . . . 290111. Keywords for PKA Decrypt . . . . . . . 293112. PKA Decrypt access controls . . . . . . 295113. PKA Decrypt required hardware . . . . . 296

114. Keywords for PKA Encrypt . . . . . . . 298115. PKA Encrypt access controls . . . . . . 301116. PKA Encrypt required hardware . . . . . 301117. Prohibit Export required hardware . . . . 304118. Prohibit Export Extended required hardware 306119. Keywords for the Form Parameter . . . . 308120. Keywords for Random Number Generate

Control Information . . . . . . . . . 308121. Random Number Generate required

hardware . . . . . . . . . . . . . 310122. rule_array keywords . . . . . . . . . 312123. Structure of values used by RKX . . . . . 313124. Values defined for hash algorithm identifier

at offset 24 in the structure for Remote KeyExport . . . . . . . . . . . . . . 314

125. Transport_key_identifer used by RKX 315126. Examination of key token for

source_key_identifier . . . . . . . . . 316127. Remote Key Export required hardware 319128. Keywords for Restrict Key Attribute Control

Information . . . . . . . . . . . . 321129. Required access control points for Restrict

Key Attribute . . . . . . . . . . . 324130. Restrict Key Attribute required hardware 324131. Required access control points for Secure Key

Import . . . . . . . . . . . . . . 327132. Secure Key Import required hardware 328133. Keywords for Secure Key Import2 Control

Information . . . . . . . . . . . . 330134. Required access control points for Secure Key

Import2 . . . . . . . . . . . . . 333135. Secure Key Import2 required hardware 333136. Keywords for Symmetric Key Export Control

Information . . . . . . . . . . . . 335137. Minimum RSA modulus strength required to

contain a PKOAEP2 block when exporting anAES key . . . . . . . . . . . . . 337

138. Required access control points for SymmetricKey Export . . . . . . . . . . . . 338

139. Symmetric Key Export required hardware 338140. Keywords for Symmetric Key Export with

Data (CSNDSXD) . . . . . . . . . . 341141. Required access control points for Symmetric

Key Export with Data. . . . . . . . . 343142. Symmetric key export with data required

hardware . . . . . . . . . . . . . 343143. Keywords for Symmetric Key Generate

Control Information . . . . . . . . . 345144. Required access control points for Symmetric

Key Generate . . . . . . . . . . . 348145. Symmetric Key Generate required hardware 349146. Keywords for Symmetric Key Import Control

Information . . . . . . . . . . . . 352147. Required access control points for Symmetric

Key Import . . . . . . . . . . . . 354148. Symmetric Key Import required hardware 355149. Keywords for Symmetric Key Import2

Control Information . . . . . . . . . 357150. PKCS#1 OAEP encoded message layout

(PKOAEP2) . . . . . . . . . . . . 359

xx z/OS ICSF Application Programmer's Guide

151. Symmetric Key Import2 Access ControlPoints . . . . . . . . . . . . . . 360

152. Symmetric Key Import2 required hardware 360153. Rule_array keywords for Trusted Block Create

(CSNDTBC) . . . . . . . . . . . . 362154. Required access control points for Trusted

Block Create . . . . . . . . . . . . 364155. Trusted Block Create required hardware 364156. Keywords for TR-31 Export Rule Array

Control Information . . . . . . . . . 366157. Valid CCA to TR-31 Export Translations and

Required Access Control Points (ACPs) . . . 372158. TR-31 Export required hardware . . . . . 379159. Keywords for TR-31 Import Rule Array

Control Information . . . . . . . . . 381160. Export attributes of an imported CCA token 386161. Valid TR-31 to CCA Import Translations and

Required Access Control Points (ACPs) . . . 388162. TR-31 Import required hardware . . . . . 393163. Keywords for TR-31 Optional Data Read Rule

Array Control Information . . . . . . . 398164. Keywords for Unique Key Derive . . . . . 405165. Contents of the TR-31 block header of the

generated TR-31 key block and their meaning. 409166. Valid Control Vectors for Derived Keys 411167. Derivation Variants . . . . . . . . . 412168. Unique Key Derive required hardware 412169. Keywords for Ciphertext Translate2 . . . . 420170. Restrictions for ciphertext_in_length and

ciphertext_out_length . . . . . . . . . 425171. Ciphertext Translate2 key usage . . . . . 429172. Ciphertext Translate2 access control points 429173. Ciphertext Translate2 required hardware 430174. Keywords for the Decipher Rule Array

Control Information . . . . . . . . . 434175. Decipher required hardware . . . . . . 436176. Decode required hardware . . . . . . . 438177. Keywords for the Encipher Rule Array

Control Information . . . . . . . . . 443178. Encipher required hardware . . . . . . 446179. Encode required hardware . . . . . . . 448180. Symmetric Algorithm Decipher Rule Array

Keywords. . . . . . . . . . . . . 451181. Symmetric Algorithm Decipher required

hardware . . . . . . . . . . . . . 455182. Symmetric Algorithm Encipher Rule Array

Keywords. . . . . . . . . . . . . 458183. Symmetric Algorithm Encipher required

hardware . . . . . . . . . . . . . 463184. Symmetric Key Decipher Rule Array

Keywords. . . . . . . . . . . . . 467185. Required access control points for Symmetric

Key Decipher . . . . . . . . . . . 473186. Symmetric Key Decipher required hardware 473187. Symmetric Key Encipher Rule Array

Keywords. . . . . . . . . . . . . 477188. Required access control points for Symmetric

Key Encipher . . . . . . . . . . . 483189. Symmetric Key Encipher required hardware 484190. Keywords for HMAC Generate Control

Information . . . . . . . . . . . . 491

191. Minimum HMAC key size in bits based onhash method . . . . . . . . . . . . 492

192. HMAC Generate Access Control Points 494193. HMAC Generate required hardware . . . . 494194. Keywords for HMAC Verify Control

Information . . . . . . . . . . . . 496195. HMAC Verify Access Control Points . . . . 498196. HMAC Verify required hardware . . . . . 499197. Keywords for MAC Generate control

information . . . . . . . . . . . . 502198. MAC Generate required hardware . . . . 503199. Keywords for MAC Generate2 control

information . . . . . . . . . . . . 506200. MAC Generate2 Access Control Points 508201. MAC Generate2 required hardware . . . . 508202. Keywords for MAC Verify control

information . . . . . . . . . . . . 512203. MAC Verify required hardware . . . . . 513204. Keywords for MAC Verify2 control

information . . . . . . . . . . . . 516205. MAC Verify2 Access Control Points . . . . 518206. MAC Verify2 required hardware . . . . . 519207. Keywords for MDC Generate control

information . . . . . . . . . . . . 522208. MDC Generate required hardware . . . . 523209. Blocksize and hash length for hash methods 524210. Keywords for One-Way Hash Generate Rule

Array Control Information . . . . . . . 526211. One-Way Hash Generate required hardware 529212. Keywords for Symmetric MAC Generate

control information . . . . . . . . . 532213. Symmetric MAC Generate required hardware 534214. Keywords for Symmetric MAC Verify control

information . . . . . . . . . . . . 537215. Symmetric MAC Verify required hardware 539216. ANSI X9.8 PIN - Allow only ANSI PIN blocks 547217. Format of a PIN profile . . . . . . . . 547218. Format values of PIN blocks . . . . . . 548219. PIN block format and PIN extraction method

keywords . . . . . . . . . . . . . 548220. Callable services affected by enhanced PIN

security mode . . . . . . . . . . . 550221. Format of a pad digit . . . . . . . . . 551222. Pad digits for PIN block formats . . . . . 551223. Format of the current key serial number field 552224. Base-10 alphabet . . . . . . . . . . 553225. FPE base-15 alphabet . . . . . . . . . 553226. FPE track 1 cardholder name alphabet 554227. FPE track 1 discretionary data alphabet 555228. VFPE track 2 discretionary data alphabet 557229. Authentication Parameter Generate Rule

Array Keywords . . . . . . . . . . 559230. Access Control Points for Authentication

Parameter Generate (CSNBAPG andCSNEAPG) . . . . . . . . . . . . 560

231. Authentication Parameter Generate requiredhardware . . . . . . . . . . . . . 561

232. Process Rules for the Clear PIN EncryptionCallable Service . . . . . . . . . . . 563

233. Clear PIN Encrypt required hardware 565

Tables xxi

234. Process Rules for the Clear PIN GenerateCallable Service . . . . . . . . . . . 567

235. Array Elements for the Clear PIN GenerateCallable Service . . . . . . . . . . . 568

236. Array Elements Required by the Process Rule 568237. Required access control points for Clear PIN

Generate . . . . . . . . . . . . . 569238. Clear PIN Generate required hardware 569239. Rule Array Elements for the Clear PIN

Generate Alternate Service . . . . . . . 572240. Rule Array Keywords (First Element) for the

Clear PIN Generate Alternate Service . . . 572241. Data Array Elements for the Clear PIN

Generate Alternate Service (IBM-PINO) . . . 573242. Data Array Elements for the Clear PIN

Generate Alternate Service (VISA-PVV) . . . 574243. Required access control points for Clear PIN

Generate Alternate . . . . . . . . . . 574244. Clear PIN Generate Alternate required

hardware . . . . . . . . . . . . . 574245. Keywords for CVV Key Combine Rule Array

Control Information . . . . . . . . . 576246. Key type combinations for the CVV Key

Combine callable service . . . . . . . . 578247. Wrapping combinations for the CVV

Combine Callable Service . . . . . . . 579248. CVV Key Combine required hardware 580249. Rule array keywords for EMV Scripting

Service . . . . . . . . . . . . . . 582250. EMV Scripting Service: Key requirements 584251. Key type requirements for actions SMCON

and SMCONINT . . . . . . . . . . 585252. Key type requirements for actions

SMCONPIN, SMCIPIN, and VISAPIN . . . 585253. EMV Scripting Service required hardware 592254. Rule array keywords for EMV Transaction

(ARQC/ARPC) Service . . . . . . . . 594255. EMV Transaction (ARQC/ARPC) Service: Key

requirements . . . . . . . . . . . . 595256. EMV Transaction (ARQC/ARPC) Service

required hardware . . . . . . . . . . 599257. Rule array keywords for EMV Verification

Functions . . . . . . . . . . . . . 602258. EMV Verification Functions: Key

requirements . . . . . . . . . . . . 603259. EMV Verification Functions required

hardware . . . . . . . . . . . . . 606260. Process Rules for the Encrypted PIN Generate

Callable Service . . . . . . . . . . . 609261. Array Elements for the Encrypted PIN

Generate Callable Service . . . . . . . 609262. Array Elements Required by the Process Rule 610263. Required access control points for Encrypted

PIN Generate . . . . . . . . . . . 611264. Encrypted PIN Generate required hardware 611265. Keywords for Encrypted PIN Translate 615266. Additional Names for PIN Formats . . . . 617267. Required access control points for Encrypted

PIN Translate . . . . . . . . . . . 617268. Encrypted PIN Translate required hardware 617269. VMDS pairings for enciphered PAN data 618

270. Rule array keywords for Encrypted PINTranslate Enhanced . . . . . . . . . 620

271. Encrypted PIN Translate Enhanced requiredhardware . . . . . . . . . . . . . 626

272. Keywords for Encrypted PIN Verify . . . . 629273. Array Elements for the Encrypted PIN Verify

Callable Service . . . . . . . . . . . 631274. Array Elements Required by the Process Rule 631275. Required access control points for Encrypted

PIN Verify . . . . . . . . . . . . 631276. Encrypted PIN Verify required hardware 632277. Rule array keywords for Field Level Decipher 634278. Access control points for Field Level Decipher 640279. Field Level Decipher required hardware 640280. Rule array keywords for Field Level Encipher 643281. Access control points for Field Level Encipher 649282. Field Level Encipher required hardware 650283. Rule array keywords for FPE Decipher 653284. FPE Decipher required hardware . . . . . 659285. Rule array keywords for FPE Encipher 662286. FPE Encipher required hardware . . . . . 668287. Rule array keywords for FPE Translate 670288. FPE Translate required hardware . . . . . 677289. Rule Array Keywords for PIN

Change/Unblock . . . . . . . . . . 680290. Required access control points for PIN

Change/Unblock . . . . . . . . . . 684291. PIN Change/Unblock hardware . . . . . 684292. Recover PIN from Offset required hardware 688293. Rule Array Keywords for Secure Messaging

for Keys . . . . . . . . . . . . . 690294. Secure Messaging for Keys required hardware 692295. Rule Array Keywords for Secure Messaging

for PINs . . . . . . . . . . . . . 694296. Secure Messaging for PINs required hardware 697297. Keywords for SET Block Compose Control

Information . . . . . . . . . . . . 699298. SET Block Compose required hardware 703299. Keywords for SET Block Compose Control

Information . . . . . . . . . . . . 705300. Required access control points for PIN-block

encrypting key . . . . . . . . . . . 708301. SET Block Decompose required hardware 709302. Rule Array Keywords for Transaction

Validation . . . . . . . . . . . . . 711303. Output description for validation values 712304. Required access control points for Transaction

Validation. . . . . . . . . . . . . 712305. Transaction Validation required hardware 713306. CVV Generate Rule Array Keywords 715307. VISA CVV Service Generate required

hardware . . . . . . . . . . . . . 717308. CVV Verify Rule Array Keywords . . . . 719309. VISA CVV Service Verify required hardware 722310. Rule array keywords for the DK

Deterministic PIN Generate service . . . . 726311. DK Deterministic PIN Generate required

hardware . . . . . . . . . . . . . 731312. Rule array keywords for the DK Migrate PIN

service . . . . . . . . . . . . . . 733313. DK Migrate PIN required hardware . . . . 737

xxii z/OS ICSF Application Programmer's Guide

314. DK PAN Modify in Transaction requiredhardware . . . . . . . . . . . . . 745

315. DK PAN Translate required hardware 752316. Rule array keywords for the DK PIN Change

Service . . . . . . . . . . . . . . 755317. DK PIN Change required hardware . . . . 764318. DK PIN Verify required hardware. . . . . 769319. Keywords for the DK PRW Card Number

Update service . . . . . . . . . . . 771320. DK PRW Card Number Update required

hardware . . . . . . . . . . . . . 776321. DK PRW CMAC Generate required hardware 780322. Rule array keywords for DK Random PIN

Generate with Reference Value Service . . . 782323. DK Random PIN Generate required hardware 787324. DK Regenerate PRW required hardware 793325. Keywords for Digital Signature Generate

Control Information . . . . . . . . . 797326. Digital Signature Generate required hardware 802327. Keywords for Digital Signature Verify Control

Information . . . . . . . . . . . . 805328. Digital Signature Verify required hardware 809329. Keywords for PKA Key Generate Rule Array 815330. Required access control points for PKA Key

Generate rule array keys . . . . . . . . 818331. PKA Key Generate required hardware 818332. Keywords for PKA Key Import . . . . . 821333. PKA Key Import required hardware . . . . 823334. Keywords for PKA Key Token Build Control

Information . . . . . . . . . . . . 826335. Key Value Structure

z/os icsf application programmer's guidefile/csfb400_icsf_apg_hcr77c1.pdf · derive session key...

Documents