z/OS Cryptographic Services Integrated Cryptographic Service Facility Application Programmer's Guide SA22-7522-15 Note! Before using this information and the product it supports, be sure to read the general information in the “Notices” on page 911. This edition applies to Version 1, Release 13 of IBM z/OS (product number 5694-A01) and all subsequent releases and modifications until otherwise indicated in new editions. This edition applies to ICSF FMID HCR7790. This edition replaces SA22-7522-14 © Copyright IBM Corporation 1997, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii About this information . . . . Who should use this information . How to use this information . . . Where to find more information . Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi . xxxi . xxxi . xxxiii . xxxiii How to send your comments to IBM . . . . . . . . . . . . . . . xxxv If you have a technical problem . . . . . . . . . . . . . . . . . . xxxv Summary of changes Changes made in z/OS Changes made in z/OS Changes made in z/OS . . . Version Version Version . . . . 1 Release 1 Release 1 Release . . 13 . 12 . 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvii . xxxvii . xxxix . . xlii Part 1. IBM CCA Programming. . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introducing Programming for the IBM CCA ICSF Callable Services Naming Conventions . . . . . Callable Service Syntax . . . . . . . . . . . . . Callable Services with ALET Parameters . . . . . . Rules for Defining Parameters and Attributes . . . . Parameter Definitions . . . . . . . . . . . . . Invocation Requirements . . . . . . . . . . . . Security Considerations . . . . . . . . . . . . Performance Considerations . . . . . . . . . . . Special Secure Mode . . . . . . . . . . . . . Using the Callable Services . . . . . . . . . . . When the Call Succeeds . . . . . . . . . . . When the Call Does Not Succeed . . . . . . . . Linking a Program with the ICSF Callable Services . . | | | . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 . 3 . 3 . 4 . 5 . 6 . 9 . 9 . 10 . 10 . 11 . 11 . 12 . 12 Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services . . . . . . . . . . . . . . . . . . . . . Functions of the Symmetric Cryptographic Keys. . . . . . . . . . . . . Key Separation . . . . . . . . . . . . . . . . . . . . . . . . Master Key Variant for Fixed-length Tokens . . . . . . . . . . . . . Transport Key Variant for Fixed-length Tokens . . . . . . . . . . . . Key Forms . . . . . . . . . . . . . . . . . . . . . . . . . Key Token . . . . . . . . . . . . . . . . . . . . . . . . . Key Wrapping . . . . . . . . . . . . . . . . . . . . . . . . Control Vector for DES Keys . . . . . . . . . . . . . . . . . . . Types of Keys . . . . . . . . . . . . . . . . . . . . . . . . Generating and Managing Symmetric Keys . . . . . . . . . . . . . . Key Generator Utility Program . . . . . . . . . . . . . . . . . . Common Cryptographic Architecture DES Key Management Services. . . . Common Cryptographic Architecture AES Key Management Services . . . . Common Cryptographic Architecture HMAC Key Management Services . . . ECC Diffie-Hellman Key Agreement Models . . . . . . . . . . . . . Improved remote key distribution . . . . . . . . . . . . . . . . . © Copyright IBM Corp. 1997, 2011 15 15 16 16 16 17 17 19 19 19 25 25 25 29 31 32 32 iii Diversifying keys . . . . . . . . . . . . . . . . . . . . . . . Callable Services for Dynamic CKDS Update. . . . . . . . . . . . . Callable Services that Support Secure Sockets Layer (SSL) . . . . . . . System Encryption Algorithm . . . . . . . . . . . . . . . . . . . ANSI X9.17 Key Management Services . . . . . . . . . . . . . . . Enciphering and Deciphering Data. . . . . . . . . . . . . . . . . . Encoding and Decoding Data (CSNBECO, CSNEECO, CSNBDCO, and CSNEDCO) . . . . . . . . . . . . . . . . . . . . . . . . . Translating Ciphertext (CSNBCTT or CSNBCTT1 and CSNECTT or CSNECTT1) . . . . . . . . . . . . . . . . . . . . . . . . . Managing Data Integrity and Message Authentication . . . . . . . . . . . Message Authentication Code Processing . . . . . . . . . . . . . . Hashing Functions . . . . . . . . . . . . . . . . . . . . . . Managing Personal Authentication . . . . . . . . . . . . . . . . . . Verifying Credit Card Data. . . . . . . . . . . . . . . . . . . . ANSI TR-31 key block support . . . . . . . . . . . . . . . . . . . TR-31 Export Callable Service (CSNBT31X and CSNET31X) . . . . . . . TR-31 Import Callable Service (CSNBT31I and CSNET31I) . . . . . . . TR-31 Parse Callable Service (CSNBT31P and CSNET31P) . . . . . . . TR-31 Optional Data Read Callable Service (CSNBT31R and CSNET31R) TR-31 Optional Data Build Callable Service (CSNBT31O and CSNET31O) Secure Messaging . . . . . . . . . . . . . . . . . . . . . . . Trusted Key Entry (TKE) Support . . . . . . . . . . . . . . . . . . Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character/Nibble Conversion Callable Services (CSNBXBC and CSNBXCB) Code Conversion Callable Services (CSNBXEA and CSNBXAE) . . . . . X9.9 Data Editing Callable Service (CSNB9ED) . . . . . . . . . . . . ICSF Query Algorithm Callable Service (CSFIQA) . . . . . . . . . . . ICSF Query Facility Callable Service (CSFIQF) . . . . . . . . . . . . Typical Sequences of ICSF Callable Services . . . . . . . . . . . . . Key Forms and Types Used in the Key Generate Callable Service . . . . . . Generating an Operational Key . . . . . . . . . . . . . . . . . . Generating an Importable Key . . . . . . . . . . . . . . . . . . Generating an Exportable Key . . . . . . . . . . . . . . . . . . Examples of Single-Length Keys in One Form Only . . . . . . . . . . Examples of OPIM Single-Length, Double-Length, and Triple-Length Keys in Two Forms . . . . . . . . . . . . . . . . . . . . . . . . Examples of OPEX Single-Length, Double-Length, and Triple-Length Keys in Two Forms . . . . . . . . . . . . . . . . . . . . . . . . Examples of IMEX Single-Length and Double-Length Keys in Two Forms Examples of EXEX Single-Length and Double-Length Keys in Two Forms Generating AKEKs . . . . . . . . . . . . . . . . . . . . . . Using the Ciphertext Translate Callable Service . . . . . . . . . . . . . Summary of Callable Services . . . . . . . . . . . . . . . . . . . | | | | | | Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services . . . . . . . . . . . . . . . . . . . . . . PKA Key Algorithms . . . . . . . . . . . . . . . . . . . PKA Master Keys . . . . . . . . . . . . . . . . . . . . Operational private keys . . . . . . . . . . . . . . . . PKA Callable Services . . . . . . . . . . . . . . . . . . Callable Services Supporting Digital Signatures . . . . . . . . Callable Services for PKA Key Management . . . . . . . . . Callable Services to Update the Public Key Data Set (PKDS) . . . Callable Services for Working with Retained Private Keys . . . . Callable Services for SET Secure Electronic Transaction . . . . | iv z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 46 48 49 50 52 53 53 53 53 55 56 57 59 59 59 60 60 60 60 60 61 61 61 61 61 61 62 63 63 63 63 63 64 64 65 65 65 66 67 79 79 79 80 81 81 82 83 84 85 PKA Key Tokens . . . . . . . . . . PKA Key Management . . . . . . . . Security and Integrity of the Token. . . . Key Identifier for PKA Key Token . . . . Key Label . . . . . . . . . . . . Key Token . . . . . . . . . . . The Transaction Security System and ICSF Summary of the PKA Callable Services . . Chapter 4. Introducing PKCS #11 PKCS #11 Management Services . Attribute List . . . . . . . . . Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Portability . . . . and using . . . . . . . . . . . . . . . . . . . . PKCS #11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 86 87 88 88 88 89 89 callable services 93 . . . . . . . . . 93 . . . . . . . . . 94 . . . . . . . . . 95 Part 2. CCA Callable Services . . . . . . . . . . . . . . . . . . . . . . . . 97 | | | | | Chapter 5. Managing Symmetric Cryptographic Keys . . Clear Key Import (CSNBCKI and CSNECKI) . . . . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Control Vector Generate (CSNBCVG and CSNECVG) . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Control Vector Translate (CSNBCVT and CSNECVT) . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Cryptographic Variable Encipher (CSNBCVE and CSNECVE) Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Data Key Export (CSNBDKX and CSNEDKX) . . . . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Data Key Import (CSNBDKM and CSNEDKM) . . . . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Diversified Key Generate (CSNBDKG and CSNEDKG) . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . ECC Diffie-Hellman (CSNDEDH and CSNFEDH) . . . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Key Export (CSNBKEX and CSNEKEX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 100 100 100 101 102 102 102 105 105 106 106 108 108 109 109 109 111 111 111 112 112 113 113 114 114 114 116 116 117 117 118 121 121 123 124 124 128 129 130 Contents v Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Generate (CSNBKGN and CSNEKGN) . . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Generate2 (CSNBKGN2 and CSNEKGN2) . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Import (CSNBKIM and CSNEKIM) . . . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Part Import (CSNBKPI and CSNEKPI) . . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Related Information . . . . . . . . . . . Key Part Import2 (CSNBKPI2 and CSNEKPI2). . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Test (CSNBKYT and CSNEKYT) . . . . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Test2 (CSNBKYT2 and CSNEKYT2) . . . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Test Extended (CSNBKYTX and CSNEKTX) . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Token Build (CSNBKTB and CSNEKTB) . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Related Information . . . . . . . . . . . Key Token Build2 (CSNBKTB2 and CSNEKTB2) . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . Key Translate (CSNBKTR and CSNEKTR) . . . Format . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . vi z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 131 132 133 135 135 135 143 143 147 148 148 153 155 156 156 158 158 160 161 161 163 164 165 165 166 166 168 169 170 170 172 172 173 174 174 177 178 178 178 180 180 181 182 182 188 188 190 191 191 191 197 197 197 198 199 Usage Notes . . . . . . . . . . . . . . . . . . . . . Key Translate2 (CSNBKTR2 and CSNEKTR2) . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Multiple Clear Key Import (CSNBCKM and CSNECKM) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Multiple Secure Key Import (CSNBSKM and CSNESKM) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKA Decrypt (CSNDPKD and CSNFPKD) . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKA Encrypt (CSNDPKE and CSNFPKE) . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Prohibit Export (CSNBPEX and CSNEPEX) . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Prohibit Export Extended (CSNBPEXX and CSNEPEXX) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Random Number Generate (CSNBRNG, CSNERNG, CSNBRNGL and CSNERNGL) . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Remote Key Export (CSNDRKX and CSNFRKX) . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Restrict Key Attribute (CSNBRKA and CSNERKA) . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Secure Key Import (CSNBSKI and CSNESKI) . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Secure Key Import2 (CSNBSKI2 and CSNESKI2) . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . Symmetric Key Export (CSNDSYX and CSNFSYX) . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 199 200 200 204 204 205 206 206 208 209 210 210 213 215 216 216 218 218 220 221 221 223 223 225 225 225 226 226 227 227 228 228 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 229 229 231 232 232 232 238 239 239 239 243 243 244 244 246 247 248 248 251 251 252 Contents vii Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Symmetric Key Generate (CSNDSYG and CSNFSYG) . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Symmetric Key Import (CSNDSYI and CSNFSYI). . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Symmetric Key Import2 (CSNDSYI2 and CSNFSYI2) . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Transform CDMF Key (CSNBTCK and CSNETCK) . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Trusted Block Create (CSNDTBC and CSNFTBC) . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . TR-31 Export (CSNBT31X and CSNET31X). . . . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . TR-31 Import (CSNBT31I and CSNET31I) . . . . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . TR-31 Optional Data Build (CSNBT31O and CSNET31O). Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . TR-31 Optional Data Read (CSNBT31R and CSNET31R) Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . TR-31 Parse (CSNBT31P and CSNET31P) . . . . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . User Derived Key (CSFUDK and CSFUDK6) . . . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . | | | | | | | | | | | | | | | | | | | | | | | | | viii z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 254 254 258 259 259 262 263 266 266 266 269 269 272 273 273 275 275 277 277 277 279 279 279 280 280 282 283 283 283 288 288 298 298 298 303 303 311 311 311 313 313 314 314 314 317 317 318 318 318 320 320 321 322 322 324 Chapter 6. Protecting Data . . . . . . . . . . . . . . . . . . . Modes of Operation. . . . . . . . . . . . . . . . . . . . . . . Electronic Code Book (ECB) Mode . . . . . . . . . . . . . . . . Cipher Block Chaining (CBC) Mode . . . . . . . . . . . . . . . . Cipher Feedback (CFB) Mode . . . . . . . . . . . . . . . . . . Output Feedback (OFB) Mode. . . . . . . . . . . . . . . . . . Galois/Counter Mode (GCM) . . . . . . . . . . . . . . . . . . Triple DES Encryption . . . . . . . . . . . . . . . . . . . . . Ciphertext Translate (CSNBCTT or CSNBCTT1 and CSNECTT or CSNECTT1) Choosing Between CSNBCTT and CSNBCTT1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Decipher (CSNBDEC or CSNBDEC1 and CSNEDEC or CSNEDEC1) . . . . Choosing Between CSNBDEC and CSNBDEC1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . . . . . . . . Decode (CSNBDCO and CSNEDCO) . . . . . . . . . . . . . . . . Considerations . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Encipher (CSNBENC or CSNBENC1 and CSNEENC or CSNEENC1) . . . . Choosing between CSNBENC and CSNBENC1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . . . . . . . . Encode (CSNBECO and CSNEECO) . . . . . . . . . . . . . . . . Considerations . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Symmetric Algorithm Decipher (CSNBSAD or CSNBSAD1 and CSNESAD or CSNESAD1) . . . . . . . . . . . . . . . . . . . . . . . . Choosing Between CSNBSAD and CSNBSAD1 or CSNESAD and CSNESAD1 . . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Symmetric Algorithm Encipher (CSNBSAE or CSNBSAE1 and CSNESAE or CSNESAE1) . . . . . . . . . . . . . . . . . . . . . . . . Choosing between CSNBSAE and CSNBSAE1 or CSNESAE and CSNESAE1 . . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Symmetric Key Decipher (CSNBSYD or CSNBSYD1 and CSNESYD or CSNESYD1) . . . . . . . . . . . . . . . . . . . . . . . . 325 325 326 326 326 326 327 327 328 328 329 329 331 331 331 333 333 333 337 337 337 338 338 338 339 339 339 340 342 342 342 346 346 347 348 348 348 348 349 349 Contents ix 350 350 351 351 355 356 356 357 357 361 362 Choosing Between CSNBSYD and CSNBSYD1 . . Format . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . Symmetric Key Encipher (CSNBSYE or CSNBSYE1 and CSNESYE1) . . . . . . . . . . . . . . . Choosing between CSNBSYE and CSNBSYE1 . . Format . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . x . . . . . . . . . . . . . . . 364 364 365 370 371 . . . . . . . . . . . . . . . . . . 371 373 374 374 379 380 Chapter 7. Verifying Data Integrity and Authenticating Messages . . . . How MACs are Used . . . . . . . . . . . . . . . . . . . . . . How Hashing Functions Are Used . . . . . . . . . . . . . . . . . How MDCs Are Used . . . . . . . . . . . . . . . . . . . . . HMAC Generate (CSNBHMG or CSNBHMG1 and CSNEHMG or CSNEHMG1) Choosing Between CSNBHMG and CSNBHMG1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . HMAC Verify (CSNBHMV or CSNBHMV1 and CSNEHMV or CSNEHMV1) Choosing Between CSNBHMV and CSNBHMV1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . MAC Generate (CSNBMGN or CSNBMGN1 and CSNEMGN or CSNEMGN1) Choosing Between CSNBMGN and CSNBMGN1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . . . . . . . . MAC Verify (CSNBMVR or CSNBMVR1 and CSNEMVR or CSNEMVR1) Choosing Between CSNBMVR and CSNBMVR1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . . . . . . . . MDC Generate (CSNBMDG or CSNBMDG1 and CSNEMDG or CSNEMDG1) Choosing Between CSNBMDG and CSNBMDG1 . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . One-Way Hash Generate (CSNBOWH or CSNBOWH1 and CSNEOWH or CSNEOWH1) . . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . Symmetric MAC Generate (CSNBSMG or CSNBSMG1 and CSNESMG or CSNESMG1) . . . . . . . . . . . . . . . . . . . . . . . . Choosing Between CSNBSMG and CSNBSMG1 or CSNESMG and CSNESMG1 . . . . . . . . . . . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . 383 383 384 384 385 385 386 386 389 389 389 390 390 393 393 394 394 394 397 398 398 399 399 400 403 404 404 404 405 405 407 z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CSNESYE or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 409 409 412 413 413 413 414 417 Symmetric MAC Verify (CSNBSMV or CSNESMV1) . . . . . . . . Choosing Between CSNBSMV and CSNESMV1. . . . . . . . Format . . . . . . . . . . Parameters . . . . . . . . . Usage Notes . . . . . . . . | | | | | | | CSNBSMV1 . . . . . CSNBSMV1 . . . . . . . . . . . . . . . . . . . . and CSNESMV or . . . . . . . or CSNESMV and . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 8. Financial Services . . . . . . . . . . . . . How Personal Identification Numbers (PINs) are Used . . . . . How VISA Card Verification Values Are Used . . . . . . . . Translating Data and PINs in Networks . . . . . . . . . . Working with Europay–MasterCard–Visa smart cards . . . . . PIN Callable Services . . . . . . . . . . . . . . . . . Generating a PIN . . . . . . . . . . . . . . . . . Encrypting a PIN. . . . . . . . . . . . . . . . . . Generating a PIN Validation Value from an Encrypted PIN Block Verifying a PIN . . . . . . . . . . . . . . . . . . Translating a PIN . . . . . . . . . . . . . . . . . Algorithms for Generating and Verifying a PIN . . . . . . . Using PINs on Different Systems . . . . . . . . . . . . PIN-Encrypting Keys . . . . . . . . . . . . . . . . ANSI X9.8 PIN Restrictions . . . . . . . . . . . . . . . ANSI X9.8 PIN - Enforce PIN block restrictions . . . . . . ANSI X9.8 PIN - Allow modification of PAN . . . . . . . . ANSI X9.8 PIN - Allow only ANSI PIN blocks . . . . . . . ANSI X9.8 PIN – Use stored decimalization tables only . . . The PIN Profile . . . . . . . . . . . . . . . . . . . PIN Block Format . . . . . . . . . . . . . . . . . Enhanced PIN Security Mode . . . . . . . . . . . . . Format Control . . . . . . . . . . . . . . . . . . Pad Digit . . . . . . . . . . . . . . . . . . . . Current Key Serial Number . . . . . . . . . . . . . . Decimalization Tables . . . . . . . . . . . . . . . . Clear PIN Encrypt (CSNBCPE and CSNECPE) . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . Clear PIN Generate (CSNBPGN and CSNEPGN) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . . . Clear PIN Generate Alternate (CSNBCPA and CSNECPA) . . . Format . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . CVV Key Combine (CSNBCKC and CSNECKC) . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . Encrypted PIN Generate (CSNBEPG and CSNEEPG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 . . . . . . . . . . . . . . . . 417 418 418 421 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 423 423 424 424 425 425 425 425 425 425 425 426 426 427 427 428 428 428 429 429 431 432 432 433 434 434 435 435 437 437 438 438 438 441 441 442 442 443 443 446 447 448 449 449 451 451 453 Contents xi xii Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Encrypted PIN Translate (CSNBPTR and CSNEPTR) . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Encrypted PIN Verify (CSNBPVR and CSNEPVR) . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . PIN Change/Unblock (CSNBPCU and CSNEPCU) . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Secure Messaging for Keys (CSNBSKY and CSNESKY) . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Secure Messaging for PINs (CSNBSPN and CSNESPN) . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . SET Block Compose (CSNDSBC and CSNFSBC) . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . SET Block Decompose (CSNDSBD and CSNFSBD) . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Transaction Validation (CSNBTRV and CSNETRV) . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . VISA CVV Service Generate (CSNBCSG and CSNECSG) Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . VISA CVV Service Verify (CSNBCSV and CSNECSV) . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 454 457 457 458 459 459 463 463 466 466 466 470 470 472 473 474 474 478 479 479 479 482 482 483 483 486 487 487 487 491 491 492 492 493 496 496 498 498 499 501 502 502 502 505 505 506 507 507 510 510 Chapter 9. Using Digital Signatures . . . . . . . Digital Signature Generate (CSNDDSG and CSNFDSG) Format . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 511 512 512 z/OS V1R13 ICSF Application Programmer's Guide . . . . Restrictions. Usage Notes Digital Signature Format . . Parameters . Restrictions. Usage Notes | | | . . . . . . . . . . . . . . Verify (CSNDDSV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and . . . . . . . . . . . . . . . . . . CSNFDSV). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 515 518 519 519 521 522 Chapter 10. Managing PKA Cryptographic Keys . PKA Key Generate (CSNDPKG and CSNFPKG) . . Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . PKA Key Import (CSNDPKI and CSNFPKI) . . . . Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . PKA Key Token Build (CSNDPKB and CSNFPKB) . Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . PKA Key Token Change (CSNDKTC and CSNFKTC) Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . PKA Key Translate (CSNDPKT and CSNFPKT) . . Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . PKA Public Key Extract (CSNDPKX and CSNFPKX) Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . Retained Key Delete (CSNDRKD and CSNFRKD) . Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . Retained Key List (CSNDRKL and CSNFRKL) . . . Format . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 525 526 526 530 530 531 532 532 534 534 535 536 537 547 548 548 548 550 551 552 552 554 554 555 556 556 557 558 558 558 559 560 561 561 563 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 565 565 565 566 566 567 567 567 568 569 Chapter 11. Key Data Set Management . . . . . . . CKDS Key Record Create (CSNBKRC and CSNEKRC) . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . CKDS Key Record Create2 (CSNBKRC2 and CSNEKRC2) Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . CKDS Key Record Delete (CSNBKRD and CSNEKRD) . Contents xiii | | | | | | | | | | | xiv Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . CKDS Key Record Read (CSNBKRR and CSNEKRR) . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . CKDS Key Record Read2 (CSNBKRR2 and CSNEKRR2) . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . CKDS Key Record Write (CSNBKRW and CSNEKRW) . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . CKDS Key Record Write2 (CSNBKRW2 and CSNEKRW2) . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . Coordinated KDS Administration (CSFCRC and CSFCRC6) . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKDS Key Record Create (CSNDKRC and CSNFKRC) . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKDS Key Record Delete (CSNDKRD and CSNFKRD) . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKDS Key Record Read (CSNDKRR and CSNFKRR) . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKDS Key Record Write (CSNDKRW and CSNFKRW). . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Restrictions. . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 569 570 570 571 571 571 572 572 573 573 573 574 575 575 575 576 576 577 577 578 578 579 580 580 580 582 583 583 583 584 585 585 585 586 587 587 587 588 589 589 590 590 591 591 Chapter 12. Utilities . . . . . . . . . . . . . . Character/Nibble Conversion (CSNBXBC and CSNBXCB) Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . Code Conversion (CSNBXEA and CSNBXAE) . . . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . ICSF Query Algorithm (CSFIQA and CSFIQA6) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 593 593 593 594 595 595 595 596 597 z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . Format . . . . . . . . . . . . . Parameters . . . . . . . . . . . . Usage Notes . . . . . . . . . . . ICSF Query Facility (CSFIQF and CSFIQF6) Format . . . . . . . . . . . . . Parameters . . . . . . . . . . . . Usage Notes . . . . . . . . . . . X9.9 Data Editing (CSNB9ED). . . . . . Format . . . . . . . . . . . . . Parameters . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 598 601 602 602 603 620 621 621 622 622 Chapter 13. Trusted Key Entry Workstation Interfaces . PCI Interface Callable Service (CSFPCI and CSFPCI6) . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . PKSC Interface Callable Service (CSFPKSC) . . . . . Format . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 625 625 625 629 629 630 630 631 Chapter 14. Managing Keys According to the ANSI X9.17 Standard ANSI X9.17 EDC Generate (CSNAEGN and CSNGEGN) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . ANSI X9.17 Key Export (CSNAKEX and CSNGKEX) . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . ANSI X9.17 Key Import (CSNAKIM and CSNGKIM) . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . ANSI X9.17 Key Translate (CSNAKTR and CSNGKTR) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . ANSI X9.17 Transport Key Partial Notarize (CSNATKN and CSNGTKN) Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 633 633 633 635 635 636 636 640 640 641 641 644 645 646 646 649 650 650 650 652 Part 3. PKCS #11 Callable Services . . . . . . . . . . . . . . . . . . . . . 653 | | Chapter 15. Using PKCS #11 Tokens and Objects . . . PKCS #11 Derive multiple keys (CSFPDMK and CSFPDMK6) Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKCS #11 Derive key (CSFPDVK and CSFPDVK6) . . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 655 656 656 661 661 663 663 663 667 Contents xv Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Get attribute value (CSFPGAV and CSFPGAV6) . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Generate key pair (CSFPGKP and CSFPGKP6) . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Generate secret key (CSFPGSK and CSFPGSK6) . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Generate HMAC (CSFPHMG and CSFPHMG6) . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Verify HMAC (CSFPHMV and CSFPHMV6). . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 One-way hash, sign, or verify (CSFPOWH and CSFPOWH6) Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Private key sign (CSFPPKS and CSFPPKS6) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Public key verify (CSFPPKV and CSFPPKV6) . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Pseudo-random function (CSFPPRF and CSFPPRF6) . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Set attribute value (CSFPSAV and CSFPSAV6) . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . PKCS #11 Secret key decrypt (CSFPSKD and CSFPSKD6) . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . | | | | | | | | | | xvi z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 668 668 668 670 671 671 671 671 673 673 673 673 673 675 675 675 676 676 678 678 679 679 679 682 682 682 683 683 686 687 687 687 688 689 689 689 690 690 692 692 692 692 692 694 694 695 695 695 696 696 697 697 697 701 701 | | | | | | PKCS #11 Secret key encrypt (CSFPSKE and CSFPSKE6) . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKCS #11 Token record create (CSFPTRC and CSFPTRC6) Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKCS #11 Token record delete (CSFPTRD and CSFPTRD6) Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKCS #11 Token record list (CSFPTRL and CSFPTRL6) . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . PKCS #11 Unwrap key (CSFPUWK and CSFPUWK6) . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . PKCS #11 Wrap key (CSFPWPK and CSFPWPK6) . . . . Format . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 702 702 706 706 707 707 708 709 710 711 711 711 712 712 713 713 713 715 716 717 717 717 719 720 720 720 722 Part 4. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 Appendix A. ICSF and TSS Return and Reason Return Codes and Reason Codes . . . . . . Return Codes . . . . . . . . . . . . . Reason Codes for Return Code 0 (0) . . . . Reason Codes for Return Code 4 (4) . . . . Reason Codes for Return Code 8 (8) . . . . Reason Codes for Return Code C (12) . . . Reason Codes for Return Code 10 (16) . . . | | | Appendix B. Key Token Formats . . . . . AES Key Token Formats . . . . . . . . . AES Internal Key Token . . . . . . . . Token Validation Value . . . . . . . . DES Key Token Formats . . . . . . . . . DES Internal Key Token . . . . . . . . DES External Key Token . . . . . . . . External RKX DES Key Token . . . . . . DES Null Key Token . . . . . . . . . Variable-length Symmetric Key Token Formats . Variable-length Symmetric Key Token . . . Variable-length Symmetric Null Key Token . PKA Key Token Formats . . . . . . . . . PKA Null Key Token . . . . . . . . . RSA Key Token Formats . . . . . . . . DSS Key Token Formats . . . . . . . . . . . . . . . . . . . . . . . . Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725 725 725 726 727 730 765 776 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 777 777 778 778 778 780 781 782 782 782 792 793 793 793 803 Contents xvii ECC Key Token Format . . . . . . . . . . . . . . . . . . . . 807 Trusted Block Key Token . . . . . . . . . . . . . . . . . . . . 811 xviii Appendix C. Control Vectors and Changing Control Vectors with the CVT Callable Service . . . . . . . . . . . . . . . . . . . . . . . Control Vector Table . . . . . . . . . . . . . . . . . . . . . . Specifying a Control-Vector-Base Value . . . . . . . . . . . . . . Changing Control Vectors with the Control Vector Translate Callable Service Providing the Control Information for Testing the Control Vectors . . . . . Mask Array Preparation . . . . . . . . . . . . . . . . . . . . Selecting the Key-Half Processing Mode . . . . . . . . . . . . . . When the Target Key Token CV Is Null . . . . . . . . . . . . . . Control Vector Translate Example . . . . . . . . . . . . . . . . 827 827 832 837 837 837 839 841 841 Appendix D. C . . . . COBOL . . Assembler H PL/1 . . . Coding . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 843 846 848 850 Appendix E. Using ICSF with BSAFE . . . . . . . Some BSAFE Basics . . . . . . . . . . . . . . Computing Message Digests and Hashes . . . . . Generating Random Numbers . . . . . . . . . . Encrypting and Decrypting with DES . . . . . . . Generating and Verifying RSA Digital Signatures . . . Encrypting and Decrypting with RSA . . . . . . . . Using the New Function Calls in Your BSAFE Application . Using the BSAFE KI_TOKEN . . . . . . . . . . . ICSF Triple DES via BSAFE . . . . . . . . . . . Retrieving ICSF Error Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855 855 855 855 856 856 857 857 859 859 860 Appendix F. Cryptographic Algorithms and Processes . . PIN Formats and Algorithms . . . . . . . . . . . . . PIN Notation . . . . . . . . . . . . . . . . . . PIN Block Formats . . . . . . . . . . . . . . . . PIN Extraction Rules . . . . . . . . . . . . . . . IBM PIN Algorithms . . . . . . . . . . . . . . . . VISA PIN Algorithms . . . . . . . . . . . . . . . Cipher Processing Rules . . . . . . . . . . . . . . . CBC and ANSI X3.106 . . . . . . . . . . . . . . ANSI X9.23 and IBM 4700 . . . . . . . . . . . . . CUSP . . . . . . . . . . . . . . . . . . . . . The Information Protection System (IPS) . . . . . . . . PKCS Padding Method . . . . . . . . . . . . . . Wrapping Methods for Symmetric Key Tokens . . . . . . . ECB Wrapping of DES Keys (Original Method). . . . . . CBC Wrapping of AES Keys . . . . . . . . . . . . Enhanced CBC Wrapping of DES Keys (Enhanced Method). Wrapping key derivation for enhanced wrapping of DES keys Variable length token (AESKW method) . . . . . . . . PKA92 Key Format and Encryption Process. . . . . . . . ANSI X9.17 Partial Notarization Method . . . . . . . . . Partial Notarization . . . . . . . . . . . . . . . . Transform CDMF Key Algorithm . . . . . . . . . . . . Formatting Hashes and Keys in Public-Key Cryptography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 863 863 863 865 866 872 874 874 875 876 876 877 879 879 879 879 880 881 881 883 883 884 885 z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ANSI X9.31 Hash Format . . . . . . . . . . . . . . . PKCS #1 Formats . . . . . . . . . . . . . . . . . . Visa and EMV-related smart card formats and processes . . . . . Deriving the smart-card-specific authentication code. . . . . . Constructing the PIN-block for transporting an EMV smart-card PIN Deriving the CCA TDES-XOR session key . . . . . . . . . Deriving the EMV TDESEMVn tree-based session key . . . . . PIN-block self-encryption . . . . . . . . . . . . . . . . Key Test Verification Pattern Algorithms . . . . . . . . . . . DES Algorithm (single- and double-length keys) . . . . . . . SHAVP1 Algorithm . . . . . . . . . . . . . . . . . . Appendix G. EBCDIC and ASCII Default Conversion Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886 886 887 887 888 888 889 889 889 889 889 . . . . . . 891 Appendix H. Access Control Points and Callable Services . . . . . . . 893 Callable Service Access Control Points . . . . . . . . . . . . . . . 898 Appendix I. Accessibility . . Using assistive technologies . Keyboard navigation of the user z/OS information . . . . . . . . . . . . . . interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 909 909 909 Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 911 Programming Interface Information . . . . . . . . . . . . . . . . . 912 Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 912 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 913 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923 Contents xix xx z/OS V1R13 ICSF Application Programmer's Guide Figures 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. Overview of trusted block contents . . . . . . . . . . . . . . . . . . . . . . . . 35 Simplified RKX key-token structure . . . . . . . . . . . . . . . . . . . . . . . . 39 Trusted block creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Exporting keys using a trusted block . . . . . . . . . . . . . . . . . . . . . . . 40 Generating keys using a trusted block . . . . . . . . . . . . . . . . . . . . . . . 43 Typical flow of callable services for remote key export . . . . . . . . . . . . . . . . . 44 PKA Key Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Control Vector Base Bit Map (Common Bits and Key-Encrypting Keys) . . . . . . . . . . 829 Control Vector Base Bit Map (Data Operation Keys) . . . . . . . . . . . . . . . . . 830 Control Vector Base Bit Map (PIN Processing Keys and Cryptographic Variable-Encrypting Keys) 831 Control Vector Base Bit Map (Key Generating Keys) . . . . . . . . . . . . . . . . . 832 Control Vector Translate Callable Service Mask_Array Processing . . . . . . . . . . . . 839 Control Vector Translate Callable Service . . . . . . . . . . . . . . . . . . . . . 840 3624 PIN Generation Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 867 GBP PIN Generation Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 868 PIN-Offset Generation Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . 869 PIN Verification Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 871 GBP PIN Verification Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 872 PVV Generation Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 873 The CDMF Key Transformation Algorithm . . . . . . . . . . . . . . . . . . . . . 885 © Copyright IBM Corp. 1997, 2011 xxi xxii z/OS V1R13 ICSF Application Programmer's Guide Tables | | | | | | | | | | | | | | | | | 1. ICSF Callable Services Naming Conventions . . . . . . . . . . . . . . . . . . . . . 3 2. Standard Return Code Values From ICSF Callable Services . . . . . . . . . . . . . . . 7 3. Descriptions of Key Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4. Summary of Data Encryption Standard Bits . . . . . . . . . . . . . . . . . . . . . 50 5. Combinations of the Callable Services . . . . . . . . . . . . . . . . . . . . . . . 62 6. Summary of ICSF Callable Services. . . . . . . . . . . . . . . . . . . . . . . . 67 7. Summary of PKA Key Token Sections . . . . . . . . . . . . . . . . . . . . . . . 86 8. Summary of PKA Callable Services . . . . . . . . . . . . . . . . . . . . . . . . 90 9. Summary of PKCS #11 callable services . . . . . . . . . . . . . . . . . . . . . . 93 10. Clear key import required hardware . . . . . . . . . . . . . . . . . . . . . . . 101 11. Control vector generate required hardware . . . . . . . . . . . . . . . . . . . . . 105 12. Keywords for Control Vector Translate . . . . . . . . . . . . . . . . . . . . . . 107 13. Control vector translate required hardware . . . . . . . . . . . . . . . . . . . . . 109 14. Cryptographic variable encipher required hardware . . . . . . . . . . . . . . . . . . 111 15. Required access control points for Data key export . . . . . . . . . . . . . . . . . . 113 16. Data key export required hardware . . . . . . . . . . . . . . . . . . . . . . . . 114 17. Required access control points for Data key import . . . . . . . . . . . . . . . . . . 116 18. Data key import required hardware . . . . . . . . . . . . . . . . . . . . . . . . 116 19. Rule Array Keywords for Diversified Key Generate . . . . . . . . . . . . . . . . . . 118 20. Required access control points for Diversified Key Generate . . . . . . . . . . . . . . 122 21. Diversified key generate required hardware . . . . . . . . . . . . . . . . . . . . 122 22. Keywords for ECC Diffie-Hellman . . . . . . . . . . . . . . . . . . . . . . . . 125 23. Valid key bit lengths and minimum curve size required for the supported output key types. 129 24. ECC Diffie-Hellman required hardware . . . . . . . . . . . . . . . . . . . . . . 130 25. Required access control points for Key Export . . . . . . . . . . . . . . . . . . . 134 26. Key export required hardware . . . . . . . . . . . . . . . . . . . . . . . . . 134 27. Key Form Values for the Key Generate Callable Service . . . . . . . . . . . . . . . . 136 28. Key Length Values for the Key Generate Callable Service . . . . . . . . . . . . . . . 137 29. Key lengths for DES keys - CCF systems . . . . . . . . . . . . . . . . . . . . . 138 30. Key lengths for DES keys - PCIXCC/CEX2C/CEX3C systems . . . . . . . . . . . . . . 139 31. Key lengths for AES keys - CEX2C/CEX3C systems . . . . . . . . . . . . . . . . . 140 32. Required access control points for Key Generate . . . . . . . . . . . . . . . . . . 143 33. Key Generate Valid Key Types and Key Forms for a Single Key . . . . . . . . . . . . . 144 34. Key Generate Valid Key Types and Key Forms for a Key Pair . . . . . . . . . . . . . . 144 35. Key generate required hardware. . . . . . . . . . . . . . . . . . . . . . . . . 146 36. Keywords for Key Generate2 Control Information . . . . . . . . . . . . . . . . . . 149 37. Keywords and associated algorithms for key_type_1 parameter . . . . . . . . . . . . . 150 38. Keywords and associated algorithms for key_type_2 parameter . . . . . . . . . . . . . 150 39. Key Generate2 valid key type and key form for one key . . . . . . . . . . . . . . . . 154 40. Key Generate2 Valid key type and key forms for two keys . . . . . . . . . . . . . . . 154 41. AES KEK strength required for generating an HMAC key under an AES KEK . . . . . . . . 154 42. Required access control points for Key Generate2 . . . . . . . . . . . . . . . . . . 154 43. Key Generate2 required hardware . . . . . . . . . . . . . . . . . . . . . . . . 155 44. Required access control points for Key Import . . . . . . . . . . . . . . . . . . . 159 45. Key import required hardware . . . . . . . . . . . . . . . . . . . . . . . . . 160 46. Keywords for Key Part Import Control Information . . . . . . . . . . . . . . . . . . 162 47. Required access control points for Key Part Import . . . . . . . . . . . . . . . . . . 164 48. Key part import required hardware . . . . . . . . . . . . . . . . . . . . . . . . 164 49. Keywords for Key Part Import2 Control Information . . . . . . . . . . . . . . . . . . 167 50. Required access control points for Key Part Import2 . . . . . . . . . . . . . . . . . 168 51. Key Part Import2 required hardware . . . . . . . . . . . . . . . . . . . . . . . 168 52. Keywords for Key Test Control Information . . . . . . . . . . . . . . . . . . . . . 171 53. Key test required hardware . . . . . . . . . . . . . . . . . . . . . . . . . . 173 © Copyright IBM Corp. 1997, 2011 xxiii | | | | | | | | | | | | | | 54. Keywords for Key Test2 Control Information . . . . . . . . . . . . . . . . . . . 55. Key Test2 required hardware . . . . . . . . . . . . . . . . . . . . . . . . . 56. Keywords for Key Test Extended Control Information . . . . . . . . . . . . . . . . 57. Key test extended required hardware . . . . . . . . . . . . . . . . . . . . . . 58. Key type keywords for key token build . . . . . . . . . . . . . . . . . . . . . 59. Keywords for Key Token Build Control Information . . . . . . . . . . . . . . . . . 60. Key types and field lengths for AES keys . . . . . . . . . . . . . . . . . . . . 61. Control Vector Generate and Key Token Build Control Vector Keyword Combinations . . . . 62. Key token build required hardware . . . . . . . . . . . . . . . . . . . . . . . 63. Keywords for Key Token Build2 Control Information . . . . . . . . . . . . . . . . 64. Key Token Build2 required hardware . . . . . . . . . . . . . . . . . . . . . . 65. Key translate required hardware . . . . . . . . . . . . . . . . . . . . . . . . 66. Key Translate2 Access Control Points. . . . . . . . . . . . . . . . . . . . . . 67. Key Translate2 required hardware . . . . . . . . . . . . . . . . . . . . . . . 68. Keywords for Multiple Clear Key Import Rule Array Control Information . . . . . . . . . 69. Required access control points for Multiple Clear Key Import . . . . . . . . . . . . . 70. Multiple clear key import required hardware . . . . . . . . . . . . . . . . . . . 71. Keywords for Multiple Secure Key Import Rule Array Control Information . . . . . . . . . 72. Required access control points for Multiple Secure Key Import . . . . . . . . . . . . 73. Multiple secure key import required hardware . . . . . . . . . . . . . . . . . . . 74. Keywords for PKA Decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . 75. PKA decrypt required hardware . . . . . . . . . . . . . . . . . . . . . . . . 76. Keywords for PKA Encrypt . . . . . . . . . . . . . . . . . . . . . . . . . . 77. PKA encrypt required hardware . . . . . . . . . . . . . . . . . . . . . . . . 78. Prohibit export required hardware . . . . . . . . . . . . . . . . . . . . . . . 79. Prohibit export extended required hardware . . . . . . . . . . . . . . . . . . . 80. Keywords for the Form Parameter . . . . . . . . . . . . . . . . . . . . . . . 81. Keywords for Random Number Generate Control Information . . . . . . . . . . . . . 82. Random number generate required hardware . . . . . . . . . . . . . . . . . . . 83. Structure of values used by RKX . . . . . . . . . . . . . . . . . . . . . . . 84. Values defined for hash algorithm identifier at offset 24 in the structure for remote key export 85. Transport_key_identifer used by RKX . . . . . . . . . . . . . . . . . . . . . . 86. Examination of key token for source_key_identifier . . . . . . . . . . . . . . . . . 87. Remote key export required hardware . . . . . . . . . . . . . . . . . . . . . 88. Keywords for Restrict Key Attribute Control Information . . . . . . . . . . . . . . . 89. Restrict Key Attribute required hardware . . . . . . . . . . . . . . . . . . . . . 90. Required access control points for Secure Key Import. . . . . . . . . . . . . . . . 91. Secure key import required hardware . . . . . . . . . . . . . . . . . . . . . . 92. Keywords for Secure Key Import2 Control Information. . . . . . . . . . . . . . . . 93. Required access control points for Secure Key Import2 . . . . . . . . . . . . . . . 94. Secure Key Import2 required hardware . . . . . . . . . . . . . . . . . . . . . 95. Keywords for Symmetric Key Export Control Information . . . . . . . . . . . . . . . 96. AES EXPORTER strength required for exporting an HMAC key under an AES EXPORTER 97. Minimum RSA modulus strength required to contain a PKOAEP2 block when exporting an AES key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98. Minimum RSA modulus length to adequately protect an AES key . . . . . . . . . . . 99. Required access control points for Symmetric Key Export . . . . . . . . . . . . . . 100. Symmetric key export required hardware . . . . . . . . . . . . . . . . . . . . 101. Keywords for Symmetric Key Generate Control Information . . . . . . . . . . . . . . 102. Required access control points for Symmetric Key Generate . . . . . . . . . . . . . 103. Symmetric key generate required hardware . . . . . . . . . . . . . . . . . . . 104. Keywords for Symmetric Key Import Control Information . . . . . . . . . . . . . . . 105. Required access control points for Symmetric Key Import . . . . . . . . . . . . . . 106. Symmetric key import required hardware . . . . . . . . . . . . . . . . . . . . 107. Keywords for Symmetric Key Import2 Control Information . . . . . . . . . . . . . . 108. PKCS#1 OAEP encoded message layout (PKOAEP2) . . . . . . . . . . . . . . . xxiv z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 177 179 181 183 184 186 188 190 192 197 199 205 205 207 208 208 211 213 214 217 219 222 224 226 228 230 230 231 234 235 235 236 238 240 243 246 247 249 251 251 253 255 255 255 256 257 260 263 264 267 269 270 274 275 | | | | | | | | | | | | | | | 109. Symmetric Key Import2 Access Control Points . . . . . . . . . . . . . . 110. Symmetric key import2 required hardware . . . . . . . . . . . . . . . . 111. Transform CDMF key required hardware . . . . . . . . . . . . . . . . 112. Rule_array keywords for Trusted Block Create (CSNDTBC) . . . . . . . . . 113. Required access control points for Trusted Block Create . . . . . . . . . . . 114. Trusted Block Create required hardware . . . . . . . . . . . . . . . . . 115. Keywords for TR-31 Export Rule Array Control Information . . . . . . . . . . 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) 117. TR-31 export required hardware . . . . . . . . . . . . . . . . . . . . 118. Keywords for TR-31 Import Rule Array Control Information . . . . . . . . . . 119. Export attributes of an imported CCA token . . . . . . . . . . . . . . . 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) 121. TR-31 export required hardware . . . . . . . . . . . . . . . . . . . . 122. TR-31 Optional Data Build required hardware . . . . . . . . . . . . . . . 123. Keywords for TR-31 Optional Data Read Rule Array Control Information . . . . . 124. TR-31 Optional Data Read required hardware. . . . . . . . . . . . . . . 125. TR-31 Parse required hardware . . . . . . . . . . . . . . . . . . . . 126. Keywords for User Derived Key Control Information . . . . . . . . . . . . 127. User derived key required hardware . . . . . . . . . . . . . . . . . . 128. Ciphertext translate required hardware . . . . . . . . . . . . . . . . . 129. Keywords for the Decipher Rule Array Control Information . . . . . . . . . . 130. Decipher required hardware . . . . . . . . . . . . . . . . . . . . . 131. Decode required hardware . . . . . . . . . . . . . . . . . . . . . . 132. Keywords for the Encipher Rule Array Control Information . . . . . . . . . . 133. Encipher required hardware . . . . . . . . . . . . . . . . . . . . . 134. Encode required hardware . . . . . . . . . . . . . . . . . . . . . . 135. Symmetric Algorithm Decipher Rule Array Keywords . . . . . . . . . . . . 136. Symmetric Algorithm Decipher required hardware . . . . . . . . . . . . . 137. Symmetric Algorithm Encipher Rule Array Keywords . . . . . . . . . . . . 138. Symmetric Algorithm Encipher required hardware . . . . . . . . . . . . . 139. Symmetric Key Decipher Rule Array Keywords . . . . . . . . . . . . . . 140. Required access control points for Symmetric Key Decipher . . . . . . . . . 141. Symmetric Key Decipher required hardware . . . . . . . . . . . . . . . 142. Symmetric Key Encipher Rule Array Keywords . . . . . . . . . . . . . . 143. Required access control points for Symmetric Key Encipher . . . . . . . . . 144. Symmetric Key Encipher required hardware . . . . . . . . . . . . . . . 145. Keywords for HMAC Generate Control Information . . . . . . . . . . . . . 146. HMAC Generate Access Control Points . . . . . . . . . . . . . . . . . 147. HMAC generate required hardware . . . . . . . . . . . . . . . . . . 148. Keywords for HMAC Verify Control Information . . . . . . . . . . . . . . 149. HMAC Verify Access Control Points . . . . . . . . . . . . . . . . . . 150. HMAC generate required hardware . . . . . . . . . . . . . . . . . . 151. Keywords for MAC generate Control Information. . . . . . . . . . . . . . 152. MAC generate required hardware . . . . . . . . . . . . . . . . . . . 153. Keywords for MAC verify Control Information . . . . . . . . . . . . . . . 154. MAC verify required hardware . . . . . . . . . . . . . . . . . . . . 155. Keywords for MDC Generate Control Information . . . . . . . . . . . . . 156. MDC generate required hardware . . . . . . . . . . . . . . . . . . . 157. Keywords for One-Way Hash Generate Rule Array Control Information . . . . . 158. One-way hash generate required hardware. . . . . . . . . . . . . . . . 159. Keywords for symmetric MAC generate control information . . . . . . . . . . 160. Symmetric MAC generate required hardware . . . . . . . . . . . . . . . 161. Keywords for symmetric MAC verify control information . . . . . . . . . . . 162. Symmetric MAC verify required hardware . . . . . . . . . . . . . . . . 163. ANSI X9.8 PIN - Allow only ANSI PIN blocks . . . . . . . . . . . . . . . 164. Format of a PIN Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 276 279 281 282 282 284 289 297 299 304 305 310 314 315 317 321 323 324 331 335 338 340 344 347 349 352 355 358 361 366 370 371 375 380 380 387 389 389 391 393 393 396 398 401 403 406 408 410 412 415 417 420 421 428 429 xxv | | | | | | | | | | | | 165. Format Values of PIN Blocks . . . . . . . . . . . . . . . . . . . . 166. PIN Block Format and PIN Extraction Method Keywords . . . . . . . . . . 167. Callable Services Affected by Enhanced PIN Security Mode . . . . . . . . 168. Format of a Pad Digit. . . . . . . . . . . . . . . . . . . . . . . 169. Pad Digits for PIN Block Formats . . . . . . . . . . . . . . . . . . 170. Format of the Current Key Serial Number Field . . . . . . . . . . . . . 171. Process Rules for the Clear PIN Encryption Callable Service . . . . . . . . 172. Clear PIN encrypt required hardware . . . . . . . . . . . . . . . . . 173. Process Rules for the Clear PIN Generate Callable Service . . . . . . . . 174. Array Elements for the Clear PIN Generate Callable Service . . . . . . . . 175. Array Elements Required by the Process Rule . . . . . . . . . . . . . 176. Required access control points for Clear PIN Generate . . . . . . . . . . 177. Clear PIN generate required hardware . . . . . . . . . . . . . . . . 178. Rule Array Elements for the Clear PIN Generate Alternate Service . . . . . . 179. Rule Array Keywords (First Element) for the Clear PIN Generate Alternate Service 180. Data Array Elements for the Clear PIN Generate Alternate Service (IBM-PINO) . 181. Data Array Elements for the Clear PIN Generate Alternate Service (VISA-PVV) . 182. PIN Block Variant Constants (PBVCs) . . . . . . . . . . . . . . . . 183. Required access control points for Clear PIN Generate Alternate. . . . . . . 184. Clear PIN generate alternate required hardware . . . . . . . . . . . . . 185. Keywords for CVV Key Combine Rule Array Control Information . . . . . . . 186. Key type combinations for the CVV key combine callable service . . . . . . 187. Wrapping combinations for the CVV Combine Callable Service . . . . . . . 188. TR-31 export required hardware . . . . . . . . . . . . . . . . . . . 189. Process Rules for the Encrypted PIN Generate Callable Service . . . . . . . 190. Array Elements for the Encrypted PIN Generate Callable Service . . . . . . 191. Array Elements Required by the Process Rule . . . . . . . . . . . . . 192. Required access control points for Encrypted PIN Generate . . . . . . . . 193. Encrypted PIN generate required hardware. . . . . . . . . . . . . . . 194. Keywords for Encrypted PIN Translate . . . . . . . . . . . . . . . . 195. Additional Names for PIN Formats . . . . . . . . . . . . . . . . . . 196. PIN Block Variant Constants (PBVCs) . . . . . . . . . . . . . . . . 197. Required access control points for Encrypted PIN Translate . . . . . . . . 198. Encrypted PIN translate required hardware . . . . . . . . . . . . . . . 199. Keywords for Encrypted PIN Verify . . . . . . . . . . . . . . . . . . 200. Array Elements for the Encrypted PIN Verify Callable Service . . . . . . . . 201. Array Elements Required by the Process Rule . . . . . . . . . . . . . 202. PIN Block Variant Constants (PBVCs) . . . . . . . . . . . . . . . . 203. Required access control points for Encrypted PIN Verify . . . . . . . . . . 204. Encrypted PIN verify required hardware . . . . . . . . . . . . . . . . 205. Rule Array Keywords for PIN Change/Unblock . . . . . . . . . . . . . 206. Required access control points for PIN Change/Unblock . . . . . . . . . . 207. PIN Change/Unblock hardware . . . . . . . . . . . . . . . . . . . 208. Rule Array Keywords for Secure Messaging for Keys . . . . . . . . . . . 209. Secure messaging for keys required hardware . . . . . . . . . . . . . 210. Rule Array Keywords for Secure Messaging for PINs . . . . . . . . . . . 211. Secure messaging for PINs required hardware . . . . . . . . . . . . . 212. Keywords for SET Block Compose Control Information . . . . . . . . . . 213. SET block compose required hardware . . . . . . . . . . . . . . . . 214. Keywords for SET Block Compose Control Information . . . . . . . . . . 215. Required access control points for PIN-block encrypting key . . . . . . . . 216. SET block decompose required hardware . . . . . . . . . . . . . . . 217. Rule Array Keywords for Transaction Validation . . . . . . . . . . . . . 218. Output description for validation values . . . . . . . . . . . . . . . . 219. Required access control points for Transaction Validation . . . . . . . . . 220. Transaction validation required hardware . . . . . . . . . . . . . . . xxvi z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 430 431 433 433 434 436 437 439 440 441 441 442 445 445 446 446 447 447 448 450 452 452 453 455 456 456 457 457 461 463 463 464 465 468 469 470 471 471 472 475 478 478 480 482 484 486 488 492 493 497 497 499 501 501 501 | | | | | | | | 221. CVV Generate Rule Array Keywords . . . . . . . . . . . . . . . 222. VISA CVV service generate required hardware . . . . . . . . . . . 223. CVV Verify Rule Array Keywords . . . . . . . . . . . . . . . . 224. VISA CVV service verify required hardware . . . . . . . . . . . . 225. Keywords for Digital Signature Generate Control Information . . . . . . 226. Digital signature generate required hardware . . . . . . . . . . . . 227. Keywords for Digital Signature Verify Control Information . . . . . . . 228. Digital signature verify required hardware . . . . . . . . . . . . . 229. Keywords for PKA Key Generate Rule Array . . . . . . . . . . . . 230. Required access control points for PKA Key Generate rule array keys . . . 231. PKA key generate required hardware . . . . . . . . . . . . . . . 232. Keywords for PKA Key Import . . . . . . . . . . . . . . . . . 233. PKA key import required hardware . . . . . . . . . . . . . . . . 234. Keywords for PKA Key Token Build Control Information . . . . . . . . 235. Key Value Structure Length Maximum Values for Key Types . . . . . . 236. Key Value Structure Elements for PKA Key Token Build . . . . . . . . 237. PKA key token build required hardware . . . . . . . . . . . . . . 238. Rule Array Keywords for PKA Key Token Change . . . . . . . . . . 239. PKA key token change required hardware . . . . . . . . . . . . . 240. Keywords for PKA Key Generate Rule Array . . . . . . . . . . . . 241. Required access control points for PKA Key Translate . . . . . . . . 242. Required access control points for source/target transport key combinations 243. PKA key translate required hardware . . . . . . . . . . . . . . . 244. PKA public key extract build required hardware . . . . . . . . . . . 245. Retained key delete required hardware . . . . . . . . . . . . . . 246. Retained key list required hardware . . . . . . . . . . . . . . . 247. CKDS record create required hardware . . . . . . . . . . . . . . 248. CKDS Key Record Create2 required hardware . . . . . . . . . . . 249. CKDS record delete required hardware . . . . . . . . . . . . . . 250. CKDS record read required hardware . . . . . . . . . . . . . . . 251. CKDS key record read2 required hardware. . . . . . . . . . . . . 252. CKDS record write required hardware. . . . . . . . . . . . . . . 253. CKDS key record write2 required hardware . . . . . . . . . . . . 254. Coordinated CKDS administration required hardware . . . . . . . . . 255. PKDS key record create required hardware . . . . . . . . . . . . 256. Keywords for PKDS Key Record Delete . . . . . . . . . . . . . . 257. PKDS key record delete required hardware . . . . . . . . . . . . 258. PKDS key record read required hardware . . . . . . . . . . . . . 259. Keywords for PKDS Key Record Write . . . . . . . . . . . . . . 260. PKDS key record write required hardware . . . . . . . . . . . . . 261. Character/Nibble conversion required hardware . . . . . . . . . . . 262. Code conversion required hardware . . . . . . . . . . . . . . . 263. Keywords for ICSF Query Algorithm . . . . . . . . . . . . . . . 264. Output for ICSF Query Algorithm . . . . . . . . . . . . . . . . 265. ICSF Query Algorithm required hardware . . . . . . . . . . . . . 266. Keywords for ICSF Query Service . . . . . . . . . . . . . . . . 267. Output for option ICSFSTAT . . . . . . . . . . . . . . . . . . 268. Output for option ICSFST2 . . . . . . . . . . . . . . . . . . . 269. Output for option NUM-DECT. . . . . . . . . . . . . . . . . . 270. Output for option STATAES . . . . . . . . . . . . . . . . . . 271. Output for option STATCCA . . . . . . . . . . . . . . . . . . 272. Output for option STATCCAE . . . . . . . . . . . . . . . . . . 273. Output for option STATCARD . . . . . . . . . . . . . . . . . . 274. Output for option STATDECT . . . . . . . . . . . . . . . . . . 275. Output for option STATDIAG . . . . . . . . . . . . . . . . . . 276. Output for option STATEID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 506 508 510 513 516 520 522 527 530 530 533 535 537 539 539 548 549 551 553 554 555 555 557 560 563 567 569 571 572 575 577 579 583 585 586 587 589 591 592 595 597 598 599 601 603 605 607 612 612 613 613 614 615 616 617 xxvii | | | | 277. Output for option STATEXPT . . . . . . . . . . . . . . . . . . . . . . . . . 278. Output for option STATAPKA . . . . . . . . . . . . . . . . . . . . . . . . . 279. Output for option WRAPMTHD . . . . . . . . . . . . . . . . . . . . . . . . 280. ICSF Query Service required hardware . . . . . . . . . . . . . . . . . . . . . 281. X9.9 data editing required hardware . . . . . . . . . . . . . . . . . . . . . . 282. Keywords for PCI Interface Callable Service . . . . . . . . . . . . . . . . . . . 283. PCI Interface required hardware . . . . . . . . . . . . . . . . . . . . . . . . 284. PKSC Interface required hardware . . . . . . . . . . . . . . . . . . . . . . . 285. ANSI X9.17 EDC generate required hardware. . . . . . . . . . . . . . . . . . . 286. Keywords for ANSI X9.17 Key Export Rule Array . . . . . . . . . . . . . . . . . 287. ANSI X9.17 key export required hardware . . . . . . . . . . . . . . . . . . . . 288. Keywords for ANSI X9.17 Key Import Rule Array . . . . . . . . . . . . . . . . . 289. ANSI X9.17 key import required hardware . . . . . . . . . . . . . . . . . . . . 290. Keywords for ANSI X9.17 Key Translate Rule Array . . . . . . . . . . . . . . . . 291. ANSI X9.17 key translate required hardware . . . . . . . . . . . . . . . . . . . 292. ANSI X9.17 transport key partial notarize required hardware . . . . . . . . . . . . . 293. Keywords for derive multiple keys . . . . . . . . . . . . . . . . . . . . . . . 294. parms_list parameter format for SSL-KM and TLS-KM mechanisms. . . . . . . . . . . 295. parms_list parameter format for IKE1PHA1 mechanism . . . . . . . . . . . . . . . 296. parms_list parameter format for IKE2PHA1 mechanism . . . . . . . . . . . . . . . 297. parms_list parameter format for IKE1PHA2 and IKE2PHA2 mechanisms . . . . . . . . . 298. Keywords for derive key. . . . . . . . . . . . . . . . . . . . . . . . . . . 299. parms_list parameter format for PKCS-DH mechanism . . . . . . . . . . . . . . . 300. parms_list parameter format for SSL-MS, SSL-MSDH, TLS-MS, and TLS-MSDH mechanisms 301. parms_list parameter format for EC-DH mechanism . . . . . . . . . . . . . . . . 302. parms_list parameter format for IKESEED, IKESHARE, and IKEREKEY mechanisms . . . . 303. Get attribute value processing for objects possessing sensitive attributes. . . . . . . . . 304. Keywords for generate secret key . . . . . . . . . . . . . . . . . . . . . . . 305. parms_list parameter format for SSL and TLS mechanism . . . . . . . . . . . . . . 306. Keywords for generate HMAC . . . . . . . . . . . . . . . . . . . . . . . . 307. chain_data parameter format . . . . . . . . . . . . . . . . . . . . . . . . . 308. Keywords for verify HMAC . . . . . . . . . . . . . . . . . . . . . . . . . . 309. chain_data parameter format . . . . . . . . . . . . . . . . . . . . . . . . . 310. Keywords for one-way hash generate . . . . . . . . . . . . . . . . . . . . . . 311. chain_data parameter format . . . . . . . . . . . . . . . . . . . . . . . . . 312. Keywords for private key sign. . . . . . . . . . . . . . . . . . . . . . . . . 313. Keywords for public key verify . . . . . . . . . . . . . . . . . . . . . . . . 314. Keywords for derive multiple keys . . . . . . . . . . . . . . . . . . . . . . . 315. parms_list parameter format for TLS-PRF mechanism. . . . . . . . . . . . . . . . 316. Authorization requirements for the set attribute value callable service . . . . . . . . . . 317. Keywords for secret key decrypt. . . . . . . . . . . . . . . . . . . . . . . . 318. initialization_vector parameter format for GCM mechanism . . . . . . . . . . . . . . 319. chain_data parameter format . . . . . . . . . . . . . . . . . . . . . . . . . 320. Keywords for secret key encrypt. . . . . . . . . . . . . . . . . . . . . . . . 321. initialization_vector parameter format for GCM mechanism . . . . . . . . . . . . . . 322. initialization_vector parameter format for GCMIVGEN mechanism . . . . . . . . . . . 323. chain_data parameter format . . . . . . . . . . . . . . . . . . . . . . . . . 324. Authorization requirements for the token record create callable service . . . . . . . . . 325. Authorization requirements for the token record delete callable service . . . . . . . . . 326. Keywords for unwrap key . . . . . . . . . . . . . . . . . . . . . . . . . . 327. Keywords for wrap key . . . . . . . . . . . . . . . . . . . . . . . . . . . 328. Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329. Reason Codes for Return Code 0 (0) . . . . . . . . . . . . . . . . . . . . . . 330. Reason Codes for Return Code 4 (4) . . . . . . . . . . . . . . . . . . . . . . 331. Reason Codes for Return Code 8 (8) . . . . . . . . . . . . . . . . . . . . . . 332. Reason Codes for Return Code C (12) . . . . . . . . . . . . . . . . . . . . . xxviii z/OS V1R13 ICSF Application Programmer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 619 619 620 623 626 629 631 635 637 640 642 645 647 650 652 657 659 660 660 660 664 666 666 666 667 670 674 675 677 678 680 681 684 685 688 691 693 694 696 698 699 700 703 704 705 705 709 712 718 721 725 726 727 730 766 | | | | | 333. Reason Codes for Return Code 10 (16) . . . . . . . . . . . . . . . . . . . . . 334. Internal Key Token Format . . . . . . . . . . . . . . . . . . . . . . . . . . 335. Internal Key Token Format . . . . . . . . . . . . . . . . . . . . . . . . . . 336. Format of External Key Tokens . . . . . . . . . . . . . . . . . . . . . . . . 337. External RKX DES key-token format, version X'10' . . . . . . . . . . . . . . . . . 338. Format of Null Key Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . 339. Variable-length Symmetric Key Token . . . . . . . . . . . . . . . . . . . . . . 340. HMAC Algorithm Key-usage fields . . . . . . . . . . . . . . . . . . . . . . . 341. AES Algorithm KEK Key-usage fields . . . . . . . . . . . . . . . . . . . . . . 342. AES Algorithm Cipher Key Associated Data . . . . . . . . . . . . . . . . . . . 343. Variable-length Symmetric Null Token . . . . . . . . . . . . . . . . . . . . . . 344. Format of PKA Null Key Tokens . . . . . . . . . . . . . . . . . . . . . . . . 345. RSA Public Key Token . . . . . . . . . . . . . . . . . . . . . . . . . . . 346. RSA Private External Key Token Basic Record Format . . . . . . . . . . . . . . . 347. RSA Private Key Token, 1024-bit Modulus-Exponent External Format . . . . . . . . . . 348. RSA Private Key Token, 4096-bit Modulus-Exponent External Format . . . . . . . . . . 349. RSA Private Key Token, 4096-bit Chinese Remainder Theorem External Format . . . . . . 350. RSA Private Internal Key Token Basic Record Format . . . . . . . . . . . . . . . . 351. RSA Private Internal Key Token, 1024-bit ME Form for Cryptographic Coprocessor Feature 352. RSA Private Internal Key Token, 1024-bit ME Form for PCICC, PCIXCC, CEX2C, or CEX3C 353. RSA Private Internal Key Token, 4096-bit Chinese Remainder Theorem Internal Format . . . 354. DSS Public Key Token . . . . . . . . . . . . . . . . . . . . . . . . . . . 355. DSS Private External Key Token . . . . . . . . . . . . . . . . . . . . . . . 356. DSS Private Internal Key Token . . . . . . . . . . . . . . . . . . . . . . . . 357. ECC Key Token Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 358. Associated Data Format for ECC Private Key Token . . . . . . . . . . . . . . . . 359. AESKW Wrapped Payload Format for ECC Private Key Token . . . . . . . . . . . . 360. Trusted block header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361. Trusted block trusted RSA public-key section (X'11') . . . . . . . . . . . . . . . . 362. Trusted block rule section (X'12') . . . . . . . . . . . . . . . . . . . . . . . 363. Summary of trusted block rule subsection . . . . . . . . . . . . . . . . . . . . 364. Transport key variant subsection (X'0001' of trusted block rule section (X'12') . . . . . . . 365. Transport key rule reference subsection (X'0002') of trusted block rule section (X'12') . . . . 366. Common export key parameters subsection (X'0003') of trusted block rule section (X'12') 367. Source key rule reference subsection (X'0004' of trusted block rule section (X'12') . . . . . 368. Export key CCA token parameters subsection (X'0005') of trusted block rule section (X'12') 369. Trusted block key label (name) section X'13' . . . . . . . . . . . . . . . . . . . 370. Trusted block information section X'14' . . . . . . . . . . . . . . . . . . . . . 371. Summary of trusted block information subsections . . . . . . . . . . . . . . . . . 372. Protection information subsection (X'0001') of trusted block information section (X'14') . . . . 373. Activation and expiration dates subsection (X'0002') of trusted block information section (X'14') 374. Trusted block application-defined data section X'15' . . . . . . . . . . . . . . . . 375. Default Control Vector Values. . . . . . . . . . . . . . . . . . . . . . . . . 376. PKA96 Clear DES Key Record . . . . . . . . . . . . . . . . . . . . . . . . 377. EBCDIC to ASCII Default Conversion Table . . . . . . . . . . . . . . . . . . . 378. ASCII to EBCDIC Default Conversion Table . . . . . . . . . . . . . . . . . . . 379. Callable service access control points. . . . . . . . . . . . . . . . . . . . . . Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776 777 778 780 781 782 783 788 789 792 792 793 793 794 795 796 797 798 799 800 801 803 804 805 807 810 811 814 815 816 817 818 818 819 821 821 823 823 824 824 825 826 827 881 891 892 898 xxix xxx z/OS V1R13 ICSF Application Programmer's Guide About this information This information supports z/OS (5694-A01). It describes how to use the callable services provided by the Integrated Cryptographic Service Facility (ICSF). The z/OS Cryptographic Services includes these components: v v v v z/OS z/OS z/OS z/OS Integrated Cryptographic Service Facility (ICSF) Open Cryptographic Services Facility (OCSF) System Secure Socket Level Programming (SSL) Public Key Infrastructure Services (PKI) ICSF is a software element of z/OS that works with the hardware cryptographic feature and the Security Server RACF to provide secure, high-speed cryptographic services. ICSF provides the application programming interfaces by which applications request the cryptographic services. | | | | | | Note: References to the IBM Eserver zSeries 800 (z800) do not appear in this information. Be aware that the documented notes and restrictions for the IBM Eserver zSeries 900 (z900) also apply to the z800. References to the IBM zEnterprise 114 (z114) do not appear in this information. Be aware that the documented notes and restrictions for the IBM zEnterprise 196 (z196) also apply to the z114. Who should use this information This information is intended for application programmers who: v Are responsible for writing application programs that use the security application programming interface (API) to access cryptographic functions. v Want to use ICSF callable services in high-level languages such as C, COBOL, FORTRAN, and PL/I, as well as in assembler. How to use this information ICSF includes Advanced Encryption Standard (AES), Data Encryption Standard (DES) and public key cryptography. These are very different cryptographic systems. These topics focus on IBM CCA programming and include: v Chapter 1, “Introducing Programming for the IBM CCA” describes the programming considerations for using the ICSF callable services. It also explains the syntax and parameter definitions used in callable services. v Chapter 2, “Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services” gives an overview of AES and DES cryptography and provides general guidance information on how the callable services use different key types and key forms. It also discusses how to write your own callable services called installation-defined callable services and provides suggestions on what to do if there is a problem. v Chapter 3, “Introducing PKA Cryptography and Using PKA Callable Services” introduces Public Key Algorithm (PKA) support and describes programming considerations for using the ICSF PKA callable services, such as the PKA key token structure and key management. v Chapter 4, “Introducing PKCS #11 and using PKCS #11 callable services” gives an overview of PKCS #11 support and management services. © Copyright IBM Corp. 1997, 2011 xxxi These topics focus on CCA callable services and include: v Chapter 5, “Managing Symmetric Cryptographic Keys” describes the callable services for generating and maintaining cryptographic keys and the random number generate callable service. It also presents utilities to build AES and DES tokens and generate and translate control vectors and describes the PKA callable services that support AES and DES key distribution. v Chapter 6, “Protecting Data” describes the callable services for deciphering ciphertext from one key and enciphering it under another key. It also describes enciphering and deciphering data with encrypted keys and encoding and decoding data with clear keys. v Chapter 7, “Verifying Data Integrity and Authenticating Messages” describes the callable services for generating and verifying message authentication codes (MACs), generating modification detection codes (MDCs) and generating hashes (SHA-1, SHA-2, MD5, RIPEMD-160). v Chapter 8, “Financial Services” describes the callable services for generating, verifying, and translating personal identification numbers (PINs). It also describes the callable services that support the Secure Electronic Transaction (SET) protocol and those that and generate and verify VISA card verification values and American Express card security codes. v Chapter 9, “Using Digital Signatures” describes the PKA callable services that support using digital signatures to authenticate messages. v Chapter 10, “Managing PKA Cryptographic Keys” describes the PKA callable services that generate and manage PKA keys. v Chapter 11, “Key Data Set Management,” on page 565 describes the callable services that manage key tokens in the Cryptographic Key Data Set (CKDS) and the PKA Key Data Set (PKDS). | | | | v Chapter 12, “Utilities” describes callable services that convert data between EBCDIC and ASCII format, convert between binary strings and character strings, and query ICSF services and algorithms. v Chapter 13, “Trusted Key Entry Workstation Interfaces” describes the PCI interface (PCI) and the Public Key Secure Cable (PKSC) interface that supports Trusted Key Entry (TKE), an optional feature available with ICSF. v Chapter 14, “Managing Keys According to the ANSI X9.17 Standard” describes the callable services that support the ANSI X9.17 key management standard 1, which defines a process for protecting and exchanging DES keys. v Chapter 15, “Using PKCS #11 Tokens and Objects” describes the callable services for managing the PKCS #11 tokens and objects in the TKDS. The appendixes include this information: v Appendix A, “ICSF and TSS Return and Reason Codes” explains the return and reason codes returned by the callable services. v Appendix B, “Key Token Formats” describes the formats for AES key tokens, DES internal, external, and null key tokens and for PKA public, private external, and private internal key tokens containing either Rivest-Shamir-Adleman (RSA) or Digital Signature Standard (DSS) information. This appendix also describes the PKA null key token. v Appendix C, “Control Vectors and Changing Control Vectors with the CVT Callable Service,” on page 827 contains a table of the default control vector values that are associated with each key type and describes the control 1. ANSI X9.17-1985: Financial Institution Key Management (Wholesale) xxxii z/OS V1R13 ICSF Application Programmer's Guide information for testing control vectors, mask array preparation, selecting the key-half processing mode, and an example of Control Vector Translate. v Appendix D, “Coding Examples” provides examples for COBOL, assembler, and PL/1. v Appendix E, “Using ICSF with BSAFE” explains how to access ICSF services from applications written using RSA's BSAFE cryptographic toolkit. v Appendix F, “Cryptographic Algorithms and Processes,” on page 863 describes the PIN formats and algorithms, cipher processing and segmenting rules, multiple encipherment and decipherment and their equations, the PKA92 encryption process, partial notarization of an ANSI key-encrypting key (AKEK), and the algorithm for transforming a Commercial Data Masking Facility (CDMF) key. v Appendix G, “EBCDIC and ASCII Default Conversion Tables” presents EBCDIC to ASCII and ASCII to EBCDIC conversion tables. v Appendix H, “Access Control Points and Callable Services” lists which access control points correspond to which callable services. v Appendix I, “Accessibility,” on page 909 contains information on accessibility features in z/OS. v Notices contains notices, programming interface information, and trademarks. Where to find more information The publications in the z/OS ICSF library include: v z/OS Cryptographic Services ICSF Overview v z/OS Cryptographic Services ICSF Administrator's Guide v z/OS Cryptographic Services ICSF System Programmer's Guide v z/OS Cryptographic Services ICSF Application Programmer's Guide v z/OS Cryptographic Services ICSF Messages v z/OS Cryptographic Services ICSF Writing PKCS #11 Applications Other publications referenced in this publication are: v IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface Reference, SC40-1675 Related Publications v z/OS Cryptographic Services ICSF TKE Workstation User's Guide, SA23-2211 v z/OS MVS Programming: Callable Services for High-Level Languages, SA22-7613 v z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU, SA22-7611 v BSAFE User's Manual v BSAFE Library Reference Manual v z/OS Security Server RACF Command Language Reference v z/OS Security Server RACF Security Administrator's Guide v IBM Common Cryptographic Architecture (CCA) Basic Services API, Release 2.53 This publication can be obtained in PDF format from the Library page at http://www.ibm.com/security/cryptocards. v IBM Distributed Key Management System, Installation and Customization Guide, GG24-4406 About this information xxxiii xxxiv z/OS V1R13 ICSF Application Programmer's Guide How to send your comments to IBM We appreciate your input on this publication. Feel free to comment on the clarity, accuracy, and completeness of the information or give us any other feedback that you might have. Use one of the following methods to send us your comments: 1. Send an e-mail to [email protected] 2. Visit the Contact z/OS Web page at http://www.ibm.com/servers/eserver/zseries/ zos/webqs.html 3. Mail the comments to the following address: IBM Corporation Attention: MHVRCFS Reader Comments Department H6MA, Mail Station P181 2455 South Road Poughkeepsie, NY 12601-5400 U.S.A. 4. Fax the comments to us as follows: From the United States and Canada: 1+845+432-9405 From all other countries: Your international access code +1+845+432-9405 Include the following information: v Your name and address v Your e-mail address v Your telephone or fax number v The publication title and order number: z/OS Cryptographic Services Application Programmer's Guide SA22-7522-15 v The topic and page number related to your comment v The text of your comment. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you submit. If you have a technical problem Do not use the feedback methods listed above. Instead, do one of the following: v Contact your IBM service representative v Call IBM technical support v Visit the IBM zSeries support Web page at http://www.ibm.com/servers/eserver/ support/zseries/. © Copyright IBM Corp. 1997, 2011 xxxv xxxvi z/OS V1R13 ICSF Application Programmer's Guide Summary of changes Changes made in z/OS Version 1 Release 13 This document contains information previously presented in z/OS ICSF Application Programmer's Guide, SA22-7522-14, which supports z/OS Version 1 Release 12. This document is for ICSF FMID HCR7790. This release of ICSF runs on z/OS V1R11, z/OS V1R12, and z/OS V1R13 and only on zSeries hardware. New information: v Added support for the TR-31 key block format defined by the American National Standards Institute (ANSI). ICSF enables applications to convert a CCA token to a TR-31 key block for export to another party, and to convert an imported TR-31 key block to a CCA token. This enables you to securely exchange keys and their attributes with non-CCA systems. The following callable services have been added to provide this support: – TR-31 Export (CSNBT31X and CSNET31X) – TR-31 Import (CSNBT31I and CSNET31I) TR-31 – TR-31 Parse (CSNBT31P and CSNET31P) TR-31 – TR-31 Optional Data Read (CSNBT31R and CSNET31R) – TR-31 Optional Data Build (CSNBT31O and CSNET31O) v Added new callable service, CVV key combine (CSNBCKC and CSNECKC). This callable service combines 2 single-length CCA internal key tokens into 1 double-length CCA key token containing a CVVKEY-A key type for use with the VISA CVV Service Generate or VISA CVV Service Verify callable services. This combined double-length key satisfies current VISA requirements and eases translation between TR-31 and CCA formats for CVV keys. See “CVV Key Combine (CSNBCKC and CSNECKC)” on page 448 for more information. v Added support for coordinated and dynamic update of a CKDS. The new callable service Coordinated KDS Administration (CSFCRC and CSFCRC6) which performs a CKDS refresh or reencipher operation while allowing applications to update the CKDS. In a sysplex environment, this callable service enables an application to perform a coordinated sysplex-wide refresh or reencipher operation from a single ICSF instance. v Added new callable service ECC Diffie-Hellman (CSNDEDH and CSNFEDH), which applications can use to create symmetric key material from a pair of ECC keys using the Elliptic Curve Diffie-Hellman protocol and the static unified model key agreement scheme. v A new health check, ICSFMIG_DEPRECATED_SERV_WARNINGS, has been added to the Health Checker to detect the use of services that will not be supported in subsequent releases: The deprecated services checked in this release are listed below. These are not supported on post zSeries 900 hardware, and will not be supported in subsequent releases of ICSF. – ANSI X9.17 EDC Generate – ANSI X9.17 Key Export – ANSI X9.17 Key Import – – – – © Copyright IBM Corp. 1997, 2011 ANSI X9.17 Key Translate ANSI X9.17 Transport Key Partial Notarize Ciphertext Translate Ciphertext Translate with ALET xxxvii – Transform CDMF Key – User Derived Key – PKSC Interface Callable Service You should use the ICSFMIG_DEPRECATED_SERV_WARNINGS check to determine if these services are being used. For more information on this health check, refer to z/OS Cryptographic Services ICSF Administrator's Guide. Changed information: v CKDS Key Record Write2 (CSNBKRW2 and CSNEKRW2) v Clear PIN Generate (CSNBPGN and CSNEPGN) v Clear PIN Generate Alternate (CSNBCPA and CSNECPA) v Control Vector Generate (CSNBCVG and CSNECVG) v Digital Signature Verify (CSNDDSV and CSNFDSV) v Encrypted PIN Generate (CSNBEPG and CSNEEPG) v v v v v Encrypted PIN Verify (CSNBPVR and CSNEPVR) ICSF Query Facility (CSFIQF and CSFIQF6) Key Generate2 (CSNBKGN2 and CSNEKGN2) Key Part Import2 (CSNBKPI2 and CSNEKPI2) Key Test2 (CSNBKYT2 and CSNEKYT2) v Key Token Build (CSNBKTB and CSNEKTB) v Key Token Build2 (CSNBKTB2 and CSNEKTB2) v Key Translate2 (CSNBKTR2 and CSNEKTR2) v v v v PKDS PKDS PKDS PKDS Key Key Key Key Record Record Record Record Create (CSNDKRC and CSNFKRC) Delete (CSNDKRD and CSNFKRD) Read (CSNDKRR and CSNFKRR) Write (CSNDKRW and CSNFKRW) v PKA Decrypt (CSNDPKD and CSNFPKD) v PKA Encrypt (CSNDPKE and CSNFPKE) v PKA Key Generate (CSNDPKG and CSNFPKG) v PKA Key Import (CSNDPKI and CSNFPKI) PKA Key Token Change (CSNDKTC and CSNFKTC) Restrict Key Attribute (CSNBRKA and CSNERKA) Secure Key Import2 (CSNBSKI2 and CSNESKI2) Symmetric Algorithm Decipher (CSNBSAD or CSNBSAD1 and CSNESAD or CSNESAD1) v Symmetric Algorithm Encipher (CSNBSAE or CSNBSAE1 and CSNESAE or CSNESAE1) v Symmetric Key Import2 (CSNDSYI2 and CSNFSYI2) v v v v v v v v v Symmetric Key Generate (CSNDSYG and CSNFSYG) Symmetric Key Import (CSNDSYI and CSNFSYI) Symmetric Key Export (CSNDSYX and CSNFSYX) VISA CVV Service Generate (CSNBCSG and CSNECSG) VISA CVV Service Verify (CSNBCSV and CSNECSV) For clarity: xxxviii z/OS V1R13 ICSF Application Programmer's Guide v CSNBKRC and CSNEKRC, which had been referred to as the "Key Record Create" service, are now referred to as the "CKDS Key Record Create" service v CSNBKRC2 and CSNEKRC2, which had been referred to as the "Key Record Create2" service, are now referred to as the "CKDS Key Record Create2" service v CSNBKRD and CSNEKRD, which had been referred to as the "Key Record Delete" service, are now referred to as the "CKDS Key Record Delete" service v CSNBKRR and CSNEKRR, which had been referred to as the "Key Record Read" service, are now referred to as the "CKDS Key Record Read" service v CSNBKRR2 and CSNEKRR2, which had been referred to as the "Key Record Read2" service, are now referred to as the "CKDS Key Record Read2" service v CSNBKRW and CSNEKRW, which had been referred to as the "Key Record Write" service, are now referred to as the "CKDS Key Record Write" service v CSNBKRW2 and CSNEKRW2, which had been referred to as the "Key Record Write2" service, are now referred to as the "CKDS Key Record Write2" service v CSNDKRC and CSNFKRC, which had been referred to as the "PKDS Record Create" service, are now referred to as the "PKDS Key Record Create" service v CSNDKRD and CSNFKRD, which had been referred to as the "PKDS Record Delete" service, are now referred to as the "PKDS Key Record Delete" service v CSNDKRR and CSNFKRR, which had been referred to as the "PKDS Record Read" service, are now referred to as the "PKDS Key Record Read" service v CSNDKRW and CSNFKRW, which had been referred to as the "PKDS Record Write" service, are now referred to as the "PKDS Key Record Write" service | | | References to the IBM Eserver zSeries 800 (z800) do not appear in this information. Be aware that the documented notes and restrictions for the IBM Eserver zSeries 900 (z900) also apply to the z800. Changes made in z/OS Version 1 Release 12 This document contains information previously presented in z/OS ICSF Application Programmer's Guide, SA22-7522-13, which supports z/OS Version 1 Release 11. This document is for ICSF FMID HCR7780. This release of ICSF runs on z/OS V1R10, z/OS V1R11, and z/OS V1R12 and only on zSeries hardware. New information: v All ICSF callable services now support invocation in AMODE(64). Previously, only certain callable services had this support. Applications that are written for AMODE(64) operation must be linked with the ICSF 64-bit service stubs. v Added information for HMAC key support. This support is to be enabled with the PTF for APAR OA33260, planned for February 2011 availability. – Added the following services to support CCA key management of HMAC keys: - Key Generate2 (CSNBKGN2 and CSNEKGN2) - Key Part Import2 (CSNBKPI2 and CSNEKPI2) - Key Test2 (CSNBKYT2 and CSNEKYT2) - Key Token Build2 (CSNBKTB2 and CSNEKTB2) - Restrict Key Attribute (CSNBRKA and CSNERKA) - Secure Key Import2 (CSNBSKI2 and CSNESKI2) - Symmetric Key Import2 (CSNDSYI2 and CSNFSYI2) Summary of changes xxxix – The following services for Dynamic CKDS update were added for use with HMAC tokens. These services must be used with HMAC tokens, but also support existing DES and AES tokens. - Key Record Create2 (CSNBKRC2 and CSNEKRC2) - Key Record Read2 (CSNBKRR2 and CSNEKRR2) - Key Record Write2 (CSNBKRW2 and CSNEKRW2) – Added the following services to support the generation and verification of MACs using keyed-HMAC algorithm: - HMAC Generate (CSNBHMG or CSNBHMG1 and CSNEHMG or CSNEHMG1) - HMAC Verify (CSNBHMV or CSNBHMV1 and CSNEHMV or CSNEHMV1) v Added the following modes of operation for protecting data to the Symmetric Key Encipher and Symmetric Key Decipher callable services: – Cipher Block Chaining with Ciphertext Stealing (CBC-CS) Mode – Cipher Feedback (CFB) Mode – Output Feedback (OFB) Mode – Galois/Counter Mode (GCM) v Added an enhanced method of key wrapping that is ANSI X9.24 compliant. See “Key Wrapping” on page 19 for more information. v Added Elliptic Curve Cryptography (ECC) support to the following callable services: – Digital Signature Generate (CSNDDSG and CSNFDSG) – – – – Digital Signature Verify (CSNDDSV and CSNFDSV) PKA Key Generate (CSNDPKG and CSNFPKG) PKA Key Import (CSNDPKI and CSNFPKI) PKA Key Token Build (CSNDPKB and CSNFPKB) – – – – PKA Key Token Change (CSNDKTC and CSNFKTC) PKA Public Key Extract (CSNDPKX and CSNFPKX) PKDS Record Create (CSNDKRC and CSNFKRC) PKDS Record Delete (CSNDKRD and CSNFKRD) – PKDS Record Read (CSNDKRR and CSNFKRR) – PKDS Record Write (CSNDKRW and CSNFKRW) Changed information v ANSI X9.17 EDC Generate - CSNGEGN v ANSI X9.17 Key Export - CSNGKEX v ANSI X9.17 Key Import - CSNGKIM xl v v v v v ANSI X9.17 Key Translate - CSNGKTR ANSI X9.17 Transport Key Partial Notarize - CSNGTKN Ciphertext Translate - CSNECTT and CSNECTT1 Clear PIN Encrypt - CSNECPE Clear PIN Generate - CSNEPGN v v v v v Clear PIN Generate Alternate - CSNECPA Control Vector Generate - CSNECVG Control Vector Translate - CSNECVT Cryptographic Veriable Enciper - CSNECVE Data Key Export - CSNEDKX z/OS V1R13 ICSF Application Programmer's Guide v v v v v Data Key Import - CSNEDKM Decipher - CSNEDEC and CSNEDEC1 Decode - CSNEDCO Diversified Key Generate - CSNEDKG Encipher - CSNEENC and CSNEENC1 v v v v v v v Encode - CSNEECO Encrypted PIN Generate - CSNEEPG Encrypted PIN Translate - CSNEPTR Encrypted PIN Verify - CSNEPVR HMAC Generate - CSNEHMG and CSFEHMG1 HMAC Verify - CSNEHMV and CSFEHMV1 Key Export - CSNEKEX v v v v v v Key Key Key Key Key Key Generate2 - CSNEKGN2 Import - CSNEKIM Part Import - CSNEKPI Part Import2 - CSNEKPI2 Record Create - CSNEKRC Record Create2 - CSNEKRC2 v Key Record Delete - CSNEKRD v Key Record Read - CSNEKRR v Key Record Read2 - CSNEKRR2 v v v v Key Key Key Key Record Write - CSNEKRW Record Write2 - CSNEKRW2 Test - CSNEKYT Test2 - CSNEKYT2 v Key Test Extended - CSNEKYTX v Key Token Build - CSNEKTB v Key Token Build2 - CSNEKTB2 v v v v v Key Translate - CSNEKTR MAC Generate - CSNEMGN and CSNEMGN1 MAC Verify - CSNEMVR and CSNEMVR1 MDC Generate - CSNEMDG and CSNEMDG1 Multiple Secure Key Import - CSNESKM v PCI Interface - CSFPCI and CSFPCI6 v PIN Change/Unblock - CSNEPCU v v v v v v v PKA Key Token Change - CSNDKTC PKDS Record Read - CSNFKRR PKDS Record Write - CSNFKRW Prohibit Export - CSNEPEX Prohibit Export Extended - CSNEPEXX Remote Key Export - CSNFRKX Restrict Key Attribute - CSNBRKA and CSNERKA v Secure Key Import - CSNESKI v Secure Key Import2 - CSNESKI2 v Secure Messaging for Keys - CSNESKY Summary of changes xli v v v v v Secure Messaging for PINS - CSNESPN SET Block Compose - CSNFSBC SET Block Decompose - CSNFSBD Symmetric Key Generate - CSNFSYG Transaction Validation - CSNETRV v v v v v v v Transform CDMF Key - CSNETCK Trusted Block Create - CSNFTBC User Derived Key - CSFUDK6 VISA CVV Service Generate - CSNECSG VISA CVV Service Verify - CSNECSV PKCS #11 Secret Key Encrypt (CSFPSKE) PKCS #11 One-way hash, sign, or verify (CSFPOWH). This was previously referred to as PKCS #11 One-way hash generate (CSFPOWH). Changes made in z/OS Version 1 Release 11 This document contains information previously presented in z/OS ICSF Application Programmer's Guide, SA22-7522-12, which supports z/OS Version 1 Release 10. This document is for ICSF FMID HCR7770. This release of ICSF runs on z/OS V1R9 and z/OS V1R10 and only on zSeries hardware. New information: v Added new callable service PKA Key Translate (CSNDPKT and CSNFPKT). Using this callable service, applications can translate a source CCA RSA key token into a target external smart card key token. v Added new callable services for managing PKCS #11 tokens and objects. These additional services are: – – – – – – – – PKCS PKCS PKCS PKCS PKCS PKCS PKCS PKCS #11 #11 #11 #11 #11 #11 #11 #11 Derive key (CSFPDVK) Derive multiple keys (CSFPDMK) Generate HMAC (CSFPHMG) Generate key pair (CSFPGKP) Generate secret key (CSFPGSK) One-way hash generate (CSFPOWH) Private key sign (CSFPPKS) Pseudo-random function (CSFPPRF) – PKCS #11 Public key verify (CSFPPKV) – PKCS #11 Secret key decrypt (CSFPSKD) – PKCS #11 Secret key encrypt (CSFPSKE) – PKCS #11 Unwrap key (CSFPUWK) – PKCS #11 Verify HMAC (CSFPHMV) – PKCS #11 Wrap key (CSFPWPK) v Added information for the Crypto Express3 Coprocessor. Changed information: v The Symmetric Key Export and Symmetric Key Import callable services now support invocation in AMODE(64). xlii z/OS V1R13 ICSF Application Programmer's Guide The Symmetric Key Encipher and Symmetric Key Decipher callable services now support an encrypted key in the CKDS. This enables applications to leverage the performance capabilities of CPACF when enciphering/deciphering data using encrypted symmetric keys. v The ICSF Query Algorithm (CSFIQA and CSFIQA6) utility and ICSF Query Facility (CSFIQF and CSFIQF6) updated to return additional data. This document contains terminology, maintenance, and editorial changes. Technical changes or additions to the text and illustrations are indicated by a vertical line to the left of the change. Summary of changes xliii xliv z/OS V1R13 ICSF Application Programmer's Guide Part 1. IBM CCA Programming IBM CCA Programming introduces programming for the IBM CCA, AES cryptography, DES cryptography and PKA cryptography. It explains how to use DES, AES and PKA callable services. | | | | | | Note: References to the IBM Eserver zSeries 800 (z800) do not appear in this information. Be aware that the documented notes and restrictions for the IBM Eserver zSeries 900 (z900) also apply to the z800. References to the IBM zEnterprise 114 (z114) do not appear in this information. Be aware that the documented notes and restrictions for the IBM zEnterprise 196 (z196) also apply to the z114. © Copyright IBM Corp. 1997, 2011 1 2 z/OS V1R13 ICSF Application Programmer's Guide Chapter 1. Introducing Programming for the IBM CCA ICSF provides access to cryptographic functions through callable services, which are also known as verbs. A callable service is a routine that receives control using a CALL statement in an application language. Prior to invoking callable services in an application program, you must link them into the application program. See “Linking a Program with the ICSF Callable Services” on page 12. To invoke the callable service, the application program must include a procedure call statement that has the entry point name and parameters for the callable service. The parameters that are associated with a callable service provide the only communication between the application program and ICSF. ICSF Callable Services Naming Conventions The ICSF callable services generally follow the naming conventions outlined in the following table. There are five exceptions where the CSFzzz names would collide and in those cases, the CSFzzz alias is CSFPzzz instead: PKDS Key Record Create (CSFPKRC), PKDS Key Record Delete (CSFPKRD), PKDS Key Record Read (CSFPKRR), PKDS Key Record Write (CSFPKRW), PKA Key Token Change (CSFPKTC), | | | In the following table, zzz is a 3- or 4-letter service name, such as ENC for the Encipher service or PKG for the PKA Key Generate service. Not all CSNBzzz/CSNEzzz services have ALET-qualified entry points (where certain parameters can be in a dataspace or an address space other than the caller's). See each specific service for details. Table 1. ICSF Callable Services Naming Conventions This callable service prefix: Identifies: CSNBzzz / CSFzzz 31-bit CSNBzzz1 / CSFzzz1 31-bit ALET-qualified CSNEzzz / CSFzzz6 64-bit CSNEzzz1 / CSFzzz16 64-bit ALET-qualified CSNDzzz / CSFzzz 31-bit CSNFzzz / CSFzzz6 64-bit CSNAzzz / CSFAzzz 31-bit CSNGzzz / CSFAzzz6 64-bit CSFPzzz 31-bit CSFPzzz6 64-bit CSFzzz 31-bit CSFzzz6 64-bit Symmetric Key Services and Hashing Services Asymmetric Key Services ANSI X9.17 Services PKCS #11 Services Utility Services and TKE Workstation Interfaces Callable Service Syntax This publication uses a general call format to show the name of the ICSF callable service and its parameters. An example of that format is shown here: © Copyright IBM Corp. 1997, 2011 3 CALL CSNBxxx (return_code, reason_code, exit_data_length, exit_data, parameter_5, parameter_6, . . . parameter_N) where CSNBxxx is the name of the callable service. The return code, reason code, exit data length, exit data, parameter 5 through parameter N represent the parameter list. The call generates a fixed length parameter list. You must supply the parameters in the order shown in the syntax diagrams. “Parameter Definitions” on page 6 describes the parameters in more detail. ICSF callable services can be called from application programs written in a number of high-level languages as well as assembler. The high-level languages are: v C v COBOL v FORTRAN v PL/I The ICSF callable services comply with the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The services can be invoked using the generic format, CSNBxxx. Use the generic format if you want your application to work with more than one cryptographic product. The format CSFxxxx can be used in place of CSNBxxx. Otherwise, use the CSFxxxx format. Specific formats for the languages that can invoke ICSF callable services are as follows: C CSNBxxxx (return_code,reason_code,exit_data_length,exit_data, parameter_5,...parameter_N) COBOL CALL 'CSNBxxxx' USING return_code,reason_code,exit_data_length, exit_data,parameter_5,...parameter_N FORTRAN CALL CSNBxxxx (return_code,reason_code,exit_data_length,exit_data, parameter_5,...parameter_N) PL/I DCL CSNBxxxx ENTRY OPTIONS(ASM); CALL CSNBxxxx return_code,reason_code,exit_data_length,exit_data, parameter_5,...parameter_N; Assembler language programs must use standard linkage conventions when invoking ICSF callable services. An example of how an assembler language program can invoke a callable service is shown as follows: CALL CSNBxxxx,(return_code,reason_code,exit_data_length,exit_data, parameter_5,...parameter_N) Coding examples using the high-level languages are shown in Appendix D, “Coding Examples.” Callable Services with ALET Parameters Some callable services have an alternate entry point (with ALET parameters—for data that resides in data spaces). They are in the format of CSNBxxx1 as shown in 4 z/OS V1R13 ICSF Application Programmer's Guide the following table. For the associated 64-bit versions of the callable services (CSNExxx), the ALET-qualified versions are in the format CSNExxx1. Verb Callable Service without ALET Callable Service with ALET Ciphertext translate CSNBCTT CSNBCTT1 Decipher CSNBDEC CSNBDEC1 Encipher CSNBENC CSNBENC1 HMAC Generate CSNBHMG CSNBHMG1 HMAC Verify CSNBHMV CSNBHMV1 MAC generate CSNBMGN CSNBMGN1 MAC verify CSNBMVR CSNBMVR1 MDC generate CSNBMDG CSNBMDG1 One way hash generate CSNBOWH CSNBOWH1 Symmetric algorithm decipher CSNBSAD CSNBSAD1 Symmetric algorithm encipher CSNBSAE CSNBSAE1 Symmetric key decipher CSNBSYD CSNBSYD1 Symmetric key encipher CSNBSYE CSNBSYE1 Symmetric MAC generate CSNBSMG CSNBSMG1 Symmetric MAC verify CSNBSMV CSNBSMV1 When choosing which service to use, consider the fact that: v Callable services that do not have an ALET parameter require data to reside in the caller's primary address space. A program using these services adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. v Callable services that have an ALET parameter allow data to reside either in the caller's primary address space or in a data space. This can allow you to encipher more data with one call. However, a program using these services does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to running with other cryptographic products that follow this programming interface. Rules for Defining Parameters and Attributes These rules apply to the callable services: v Parameters are required and positional. v Each parameter list has a fixed number of parameters. v Each parameter is defined as an integer or a character string. Null pointers are not acceptable for any parameter. v Keywords passed to the callable services, such as TOKEN, CUSP, and FIRST can be in lower, upper, or mixed case. The callable services fold them to uppercase prior to using them. Each callable service defines its own list of parameters. The entire list must be supplied on every call. If you do not use a specific parameter, you must supply that parameter with hexadecimal zeros or binary zeros. Chapter 1. Introducing Programming for the IBM CCA 5 Parameters are passed to the callable service. All information that is exchanged between the application program and the callable service is through parameters passed on the call. Each parameter definition begins with the direction that the data flows and the attributes that the parameter must possess (called “type”). This describes the direction. Direction Meaning Input The application sends (supplies) the parameter to the callable service. The callable service does not change the value of the parameter. Output The callable service returns the parameter to the application program. The callable service may have changed the value of the parameter on return. Input/Output The application sends (supplies) the parameter to the callable service. The callable service may have changed the value of the parameter on return. This describes the attributes or type. Type Meaning Integer (I) A 4-byte (32-bit), twos complement, binary number that has sign significance. String A series of bytes where the sequence of the bytes must be maintained. Each byte can take on any bit configuration. The string consists only of data bytes. No string terminators, field-length values, or type-casting parameters are included. The maximum size of a string is X'7FFFFFFF' or 2 gigabytes. In some of the callable services, the length of some string data has an upper bound defined by the installation. The upper bound of a string can also be defined by the service. Alphanumeric character string A string of bytes in which each byte represents characters from this set: Character A-Z a-z 0-9 Blank * < > EBCDIC Value Character EBCDIC Value Character X'40' X'5C' X'4C' X'6E' ( ) + & . ; - X'4D' X'5D' X'4E' X'50' X'4B' X'5E' X'60' / , % ? : = ’ EBCDIC Value X'61' X'6B' X'6C' X'6F' X'7A' X'7E' X'7D' Parameter Definitions This topic describes these parameters, which are used by most of the callable services: v Return_code v Reason_code v Exit_data_length v Exit_data v Key_identifier 6 z/OS V1R13 ICSF Application Programmer's Guide Note: The return_code parameter, the reason_code parameter, the exit_data_length parameter, and the exit_data parameter are required with every callable service. Return and Reason Codes Return_code and reason_code parameters return integer values upon completion of the call. Return_code The return code parameter contains the general results of processing as an integer. Table 2 shows the standard return code values that the callable services return. A complete list of return codes is shown in Appendix A, “ICSF and TSS Return and Reason Codes.” Table 2. Standard Return Code Values From ICSF Callable Services Value Hex (Decimal) Meaning 00 (00) Successful. Normal return. 04 (04) A warning. Execution was completed with a minor, unusual event encountered. 08 (08) An application error occurred. The callable service was stopped due to an error in the parameters. Or, another condition was encountered that needs to be investigated. 0C (12) Error. ICSF is not active or an environment error was detected. 10 (16) System error. The callable service was stopped due to a processing error within the software or hardware. Generally, PCF macros will receive identical error return codes if they execute on PCF or on ICSF. A single exception has been noted: if a key is installed on the ICSF CKDS with the correct label but with the wrong key type, PCF issues a return code of 8, indicating that the key type was incorrect. ICSF issues a return code of 12, indicating that the key could not be found. Reason_code The reason code parameter contains the results of processing as an integer. You can specify which set of reason codes (ICSF or TSS) are returned from callable services. The default value is ICSF. For more information about the REASONCODES installation option, see z/OS Cryptographic Services ICSF System Programmer's Guide. Different results are assigned to unique reason code values under a return code. A list of reason codes is shown in Appendix A, “ICSF and TSS Return and Reason Codes.” Exit Data Length and Exit Data The exit_data_length and exit_data parameters are described here. The parameters are input to all callable services. Although all services require these parameters, several services ignore them. Exit_data_length The integer that has the string length of the data passed to the exit. The data is identified in the exit_data parameter. Exit_data The installation exit data string that is passed to the callable service's preprocessing exit. The installation exit can use the data for its own processing. Chapter 1. Introducing Programming for the IBM CCA 7 ICSF provides two installation exits for each callable service. The preprocessing exit is invoked when an application program calls a callable service, but prior to when the callable service starts processing. For example, this exit is used to check or change parameters passed on the call or to stop the call. It can also be used to perform additional security checks. The post-processing exit is invoked when the callable service has completed processing, but prior to when the callable service returns control to the application program. For example, this exit can be used to check and change return codes from the callable service or perform clean-up processing. For more information about the exits, see z/OS Cryptographic Services ICSF System Programmer's Guide. Key Identifier for Key Token A key identifier for a key token is an area that contains one of these: v Key label identifies keys that are in the CKDS or PKDS. Ask your ICSF administrator for the key labels that you can use. v Key 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 key generate callable service), or received from another system that can produce external key tokens. An internal key token can be used only on ICSF because the master 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. A null key token can be used to import a key from a system that cannot produce external key tokens. A null key token contains a key encrypted under an importer key-encrypting key but does not contain the other information present in an external key token. The term key identifier is used to indicate that different inputs are possible for a parameter. One or more of the previously described items may be accepted by the callable service. Key Label: If the first byte of the key identifier is greater than X'40', the field is considered to be holding a key label. The contents of a key label are interpreted as a pointer to a CKDS or PKDS key entry. The key label is an indirect reference to an internal key token. A key label is specified on callable services with the key_identifier parameter as a 64-byte character string, left-justified, and padded on the right with blanks. In most cases, the callable service does not check the syntax of the key label beyond the first byte. One exception is the CKDS key record create callable service which enforces the KGUP rules for key labels unless syntax checking is bypassed by a preprocessing exit. | A key label has this form: Offset 00-63 Length 64 Data Key label name There are some general rules for creating labels for CKDS key records. 8 z/OS V1R13 ICSF Application Programmer's Guide v Each label can consist of up to 64 characters. The first character must be alphabetic or a national character (#, $, @). The remaining characters can be alphanumeric, a national character (#, $, @), or a period (.). | | v All alphabetic characters must be upper case (A-Z). All labels in the key data sets are created with upper case characters. v Labels must be unique for DATA, DATAXLAT, MAC, MACVER, DATAM, and DATAMV keys. v For compatibility with Version 1 Release 1 function, transport and PIN keys can have duplicate labels for different key types. Keys that use the dynamic CKDS update services to create or update, however, must have unique key labels. v Labels must be unique for any key record, including transport and PIN keys, created or updated using the dynamic CKDS update services. Invocation Requirements | | | | Applications that use ICSF callable services must meet these invocation requirements: v All output parameters must be in storage that the caller is allowed to modify in their execution key. v All input parameters must be in storage that the caller is allowed to read in their execution key. v Data can be located higher or lower than 16Mb but must be 31-bit addressable. Data can be located above 2Gb if the service is invoked in AMODE(64) v Problem or supervisor state v Any PSW key v Task mode or Service Request Block (SRB) mode v No mode restrictions v Enabled for interrupts v No locks held The exceptions to this list are documented with the individual callable services. All ICSF callable services support invocation in AMODE(64). Applications which are written for AMODE(64) operation must be linked with the ICSF 64-bit service stubs, and must invoke the service with the appropriate service name. (Refer to the description of the individual callable service to determine the service name to be used.) Security Considerations Your installation can use the Security Server RACF or an equivalent product to control who can use ICSF callable services or key labels. Prior to using an ICSF callable service or a key label, ask your security administrator to ensure that you have the necessary authorization. For more information, see z/OS Security Server RACF Security Administrator's Guide. HCR7751 and later supports a key store policy using the RACF XFACILIT class. See z/OS Security Server RACF Security Administrator's Guide. RACF does not control all services. The usage notes topic in the callable service description will highlight those services which are not controlled. Chapter 1. Introducing Programming for the IBM CCA 9 Performance Considerations In most cases, the z/OS operating system dispatcher provides optimum performance. However, if your application makes extensive use of ICSF functions, you should consider using one or both of these: v CCF Systems Only: If your application runs in SRB mode, use the SCHEDULE macro or IEAAFFN callable service. You should consider scheduling an SRB to run on a processor with the cryptographic feature installed (using the FEATURE=CRYPTO keyword on the SCHEDULE macro). For more information on the SCHEDULE macro, refer to z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU. Restriction: The FEATURE=CRYPTO keyword should not be specified when running on an IBM Eserver zSeries 990. v Use the IEAAFFN callable service (processor affinity) to avoid system overhead in selecting which processor your program (specifically, a particular TCB in the application) runs in. Note that you do not have to use the IEAAFFN service to ensure that the system runs a program on a processor with a cryptographic feature; the system ensures that automatically. However, you can avoid some of the system overhead involved in the selection process by using the IEAAFFN service, thus improving the program's performance. For more information on using the IEAAFFN callable service, refer to z/OS MVS Programming: Callable Services for High-Level Languages. IBM recommends that you run applications first without using these options. Consider these options when you are tuning your application for performance. Use these options only if they improve the performance of your application. Special Secure Mode Special secure mode is a special processing mode in which: v The Secure Key Import, Secure Key Import2, and Multiple Secure Key Import callable services, which work with clear keys, can be used. v The Clear PIN Generate callable service, which works with clear PINs, can be used. | v The Symmetric Key Generate callable service with the "IM" keyword (the DES enciphered key is enciphered by an IMPORTER key) can be used (CCF Systems Only). v The key generator utility program (KGUP) can be used to enter clear keys into the CKDS. To use special secure mode, several conditions must be met. v The installation options data set must specify YES for the SSM installation option. For information about specifying installation options, see z/OS Cryptographic Services ICSF System Programmer's Guide. This is required for all systems. v The environmental control mask (ECM) must be configured to permit special secure mode. The ECM is a 32-bit mask defined for each cryptographic domain during hardware installation. The second bit in this mask must have been turned on to enable special secure mode. The default is to have this bit turned on in the ECM. The bit can only be turned off/on through the optional TKE Workstation. This is required for systems with the Cryptographic Coprocessor Feature. 10 z/OS V1R13 ICSF Application Programmer's Guide v If you are running in LPAR mode, special secure mode must be enabled. On the IBM Eserver zSeries 900, you enable special secure mode during activation using the Crypto page of the Customize Activation Profiles task. When activated, you can enable or disable special secure mode on the Change LPAR Crypto task. Both of these tasks can be accessed from the Hardware Management Console. This is required for systems with the Cryptographic Coprocessor Feature. For the IBM Eserver zSeries 900 with TKE, TKE can disable/enable special secure mode. Using the Callable Services This topic discusses how ICSF callable services use the different key types and key forms. It also provides suggestions on what to do if there is a problem. ICSF provides callable services that perform cryptographic functions. You call and pass parameters to a callable service from an application program. Besides the callable services ICSF provides, you can write your own callable services called installation-defined callable services. Note that only an experienced system programmer should attempt to write an installation-defined callable service. To write an installation-defined callable service, you must first write the callable service and link-edit it into a load module. Then define the service in the installation options data set. You must also write a service stub. To execute an installation-defined callable service, you call a service stub from your application program. In the service stub, you specify the service number that identifies the callable service. For more information about installation-defined callable services, see z/OS Cryptographic Services ICSF System Programmer's Guide. When the Call Succeeds If the return code is 0, ICSF has successfully completed the call. If a reason code other than 0 is included, refer to Appendix A, “ICSF and TSS Return and Reason Codes,” on page 725, for additional information. For instance, reason code 10000 indicates the key in the key identifier (or more than one key identifier, for services that use two internal key identifiers) has been reenciphered from encipherment under the old master key to encipherment under the current master key. Keys in external tokens are not affected by this processing because they contain keys enciphered under keys other than the host master key. If you manage your key identifiers on disk, then reason code 10000 should be a “trigger” to store these updated key identifiers back on disk. Your program can now continue providing its function, but you may want to communicate the key that you used to another enterprise. This process is exporting a key. If you want to communicate the key that you are using to a cryptographic partner, there are several methods to use: v For DATA keys only, call the data key export callable service. You now have a DATA key type in exportable form. Chapter 1. Introducing Programming for the IBM CCA 11 v Call the key export callable service. You now have the key type in exportable form. v When you use the key generate callable service to create your operational or importable key form, you can create an exportable form, at the same time, and you now have the key type, in exportable form, at the same time as you get the operational or importable form. When the Call Does Not Succeed Now you have planned your use of the ICSF callable services, made the call, but the service has completed with a return and reason codes other than zero. If the return code is 4, there was a minor problem. For example, reason code 8004 indicates the trial MAC that was supplied does not match the message text provided. If the return code is 8, there was a problem with one of your parameters. Check the meaning of the reason code value, correct the parameter, and call the service again. You may go through this process several times prior to succeeding. If the return code is 12, ICSF is not active, or has no access to cryptographic units, or has an environmental problem. Check with your ICSF administrator. If the return code is 16, the service has a serious problem that needs the help of your system programmer. There are several reason codes that can occur when you have already fully debugged and tested your program. For example: v Reason code 10004 indicates that you provided a key identifier that holds a key enciphered under a host master key. The host master key is not installed in the cryptographic unit. If this happens, you have to go back and import your importable key form again and call the service again. You need to build this flow into your program logic. v Reason code 10012 indicates a key corresponding to the label that you specified is not in the CKDS or PKDS. Check with your ICSF administrator to see if the label is correct. v Reason code 3063 indicates RACF failed your request to use a token. v Reason code 16000 indicates RACF failed your request to use a service. v Reason code 16004 indicates RACF failed your request to use the key label. Examine your CSFKEYS profiles and key store policies for possible errors. Return and reason codes are described in Appendix A, “ICSF and TSS Return and Reason Codes,” on page 725. Linking a Program with the ICSF Callable Services To link the ICSF callable services into an application program, you can use these sample JCL statements.In the SYSLIB concatenation, include the CSF.SCSFMOD0 module in the link edit step. This provides the application program access to all ICSF callable services (those that can be invoked in AMODE(24)/AMODE(31) as well as those that can be invoked in AMODE(64)). //LKEDENC JOB //*-----------------------------------------------------------------* //* * //* The JCL links the ICSF encipher callable service, CSNBENC, * 12 z/OS V1R13 ICSF Application Programmer's Guide //* into an application called ENCIPHER. * //* * //*-----------------------------------------------------------------* //LINK EXEC PGM=IEWL, // PARM=’XREF,LIST,LET’ //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,10)) //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=CSF.SCSFMOD0,DISP=SHR * SERVICES ARE IN HERE //SYSLMOD DD DSN=MYAPPL.LOAD,DISP=SHR * MY APPLICATION LIBRARY //SYSLIN DD DSN=MYAPPL.ENCIPHER.OBJ,DISP=SHR * MY ENCIPHER PROGRAM // DD * ENTRY ENCIPHER NAME ENCIPHER(R) /* Chapter 1. Introducing Programming for the IBM CCA 13 14 z/OS V1R13 ICSF Application Programmer's Guide Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services The Integrated Cryptographic Service Facility protects data from unauthorized disclosure or modification. ICSF protects data stored within a system, stored in a file off a system on magnetic tape, and sent between systems. ICSF also authenticates the identity of customers in the financial industry and authenticates messages from originator to receiver. It uses cryptography to accomplish these functions. | | | | ICSF provides access to cryptographic functions through callable services. A callable service is a routine that receives control using a CALL statement in an application language. Each callable service performs one or more cryptographic functions, including: v Generating and managing cryptographic keys v Enciphering and deciphering data with encrypted keys using the U.S. National Institute of Standards and Technology (NIST) Data Encryption Standard (DES), Advanced Encryption Standard (AES) or the Commercial Data Masking Facility (CDMF) v Enciphering and deciphering data with clear keys using either the NIST Data Encryption Standard (DES), or Advanced Encryption Standard (AES) v Transforming a CDMF DATA key to a transformed shortened DES key v Reenciphering 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 topic provides an overview of the symmetric key cryptographic functions provided in ICSF, explains the functions of the cryptographic keys, and introduces the topic of building key tokens. Many services have hardware requirements. See each service for details. Functions of the Symmetric Cryptographic Keys ICSF provides functions to create, import, and export AES, DES, and HMAC keys. This topic gives an overview of these cryptographic keys. Detailed information about how ICSF organizes and protects keys is in z/OS Cryptographic Services ICSF Administrator's Guide. | | | | | ICSF supports two types of symmetric key tokens: fixed-length and variable-length. In fixed-length key tokens, key type and usage are defined by the control vector. In variable-length key tokens, the key type and usage are defined in the associated data section. The control vector and associated data section are cryptographically bound to the encrypted key value in the token. © Copyright IBM Corp. 1997, 2011 15 Key Separation The cryptographic feature 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. An ICSF system has only one DES master key and one AES master key. However, to provide for key separation, the cryptographic feature automatically encrypts each type of key in a fixed-length token 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. | Note: In PCF, key separation applies only to keys enciphered under the master key (keys in operational form). In ICSF, key separation also applies to keys enciphered under transport keys (keys in importable or exportable form). This allows the creator of a key to transmit the key to another system and to enforce its use at the other system. | Master Key Variant for Fixed-length Tokens 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 the master key will encipher. These variations are called master key variants. The cryptographic coprocessor creates a master key variant by exclusive ORing a fixed pattern, called a control vector, onto the master key. A unique 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 exclusive ORed with the master key in order to produce the variant. The different key types are described in “Types of Keys” on page 19. 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. The master key, in the form of master key variants, protects keys operating on the system. A key 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 for Fixed-length Tokens Like the master key, ICSF 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. A transport 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 exclusive ORed 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, ICSF allows you to encrypt selected keys under a transport key itself, not under the transport key variant. For more information, see the 'Transport keys (or key-encrypting keys)' list item in “Types of Keys” on page 19. 16 z/OS V1R13 ICSF Application Programmer's Guide Key Forms A key that is protected under the master key is in operational form, which means ICSF 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 because, for security reasons, the key should no longer be active on the system. When ICSF enciphers 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 reenciphered 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 callable services can use an operational key form. The key token build, key generate, key import, data key import, clear key import, multiple clear key import, secure key import, and multiple secure key import callable services can create an operational key form. v Exportable key form is transported to another cryptographic system. It can only be passed to another system. The ICSF callable services cannot use it for cryptographic functions. The key generate, data key export, and key export callable services produce the exportable key form. v Importable key form can be transformed into operational form on the local system. The key import callable service (CSNBKIM) and the Data key import callable service (CSNBDKM) can use an importable key form. Only the key generate callable service (CSNBKGN) can create an importable key form. The secure key import (CSNBSKI) and multiple secure key import (CSNBSKM) callable services can convert a clear key into an importable key form. For more information about the key types, see either “Functions of the Symmetric Cryptographic Keys” on page 15 or the z/OS Cryptographic Services ICSF Administrator's Guide. See “Key Forms and Types Used in the Key Generate Callable Service” on page 63 for more information about key form. DES Key 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 ICSF key forms can only be in one direction: IMPORTABLE —to→ OPERATIONAL —to→ EXPORTABLE Key Token | | | | | | | ICSF supports two types of symmetric key tokens: fixed-length and variable-length. The fixed-length token is a 64-byte field composed of a key value and control information in the control vector. The variable-length token is composed of a key value and control information in the associated data section of the token. The control information is assigned to the key when ICSF 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, ICSF can: v Support continuous operation across a master key change Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 17 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 ICSF system that created it (or another ICSF 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 callable services such as those listed here. The callable services are described in detail in Chapter 5, “Managing Symmetric Cryptographic Keys.” v CKDS Key record read and CKDS key record read2 v Clear key import v Data key import v Key generate and Key generate2 v Key import v Key part import and Key part import2 v Key token build and Key token build2 v Multiple secure key import v Multiple clear key import v Secure key import and secure key import2 v Symmetric key import2 | | The master key may be dynamically changed between the time that you invoke a service, such as the key import callable service to obtain a key token, and the time that you pass the key token to the encipher callable service. When a change to the master key occurs, ICSF reenciphers the caller's key from under the old master key to under the new master key. A Return Code of 0 with a reason code of 10000 notifies you that ICSF reenciphered the key. For information on reenciphering the CKDS or the PKDS, see z/OS Cryptographic Services ICSF Administrator's Guide. 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. (See “Other Considerations” on page 22 for additional information.) For debugging information, see Appendix B, “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 An application obtains the external key token by using one of the callable services such as these listed. They are described in detail in Chapter 5, “Managing Symmetric Cryptographic Keys.” v Key generate v Key export v Data key export v Symmetric key export | 18 z/OS V1R13 ICSF Application Programmer's Guide For debugging information, see Appendix B, “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- to 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 callable service to get the key in operational form. For debugging information, see Appendix B, “Key Token Formats” for the format of a null key token. Key Wrapping ICSF supports two methods of wrapping the key value in a fixed-length symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. | | | The key value in a symmetric key token may be wrapped in two ways. The original method has been used by ICSF since it was first released. The key value in DES key tokens are encrypted using triple DES encryption and key parts are encrypted separately. The key value in AES tokens are encrypted using AES encryption and cipher block chaining mode. The enhanced method of key wrapping, introduced in HCR7780, is ANSI X9.24 compliant. The key value of all keys are bundled with other token data and encrypted using triple DES or AES encryption and cipher block chaining mode. The enhanced method requires a z196 with a CEX3C. Your installation's system programmer can, while customizing installation options data set as described in the z/OS Cryptographic Services ICSF System Programmer's Guide, use the DEFAULTWRAP parameter to specify the default key wrapping for symmetric keys. Application programs can override this default method using the WRAP-ENH (use enhanced method) and WRAP-ECB (use original ECB key-wrapping method) rule array keywords. Note: Variable-length tokens are wrapped using the AESKW wrapping method defined in ANSI X9.102 and are not affected by the DEFAULTWRAP setting. | | Control Vector for DES Keys For DES keys, a unique control vector exists for each type of key the master key enciphers. The cryptographic feature exclusive ORs 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 only used 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 these categories based on the functions they perform. v DES master key. The DES master key is a double-length (128 bits) key used only to encrypt other keys. The ICSF administrator installs and changes the DES master key (see z/OS Cryptographic Services ICSF Administrator's Guide for Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 19 details). The administrator does this by using the Master Key Entry panels or the optional Trusted Key Entry (TKE) workstation. The master key always remains in a secure area in the cryptographic facility. It is used only to encipher and decipher keys. Other keys also encipher and decipher keys and are mostly used to protect cryptographic keys you transmit on external links. These keys, while on the system, are also encrypted under the master key. v AES master key. The AES master key is a 32–byte (256 bits) key used only to encrypt other keys. The ICSF administrator installs and changes the AES master key (see z/OS Cryptographic Services ICSF Administrator's Guide for details). The administrator does this by using the Master Key Entry panels or the optional Trusted Key Entry (TKE) workstation (TKE V5.3). The master key always remains in a secure area in the cryptographic facility. It is used only to encipher and decipher keys. Other keys also encipher and decipher keys and are mostly used to protect cryptographic keys you transmit on external links. These keys, while on the system, are also encrypted under the master key. v AES Data-encrypting keys. The AES data-encrypting keys are 128-, 192- and 256-bits keys that protect data privacy. If you intend to use a data-encrypting key for an extended period, you can store it in the CKDS so that it will be reenciphered if the master key is changed. v AES Cipher keys. The AES cipher keys are 128-, 192- and 256-bit keys that protect data privacy. If you intend to use a cipher key for an extended period, you can store it in the CKDS so that it will be reenciphered if the master key is changed. | | | | v DES Data-encrypting keys. The DES data-encrypting keys are single-length (64-bit), double-length (128-bit), or triple-length (192-bit) keys that protect data privacy. Single-length 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, you can store it in the CKDS so that it will be reenciphered if the master key is changed. You can use single-length data-encrypting keys in the encipher, decipher, encode, and decode callable services to manage data and also in the MAC generation and MAC verification callable services. Double-length and triple-length data-encrypting keys can be used in the encipher and decipher callable services for more secure data privacy. DATAC is also a double-length data encrypting key. Single-length data-encrypting keys can be exported and imported using the ANSI X9.17 key management callable services. v Data-translation keys. The data-translation keys are single-length (64 bits) keys used for the ciphertext translate callable service as either the input or the output data-transport key. Restriction: Data-translation keys are only supported on the IBM Eserver zSeries 900. v CIPHER keys. These consist of CIPHER, ENCIPHER and DECIPHER keys. They are single and double length keys for enciphering and deciphering data. Note: Double-length CIPHER, ENCIPHER and DECIPHER keys are only supported on the IBM Eserver zSeries 990, IBM Eserver zSeries 890, z9 EC, z9 BC, z10 EC and z10 BC with a PCIXCC, CEX2C, or CEX3C. v HMAC keys. HMAC keys are variable-length (80 - 2048 bits) keys used to generate and verify MACs using the key-hash MAC algorithm. 20 z/OS V1R13 ICSF Application Programmer's Guide | | | | | | | | | | | | | | | | | | v MAC keys. The MAC keys are single- and double-length (64 and 128 bits) keys used for the callable services that generate and verify MACs. With a PCIXCC, CEX2C, or CEX3C, MAC and MACVER can be single or double length keys. v 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 (128 bits) keys. PIN keys are used in the Clear PIN generate, Encrypted PIN verify, and Encrypted PIN translate callable services. For installations that do not support double-length 128-bit keys, effective single-length keys are provided. For a single-length key, the left key half of the key equals the right key half. “Managing Personal Authentication” on page 56 gives an overview of the PIN algorithms you need to know to write your own application programs. v AES Transport keys (or key-encrypting keys). Transport keys are also known as key-encrypting keys. They are used to protect AES and HMAC keys when you distribute them from one system to another. There are two types of AES transport keys: – Exporter key-encrypting 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 key-encrypting 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 at another time. The importer key at the receiver is the same key as the exporter key at the originator. Note: A key-encrypting key should be as strong or stronger than the key it is wrapping. v DES Transport keys (or key-encrypting keys). Transport keys are also known as key-encrypting keys. They are double-length (128 bits) DES keys used to protect keys when you distribute them from one system to another. There are several types of transport keys: – Exporter or OKEYXLAT key-encrypting 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 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 at another time. The importer key at the receiver is the same key as the exporter key at the originator. – NOCV Importers and Exporters are key-encrypting keys used to transport 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: - On CCF systems, installation of NOCV enablement keys on the CKDS is required. - On PCIXCC, CEX2C, and CEX3C systems, use of NOCV IMPORTERs and EXPORTERs is controlled by access control points. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 21 - Only programs in system or supervisor state can use the NOCV key-encrypting key in the form of tokens in callable services. Any problem program may use NOCV key-encrypting key with labelnames from the CKDS. - NOCV key-encrypting key on the CKDS should be protected by RACF. - NOCV key-encrypting key can be used to encrypt single or double length 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 . - With PCIXCCs, CEX2Cs, and CEX3Cs, NOCV key-encrypting keys can be used with triple length DATA keys. Since DATA keys 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). Note: Transport keys replace local, remote, and cross keys used by PCF. You use key-encrypting keys to protect keys that are transported using any of these services: data key export, key export, key import, clear key import, multiple clear key import, secure key import, multiple secure key import, key generate, and key translate. 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. v ANSI X9.17 key-encrypting keys. These bidirectional key-encrypting keys are used exclusively in ANSI X9.17 key management. They are either single-length (64 bits) or double-length (128 bits) keys used to protect keys when you distribute them from one system to another according to the ANSI X9.17 protocol. Note: ANSI X9.17 keys are only supported on the IBM Eserver zSeries 900. v Key-Generating Keys. Key-generating keys are double-length keys used to derive unique-key-per-transaction keys. Other Considerations These are considerations for keys held in the cryptographic key data set (CKDS) or by applications. v ICSF ensures that keys held in the CKDS are reenciphered during the master key change. Keys with a long life span (more than one master key change) should be stored in the CKDS. v Keys enciphered under the host DES master key and held by applications are automatically reenciphered under a new master key as they are used. Keys with a short life span (for example, VTAM SLE data keys) do not need to be stored in the CKDS. However, if you have keys with a long life span and you do not store them in the CKDS, they should be enciphered under the importer key-encrypting key. The importer key-encrypting key itself should be stored in the CKDS. Table 3 on page 23 describes the key types. You can build, generate, import, or export key types DECIPHER, ENCIPHER, CIPHER, CVARDEC, and CVARPINE on a CCF system, but they are not usable on CCF systems.They will be usable by ICSF if running on a z990, z890, z9 EC, z9 BC, z10 EC and z10 BC with a PCIXCC, CEX2C, or CEX3C. 22 z/OS V1R13 ICSF Application Programmer's Guide Table 3. Descriptions of Key Types | | | | | | | Key Type Meaning AESDATA Data encrypting key. Use the AES 128-, 192- or 256-bit key to encipher and decipher data. AESTOKEN May contain an AES key. AKEK Single-length or double-length, bidirectional key-encrypting key used for the ANSI X9.17 key management callable services. AKEK keys are only supported on the IBM Eserver zSeries 900. CIPHER v DES: This single or double-length key is used to encrypt or decrypt data. It can be used in the Encipher and Decipher callable services. z900 only: This is a single-length key and cannot be used in the Encipher and Decipher services. v AES: This 128-, 192- or 256-bit key is used to encrypt or decrypt data. It can be used in the Symmmetric Algorithm Decipher and Symmetric Algorithm Encipher callable services. CLRAES Data encrypting key. The key value is not encrypted. Use this AES 128-, 192- or 256-bit key to encipher and decipher data. CLRDES Data encrypting key. The key value is not encrypted. Use this DES single-length, double-length, or triple-length key to encipher and decipher data. CVARDEC The TSS Cryptographic variable decipher verb uses a CVARDEC key to decrypt plaintext by using the Cipher Block Chaining (CBC) method. This is a single-length key. CVARENC Cryptographic variable encipher service uses a CVARENC key to encrypt plaintext by using the Cipher Block Chaining (CBC) method. This is a single-length key. CVARPINE Used to encrypt a PIN value for decryption in a PIN-printing application. This is a single-length key. CVARXCVL Used to encrypt special control values in DES key management. This is a single-length key. CVARXCVR Used to encrypt special control values in DES key management. This is a single-length key. DATA Data encrypting key. Use this DES single-length, double-length, or triple-length key to encipher and decipher data. Use the AES 128-, 192- or 256-bit key to encipher and decipher data. DATAC Used to specify a DATA-class key that will perform in the Encipher and Decipher callable services, but not in the MAC Generate or MAC Verify callable services. This is a double-length key. Only available with a PCIXCC/CEX2C/CEX3C. DATAM Double-length MAC generation key. Used to generate a message authentication code. DATAMV Double-length MAC verification key. Used to verify a message authentication code. DATAXLAT Data translation key. Use this single-length key to reencipher text from one DATA key to another. DATAXLAT keys are only supported on the IBM Eserver zSeries 900. DECIPHER This single or double-length DES key is used to decrypt data. It can be used in the Decipher callable service. z900 only: This is a single-length key and cannot be used in the Decipher service. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 23 Table 3. Descriptions of Key Types (continued) Key Type Meaning DKYGENKY Used to generate a diversified key based on the key-generating key. This is a double-length key. ENCIPHER This single or double-length DES key is used to encrypt data. It can be used in the Encipher callable service. z900 only: This is a single-length key and cannot be used in the Encipher service. | | | | | | | | EXPORTER Exporter key-encrypting key. Use this double-length DES key or 128-, 192-, or 256-bit AES key to convert a key from the operational form into exportable form. IKEYXLAT Used to decrypt an input key in the Key Translate callable service. This is a double-length key. IMPORTER Importer key-encrypting key. Use this double-length DES key or 128-, 192or 256-bit AES key to convert a key from importable form into operational form. IMP-PKA Double-length limited-authority importer key used to encrypt PKA private key values in PKA external tokens. IPINENC Double-length input PIN-encrypting key. PIN blocks received from other nodes or automatic teller machine (ATM) terminals are encrypted under this type of key. These encrypted PIN blocks are the input to the Encrypted PIN translate, Encrypted PIN verify, and Clear PIN Generate Alternate services. If an encrypted PIN block is contained in the output of the SET Block Decompose service, it may be encrypted by an IPINENC key. KEYGENKY Used to generate a key based on the key-generating key. This is a double-length key. MAC Single, double-length, or variable-length MAC generation key. Use this key to generate a message authentication code. | z900 only: This is a single-length key. | | MACVER | Single, double-length, or variable-length MAC verification key. Use this key to verify a message authentication code. z900 only: This is a single-length key. OKEYXLAT Used to encrypt an output key in the Key Translate callable service. This is a double-length key. OPINENC Output PIN-encrypting key. Use this double-length output key to translate PINs. The output PIN blocks from the Encrypted PIN translate, Encrypted PIN generate, and Clear PIN generate alternate callable services are encrypted under this type of key. If an encrypted PIN block is contained in the output of the SET Block Decompose service, it may be encrypted by an OPINENC key. PINGEN PIN generation key. Use this double-length key to generate PINs. PINVER PIN verification key. Use this double-length key to verify PINs. SECMSG Used to encrypt PINs or keys in a secure message. This is a double-length key. TOKEN A key token that may contain a key. Clear Keys A clear 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. 24 z/OS V1R13 ICSF Application Programmer's Guide There are four callable services you can use to convert a clear key to an encrypted key: v To convert a clear key to an encrypted data key in operational form, use either the Clear Key Import callable service or the Multiple Clear Key Import callable service. v To convert a clear key to an encrypted key of any type, in operational or importable form, use either the Secure Key Import callable service or the Multiple Secure Key Import callable service. Note: The Secure Key Import and Multiple Secure Key Import callable services can only execute in special secure mode. Clear key DATA tokens can be stored in the CKDS. These tokens can only be used by symmetric key decipher and symmetric key encipher callable services for the DES and AES algorithms. Generating and Managing Symmetric Keys Using ICSF, you can generate keys using either the key generator utility program or the key generate callable service. The dynamic CKDS update callable services allow applications to directly manipulate the CKDS. ICSF provides callable services that support DES and AES key management as defined by the IBM Common Cryptographic Architecture (CCA) and by the ANSI X9.17 standard. The next few topics describe the key generating and management options ICSF provides. Key Generator Utility Program The key generator utility program generates data, data-translation, MAC, PIN, and key-encrypting keys, and enciphers each type of key under a specific master key variant. When the KGUP generates a key, it stores it in the cryptographic key data set (CKDS). Note: If you specify CLEAR, KGUP uses the random number generate and secure key import callable services rather than the key generate service. You can access KGUP using ICSF panels. The KGUP path of these panels helps you create the JCL control statements to control the key generator utility program. When you want to generate a key, you can enter the ADD control statement and information, such as the key type on the panels. For a detailed description of the key generator utility program and how to use it to generate keys, see z/OS Cryptographic Services ICSF Administrator's Guide. Common Cryptographic Architecture DES Key Management Services ICSF provides callable services that support CCA key management for DES keys. Clear Key Import Callable Service (CSNBCKI and CSNECKI) This service imports a clear DATA key that is used to encipher or decipher data. It accepts a clear key and enciphers the key under the host master key, returning an encrypted DATA key in operational form in an internal key token. Control Vector Generate Callable Service (CSNBCVG and CSNECVG) The control vector generate callable service builds a control vector from keywords specified by the key_type and rule_array parameters. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 25 Control Vector Translate Callable Service (CSNBCVT and CSNECVT) The control vector translate callable service changes the control vector used to encipher an external key. Use of this service requires the optional PCI Cryptographic Coprocessor. Cryptographic Variable Encipher Callable Service (CSNBCVE and CSNECVE) The cryptographic variable encipher callable service uses a CVARENC key to encrypt plaintext by using the Cipher Block Chaining (CBC) method. You can use this service to prepare a mask array for the control vector translate service. The plaintext must be a multiple of eight bytes in length. Data Key Export Callable Service (CSNBDKX and CSNEDKX) This service reenciphers a DATA key from encryption under the master key to encryption under an exporter key-encrypting key, making it suitable for export to another system. Data Key Import Callable Service (CSNBDKM and CSNEDKM) This service imports an encrypted source DES DATA key and creates or updates a target internal key token with the master key enciphered source key. | | Diversified Key Generate Callable Service (CSNBDKG and CSNEDKG) The diversified key generate service generates 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. Key Export Callable Service (CSNBKEX and CSNEKEX) This service reenciphers any type of key (except an AKEK or IMP-PKA key) from encryption under a master key variant to encryption under the same variant of an exporter key-encrypting key, making it suitable for export to another system. Key Generate Callable Service (CSNBKGN and CSNEKGN) The key generate callable service generates data, data-translation, MAC, PIN, and key-encrypting keys. It generates a single key or a pair of keys. Unlike the key generator utility program, the key generate service does not store the keys in the CKDS where they can be saved and maintained. The key generate callable service returns the key to the application program that called it. The application program can then use a dynamic CKDS update service to store the key in the CKDS. When you call the key generate callable service, include parameters specifying information about the key you want generated. Because the form of the key restricts its use, you need to choose the form you want the generated key to have. You can use the key_form parameter to specify the form. The possible forms are: v Operational, if 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 CKDS or held by applications in internal key tokens. v Importable, if the key is stored with a file or sent to another system. Importable keys are protected by importer key-encrypting keys. v Exportable, if 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 ICSF callable service. Importable and exportable keys are contained in external key tokens. For more information on key tokens, refer to “Key Token” on page 17. 26 z/OS V1R13 ICSF Application Programmer's Guide Key Import Callable Service (CSNBKIM and CSNEKIM) This service reenciphers a key (except an AKEK) from encryption under an importer key-encrypting key to encryption under the master key. The reenciphered key is in the operational form. Key Part Import Callable Service (CSNBKPI and CSNEKPI) This service combines clear key parts of any key type and returns the combined key value either in an internal token or as an update to the CKDS. Key Test Callable Service (CSNBKYT, CSNEKYT, CSNBKYTX, and CSNEKYTX) This service generates or verifies a secure cryptographic verification pattern for keys. A parameter indicates the action you want to perform. The key to test can be in the clear or encrypted under a master key. The key test extended callable service works on keys encrypted under a KEK. For generating a verification pattern, the service creates and returns a random number with the verification pattern. For verifying a pattern, you supply the random number from the call to the service that generated the pattern. Key Token Build Callable Service (CSNBKTB and CSNEKTB) The key token build callable service is a utility you can use to create skeleton key tokens for AKEKs as input to the key generate or key part import callable service. You can also use this service to build CCA key tokens for all key types ICSF supports. You can also use this service to build CCA key tokens for all key types ICSF supports. Key Translate Callable Service (CSNBKTR and CSNEKTR) This service uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment. Key Translate2 Callable Service (CSNBKTR2 and CSNEKTR2) This service uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment. Multiple Clear Key Import Callable Service (CSNBCKM and CSNECKM) This service imports a single-length, double-length, or triple-length clear DATA key that is used to encipher or decipher data. It accepts a clear key and enciphers the key under the host master key, returning an encrypted DATA key in operational form in an internal key token. Multiple Secure Key Import Callable Service (CSNBSKM and CSNESKM) This service enciphers a single-length, double-length, or triple-length clear key under the host master key or under an importer key-encrypting key. The clear key can then be imported as any of the possible key types. Triple-length keys can only be imported as DATA keys. This service can be used only when ICSF is in special secure mode and does not allow the import of an AKEK. Prohibit Export Callable Service (CSNBPEX and CSNEPEX) This service modifies an operational key so that it cannot be exported. This callable service does not support NOCV key-encrypting keys, DATA, MAC, or MACVER keys with standard control vectors (for example, control vectors supported by the Cryptographic Coprocessor Feature). Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 27 Prohibit Export Extended Callable Service (CSNBPEXX and CSNEPEXX) This service updates the control vector in the external token of a key in exportable form so that the receiver node can import the key but not export it. When the key import callable service imports such a token, it marks the token as non-exportable. The key export callable service does not allow export of this token. Random Number Generate Callable Service (CSNBRNG, CSNERNG, CSNBRNGL, and CSNERNGL) The random number generate callable service creates a random number value to use in generating a key. The callable service uses cryptographic hardware to generate a random number for use in encryption. Remote Key Export Callable Service (CSNDRKX and CSNFRKX) The remote key export callable service uses the trusted block to generate or export DES keys for local use and for distribution to an ATM or other remote device. Restrict Key Attribute Callable Service (CSNBRKA and CSNERKA) | | | This service modifies an AES operational key so that it cannot be exported. Secure Key Import Callable Service (CSNBSKI and CSNESKI) This service enciphers a clear key under the host master key or under an importer key-encrypting key. The clear key can then be imported as any of the possible key types. This service can be used only when ICSF is in special secure mode and does not allow the import of an AKEK. Note: The PKA encrypt, PKA decrypt, symmetric key generate, symmetric key import, and symmetric key export callable services provide a way of distributing DES DATA keys protected under a PKA key. See Chapter 3, “Introducing PKA Cryptography and Using PKA Callable Services,” on page 79 for additional information. Symmetric Key Export Callable Service (CSNDSYX and CSNFSYX) This service transfers an application-supplied symmetric key (a DATA key) from encryption under the DES host master key to encryption under an application-supplied RSA public key. (There are two types of PKA public key tokens: RSA and DSS. This callable service can use only the RSA type.) The application-supplied DATA key must be an ICSF DES internal key token or the label of such a token in the CKDS. The symmetric key import callable service can import the PKA-encrypted form at the receiving node. Symmetric Key Generate Callable Service (CSNDSYG and CSNFSYG) This service generates a symmetric key (that is, a DATA key) and returns it encrypted using DES and encrypted under an RSA public key token. (There are two types of PKA public key tokens: RSA and DSS. This callable service can use only the RSA type.) The DES-encrypted key can be an internal token encrypted under a host DES master key, or an external form encrypted under a KEK. (You can use the symmetric key import callable service to import the PKA-encrypted form.) 28 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Import Callable Service (CSNDSYI and CSNFSYI) This service imports a symmetric (DES) DATA key enciphered under an RSA public key. (There are two types of PKA private key tokens: RSA and DSS. This callable service can use only the RSA type.) This service returns the key in operational form, enciphered under the DES master key. Transform CDMF Key Callable Service (CSNBTCK and CSNETCK) Restriction: This service is only available on the IBM Eserver zSeries 900. It changes a CDMF DATA key in an internal or external token to a transformed shortened DES key. It ignores the input internal DES token markings and marks the output internal token for use in the DES. You need to use this service only if you have a CDMF or DES-CDMF system that needs to send CDMF-encrypted data to a DES-only system. The CDMF or DES-CDMF system must generate the key, shorten it, and pass it to the DES-only system. If the input DATA key is in an external token, the operational KEK must be marked as DES or SYS-ENC. The service fails for an external DATA key encrypted under a KEK that is marked as CDMF. Trusted Block Create Callable Service (CSNDTBC and CSNFTBC) This service creates and activates a trusted block under two step process. User Derived Key Callable Service (CSFUDK and CSFUDK6) Restriction: This service is only available on the IBM Eserver zSeries 900. This service generates a single-length or double-length MAC key, or updates an existing user-derived key. A single-length MAC key can be used to compute a Message Authentication Code (MAC) following the ANSI X9.9, ANSI X9.19, or the Europay, MasterCard, Visa (EMV) Specification MAC processing rules. A double-length MAC key can be used to compute a MAC following the ANSI X9.19 optional double MAC processing rule or the EMV rules. Common Cryptographic Architecture AES Key Management Services ICSF provides callable services that support CCA key management for AES keys. Key Generate Callable Service (CSNBKGN and CSNEKGN) The key generate callable service generates AES data keys. It generates a single operational key. Unlike the key generator utility program, the key generate service does not store the keys in the CKDS where they can be saved and maintained. The key generate callable service returns the key to the application program that called it. The application program can then use a dynamic CKDS update service to store the key in the CKDS. | | | | | Key Generate2 Callable Service (CSNBKGN2 and CSNEKGN2) | | | Key Part Import2 Callable Service (CSNBKPI2 and CSNEKPI2) The service generates AES keys. It generates one operational key or an operational key pair. The key generate callable service returns the key to the application program that called it. The application program can then use a dynamic CKDS update service to store the key in the CKDS. This service combines clear key parts of any AES key type and returns the combined key value either in an internal token or as an update to the CKDS. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 29 Key Test2 Callable Service (CSNBKYT2 and CSNEKYT2) | | | This service generates or verifies a secure cryptographic verification pattern for AES keys. A parameter indicates the action you want to perform. Key Token Build Callable Service (CSNBKTB and CSNEKTB) The key token build callable service is a utility you can use to create clear AES key tokens, secure AES key tokens and skeleton secure AES key tokens for use with other callable services. You can also use this service to build CCA key tokens for all key types ICSF supports. You can also use this service to build CCA key tokens for all key types ICSF supports. Multiple Clear Key Import Callable Service (CSNBCKM and CSNECKM) This service imports a a 128-, 192- or 256-bit clear DATA key that is used to encipher or decipher data. It accepts a clear key and enciphers the key under the host master key, returning an encrypted DATA key in operational form in an internal key token. Multiple Secure Key Import Callable Service (CSNBSKM and CSNESKM) This service enciphers 128-, 192- or 256-bit clear DATA key under the host master key. This service can be used only when ICSF is in special secure mode. | | | Restrict Key Attribute Callable Service (CSNBRKA and CSNERKA) | | | Secure Key Import2 Callable Service (CSNBSKI2 and CSNESKI2) This service modifies an AES operational key so that it cannot be exported. This service enciphers a variable length clear AES key under the host master key. This service can be used only when ICSF is in special secure mode. Symmetric Key Export Callable Service (CSNDSYX and CSNFSYX) Use the symmetric key export callable service to transfer an application-supplied AES DATA key from encryption under a master key to encryption under an application-supplied RSA public key or AES EXPORTER key. The application-supplied key must be an ICSF AES internal key token or the label of such a token in the CKDS. The Symmetric Key Import or Symmetric Key Import2 callable services can import the key encrypted under the RSA public key or AES EXPORTER at the receiving node. | | | | | | | Symmetric Key Generate Callable Service (CSNDSYG and CSNFSYG) This service generates a symmetric DATA key and returns it encrypted under the host AES master key and encrypted under an RSA public key token. (There are two types of PKA public key tokens: RSA and DSS. This callable service can use only the RSA type.) The AES-encrypted key can only be an internal token encrypted under a host AES master key. You can use the symmetric key import callable service to import the PKA-encrypted form. Symmetric Key Import Callable Service (CSNDSYI and CSNFSYI) This service imports a symmetric (AES) DATA key enciphered under an RSA public key. (There are two types of PKA private key tokens: RSA and DSS. This callable 30 z/OS V1R13 ICSF Application Programmer's Guide service can use only the RSA type.) This service returns the key in operational form, enciphered under the AES master key. | | | | | | Symmetric Key Import2 Callable Service (CSNDSYI2 and CSNFSYI2) This service imports an AES key enciphered under an RSA public key. (There are two types of PKA private key tokens: RSA and DSS. This callable service can use only the RSA type.) This service returns the key in operational form, enciphered under the AES master key. Common Cryptographic Architecture HMAC Key Management Services ICSF provides callable services that support CCA key management for HMAC keys. HMAC keys are stored in the cryptographic key data set (CKDS). Key Generate2 callable service (CSNBKGN2 and CSNEKGN2) The service generates HMAC keys. It generates operational key or operational key pair. The key generate callable service returns the key to the application program that called it. The application program can then use a dynamic CKDS update service to store the key in the CKDS. Key Part Import2 callable service (CSNBKPI2 and CSNEKPI2) This service combines clear key parts of any HMAC key type and returns the combined key value either in an internal token or as an update to the CKDS. Key Test2 callable service (CSNBKYT2 and CSNEKYT2) This service generates or verifies a secure cryptographic verification pattern for HMAC keys. A parameter indicates the action you want to perform. Key Token Build2 callable service (CSNBKTB2 and CSNEKTB2) This service is a utility you can use to create skeleton HMAC key tokens for use with other callable services. Restrict Key Attribute callable service (CSNBRKA and CSNERKA) This service modifies an HMAC operational key so that it cannot be exported. Secure Key Import2 callable service (CSNBSKI2 and CSNESKI2) This service enciphers a variable length clear HMAC key under the host master key. This service can be used only when ICSF is in special secure mode. Symmetric Key Export Callable Service (CSNDSYX and CSNFSYX) This service transfers an application-supplied symmetric key (HMAC key) from encryption under the AES host master key to encryption under an application-supplied RSA public key. (There are two types of PKA public key tokens: RSA and DSS. This callable service can use only the RSA type.) The application-supplied key must be an ICSF internal key token or the label of such a token in the CKDS. The symmetric key import callable service can import the PKA-encrypted form at the receiving node. Symmetric Key Import2 Callable Service (CSNDSYI2 and CSNFSYI2) This service imports an HMAC key enciphered under an RSA public key. (There are two types of PKA private key tokens: RSA and DSS. This callable service can use only the RSA type.) This service returns the key in operational form, enciphered under the AES master key. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 31 | ECC Diffie-Hellman Key Agreement Models | | | | | | | | | | | | | | Token Agreement Scheme | | | | | | v Specify an ECC token as the public key identifier containing other party's ECC public key part. The caller must have both the required key tokens and both Parties identifiers including a randomly generated nonce. Combine the exchanged nonce and Party Info into the party identifier. (Both parties must combine this information in the same format.) Then call the ECC Diffie-Hellman callable service. Specify a skeleton token or the label of a skeleton token as the output key identifier as a container for the computed symmetric key material. Note, both parties must specify the same key type in their skeleton key tokens. v Specify rule array keyword DERIV01 to denote the Static Unified Model key agreement scheme. v Specify an ECC token as the private key identifier containing this party's ECC public-private key pair. v Optionally specify a private KEK key identifier, if the key pair is in an external key token. v Specify a skeleton token as the output key identifier as a container for the computed symmetric key material. v Optionally specify an output KEK key identifier, if the output key is to be in an external key token. v Specify the combined party info (including nonce) as the party identifier. v Specify the desired size of the key to be derived (in bits) as the key bit length. | | Obtaining the Raw “Z” value | | | | | | | | | | | | To use a key agreement scheme that differs from the above, one may obtain the raw shared secret "Z" and skip the key derivation step. The caller must then derive the final key material using a method of their choice. Do not specify any party info. v Specify rule array keyword “PASSTHRU" to denote no key agreement scheme. v Specify an ECC token as the private key identifier containing this party's ECC public-private key pair. v Optionally specify a private KEK key identifier, if the key pair is in an external key token. v Specify an ECC token as the public key identifier containing other party's ECC public key part. v The output key identifier be populated with the resulting shared secret material. Improved remote key distribution Note: This improved remote key distribute support is only available on the 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 as Automated 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 is especially important to banks, since it replaces expensive human operations with network transactions that can be processed quickly and inexpensively. This method supports a variety of requirements, fulfilling the new 32 z/OS V1R13 ICSF Application Programmer's Guide needs of the banking community while simultaneously making significant interoperability improvements to related cryptographic key-management functions. For the purposes of this description, the ATM scenario will be used to illustrate operation of the new methods. Other uses of this method are also valuable. Remote Key Loading Remote key loading refers to the process of installing 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. A KEK is a type of symmetric encryption key that is used to encrypt other keys so 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. Old remote key loading example: Use an ATM as an example of the remote key loading process. A new ATM has none of the bank's keys installed when it is delivered from the manufacturer. The process of getting the first key securely loaded is difficult. This has typically been done by loading the first KEK into each ATM manually, in multiple cleartext key parts. Using dual control for key parts, two separate people must carry key part values to the ATM, then load each key part manually. Once inside the ATM, the key parts are combined to form the actual KEK. In this manner, neither of the two people has the entire key, protecting the key value from disclosure or misuse. This method is labor-intensive and error-prone, making it expensive for the banks. New remote key loading methods: New remote key loading methods have been developed to overcome some of the shortcomings of the old manual key loading methods. These new methods define acceptable techniques using public key cryptography to load keys remotely. Using these new methods, banks will be able to load the initial KEKs without sending people to the remote device. This will reduce labor costs, be more reliable, and be much less expensive to install and change keys. The new cryptographic features added provide new methods for the creation and use of the special key forms needed for remote key distribution of this type. In addition, they provide ways to solve long-standing barriers to secure key exchange with non-IBM cryptographic systems. Once an ATM is in operation, the bank can install new keys as needed by sending them enciphered under a KEK installed previously. This is straightforward in concept, but the cryptographic architecture in ATMs is often different from that of the host system sending the keys, and it is difficult to export the keys in a form understood by the ATM. For example, cryptographic architectures often enforce key-usage restrictions in which a key is bound to data describing limitations on how it can be used - for encrypting data, for encrypting keys, for operating on message authentication codes (MACs), and so forth. The encoding of these restrictions and the method used to bind them to the key itself differs among cryptographic architectures, and it is often necessary to translate the format to that understood by the target device 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. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 33 A new data structure called a trusted block is defined to facilitate the remote key loading methods. The trusted block is the primary vehicle supporting these new methods. Trusted block The trusted block is the central data structure to support all remote key loading functions. It provides great power and flexibility, but this means that it must be designed and used with care in order to have a secure system. This security is provided through several features of the design. v A two step process is used to create a trusted block. v The trusted block includes cryptographic protection that prevents any modification when it is created. v A number of fields in the rules of a trusted block offer the ability to limit how the block is used, reducing the risk of it being used in unintended ways or with unintended keys. The trusted block is the enabler which requires secure approval for its creation, then enables the export or generation of DES and TDES keys in a wide variety of forms as approved by the administrators who created the trusted block. For added security, the trusted blocks themselves can be created on a separate system, such as an xSeries server with an IBM 4764 Cryptographic Coprocessor, locked in a secure room. The trusted block can subsequently be imported into the zSeries server where they will be used to support applications. There are two CCA callable services to manage and use trusted blocks: Trusted Block Create (CSNDTBC and CSNETBC) and Remote Key Export (CSNDRKX and CSNFRKX). The Trusted Block Create service creates a trusted block, and the Remote Key Export service uses a trusted block to generate or export DES keys according to the parameters in the trusted block. The trusted block consists of a header followed by several sections. Some elements are required, while others are optional. Figure 1 on page 35 shows the contents of a trusted block. The elements shown in the table give an overview of the structure and do not provide all of the details of a trusted block. 34 z/OS V1R13 ICSF Application Programmer's Guide Structure version information Modulus Public key Exponent Attributes MAC key MAC Trusted block protection information Flags MKVP Activation/Expiration dates Public key name (optional) Label Rule 1 Rule 2 Rules Rule 3 ... Rule N Application defined data Data defined and understood only by the application using the trusted block Figure 1. Overview of trusted block contents Here is a brief description of the elements that are depicted. Structure version information - This identifies the version of the trusted block structure. It is included so that code can differentiate between this trusted block layout and others that may be developed in the future. Public key - This contains the RSA public key and its attributes. For distribution of keys to a remote ATM, this will be the root certification key for the ATM vendor, and it will be used to verify the signature on public-key certificates for specific individual ATMs. In this case, the Trusted Block will also contain Rules that will be used to generate or export symmetric keys for the ATMs. It is also possible for the Trusted Block to be used simply as a trusted public key container, and in this case the Public Key in the block will be used in general-purpose cryptographic functions such as digital signature verification. The public key attributes contain information on key usage restrictions. This is used to securely control what operations will be permitted to use the public key. If desired, the public key can be restricted to use for only digital signature operations, or for only key management operations. Trusted block protection information - This topic contains information that is used to protect the Trusted Block contents against modification. According to the method in ISO 16609, a CBC-mode MAC is calculated over the Trusted Block using a randomly-generated triple-DES (TDES) key, and the MAC key itself is encrypted Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 35 and embedded in the block. For the internal form of the block, the MAC key is encrypted with a randomly chosen fixed-value variant of the PKA master key. For the external form, the MAC key is encrypted with a fixed variant of a key-encrypting key. The MKVP field contains the master key verification pattern for the PKA master key that was used, and is filled with binary zeros if the trusted block is in external format. Various flag fields contain these boolean flags. v Active flag - Contained within the flags field of the required trusted block information section, this flag indicates whether the trusted block is active and ready for use by other callable services. Combined with the use of two separate access control points, the active flag is used to enforce dual control over creation of the block. A person whose active role is authorized to create a trusted block in inactive form creates the block and defines its parameters. An inactive trusted block can only be used to make it active. A person whose active role is authorized to activate an inactive trusted block must approve the block by changing its status to active. See Figure 3 on page 39. The Remote_Key_Export callable service can only use an internal active trusted block to generate or export DES keys according to the parameters defined in the trusted block. v Date checking flag - Contained within the optional activation and expiration date subsection of the required trusted block information subsection, this flag indicates whether the coprocessor checks the activation and expiration dates for the trusted block. If the date checking flag is on, the coprocessor compares the activation and expiration dates in the optional subsection to the coprocessor internal real time clock, and processing terminates if either date is out of range. If this flag is off or the activation and expiration dates subsection is not defined, the device does no date checking. If this flag is off and the activation and expiration dates subsection is defined, date checking can still be performed outside of the device if required. The date checking flag enables use of the trusted block in systems where the coprocessor clock is not set. Trusted block name - This field optionally contains a text string that is a name (key label) for the trusted block. It is included in the block for use by an external system such as a host computer, and not by the card itself. In the zSeries system, the label can be checked by RACF to determine if use of the block is authorized. It is possible to disable use of trusted blocks that have been compromised or need to be removed from use for other reasons by publishing a revocation list containing the key names for the blocks that must not be used. Code in the host system could check each trusted block prior to it being used in the cryptographic coprocessor, to ensure that the name from that block is not in the revocation list. Expiration date and activation dates - The trusted block can optionally contain an expiration date and an activation date. The activation date is the first day on which the block can be used, and the expiration date is the last day when the block can be used. If these dates are present, the date checking flag in the trusted block will indicate whether the coprocessor should check the dates using its internal real-time clock. In the case of a system that does set the coprocessor clock, checking would have to be performed by an application program prior to using the trusted block. This is not quite as secure, but it is still valuable, and storing the dates in the block itself is preferable to making the application store it somewhere else and maintain the association between the separate trusted block and activation and expiration dates. Application-defined data - The trusted block can hold data defined and understood only by the host application program. This data is included in the protected contents of the trusted block, but it is not used or examined in any way by 36 z/OS V1R13 ICSF Application Programmer's Guide the coprocessor. By including its own data in the trusted block, an application can guarantee that the data is not changed in any way, since it is protected in the same way as the other trusted block contents. Rules - A variable number of rules can be included in the block. Each rule contains information on how to generate or export a symmetric key, including values for variants to be used in order to provide keys in the formats expected by systems with differing cryptographic architectures. Use of the rules are described in the topics covering key generation and export using the RKX function. This table summarizes the required and optional values of each rule. Field name Required field Description Rule ID Yes Specifies the 8-character name of the rule Operation Yes Indicates whether this rule generates a new key or exports an existing key Generated key length Yes Specifies the length of the key to be generated Key-check algorithm ID Yes Specifies which algorithm to use to compute the optional key-check value (KCV). Options are v No KCV v Encrypt zeros with the key v Compute MDC-2 hash of the key Symmetricencrypted output format Yes Specifies the format of the required symmetric-encrypted key output. Options are: v CCA key token v RKX key token Asymmetricencrypted output format Yes Specifies the format of the optional asymmetricencrypted key output (key is encrypted with RSA). Options are: v No asymmetric-encrypted key output v Encrypt in PKCS1.2 format v Encrypt in RSAOAEP format Transport-key variant No Specifies the variant to apply to the transport key prior to it being used to encrypt the key being generated or exported Export key CV No Specifies the CCA CV to apply to the transport key prior to it being used to encrypt the key being generated or exported. The CV defines permitted uses for the exported key. Export key length limits No Defines the minimum and maximum lengths of the key that can be exported with this rule. Output key variant No Specifies the variant to apply to the generated or exported key prior to it being encrypted. Export-key rule reference No Specifies the rule ID for the rule that must have been used to generate the key being exported, if that key is an RKX key token. Export-key CV restrictions No Defines masks and templates to use to restrict the possible CV values that a source key can have when being exported with RKX. Only applies if the key is a CCA key token. This can control the types of CCA keys that can be processed using the rule. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 37 Field name Required field Description Export-key label template No Specifies the key label of the key token that contains the source key to be exported. A key label is a name used to identify a key. The rule can optionally contain a key label template, which will be matched against the host-supplied key label, using a wildcard (*) so that the template can match a set of related key labels. The operation will only be accepted if the supplied label matches the wildcard template in the rule. Changes to the CCA API These changes have been made to the CCA API to support remote key loading using trusted blocks: v A new Trusted Block Create (CSNDTBC and CSNETBC) callable service has been developed to securely create trusted blocks under dual control. v A new Remote Key Export (CSNDRKX and CSNFRKX) callable service has been developed to generate or export DES and TDES keys under control of the rules contained in a trusted block. v The Digital Signature Verify (CSNDDSV) callable service has been enhanced so that, in addition to verifying ordinary CCA RSA keys, it can use the RSA public key contained in a trusted block to verify digital signatures. v The PKA Key Import (CSNDPKI) callable service has been enhanced so it can import an RSA key into the CCA domain. In addition, the verb can import an external format trusted block into an internal format trusted block, ready to be used in the local system. v The PKA Key Token Change (CSNDKTC and CSNFKTC) callable service has been enhanced so that it can update trusted blocks to the current PKA master key when the master key is changed. A trusted block contains an embedded MAC key enciphered under the PKA master key. When the PKA master key is changed, the outdated MAC key and the trusted block itself need to be updated to reflect the current PKA master key. v The MAC Generate (CSNBMGN) and MAC Verify (CSNBMVR) callable services have been enhanced to add ISO 16609 TDES MAC support in which the text will be CBC-TDES encrypted using a double-length key and the MAC will be extracted from the last block. v The PKA key storage callable services support trusted blocks. The RKX key token CCA normally uses key tokens that are designed solely for the purposes of protecting the key value and carrying metadata associated with the key to control its use by CCA cryptographic functions. The remote key loading design introduces a new type of key token called an RKX key token. The purpose of this token is somewhat different, and its use is connected directly with the Remote Key Export callable service added to CCA of the remote key loading design. The RKX key token uses a special structure that binds the token to a specific trusted block, and allows sequences of Remote Key Export calls to be bound together as if they were an atomic operation. This allows a series of related key-management operations to be performed using the Remote Key Export callable service. These capabilities are made possible by incorporating these three features into the RKX key token structure: 38 z/OS V1R13 ICSF Application Programmer's Guide v The key is enciphered using a variant of the MAC key that is in the trusted block. A fixed, randomly-derived variant is applied to the key prior to it being used. As a result, the enciphered key is protected against disclosure since the trusted block MAC key is itself protected at all times. v The structure includes the rule ID contained in the trusted block rule that was used to create the key. A subsequent call to the Remote Key Export callable service can use this key with a trusted block rule that references this rule ID, effectively chaining use of the two rules together securely. v A MAC is computed over the encrypted key and the rule ID, using the same MAC key that is used to protect the trusted block itself. This MAC guarantees that the key and the rule ID cannot be modified without detection, providing integrity and binding the rule ID to the key itself. In addition, the MAC will only verify if the RKX key token is used with the same trusted block that created the token, thus binding the key to that specific trusted block. This figure shows a simplified conceptual view of the RKX key token structure. Enciphered key MAC covers these areas Rule ID MAC Figure 2. Simplified RKX key-token structure Using trusted blocks These examples illustrate how trusted blocks are used with the new and enhanced CCA callable services. Creating a trusted block: This figure illustrates the steps used to create a trusted block. Administrator 1 Administrator 2 External trusted block TBC Inactive TBC External trusted block Active Figure 3. Trusted block creation Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 39 A two step process is used to create a trusted block. Trusted blocks are structures that could be abused to circumvent security if an attacker could create them with undesirable settings, and the requirement for two separate and properly authorized people makes it impossible for a single dishonest employee to create such a block. A trusted block cannot be used for any operations until it is in the active state. Any number of trusted blocks can be created in order to meet different needs of application programs. Exporting keys with Remote_Key_Export: This figure shows the process for using a trusted block in order to export a DES or TDES key. This representation is at a very high level in order to illustrate the basic flow. Internal trusted block Active RXK Transport key Validate trusted block Source key Importer key Validate parameter against rules in trusted block Certificate Note: Importer key is only used if source key is an external CCA token. Apply rules in trusted block to build output key value from source key Compute key check value (KCV) on source key, if specified by rule Apply rules to encrypt key value with transport key and optionally with public key in certificate Symmetric encrypted key Figure 4. Exporting keys using a trusted block 40 z/OS V1R13 ICSF Application Programmer's Guide RSA-encrypted key (optional) Key check value (optional) The Remote Key Export callable service is called with these main parameters: v A trusted block, in the active state, defines how the export operation is to be processed, including values to be used for things such as variants to apply to the keys. v The key to be exported, shown previously as the source key. The source key takes one of two forms: 1. A CCA DES key token 2. An RKX key token v A key-encrypting key, shown in the figure as the importer key. This is only used if the source key is an external CCA DES key token, encrypted under a KEK. In this case, the KEK is the key needed to obtain the cleartext value of the source key. v A transport key, either an exporter KEK or an RKX key token, used to encrypt the key being exported. v An optional public key certificate which, if included, contains the certified public key for a specific ATM. The certificate is signed with the ATM vendor's private key, and its corresponding public key must be contained in the trusted block so that this certificate can be validated. The public key contained in the certificate can be used to encrypt the exported key. The processing steps are simple at a high level, but there are many options and significant complexity in the details. v The trusted block itself is validated. This includes several types of validation. – Cryptographic validation using the MAC that is embedded in the block, in which the MAC key is decrypted using the coprocessor's master key, and the MAC is then verified using that key. This verifies the block has not been corrupted or tampered with, and it also verifies that the block is for use with this coprocessor since it will only succeed if the master key is correct. – Consistency checking and field validation, in which the validity of the structure itself is checked, and all values are verified to be within defined ranges. – Fields in the trusted block are checked to see if all requirements are met for use of this trusted block. One check which is always required is to ensure that the trusted block is in the active state prior to continuing. Another check, which is optional based on the contents of the trusted block, is to ensure the operation is currently allowed by comparing the date of the coprocessor real-time clock to the activation and expiration dates defined in the trusted block. v Input parameters to the Remote Key Export callable service are validated against rules defined for them within the trusted block. For example: – The rule can restrict the length of the key to be exported. – The rule can restrict the control vector values for the key to be exported, so only certain key types can be exported with that rule. v When the export key is decrypted, the rules embedded in the trusted block are then used to modify that key to produce the desired output key value. For example, the trusted block can contain a variant to be exclusive-ORed with the source key prior to when that key is encrypted. Many non-IBM cryptographic systems use variants to provide key separation to restrict a key from improper use. v A key check value (KCV) can be optionally computed for the source key. If the KCV is computed, the trusted block allows for one of two key check algorithms to Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 41 be used: (1) encrypting binary zeros with the key, or (2) computing an MDC-2 hash of the key. The KCV is returned as output from the Remote Key Export function. v The export key, which could possibly be modified with a variant according to the rules in the trusted block, is enciphered with the transport key. The rules can specify that the key be created in one of two formats: (1) a CCA key token, or (2) the new RKX key token, described previously. With proper selection of rule options, the CCA key token can create keys that can be used in non-CCA systems. The key value can be extracted from the CCA key token resulting in a generic encrypted key, with variants and other options as defined in the rule. Two optional fields in the trusted block may modify the transport key prior to it being used to encrypt the source key: – The trusted block can contain a CCA control vector (CV) to be exclusive-ORed with the transport key prior to it being used to encrypt the export key. This exclusive-OR process is the standard way CCA applies a CV to a key. – In addition to the CV described previously, the trusted block can also contain a variant to be exclusive-ORed with the transport key prior to its use. If a variant and CV are both present in the trusted block, the variant is applied first, then the CV. v The export key can optionally be encrypted with the RSA public key identified by the certificate parameter of the Remote Key Export callable service, in addition to encrypting it with the transport key as described previously. These two encrypted versions of the export key are provided as separate outputs of the Remote Key Export callable service. The trusted block allows a choice of encrypting the key in either PKCS1.2 format or PKCSOAEP format. Generating keys with Remote_Key_Export: This figure shows the process for using a trusted block to generate a new DES or TDES key. This representation is at a very high level in order to illustrate the basic flow. 42 z/OS V1R13 ICSF Application Programmer's Guide Internal trusted block Active RKX Transport key Validate trusted block. Certificate Validate parameter against rules in trusted block. Generate random key K based on rules in trusted block. Apply rules in trusted block to build output key value from key K. Compute key check value (KCV) on key K if specified by rule. Apply rules to encrypt key value with transport key and optionally with public key in certificate. Symmetric encrypted key RSA-encrypted key (optional) Key check vlaue (optional) Figure 5. Generating keys using a trusted block For key generation, the Remote Key Export callable service is called with these main parameters: v A trusted block, in the internal active state, which defines how the key generation operation is to be processed, including values to be used for things such as variants to apply to the keys. The generated key is encrypted by a variant of the MAC key contained in a trusted block. v An optional public key certificate which, if included, contains the certified public key for a specific ATM. The certificate is signed with the ATM vendor's private key, and its corresponding public key must be contained in the trusted block so that this certificate can be validated. The public key contained in the certificate can be used to encrypt the generated key. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 43 The processing steps are simple at a high level, but there are many options and significant complexity in the details. Most of the processing steps are the same as those described previously for key export. Therefore, only those processing steps that differ are described here in detail. v Validation of the trusted block and input parameters is done as described for export previously. v The DES or TDES key to be returned by the Remote Key Export callable service is randomly generated. The trusted block indicates the length for the generated key. v The output key value is optionally modified by a variant as described previously for export, and then encrypted in the same way as for export using the Transport key and optionally the public key in the certificate parameter. v The key check value (KCV) is optionally computed for the generated key using the same method as for an exported key. Remote key distribution scenario The new and modified CCA functions for remote key loading are used together to create trusted blocks, and then generate or export keys under the control of those trusted blocks. This figure summarizes the flow of the CCA functions to show how they are used: Trusted block parameters Transport key Option=INACTIVE TBC Trusted block (external, inactive) Trusted block Transport key Option=ACTIVATE TBC Trusted block (external, active) Trusted block Transport key PKI Trusted block (internal, active) RKX Symmetric-encrypted key Asymmetric-encrypted key Trusted block Transport key Source key Certificate Importer key (if needed) Key check value Possible to do one of these if key format is an RKX token Trusted block Transport key Source key Symmetric-encrypted key RKX Certificate Importer key (if needed) Figure 6. Typical flow of callable services for remote key export 44 z/OS V1R13 ICSF Application Programmer's Guide Asymmetric-encrypted key Key check value Usage example: The scenario described shows how these functions might be combined in a real-life application to distribute a key to an ATM and keep a copy for local use. Some of the terminology used reflects typical terms used in ATM networks. The example illustrates a fairly complex real-world key distribution scenario, in which these values are produced. v A TMK (Terminal Master Key), which is the root KEK used by the ATM to exchange other keys, is produced in two forms: (1) encrypted under the ATM public key, so it can be sent to the ATM, and (2) as an RKX key token that will be used in subsequent calls to the Remote Key Export callable service to produce other keys. v A key-encrypting key KEK1 that is encrypted under the TMK in a form that can be understood by the ATM. v A PIN-encrypting key PINKEY be used by the ATM to encrypt customer-entered PINs and by the host to verify those PINs. The PINKEY is produced in two forms: (1) encrypted under KEK1 in a form that can be understood by the ATM, and (2) as a CCA internal DES key token with the proper PIN-key CV, encrypted under the CCA DES master key and suitable for use with the coprocessor. It takes seven steps to produce these keys using the Remote Key Export callable service. These steps use a combination of five rules contained in a single trusted block. The rules in this example are referred to as GENERAT1, GENERAT2, EXPORT1, EXPORT2, and EXPORT3. 1. Use the Remote Key Export callable service with rule ID "GENERAT1" to generate a TMK for use with the ATM. The key will be output in two forms: a. ePu(TMK): Encrypted under the ATM public key, supplied in the certificate parameter, CERT 2. 3. 4. 5. b. RKX(TMK): As an RKX key token, suitable for subsequent input to the CSNDRKX callable service Use the Remote Key Export callable service with rule ID "GENERAT2" to generate a key-encrypting key (KEK1) as an RKX key token, RKX(KEK1) Use the Remote Key Export callable service with rule ID "GENERAT2" to generate a PIN key (PINKEY) as an RKX key token: RKX(PINKEY). Use the Remote Key Export callable service with rule ID "EXPORT1 " to export KEK1 encrypted under the TMK as a CCA DES key token using a variant of zeros applied to the TMK. This produces eTMK(KEK1). Use the Remote Key Export callable service with rule ID "EXPORT2 " to export PINKEY encrypted under KEK1 as a CCA token using a variant of zeros applied to KEK1. This produces eKEK1(PINKEY). 6. Use the Remote Key Export callable service with rule ID "EXPORT3 " to export PINKEY under KEK2, an existing CCA key-encrypting key on the local server. This produces eKEK2(PINKEY), with the CCA control vector for a PIN key. 7. Use the Key Import callable service to import the PINKEY produced in step 6 into the local system as an operational key. This produces eMK(PINKEY), a copy of the key encrypted under the local DES master key (MK) and ready for use by CCA PIN API functions. Remote key distribution benefits CCA support for remote key loading solves one new problem, and one long-standing problem. This support allows the distribution of initial keys to ATMs and other remote devices securely using public-key techniques, in a flexible way that can support a wide variety of different cryptographic architectures. They also make it far easier and far more secure to send keys to non-CCA systems when Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 45 those keys are encrypted with a triple-DES key-encrypting key. These changes make it easier for customers to develop more secure systems. Diversifying keys CCA supports several methods for diversifying a key using the diversified key generate callable service. Key-diversification is a technique often used in working with smart cards. In order to secure interactions with a population of cards, a "key-generating key" is used with some data unique to a card to derive ("diversify") keys for use with that card. The data is often the card serial number or other quantity stored on the card. The data is often public, and therefore it is very important to handle the key-generating key with a high degree of security lest the interactions with the whole population of cards be placed in jeopardy. In the current implementation, several methods of diversifying a key are supported: CLR8-ENC, TDES-ENC, TDES-DEC, SESS-XOR, TDES-XOR, TDESEMV2 and TDESEMV4. The first two methods triple-encrypt data using the generating_key to form the diversified key. The diversified key is then multiply-enciphered by the master key modified by the control vector for the output key. The TDES-DEC method is similar except that the data is triple-decrypted. The SESS-XOR method provides a means for modifying an existing DATA, DATAC, MAC, DATAM, or MACVER, DATAMV single- or double-length key. The provided data is exclusive-ORed into the clear value of the key. This form of key diversification is specified by several of the credit card associations. The TDES-ENC and TDES-DEC methods permit the production of either another key-generating key, or a final key. Control-vector bits 19 – 22 associated with the key-generating key specify the permissible type of final key. (See DKYGENKY in Figure 11 on page 832.) Control-vector bits 12 – 14 associated with the key-generating key specify if the diversified key is a final key or another in a series of key-generating keys. Bits 12 – 14 specify a counter that is decreased by one each time the diversified key generate service is used to produce another key-generating key. For example, if the key-generating key that you specify has this counter set to B'010', then you must specify the control vector for the generated_key with a DKYGENKY key type having the counter bits set to B'001' and specifying the same final key type in bits 19 – 22. Use of a generating_key with bits 12 – 14 set to B'000' results in the creation of the final key. Thus you can control both the number of diversifications required to reach a final key, and you can closely control the type of the final key. The TDESEMV2, TDESEMV4, and TDES-XOR methods also derive a key by encrypting supplied data including a transaction counter value received from an EMV smart card. The processes are described in detail at “Visa and EMV-related smart card formats and processes” on page 887. Refer to “Working with Europay–MasterCard–Visa smart cards” on page 424 to understand the various verbs you can use to operate with EMV smart cards. Callable Services for Dynamic CKDS Update ICSF provides the dynamic CKDS update services that allow applications to directly manipulate both the DASD copy and in-storage copy of the current CKDS. Note: Applications using the dynamic CKDS update callable services can run concurrently with other operations that affect the CKDS, such as KGUP, CKDS conversion, REFRESH, and dynamic master key change. An operation can fail if it needs exclusive or shared access to the same DASD 46 z/OS V1R13 ICSF Application Programmer's Guide copy of the CKDS that is held shared or exclusive by another operation. ICSF provides serialization to prevent data loss from attempts at concurrent access, but your installation is responsible for the effective management of concurrent use of competing operations. Consult your system administrator or system programmer for your installation guidelines. | The syntax of the CKDS key record create, CKDS key record read, and CKDS key record write services is identical with the same services provided by the Transaction Security System security application programming interface. Key management applications that use these common interface verbs can run on both systems without change. | | | | Additional versions of CKDS key record create, CKDS key record read, and CKDS key record write (introduced in HCR7780) must be used for variable-length key tokens. These are the CKDS Key Record Create2, CKDS Key Record Read2, and CKDS Key Record Write2 callable services. These services also support existing DES and AES tokens. | | CKDS Key Record Create Callable Service (CSNBKRC and CSNEKRC) This service accepts a key label and creates a null key record in both the DASD copy and in-storage copy of the CKDS. The record contains a key token set to binary zeros and is identified by the key label passed in the call statement. The key label must be unique. | Prior to updating a key record using either the dynamic CKDS update services or KGUP, that record must already exist in the CKDS. You can use either the CKDS key record create service, KGUP, or your key entry hardware to create the initial record in the CKDS. CKDS Key Record Create2 Callable Service (CSNBKRC2 and CSNEKRC2) This service accepts a key label and optionally, a symmetric key token, and creates a key record in both the DASD copy and in-storage copy of the CKDS. The record contains the supplied key token or a null key token and is identified by the key label passed in the call statement. The key label must be unique. | This service must be used with variable-length key tokens. This service supports existing DES and AES key tokens. | | CKDS Key Record Delete Callable Service (CSNBKRD and CSNEKRD) This service accepts a unique key label and deletes the associated key record from both the in-storage and DASD copies of the CKDS. This service deletes the entire record, including the key label from the CKDS. | | CKDS Key Record Read Callable Service (CSNBKRR and CSNEKRR) This service copies an internal key token from the in-storage CKDS to the application storage, where it may be used directly in other cryptographic services. Key labels specified with this service must be unique. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 47 CKDS Key Record Read2 Callable Service (CSNBKRR2 and CSNEKRR2) | | This service copies an internal key token from the in-storage CKDS to the application storage, where it may be used directly in other cryptographic services. Key labels specified with this service must be unique. | This service must be used with variable-length key tokens. This service supports existing DES and AES key tokens. | | CKDS Key Record Write Callable Service (CSNBKRW and CSNEKRW) This service accepts an internal key token and a label and writes the key token to the CKDS record identified by the key label. The key label must be unique. Application calls to this service write the key token to both the DASD copy and in-storage copy of the CKDS, so the record must already exist in both copies of the CKDS. CKDS Key Record Write2 Callable Service (CSNBKRW2 and CSNEKRW2) This service accepts an internal key token and a label and writes the key token to the CKDS record identified by the key label. The key label must be unique. Application calls to this service write the key token to both the DASD copy and in-storage copy of the CKDS, so the record must already exist in both copies of the CKDS. | This service must be used with variable-length key tokens. This service supports existing DES and AES key tokens. | | | | | | | Coordinated KDS Administration Callable Service (CSFCRC and CSFCRC6) This service performs a dynamic CKDS refresh or a dynamic CKDS reencipher operation. This callable service performs the refresh or reencipher operation while allowing applications to update the CKDS. In a sysplex environment, this callable service enables an application to perform a coordinated sysplex-wide refresh or reencipher operation from a single ICSF instance. Callable Services 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 SSL protocol to provide secure communications and prevent eavesdropping, tampering, or message forgery. ICSF provides callable services 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 SSL session between the sender and receiver. PKA Decrypt Callable Service (CSNDPKD) The PKA decrypt callable service uses the corresponding private RSA key to unwrap the RSA-encrypted key and deformat the key value. This service then returns the clear key value to the application. PKA Encrypt Callable Service (CSNDPKE) The PKA encrypt callable service encrypts a supplied clear key value under an RSA public key. Currently, the supplied key can be formatted using the PKCS 1.2 or ZERO-PAD methods prior to encryption. 48 z/OS V1R13 ICSF Application Programmer's Guide System Encryption Algorithm Note: This topic only applies to systems with the Cryptographic Coprocessor Feature. ICSF uses either the DES or AES algorithm or the Commercial Data Masking Facility (CDMF) to encipher and decipher data. The CDMF defines a scrambling technique for data confidentiality. It is a substitute for those customers prohibited from receiving IBM products that support DES data confidentiality services. The CDMF data confidentiality algorithm is composed of two processes: a key shortening process and a standard DES process to encipher and decipher data. Your system can be one of these: v DES v CDMF v DES-CDMF A DES system protects data using a single-length, double-length, or triple-length DES data-encrypting key and the DES algorithm. A CDMF system protects data using a single-length DES data-encrypting key and the CDMF. You input a standard single-length data-encrypting key to the encipher (CSNBENC) and decipher (CSNBDEC) callable services. The single-length data-encrypting key that is intended to be passed to the CDMF is called a CDMF key. Cryptographically, it is indistinguishable from a DES data-encrypting key. Prior to the key being used to encipher or decipher data, however, the Cryptographic Coprocessor Feature hardware cryptographically shortens the key of the CDMF process. This transformed, shortened data-encrypting key can be used only in the DES. (It must never be used in the CDMF; this would result in a double shortening of the key.) When used with the DES, a transformed, shortened data-encrypting key produces results identical to those that the CDMF would produce using the original single-length key. A DES-CDMF system protects data using either the DES or the CDMF. The default is DES. ICSF provides functions to mark internal IMPORTER, EXPORTER, and DATA key tokens with data encryption algorithm bits. IMPORTER and EXPORTER KEKs are marked when they are installed in operational form in ICSF. Your cryptographic key administrator does this. (See z/OS Cryptographic Services ICSF Administrator's Guide for details.) Whenever a DATA key is imported or generated in concert with a marked KEK, this marking is transferred to the DATA key token, unless the token copying function of the callable service is used to override the KEK marking with the marking of the key token passed. These data encryption algorithm bits internally drive the DES or CDMF for the ICSF encryption services. External key tokens are not marked with these data encryption algorithm bits. IMPORTER and EXPORTER KEKs can have data encryption algorithm bit markings of CDMF (X'80'), DES (X'40'), or SYS-ENC (X'00'). DATA keys generated or imported with marked KEKs will also be marked. A CDMF-marked KEK will transfer a data encryption algorithm bit marking of CDMF (X'80') to the DATA key token. A DES-marked KEK will transfer a data encryption algorithm bit marking of DES (X'00') to the DATA key token. A SYS-ENC-marked KEK will transfer a CDMF (X'80') marking to the DATA key token on a CDMF system, and a DES (X'00') marking to the DATA key token on DES-CDMF and DES systems. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 49 To accomplish token copying of data encryption algorithm marks, a valid internal token of the same key type must be provided in the target key identifier field of the service. The token must have the proper token mark to be copied. Notes: 1. For the multiple secure key import callable service the token markings on the KEK are ignored. In this case, the algorithm choice specified in the rule array determines the markings on the DATA key. 2. Propagation of data encryption algorithm bits and token copying are only performed when the ICSF callable service is performed on the Cryptographic Coprocessor Feature. The PCI Cryptographic Coprocessor, PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, and Crypto Express3 Coprocessor do not perform these functions. Table 4 summarizes the data encryption algorithm bits by key type, and the algorithm they drive in the ICSF encryption services. Table 4. Summary of Data Encryption Standard Bits Algorithm Key Type Bits CDMF DATA X'80' KEK X'80' DATA X'00' KEK X'40' KEK X'00' DES System Default Algorithm For PCF users, your system programmer specifies a default encryption mode of DES or CDMF when installing ICSF. (See z/OS Cryptographic Services ICSF System Programmer's Guide for details.) ANSI X9.17 Key Management Services Restriction: ANSI X9.17 keys and ANSI key management services are only supported on the IBM Eserver zSeries 900. The ANSI X9.17 key management standard defines a process for protecting and exchanging DES keys. The ANSI X9.17 standard defines methods for generating, exchanging, using, storing, and destroying these keys. ANSI X9.17 keys are protected by the processes of notarization and offsetting, instead of control vectors. In addition to providing services to support these processes, ICSF also defines and uses an optional process of partial notarization. Offsetting involves exclusive-ORing a key-encrypting key with a counter. The counter, a 56-bit binary number that is associated with a key-encrypting key and contained in certain ANSI X9.17 messages, prevents either a replay or an out-of-sequence transmission of a message. When the associated AKEK is first used, the application initializes the counter. With each additional use, the application increments the counter. Notarization associates the identities of a pair of communicating parties with a cryptographic key. The notarization process cryptographically combines a key with two 16-byte quantities, the origin identifier and the destination identifier, to produce a notarized key. The notarization process is completed by offsetting the AKEK with a counter. 50 z/OS V1R13 ICSF Application Programmer's Guide ICSF makes it possible to divide the AKEK notarization process into two steps. In the first step, partial notarization, the AKEK is cryptographically combined with the origin and destination identifiers and returned in a form that can be stored in the CKDS or application storage. In the second step, the partially notarized AKEK is exclusive OR-ed with a binary counter to complete the notarization process. Partial notarization improves performance when you use an AKEK for many cryptographic service messages, each with a different counter. For details of the partial notarization calculations, refer to “ANSI X9.17 Partial Notarization Method” on page 883. ICSF provides these callable services to support the ANSI X9.17 key management standard. Except where noted, these callable services have the identical syntax as the Transaction Security System verbs of the same name. With few exceptions, key management applications that use these common callable services, or verbs, can be executed on either system without change. Internal tokens cannot be interchanged; external tokens can be. Key Generate Callable Service Used to Generate an AKEK (CSNBKGN) The key generate callable service, described in “Key Generate Callable Service (CSNBKGN and CSNEKGN)” on page 26, can also be used to generate an AKEK in the operational form. It generates either an 8-byte or 16-byte AKEK and places it in a skeleton key token created by the key token build callable service. The length of the AKEK is determined by the key length keyword specified when building the key token. ANSI X9.17 EDC Generate Callable Service (CSNAEGN and CSNGEGN) This service generates an ANSI X9.17 error detection code on an arbitrary length string. ANSI X9.17 Key Export Callable Service (CSNAKEX and CSNGKEX) This service uses the ANSI X9.17 protocol to export a DATA key or a pair of DATA keys, with or without an AKEK. It also provides the ability to convert a single supplied DATA key or combine two supplied DATA keys into a MAC key. ANSI X9.17 Key Import Callable Service (CSNAKIM and CSNGKIM) This service uses the ANSI X9.17 protocol to import a DATA key or a pair of DATA keys, with or without an AKEK. It also provides the ability to convert a single supplied DATA key or combine two supplied DATA keys into a MAC key. The syntax is identical to the Transaction Security System verb, with these exceptions: v Keys cannot be imported directly into the CKDS. ANSI X9.17 Key Translate Callable Service (CSNAKTR and CSNGKTR) This service translates one or two DATA keys or an AKEK from encryption under one AKEK to encryption under another AKEK, using the ANSI X9.17 protocol. ANSI X9.17 Transport Key Partial Notarize Callable Service (CSNATKN and CSNGTKN) This service preprocesses or partially notarizes an AKEK with origin and destination identifiers. The partially notarized key is supplied to the ANSI X9.17 key export, Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 51 ANSI X9.17 key import, or ANSI X9.17 key translate callable service to complete the notarization process. The syntax is identical to the Transaction Security System verb except that: v The callable service does not update the CKDS. Enciphering and Deciphering Data The encipher and decipher callable services protect data off the host. ICSF protects sensitive data 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, ICSF can use the Data Encryption Standard (DES) algorithm to encipher or decipher data or keys. The algorithm is documented in the Federal Information Processing Standard #46. On z900 systems, ICSF also supports the CDMF encryption mode. See “System Encryption Algorithm” on page 47 for more information. The Advanced Encryption Standard (AES) algorithm can also be used to encipher or decipher data or keys. The algorithm is documented in the Federal Information Processing Standard #192. | These services can be used to protect data. v Decipher Callable Service (CSNBDEC, CSNBDEC1, CSNEDEC and CSNEDEC1) The decipher callable service uses encrypted DES data-encrypting keys to decipher data. | | | | v Encipher Callable Service (CSNBENC, CSNBENC1, CSNEENC and CSNEENC1) | | | | | | | | | | The encipher callable service uses encrypted DES data-encrypting keys to encipher data. v Symmetric Algorithm Decipher Callable Service (CSNBSAD, CSNBSAD1, CSNESAD and CSNESAD1) The symmetric algorithm decipher callable service uses encrypted AES data-encrypting keys to decipher data. v Symmetric Algorithm Encipher Callable Service (CSNBSAE, CSNBSAE1, CSNESAE and CSNESAE1) The symmetric algorithm Encipher callable service uses encrypted AES data-encrypting keys to encipher data. | | | | | | | | v Symmetric Key Decipher Callable Service (CSNBSYD, CSNBSYD1, CSNESYD and CSNESYD1) The symmetric key decipher callable service uses clear and encrypted AES and DES data-encrypting keys to decipher data. v Symmetric Key Encipher Callable Service (CSNBSYE, CSNBSYE1, CSNESYE and CSNESYE1) The symmetric key encipher callable service uses clear and encrypted AES and DES data-encrypting keys to encipher data. | | 52 z/OS V1R13 ICSF Application Programmer's Guide Encoding and Decoding Data (CSNBECO, CSNEECO, CSNBDCO, and CSNEDCO) The encode and decode callable services perform functions with clear keys. Encode enciphers 8 bytes of data using the electronic code book (ECB) mode of the DES and a clear key. Decode does the inverse of the encode service. These services are available only on a DES-capable system. (See “System Encryption Algorithm” on page 49 for more information.) Translating Ciphertext (CSNBCTT or CSNBCTT1 and CSNECTT or CSNECTT1) Restriction: These services are only available on the IBM Eserver zSeries 900. ICSF also provides a ciphertext translate callable service. It deciphers encrypted data (ciphertext) under one encryption key and reenciphers it under another key without having the data appear in the clear outside the cryptographic feature. Such a function is useful in a multiple node network, where sensitive data is passed through multiple nodes prior to it reaching its final destination. Different nodes use different keys in the process. For more information about different nodes, see “Using the Ciphertext Translate Callable Service” on page 66. The keys cannot be used for the encipher and decipher callable services. (See “System Encryption Algorithm” on page 49 for more information.) Managing Data Integrity and Message Authentication To ensure the integrity of transmitted messages and stored data, ICSF provides: v Message authentication code (MAC) v Several hashing functions, including modification detection code (MDC), SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, RIPEMD-160 and MD5. (See Chapter 9, “Using Digital Signatures,” on page 511 for an alternate method of message authentication using digital signatures.) The choice of callable service 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, such as the modification detection code process. 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 may be in clear or encrypted form. The comparison is performed within the cryptographic feature. Since 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. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 53 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. ICSF provides support for both single-length and double-length MAC generation and MAC verification keys. With the ANSI X9.9-1 single key algorithm, use the single-length MAC and MACVER keys. ICSF provides support for the use of data-encrypting keys in the MAC generation and verification callable services, and also the use of a MAC generation key in the MAC verification callable service. This support permits ICSF MAC services to interface more smoothly with non-CCA key distribution system, including those implementing the ANSI X9.17 protocol. HMAC Generation Callable Service (CSNBHMG or CSNBHMG1 and CSNEHMG or CSNEHMG1) When a message is sent, an application program can generate an authentication code for it using the HMAC generation callable service. The callable service computes the message authentication code using FIPS-198 Keyed-Hash Message Authentication Code method. HMAC Verification Callable Service (CSNBHMV or CSNBHMV1 and CSNEHMV or CSNEHMV1) When the receiver gets the message, an application program calls the HMAC verification callable service. The callable service verifies a MAC by generating another MAC and comparing it with the MAC received with the message. If the two codes are the same, the message sent was the same one received. A return code indicates whether the MACs are the same. The MAC verification callable service can use FIPS-198 Keyed-Hash Message Authentication Code method. MAC Generation Callable Service (CSNBMGN or CSNBMGN1 and CSNEMGN or CSNEMGN1) When a message is sent, an application program can generate an authentication code for it using the MAC generation callable service. The callable service computes the message authentication code using one of these methods: v Using the ANSI X9.9-1 single key algorithm, a single-length MAC generation key or data-encrypting key, and the message text. v Using the ANSI X9.19 optional double key algorithm, a double-length MAC generation key and the message text. v Using Europay, MasterCard and Visa (EMV) padding rules with a single-length MAC key or double-length MAC key and the message text. v Using ISO 16609 algorithm with a double-length MAC or a double-length DATA key and the message text. ICSF allows a MAC to 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 message authentication code with the message text. MAC Verification Callable Service (CSNBMVR or CSNBMVR1 and CSNEMVR or CSNEMVR1) When the receiver gets the message, an application program calls the MAC verification callable service. The callable service verifies a MAC by generating another MAC and comparing it with the MAC received with the message. If the two 54 z/OS V1R13 ICSF Application Programmer's Guide codes are the same, the message sent was the same one received. A return code indicates whether the MACs are the same. The MAC verification callable service can use either of these methods to generate the MAC for authentication: v The ANSI 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 The ANSI X9.19 optional double key algorithm, a double-length MAC verification or MAC generation key and the message text. v Using Europay, MasterCard and Visa (EMV) padding rules with a single-length MAC key or double-length MAC key and the message text. v Using ISO 16609 algorithm with a double-length MAC or a double-length DATA key and the message text. The method used to verify the MAC should correspond with the method used to generate the MAC. Symmetric MAC Generate Callable Service (CSNBSMG, CSNBSMG1, CSNESMG and CSNESMG1) This service supports generating a MAC using a clear AES key. The algorithms supported are CBC-MAC and XCBC-MAC (AES-XCBC-MAC-96 and AES-XCBC-PRF-128) Symmetric MAC Verify Callable Service (CSNBSMV, CSNBSMV1, CSNESMV and CSNESMV1) This service supports verifying a MAC using a clear AES key. The algorithms supported are CBC-MAC and XCBC-MAC (AES-XCBC-MAC-96 and AES-XCBC-PRF-128) Hashing Functions Hashing functions include one-way hash generation and modification detection code (MDC) processing. One-Way Hash Generate Callable Service (CSNBOWH or CSNBOWH1 and CSNEOWH or CSNEOWH1) This service hashes a supplied message. Supported hashing methods include: v SHA-12 v SHA-224 v SHA-256 v SHA-384 v SHA-512 v RIPEMD-160 v MD5 MDC Generation Callable Service (CSNBMDG or CSNBMDG1 and CSNEMDG or CSNEMDG1) The modification detection code (MDC) provides a form of support for data integrity. The MDC allows you to verify that data was not altered during transmission or while in storage. The originator of the data ensures that the MDC is transmitted with integrity to the intended receiver of the data. For instance, the MDC could be published in a reliable source of public information. When the receiver gets the 2. The Secure Hash Algorithm (SHA) is also called the Secure Hash Standard (SHS), which Federal Information Processing Standard (FIPS) Publication 180 defines. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 55 data, an application program can generate an MDC, and compare it with the original MDC value. If the MDC values are equal, the data is accepted as unaltered. If the MDC values differ the data is assumed to be bogus. Supported hashing methods through the MDC generation callable service are: v MDC-2 v MDC-4 v PADMDC-2 v PADMDC-4 In a similar manner, MDCs can be used to ensure the integrity of data stored on the system or on removable media, such as tape. When data is sent, an application program can generate a modification detection code for it using the MDC generation callable service. The callable service computes the modification detection code by encrypting the data using a publicly-known cryptographic one-way function. The MDC is a 128-bit value that is easy to compute for specific data, yet it is hard to find data that will result in a given MDC. Once an MDC has been established for a file, the MDC generate service can be run at any other time on the file. The resulting MDC can then be compared with the previously established MDC to detect deliberate or inadvertent modification. Managing Personal Authentication 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. ICSF checks a customer-supplied PIN by verifying it using an algorithm. The financial industry needs functions to generate, translate, and verify PINs. These functions prevent unauthorized disclosures when organizations handle personal identification numbers. ICSF supports these 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 VISA PIN validation value v Interbank With ICSF, you can translate PIN blocks from one format to another. ICSF supports these formats: v ANSI X9.8 v ISO formats 0, 1, 2, 3 v VISA formats 1, 2, 3, 4 v IBM 4704 Encrypting PINPAD format v IBM 3624 formats v IBM 3621 formats v ECI formats 1, 2, 3 With the capability to translate personal identification numbers into different PIN block formats, you can use personal identification numbers on different systems. 56 z/OS V1R13 ICSF Application Programmer's Guide Verifying Credit Card Data The Visa International Service Association (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 VISA card-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 ICSF callable services generate and verify the CVV3 by the track-2 method. The VISA CVV generate callable service calculates a 1- 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 service verify callable service 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. Clear PIN Encrypt Callable Service (CSNBCPE and CSNECPE) To format a PIN into a PIN block format and encrypt the results, use the Clear PIN Encrypt callable service. You can also use this service to create an encrypted PIN block for transmission. With the RANDOM keyword, you can have the service generate random PIN numbers. Use of this service requires the optional PCIXCC, CEX2C, or CEX3C. An enhanced PIN security mode, on PCICC, PCIXCC, CEX2C, and CEX3C, is available for formatting an encrypted PIN block into IBM 3621 format or IBM 3624 format. See “Clear PIN Encrypt (CSNBCPE and CSNECPE)” on page 434 for more information. Clear PIN Generate Alternate Callable Service (CSNBCPA and CSNECPA) To generate a clear VISA PIN validation value from an encrypted PIN block, call the clear PIN generate alternate callable service. This service also supports the IBM-PINO algorithm to produce a 3624 offset from a customer selected encrypted PIN. An enhanced PIN security mode is available for extracting PINs from encrypted PIN blocks. This mode only applies on PCICC, PCIXCC, CEX2C, or CEX3C, when specifying a PIN-extraction method for an IBM 3621 or an IBM 3624 PIN-block. See “Clear PIN Generate Alternate (CSNBCPA and CSNECPA)” on page 442 for more information. Note: The PIN block must be encrypted under either an input PIN-encrypting key (IPINENC) or output PIN-encrypting key (OPINENC). Using an IPINENC key requires NOCV keys to be enabled in the CKDS. Functions other than VISA PIN validation value generation require the optional PCICC, PCIXCC, CEX2C, or CEX3C. Clear PIN Generate Callable Service (CSNBPGN and CSNEPGN) To generate personal identification numbers, call the Clear PIN generate callable service. Using a PIN generation algorithm, data used in the algorithm, and the PIN generation key, the callable service generates a clear PIN, a PIN verification value, or an offset. The callable service can only execute in special secure mode, which is described in “Special Secure Mode” on page 10. 3. The VISA CVV and the MasterCard CVC refer to the same value. CVV is used here to mean both CVV and CVC. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 57 | | | | | CVV Key Combine Callable Service (CSNBCKC and CSNECKC) | The callable service name for AMODE(64) is CSNECKC. This callable service combines 2 single-length CCA internal key tokens into 1 double-length CCA key token containing a CVVKEY-A key type. This combined double-length key satisfies current VISA requirements and eases translation between TR-31 and CCA formats for CVV keys. Encrypted PIN Generate Callable Service (CSNBEPG and CSNEEPG) To generate personal identification numbers, call the Encrypted PIN generation callable service. Using a PIN generation algorithm, data used in the algorithm, and the PIN generation key, the callable service generates a PIN and using a PIN block format and the PIN encrypting key, formats and encrypts the PIN. Use of this service requires the optional PCICC, PCIXCC, CEX2C, or CEX3C. An enhanced PIN security mode, on PCICC, PCIXCC, CEX2C, and CEX3C, is available for formatting an encrypted PIN block into IBM 3621 format or IBM 3624 format. See “Encrypted PIN Generate (CSNBEPG and CSNEEPG)” on page 453 for more information. Encrypted PIN Translate Callable Service (CSNBPTR and CSNEPTR) To translate a PIN from one PIN-encrypting key to another or from one PIN block format to another or both, call the Encrypted PIN translation callable service. You must identify the input PIN-encrypting key that originally enciphers the PIN. You also need to specify the output PIN-encrypting key that you want the callable service 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. An enhanced PIN security mode, on PCICC, PCIXCC, CEX2C, and CEX3C, is available for formatting an encrypted PIN block into IBM 3621 format or IBM 3624 format. The enhanced security mode is also 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. See “Encrypted PIN Translate (CSNBPTR and CSNEPTR)” on page 458 for more information. Encrypted PIN Verify Callable Service (CSNBPVR and CSNEPVR) To verify a supplied PIN, call the Encrypted PIN verify callable service. You need to specify the supplied enciphered PIN, the PIN-encrypting key that enciphers it, and other relevant data. You must also specify the PIN verification key and PIN verification algorithm. It compares the two personal identification numbers; if they are the same, it verifies the supplied PIN. See Chapter 8, “Financial Services,” on page 423 for additional information. An enhanced PIN security mode, on PCICC, PCIXCC, CEX2C, and 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. See “Encrypted PIN Verify (CSNBPVR and CSNEPVR)” on page 466 for more information. PIN Change/Unblock Callable Service (CSNBPCU and CSNEPCU) To support PIN change algorithms specified in the VISA Integrated Circuit Card Specification, call the PIN change/unblock callable service. The service can be executed on z890/z990 and later machines. An enhanced PIN security mode, on PCICC, PCIXCC, CEX2C, and CEX3C, is available for extracting PINs from encrypted PIN blocks. This mode only applies 58 z/OS V1R13 ICSF Application Programmer's Guide when specifying a PIN-extraction method for an IBM 3621 or an IBM 3624 PIN-block. See “PIN Change/Unblock (CSNBPCU and CSNEPCU)” on page 473 for more information. Transaction Validation Callable Service (CSNBTRV and CSNETRV) To support generation and validation of American Express card security codes, call the transaction validation callable service. The service can be executed on z890/z990 and later machines. | ANSI TR-31 key block support | | | | | | | | A TR-31 key block is a format defined by the American National Standards Institute (ANSI) to support the interchange of keys in a secure manner with key attributes included in the exchanged data. The TR-31 key block format has a set of defined key attributes that are securely bound to the key so that they can be transported together between any two systems that both understand the TR-31 format. ICSF enables applications to convert a CCA token to a TR-31 key block for export to another party, and to convert an imported TR-31 key block to a CCA token. This enables you to securely exchange keys and their attributes with non-CCA systems. | | | | | | | Although there is often a one-to-one correspondence between TR-31 key attributes and the attributes defined by CCA, there are also cases where the correspondence is many-to-one or one-to-many. Because there is not always a one-to-one mapping between the key attributes defined by TR-31 and those defined by CCA, the TR-31 Export callable service and the TR-31 Import callable service provide rule array keywords that enable an application to specify the attributes to attach to the exported or imported key. | | | | | | The TR-31 key block format defines a header section. The header contains metadata about the key, including its usage attributes. The header can also be extended with optional blocks, which can either have standardized content or proprietary information. Callable services are also provided for retrieving standard header or optional block information from a TR-31 key block without importing the key and for building an optional block. | | | The TR-31 key block support requires a z196 with a CEX3C and the the Sept. 2011 or later LIC. Only DES/TDES keys can be transported in TR-31 key blocks. There is no support for transporting AES keys. | | | | | | | | | | TR-31 Export Callable Service (CSNBT31X and CSNET31X) The TR-31 Export callable service converts a CCA token to TR-31 format for export to another party. Since there is not always a one-to-one mapping between the key attributes defined by TR-31 and those defined by CCA, the caller may need to specify the attributes to attach to the exported key through the rule array. TR-31 Import Callable Service (CSNBT31I and CSNET31I) The TR-31 Import callable service converts a TR-31 key block to a CCA token. Since there is not always a one-to-one mapping between the key attributes defined by TR-31 and those defined by CCA, the caller may need to specify the attributes to attach to the imported key through the rule array. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 59 | TR-31 Parse Callable Service (CSNBT31P and CSNET31P) The TR-31 Parse callable service retrieves standard header information from a TR-31 key block without importing the key. This callable service can be used with the TR-31 Optional Data Read callable service to obtain both the standard header fields and any optional data blocks from the key block. | | | | | | TR-31 Optional Data Read Callable Service (CSNBT31R and CSNET31R) A TR-31 key block can hold optional fields which are securely bound to the key block using the integrated MAC. The optional blocks may either contain information defined in the TR-31 standard, or they may contain proprietary data. A separate range of optional block identifiers is reserved for use with proprietary blocks. Applications can call the TR-31 Optional Data Read callable service to obtain lists of the optional block identifiers and optional block lengths, and to obtain the data for a particular optional block. This callable service is often used in conjunction with the TR-31 Parse Callable Service which can be used to determine the number of optional blocks in the TR-31 token. | | | | | | | | | | | TR-31 Optional Data Build Callable Service (CSNBT31O and CSNET31O) The TR-31 Optional Data Build callable service constructs the optional block data structure for a TR-31 key block. It builds the structure by adding one optional block with each call, until your entire set of optional blocks have been added. With each call, the application program provides a single optional block by specifying its ID, its length, and its data. Each subsequent call appends the current optional block to any pre-existing blocks. | | | | | | Secure Messaging These services will assist applications in encrypting secret information such as clear keys and PIN blocks in a secure message. These services will execute within the secure boundary of the PCICC, PCIXCC, CEX2C, or CEX3C. The Secure Messaging for Keys callable service encrypts a text block, including a clear key value decrypted from an internal or external DES token. The Secure Messaging for PINs callable service encrypts a text block, including a clear PIN block recovered from an encrypted PIN block. Trusted Key Entry (TKE) Support The Trusted Key Entry (TKE) workstation is an optional feature. It offers an alternative to clear key entry. You can use the TKE workstation to load: v DES master key, AES master key, PKA master keys, and operational keys in a secure way. CCF only supports Operational Transport and PIN keys. On the PCIXCC/CEX2C, all operational keys may be loaded with TKE V4.1 or higher. AES master key and AES operational keys may be loaded with TKE V5.3. On the CEX3C, all operational keys may be loaded with TKE 6.0 or later. v DES-MK and ASYM-MK master keys on the PCICC, PCIXCC, CEX2C, or CEX3C. v AES master keys are only on z9 and z10 systems running with the Nov. 2008 or later licensed internal code (LIC). 60 z/OS V1R13 ICSF Application Programmer's Guide You can load keys remotely and for multiple PCICCs, PCIXCCs, CEX2Cs, or CEX3Cs. The TKE workstation eases the administration for using one Cryptographic Coprocessor Feature or PCIXCC/CEX2C/CEX3C 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/disabling access control points for callable services executed on PCICCs, PCIXCCs, CEX2Cs, and CEX3Cs. See Appendix H, “Access Control Points and Callable Services,” on page 893 for additional information. For complete details about the TKE workstation see z/OS Cryptographic Services ICSF TKE Workstation User's Guide. TKE Version 4.0 or higher is required if using a PCIXCC/CEX2C. TKE Version 6.0 or higher is required is using a CEX3C. On z890, z990 z9 EC, z9 BC, z10 EC and z10 BC systems running with May 2004 or higher version of Licensed Internal Code or an z9 EC, z9 BC, z10 EC and z10 BC with MCL 029 Stream J12220 or higher of Licensed Internal Code, you must enable TKE commands for each PCIXCC/CEX2C/CEX3C card from the Support Element. This is true for new TKE users and those upgrading from TKE V4.0 to V4.1, V4.2 or V5.x when the new LIC is installed. See Support Element Operations Guide and z/OS Cryptographic Services ICSF TKE Workstation User's Guide, SA23-2211 for more information. Utilities ICSF provides these utilities. Character/Nibble Conversion Callable Services (CSNBXBC and CSNBXCB) The character/nibble conversion callable services are utilities that convert a binary string to a character string and vice versa. Code Conversion Callable Services (CSNBXEA and CSNBXAE) The code conversion callable services are utilities that convert EBCDIC data to ASCII data and vice versa. X9.9 Data Editing Callable Service (CSNB9ED) The data editing callable service is a utility that edits an ASCII text string according to the editing rules of ANSI X9.9-4. ICSF Query Algorithm Callable Service (CSFIQA) The callable service provides information regarding the cryptographic and hash algorithms available. ICSF Query Facility Callable Service (CSFIQF) The callable service provides ICSF status information, as well as PCICC, PCIXCC, CEX2C, and CEX3C information. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 61 Typical Sequences of ICSF Callable Services Sample sequences in which the ICSF callable services might be called are shown in Table 5. Table 5. Combinations of the Callable Services Combination A (DATA keys only) 1. Random number generate 2. Clear key import or multiple clear key import 3. Encipher/decipher 4. Data key export or key export (optional step) Combination B 1. Random number generate 2. Secure key import or multiple secure key import 3. Any service 4. Data key export for DATA keys, or key export in the general case (optional step) Combination C Combination D 1. Key generate (OP form only) 2. Any service 3. Key export (optional) 1. Key generate (OPEX form) 2. Any service Combination E 1. 2. 3. 4. Key Key Any Key Combination F generate (IM form only) import service export (optional) 1. Key generate (IMEX form) 2. Key import 3. Any service Combination G 1. 2. 3. 4. Combination H Key generate Key record create Key record write Any service (passing label of the key just generated) 1. 2. 3. 4. Key import Key record create Key record write Any service (passing label of the key just generated) Combination I 1. Key token build to create key token skeleton 2. Key generate to OP form of AKEK using key token skeleton 3. Use AKEK in any ANSI X9.17 service Notes: 1. An example of “any service” is CSNBENC. 2. These combinations exclude services that can be used on their own; for example, key export or encode, or using key generate to generate an exportable key. 3. These combinations do not show key communication, or the transmission of any output from an ICSF callable service. 4. Combination I is not available on the IBM Eserver zSeries 990. The key forms are described in “Key Generate (CSNBKGN and CSNEKGN)” on page 135. 62 z/OS V1R13 ICSF Application Programmer's Guide Key Forms and Types Used in the Key Generate Callable Service The key generate callable service is the most complex of all the ICSF callable services. This topic provides examples of the key forms and key types used in the key generate callable service. Generating an Operational Key To generate an operational key, choose one of these methods: v For operational keys, call the key generate callable service (CSNBKGN). Table 33 on page 144 and Table 34 on page 144 show the key type and key form combinations for a single key and for a key pair. v For operational keys, call the random number generate callable service (CSNBRNG) and specify the form parameter as RANDOM. Specify ODD parity for a random number you intend to use as a key. Then pass the generated value to the secure key import callable service (CSNBSKI) with a required key type. The required key type is now in operational form. This method requires a cryptographic unit to be in special secure mode. For more information about special secure mode, see “Special Secure Mode” on page 10. v For data-encrypting keys, call the random number generate callable service (CSNBRNG) and specify the form parameter as ODD. Then pass the generated value to the clear key import callable service (CSNBCKI) or the multiple clear key import callable service (CSNBCKM). The DATA key 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 callable service (CSNBKGN). 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 callable service (CSNBKGN). 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 Form OP Key 1 DATA Encipher or decipher data. Use data key export or key export to send encrypted key to another cryptographic partner. Then communicate the ciphertext. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 63 OP IM EX MAC MAC generate. Because no MACVER key exists, there is no secure communication of the MAC with another cryptographic partner. DATA Key Import, and then encipher or decipher. Then key export to communicate ciphertext and key with another cryptographic partner. 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. 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 Form Type Type 1 2 OPIM DATA DATA OPIM MAC MAC 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. Single-length MAC generation key. Use the OP form in MAC generation. You have no corresponding MACVER key, but you can call the MAC verification service with the MAC key directly. Use the key import callable service and then compute the MAC again using the MAC verification callable service, 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 Form Type 1 Type 2 OPEX DATA DATA OPEX OPEX OPEX OPEX OPEX 64 Use the OP form in encipher. Send the EX form and the ciphertext to another cryptographic partner. MAC MAC Single-length MAC generation key. Use the OP form in both MAC generation and MAC verification. Send the EX form to a cryptographic partner to be used in the MAC generation or MAC verification services. MAC MACVER Single-length MAC generation and MAC verification keys. Use the OP form in MAC generation. Send the EX form to a cryptographic partner where it will be put into key import, and then MAC verification, with the message and MAC that you have also transmitted. 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. IMPORTER EXPORTER Use the OP form in key import, key generate, or secure key import. 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 CKDS. EXPORTER IMPORTER Use the OP form in key export, data key export, z/OS V1R13 ICSF Application Programmer's Guide or key generate. Send the EX form to a cryptographic partner where it is put into the CKDS or used in key import, key generate or secure key import. 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” on page 64 installed, you can start key and data exchange. Examples of IMEX Single-Length and Double-Length Keys in Two Forms Key Form Type 1 Type 2 IMEX DATA DATA Use the key import callable service 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 callable service 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 callable service 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 callable service 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 this 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 Form EXEX EXEX EXEX EXEC Type 1 DATA MAC IMPORTER OPINENC Type 2 DATA MACVER EXPORTER IPINENC Send the first EX form to a cryptographic partner with the corresponding IMPORTER and send the second EX form to another cryptographic partner with the corresponding IMPORTER. This exchange establishes a key between two partners. Generating AKEKs Restriction: AKEKs are only supported on the IBM Eserver zSeries 800 and the IBM Eserver zSeries 900. AKEKs are bidirectional and are OP-form-only keys that can be used in both import and export. Prior to using the key generate callable service to create an AKEK, you need to use the key token build callable service to create a key token for receiving the AKEK. The steps involved in this process are: 1. Use the key token build callable service with these parameter values: Parameter Value Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 65 Key_type AKEK Rule_array INTERNAL NO-KEY {SINGLE or DOUBLE-O} 2. Use the key generate callable service with these parameter values: Parameter Value Key_form OP Key_type_1 TOKEN Generated_key_identifier_1 The skeleton key token created in step 1 Using the Ciphertext Translate Callable Service Restriction: The ciphertext translate callable service does not work in CDMF-only systems (see “System Encryption Algorithm” on page 49). The ciphertext translate callable service does not work on the PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor. This topic describes a scenario using the encipher, ciphertext translate, and decipher callable services with four network nodes: A, B, C, and D. You want to send data from your network node A to a destination node D. You cannot communicate directly with node D, and nodes B and C are situated between you. You do not want nodes B and C to decipher your data. At node A, you use the Encipher callable service. Node D uses the Decipher callable service. Node B and C will use the ciphertext translate callable service. Consider the keys that are needed to support this process: 1. At your node, generate one key in two forms: OPEX DATA DATAXLAT 2. Send the exportable DATAXLAT key to node B. 3. Node B and C need to share a DATAXLAT key, so generate a different key in two forms: EXEX DATAXLAT DATAXLAT. 4. Send the first exportable DATAXLAT key to node B. 5. Send the second exportable DATAXLAT key to node C. 6. Node C and node D need to share a DATAXLAT key and a DATA key. Node D can generate one key in two forms: OPEX DATA DATAXLAT. 7. Node D sends the exportable DATAXLAT key to node C. The communication process is shown as: Node: A Callable Service: Encipher Keys: DATA B C Ciphertext Translate DATAXLAT Key Pairs: |____ = ____| DATAXLAT D Ciphertext Translate DATAXLAT |____ = ____| DATAXLAT Decipher DATA |____ = ____| Therefore, you need three keys, each in two different forms. You can generate two of the keys at node A, and node D can generate the third key. Note that the key used in the decipher callable service at node D is not the same key used in the encipher callable service at node A. 66 z/OS V1R13 ICSF Application Programmer's Guide Summary of Callable Services Table 6 lists the callable services described in this publication, and their corresponding verbs. The figure also references the topic that describes the callable service. Table 6. Summary of ICSF Callable Services Verb Service Name Function Chapter 5, “Managing Symmetric Cryptographic Keys” | | | | | | CSNBCKI CSNECKI Clear key import Imports an 8-byte clear DATA key, enciphers it under the master key, and places the result into an internal key token. CSNBCKI converts the clear key into operational form as a DATA key. CSNBCVG CSNECVG Control vector generate Builds a control vector from keywords specified by the key_type and rule_array parameters. CSNBCVT CSNECVT Control vector translate Changes the control vector used to encipher an external key. CSNBCVE CSNECVE Cryptographic variable encipher Uses a CVARENC key to encrypt plaintext by using the Cipher Block Chaining (CBC) method. The plaintext must be a multiple of eight bytes in length. CSNBDKX CSNEDKX Data key export Converts a DATA key from operational form into exportable form. CSNBDKM CSNEDKM Data key import Imports an encrypted source DES single- or double-length DATA key and creates or updates a target internal key token with the master key enciphered source key. CSNBDKG CSNEDKG Diversified key generate Generates a key based upon the key-generating key, the processing method, and the parameter data that is supplied. CSNBEDH CSNEEDH ECC Diffie-Hellman Creates symmetric key material from a pair of ECC keys using the Elliptic Curve Diffie-Hellman protocol and the static unified model key agreement scheme or “Z” data (the “secret” material output from D-H process). CSNBKEX CSNEKEX Key export Converts any key from operational form into exportable form. (However, this service does not export a key that was marked non-exportable when it was imported.) CSNBKGN CSNEKGN Key generate Generates a 64-bit, 128-bit, or 192-bit odd parity key, or a pair of keys; and returns them in encrypted forms (operational, exportable, or importable). CSNBKGN does not produce keys in plaintext. CSNBKGN2 CSNEKGN2 Key generate2 Generates a variable-length HMAC or AES key or a pair of keys; and returns them in encrypted forms (operational, exportable, or importable). CSNBKIM CSNEKIM Key import Converts any key from importable form into operational form. CSNBKPI CSNEKPI Key part import Combines the clear key parts of any key type and returns the combined key value in an internal key token or an update to the CKDS. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 67 Table 6. Summary of ICSF Callable Services (continued) | | Verb Service Name Function CSNBKPI2 CSNEKPI2 Key part import2 Combines the clear key parts of an HMAC or AES key and returns the combined key value in an internal key token or an update to the CKDS. CSNBKYT CSNEKYT CSNBKYTX CSNEKYTX Key test Generates or verifies (depending on keywords in the rule array) a secure verification pattern for keys. CSNBKYT and CSNEKYT require the tested key to be in the clear or encrypted under the master key. CSNBKYTX and CSNEKYTX also allow the tested key to be encrypted under a key-encrypting key. CSNBKYT2 CSNEKYT2 Key test2 Generates or verifies (depending on keywords in the rule array) a secure verification pattern for keys. CSNBKYT2 and CSNEKYT2 allow the tested key to be in the clear or encrypted under the master key or a key-encrypting key. CSNBKTB CSNEKTB Key token build Builds an internal or external token from the supplied parameters. You can use this callable service to build an internal token for an AKEK for input to the key generate and key part import callable services. You can also use this service to build CCA key tokens for all key types ICSF supports. You can also use this service to build CCA key tokens for all key types ICSF supports. CSNBKTB2 CSNEKTB2 Key token build2 Builds an internal clear key or skeleton token from the supplied parameters. You can use this callable service to build an internal clear key token for any key type for input to the key test2 callable service. You can use this callable service to build a skeleton token for input to the key generate2 and key part import2 callable services. CSNBKTR CSNEKTR Key translate Uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment. CSNBKTR2 CSNEKTR2 Key translate2 Uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment. CSNBCKM CSNECKM Multiple clear key import Imports a single-, double-, or triple-length clear DATA key, enciphers it under the master key, and places the result into an internal key token. CSNBCKM converts the clear key into operational form as a DATA key. | 68 z/OS V1R13 ICSF Application Programmer's Guide Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNBSKM CSNESKM Multiple secure key import Enciphers a single-, double-, or triple-length clear key under the master key or an input importer key, and places the result into an internal or external key token as any key type. Triple-length keys can only be imported as DATA keys. This service executes only in special secure mode. CSNDPKD CSNFPKD PKA decrypt Uses an RSA private key to decrypt the RSA-encrypted key value and return the clear key value to the application. CSNDPKE CSNFPKE PKA encrypt Encrypts a supplied clear key value under an RSA public key. CSNBPEX CSNEPEX Prohibit export Modifies an operational key so that it cannot be exported. CSNBPEXX CSNEPEXX Prohibit export extended Changes the external token of a key in exportable form so that it can be imported at the receiver node but not exported from that node. CSNBRKA CSNERKA Restrict Key Attribute Modifies an operational variable-length key so that it cannot be exported. CSNBRNG CSNERNG CSNBRNGL CSNERNGL Random number generate Generates an 8-byte random number or a random number with a user-specified length. The output can be specified in three forms of parity: RANDOM, ODD, and EVEN. CSNDRKX CSNFRKX Remote key export Generates or exports DES keys for local use and for distribution to an ATM or other remote device. RKX uses a special structure to hold encrypted symmetric keys in a way that binds them to the trusted block and allows sequences of RKX calls to be bound together as if they were an atomic operation. CSNBSKI CSNESKI Secure key import Enciphers a clear key under the master key, and places the result into an internal or external key token as any key type. This service executes only in special secure mode. | | CSNBSKI2 CSNESKI2 Secure key import2 Enciphers a variable-length clear HMAC or AES key under the master key and places the result into an internal key token. This service executes only in special secure mode. CSNDSYX CSNFSYX | | Symmetric key export Transfers an application-supplied symmetric key from encryption under the host master key to encryption under an application-supplied RSA public key or AES EXPORTER key. The application-supplied key must be an internal key token or the label in the CKDS of a DES DATA, AES DATA, or variable-length symmetric key token. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 69 Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNDSYG CSNFSYG Symmetric key generate Generates a symmetric DATA key and returns the key in two forms: enciphered under the DES master key or KEK and under a PKA public key. CSNDSYI CSNFSYI Symmetric key import Imports a symmetric key enciphered under an RSA public key into operational form enciphered under a host master key. CSNDSYI2 CSNFSYI2 Symmetric key import2 Imports a symmetric key enciphered under an RSA public key or AES EXPORTER key into operational form enciphered under a host master key. CSNBTCK CSNETCK Transform CDMF key Changes a CDMF DATA key in an internal or external token to a transformed shortened DES key. CSNDTBC CSNETBC Trusted block create Creates a trusted block in a two step process. The block will be in external form, encrypted under an IMP-PKA transport key. This means that the MAC key contained within the trusted block will be encrypted under the IMP-PKA key. | | CSNBT31X CSNET31X TR-31 Export Converts a CCA token to TR-31 format for export to another party. | | CSNBT31I CSNET31I TR-31 Import Converts a TR-31 key block to a CCA token. | | CSNBT31P CSNET31P TR-31 Parse Retrieves standard header information from a TR-31 key block without importing the key. | | | CSNBT31R CSNET31R TR-31 Optional Data Read Obtains lists of the optional block identifiers and optional block lengths, and obtains the data for a particular optional block. | | CSNBT31O CSNET31O TR-31 Optional Data Build Constructs the optional block data structure for a TR-31 key block. CSFUDK CSFUDK6 User Derived Key Generates single-length or double-length MAC keys, or updates an existing user derived key. | Chapter 6, “Protecting Data” CSNBCTT CSNECTT CSNBCTT1 CSNECTT1 Ciphertext translate Translates the user-supplied ciphertext from one key and enciphers the ciphertext to another key. (This is for DES encryption only.) CSNBCTT and CSNECTT require the ciphertext to reside in the caller's primary address space. CSNBCTT1 and CSNECCT1 allow the ciphertext to reside in the caller's primary address space or in a z/OS data space. 70 z/OS V1R13 ICSF Application Programmer's Guide Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNBDEC CSNEDEC CSNBDEC1 CSNEDEC1 Decipher Deciphers data using either the CDMF or the cipher block chaining mode of the DES. (The method depends on the token marking or keyword specification.) The result is called plaintext. CSNBDEC and CSNEDEC require the plaintext and ciphertext to reside in the caller's primary address space. CSNBDEC1 and CSNEPEC1 allow the plaintext and ciphertext to reside in the caller's primary address space or in a z/OS data space. CSNBDCO CSNEDCO Decode Decodes an 8-byte string of data using the electronic code book mode of the DES. (This is for DES encryption only.) CSNBENC CSNEENC CSNBENC1 CSNEENC1 Encipher Enciphers data using either the CDMF or the cipher block chaining mode of the DES. (The method depends on the token marking or keyword specification.) The result is called ciphertext. CSNBENC and CSNEENC require the plaintext and ciphertext to reside in the caller's primary address space. CSNBENC1 and CSNEENC1 allow the plaintext and ciphertext to reside in the caller's primary address space or in a z/OS data space. CSNBECO CSNEECO Encode Encodes an 8-byte string of data using the electronic code book mode of the DES. (This is for DES encryption only.) CSNBSAD CSNESAD CSNBSAD1 CSNESAD1 Symmetric algorithm decipher Deciphers data using the AES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. CSNBSAD and CSNESAD require the plaintext and ciphertext to reside in the caller's primary address space. CSNBSAD1 and CSNESAD1 allows the plaintext and ciphertext to reside in the caller's primary address space or in a z/OS data space. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 71 Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNBSAE CSNESAE CSNBSAE1 CSNESAE1 Symmetric algorithm encipher Enciphers data using the AES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. CSNBSAE and CSNESAE require the plaintext and ciphertext to reside in the caller's primary address space. CSNBSAE1 and CSNESAE1 allows the plaintext and ciphertext to reside in the caller's primary address space or in a z/OS data space. CSNBSYD CSNBSYD1 CSNESYD CSNESYD1 Symmetric key decipher Deciphers data using the AES or DES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. Only clear keys are supported. CSNBSYD and CSNESYD require the plaintext and ciphertext to reside in the caller's primary address space. CSNBSYD1 and CSNESYD1 allow the plaintext and ciphertext to reside in the caller's primary address space or in a z/OS data space. CSNBSYE CSNBSYE1 CSNESYE CSNESYE1 Symmetric key encipher Enciphers data using the AES or DES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. Only clear keys are supported. CSNBSYE and CSNESYE require the plaintext and ciphertext to reside in the caller's primary address space. CSNBSYE1 and CSNESYE1 allows the plaintext and ciphertext to reside in the caller's primary address space or in a z/OS data space. Chapter 7, “Verifying Data Integrity and Authenticating Messages” CSNBHMG CSNEHMG CSNBHMG1 CSNEHMG1 HMAC generation Generates message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the FIPS-198 Keyed-Hash Message Authentication Code algorithm. CSNBHMG and CSNEHMG require data to reside in the caller’s primary address space. CSNBHMG1 and CSNEHMG1 allow data to reside in the caller’s primary address space or in a z/OS data space. 72 z/OS V1R13 ICSF Application Programmer's Guide Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNBHMV CSNEHMV CSNBHMV1 CSNEHMV1 HMAC verification Verifies message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the FIPS-198 Keyed-Hash Message Authentication Code algorithm. CSNBHMV and CSNEHMV requires data to reside in the caller’s primary address space. CSNBHMV1 and CSNEHMV1 allows data to reside in the caller’s primary address space or in a z/OS data space. CSNBMGN CSNEMGN CSNBMGN1 CSNEMGN1 MAC generate Generates a 4-, 6-, or 8-byte message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the ANSI X9.9-1 algorithm, ANSI X9.19 optional double key algorithm the EMV padding rules or the ISO 16609 TDES algorithm. CSNBMGN and CSNEMGN require data to reside in the caller's primary address space. CSNBMGN1 and CSNEMGN1 allow data to reside in the caller's primary address space or in a z/OS data space. CSNBMVR CSNEMVR CSNBMVR1 CSNEMVR1 MAC verify Verifies a 4-, 6-, or 8-byte message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the ANSI X9.9-1 algorithm, ANSI X9.19 optional double key algorithmthe EMV padding rules or the ISO 16609 TDES algorithm. CSNBMVR and CSNEMVR require data to reside in the caller's primary address space. CSNBMVR1 and CSNEMVR1 allow data to reside in the caller's primary address space or in a z/OS data space. CSNBMDG CSNEMDG CSNBMDG1 CSNEMDG1 MDC generate Generates a 128-bit modification detection code (MDC) for a text string that the application program supplies. CSNBMDG and CSNEMDG require data to reside in the caller's primary address space. CSNBMDG1 and CSNEMDG1 allow data to reside in the caller's primary address space or in a z/OS data space. CSNBOWH CSNEOWH CSNBOWH1 CSNEOWH1 One way hash generate Generates a one-way hash on specified text. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 73 Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNBSMG, CSNESMG CSNBSMG1 CSNESMG1 Symmetric MAC Generate Use the symmetric MAC generate callable service to generate a 96- or 128-bit message authentication code (MAC) for an application-supplied text string using a clear AES key. CSNBSMG1 allows data to reside in the caller's primary address space or in a z/OS data space. CSNBSMV, CSNESMV CSNBSMV1 CSNESMV1 Symmetric MAC Verify Use the symmetric MAC verify callable service to verify a 96- or 128-bit message authentication code (MAC) for an application-supplied text string using a clear AES key. CSNBSMV1 allows data to reside in the caller's primary address space or in a z/OS data space. Chapter 8, “Financial Services” CSNBCPE CSNECPE Clear PIN encrypt Formats a PIN into a PIN block format and encrypts the results. CSNBPGN CSNEPGN Clear PIN generate Generates a clear personal identification number (PIN), a PIN verification value (PVV), or an offset using one of these algorithms: IBM 3624 (IBM-PIN or IBM-PINO) IBM German Bank Pool (GBP-PIN or GBP-PINO) VISA PIN validation value (VISA-PVV) Interbank PIN (INBK-PIN) This service executes only in special secure mode. | | | CSNBCPA CSNECPA Clear PIN generate alternate Generates a clear VISA PIN validation value (PVV) from an input encrypted PIN block. The PIN block may have been encrypted under either an input or output PIN encrypting key. The IBM-PINO algorithm is supported to produce a 3624 offset from a customer selected encrypted PIN. CSNBCKC CSNECKC CVV Key Combine Combines two single-length CCA internal key tokens into 1 double-length CCA key token containing a CVVKEY-A key type. CSNBEPG CSNEEPG Encrypted PIN generate Generates and formats a PIN and encrypts the PIN block. CSNBPTR CSNEPTR Encrypted PIN translate Reenciphers a PIN block from one PIN-encrypting key to another and, optionally, changes the PIN block format. UKPT keywords are supported. 74 z/OS V1R13 ICSF Application Programmer's Guide Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNBPVR CSNEPVR Encrypted PIN verify Verifies a supplied PIN using one of these algorithms: IBM 3624 (IBM-PIN or IBM-PINO) IBM German Bank Pool (GBP-PIN or GBP-PINO) VISA PIN validation value (VISA-PVV) Interbank PIN (INBK-PIN) UKPT keywords are supported. CSNBPCU CSNEPCU PIN Change/Unblock Supports the PIN change algorithms specified in the VISA Integrated Circuit Card Specification; only available on a z890 or Requires May 2004 or later version of Licensed Internal Code (LIC). CSNBSKY CSNESKY Secure messaging for keys Encrypts a text block, including a clear key value decrypted from an internal or external DES token. CSNBSPN CSNESPN Secure messaging for PINs Encrypts a text block, including a clear PIN block recovered from an encrypted PIN block. CSNDSBC CSNFSBC SET block compose Composes the RSA-OAEP block and the DES-encrypted block in support of the SET protocol. CSNDSBD CSNFSBD SET block decompose Decomposes the RSA-OAEP block and the DES-encrypted block to provide unencrypted data back to the caller. CSNBTRV CSNETRV Transaction Validation Supports the generation and validation of American Express card security codes; only available on a z890 or Requires May 2004 or later version of Licensed Internal Code (LIC). CSNBCSG CSNECSG VISA CVV service generate Generates a VISA Card Verification Value (CVV) or a MasterCard Card Verification Code (CVC). CSNBCSV CSNECSV VISA CVV service verify Verifies a VISA Card Verification Value (CVV) or a MasterCard Card Verification Code (CVC). Chapter 11, “Key Data Set Management” | CSNBKRC CSNEKRC CKDS key record create Adds a key record containing a key token set to binary zeros to both the in-storage and DASD copies of the CKDS. | CSNBKRC2 CSNEKRC2 CKDS key record create2 Adds a key record containing a key token to both the in-storage and DASD copies of the CKDS. | CSNBKRD CSNEKRD CKDS key record delete Deletes a key record from both the in-storage and DASD copies of the CKDS. | CSNBKRR CSNEKRR CKDS key record read Copies an internal key token from the in-storage copy of the CKDS to application storage. | CSNBKRR2 CSNEKRR2 CKDS key record read2 Copies an internal key token from the in-storage copy of the CKDS to application storage. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 75 Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function | CSNBKRW CSNEKRW CKDS key record write Writes an internal key token to the CKDS record specified in the key label parameter. Updates both the in-storage and DASD copies of the CKDS currently in use. | CSNBKRW2 CSNEKRW2 CKDS key record write2 Writes an internal key token to the CKDS record specified in the key label parameter. Updates both the in-storage and DASD copies of the CKDS currently in use. | | | | | | | CSFCRC CSFCRC6 Coordinated KDS Administration Performs a CKDS refresh or CKDS reencipher and change master key operation while allowing applications to update the CKDS. In a sysplex environment, this callable service performs a coordinated sysplex-wide refresh or change master key operation from a single ICSF instance. CSNBXBC or CSNBXCB Character/nibble conversion Converts a binary string to a character string or vice versa. CSNBXEA or CSNBXAE Code conversion Converts EBCDIC data to ASCII data or vice versa. CSFIQA CSFIQA6 ICSF Query Algorithm Use this utility to retrieve information about the cryptographic and hash algorithms available. You can control the amount of data that is returned by passing in different rule_array keywords. CSFIQF CSFIQF6 ICSF Query Service Provides ICSF status, as well as PCICC, PCIXCC, CEX2C, and CEX3C information. CSNB9ED X9.9 data editing Edits an ASCII text string according to the editing rules of ANSI X9.9–4. Chapter 12, “Utilities” Chapter 13, “Trusted Key Entry Workstation Interfaces” CSFPCI PCI interface Puts a request to a specific PCI Cryptographic Coprocessor / PCI X Cryptographic Coprocessor / Crypto Express2 Coprocessor / Crypto Express3 Coprocessor queue and removes the corresponding response when complete. Only the Trusted Key Entry (TKE) workstation uses this service. CSFPKSC PKSC interface Puts a request to a specific cryptographic module and removes the corresponding response when complete. Only the Trusted Key Entry (TKE) workstation uses this service. Chapter 14, “Managing Keys According to the ANSI X9.17 Standard” CSNAEGN CSNGEGN ANSI X9.17 EDC generate Generates an ANSI X9.17 error detection code on an arbitrary length string using the special MAC key (x'0123456789ABCDEF'). CSNAKEX CSNGKEX ANSI X9.17 key export Uses the ANSI X9.17 protocol to export a DATA key or a pair of DATA keys with or without an AKEK. Supports the export of a CCA IMPORTER or EXPORTER KEK. Converts a single DATA key or combines two DATA keys into a single MAC key. 76 z/OS V1R13 ICSF Application Programmer's Guide Table 6. Summary of ICSF Callable Services (continued) Verb Service Name Function CSNAKIM CSNGKIM ANSI X9.17 key import Uses the ANSI X9.17 protocol to import a DATA key or a pair of DATA keys with or without an AKEK. Supports the import of a CCA IMPORTER or EXPORTER KEK. Converts a single DATA key or combines two DATA keys into a single MAC key. CSNAKTR CSNGKTR ANSI X9.17 key translate Uses the ANSI X9.17 protocol to translate, in a single service call, either one or two DATA keys or a single KEK from encryption under one AKEK to encryption under another AKEK. Converts a single DATA key or combines two DATA keys into a single MAC key. CSNATKN CSNGTKN ANSI X9.17 transport key partial notarize Permits the preprocessing of an AKEK with origin and destination identifiers to create a partially notarized AKEK. Chapter 2. Introducing Symmetric Key Cryptography and Using Symmetric Key Callable Services 77 78 z/OS V1R13 ICSF Application Programmer's Guide Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services The preceding topic focused on DES cryptography or secret-key cryptography. This 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 PKA support to exchange symmetric secret keys securely and to compute digital signatures for authenticating messages to users. You can also use public key cryptography in support of secure electronic transactions over open networks, using SET protocols. PKA Key Algorithms Public key cryptography uses a key pair consisting of a public key and a private key. The PKA public key uses one of the following algorithms: v Rivest-Shamir-Adleman (RSA) The RSA algorithm 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, this operation recovers cleartext from ciphertext: cleartext = ciphertextPR (modulo M) An RSA key consists of an exponent and a modulus. The private exponent must be secret, but the public exponent and modulus need not be secret. v Digital Signature Standard (DSS) The U.S. National Institute of Standards and Technology (NIST) defines DSS in Federal Information Processing Standard (FIPS) Publication 186. v Elliptic Curve Digital Signature Algorithm (ECDSA) The ECDSA algorithm uses elliptic curve cryptography (an encryption system based on the properties of elliptic curves) to provide a variant of the Digital Signature Algorithm. PKA Master Keys PKA master keys protect private keys. v On the Cryptographic Coprocessor Feature, there are two PKA master keys: the Signature Master Key (SMK) and the RSA Key Management Master Key (KMMK). The SMK protects PKA private keys used only in digital signature services. The KMMK protects PKA private keys used in digital signature services and in the DES DATA key distribution functions. v On the PCI Cryptographic Coprocessor, PKA keys are protected by the Asymmetric-Keys Master Key (ASYM-MK). The ASYM-MK is a triple-length DES key used to protect PKA keys. © Copyright IBM Corp. 1997, 2011 79 In order for the PCI Cryptographic Coprocessor to function, the hash pattern of the ASYM-MK must match the hash pattern of the SMK on the Cryptographic Coprocessor Feature. The ICSF administrator installs the PKA master keys on the Cryptographic Coprocessor Feature and the ASYM-MK on the PCI Cryptographic Coprocessor by using either the pass phrase initialization routine, the Clear Master Key Entry panels, or the optional Trusted Key Entry (TKE) workstation. Prior to PKA services being enabled on the PCI Cryptographic Coprocessor, these conditions must be met: – The Symmetric-Keys Master Key (SYM-MK) must be installed on the PCI Cryptographic Coprocessor. It must match the Cryptographic Coprocessor Feature DES master key and match the master key that the CKDS was enciphered with. – The PKA master keys (SMK and KMMK) on the Cryptographic Coprocessor Feature must be installed and valid. – The ASYM-MK PKA master key on the PCI Cryptographic Coprocessor must be installed and valid. – The hash pattern of the ASYM-MK on the PCI Cryptographic Coprocessor must match the hash pattern of the SMK on the Cryptographic Coprocessor Feature. – The PKDS must be initialized with the PKA master keys installed on the Cryptographic Coprocessor Feature. v On the PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor, PKA keys are protected by the Asymmetric-Keys Master Key (ASYM-MK). The ASYM-MK is a triple-length DES key used to protect PKA private keys. On the PCIXCC, CEX2C and CEX3C, the ASYM-MK protects RSA private keys. On the z196 with a CEX3C, there are two PKA master keys: RSA and ECC. The RSA master key is the same as the ASYM-MK. The ECC master key is a 256-bit AES key used to protect ECC private keys. v In order for PKA services to function on the PCIXCC, CEX2C, or CEX3C, the Asymmetric-Keys/RSA and/or ECC master keys must be installed. The ICSF administrator installs the master keys on the PCIXCC, CEX2C, or CEX3C by using either the pass phrase initialization routine, the Clear Master Key Entry panels, or the optional Trusted Key Entry (TKE) workstation. Prior to PKA services being enabled on the PCIXCC, CEX2C, or CEX3C, these conditions must be met: – The ASYM-MK/RSA and/or ECC master keys on the PCIXCC, CEX2C, or CEX3C must be installed. – The PKDS must be initialized with the ASYM-MK/RSA and/or ECC master keys installed on the PCIXCC, CEX2C, or CEX3C. | | | | | | | | | | | | Operational private keys RSA and DSS 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 the SMK/ASYM-MK/RSA or KMMK. ECC operational private keys are protected under two layers of AES encryption. They are encrypted under an AES OPK that in turn is encrypted under the ECC master key. You dynamically generate the OPK for each private key at import time or when the private key is generated on a PCI Cryptographic Coprocessor, PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor. ICSF provides a public key data set (PKDS) for the storage of application PKA keys. | | | | | | | | | 80 z/OS V1R13 ICSF Application Programmer's Guide | | | | | | | | On systems with the Cryptographic Coprocessor Feature, the PKA master keys can't be changed dynamically. The PKA callable services control must be disabled when the master keys are changed. Systems with the PCI Cryptographic Coprocessor can change the SMK/ASMY-MK by loading the new master key and using the PKDS Reencipher utility to reencipher private keys encrypted to the new master key. Private tokens encrypted under the KMMK will only be reenciphered if the KMMK was equal to the SMK. When the reenciphered PKDS is refreshed to become the active PKDS, the PKA callable services control can be enabled. | | | | | | On systems with the PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor, changing the Asymmetric-keys/RSA master key requires that the PKA callable services control be disabled. The new master key value is loaded, the PKDS is reenciphered and the Change Asymmetric Master Key utility makes the reenciphered PKDS the active PKDS. The PKA callable services control will be enabled automatically. | | | | | On systems with the Crypto Express3 Coprocessor, the ECC master key is changed in the same manner as the DES and AES master keys. On systems with the Crypto Express3 Coprocessor with the September 2011 licensed internal code, the RSA master key is changed in the same manner as the DES, AES and ECC master keys. PKA Callable Services The Cryptographic Coprocessor Feature available on the IBM Eserver zSeries 900, provides RSA and DSS digital signature functions, key management functions, and DES key distribution functions. The IBM Eserver zSeries 900 provides the ability to generate RSA keys on the PCI Cryptographic Coprocessor. ICSF provides application programming interfaces to these functions through callable services. The PCIXCC (available on the z890 and z990), the CEX2C (available on the z9 EC, z9 BC, z10 EC and z10 BC), and the CEX3C (available on the z10 EC and z10 BC) provide RSA digital signature functions, key management functions, and DES key distribution functions, PIN, MAC and data encryption functions, and application programming interfaces to these functions through callable services. You can also generate RSA keys on the PCIXCC/CEX2C/CEX3C. The CEX3C on the z196 provides support for ECC. Specifically, it provides ECDSA digital signature functions, ECC key management functions, and application programming interfaces to these functions through callable services. Callable Services Supporting Digital Signatures ICSF provides these services that support digital signatures. Restrictions: v DSS is only supported on the IBM Eserver zSeries 900. v ECDSA is only supported through the CEX3C cryptographic hardware on the z196. Digital Signature Generate Callable Service (CSNDDSG and CSNFDSG) This service generates a digital signature using an RSA, DSS, or ECC private key. It supports these methods of signature generation: Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services 81 v v v v v v ANSI X9.30 (DSS) ANSI X9.30 (ECDSA) ANSI X9.31 (RSA) ISO 9796-1 (RSA) RSA DSI PKCS 1.0 and 1.1 (RSA) Padding on the left with zeros (RSA) The input text must have been previously hashed using the one-way hash generate callable service or the MDC generation service. Digital Signature Verify Callable Service (CSNDDSV and CSNFDSG) This service verifies a digital signature using an RSA, DSS, or ECC public key. This service supports these methods of signature generation: v ANSI X9.30 (DSS) v ANSI X9.30 (ECDSA) v ANSI X9.31 (RSA) v ISO 9796-1 (RSA) v RSA DSI PKCS 1.0 and 1.1 (RSA) v Padding on the left with zeros (RSA) The text that is input to this service must be previously hashed using the one-way hash generate callable service or the MDC generation service. Callable Services for PKA Key Management ICSF provides these services for PKA key management. PKA Key Generate Callable Service (CSNDPKG and CSNFPKG) This service generates a PKA internal token for use with the DSS algorithm in digital signature services. You can then use the PKA public key extract callable service to extract a DSS public key token from the internal key token. This service also supports the generation of RSA keys (on the PCICC, PCIXCC, CEX2C, or CEX3C), and ECC keys (on the CEX3C). Input to the PKA key generate callable service is either a skeleton key token created by the PKA key token build callable service or a valid key token. Upon examination of the input skeleton key token, the PKA key generate service routes the key generation request as follows: v If the skeleton is for a DSS key token, ICSF routes the request to a Cryptographic Coprocessor Feature. v If the skeleton is for an RSA key, ICSF routes the request to any available PCICC, PCIXCC, CEX2C, or CEX3C. v If the skeleton is for a retained RSA key, ICSF routes the request to a PCICC, PCIXCC, CEX2C, or CEX3C where the key is generated and retained for additional security. v If the skeleton is for an ECC key, ICSF routes the request to any available CEX3C. PKA Key Import Callable Service (CSNDPKI and CSNFPKI) This service imports a PKA private key, which may be RSA or DSS. The key token to import can be in the clear or encrypted. The PKA key token build utility creates a clear PKA key token. The PKA key generate callable service generates either a clear or an encrypted PKA key token. 82 z/OS V1R13 ICSF Application Programmer's Guide PKA Key Token Build Callable Service (CSNDPKB and CSNFPKB) The PKA key token build callable service is a utility you can use to create an external PKA key token containing an unenciphered private RSA or DSS key. You can supply this token as input to the PKA key import callable service to obtain an operational internal token containing an enciphered private key. You can also use this service to input a clear unenciphered public ECC, RSA, or DSS key and return the public key in a token format that other PKA services can use directly. Use this service to build skeleton key tokens for input to the PKA key generate callable service for creation of RSA keys (on the PCICC, PCIXCC, CEX2C, or CEX3C), or ECC keys (on the CEX3C). PKA Key Token Change Callable Service (CSNDKTC and CSNFKTC) This service changes PKA key tokens (RSA, DSS, and ECC) or trusted block key tokens, from encipherment under the cryptographic coprocessor's old RSA master key or ECC master key to encipherment under the current cryptographic coprocessor's RSA master key or ECC master key. This callable service only changes private internal tokens. An active PCICC, PCIXCC, CEX2C, or CEX3C is required. PKA Key Translate (CSNDPKT and CSNFPKT) This service translates a CCA RSA key token to an external smart card key token. An active CEX2C or CEX3C is required. PKA Public Key Extract Callable Service (CSNDPKX and CSNFPKX) This service extracts a PKA public key token from a PKA internal (operational) or external (importable) private key token. It performs no cryptographic verification of the PKA private key token. Callable Services to Update the Public Key Data Set (PKDS) | | The Public Key Data Set (PKDS) is a repository for DSS, ECC, and RSA public and private keys and trusted blocks. An application can store keys in the PKDS and refer to them by label when using any of the callable services which accept public key tokens as input. The PKDS update callable services provide support for creating and writing records to the PKDS and reading and deleting records from the PKDS. | | PKDS Key Record Create Callable Service (CSNDKRC and CSNFKRC) | | | This service accepts an RSA, DSS, or ECC private key token in either external or internal format, or an RSA, DSS, or ECC public key token or trusted blocks and writes a new record to the PKDS. An application can create a null token in the PKDS by specifying a token length of zero. The key label must be unique. PKDS Key Record Delete Callable Service (CSNDKRD and CSNFKRD) This service deletes a record from the PKDS. An application can specify that the entire record be deleted, or that only the contents of the record be deleted. If only the contents of the record are deleted, the record will still exist in the PKDS but will contain only binary zeros. The key label must be unique. Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services 83 Note: Retained keys cannot be deleted from the PKDS with this service. See “Retained Key Delete (CSNDRKD and CSNFRKD)” on page 558 for information on deleting retained keys. PKDS Key Record Read Callable Service (CSNDKRR and CSNFKRR) | | This service reads a record from the PKDS and returns the contents of that record to the caller. The key label must be unique. PKDS Key Record Write Callable Service (CSNDKRW and CSNFKRW) | | This service accepts an RSA, DSS, or ECC private key token in either external or internal format, or an RSA, DSS, or ECC public key token or trusted blocks and writes over an existing record in the PKDS. An application can check the PKDS for a null record with the label provided and overwrite this record if it does exist. Alternatively, an application can specify to overwrite a record regardless of the contents of the record. | Note: Retained keys cannot be written to the PKDS with the PKDS Key Record Write service, nor can a retained key record in the PKDS be overwritten with this service. | | Callable Services for Working with Retained Private Keys Private keys can be generated, retained, and used within the secure boundary of a PCICC, PCIXCC, CEX2C, or CEX3C. Retained keys are generated by the PKA Key Generate (CSNDPKG) callable service. The private key values of retained keys never appear in any form outside the secure boundary. All retained keys have an entry in the PKDS that identifies the PCICC, PCIXCC, CEX2C, or CEX3C where the retained private key is stored. ICSF provides these callable services to list and delete retained private keys. Retained Key Delete Callable Service (CSNDRKD and CSNFRKD) The retained key delete callable service deletes a key that has been retained within a PCICC, PCIXCC, CEX2C, or CEX3C and also deletes the record containing the key token from the PKDS. Retained Key List Callable Service (CSNDRKL and CSNFKRL) The retained key list callable service lists the key labels of private keys that are retained within the boundaries of PCICC, PCIXCC, CEX2C, or CEX3C installed on your server. Clearing the retained keys on a coprocessor The retained keys on a PCICC, PCIXCC, CEX2C, or CEX3C may be cleared. These are the conditions under which the retained key will be lost: v If the PCICC, PCIXCC, CEX2C, or CEX3C detects tampering (the intrusion latch is tripped), ALL installation data is cleared: master keys, retained keys for all domains, as well as roles and profiles. v If the PCICC, PCIXCC, CEX2C, or CEX3C detects tampering (the secure boundary of the card is compromised), it self-destructs and can no longer be used. v If you issue a command from the TKE workstation to zeroize a domain This command zeroizes the data specific to a domain: master keys and retained keys. v If you issue a command from the Support Element panels to zeroize all domains. 84 z/OS V1R13 ICSF Application Programmer's Guide This command zeroizes ALL installation data: master keys, retained keys and access control roles and profiles. Callable Services for SET Secure Electronic Transaction SET is an industry-wide open standard for securing bankcard transactions over open networks. The SET protocol addresses the payment phase of a transaction from the individual, to the merchant, to the acquirer (the merchant's current bankcard processor). It can be used to help ensure the privacy and integrity of real time bankcard payments over the Internet. In addition, with SET in place, everyone in the payment process knows who everyone else is. The card holder, the merchant, and the acquirer can be fully authenticated because the core protocol of SET is based on digital certificates. Each participant in the payment transaction holds a certificate that validates his or her identity. The public key infrastructure allows these digital certificates to be exchanged, checked, and validated for every transaction made over the Internet. The mechanics of this operation are transparent to the application. Under the SET protocol, every online purchase must be accompanied by a digital certificate which identifies the card-holder to the merchant. The buyer's digital certificate serves as an electronic representation of the buyer's credit card but does not actually show the credit card number to the merchant. Once the merchant's SET application authenticates the buyer's identity, it then decrypts the order information, processes the order, and forwards the still-encrypted payment information to the acquirer for processing. The acquirer's SET application authenticates the buyer's credit card information, identifies the merchant, and arranges settlement. With SET, the Internet becomes a safer, more secure environment for the use of payment cards. ICSF provides these callable services that can be used in developing SET applications that make use of the S/390 and IBM Eserver zSeries cryptographic hardware at the merchant and acquirer payment gateway. SET Block Compose Callable Service (CSNDSBC and CSNFSBC) The SET Block Compose callable service performs DES encryption of data, OAEP-formatting through a series of SHA-1 hashing operations, and the RSA-encryption of the Optimal Asymmetric Encryption Padding (OAEP) block. SET Block Decompose Callable Service (CSNDSBD and CSNFSBD) The SET Block Decompose callable service decrypts both the RSA-encrypted and the DES-encrypted data. PKA Key Tokens PKA key tokens contain RSA, DSS or ECC private or public keys. PKA tokens are variable length because they contain either RSA, DSS, or ECC key values, which are variable in length. Consequently, length parameters precede all PKA token parameters. The maximum allowed size is 3500 bytes. PKA key tokens consist of a token header, any required sections, and any optional sections. Optional sections depend on the token type. PKA key 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 RSA, DSS, or ECC information: v A public key token v A private external key token v A private internal key token Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services 85 Public key tokens contain only the public key. Private key tokens contain the public and private key pair. Table 7 summarizes the sections in each type of token. Table 7. Summary of PKA Key Token Sections Section Public External Key Token Private External Key Token Private Internal Key Token Header X X X X X X X X X RSA, DSS, or ECC private key information RSA, DSS, or ECC public key information X Key name (optional) Internal information X As with DES and AES key tokens, the first byte of a PKA key token contains the token identifier which indicates the type of token. A first 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. A first byte of X'1F' indicates an internal token with a cleartext public key and a private key that is enciphered by the PKA master key and ready for internal use. An internal key token is in operational key form. A PKA private key token must be in operational form for ICSF to use it. (PKA public key tokens are used directly in the external form.) Formats for public and private external and internal RSA, DSS, and ECC key tokens begin in “RSA Public Key Token” on page 793. PKA Key Management You can also generate PKA keys in several ways. v Using the ICSF PKA key generate callable service. v Using the Transaction Security System PKA key generate verb, or a comparable product from another vendor. 86 z/OS V1R13 ICSF Application Programmer's Guide Clear Key Values TSS Skeleton Key Token PKA Key Generate Service PKA Key Token Build Service Clear external External unencrypted External encrypted PKA token PKA token PKA token Internal PKA token PKA Key Import Figure 7. PKA Key Management With a PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor, you can use the ICSF PKA key generate callable service to generate internal and external PKA tokens. You can also generate RSA keys on another system. To input a clear RSA key to ICSF, create the token with the PKA key token build callable service and import it using the PKA key import callable service. To input an encrypted RSA key, generate the key on the Transaction Security System and import it using the PKA key import callable service. In either case, use the PKA key token build callable service to create a skeleton key token as input (see “PKA Key Token Build (CSNDPKB and CSNFPKB)” on page 535). You can generate DSS keys on another system or on ICSF. You need to supply DSS network quantities to the PKA key generate callable service. If you generate DSS keys on another system, you can import them the same way as RSA keys. If you generate a DSS key on ICSF, you can never export it. You can use it on another ICSF host only if the same PKA master keys are installed on both systems. The PKA key import callable service uses the clear token from the PKA key token build service or a clear or encrypted token from the Transaction Security System to securely import the key token into operational form for ICSF to use. ICSF does not permit the export of the imported PKA key. The PKA public key extract callable service builds a public key token from a private key token. | Application RSA, DSS, and ECC public and private keys can be stored in the public key data set (PKDS), a VSAM data set. Security and Integrity of the Token PKA private key tokens may optionally have a 64-byte private_key_name field. If private_key_name exists, ICSF uses RACROUTE REQUEST=AUTH to verify it prior to using the token in a callable service. For additional security, the processor also validates the entire private key token. Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services 87 Key Identifier for PKA Key Token A key identifier for a PKA key token is a variable length (maximum allowed size is 3500 bytes) area that contains one of these: v Key label identifies keys that are in the PKDS. Ask your ICSF administrator for the key labels that you can use. v Key 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 PKA key generate callable service), or received from another system that can produce external key tokens. An internal key token can be used only on ICSF, because a PKA master 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. A null key token consists of 8 bytes of binary zeros. The PKDS Key Record Create service can be used to write a null token to the PKDS. This PKDS record can subsequently be identified as the target token for the PKA key import or PKA key generate service. | | The term key identifier is used when a parameter could be one of the previously discussed items and to indicate that different inputs are possible. For example, you may 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'40', the field is considered to be holding a key label. The contents of a key label are interpreted as a pointer to a public key data set (PKDS) key entry. The key label is an indirect reference to an internal key token. A key label is specified on callable services with the key_identifier parameter as a 64-byte character string, left-justified, and padded on the right with blanks. In most cases, the callable service does not check the syntax of the key label beyond the first byte. One exception is the CKDS key record create callable service which enforces the KGUP rules for key labels unless syntax checking is bypassed by a preprocessing exit. | A key label has this form: Offset 00-63 Length 64 Data Key label name Key Token A key token is a variable length (maximum allowed size is 3500 bytes) field composed of key value and control information. PKA keys can be either public or private RSA, DSS, 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 private key token (the first byte of the key identifier is X'00'). For the format of each token type, refer to Appendix B, “Key Token Formats,” on page 777. 88 z/OS V1R13 ICSF Application Programmer's Guide An internal key token is a token that can be used only on the ICSF system that created it (or another ICSF system with the same PKA master key). It contains a key that is encrypted under the PKA master key. An application obtains an internal key token by using one of the callable services such as those listed. The callable services are described in detail in Chapter 10, “Managing PKA Cryptographic Keys.” v PKA key generate v PKA key import The PKA Key Token Change callable service can reencipher private internal tokens from encryption under the old ASYM-MK to encryption under the current ASYM-MK. PKDS Reencipher/Activate options are available to reencipher RSA, DSS and ECC internal tokens in the PKDS when the SMK/ASYM-MK keys are changed. PKA master keys may not be changed dynamically. For debugging information, see Appendix B, “Key Token Formats” for the format of an internal 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 PKA key 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 callable services such as those listed. They are described in detail in Chapter 10, “Managing PKA Cryptographic Keys.” v PKA public key extract v PKA key token build v PKA key generate For debugging information, see Appendix B, “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. For debugging information, see Appendix B, “Key Token Formats” for the format of a null key token. The Transaction Security System and ICSF Portability The Transaction Security System PKA verbs from releases prior to 1996 can run only on the Transaction Security System. The PKA96 release of the Transaction Security System PKA verbs generally runs on ICSF without change. As with DES cryptography, you cannot interchange internal PKA tokens but can interchange external tokens. Summary of the PKA Callable Services Table 8 on page 90 lists the PKA callable services, described in this publication, and their corresponding verbs. (The PKA services start with CSNDxxx and have corresponding CSFxxx names.) This table also references the topic that describes the callable service. Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services 89 Table 8. Summary of PKA Callable Services Verb Service Name Function Chapter 8, “Financial Services” CSNDSBC CSNFSBC SET block compose Composes the RSA-OAEP block and the DES-encrypted block in support of the SET protocol. CSNDSBD SET block decompose Decomposes the RSA-OAEP block and the DES-encrypted block to provide unencrypted data back to the caller. Chapter 9, “Using Digital Signatures” CSNDDSG CSNFDSG Digital signature generate Generates a digital signature using a PKA private key supporting RSA, DSS, and ECDSA algorithms. CSNDDSV CSNFDSV Digital signature verify Verifies a digital signature using a PKA public key supporting RSA, DSS, and ECDSA algorithms. Chapter 10, “Managing PKA Cryptographic Keys” CSNDPKG CSNFPKG PKA key generate Generates a DSS internal token for use in digital signature services, RSA keys (for use on the PCICC, PCIXCC, CEX2C, or CEX3C) and ECC keys (for use on the CEX3C). CSNDPKI CSNFPKI PKA key import Imports a PKA key token containing either a clear PKA key or a PKA key enciphered under a limited authority IMP-PKA KEK. CSNDPKB CSNFPKB PKA key token build Creates an external PKA key token containing a clear private RSA or DSS key. Using this token as input to the PKA key import callable service returns an operational internal token containing an enciphered private key. Using CSNDPKB on a clear public RSA or DSS key, returns the public key in a token format that other PKA services can directly use. CSNDPKB can also be used to create a skeleton token for input to the PKA Key Generate service for the generation of an internal DSS or RSA key token. CSNDKTC CSNFKTC PKA key token change Changes PKA key tokens (RSA, DSS, and ECC) or trusted block key tokens, from encipherment under the cryptographic coprocessor's old RSA master key or ECC master key to encipherment under the current cryptographic coprocessor's RSA master key or ECC master key. This callable service only changes private internal tokens. CSNDPKT CSNFPKT PKA key translate Translates a CCA RSA key token to a smart card format. CSNDPKX PKA public key extract Extracts a PKA public key token from a supplied PKA internal or external private key token. Performs no cryptographic verification of the PKA private token. CSNDRKD CSNFRKD Retained key delete Deletes a key that has been retained within the PCICCs, PCIXCCs, CEX2Cs, or CEX3Cs. CSNDRKL CSNFRKL Retained key list Lists key labels of keys that have been retained within all currently active PCICCs, PCIXCCs, CEX2Cs, or CEX3Cs. Chapter 11, “Key Data Set Management” | CSNDKRC CSNFKRC 90 PKDS key record create z/OS V1R13 ICSF Application Programmer's Guide Writes a new record to the PKDS. Table 8. Summary of PKA Callable Services (continued) Verb Service Name Function | CSNDKRD CSNFKRD PKDS key record delete Delete a record from the PKDS. | CSNDKRR CSNFKRR PKDS key record read Read a record from the PKDS and return the contents of that record. | CSNDKRW CSNFKRW PKDS key record write Write over an existing record in the PKDS. Chapter 3. Introducing PKA Cryptography and Using PKA Callable Services 91 92 z/OS V1R13 ICSF Application Programmer's Guide Chapter 4. Introducing PKCS #11 and using PKCS #11 callable services The Integrated Cryptographic Service Facility has implemented callable service in support of PKCS #11. A callable service is a routine that receives control using a CALL statement in an application language. Each callable service performs one or more functions, including: v initializing and deleting PKCS11 tokens v creating, reading, updating and deleting PKCS11 objects Many services have hardware requirements. See each service for details. All new callable services will be invocable in AMODE(24), AMODE(31), or AMODE(64). For more information about PKCS #11 see z/OS Cryptographic Services ICSF Writing PKCS #11 Applications. PKCS #11 Management Services ICSF provides callable services that support PKCS #11 token and object management. The following table summarizes these callable services. For complete syntax and reference information, refer to Part 3, “PKCS #11 Callable Services,” on page 653. Table 9. Summary of PKCS #11 callable services Verb Service Name Function CSFPDVK PKCS #11 Derive key Generate a new secret key object from an existing key object CSFPDMK PKCS #11 Derive multiple keys Generate multiple secret key objects and protocol dependent keying material from an existing secret key object CSFPHMG PKCS #11 Generate HMAC Generate a hashed message authentication code (MAC) CSFPGKP PKCS #11 Generate key pair Generate an RSA, DSA, Elliptic Curve, or Diffie-Hellman key pair CSFPGSK PKCS #11 Generate secret key Generate a secret key or set of domain parameters CSFPGAV PKCS #11 Get attribute value List the attributes of a PKCS11 object CSFPOWH PKCS #11 One-way hash, sign, or verify Generate a one-way hash on specified text, sign specified text, or verify a signature on specified text CSFPPKS PKCS #11 Private key sign v Decrypt or sign data using an RSA private key using zero-pad or PKCS #1 v1.5 formatting v Sign data using a DSA private key v Sign data using an Elliptic Curve private key in combination with DSA CSFPPRF © Copyright IBM Corp. 1997, 2011 PKCS #11 Pseudo-random function Generate pseudo-random output of arbitrary length. 93 Table 9. Summary of PKCS #11 callable services (continued) Verb Service Name Function CSFPPKV PKCS #11 Public key verify v Encrypt or verify data using an RSA public key using zero-pad or PKCS #1 v1.5 formatting. For encryption, the encrypted data is returned v Verify a signature using a DSA public key. No data is returned v Verify a signature using an Elliptic Curve public key in combination with DSA. No data is returned CSFPSKD PKCS #11 Secret key decrypt Decipher data using a clear symmetric key CSFPSKE PKCS #11 Secret key encrypt Encipher data using a clear symmetric key CSFPSAV PKCS #11 Set attribute value Update the attributes of a PKCS11 object CSFPTRC PKCS #11 Token record create Initialize or re-initialize a z/OS PKCS #11 token, creates or copies a token object in the token data set and creates or copies a session object for the current PKCS #11 session CSFPTRD PKCS #11 Token record delete Delete a z/OS PKCS #11 token, token object, or session object CSFPTRL PKCS #11 Token record list Obtain a list of z/OS PKCS #11 tokens. The caller must have SAF authority to the token. Also obtains a list of token and session objects for a token. Use a search template to restrict the search for specific attributes. CSFPUWK PKCS #11 Unwrap key Unwrap and create a key object using another key CSFPHMV PKCS #11 Verify HMAC Verify a hash message authentication code (MAC) CSFPWPK PKCS #11 Wrap key Wrap a key with another key Attribute List The attributes of an object can be the input and the output of a service. The format of the attributes is shown here and applies to all PKCS #11 callable services. For the token record list service, the search_template has the same format as an attribute list. The lengths in the attribute list and attribute structures are unsigned integers. An attribute_list is a structure in this format: Number of attributes 2 bytes Attribute Attribute ... 4 + 2 + length of value bytes 4 + 2 + length of value bytes ... Each attribute is a structure in this format: 94 z/OS V1R13 ICSF Application Programmer's Guide Attribute name Length of value (n) Value 4 bytes 2 bytes n bytes Handles A handle is a 44-byte identifier for a token or an object. The format of the handle is as follows: Name of token or object Sequence number ID 32 bytes 8 bytes 4 bytes The token name in the first 32 bytes of the handle is provided by the PKCS #11 application when the token or object is created. The first character of the name must be alphabetic or a national character (“#”, “$”, or “@”). Each of the remaining characters can be alphanumeric, a national character (“#”, “$”, or“ @”), or a period(“.”) The sequence number is a hexadecimal number stored as the EBCDIC representation of 8 hexadecimal numbers. The sequence number field in a token is EBCDIC blanks. The token record contains a last-used sequence number field, which is incremented each time an object associated with the token is created. This sequence number value is placed in the handle of the newly-created object. The ID field is 4 characters. The first character contains an EBCDIC “T” if the handle belongs to a token object, “S” if the handle belongs to a session object, or blank if the handle belongs to a token. The last three characters must be EBCDIC blanks. Chapter 4. Introducing PKCS #11 and using PKCS #11 callable services 95 96 z/OS V1R13 ICSF Application Programmer's Guide Part 2. CCA Callable Services This publication introduces DES, AES and PKA callable services. | | | | | | Note: References to the IBM Eserver zSeries 800 (z800) do not appear in this information. Be aware that the documented notes and restrictions for the IBM Eserver zSeries 900 (z900) also apply to the z800. References to the IBM zEnterprise 114 (z114) do not appear in this information. Be aware that the documented notes and restrictions for the IBM zEnterprise 196 (z196) also apply to the z114. © Copyright IBM Corp. 1997, 2011 97 98 z/OS V1R13 ICSF Application Programmer's Guide Chapter 5. Managing Symmetric Cryptographic Keys This topic describes the callable services that generate and maintain cryptographic keys. Using ICSF, you can generate keys using either the key generator utility program or the key generate callable service. ICSF provides a number of callable services to assist you in managing and distributing keys and maintaining the cryptographic key data set (CKDS). | | | | | | This topic describes these callable services: v “Clear Key Import (CSNBCKI and CSNECKI)” on page 100 v “Control Vector Generate (CSNBCVG and CSNECVG)” on page 102 v “Control Vector Translate (CSNBCVT and CSNECVT)” on page 105 v “Cryptographic Variable Encipher (CSNBCVE and CSNECVE)” on page 109 v “Data Key Export (CSNBDKX and CSNEDKX)” on page 111 v “Data Key Import (CSNBDKM and CSNEDKM)” on page 114 v “Diversified Key Generate (CSNBDKG and CSNEDKG)” on page 117 v “ECC Diffie-Hellman (CSNDEDH and CSNFEDH)” on page 123 v “Key Export (CSNBKEX and CSNEKEX)” on page 130 v “Key Generate (CSNBKGN and CSNEKGN)” on page 135 v “Key Generate2 (CSNBKGN2 and CSNEKGN2)” on page 147 v “Key Import (CSNBKIM and CSNEKIM)” on page 155 v “Key Part Import (CSNBKPI and CSNEKPI)” on page 160 v “Key Part Import2 (CSNBKPI2 and CSNEKPI2)” on page 165 v “Key Test (CSNBKYT and CSNEKYT)” on page 169 v “Key Test2 (CSNBKYT2 and CSNEKYT2)” on page 173 v “Key Test Extended (CSNBKYTX and CSNEKTX)” on page 178 v “Key Token Build (CSNBKTB and CSNEKTB)” on page 181 v “Key Token Build2 (CSNBKTB2 and CSNEKTB2)” on page 191 v “Key Translate (CSNBKTR and CSNEKTR)” on page 197 v “Key Translate2 (CSNBKTR2 and CSNEKTR2)” on page 199 v “Multiple Clear Key Import (CSNBCKM and CSNECKM)” on page 205 v “Multiple Secure Key Import (CSNBSKM and CSNESKM)” on page 209 v “PKA Decrypt (CSNDPKD and CSNFPKD)” on page 215 v “PKA Encrypt (CSNDPKE and CSNFPKE)” on page 220 v “Prohibit Export (CSNBPEX and CSNEPEX)” on page 225 v “Prohibit Export Extended (CSNBPEXX and CSNEPEXX)” on page 226 v “Random Number Generate (CSNBRNG, CSNERNG, CSNBRNGL and CSNERNGL)” on page 228 v “Remote Key Export (CSNDRKX and CSNFRKX)” on page 232 v “Restrict Key Attribute (CSNBRKA and CSNERKA)” on page 239 v “Secure Key Import (CSNBSKI and CSNESKI)” on page 243 v “Secure Key Import2 (CSNBSKI2 and CSNESKI2)” on page 247 v “Symmetric Key Export (CSNDSYX and CSNFSYX)” on page 251 v “Symmetric Key Generate (CSNDSYG and CSNFSYG)” on page 258 v “Symmetric Key Import (CSNDSYI and CSNFSYI)” on page 266 v “Symmetric Key Import2 (CSNDSYI2 and CSNFSYI2)” on page 272 v “Transform CDMF Key (CSNBTCK and CSNETCK)” on page 277 v “Trusted Block Create (CSNDTBC and CSNFTBC)” on page 279 v “TR-31 Export (CSNBT31X and CSNET31X)” on page 283 v “TR-31 Import (CSNBT31I and CSNET31I)” on page 298 v “TR-31 Optional Data Build (CSNBT31O and CSNET31O)” on page 311 v “TR-31 Optional Data Read (CSNBT31R and CSNET31R)” on page 314 v “TR-31 Parse (CSNBT31P and CSNET31P)” on page 318 © Copyright IBM Corp. 1997, 2011 99 v “User Derived Key (CSFUDK and CSFUDK6)” on page 321 Clear Key Import (CSNBCKI and CSNECKI) Use the clear key import callable service to import a clear DATA key that is to be used to encipher or decipher data. This callable service can import only DATA keys. Clear key import accepts an 8-byte clear DATA key, enciphers it under the master key, and returns the encrypted DATA key 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 service returns a warning value in the reason_code parameter. The callable service does not adjust the parity of the key. Note: To import 16-byte or 24-byte DATA keys, use the multiple clear key import callable service that is described in “Multiple Clear Key Import (CSNBCKM and CSNECKM)” on page 205. The multiple clear key import service supports AES DATA keys. The callable service name for AMODE(64) invocation is CSNECKI. Format CALL CSNBCKI( return_code, reason_code, exit_data_length, exit_data, clear_key, key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that are assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. 100 z/OS V1R13 ICSF Application Programmer's Guide Clear Key Import exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. 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 A 64-byte string that is to receive the internal key token. “Key Identifier for Key Token” on page 8 describes the internal key token. Usage Notes These usage notes only apply to CCF systems. This service produces an internal DATA token with a control vector which is usable on the Cryptographic Coprocessor Feature. If a valid internal token is supplied as input to the service in the key_identifier field, that token's control vector will not be used in the encryption of the clear key value. This service marks this internal key token CDMF or DES, according to the system's default encryption algorithm, unless token copying overrides this. The service marks this internal key token CDMF or DES, according to the system's default encryption algorithm, unless token copying overrides this. See “System Encryption Algorithm” on page 49 for details. | | The Clear Key Import/Multiple Clear Key Import - DES access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 10. Clear key import required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries PCI X Cryptographic 890 Coprocessor/Crypto Express2 IBM Eserver zSeries Coprocessor 990 There are no internal token markings for CDMF or DES. There is no token copying. IBM System z9 EC There are no internal token markings for CDMF or DES. There is no token copying. Crypto Express2 Coprocessor IBM System z9 BC Chapter 5. Managing Symmetric Cryptographic Keys 101 Clear Key Import Table 10. Clear key import required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z10 EC Crypto Express2 Coprocessor There are no internal token markings for CDMF or DES. There is no token copying. IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor There are no internal token markings for CDMF or DES. There is no token copying. Control Vector Generate (CSNBCVG and CSNECVG) The Control Vector Generate callable service builds a control vector from keywords specified by the key_type and rule_array parameters. The callable service name for AMODE(64) is CSNECVG. Format CALL CSNBCVG( return_code, reason_code, exit_data_length, exit_data, key_type, rule_array_count, rule_array, reserved, control_vector ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | exit_data_length || | Direction: Ignored This field is ignored. It is recommended to specify 0 for this parameter. | | | Type: Integer exit_data 102 z/OS V1R13 ICSF Application Programmer's Guide Control Vector Generate || | | Direction: Ignored Type: String This field is ignored. key_type Direction: Input Type: String A string variable containing a keyword for the key type. The keyword is 8 bytes in length, left justified, and padded on the right with space characters. It is taken from this list: CIPHER CVARDEC CVARENC CVARPINE CVARXCVL CVARXCVR DATA DATAM DATAMV DECIPHER DKYGENKY ENCIPHER EXPORTER IKEYXLAT IMPORTER IPINENC KEYGENKY MAC MACVER OKEYXLAT OPINENC PINGEN PINVER SECMSG rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. rule_array Direction: Input | | | | | Type: Character String Keywords that provide control information to the callable service. 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 and CSNEKTB)” on page 181 illustrates the key type and key usage keywords that can be combined in the Control Vector Generate and Key Token Build callable services to create a control vector. The rule array keywords are: v AMEX-CSC v ANSIX9.9 v ANY v ANY-MAC v CLR8-ENC v CPINENC v CPINGEN v v v v v v v CPINGENA CVVKEY-A CVVKEY-B DALL DATA DDATA DEXP v DIMP v DKYL0 v DKYL1 v DKYL2 Chapter 5. Managing Symmetric Cryptographic Keys 103 Control Vector Generate v v v v v DKYL3 DKYL4 DKYL5 DKYL6 DKYL7 v v v v v v v DMAC DMKEY DMPIN DMV DOUBLE DPVR ENH-ONLY v v v v v v EPINGEN EPINGENA EPINVER EXEX EXPORT GBP-PIN v GBP-PINO v IBM-PIN v IBM-PINO v v v v IMEX IMIM IMPORT INBK-PIN v KEY-PART v KEYLN8 v KEYLN16 v v v v v LMTD-KEK MIXED NO-SPEC NO-XPORT NON-KEK | v NOOFFSET v NOT31XPT | v v v v v v v OPEX OPIM REFORMAT SINGLE SMKEY SMPIN T31XPTOK v TRANSLAT v UKPT v VISA-PVV 104 z/OS V1R13 ICSF Application Programmer's Guide Control Vector Generate v XLATE v XPORT-OK Note: CLR8-ENC or UKPT must be coded in rule_array when the KEYGENKY key type is coded. When the SECMSG key_type is coded, either SMKEY or SMPIN must be specified in the rule_array. ENH-ONLY is not supported with key type DATA. reserved Direction: Input Type: String The reserved parameter must be a variable of 8 bytes of X'00'. control_vector Direction: Output Type: String A 16-byte string variable in application storage where the service returns the generated control vector. Usage Notes See Table 61 on page 188 for an illustration of key type and key usage keywords that can be combined in the Control Vector Generate and Key Token Build callable services to create a control vector. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 11. Control vector generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries None. 900 IBM Eserver zSeries None. 990 IBM Eserver zSeries 890 IBM System z9 EC None. IBM System z9 BC IBM System z10 EC None. IBM System z10 BC z196 None. Control Vector Translate (CSNBCVT and CSNECVT) The Control Vector Translate callable service changes the control vector used to encipher an external key. See “Changing Control Vectors with the Control Vector Translate Callable Service” on page 837 for additional information about this service. Chapter 5. Managing Symmetric Cryptographic Keys 105 Control Vector Translate The callable service name for AMODE(64) invocation is CSNECVT. Format CALL CSNBCVT( return_code, reason_code, exit_data_length, exit_data, KEK_key_identifier, source_key_token, array_key_left, mask_array_left, array_key_right, mask_array_right, rule_array_count, rule_array, target_key_token ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFFFF' (2 gigabytes). The data is defined in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. KEK_key_identifier Direction: Input/Output Type: String The 64-byte string variable containing an internal key token or the key label of an internal key token record containing the key-encrypting key. The control vector in the internal key token must specify the key type of IMPORTER, EXPORTER, IKEYXLAT, or OKEYXLAT. 106 z/OS V1R13 ICSF Application Programmer's Guide Control Vector Translate source_key_token Direction: Input Type: String A 64-byte string variable containing the external key token with the key and control vector to be processed. array_key_left Direction: Input/Output Type: String A 64-byte string variable containing an internal key token or a key label of an internal key token record that deciphers the left mask array. The internal key token must contain a control vector specifying a CVARXCVL key type. mask_array_left Direction: Input Type: String A string of seven 8-byte elements containing the mask array enciphered under the left array key. array_key_right Direction: Input/Ouput Type: String A 64-byte string variable containing an internal key token or a key label of an internal key token record that deciphers the right mask array. The internal key token must contain a control vector specifying a CVARXCVR key type. mask_array_right Direction: Input Type: String A string of seven 8-byte elements containing the mask array enciphered under the right array key. rule_array_count Direction: Input Type: Integer An integer containing the number of elements in the rule array. The value of the rule_array_count must be 0, 1, or 2 for this service. If the rule_array_count is 0, the default keywords are used. rule_array Direction: Input Type: Character String The rule_array parameter is an array of keywords. 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: Table 12. Keywords for Control Vector Translate Keyword Meaning Parity Adjustment Rule (optional) Chapter 5. Managing Symmetric Cryptographic Keys 107 Control Vector Translate Table 12. Keywords for Control Vector Translate (continued) Keyword Meaning ADJUST Ensures that all target key bytes have odd parity. This is the default. NOADJUST Prevents the parity of the target being altered. Key-portion Rule (optional) BOTH Causes both halves of a 16-byte source key to be processed with the result placed into corresponding halves of the target key. When you use the BOTH keyword, the mask array must be able to validate the translation of both halves. LEFT Causes an 8-byte source key, or the left half of a 16-byte source key, to be processed with the result placed into both halves of the target key. This is the default. RIGHT Causes the right half of a 16-byte source key to be processed with the result placed into the right half of the target key. The left half is copied unchanged (still enciphered) from the source key. SINGLE Causes the left half of the source key to be processed with the result placed into the left half of the target key token. The right half of the target key is unchanged. target_key_token Direction: Input/Output Type: String A 64-byte string variable containing an external key token with the new control vector. This key token contains the key halves with the new control vector. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output target_key_token will be wrapped in the same manner as the input source_key_token. Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. If KEK_key_identifier is a label of an IMPORTER or EXPORTER key, the label must be unique in the CKDS. The Control Vector Translate access control point controls the function of this service. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. 108 z/OS V1R13 ICSF Application Programmer's Guide Control Vector Translate Table 13. Control vector translate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI Cryptographic 900 Coprocessor ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. Crypto Express2 Coprocessor ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. Crypto Express3 Coprocessor Enhanced key token wrapping not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC z196 Crypto Express3 Coprocessor Cryptographic Variable Encipher (CSNBCVE and CSNECVE) The Cryptographic Variable Encipher callable service uses a CVARENC key to encrypt plaintext by using the Cipher Block Chaining (CBC) method. You can use this service to prepare a mask array for the Control Vector Translate service. The plaintext must be a multiple of eight bytes in length. The callable service name for AMODE(64) invocation is CSNECVE. Format CALL CSNBCVE( return_code, reason_code, exit_data_length, exit_data, c-variable_encrypting_key_identifier, text_length, plaintext, initialization_vector, ciphertext ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 109 Cryptographic Variable Encipher The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFFFF' (2 gigabytes). The data is defined in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. c-variable_encrypting_key_identifier Direction: Input/Output Type: String The 64-byte string variable containing an internal key or a key label of an internal key token record in the CKDS. The internal key must contain a control vector that specifies a CVARENC key type. text_length Direction: Input Type: Integer An integer variable containing the length of the plaintext and the returned ciphertext. plaintext Direction: Input Type: String A string of length 8 to 256 bytes which contains the plaintext. The data must be a multiple of 8 bytes. initialization_vector Direction: Input Type: String A string variable containing the 8-byte initialization vector that the service uses in encrypting the plaintext. ciphertext Direction: Output Type: String The field which receives the ciphertext. The length of this field is the same as the length of the plaintext. 110 z/OS V1R13 ICSF Application Programmer's Guide Cryptographic Variable Encipher Restrictions v The text length must be a multiple of 8 bytes. v The maximum length of text that the security server can process is 256 bytes. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | | The Cryptographic Variable Encipher access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 14. Cryptographic variable encipher required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI Cryptographic 900 Coprocessor IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Data Key Export (CSNBDKX and CSNEDKX) Use the data key export callable service to reencipher a data-encrypting key (key type of DATA only) from encryption under the master key to encryption under an exporter key-encrypting key. The reenciphered key is in a form suitable for export to another system. The data key export service generates a key token with the same key length as the input token's key. The callable service name for AMODE(64) invocation is CSNEDKX. Chapter 5. Managing Symmetric Cryptographic Keys 111 Data Key Export Format CALL CSNBDKX( return_code, reason_code, exit_data_length, exit_data, source_key_identifier, exporter_key_identifier, target_key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. source_key_identifier Direction: Input/Output Type: String A 64-byte string for an internal key token or label that contains a data-encrypting key to be reenciphered. The data-encrypting key is encrypted under the master key. exporter_key_identifier Direction: Input/Output Type: String A 64-byte string for an internal key token or key label that contains the exporter key_encrypting key. The data-encrypting key previously discussed will be encrypted under this exporter key_encrypting key. 112 z/OS V1R13 ICSF Application Programmer's Guide Data Key Export target_key_identifier Direction: Input/Output Type: String A 64-byte field that is to receive the external key token, which contains the reenciphered key that has been exported. The reenciphered key can now be exchanged with another cryptographic system. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output target_key_identifier will be wrapped in the same manner as the source_key_identifier. Restrictions For existing TKE V3.1 (or higher) users, you may have to explicitly enable new access control points. Current applications will fail 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. This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. When the service is processed on the CCF, ICSF examines the data encryption algorithm bits on the exporter key-encrypting key and DATA key for consistency. It does not export a CDMF key under a DES-marked key-encrypting key or a DES key under a CDMF-marked key-encrypting key. ICSF does not propagate the data encryption marking on the operational key to the external token. Token marking for DES/CDMF on DATA and key-encrypting keys is ignored on a PCICC, PCIXCC, CEX2C, or CEX3C. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 15. Required access control points for Data key export | Access Control Point Restrictions | Data Key Export - Unrestricted None | | Data Key Export Key-encrypting key may not have equal key halves | | | To use a NOCV key-encrypting key with the data key export service, the NOCV KEK usage for export-related functions access control point must be enabled in addition to one or both of the access control points listed. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 5. Managing Symmetric Cryptographic Keys 113 Data Key Export Table 16. Data key export required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature PCI Cryptographic Coprocessor ICSF routes the request to a PCI Cryptographic Coprocessor if the control vector of the exporter_key_identifier cannot be processed on the Cryptographic Coprocessor Feature. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Data Key Import (CSNBDKM and CSNEDKM) Use the data key import callable service to import an encrypted source DES single-length, double-length or triple-length DATA key and create or update a target internal key token with the master key enciphered source key. The callable service name for AMODE(64) invocation is CSNEDKM. Format CALL CSNBDKM( return_code, reason_code, exit_data_length, exit_data, source_key_token, importer_key_identifier, target_key_identifier) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. 114 z/OS V1R13 ICSF Application Programmer's Guide Data Key Import reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. 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. A double-length key that should result in a default DATA control vector must be specified in a version X'01' external key token. Otherwise, both single and double-length keys are presented in a version X'00' key token. For the null token, the service will process this token format as a DATA key encrypted by the importer key and a null (all zero) control vector. importer_key_identifier Direction: Input/Output Type: String A 64-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: Input/Output Type: String A 64-byte string variable containing a null key token or an internal key token. The key token receives the imported key. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. If a skeleton key token is provided as input to this parameter, the wrapping method in the skeleton token will be used. Otherwise, the system default key wrapping method will be used to wrap the token. Chapter 5. Managing Symmetric Cryptographic Keys 115 Data Key Import Restrictions For existing TKE V3.1 (or higher) users, you may have to explicitly enable new access control points. Current applications will fail 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. This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. This service does not adjust the key parity of the source key. CDMF/DES token markings will be ignored. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 17. Required access control points for Data key import | Access Control Point Restrictions | Data Key Import - Unrestricted None | | Data Key Import Key-encrypting key may not have equal key halves | | | To use a NOCV key-encrypting key with the data key import service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 18. Data key import required hardware Server Required cryptographic hardware IBM Eserver zSeries PCI Cryptographic 900 Coprocessor IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 116 Crypto Express3 Coprocessor z/OS V1R13 ICSF Application Programmer's Guide Restrictions Does not support triple length DATA keys. Diversified Key Generate Diversified Key Generate (CSNBDKG and CSNEDKG) Use the diversified key generate service 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 service, specify: 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 may 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 A key generation method keyword. Some keywords require Requires May 2004 or later version of Licensed Internal Code (LIC) or a z890. This service generates diversified keys as follows: v Determines if it can support the process specified in 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. The callable service name for AMODE(64) invocation is CSNEDKG. Format CALL 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) Chapter 5. Managing Symmetric Cryptographic Keys 117 Diversified Key Generate Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The only valid value is 1, 2, or 3. rule_array Direction: Input Type: String Keywords that provide control information to the callable service. The processing method is the algorithm used to create the generated 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. Table 19. Rule Array Keywords for Diversified Key Generate Keyword Meaning Processing Method for generating or updating diversified keys (required) 118 z/OS V1R13 ICSF Application Programmer's Guide Diversified Key Generate Table 19. Rule Array Keywords for Diversified Key Generate (continued) Keyword Meaning CLR8-ENC Specifies that 8-bytes of clear data shall be multiply encrypted with the generating key. The generating_key_identifier must be a KEYGENKY key type with bit 19 of the control vector set to 1. The control vector in generated_key_identifier must specify a single-length key. The key type may be DATA, MAC, or MACVER. Note: CIPHER class keys are not supported. SESS-XOR Modifies an existing DATA, DATAC, MAC, DATAM, or MACVER, DATAMV single- or double-length key. Specifies the VISA method for session key generation. Data supplied may be 8 or 16 bytes of data depending on whether the generating_key_identifier is a single or double length key. The 8 or 16 bytes of data is XORed with the clear value of the generating_key_identifier. The generated_key_identifier has the same control vector as the generating_key_identifier. The generating_key_identifier may be DATA/DATAC, MAC/DATAM or MACVER/DATAMV key types. TDES-DEC Data supplied may be 8 or 16 bytes of clear data. If the generated_key_identifier specifies a single length key, then 8-bytes of data is TDES decrypted under the generating_key_identifier. If the generated_key_identifier specifies a double length key, then 16-bytes of data is TDES ECB mode decrypted under the generating_key_identifier. No formating of data is done prior to encryption. The generating_key_identifier must be a DKYGENKY key type, with appropriate usage bits for the desired generated key. TDES-ENC Data supplied may be 8 or 16 bytes of clear data. If the generated_key_identifier specifies a single length key, then 8-bytes of data is TDES encrypted under the generating_key_identifier. If the generated_key_identifier specifies a double length key, then 16-bytes of data is TDES ECB mode encrypted under the generating_key_identifier. No formatting of data is done prior to encryption. The generating_key_identifier must be a DKYGENKY key type, with appropriate usage bits for the desired generated key. The generated_key_identifier may be a single or double length key with a CV that is permitted by the generating_key_identifier. TDES-XOR Requires Requires May 2004 or later version of Licensed Internal Code (LIC). It combines the function of the existing TDES-ENC and SESS-XOR into one step. The generating key must be a level 0 DKYGENKY and cannot have replicated halves. The session key generated must be double length and the allowed key types are DATA, DATAC, MAC, MACVER, DATAM, DATAMV, SMPIN and SMKEY. Key type must be allowed by the generating key control vector. Chapter 5. Managing Symmetric Cryptographic Keys 119 Diversified Key Generate Table 19. Rule Array Keywords for Diversified Key Generate (continued) Keyword Meaning TDESEMV2 Requires Requires May 2004 or later version of Licensed Internal Code (LIC): supports generation of a session key by the EMV 2000 algorithm (This EMV2000 algorithm uses a branch factor of 2). The generating key must be a level 0 DKYGENKY and cannot have replicated halves. The session key generated must be double length and the allowed key types are DATA, DATAC, MAC, MACVER, DATAM, DATAMV, SMPIN and SMKEY. Key type must be allowed by the generating key control vector. TDESEMV4 Requires Requires May 2004 or later version of Licensed Internal Code (LIC): supports generation of a session key by the EMV 2000 algorithm (This EMV2000 algorithm uses a branch factor of 4). The generating key must be a level 0 DKYGENKY and cannot have replicated halves. The session key generated must be double length and the allowed key types are DATA, DATAC, MAC, MACVER, DATAM, DATAMV, SMPIN and SMKEY. Key type must be allowed by the generating key control vector. Key Wrapping Method (optional) USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default keyword. The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. Translation Control (optional) ENH-ONLY Restrict rewrapping of the generated_key_identifier token. Once the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. generating_key_identifier Direction: Input/Output Type: String The label or internal 64 byte token of a key that is a DKYLO, DKYGENKY or a subtype appropriate to the session key to be derived. The type of key-generating key depends on the processing method. data_length Direction: Input 120 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Diversified Key Generate The length of the data parameter that follows. Length depends on the processing method and the generated key. The data length for TDESEMV4 or TDESEMV2 is either 18 or 34. 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. For TDESEMV4 or TDESEMV2 the data is either 18 bytes (36 digits) or 34 bytes 68 digits) or data comprised of: v 16 bytes (32 digits) of card specific data used to create the card specific intermediate key (UDK) as per the TDES-ENC method. This will typically be the PAN and PAN Sequence number as per the EMV specifications v 2 bytes (4 digits) of ATC (Application Transaction Count) v (optional) 16 bytes (32 digits) of IV (Initial Value) used in the EMV 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. A null token can be supplied if the generated_key_identifier will be a DKYGENKY with a CV derived from the generating_key_identifier. A skeleton 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. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output generated_key_token will use the default method unless a rule array keyword overriding the default is specified. Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. Refer to Appendix C, “Control Vectors and Changing Control Vectors with the CVT Callable Service,” on page 827 for information on the control vector bits for the DKG key generating key. For Session key algorithm (EMV Smartcard specific), an MDK can be used in two ways: Chapter 5. Managing Symmetric Cryptographic Keys 121 Diversified Key Generate v To calculate the Card Specific Key (or UDK) in the personalization process, call this service with the TDES-ENC method using an output token that has been primed with the CV of the final session key, for instance, if the MDK is a DMPIN, the token should have the CV of an SMPIN key; DMAC; a double length MAC; DDATA, a double length DATA key, etc. The result would then be exported in the personalization file. This key is not usable in this form for any other calculations. v To use the session key, call this service with the TDESEMV4 method. Provide, for input, the same card data that was used to create the UDK as well as the ATC and optionally the IV value. This is the key that will be used in EMV related Smartcard processing. This same processing applies to those API's the generate the session key on your behalf, like CSNBPCU. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 20. Required access control points for Diversified Key Generate | Rule array keyword Access control point | CLR8-ENC Diversified Key Generate - CLR8-ENC | SESS-XOR Diversified Key Generate - SESS-XOR | TDES-DEC Diversified Key Generate - TDES-DEC | TDES-ENC Diversified Key Generate - TDES-ENC | TDES-XOR Diversified Key Generate - TDES-XOR | TDESEMV2 or TDESEMV4 Diversified Key Generate - TDESEMV2/TDESEMV4 | | | | WRAP-ECB or WRAP-ENH and Diversified Key Generate - Allow wrapping override default key-wrapping method keywords setting does not match the keyword | | | 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 – DALL access control point must also be enabled in the ICSF role. | | | | 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 by enabling the Diversified Key Generate - Single length or same halves access control point. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 21. Diversified key generate required hardware Server Required cryptographic hardware IBM Eserver zSeries PCI Cryptographic 900 Coprocessor Restrictions Keywords TDES-XOR, TDESEMV2 and TDESEMV4 are not supported. ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. 122 z/OS V1R13 ICSF Application Programmer's Guide Diversified Key Generate Table 21. Diversified key generate required hardware (continued) Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor Enhanced key token wrapping not supported. IBM System z9 EC ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. IBM System z9 BC Cryptographic Express2 Coprocessor Enhanced key token wrapping not supported. IBM System z10 EC Crypto Express2 Coprocessor ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. IBM System z10 BC Enhanced key token wrapping not supported. Crypto Express3 Coprocessor z196 | Enhanced key token wrapping not supported. Crypto Express3 Coprocessor ECC Diffie-Hellman (CSNDEDH and CSNFEDH) | | | | Use the ECC Diffie-Hellman callable service to create: v Symmetric key material from a pair of ECC keys using the Elliptic Curve Diffie-Hellman protocol and the static unified model key agreement scheme. v “Z” – The “secret” material output from D-H process. | | | | | | | Output may be one of the following forms: v Internal CCA Token (DES or AES): AES keys are in the "Variable-length Symmetric Key Token" format. DES keys are in the "DES Internal Key Token" format. | v External CCA Token (DES or AES): AES keys are in the "Variable-length Symmetric Key Token" format. DES keys are in the "DES External Key Token" format. v “Z” – The “secret” material output from D-H process. Chapter 5. Managing Symmetric Cryptographic Keys 123 ECC Diffie-Hellman | Format || | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | CALL CSNDEDH( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, private_key_identifier_length, private_key_identifier, private_KEK_key_identifier_length, private_KEK_key_identifier, public_key_identifier_length, public_key_identifier, chaining_vector_length, chaining_vector, party_identifier_length, party_identifier, key_bit_length, reserved_length, reserved, reserved2_length, reserved2, reserved3_length, reserved3, reserved4_length, reserved4, reserved5_length, reserved5, output_KEK_key_identifier_length, output_KEK_key_identifier, output_key_identifier_length, output_key_identifier) Parameters | return_code || | Direction: Output The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. | | | reason_code || | Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | | | | | exit_data_length || | Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. | | | | | Type: Integer exit_data 124 z/OS V1R13 ICSF Application Programmer's Guide ECC Diffie-Hellman || | | Direction: Input/Output Type: String The data that is passed to the installation exit. | rule_array_count || | | | Direction: Input | rule_array || | Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. Valid values are between 1 and 5. Type: String | | | The rule_array parameter is an array of keywords. 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: | Table 22. Keywords for ECC Diffie-Hellman | Keyword | Key agreement (one required) | DERIV01 Use the static unified model key agreement scheme. | PASSTHRU Skip Key derivation step and return raw “Z" material. | Transport Key Type (one optional if output KEK key identifier is present) | OKEK-DES The output KEK key identifier is a “DES” KEK token. | OKEK-AES The output KEK key identifier is a “AES” KEK token. | Output Key Type (one optional if output key identifier is present) | KEY-DES The output key identifier is a “DES” skeleton token. | KEY-AES The output key identifier is an “AES” skeleton token. | Key Wrapping Method (one optional, only supported when the output type is DES) | | | USECONFG Specifies that the configuration setting for the default wrapping method is to be used to wrap the key. This is the default. | | WRAP-ENH Specifies that the new enhanced wrapping method is to be used to wrap the key. | WRAP-ECB Specifies that the original wrapping method is to be used. | Translation Control (one optional, only supported when the output type is DES) | | | | | | | | ENH-ONLY Meaning Specify this keyword to indicate that the key once wrapped with the enhanced method cannot be wrapped with the original method. This restricts translation to the original method. If the keyword is not specified translation to the original method will be allowed. This turns on bit 56 (ENH ONLY) in the control vector. This keyword is not valid if processing a zero CV data key. | private_key_identifier_length || | | Direction: Input | | private_key_identifier Type: Integer The length of the private_key_identifier parameter. Chapter 5. Managing Symmetric Cryptographic Keys 125 ECC Diffie-Hellman || | | | | Direction: Input | private_KEK_key_identifier_length || | | | | Direction: Input | private_KEK_key_identifier || | | | | Direction: Input | public_key_identifier_length || | | Direction: Input | public_key_identifier || | | | | | | Direction: Input | chaining_vector_length || | | Direction: Input/Output | chaining_vector || | | Direction: Input/Output | party_identifier_length || | | | | Direction: Input/Output | party_identifier || | | | | Direction: Input/Output Type: String The private_key_identifier must contain an internal or an external token or a label of an internal or external ECC key. The ECC key token must contain a public-private key pair. Clear keys will be accepted. Type: Integer The length of the private_KEK_key_identifier in bytes. The maximum value is 900. If the private_key_identifier contains an internal ECC token this value must be a zero. Type: String The private_KEK_key_identifier must contain a KEK key token, the label of a KEK key token, or a null token. The KEK key token must be present if the private_key_identifier contains an external ECC token. Type: Integer The length of the public_key_identifier. Type: String The public_key_identifier parameter must contain an ECC public token or the label of an ECC Public token. The public_key_identifier specifies the other party’s ECC public key which is enabled for key management functions. If the public_key_identifier identifies a token containing a public-private key pair, no attempt to decrypt the private part will be made. Type: Integer The chaining_vector_length parameter must be zero. Type: String The chaining_vector parameter is ignored. Type: Integer The length of the party_identifier parameter. Valid values are 0, or between 8 and 64. The party_identifier_length must be 0 when the PASSTHRU rule array keyword is specified. Type: String The party_identifier parameter contains the entity identifier information. This information should contain the both entities data according to NIST SP800-56A Section 5.8 when the DERIV01 rule array keyword is specified. 126 z/OS V1R13 ICSF Application Programmer's Guide ECC Diffie-Hellman | key_bit_length || | | | | Direction: Input/Output | reserved_length || | | Direction: Input/Output | reserved || | | Direction: Input/Output | reserved2_length || | | Direction: Input/Output | reserved2 || | | Direction: Input/Output | reserved3_length || | | Direction: Input/Output | reserved3 || | | Direction: Input/Output | reserved4_length || | | Direction: Input/Output | reserved4 || | | Direction: Input/Output | reserved5_length || | | Direction: Input/Output | reserved5 || | | Direction: Input/Output Type: Integer The key bit length parameter contains the number of bits of key material to derive and place in the provided key token. The value must be 0 if the PASSTHRU rule array keyword was specified. Otherwise it must be 64 - 2048. Type: Integer The reserved_length parameter must be zero. Type: String This parameter is ignored. Type: Integer The reserved2_length parameter must be zero. Type: String This parameter is ignored. Type: Integer The reserved3_length parameter must be zero. Type: String This parameter is ignored. Type: Integer The reserved4_length parameter must be zero. Type: String This parameter is ignored. Type: Integer The reserved5_length parameter must be zero. Type: String This parameter is ignored. Chapter 5. Managing Symmetric Cryptographic Keys 127 ECC Diffie-Hellman | output_KEK_key_identifier_length || | | | | Direction: Input | output_KEK_key_identifier || | | | | Direction: Input Type: Integer The length of the output_KEK_key_identifier. The maximum value is 900. The output_KEK_key_identifier_length must be zero if output_key_identifier will contain an internal token or if the PASSTHRU rule array keyword was specified. Type: String The output_KEK_key_identifier contains a KEK key token or the label of a KEK key if the output_key_identifier will contain an external ECC token. Otherwise this field is ignored. If the output KEK key identifier identifies a DES KEK, then it must be an IMPORTER or an EXPORTER key type, and have the export bit set. The XLATE bit is not checked. If the output KEK key identifier identifies an AES KEK, then it must be either an IMPORTER or an EXPORTER key type and have the export/import bit set in key usage field 1 and the derivation bit set in key usage field 4. | | | | | | | output_key_identifier_length || | | | | | Direction: Input/Output | output_key_identifier || | | | Direction: Output Type: Integer The length of the output_key_identifier. The service checks the field to ensure it is at least equal to the size of the token to return. On return from this service, this field is updated with the exact length of the key token created. The maximum allowed value is 900 bytes. Type: String On input, the output_key_identifier must contain a skeleton token or a null token. | | | On output, the output_key_identifier will contain: v An internal or an external key token containing the generated symmetric key material. | v “Z” data (in the clear) if the PASSTHRU rule array keyword was specified. | | | | If this variable specifies an external DES key token then the output KEK key identifier must identify a DES KEK key token. If this specifies an external key token other than a DES key token then the output KEK key identifier must identify an AES KEK key token. | Restrictions | | The NIST security strength requirements will be enforced, with respect to ECC Curve type (input) and derived key length. | | | | | | Only the following key types will be generated, skeleton key tokens of any other type will fail. v DES: (Legacy DES token) – CIPHER – DECIPHER – ENCIPHER 128 z/OS V1R13 ICSF Application Programmer's Guide ECC Diffie-Hellman – IMPORTER – EXPORTER – IMP-PKA v AES – DATA (Legacy AES token) | | | | | – – – – | | | | | CIPHER (Variable-length symmetric key-token) KEK (Variable-length symmetric key-token) IMPORTER (Variable-length symmetric key-token) EXPORTER (Variable-length symmetric key-token) Usage Notes | | SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | | The ECC Diffie-Hellman callable service requires the ECC Diffie-Hellman Callable Service access control point to be enabled in the active role. | | | Specifying the PASSTHRU rule array keyword requires that the ECC Diffie-Hellman – Allow PASSTHRU access control point be enabled in the active role. | | | If the output_key_identifier parameter references a DES key token and the wrapping method specified in not the default method, then the ECC Diffie-Hellman – Allow key wrap override access control point must be enabled in the active role. | | This table lists the valid key bit lengths and the minimum curve size required for each of the supported output key types. | | Table 23. Valid key bit lengths and minimum curve size required for the supported output key types. | Output Key ID type Valid Key Bit Lengths Minimum Curve Required | DES 64 P160 | 128 P160 | 192 P224 128 P256 | 192 P384 | | 256 P512 | | | | | | | | | | | AES The following access control points control the function of this service. Note that each Elliptic Curve type supported has its own access control point. v ECC Diffie-Hellman Callable Service v ECC Diffie-Hellman – Allow PASSTHRU v v v v v v ECC ECC ECC ECC ECC ECC Diffie-Hellman Diffie-Hellman Diffie-Hellman Diffie-Hellman Diffie-Hellman Diffie-Hellman – Allow – Allow – Allow – Allow – Allow – Allow key wrap override Prime Curve 192 Prime Curve 224 Prime Curve 256 Prime Curve 384 Prime Curve 521 Chapter 5. Managing Symmetric Cryptographic Keys 129 ECC Diffie-Hellman | | | | | v v v v v ECC ECC ECC ECC ECC Diffie-Hellman Diffie-Hellman Diffie-Hellman Diffie-Hellman Diffie-Hellman – Allow – Allow – Allow – Allow – Allow BP BP BP BP BP Curve Curve Curve Curve Curve | | | | v v v v ECC Diffie-Hellman – Allow BP Curve 384 ECC Diffie-Hellman – Allow BP Curve 512 ECC Diffie-Hellman – Prohibit weak key generate Variable-length Symmetric Token - disallow weak wrap | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. | Table 24. ECC Diffie-Hellman required hardware | | | Server | | IBM Eserver zSeries 900 This callable service is not supported. | | IBM Eserver zSeries 990 This callable service is not supported. | | IBM Eserver zSeries 890 | IBM System z9 EC | IBM System z9 BC | IBM System z10 EC | IBM System z10 BC | | | z196 Required cryptographic hardware 160 192 224 256 320 Restrictions This callable service is not supported. This callable service is not supported. Crypto Express3 Coprocessor | | | | ECC Clear Key and Internal tokens support requires the Sep. 2010 licensed internal code (LIC). ECC External and Diffie-Hellman support requires Sep. 2011 licensed internal code (LIC). | Key Export (CSNBKEX and CSNEKEX) Use the key export callable service to reencipher any type of key (except an AKEK or an IMP-PKA) from encryption under a master key variant to encryption under the same variant of an exporter key-encrypting key. The reenciphered key can be exported to another system. If the key to be exported is a DATA key, the key export service generates a key token with the same key length as the input token's key. This service supports the no-export bit that the prohibit export service sets in the internal token. The callable service name for AMODE(64) invocation is CSNEKEX. 130 z/OS V1R13 ICSF Application Programmer's Guide Key Export Format CALL CSNBKEX( return_code, reason_code, exit_data_length, exit_data, key_type, source_key_identifier, exporter_key_identifier, target_key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_type Direction: Input Type: Character 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, ICSF determines the key type from the control vector (CV) field in the internal key token provided in the source_key_identifier parameter. If the control vector is invalid on the Cryptographic Coprocessor Feature, the key export request will be routed to the PCI Cryptographic Coprocessor. Chapter 5. Managing Symmetric Cryptographic Keys 131 Key Export Key type values for the Key Export callable service are: CIPHER, DATA, DATAC, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACD, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER. For information on the meaning of the key types, see Table 3 on page 23. source_key_identifier Direction: Input Type: String A 64-byte string of the internal key token that contains the key to be reenciphered. This parameter must identify an internal key token in application storage, or a label of an existing key in the cryptographic key data set. If you supply TOKEN for the key_type parameter, ICSF looks 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 cryptographic key data set. exporter_key_identifier Direction: Input/Output Type: String A 64-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 cryptographic key data set. 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. For example, the key has been installed in the cryptographic key data set through the key generator utility program or the key entry hardware using the NOCV parameter; or you are passing the key-encrypting key in the internal key token with the NOCV bit on and your program is running in supervisor state or in key 0-7. Control vectors are explained in “Control Vector for DES Keys” on page 19 and the NOCV bit is shown in Table 335 on page 778. target_key_identifier Direction: Output Type: String The 64-byte field external key token that contains the reenciphered key. The reenciphered key can be exchanged with another cryptographic system. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output target_key_identifier will be wrapped in the same manner as the source_key_identifier. Restrictions For existing TKE V3.1 (or higher) users, you may have to explicitly enable new access control points. Current applications will fail 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. 132 z/OS V1R13 ICSF Application Programmer's Guide Key Export This service cannot be used to export AKEKs. Refer to “ANSI X9.17 Key Export (CSNAKEX and CSNGKEX)” on page 635 for information on exporting AKEKs. This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. For key export, you can use these combinations of parameters: v A valid 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 A key_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 labelname is unique on the CKDS. The key type is extracted from the control vector contained in the internal key token. v A valid 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 reenciphered. 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 reenciphered. Therefore, assume both keys have been reenciphered. Systems with the Cryptographic Coprocessor Feature. ICSF examines the data encryption algorithm bits on the exporter key-encrypting key and the key being exported for consistency. It does not export a CDMF key under a DES-marked key-encrypting key or a DES key under a CDMF-marked key-encrypting key. ICSF does not propagate the data encryption marking on the operational key to the external token. If the key type is MACD, the control vectors of the input keys must be the standard control vectors supported by the Cryptographic Coprocessor Feature, since the key export service will be processed on the Cryptographic Coprocessor Feature in this case. To use NOCV key-encrypting keys or to export double-length DATAM and DATAMV keys, the NOCV-enablement keys must be installed in the CKDS. NOCV-enablement keys are only needed with the Cryptographic Coprocessor Feature. For a double-length MAC key with a key type of DATAM, the service uses the data compatibility control vector to create an external token. For a double-length MAC key with a key type of MACD, the service uses the single-length control vector for both the left and right half of the key to create an external token (MAC||MAC). For a table of control vectors, refer to Control Vector Table. Key Export operations which specify a NOCV key-encrypting key as the exporter key and also specify a source or key-encrypting key which contains a control vector not supported by the Cryptographic Coprocessor Feature will fail. Chapter 5. Managing Symmetric Cryptographic Keys 133 Key Export To export a double-length MAC generation or MAC verification key, it is recommended that a key type of TOKEN be used. Systems with a PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor If running with a PCIXCC, CEX2C, or CEX3C, 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. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 25. Required access control points for Key Export | Access Control Point Restrictions | Key Export - Unrestricted None | | Key Export Key-encrypting key may not have equal key halves | | | To use a NOCV key-encrypting key with the key export service, the NOCV KEK usage for export-related functions access control point must be enabled in addition to one or both of the access control points listed. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 26. Key export required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature PCI Cryptographic Coprocessor Restrictions Key_type MACD is processed on a Cryptographic Coprocessor Feature. DATAC key type is not supported. ICSF routes the request to a PCI Cryptographic Coprocessor if: v The key_type specified is one of these: DECIPHER, ENCIPHER, IKEYXLAT, OKEYXLAT or CIPHER. v The control vector of either the exporter_key_identifier or the source_key_identifier cannot be processed on the Cryptographic Coprocessor Feature. v Token markings for DES/CDMF on DATA and KEKs are ignored. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC 134 z/OS V1R13 ICSF Application Programmer's Guide Key_type MACD and DATAXLAT are not supported. Token markings for DES/CDMF on DATA and KEKs are ignored. Key_type MACD and DATAXLAT are not supported. Token markings for DES/CDMF on DATA and KEKs are ignored. Key Export Table 26. Key export required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z10 EC Crypto Express2 Coprocessor Key_type MACD and DATAXLAT are not supported. Token markings for DES/CDMF on DATA and KEKs are ignored. IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Key_type MACD and DATAXLAT are not supported. Token markings for DES/CDMF on DATA and KEKs are ignored. Key Generate (CSNBKGN and CSNEKGN) Use the key generate callable service to generate either one or two odd parity DES keys of any type. The keys can be single-length (8 bytes), double-length (16 bytes), or, in the case of DATA keys, triple-length (24 bytes). The callable service 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. Use the key generate callable service to generate an AES key of DATA type. The callable service does not produce AES keys in clear form and all AES keys are returned in encrypted form. Only one AES key is generated. It's clear value is not exposed outside the secure cryptographic feature. The callable service name for AMODE (64) invocation is CSNEKGN. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Chapter 5. Managing Symmetric Cryptographic Keys 135 Key Generate Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_form Direction: Input Type: Character string A 4-byte keyword that defines the type of key(s) you want to generate. 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 first two characters refer to key_type_1. The next two characters refer to key_type_2. These keywords are allowed: OP, IM, EX, OPIM, OPEX, IMEX, EXEX, OPOP, and IMIM. See Table 27 for their meanings. If the key_form is OP, EX or IM, the KEK_key_identifier_2, generated_key_identifier_1 and generated_key_identifier_2 should be set to NULL. Table 27. Key Form Values for the Key Generate Callable Service 136 Keyword Meaning EX One key that can be sent to another system. EXEX A key pair; both keys to be sent elsewhere, possibly for exporting to two different systems. The key pair has the same clear value. IM One key that can be locally imported. The key can be imported onto this system to make it operational at another time. IMEX A key pair to be imported; one key to be imported locally and one key to be sent elsewhere. Both keys have the same clear value. IMIM A key pair to be imported; both keys to be imported locally at another time. OP One operational key. The key is returned to the caller in the key token format. Specify the OP key form when generating AKEKs and AES keys. z/OS V1R13 ICSF Application Programmer's Guide Key Generate Table 27. Key Form Values for the Key Generate Callable Service (continued) Keyword Meaning OPEX A key pair; one key that is operational and one key to be sent from this system. Both keys have the same clear value. OPIM A key pair; one key that is operational and one key to be imported to the local system. Both keys have the same clear value. On the other system, the external key token can be imported to make it operational. OPOP A key pair; normally with different control vector values. 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. For AKEKs, the result is placed in a skeleton token created by the key token build callable service. AES AKEKs are not supported. 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 ICSF callable service. 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 Table 34 for valid key combinations. key_length Direction: Input Type: Character string An 8-byte value that defines the length of the key. 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. Table 28. Key Length Values for the Key Generate Callable Service Value Description Algorithm SINGLE, SINGLE-R or KEYLN8 The key should be a single length (8-byte or 64-bit) key. DES DOUBLE or KEYLN16 The key should be a double length (16-byte or 128-bit) key AES or DES KEYLN24 The key should be a 24-byte (192-bit) key. AES or DES KEYLN32 The key should be a 32-byte (256-bit) key. AES DES Keys: 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 Chapter 5. Managing Symmetric Cryptographic Keys 137 Key Generate same value to be used in both key halves (refered to as replicated key values), specify key_length as SINGLE, SINGLE-R or KEYLN8. If you want different values to be the basis of each key half, specify key_length as DOUBLE or KEYLN16. Triple-length (24-byte) keys have three 8-byte key parts. This key length is valid for DATA keys only. To generate a triple-length DATA key with three different values to be the basis of each key part, specify key_length as KEYLN24. Use SINGLE/SINGLE-R if you want to create a DES transport key that you would use to exchange DATA keys 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 an AKEK, the key_length parameter is ignored. The AKEK key length (8-byte or 16-byte) is determined by the skeleton token created by the key token build callable service and provided in the generated_key_identifier_1 parameter. Note: SINGLE-R is not supported on IBM Eserver zSeries 900 servers. AES Keys: AES only allows KEYLN16, KEYLN24, KEYLN32. To generate a 128-bit AES key, specify key_length as KEYLN16. For 192-bit AES keys specify key_length as KENLN24. A 256-bit AES key requires a key_length of KEYLN32. All AES keys are DATA keys. Systems with CCFs (with or without PCICCs): This table shows the valid key lengths for each key type supported by DES keys. An X indicates that a key length is permitted for a key type. A Y indicates that the key generated will be a double-length key with replicated key values. Note: When generating a double-length key with replicated key values and the key_form parameter as IMEX, the KEK_key_identifier_1 parameter must contain a NOCV IMPORTER key-encrypting key either as a key label or an internal key token. Also the CKDS must contain NOCV enablement keys. Table 29. Key lengths for DES keys - CCF systems Key Type Single - KEYLN8 MAC MACVER X X DATA X DATAM DATAMV 138 Double - KEYLN16 KEYLN24 X X X X EXPORTER IMPORTER Y Y X X IKEYXLAT OKEYXLAT Y Y X X CIPHER# DECIPHER# ENCIPHER# X X X IPINENC OPINENC PINGEN PINVER Y Y Y Y z/OS V1R13 ICSF Application Programmer's Guide X X X X Key Generate Table 29. Key lengths for DES keys - CCF systems (continued) CVARDEC*# CVARENC*# CVARPINE*# CVARXCVL*# CVARXCVR*# X X X X X X X X X X DKYGENKY*# KEYGENKY*# Y X X X Notes: 1. * — 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 2. # — key types marked with a pound sign (#) require a PCICC Systems with PCIXCCs/CEX2C/CEX3C: This table shows the valid key lengths for each key type supported by DES keys. An X indicates that a key length is permitted for a key type. A Y 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. Table 30. Key lengths for DES keys - PCIXCC/CEX2C/CEX3C systems Key Type Single KEYLN8 Single-R MAC MACVER X X X X DATA X X DATAC* DATAM DATAMV Double KEYLN16 KEYLN24 X X X X EXPORTER IMPORTER Y Y X X X X IKEYXLAT OKEYXLAT Y Y X X X X CIPHER DECIPHER ENCIPHER X X X IPINENC OPINENC PINGEN PINVER Y Y Y Y CVARDEC* CVARENC* CVARPINE* CVARXCVL* CVARXCVR* X X X X X DKYGENKY* KEYGENKY* X X X X X X X X X X X X X X X X X X X X X This table shows the valid key lengths for each key type supported by AES keys. An X indicates that a key length is permitted for that key type. Chapter 5. Managing Symmetric Cryptographic Keys 139 Key Generate Table 31. Key lengths for AES keys - CEX2C/CEX3C systems Key Type 128-byte 192-byte 256-byte AESTOKEN AESDATA X X X X X X key_type_1 Direction: Input Type: Character 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 AESDATA, AESTOKEN, CIPHER, DATA, DATAC, 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 Table 3 on page 23. If key_type_1 is TOKEN, ICSF examines the control vector (CV) field in the generated_key_identifier_1 parameter to derive the key type. When key_type_1 is TOKEN, ICSF does not check for the length of the key for DATA keys. Instead, ICSF uses the key_length parameter to determine the length of the key. To generate a DES AKEK, specify a key_type_1 of TOKEN. The generated_key_identifier_1 parameter must be a skeleton token of an AKEK created by the Key Token Build callable service. The token cannot be a partially notarized AKEK or an AKEK key part. If key_type_1 is AESDATA or AESTOKEN, the key generated will be an AES key of type DATA. When key_type_1 is AESTOKEN, ICSF uses the key_length parameter to determine the length of the key. See Table 33 and Table 34 for valid key type and key form combinations. key_type_2 Direction: Input Type: Character string Use the key_type_2 parameter for a key pair, which is shown in Table 34 on page 144. The keyword must be left-justified and padded with blanks. Valid type combinations depend on the key form. key_type_2 is only used when DES keys are generated. key_type_2 is only use when DES keys are generated. The 8-byte keyword for the key_type_2 parameter can be one of the following: v CIPHER, DATA, DATAC, 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 Description of Key Types, Table 3 on page 23. If key_type_2 is TOKEN, ICSF examines the control vector (CV) field in the generated_key_identifier_2 parameter to derive the key type. When key_type_2 140 z/OS V1R13 ICSF Application Programmer's Guide Key Generate is TOKEN, ICSF does not check for the length of the key for DATA keys. Instead, ICSF uses the key_length parameter to determine the length of the key. If only one key is to be generated, key_type_2 and KEK_key_identifier_2 are ignored. See Table 33 on page 144 and Table 34 on page 144 for valid key type and key form combinations. KEK_key_identifier_1 Direction: Input/Output Type: String A 64-byte string of a DES 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. When key_form OP is used, parameters KEK_key_identifier_1 and KEK_key_identifier_2 are ignored. In this case, it is recommended that the parameters are initialized to 64-bytes of X'00'. 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. For example, the key has been installed in the cryptographic key data set through the key generator utility program or the key entry hardware using the NOCV parameter; or you are passing the key-encrypting key in the internal key token with the NOCV bit on and your program is running in supervisor state or key 0-7. Control vectors are explained in “Control Vector for DES Keys” on page 19 and the NOCV bit is shown in Table 335 on page 778. KEK_key_identifier_1 cannot be an AES key token or label. KEK_key_identifier_2 Direction: Input/Output Type: String A 64-byte string of a DES 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. When key_form OP is used, parameter KEK_key_identifier_2 is ignored. In this case, it is recommended that the parameter is initialized to 64-bytes of X'00'. 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. For example, the key has been installed in the cryptographic key data set through the key generator utility program or the key entry hardware using the NOCV parameter; or you are passing the key-encrypting key in the internal key token with the NOCV bit on and your program is running in supervisor state or in key 0-7. Control vectors are explained in “Control Vector for DES Keys” on page 19 and the NOCV bit is shown in Table 335 on page 778. KEK_key_identifier_2 cannot be an AES key token or label. generated_key_identifier_1 Chapter 5. Managing Symmetric Cryptographic Keys 141 Key Generate Direction: Input/Output Type: String This parameter specifies either a generated: v Internal DES or AES key token for an operational key form, or v External DES key tokens 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 DES 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 DES internal token of the SAME type, the NOCV bit, if on, is propagated to the generated key token. When generating an AKEK, specify the skeleton key token created by the Key Token Build callable service as input for this parameter. When key_type_1 parameter is AESDATA, then generated_key_identifier_1 is ignored. In this case, it is recommended that the parameter be initialized to 64-bytes of X'00'. If you specify a key_type_1 of AESTOKEN, the generated_key_identifier_1 parameter must be an internal AES key token or a clear AES key token. Information in this token can be used to determine the key type: v The key_type_1 parameter overrides the type in the token. v The key_length parameter overrides the length value in the generated key token. | | ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output generated_key_identifier_1 will use the default wrapping method unless a skeleton token is supplied as input. If a skeleton token is supplied as input, the wrapping method in the skeleton token will be used. 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. When key_type_1 parameter is AESDATA or AESTOKEN, then generated_key_identifier_2 is ignored. In this case, it is recommended that the parameters are initialized to 64-bytes of X'00'. 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. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output generated_key_identifier_2 will use the default wrapping method unless a skeleton token is supplied as input. If a skeleton token is supplied as input, the wrapping method in the skeleton token will be used. 142 z/OS V1R13 ICSF Application Programmer's Guide Key Generate Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. System Encryption Algorithm Marks (CCF systems only) This applies to requests processed on a system with CCFs and only if the request is processed by the CCF. Processing on a PCICC does not cause tokens to be marked. Internal DATA, IMPORTER and EXPORTER tokens are marked with the system encryption algorithm. No external tokens generated by this service are marked. When the key form is OP, the token is marked with the system default algorithm. This marking can be overridden by specifing a valid token in the generated_key_identifer_1 parameter with the marking required. When the key form is OPEX or OPIM, the operational token is marked with the markings of the key-encrypting key (KEK_key_identifier_2). This marking can be overridden by specifing a valid token in the generated_key_identifer_1 parameter with the marking required. It is possible to generate an operational DES-marked DATA key on a CDMF-only system or a CDMF-marked DATA key on a DES-only system. However, the Encipher and Decipher callable services fail when you use these keys on the systems where they were generated unless overridden by keyword. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 32. Required access control points for Key Generate | Usage Access Control Point | | | | The key-form and key-type combinations shown with an 'X' in the Key_Form OP column in Table 33 on page 144. Key Generate – OP | | | | The key-form and key-type combinations shown with an 'X' in the Key_Form IM column in Table 33 on page 144. Key Generate – Key set | | | | The key-form and key-type combinations shown with an 'X 'in the Key_Form EX column in Table 33 on page 144. Key Generate - Key set | | | The key-form and key-type combinations shown with an 'X' in Table 34 on page 144 Key Generate - Key set | | | The key-form and key-type combinations shown with an 'E' in Table 34 on page 144 Key Generate - Key set extended Chapter 5. Managing Symmetric Cryptographic Keys 143 Key Generate | Table 32. Required access control points for Key Generate (continued) | Usage Access Control Point | | | The SINGLE-R key-length keyword is specified Key Generate - SINGLE-R | | | To use a NOCV IMPORTER key-encrypting key with the key generate service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed. | | | To use a NOCV EXPORTER key-encrypting key with the key generate service, the NOCV KEK usage for export-related functions access control point must be enabled in addition to one or both of the access control points listed. Key type and key form combinations Table 33 shows the valid key type and key form combinations for a single DES or AES 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. Note: Not all keytypes are valid on all hardware. See Table 3 on page 23. Table 33. Key Generate Valid Key Types and Key Forms for a Single Key Key Type 1 Key Type 2 OP IM EX AESDATA Not applicable X AESTOKEN Not applicable X DATA Not applicable X X X DATAC* Not applicable X X X DATAM Not applicable X X X DKYGENKY* Not applicable X X X KEYGENKY* Not applicable X X X MAC Not applicable X X X PINGEN Not applicable X X X Table 34 shows the valid key type and key form combinations for a DES 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. Table 34. Key Generate Valid Key Types and Key Forms for a Key Pair OPEX EXEX OPIM, OPOP, IMIM IMEX CIPHER X X X X CIPHER DECIPHER X X X X CIPHER ENCIPHER X X X X | CVARDEC* CVARENC* E E | CVARDEC* CVARPINE* E E | CVARENC* CVARDEC* E E | CVARENC* CVARXCVL* E E 144 Key Type 1 Key Type 2 CIPHER z/OS V1R13 ICSF Application Programmer's Guide Key Generate Table 34. Key Generate Valid Key Types and Key Forms for a Key Pair (continued) Key Type 1 Key Type 2 OPEX | CVARENC* CVARXCVR* E E | CVARXCVL* CVARENC* E E | CVARXCVR* CVARENC* E E | CVARPINE* CVARDEC* E E DATA DATA X X DATA DATAXLAT X X DATAC* DATAC* X X X X DATAM DATAM X X X X DATAM DATAMV X X X X DATAXLAT DATAXLAT 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 IPINENC OPINENC X X E 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 OPINENC OPINENC PINVER PINGEN X X X PINGEN PINVER X X X | | EXEX OPIM, OPOP, IMIM IMEX X X X X X E X X If you are running with the Cryptographic Coprocessor Feature and the key_form is IMEX, the key_length is SINGLE, and key_type_1 is IPINENC, OPINENC, PINGEN, IMPORTER, or EXPORTER, you must specify the KEK_key_identifier_1 parameter as NOCV IMPORTER If you are running with the Cryptographic Coprocessor Feature and need to use NOCV key-encrypting keys, NOCV-enablement keys must be installed in the CKDS. If you running with the PCI X Cryptographic Coprocessor, Crypto Express2 Chapter 5. Managing Symmetric Cryptographic Keys 145 Key Generate Coprocessor, or Crypto Express3 Coprocessor and need to use NOCV key-encrypting keys, you need to enable NOCV IMPORTER and NOCV EXPORTER access control points If you are running with the Cryptographic Coprocessor Feature and need to generate DATAM and DATAMV keys in the importable form, the ANSI system keys must be installed in the CKDS. Table 35 lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 35. Key generate required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions OPIM is valid on the Cryptographic Coprocessor Feature for key forms DATA/DATA, DATAM/DATAM and MAC/MAC. All other OPIM key forms are routed to the PCI Cryptographic Coprocessor. In key_form and generated_key_identifier_1, marking of data encryption algorithm bits and token copying are only performed if this service is proccessed on a Cryptographic Coprocessor Feature. In KEK_key_identifier_2 propagation of token markings is only relevant when this service is processed on the Cryptographic Coprocessor Feature. In generated_key_identifier_1, propagation of the NOCV bit is performed only if the service is processed on the Cryptographic Coprocessor Feature. AKEKs are processed on CCFs DATAC is not supported. Secure AES keys are not supported. PCI Cryptographic Coprocessor ICSF routes the request to a PCI Cryptographic Coprocessor if: v OPIM key forms are not DATA/DATA, DATAM/DATAM or MAC/MAC. v The key type specified in key_type_1 or key_type_2 is not valid for the Cryptographic Coprocessor Feature or if the control vector in a supplied token cannot be processed on the Cryptographic Coprocessor Feature. v A key length of SINGLE-R is specified, or if a key form of OPIM, OPOP or IMIM is specified. v Tokens are not marked with the system encryption algorithm. The NOCV flag is not propagated to key-encrypting keys. Secure AES keys are not supported. 146 z/OS V1R13 ICSF Application Programmer's Guide Key Generate Table 35. Key generate required hardware (continued) Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor Key_type DATAXLAT is not supported. AKEK key type is not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor Secure AES keys are not supported. IBM System z9 EC Key_type DATAXLAT is not supported. Crypto Express2 Coprocessor IBM System z9 BC AKEK key type is not supported. Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). IBM System z10 EC IBM System z10 BC Crypto Express2 Coprocessor Key_type DATAXLAT is not supported. AKEK key type is not supported. Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). Key_type DATAXLAT is not supported. AKEK key type is not supported. Key Generate2 (CSNBKGN2 and CSNEKGN2) Use the Key Generate2 callable service to generate either one or two keys of any type. This callable service 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 service returns variable-length CCA key tokens and uses the AESKW wrapping method. | | This service supports HMAC and AES keys. Operational keys will be encrypted under the AES master key. The callable service name for AMODE(64) is CSNEKGN2. Chapter 5. Managing Symmetric Cryptographic Keys 147 Key Generate2 Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. 148 z/OS V1R13 ICSF Application Programmer's Guide Key Generate2 rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value must be 2. rule_array Direction: Input Type: String The rule_array contains keywords that provide control information to the callable service. 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. | Table 36. Keywords for Key Generate2 Control Information | Keyword | Token algorithm (required) | HMAC Specifies to generate an HMAC key token. | AES Specifies to generate an AES key token. | Key Form (required) | | The first two characters refer to key_type_1. The next two characters refer to key_type_2. See the Usage Notes section for further details. | EX One key that can be sent to another system. | | | EXEX A key pair; both keys to be sent elsewhere, possibly for exporting to two different systems. Both keys have the same clear value. | | | IM One key that can be locally imported. The key can be imported onto this system to make it operational at another time. | | | IMEX A key pair to be imported; one key to be imported locally and one key to be sent elsewhere. Both keys have the same clear value. | | IMIM A key pair to be imported; both keys to be imported locally at another time. Both keys have the same clear value. | | OP One operational key. The key is returned to the caller in operational form to be used locally. | | OPEX A key pair; one key that is operational and one key to be sent elsewhere. Both keys have the same clear value. | | | OPIM A key pair; one key that is operational and one key to be imported locally at another time. Both keys have the same clear value. | | | | OPOP A key pair; either with the same key type with different associated data or complementary key types. Both keys have the same clear value. | clear_key_bit_length || | Direction: Input | | Meaning Type: Integer The size (in bits) of the key to be generated. v For the HMAC algorithm, this is a value between 80 and 2048, inclusive. Chapter 5. Managing Symmetric Cryptographic Keys 149 Key Generate2 | v For the AES algorithm, this is a value of 128, 192, or 256. | | | When key_type_1 or key_type_2 is TOKEN, this value overrides the key length contained in generated_key_identifier_1 or generated_key_identifier_2, respectively. 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, and are documented in Table 39 on page 154 and Table 40 on page 154. | | | | The 8-byte keyword for the key_type_1 parameter can be one of the following: | Table 37. Keywords and associated algorithms for key_type_1 parameter | Keyword Algorithm | CIPHER AES | EXPORTER AES | IMPORTER AES | MAC HMAC | MACVER HMAC | | | Specify the keyword TOKEN when supplying a key token in the generated_key_identifier_1 parameter. | | If key_type_1 is TOKEN, the associated data in the generated_key_identifier_1 parameter is examined 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 Table 40 on page 154. 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: | Table 38. Keywords and associated algorithms for key_type_2 parameter | Keyword Algorithm | CIPHER AES | EXPORTER AES | IMPORTER AES | MAC HMAC | MACVER HMAC | | | Specify the keyword TOKEN when supplying a key token in the generated_key_identifier_2 parameter. | | If key_type_2 is TOKEN, the associated data in the generated_key_identifier_2 parameter is examined to derive the key type. When only one key is being generated, this parameter is ignored. 150 z/OS V1R13 ICSF Application Programmer's Guide Key Generate2 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 bytes. key_name_1 Direction: Input Type: String A 64-byte key store label to be stored in the associated data structure of generated_key_identifier_1. key_name_2_length Direction: Input Type: Integer The length of the key_name parameter for generated_key_identifier_2. Valid values are 0 and 64 bytes. | When only one key is being generated, this parameter is ignored. key_name_2 Direction: Input Type: String A 64-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 to 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 to 255 bytes. | When only one key is being generated, this parameter is ignored. user_associated_data_2 Direction: Input Type: String Chapter 5. Managing Symmetric Cryptographic Keys 151 Key Generate2 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 length of the buffer for key_encrypting_key_identifier_1 in bytes. When the Key Form rule is OP, OPOP, OPIM, or OPEX, this length must be zero. When the Key Form rule is EX, EXEX, IM, IMEX, or IMIM, the value must be between the actual length of the token and 725 bytes when key_encrypting_key_identifier_1 is a token. | The value must be 64 bytes when key_encrypting_key_identifier_1 is a label. | key_encrypting_key_identifier_1 || | Direction: Input/Output Type: String | | | When key_encrypting_key_identifier_1_length is zero, this parameter is ignored. Otherwise, key_encrypting_key_identifier_1 contains an internal key token containing the AES importer or exporter key-encrypting key, or a key label. | | If the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key. | key_encrypting_key_identifier_2_length || | Direction: Input Type: Integer | | | | | The length of the buffer for key_encrypting_key_identifier_2 in bytes. When the Key Form rule is OPOP, this length must be zero. When the Key Form rule is EXEX, IMEX, IMIM, OPIM, or OPEX, the value must be between the actual length of the token and 725 when key_encrypting_key_identifier_2 is a token. The value must be 64 when key_encrypting_key_identifier_2 is a label. | When only one key is being generated, this parameter is ignored. | key_encrypting_key_identifier_2 || | Direction: Input/Output Type: String | | | When key_encrypting_key_identifier_2_length is zero, this parameter is ignored. Otherwise, key_encrypting_key_identifier_2 contains an internal key token containing the AES importer or exporter key-encrypting key, or a key label. | | If the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key. | When only one key is being generated, 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 maximum value is 900 bytes. | On output, the parameter will hold the actual length of the generated_key_identifier_1. 152 z/OS V1R13 ICSF Application Programmer's Guide Key Generate2 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. 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 maximum value is 900 bytes. | | On output, the parameter will hold the actual length of the generated_key_identifier_2. | When only one key is being generated, this parameter is ignored. 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. 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. Usage Notes 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. The corresponding key_encrypting_key_identifier_x parameter must contain an AES IMPORTER key token or label. | | | | | Exportable (EX) The key value is enciphered under an exporter key-encrypting key. The result is placed into an external key token. The corresponding key_encrypting_key_identifier_x parameter must contain an AES EXPORTER key token or label. | These tables list the valid key type and key form combinations. Chapter 5. Managing Symmetric Cryptographic Keys 153 Key Generate2 | Table 39. Key Generate2 valid key type and key form for one key | key_type_1 Key Form OP, IM, EX | CIPHER X | | MAC X | Table 40. Key Generate2 Valid key type and key forms for two keys | | key_type_1 key_type_2 Key Form OPOP, OPIM, IMIM Key Form OPEX, EXEX, IMEX | CIPHER CIPHER X X | MAC MAC X X | MAC MACVER X X | MACVER MAC X X | IMPORTER EXPORTER X | | EXPORTER IMPORTER X | | | | | | | | | | | | If an AES KEK is used, the strength of the KEK expected by Key Generate2 depends on the attributes of the key being generated. The resulting return code and reason code when using a KEK that is weaker depends on the “Variable-length Symmetric Token - disallow weak wrap” and “Variable-length Symmetric Token warn when weak wrap” access control points: v If the “disallow" access control point is disabled (the default), the key strength requirement will not be enforced. Using a weaker key will result in return code 0 with a non-zero reason code if the “warn” access control point is enabled. Otherwise, a reason code of zero will be returned. v If the “disallow” access control point is enabled (using TKE), the key strength requirement will be enforced, and attempting to use a weaker key will result in return code 8. | | For AES keys, the AES KEK must be at least as strong as the key being generated to be considered sufficient strength. | | For HMAC keys, the AES KEK must be sufficient strength as described in the following table. | Table 41. AES KEK strength required for generating an HMAC key under an AES KEK | | Key-usage field 2 in the HMAC key contains Minimum strength of AES KEK to adequately protect the HMAC key | SHA-256, SHA-384, SHA-512 256 bits | SHA-224 192 bits | | SHA-1 128 bits The following table shows the access control points in the ICSF role that control the function of this service. | Table 42. Required access control points for Key Generate2 | Access Control Point Function control | Key Generate2 – OP Key Form OP, EX, IM | Key Generate2 – Key set Key Form OPOP, OPIM, IMIM, OPEX, EXEX, IMEX 154 z/OS V1R13 ICSF Application Programmer's Guide Key Generate2 | Table 42. Required access control points for Key Generate2 (continued) | Access Control Point Function control | | Variable-length Symmetric Token disallow weak wrap Prohibit wrapping a key with a weaker key | | | Variable-length Symmetric Token warn when weak wrap Issue a non-zero reason code when using a weak wrapping key | | | Note that both the “Variable-length Symmetric Token - disallow weak wrap” and “Variable-length Symmetric Token - warn when weak wrap” access control points are disabled in the default role. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 43. Key Generate2 required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC | | z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. Crypto Express3 Coprocessor AES key support require the Sep. 2011 or later licensed internal code (LIC). | | HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). Key Import (CSNBKIM and CSNEKIM) Use the key import callable service to reencipher a key (except an AKEK) from encryption under an importer key-encrypting key to encryption under the master key. The reenciphered key is in operational form. Choose one of these 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. Chapter 5. Managing Symmetric Cryptographic Keys 155 Key Import 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 DATA keys, this service generates a key of the same length as that contained in the input token. The callable service name for AMODE(64) invocation is CSNEKIM. Format CALL CSNBKIM( return_code, reason_code, exit_data_length, exit_data, key_type, source_key_identifier, importer_key_identifier, target_key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_type Direction: Input 156 z/OS V1R13 ICSF Application Programmer's Guide Type: Character string Key Import The type of key you want to reencipher 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, ICSF determines 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 is NOCV. Supported key_type values are CIPHER, DATA, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IPINENC, MAC, MACVER, OKEXLAT, OPINENC, PINGEN and PINVER. Use key_type TOKEN for all other key types. For information on the meaning of the key types, see Table 3 on page 23. We recommend using key type of TOKEN when importing double-length MAC and MACVER keys. source_key_identifier Direction: Input Type: String The key you want to reencipher 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 DATA keys. Refer to Table 338 on page 782. If key type is TOKEN, this field may not specify a null token. This service 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 reenciphered 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. Chapter 5. Managing Symmetric Cryptographic Keys 157 Key Import Note: Propagation of the NOCV bit is performed only if the service is processed on a Cryptographic Coprocessor Feature or on a PCIXCC, CEX2C, or CEX3C. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output target_key_identifier will use the default wrapping method unless a skeleton token is supplied as input. If a skeleton token is supplied as input, the wrapping method in the skeleton token will be used. Restrictions For existing TKE V3.1 (or higher) users, you may have to explicitly enable new access control points. Current applications will fail 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. This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. Use of NOCV keys are controlled by an access control point in the PCIXCC. Creation of NOCV key-encrypting keys is only available for standard IMPORTERs and EXPORTERs. Systems with the Cryptographic Coprocessor Feature The key import callable service cannot be used to import ANSI key-encrypting keys. For information on importing these types of keys, refer to “ANSI X9.17 Key Import (CSNAKIM and CSNGKIM)” on page 640. To use NOCV key-encrypting keys or to import DATAM or DATAMV keys, NOCV-enablement keys must be installed in the CKDS. This service will mark an imported KEK as a NOCV-KEK by suppling a valid IMPORTER or EXPORTER token in the target_key_identifier field with the NOCV-KEK flag enabled. The type of the token must match the key type of the imported key. This service will mark DATA and key-encrypting key tokens with the system encryption algorithm if the request is processed on the CCF. The service propagates the data encryption algorithm mark on the operational KEK unless token copying overrides this: v The imported token is marked with the DES or CDMF encryption algorithm marks of the KEK token v The imported token is marked with the system's default encryption algorithm when the KEK is marked SYS-ENC v To override the encryption algorithm marks of the KEK, supply a valid token in the target_key_identifier field of the same key type being imported. The mark of the target_key_identifier token are used to mark the imported key token. 158 z/OS V1R13 ICSF Application Programmer's Guide Key Import Key Import operations which specify a NOCV key-encrypting key as either the importer key or the target and also specify a source or key-encrypting key which contains a control vector not supported by the Cryptographic Coprocessor Feature will fail. Systems with the PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor Use of NOCV keys are controlled by an access control point in the PCIXCC, CEX2C, or CEX3C. This service will mark an imported KEK as a NOCV-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. 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 PCIXCC, CEX2C, or CEX3C. The internal token for an export prohibited key will have the appropriate control vector that prohibits export. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 44. Required access control points for Key Import | Access Control Point Restrictions | Key Import - Unrestricted None | | Key Import Key-encrypting key may not have equal key halves | | | To use a NOCV key-encrypting key with the key import service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 5. Managing Symmetric Cryptographic Keys 159 Key Import Table 45. Key import required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions Propagation of token markings is only relevant when this service is processed on the Cryptographic Coprocessor Feature. If the key_type is MACD or IMP-PKA, the control vectors of supplied internal tokens must all be supported by the Cryptographic Coprocessor Feature, since processing for these key types will not be routed to a PCI Cryptographic Coprocessor. DATAC is not supported. Key_type CIPHER, DECIPHER and ENCIPHER require a PCICC. PCI Cryptographic Coprocessor ICSF routes the request to a PCI Cryptographic Coprocessor if: v The key_type cannot be processed on the Cryptographic Coprocessor Feature. v The control vector of the source_key_identifier or the importer_key_identifier cannot be processed on the Cryptographic Coprocessor Feature. IBM Eserver zSeries PCI X Cryptographic Coprocessor 990 IBM Eserver zSeries Crypto Express2 Coprocessor 890 Key_type DATAXLAT is not supported. DES and CDMF markings are not made on DATA and key-encrypting keys and are ignored on the IMPORTER key-encrypting key. IMP-PKA keys are not supported. IBM System z9 EC IBM System z9 BC Crypto Express2 Coprocessor Key_type DATAXLAT is not supported. DES and CDMF markings are not made on DATA and key-encrypting keys and are ignored on the IMPORTER key-encrypting key. IMP-PKA keys are not supported. IBM System z10 EC Crypto Express2 Coprocessor Key_type DATAXLAT is not supported. DES and CDMF markings are not made on DATA and key-encrypting keys and are ignored on the IMPORTER key-encrypting key. IMP-PKA keys are not supported. IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Key_type DATAXLAT is not supported. DES and CDMF markings are not made on DATA and key-encrypting keys and are ignored on the IMPORTER key-encrypting key. IMP-PKA keys are not supported. Key Part Import (CSNBKPI and CSNEKPI) Use the key part import callable service to combine, by exclusive ORing, 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 CKDS. 160 z/OS V1R13 ICSF Application Programmer's Guide Key Part Import Prior to using the key part import service for the first key part, you must use the key token build service 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 CKDS. 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 other service. 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 the ADD-PART and COMPLETE keywords in lieu of the MIDDLE and LAST keywords in order to ensure a separation of responsibilities between someone who can add key-part information and someone who can declare that appropriate information has been accumulated in a key. The key part import callable service can also be used to import a key without using key parts. Call the key part import service FIRST with key part value X'0000...' then call the key part import service LAST with the complete value. Keys created via this service have odd parity. The FIRST key part is adjusted to odd parity. All subsequent key parts are adjusted to even parity prior to being combined. The callable service name for AMODE(64) invocation is CSNEKPI. Format CALL CSNBKPI( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, key_part, key_identifier) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. Chapter 5. Managing Symmetric Cryptographic Keys 161 Key Part Import exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value must be 1 or 2. rule_array Direction: Input Type: String Keywords that provide control information to the callable service. 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. Table 46. Keywords for Key Part Import Control Information Keyword Meaning Key Part (Required) FIRST This keyword specifies that an initial key part is being entered. The callable service returns this key-part encrypted by the master key in the key token that you supplied. ADD-PART This keyword specifies that additional key-part information is provided. COMPLETE This keyword specifies that the key-part bit shall be turned off in the control vector of the key rendering the key fully operational. Note that no key-part information is added to the key with this keyword. MIDDLE This keyword specifies that an intermediate key part, which is neither the first key part nor the last key part, is being entered. Note that the command control point for this keyword is the same as that for the LAST keyword and different from that for the ADD-PART keyword. LAST This keyword specifies that the last key part is being entered. The key-part bit is turned off in the control vector. Key Wrapping Method (optional) 162 z/OS V1R13 ICSF Application Programmer's Guide Key Part Import Table 46. Keywords for Key Part Import Control Information (continued) Keyword Meaning USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default keyword. The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. key_part Direction: Input Type: String A 16-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 A 64-byte field containing an internal token or a label of an existing CKDS record. 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 the label of a CKDS 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 CKDS record. The returned key_identifier will be encrypted under the current master key. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output key_identifier will use the default method unless a rule array keyword overriding the default for the FIRST key part is specified. When the key_identifier is an existing token, the same wrapping method as the existing token will be used. Restrictions If a label is specified on key_identifier, the label must be unique. If more than one record is found, the service fails. For existing TKE V3.1 (or higher) users, you may have to explicitly enable new access control points. You must have access control point 'Key Part Import Unrestricted' explicitly enabled. Otherwise, current applications will fail with either of these conditions: v the first 8 bytes of key identifier is different than the second 8 bytes AND the first 8 bytes of the combined key are the same as the last second 8 bytes Chapter 5. Managing Symmetric Cryptographic Keys 163 Key Part Import v the first 8 bytes of key identifier is the same as the second 8 bytes AND the first 8 bytes of the combined key are different than the second 8 bytes. This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes If you are running with the Cryptographic Coprocessor Feature, this service requires that the ANSI system keys be installed on the CKDS. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 47. Required access control points for Key Part Import | Rule array keyword Access control point | FIRST Key Part Import - first key part | MIDDLE or LAST Key Part Import - middle and last | ADD-PART Key Part Import - ADD-PART | COMPLETE Key Part Import - COMPLETE | | | | WRAP-ECB or WRAP-ENH and default key-wrapping method setting does not match keyword Key Part Import - Allow wrapping override keywords | | | | | A “replicated key-halves” key (both cleartext halves of a double-length key are equal) is not as secure as a double-length key with key halves that are not the same. The key part import service verb enforces the key-halves restriction documented above when the Key Part Import - Unrestricted access control point is disabled in the ICSF role. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 48. Key part import required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions Only key type AKEK is supported ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. PCI Cryptographic Coprocessor ICSF routes all requests to the PCI Cryptographic Coprocessor except for key type of AKEK. AKEK is always processed on the Cryptographic Coprocessor Feature. Key type AKEK is not supported. ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor 164 z/OS V1R13 ICSF Application Programmer's Guide AKEK key types are not supported. ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. Key Part Import Table 48. Key part import required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z9 EC Crypto Express2 Coprocessor AKEK key types are not supported. IBM System z9 BC IBM System z10 EC ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. Crypto Express2 Coprocessor IBM System z10 BC ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. Crypto Express3 Coprocessor z196 AKEK key types are not supported. Enhanced key token wrapping not supported. Crypto Express3 Coprocessor Related Information This service is consistent with the Transaction Security System key part import verb. Key Part Import2 (CSNBKPI2 and CSNEKPI2) Use the Key Part Import2 callable service to combine, by exclusive ORing, the clear key parts of any key type and return the combined key value either in a variable-length internal token or as an update to the CKDS. Prior to using the key part import2 service for the first key part, you must use the Key Token Build2 service 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 CKDS. 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 callable service to ensure a correct key value has been accumulated prior to using the COMPLETE option to mark the key as fully operational. The callable service name for AMODE(64) is CSNEKPI2. Chapter 5. Managing Symmetric Cryptographic Keys 165 Key Part Import2 Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 2 or 3. rule_array Direction: Input 166 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Key Part Import2 The rule_array contains keywords that provide control information to the callable service. 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. Table 49. Keywords for Key Part Import2 Control Information Keyword Meaning Token Algorithm (Required) | HMAC Specifies to import an HMAC key token. AES Specifies to import an AES key token. Key Part (One required) FIRST This keyword specifies that an initial key part is being entered. The callable service returns this key-part encrypted by the master key in the key token that you supplied. ADD-PART This keyword specifies that additional key-part information is provided. COMPLETE This keyword specifies that the key-part bit shall be turned off in the control vector of the key rendering the key fully operational. Note that no key-part information is added to the key with this keyword. Split Knowledge (One required). Use only with FIRST keyword. MIN3PART Specifies that the key must be entered in at least three parts. MIN2PART Specifies that the key must be entered in at least two parts. MIN1PART Specifies that the key must be entered in at least one part. 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. For FIRST and ADD-PART keywords, valid values are 80 to 2048 for HMAC keys or 128, 192, or 256 for AES keys. The 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 bytes. 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 bytes. The output token will be longer when the first key part is imported. Chapter 5. Managing Symmetric Cryptographic Keys 167 Key Part Import2 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 CKDS record. If the Key Part rule is FIRST, the key is a skeleton token. If the Key Part rule is ADD-PART, this is an internal token or the label of a CKDS 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 CKDS record. The returned key_identifier will be encrypted under the current master key. | | 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 the ADD-PART keyword, the service exclusive-ORs the clear key-part with the key value in the input key-token. Use of the ADD-PART keyword requires that an Add 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. The following table shows the access control points in the default role that control the function of this service. Table 50. Required access control points for Key Part Import2 Rule array keywords Access control point ADD-PART Key Part Import2 - Add second of three or more key parts ADD-PART Key Part Import2 - Add last required key part ADD-PART Key Part Import2 - Add optional key part COMPLETE Key Part Import2 - Complete key FIRST MIN3PART Key Part Import2 - Load first key part, require 3 key parts FIRST MIN2PART Key Part Import2 - Load first key part, require 2 key parts FIRST MIN1PART Key Part Import2 - Load first key part, require 1 key parts This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 51. Key Part Import2 required hardware Server Required cryptographic hardware IBM Eserver zSeries 900 168 z/OS V1R13 ICSF Application Programmer's Guide Restrictions This service is not supported. Key Part Import2 Table 51. Key Part Import2 required hardware (continued) Server Required cryptographic hardware Restrictions IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC | | z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. Crypto Express3 Coprocessor AES key support requires the Sep. 2011 or later licensed internal code (LIC). | | HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). Key Test (CSNBKYT and CSNEKYT) Use the key test callable service to generate or verify a secure, cryptographic verification pattern for keys. The key to test can be in the clear or encrypted under the master key. Keywords in the rule_array specify whether the callable service generates or verifies a verification pattern. DES keys use the algorithm defined in “DES Algorithm (single- and double-length keys)” on page 889 as the default algorithm (except for triple-length DATA keys). When generating a verification pattern, the service generates a random number and calculates the verification pattern. The random number and verification pattern are returned to the caller. When verifying a key, the random number and key are used to verify the verification pattern. AES keys use the SHA-256 algorithm as the default algorithm. An 8-byte verification pattern is generated for the key specified. The random number parameter is not used. The optional ENC-ZERO algorithm can be used with any key. A 4-byte verification pattern is generated. The random number parameter is not used. CSNBKYT is consistent with the Transaction Security System verb of the same name. If you generate a key on the Transaction Security System, you can verify it on ICSF and vice versa. See “Key Test Extended (CSNBKYTX and CSNEKTX)” on page 178 to verify the value of a DES key encrypted using a KEK. The callable service name for AMODE(64) invocation is CSNEKYT. Chapter 5. Managing Symmetric Cryptographic Keys 169 Key Test Format CALL CSNBKYT( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, key_identifier, random_number, verification_pattern) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value can be 2, 3 or 4. rule_array Direction: Input 170 z/OS V1R13 ICSF Application Programmer's Guide Type: String Key Test Keywords provide control information to the callable service. Table 52 lists the keywords. 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. Table 52. Keywords for Key Test Control Information Keyword Meaning Key or key part rule (one keyword required) CLR-A128 Process a 128–bit AES clear key. CLR-A192 Process a 192–bit AES clear key. CLR-A256 Process a 256–bit AES clear key. KEY-CLR Specifies the key supplied in key_identifier is a single-length clear key. KEY-CLRD Specifies the key supplied in key_identifier is a double-length clear key. KEY-ENC Specifies the key supplied in key_identifier is a single-length encrypted key. KEY-ENCD Specifies the key supplied in key_identifier is a double-length encrypted key. TOKEN Process an AES clear or encrypted key token. Process Rule (one keyword required) GENERATE Generate a verification pattern for the key supplied in key_identifier. VERIFY Verify a verification pattern for the key supplied in key_identifier. Parity Adjustment - can not be specified with any of the AES keywords (optional) ADJUST Adjust the parity of test key to odd prior to generating or verifying the verification pattern. The key_identifier field itself is not adjusted. NOADJUST Do not adjust the parity of test key to odd prior to generating or verifying the verification pattern. This is the default. Verification Process Rule (optional) ENC-ZERO ENC-ZERO can be used with any of the rules. It is not supported on systems with CCFs. SHA-256 Use the 'SHA-256' method. Use with CLR-A128, CLR-A192, CLR-A256, and TOKEN. SHA-256 is also the default for the AES rules. 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 on the CKDS. random_number Chapter 5. Managing Symmetric Cryptographic Keys 171 Key Test 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. random_number is only used with the default algorithm for DES operational keys. 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. Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. 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. With a PCIXCC, CEX2C, or CEX3C, there is support for the generation and verification of single, double and triple-length keys for the ENC-ZERO verification process. 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 ICSF, 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. The access control point in the ICSF role that controls the function of this service is Key Test and Key Test 2. This access control point cannot be disabled. It is required for ICSF master key validation. | | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. 172 z/OS V1R13 ICSF Application Programmer's Guide Key Test Table 53. Key test required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Triple-length DATA keys are not supported. AES keys are not supported. PCI Cryptographic Coprocessor Triple-length DATA keys are not supported. ICSF routes the request to a PCI Cryptographic Coprocessor if: v ANSI enablement keys are not installed in the CKDS. v Verification process rule ENC-ZERO is specified. AES keys are not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. AES keys are not supported. Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. Key Test2 (CSNBKYT2 and CSNEKYT2) | | | | Use this callable service to generate or verify a secure, cryptographic verification pattern for keys. The key to test can be in the clear, encrypted under the master key, or encrypted under a key-encrypting key. Keywords in the rule_array specify whether the callable service generates or verifies a verification pattern. The callable service name for AMODE(64) invocation is CSNEKYT2. Chapter 5. Managing Symmetric Cryptographic Keys 173 Key Test2 Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value must be 2, 3, 4, or 5. rule_array 174 z/OS V1R13 ICSF Application Programmer's Guide Key Test2 || | Direction: Input Type: String The rule_array contains keywords that provide control information to the callable service. 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. Table 54. Keywords for Key Test2 Control Information Keyword Meaning Token algorithm (Required) | AES Specifies the key token is an AES key token. | | | DES Specifies the key token is a DES token. CCA internal, CCA external, and TR-31 token types are supported. Clear keys are not supported for this rule. HMAC Specifies the key token is an HMAC key token. Process rule (One required) GENERATE Generate a verification pattern for the specified key. VERIFY Verify that a verification pattern matches the specified key. | Verification pattern calculation algorithm (Optional) | | ENC-ZERO | | | | | | Verification pattern for AES and DES keys calculated by encrypting a data block filled with 0x00 bytes. This is the default and only method available for DES. This method is only available for AES if Access Control Point "Key Test2 - AES, ENC-ZERO" is enabled. SHA-256 | | | | Verification pattern will be calculated for an AES token using the same method as the Key Test service with the SHA-256 rule. This rule can be used to verify that the same key value is present in a version 4 DATA token and version 5 AES CIPHER token or to verify that the same key value is present in a version 5 AES IMPORTER/EXPORTER pair. | | | | SHA2VP1 | | Token type rule (Required if TR-31 token passed and Token algorithm DES is specified; not valid otherwise) | TR-31 | KEK identifier rules (Optional - see defaults) | | | IKEK-AES The wrapping KEK for the key to test is an AES KEK. This is the default for AES and HMAC Token algorithms, and is not allowed with DES. | | | IKEK-DES The wrapping KEK for the key to test is a DES KEK. This is the default for DES Token algorithm, and is only allowed with DES Token algorithm. | | | | | IKEK-PKA The wrapping KEK for the key to test is an RSA or (other key stored in PKA key storage.) This is not the default for any Token algorithm and must be specified if an RSA KEK is used. This rule is not allowed with DES Token algorithm. Specifies to use the SHA-256 based verification pattern calculation algorithm. For more information, see “SHAVP1 Algorithm” on page 889. This is the default and only method available for HMAC. Specifies that key_identifier contains a TR-31 key block. Chapter 5. Managing Symmetric Cryptographic Keys 175 Key Test2 key_identifier_length Direction: Input Type: Integer The length of the key_identifier in bytes. The maximum value is 9992. | | key_identifier || | Direction: Input Type: String | | | | The key for which to generate or verify the verification pattern. This is an internal or external token or the 64-byte label of a key in the CKDS. This token may be a DES internal or external token, AES internal version ‘04’X token, internal or external variable-length symmetric token, or a TR-31 key block. | Clear DES tokens are not supported. | | If an internal token was supplied and was encrypted under the old master key, the token will be returned encrypted under the current master key. key_encrypting_key_identifier_length Direction: Input Type: Integer | | The length of the key_encrypting_key_identifier parameter. When key_identifier is an internal token, the value must be zero. | | | | | | If key_encrypting_key_identifier is a label for either the CKDS (IKEK-AES or IKEK-DES rules) or PKDS (IKEK-PKA rule), the value must be 64. If key_encrypting_key_identifier is an AES KEK, the value must be between the actual length of the token and 725. If key_encrypting_key_identifier is a DES KEK, the value must be 64. If key_encrypting_key_identifier is an RSA KEK, the maximum length is 3500. key_encrypting_key_identifier Direction: Input/Output Type: String | | | When key_encrypting_key_identifier_length is non-zero, key_encrypting_key_identifier contains an internal key token containing the key-encrypting key, or a key label. | | If the key identifier supplied was an AES or DES token encrypted under the old master key, the token will be returned encrypted under the current master key. reserved_length Direction: Input Type: Integer The length of the reserved parameter. The value must be zero. | reserved Direction: Input/Output Type: String This parameter is ignored. verification_pattern_length Direction: Input/Output 176 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Key Test2 The 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. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS. 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 access control point in the ICSF role that controls the function of this service is Key Test and Key Test 2. This access control point cannot be disabled. It is required for ICSF master key validation. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 55. Key Test2 required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC | | | | | IBM System z10 BC z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. Crypto Express3 Coprocessor DES/AES key support requires the Sep. 2011 or later licensed internal code (LIC). HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). Chapter 5. Managing Symmetric Cryptographic Keys 177 Key Test Extended Key Test Extended (CSNBKYTX and CSNEKTX) Use the key test extended service to generate or verify a secure, cryptographic verification pattern for keys. The key to test can be in the clear or encrypted under the master key. The callable service also supports keys encrypted under a key-encrypting key (KEK). AES keys are not supported by this service. Keywords in the rule array specify whether the callable service generates or verifies a verification pattern. This algorithm is supported for encrypted single and double length keys. Single, double and triple length keys are also supported with the ENC-ZERO algorithm. When the service generates a verification pattern, it creates and cryptographically processes a random number. The service returns the random number with the verification pattern. When the service tests a verification pattern against a key, you must supply the random number and the verification pattern from a previous call to key test extended. The service returns the verification result in the return and reason codes. The callable service name for AMODE(64) invocation is CSNEKTX. Format CALL CSNBKYTX( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, key_identifier, random_number, verification_pattern, KEK_key_identifier) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output 178 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Key Test Extended The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value can be 2, 3 or 4. rule_array Direction: Input Type: String Two or three keywords that provide control information to the callable service. Table 56 lists the keywords. The keywords must be in 16 or 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. Table 56. Keywords for Key Test Extended Control Information Keyword Meaning Key Rule (required) KEY-ENC Specifies the key supplied in key_identifier is a single-length encrypted DES key. KEY-ENCD Specifies the key supplied in key_identifier is a double-length encrypted DES key. Process Rule (required) GENERATE Generate a verification pattern for the key supplied in key_identifier. VERIFY Verify a verification pattern for the key supplied in key_identifier. Parity Adjustment (optional) ADJUST Adjust the parity of test key to odd prior to generating or verifying the verification pattern. The key_identifier field itself is not adjusted. NOADJUST Do not adjust the parity of test key to odd prior to generating or verifying the verification pattern. This is the default. Verification Process Rule (optional) ENC-ZERO Specifies use of the "encrypted zeros" method. 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 or key label that is left-justified. Chapter 5. Managing Symmetric Cryptographic Keys 179 Key Test Extended Note: If you supply a key label for this parameter, it must be unique on the CKDS. 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. 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. KEK_key_identifier Direction: Input/Output Type: String If key_identifier is an external token, then this is a 64-byte string of an internal token or a key label of an IMPORTER or EXPORTER used to encrypt the test key. If key_identifier is an internal token, then the parameter is ignored. Note: If you supply a key label for this parameter, it must be unique on the CKDS. Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. 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. With a PCIXCC, CEX2C, or CEX3C and using the ENC-ZERO verification rule, there is support for enciphered single and double-length DES keys. There is no support for systems with CCF's. The access control point in the ICSF role that controls the function of this service is Key Test and Key Test 2. This access control point cannot be disabled. It is required for ICSF master key validation. | | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. 180 z/OS V1R13 ICSF Application Programmer's Guide Key Test Extended Table 57. Key test extended required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Triple-length DATA keys are not supported. The key test extended callable service is processed on the Cryptographic Coprocessor Feature. Rule_array keyword ENC-ZERO is not valid. AES keys are not supported. PCI Cryptographic Coprocessor Triple-length DATA keys are not supported. ICSF routes the request to a PCI Cryptographic Coprocessor if: v ANSI enablement keys are not installed in the CKDS. v Verification process rule ENC-ZERO is specified. AES keys are not supported. IBM Eserver zSeries PCI X Cryptographic Coprocessor 990 IBM Eserver zSeries Crypto Express2 Coprocessor 890 IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. AES keys are not supported. Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. AES keys are not supported. IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. AES keys are not supported. Clear triple-length keys are not supported. Encrypted triple-length keys are supported with the ENC-ZERO keyword only. Key Token Build (CSNBKTB and CSNEKTB) Use the key token build callable service to build an external or internal key token from information which you supply. The token can be used as input for the key generate and key part import callable services. You can specify a control vector or the service can build a control vector based upon the key type you specify and the control vector-related keywords in the rule array. ICSF supports the building of an internal key token with the key encrypted under a master key other than the current master key and building internal clear AES and DES tokens. The callable service name for AMODE(64) invocation is CSNEKTB. Chapter 5. Managing Symmetric Cryptographic Keys 181 Key Token Build Format CALL CSNBKTB( return_code, reason_code, exit_data_length, exit_data, key_token, key_type, rule_array_count, rule_array, key_value, master_key_version_number, key_register_number, token_data_1, control_vector, initialization_vector, pad_character, cryptographic_period_start, master_key_verification_pattern) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Ignored Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | exit_data Direction: Ignored Type: String This field is ignored. key_token Direction: Input/Output Type: String If the key_type parameter is TOKEN, then this is a 64-byte internal token that is updated as specified in the rule_array. The internal token must be a DATA, IMPORTER or EXPORTER key type. Otherwise this field is an output-only field. key_type 182 z/OS V1R13 ICSF Application Programmer's Guide Key Token Build Direction: Input Type: String An 8-byte field that specifies the type of key you want to build or the keyword TOKEN for updating a supplied token. The key types are: Table 58. Key type keywords for key token build Key type Description Algorithm AKEK See Table 3 on page 23. DES CIPHER See Table 3 on page 23. DES CLRAES The key_token parameter is a clear AES token. The rule_array must contain the keyword INTERNAL and one of the optional keywords: KEYLN16, KEYLN24 or KEYLN32. A key value parameter must also be provided. AES CLRDES The key_token parameter is a clear DES token. The rule_array must contain the keyword INTERNAL and one of the optional keywords: KEYLN8, KEYLN16 or KEYLN24. A key value parameter must also be provided. DES CVARDEC, CVARENC, CVARPINE, CVARXCVL, CVARXCVR See Table 3 on page 23. DES DATA Valid for AES and DES keys and must be specified with the rule_array keyword AES to build an encrypted AES key token. AES and DES DATAC, DATAM, DATAMV, DATAXLAT, DECIPHER, DKYGENKY, ENCIPHER See Table 3 on page 23. DES EXPORTER If the key_type parameter is TOKEN, then this is DES a 64-byte internal token that is updated as specified in the rule_array. IKEYXLAT See Table 3 on page 23. IMPORTER If the key_type parameter is TOKEN, then this is DES a 64-byte internal token that is updated as specified in the rule_array. KEYGENKY CLR8-ENC or UKPT must be coded in rule_array parameter DES IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN, and PINVER See Table 3 on page 23. DES SECMSG SMKEY or SMPIN must be specified in the rule_array parameter. DES DES If key_type is TOKEN, then the key_token field must contain a single-length DATA key or an IMPORTER or EXPORTER key with the standard control Chapter 5. Managing Symmetric Cryptographic Keys 183 Key Token Build vector. The valid keywords for TOKEN are EXTERNAL, INTERNAL, DES and SYS-ENC. The service will set the system encryption bits in the token (byte 59, bits 0 and 1) to zero and return the token. Key type USE-CV is used when a user-supplied control vector is specified. The USE-CV key type specifies that the key type should be obtained from the control vector specified in the control_vector parameter. The CV rule array keyword should be specified if USE-CV is specified. For information on the meaning of the key types, see Table 3 on page 23. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. rule_array Direction: Input Type: String The rule_array contains keywords that provide control information to the callable service. See Table 59 for a list. 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. Table 59. Keywords for Key Token Build Control Information Keyword Meaning Algorithm Token Algorithm (optional - zero or one keyword) AES Specifies that an AES key token will be built. This keyword is required when building an encrypted AES token. It is optional when using the CLRAES key type to build a clear AES token. AES DES Specifies a DES token will be built. DES SYS-ENC Tolerated for compatibility reasons. DES Token Type (one keyword required) EXTERNAL Specifies that an external key token will be built. DES INTERNAL Specifies that an internal key token will be AES or DES built. Key Status (optional - zero or one keyword) KEY This keyword indicates that the key token AES or DES to build will contain an encrypted key. The key_value parameter identifies the field that contains the key. NO-KEY This keyword indicates that the key token to build will not contain a key. This is the default key status. AES or DES Key Length (one keyword required for AES keys) 184 KEYLN8 Single-length or 8-byte key. Default for CLRDES. DES KEYLN16 Specifies that the key is 16-bytes long. AES or DES z/OS V1R13 ICSF Application Programmer's Guide Key Token Build Table 59. Keywords for Key Token Build Control Information (continued) Keyword Meaning Algorithm KEYLN24 Specifies that the key is 24-bytes long. AES or DES KEYLN32 Specifies that the key is 32-bytes long. AES DOUBLE Double-length or 16-byte key. DES Synonymous with KEYLN16. Not valid for CLRDES. Note: See Table 61 on page 188 for valid key types for these key length values. MIXED Double-length key. Indicates that the key can either be a replicated single-length key or a double-length key with two different 8–byte values. Not valid for CLRDES. DES SINGLE Single-length or 8-byte key. Synonymous with KEYLN8. Not valid for CLRDES. DES Key Part Indicator (optional) — not valid for CLRDES KEY-PART This token is to be used as input to the key part import service. DES Control vector (CV) source (optional - zero or one of these keywords is permitted) CV This specifies that the key token should be built using the control_vector supplied in the control_vector parameter. DES NO-CV This specifies that the key token should be built using a control vector that is based on the supplied key type control vector related rule array keywords. It is the default. DES Control vector on the link specification (optional) — valid only for IMPORTER and EXPORTER. CV-KEK This keyword indicates marking the KEK as a CV KEK. The control vector is applied to the KEK prior to using it in encrypting other keys. This is the default. DES NOCV-KEK This keyword indicates marking the KEK DES as a NOCV KEK. The control vector is not applied to the KEK prior to its use in encrypting other keys. Control vector keywords (optional - zero or more of these keywords are permitted) See Table 61 on page 188 for the key-usage keywords that can be DES specified for a given key type. Master Key Verification Pattern (optional) — not valid for CLRDES or CLRAES keywords Chapter 5. Managing Symmetric Cryptographic Keys 185 Key Token Build Table 59. Keywords for Key Token Build Control Information (continued) Keyword Meaning Algorithm MKVP This keyword indicates that the key_value AES and DES is enciphered under the master key which corresponds to the master key verification pattern specified in the master_key_verification_pattern parameter. If this keyword is not specified, the key contained in the key_value field must be enciphered under the current master key. Key Wrapping Method (optional) WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. DES WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. This is the default. DES Translation Control (optional) ENH-ONLY Restrict rewrapping of the token. Once the DES token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. Can only be specified with WRAP-ENH. key_value Direction: Input Type: String If you use the KEY keyword, this parameter is a 16-byte string that contains the encrypted key value. Single-length keys must be left-justified in the field and padded on the right with X'00'. If you are building a triple-length DATA key, this parameter is a 24-byte string containing the encrypted key value. If you supply an encrypted key value and also specify INTERNAL, the service will check for the presence of the MKVP keyword. If MKVP is present, the service will assume the key_value is enciphered under the master key which corresponds to the master key verification pattern specified in the master_key_verification_pattern parameter, and will place the key into the internal token along with the verification pattern from the master_key_verification_pattern parameter. If MKVP is not specified, ICSF assumes the key is enciphered under the current host master key and places the key into an internal token along with the verification pattern for the current master key. In this case, the application must ensure that the master key has not changed since the key was generated or imported to this system. Otherwise, use of this parameter is not recommended. For key_type CLRDES and CLRAES, this field is required to contain the clear key value. For KEYLN8, this is an 8-byte field. For KEYLN16, this is a 16-byte field. For KEYLN24, this a 24-byte field. For KEYLN32, this is a 32-byte field. Table 60. Key types and field lengths for AES keys 186 Key type Field length AES-128 clear text key 16-bytes z/OS V1R13 ICSF Application Programmer's Guide Key Token Build Table 60. Key types and field lengths for AES keys (continued) Key type Field length AES-192 clear text key 24-bytes AES-256 clear text key 32-bytes AES-128, AES-192, AES-256 encrypted key 32-bytes master_key_version_number Direction: Input Type: Integer This field is examined only if the KEY keyword is specified, in which case, this field must be zero. key_register_number Direction: Input Type: Integer This field is ignored. token_data_1 Direction: Input Type: String This parameter is ignored for DES keys. This parameter is the LRC value for AES keys. For clear AES keys it is 8-bytes of X'00' indicating to the service that it must compute the LRC field value. For encrypted AES keys, you provide a 1-byte area containing the LRC value for the key passed in the key_value parameter. The service copies it into the LRC field of the key token. control_vector Direction: Input Type: String A pointer to a 16 byte string variable. When the CV rule array keyword is used, this parameter must point to a control vector which is copied into the key token. This parameter is ignored for AES keys. initialization_vector Direction: Input Type: String This field is ignored. pad_character Direction: Input Type: Integer The only allowed value for key types MAC and MACVER is 0. This field is ignored for all other key types. cryptographic_period_start Direction: Input Type: String This field is ignored. Chapter 5. Managing Symmetric Cryptographic Keys 187 Key Token Build master_key_verification_pattern Direction: Input Type: String 8-byte verification pattern of the master key used to encrypt the key value. It is used when the KEY and INTERNAL rule_array keywords are specified. The value is inserted into the master key verification pattern field of the key token. If the KEY and INTERNAL keywords are specified in rule_array, the service will check for the existence of the MKVP rule array keyword. This parameter is ignored for any other rule_array keyword combinations. Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes No pre- or post-processing or security exits are enabled for this service. No RACF checking is done, and no calls to RACF are issued when this service is used. You can use this service to create skeleton key tokens with the desired data encryption algorithm bits for use in some key management services to override the default system specifications. v If you are running with the Cryptographic Coprocessor Feature and need to generate operational AKEKs, use key_type of TOKEN and provide a skeleton AKEK key token as the generated_key_identifier_1 into the key generate service. v If you are running with the Cryptographic Coprocessor Feature, the KEY-PART AKEK key token can also be used as input to key part import service. v To create an internal token with a specified KEY value, ICSF needs to supply a valid master key verification pattern (MKVP). NOCV keyword is only supported for the standard IMPORTERs and EXPORTERs with the default CVs. This illustrates the key type and key usage keywords that can be combined in the Control Vector Generate and Key Token Build callable services to create a control vector. | Table 61. Control Vector Generate and Key Token Build Control Vector Keyword Combinations | | Key Type | | | | | | DATA SINGLE KEYLN8 MIXED DOUBLE KEYLN16 KEYLN24 XPORT-OK NO-XPORT KEY-PART | | | | | CIPHER ENCIPHER DECIPHER SINGLE KEYLN8 MIXED DOUBLE KEYLN16 XPORT-OK NO-XPORT KEY-PART ENH-ONLY 188 Key Usage z/OS V1R13 ICSF Application Programmer's Guide T31XPTOK NOT31XPT Key Token Build | Table 61. Control Vector Generate and Key Token Build Control Vector Keyword Combinations (continued) | | Key Type Key Usage | | | | | MAC MACVER ANY-MAC ANSIX9.9 CVVKEY-A CVVKEY-B AMEX-CSC | | | | | | SINGLE KEYLN8 MIXED DOUBLE KEYLN16 XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT DATAXLAT CVARPINE CVARENC CVARDEC CVARXCVL CVARXCVR SINGLE KEYLN8 XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | DATAC DATAM DATAMV DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | KEYGENKY CLR8-ENC UKPT DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | | | | | | | DKYGENKY DDATA DMAC DMV DIMP DEXP DPVR DMKEY DMPIN DALL DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | SECMSG DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | | | IKEYXLAT OKEYXLAT ANY NOT-KEK DATA PIN LMTD-KEK DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | | | IMPORTER OPIM* IMEX* IMIM* IMPORT* XLATE ANY NOT-KEK DATA PIN LMTD-KEK DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | | | EXPORTER OPEX* IMEX* EXEX* EXPORT* XLATE ANY NOT-KEK DATA PIN LMTD-KEK DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT | | | | | | | PINVER NOOFFSET DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT DKYL0 DKYL1 DKYL2 DKYL3 DKYL4 DKYL5 DKYL6 DKYL7 SMKEY SMPIN NO-SPEC** IBM-PIN** GBP-PIN** IBM-PINO GBP-PINO VISA-PVV INBK-PIN Chapter 5. Managing Symmetric Cryptographic Keys 189 Key Token Build | Table 61. Control Vector Generate and Key Token Build Control Vector Keyword Combinations (continued) | | Key Type Key Usage | | | | | | | PINGEN CPINGEN* CPINGENA* EPINGENA* EPINGEN* EPINVER* | | | | IPINENC | | | | | DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT CPINGENA* EPINVER* REFORMAT* TRANSLAT* DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT OPINENC CPINENC* EPINGEN* REFORMAT* TRANSLAT* DOUBLE KEYLN16 MIXED XPORT-OK NO-XPORT KEY-PART ENH-ONLY T31XPTOK NOT31XPT Notes: Default keys are indicated in bold. NO-SPEC** IBM-PIN** GBP-PIN** IBM-PINO GBP-PINO VISA-PVV INBK-PIN NOOFFSET | * All keywords in the list are defaults unless one or more keywords in the list are specified | | ** The NOOFFSET keyword is only valid if NO-SPEC, IBM-PIN, GBP-PIN, or the default (NO-SPEC) is specified. | | | | A key usage keyword is required for the KEYGENKY and SECMSG key types. v CLR8-ENC and/or UKPT must be specified for the KEYGENKY key type v SMKEY or SMPIN must be specified for the SECMSG key type Related Information Attention: CDMF is no longer supported. The ICSF key token build callable service provides a subset of the parameters and keywords available with the Transaction Security System key token build verb. These key types are not supported: ADATA, AMAC, CIPHERXI, CIPHERXL, CIPHERXO, UKPTBASE. These rule array keywords are not supported: ACTIVE, ADAPTER, CARD, CBC, CLEAR-IV, CUSP, INACTIVE, IPS, KEY-REF, MACLEN4, MACLEN6, MACLEN8, NO-IV, READER, X9.2, X9.9-1. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 62. Key token build required hardware Server Required cryptographic hardware IBM Eserver zSeries None. 900 190 z/OS V1R13 ICSF Application Programmer's Guide Restrictions Key Token Build Table 62. Key token build required hardware (continued) Server Required cryptographic hardware Restrictions IBM Eserver zSeries None. 990 IBM Eserver zSeries 890 IBM System z9 EC None. IBM System z9 BC IBM System z10 EC IBM System z10 BC None. z196 None. Key Token Build2 (CSNBKTB2 and CSNEKTB2) Use the Key Token Build2 callable service to build a variable-length CCA symmetric key token in application storage from information that you supply. A clear key token built by this service can be used as input for the Key Test2 callable service. A skeleton token built by this service can be used as input for the Key Generate2 and Key Part Import2 callable services. This service will build internal or external HMAC and AES tokens, both as clear key tokens and as skeleton tokens containing no key. | | The callable service name for AMODE(64) is CSNEKTB2. Format CALL 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 return_code Direction: Output Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 191 Key Token Build2 The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Ignored Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | exit_data Direction: Ignored Type: String This field is ignored. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The minimum value is 3, and the maximum value is 33. | | rule_array Direction: Input Type: Integer The rule_array contains keywords that provide control information to the callable service. 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. | Table 63. Keywords for Key Token Build2 Control Information | Keyword | Token type (one required) | EXTERNAL Specifies to build an external key token. | INTERNAL Specifies to build an internal key token. | Token algorithm (one required) | AES Specifies to build an AES key token. | HMAC Specifies to build an HMAC key token. | Key status (one, optional) | | | KEY-CLR Specifies to build the key token with a clear key value. This creates a key token that can be used with the Key Test2 service to generate a verification pattern for the key value. | | | NO-KEY Specifies to build the key token without a key value. This creates a skeleton key token that can later be supplied to the Key Generate2 service. This is the default. | Key type (one required) 192 Meaning z/OS V1R13 ICSF Application Programmer's Guide Key Token Build2 | Table 63. Keywords for Key Token Build2 Control Information (continued) | Keyword Meaning | | CIPHER Specifies that this key is for an AES CIPHER key. Only valid for AES algorithm. | | EXPORTER Specifies that this key is for an AES KEK EXPORTER. Only valid for AES algorithm. | | IMPORTER Specifies that this key is for an AES KEK IMPORTER. Only valid for AES algorithm. | | MAC Specifies that this key is for message authentication code operations. Only valid for HMAC algorithm. | Key-management related keywords | | Symmetric-key export control (one, optional) Key-management field 1 for all algorithms and key types. | NOEX-SYM Prohibits the export of the key with a symmetric key. | XPRT-SYM Permits the export of the key with a symmetric key. This is the default. | | Unauthenticated asymmetric-key export control (one, optional) Key-management field 1 for all algorithms and key types. | NOEXUASY Prohibits the export of the key with an unauthenticated asymmetric key. | | XPRTUASY Permits the export of the key with an unauthenticated asymmetric key. This is the default. | | Authenticated asymmetric-key export control (one, optional) Key-management field 1 for all algorithms and key types. | NOEXAASY Prohibits the export of the key with an authenticated asymmetric key. | | XPRTAASY Permits the export of the key with an authenticated asymmetric key. This is the default. | | RAW-format export control (one, optional) Key-management field 1 for all algorithms and key types. | NOEX-RAW Prohibits the export of the key in RAW format. This is the default. | XPRT-RAW Permits the export of the key in RAW format. | | DES-key export control (one, optional) Key-management field 1 for all algorithms, all key types. | NOEX-DES Prohibits the export of the key using DES key. | XPRT-DES Permits the export of the key using DES key. This is the default. | | AES-key export control (one, optional) Key-management field 1 for all algorithms, all key types. | NOEX-AES Prohibits the export of the key using AES key. | XPRT-AES Permits the export of the key using AES key. This is the default. | | RSA-key export control (one, optional) Key-management field 1 for all algorithms, all key types. | NOEX-RSA Prohibits the export of the key using RSA key. | XPRT-RSA Permits the export of the key using RSA key. This is the default. | Key-usage keywords (these are specific to the key type specified) | | Generate control (one required) Key-usage field 1 for HMAC algorithm, MAC key type. | | GENERATE Specifies that this key can be used to generate a MAC. A key that can generate a MAC can also verify a MAC. Chapter 5. Managing Symmetric Cryptographic Keys 193 Key Token Build2 | Table 63. Keywords for Key Token Build2 Control Information (continued) | Keyword Meaning | | VERIFY Specifies that this key cannot be used to generate a MAC. It can only be used to verify a MAC. | | | Encrypt control (optional, any combination) Key-usage field 1 for AES algorithm, CIPHER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified. | ENCRYPT Specifies that this key can be used to encipher data using the AES algorithm. | DECRYPT Specifies that this key can be used to decipher data using the AES algorithm. | | | Exporter control (any combination, optional) Key-usage field 1 for AES algorithm, EXPORTER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified. | EXPORT Specifies that this key can be used for export. | TRANSLAT Specifies that this key can be used for translate. | GEN-OPEX Specifies that this key can be used for generate OPEX. | GEN-IMEX Specifies that this key can be used for generate IMEX. | GEN-EXEX Specifies that this key can be used for generate EXEX. | GEN-PUB Specifies that this key can be used for generate PUB. | | | Importer control (any combination, optional) Key-usage field 1 for AES algorithm, IMPORTER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified. | IMPORT Specifies that this key can be used for import. | TRANSLAT Specifies that this key can be used for translate. | GEN-OPIM Specifies that this key can be used for generate OPIM. | GEN-IMEX Specifies that this key can be used for generate IMEX. | GEN-IMIM Specifies that this key can be used for generate IMIM. | GEN-PUB Specifies that this key can be used for generate PUB. | | | | User-defined extension control (any combination, optional) Low-order byte of key-usage field 1 for all algorithms and key types. Note: The default is such that the key can be used in both UDXs and CCA and none of the user-defined UDX bits are set. | UDX-ONLY Specifies that this key can only be used in UDXs. | UDX-001 Specifies that the rightmost user-defined UDX bit is set. | UDX-010 Specifies that the middle user-defined UDX bit is set. | UDX-100 Specifies that the leftmost user-defined UDX bit is set. | | | Hash method control (any combination, optional) Key-usage field 2 for HMAC algorithm, MAC key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified. | SHA-1 Specifies that the SHA-1 hash method is allowed for the key. | SHA-224 Specifies that the SHA-224 hash method is allowed for the key. | SHA-256 Specifies that the SHA-256 hash method is allowed for the key. | SHA-384 Specifies that the SHA-384 hash method is allowed for the key. | SHA-512 Specifies that the SHA-512 hash method is allowed for the key. | | Mode control (one, optional) Key-usage field 2 for AES algorithm, CIPHER key type. 194 z/OS V1R13 ICSF Application Programmer's Guide Key Token Build2 | Table 63. Keywords for Key Token Build2 Control Information (continued) | Keyword Meaning | | CBC Specifies that this key can be used for cipher block chaining. This is the default. | CFB Specifies that this key can be used for cipher feedback. | ECB Specifies that this key can be used for electronic code book. | GCM Specifies that this key can be used for Galois/counter mode. | OFB Specifies that this key can be used for output feedback. | | XTS Specifies that this key can be used for Xor-Encrypt-Xor-based Tweaked Stealing. | | | Key-encrypting key control (any combination, optional) Key-usage field 2 for AES algorithm, EXPORTER or IMPORTER key type. Note: The default is such that the key cannot export a RAW key nor wrap or unwrap a TR-31 key block. | | KEK-RAW Specifies that this key-encrypting key can export a RAW key. A RAW key is a key that is encrypted but does not have any associated data. | WR-TR31 Specifies that this key-encrypting key can wrap or unwrap a TR-31 key block | | | Key-usage wrap algorithm control (any combination, optional) Key-usage field 3 for AES algorithm, EXPORTER or IMPORTER key type. Note: Keywords WR-DES, WR-AES, and WR-HMAC are defaults unless one or more keywords are specified. | WR-DES Specifies that this key can be used to wrap DES keys. | WR-AES Specifies that this key can be used to wrap AES keys. | WR-HMAC Specifies that this key can be used to wrap HMAC keys. | WR-RSA Specifies that this key can be used to wrap RSA keys. | WR-ECC Specifies that this key can be used to wrap ECC keys. | | | Key-usage wrap class control (any combination, optional) Key-usage field 4 for AES algorithm, EXPORTER or IMPORTER key type. Note: All keywords in the list below are defaults unless one or more keywords in the list are specified. | WR-DATA Specifies that this key can be used to wrap DATA class keys. | WR-KEK Specifies that this key can be used to wrap KEK class keys. | WR-PIN Specifies that this key can be used to wrap PIN class keys. | WRDERIVE Specifies that this key can be used to wrap DERIVATION class keys. | | WR-CARD Specifies that this key can be used to wrap CARD class keys. clear_key_bit_length Direction: Input | | | | | | Type: Integer The length of the clear key in bits. Specify 0 when no key value is supplied (Key status rule NO-KEY). Specify a valid key bit length when a key value is supplied (Key status rule KEY-CLR): v For HMAC algorithm, MAC key type, this is a value between 80 and 2048. v For AES algorithm, CIPHER/EXPORTER/IMPORTER key types, this is a value of 128, 192, or 256. clear_key_value Direction: Input Type: String Chapter 5. Managing Symmetric Cryptographic Keys 195 Key Token Build2 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 A 64-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 to 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. The value must be zero. token_data Direction: Ignored Type: String This parameter is ignored. reserved_length Direction: Input Type: Integer This parameter is reserved. The value must be zero. reserved Direction: Ignored Type: String This parameter is ignored because reserved_length must be zero. 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. 196 z/OS V1R13 ICSF Application Programmer's Guide Key Token Build2 target_key_token Direction: Output Type: String The key token built by this service. Usage Notes This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 64. Key Token Build2 required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries None 900 IBM Eserver zSeries None 990 IBM Eserver zSeries 890 IBM System z9 EC None IBM System z9 BC IBM System z10 EC None IBM System z10 BC z196 None Key Translate (CSNBKTR and CSNEKTR) The Key Translate callable service 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. The callable service name for AMODE(64) invocation is CSNEKTR. Format CALL CSNBKTR( return_code, reason_code, exit_data_length, exit_data, input_key_token, input_KEK_key_identifier, output_KEK_key_identifier, output_key_token ) Chapter 5. Managing Symmetric Cryptographic Keys 197 Key Translate Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. input_key_token Direction: Input Type: String A 64-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 A 64-byte string variable containing the internal key token or the key label of an internal key token record in the CKDS. 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 A 64-byte string variable containing the internal key token or the key label of an internal key token record in the CKDS. 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. 198 z/OS V1R13 ICSF Application Programmer's Guide Key Translate output_key_token Direction: Output Type: String A 64-byte string variable containing an external key token. The external key token contains the re-enciphered key. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output_key_token will be wrapped in the same manner as the input_key_token. Restrictions Triple length DATA key tokens are not supported. This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | The Key Translate access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 65. Key translate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI Cryptographic 900 Coprocessor IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Key Translate2 (CSNBKTR2 and CSNEKTR2) | | The Key Translate2 callable service translates the input_key_token parameter in one of several ways: Chapter 5. Managing Symmetric Cryptographic Keys 199 Key Translate2 | | | | | | v Changes an external DES or variable-length symmetric key token from encipherment under one key-encrypting key to another v Changes the wrapping method of an external DES key token v Converts an operational AES DATA token (version X’04’) to an operational AES CIPHER token (version X’05’) or converts an operational AES CIPHER token (version X’05’) to an operational AES DATA token (version X’04’) | | | | | To reencipher a key token, specify the TRANSLAT rule array keyword (the default), the external key token, and the input and output key-encrypting keys. If the input_key_token is a DES key token, you can also specify which key wrapping method to use. If no wrapping method is specified, the system default wrapping method will be used. | | | | | To change the wrapping method of an external DES key token, specify the REFORMAT rule array keyword, the Key Wrapping Method to use, the external key token and the input key-encrypting key. If no wrapping method is specified, the system default wrapping method will be used. Note that the output_KEK_identifier will be ignored. | | | | | | To convert an operational AES DATA token (version X’04’) to an operational AES CIPHER token (version X’05’) or vice versa, specify the REFORMAT rule array keyword, the operational key token as input_key_token, and either a NULL token or skeleton token as output_key_token. Note that both the input_KEK_identifier and the output_KEK_identifier will be ignored as the corresponding lengths must be zero. Note: All key labels must be unique. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code 200 z/OS V1R13 ICSF Application Programmer's Guide Key Translate2 Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFFFF' (2 gigabytes). The data is defined in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input | | Type: Integer The number of keywords you supplied in the rule_array parameter. The count must be between 0 and 4, inclusive. rule_array Direction: Input Type: String Keywords that provide control information to the callable service. 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. Keyword Meaning Encipherment (optional) | | | | | | | REFORMAT | | | TRANSLAT Reformat the input_key_token. v When input_key_token is a DES key token, reformat with the Key Wrapping Method specified. v When input_key_token is an operational AES key token, either reformat an AES DATA key (version X‘04’) to an AES CIPHER key (version X‘05’) or the reverse (version X’05’ to version X’04’). Translate the input_key_token from encipherment under the input_KEK_identifier to encipherment under the output_KEK_identifier. This is the default. Key Wrapping Method (optional, valid only if input_key_token is an external DES key token) Chapter 5. Managing Symmetric Cryptographic Keys 201 Key Translate2 | | | Keyword Meaning USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default. | | | | The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. | WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens. Translation Control (optional, valid only with WRAP-ENH) ENH-ONLY Restrict rewrapping of the output_key_token. Once the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. | Algorithm (optional) | | AES Specifies that the input key is an AES key. Where used, the key-encrypting keys will be AES transport keys. | | | DES Specifies that the input key is a DES key. Where used, the key-encrypting keys will be DES transport keys. This is the default. | | HMAC Specifies that the input key is an HMAC key. Where used, the key-encrypting keys will be AES transport keys. input_key_length Direction: Input Type: Integer The length of the input_key_token in bytes. The maximum value allowed is 900. | | input_key_token || | Direction: Input/Output Type: String | | A variable length string variable containing the key token to be translated or reformatted. | | If the REFORMAT keyword is specified and the input_key_token is an AES CIPHER key (version X‘05’), the key must have the following characteristics: v Key-usage field 1 allows the key to be used for encryption and decryption and has no UDX bits set (UDX bits are not supported in version ‘04’X AES tokens) v Key-usage field 2 allows the key to be used for Cipher Block Chaining (CBC) mode or Electronic Code Book (ECB) mode | | | | | | | | | v Key-management field 1 allows export using symmetric, unauthenticated asymmetric, and authenticated asymmetric transport keys, and allows export using DES, AES, and RSA transport keys v Key-management field 2 indicates that the key is complete If the REFORMAT and AES keywords are specified and input_key_token was encrypted under the old master key, the token will be returned encrypted under the current master key. | | | 202 z/OS V1R13 ICSF Application Programmer's Guide Key Translate2 | input_KEK_length || | Direction: Input Type: Integer | | | The length of the input_KEK_identifier in bytes. When the input_KEK_identifier is a token, the value must be between the actual length of the token and 725. When the input_KEK_identifier is a label, the value must be 64. | | If the REFORMAT keyword is specified, and input_key_token is an AES key token, this parameter must be zero. input_KEK_identifier Direction: Input/Output Type: String A variable length string variable containing the internal key token or the key label of an internal key token record in the CKDS. The internal key token contains the key-encrypting key used to decipher the key. | If input_KEK_length is zero, this parameter is ignored. | | | | If the TRANSLAT keyword is specified and the input_key_token is an external DES key, the input_KEK_identifier must be an internal DES token that contains 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. | | | | | If the TRANSLAT keyword is specified and the input_key_token is an external variable-length key token, the input_KEK_identifier must be an internal variable-length key token containing an IMPORTER key-encrypting key. The IMPORTER key must have the TRANSLAT bit on in key-usage field 1 of the token. | | | If the REFORMAT keyword is specified and input_key_token is an external DES key token, this parameter may be an IMPORTER, IKEYXLAT, EXPORTER, or OKEYXLAT key type. If an internal token was supplied and was encrypted under the old master key, the token will be returned encrypted under the current master key. output_KEK_length Direction: Input Type: Integer | | | | The length of the output_KEK_identifier in bytes. When the output_KEK_identifier is a token, the value must be between the actual length of the token and 725. When the output_KEK_identifier is a label, the value must be 64. | If the REFORMAT keyword is specified, this value must be zero. output_KEK_identifier Direction: Input/Output Type: String A variable length string variable containing the internal key token or the key label of an internal key token record in the CKDS. The internal key token contains the key-encrypting key used to encipher the key. | If output_KEK_length is zero, this parameter is ignored. Chapter 5. Managing Symmetric Cryptographic Keys 203 Key Translate2 | | | | If the output_key_token is an external DES key, the output_KEK_identifier must be an internal DES token that contains 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 input_key_token is an external variable-length key token, the output_KEK_identifier must be an internal variable-length key token containing an EXPORTER key-encrypting key. The EXPORTER key must have the TRANSLAT bit on in key-usage field 1 of the token. | | If an internal token was supplied and was encrypted under the old master key, the token will be returned encrypted under the current master key. output_key_length Direction: Input/Output Type: Integer On input, the length of the output area provided for the output_key_token. This must be between 64 and 900 bytes and provide sufficient space for the output key. On output, the parameter is updated with the length of the token copied to the output_key_token. | | | output_key_token || | Direction: Input/Output Type: String | | | | | | | | If the REFORMAT keyword is specified and the input_key_token is an AES DATA key (version X‘04’), output_key_token must contain an AES CIPHER key (version X‘05’) on input. This token must have the following characteristics: v Algorithm is AES v Key type CIPHER | Otherwise, this field is ignored on input. | | On output, a variable length string variable containing the key token that was translated or reformatted. | | | | If the REFORMAT keyword is specified and the input_key_token is an AES DATA key (version X‘04’), on output, output_key_token will be updated with the following characteristics: v Key-usage field 2 either allows the key to be used for Cipher Block Chaining (CBC) mode or allows the key to be used for Electronic Code Book (ECB) mode v Key-usage field 1 allows the key to be used for encryption and decryption v Key-management field 1 allows export using symmetric, unauthenticated asymmetric, and authenticated asymmetric transport keys, and allows export using DES, AES, and RSA transport keys v Key-management field 2 indicates that the key is complete | | | | Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS. 204 z/OS V1R13 ICSF Application Programmer's Guide Key Translate2 This table lists the access control points in the ICSF default role that control the function for this service. Table 66. Key Translate2 Access Control Points Access Control point Function control | | Key Translate2 Allows the Key Translate2 service to be functional. | | Key Translate2 – Allow use of REFORMAT Allows a key token to be rewrapped using one key-encrypting key. | | | | Key Translate2 – Allow wrapping method override keywords Allows the wrapping method keywords WRAP-ECB or WRAP-ENH to be used when the default key-wrapping method setting does not match the keyword. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 67. Key Translate2 required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries None. 900 This service is not supported. IBM Eserver zSeries None. 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC None. This service is not supported. Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. Crypto Express3 Coprocessor Enhanced key token wrapping and HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). IBM System z9 BC IBM System z10 EC IBM System z10 BC | | | | | z196 AES key support requires the Sep. 2011 or later licensed internal code (LIC). Multiple Clear Key Import (CSNBCKM and CSNECKM) The multiple clear key import callable service imports a clear AES or DES key, enciphers the key under the corresponding master key, and returns the enciphered key in an internal key token. The enciphered key's type is DATA. The enciphered key is in operational form. The callable service name for AMODE(64) invocation is CSNECKM. Chapter 5. Managing Symmetric Cryptographic Keys 205 Multiple Clear Key Import Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that are assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 0, 1, 2, or 3. If the rule_array_count is 0, the default keywords are used. rule_array Direction: Input 206 z/OS V1R13 ICSF Application Programmer's Guide Type: String Multiple Clear Key Import Keywords that supply control information to the callable service. 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.Refer to Table 68 for a list of keywords. Table 68. Keywords for Multiple Clear Key Import Rule Array Control Information Keyword Meaning Algorithm (optional) CDMF The output key identifier is to be a CDMF token. For a DATA key of length 16 or 24, you may not specify CDMF. CDMF is only supported on CCF systems. AES The output key identifier is to be an AES token. DES The output key identifier is to be a DES token. This is the default. Key Wrapping Method (optional) USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default keyword. The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. Translation Control (optional) ENH-ONLY Restrict rewrapping of the key_identifier token. Once the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. clear_key_length Direction: Input Type: Integer The clear_key_length specifies the length of the clear key value to import in bytes. For DES keys, this length must be 8-, 16-, or 24-bytes. For AES keys, this length must be 16-, 24-, or 32-bytes. 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 Chapter 5. Managing Symmetric Cryptographic Keys 207 Multiple Clear Key Import Direction: Input/Output Type: String A 64-byte string that is to receive an internal AES or DES key token. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output key_identifier will use the default method unless a rule array keyword overriding the default is specified. Usage Notes This service produces an internal DES DATA token with a control vector which is usable on the Cryptographic Coprocessor Feature. If a valid internal DES token is supplied as input to the service in the key_identifier field, that token's control vector will not be used in the encryption of the clear key value. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 69. Required access control points for Multiple Clear Key Import | Key algorithm Access control point | DES Clear Key Import/Multiple Clear Key Import – DES | | | AES Multiple Clear Key Import/Multiple Secure Key Import – AES | | | | When the WRAP-ECB or WRAP-ENH keywords are specified and default key-wrapping method setting does not match the keyword, the Multiple Clear Key Import - Allow wrapping override keywords access control point must be enabled. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 70. Multiple clear key import required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions Tokens are not marked with the system encryption algorithm. ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor CDMF keyword is not supported. Tokens are not marked with the system encryption algorithm. ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. 208 z/OS V1R13 ICSF Application Programmer's Guide Multiple Clear Key Import Table 70. Multiple clear key import required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z9 EC Crypto Express2 Coprocessor CDMF keyword is not supported. Tokens are not marked with the system encryption algorithm. IBM System z9 BC Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC CDMF keyword is not supported. Tokens are not marked with the system encryption algorithm. Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. z196 Crypto Express3 Coprocessor Enhanced key token wrapping not supported. Crypto Express3 Coprocessor CDMF keyword is not supported. Tokens are not marked with the system encryption algorithm. Multiple Secure Key Import (CSNBSKM and CSNESKM) Use this service to encipher a single-length, double-length, or triple-length DES key under the system master key or an importer key-encrypting key. The clear DES key can then be imported as any of the possible key types. In addition to DES keys, this service imports a clear AES key, enciphers the AES key under the AES master key, and returns the enciphered key in an internal token. The enciphered key's type is DATA. The enciphered key is in operational form. The callable service can execute only when ICSF is in special secure mode, which is described in “Special Secure Mode” on page 10. The callable service name for AMODE(64) invocation is CSNESKM. Chapter 5. Managing Symmetric Cryptographic Keys 209 Multiple Secure Key Import Format CALL CSNBSKM( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, clear_key_length, clear_key, key_type, key_form, key_encrypting_key_identifier, imported_key_identifier_length, imported_key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 0, 1, 2, 3, or 4. If the rule_array_count is 0, the default keywords are used. rule_array 210 z/OS V1R13 ICSF Application Programmer's Guide Multiple Secure Key Import Direction: Input Type: String Zero, one or two keywords that supply control information to the callable service. 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 keywords are shown in Table 71. The first keyword is the algorithm. If no algorithm is specified, the system default algorithm is used. If no algorithm is specified on a CDMF only system and either a double- or triple-length DATA key is specified, the token is marked DES. The algorithm keyword applies only when the desired output token is of key form OP and key type IMPORTER, EXPORTER, or DATA. For key form IM or any other key type, specifying DES or CDMF causes an error. The second keyword is optional and specifies that the output key token be marked as an NOCV-KEK. The third keyword is optional, and specifies whether the original key wrapping method or the enhanced key wrapping method (which is compliant with the ANSI X9.24 standard) should be used. The fourth keyword enables an application to specify that the imported_key_identifier output token can not be rewrapped using the original wrapping method after it has been wrapped using the enhanced method. Table 71. Keywords for Multiple Secure Key Import Rule Array Control Information Keyword Meaning Algorithm (optional) CDMF The output key identifier is to be a CDMF token. For a DATA key of length 16 or 24, you may not specify CDMF. CDMF is only supported on CCF systems. AES The output key identifier is to be a AES token. DES The output key identifier is to be a DES token. This is the default. NOCV Choice (optional) NOCV-KEK The output token is to be marked as an NOCV-KEK. This keyword only applies if key form is OP and key type is IMPORTER, EXPORTER or IMP-PKA. For key form IM or any other key type, specifying NOCV-KEK causes an error. Key Wrapping Method (optional) USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default keyword. The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. Translation Control (optional) Chapter 5. Managing Symmetric Cryptographic Keys 211 Multiple Secure Key Import Table 71. Keywords for Multiple Secure Key Import Rule Array Control Information (continued) Keyword Meaning ENH-ONLY Restrict rewrapping of the imported_key_identifier token. Once the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. clear_key_length Direction: Input Type: Integer The clear_key_length specifies the length of the clear key value to import in bytes. For AES keys, this length must be 16-, 24-, or 32-bytes. For DES keys, this length must be 8-, 16- or 24-bytes. clear_key Direction: Input Type: String The clear_key specifies the AES or DES clear key value to import. key_type Direction: Input Type: 8 Character String The type of key you want to encipher under the master key or an importer key. Specify an 8-byte field that must contain a keyword from this list or the keyword TOKEN. For types with fewer than 8 characters, the type should be padded on the right with blanks. If the key type is TOKEN, ICSF determines the key type from the control vector (CV) field in the internal key token provided in the imported_key_identifier parameter. When key_type is TOKEN, ICSF does not check for the length of the key but uses the clear_key_length parameter to determine the length of the key. Key type values for the Multiple Secure Key Import callable service are: CIPHER, CVARDEC, CVARENC, CVARPINE, CVARXCVL, CVARXCVR, DATA, DATAM, DATAMV, DATAXLAT, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IMP-PKA, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER. For information on the meaning of the key types, see Table 3 on page 23. key_form Direction: Input Type: 4 Character String The key form you want to generate. Enter a 4-byte keyword specifying whether the key should be enciphered under the master key (OP) or the importer key-encrypting key (IM). The keyword must be left-justified and padded with blanks. Valid DES keyword values are OP for encryption under the master key or IM for encryption under the importer key-encrypting key. If you specify IM, you must specify an importer key-encrypting key in the key_encrypting_key_identifier parameter. For a key_type of IMP-PKA, this service supports only the OP key_form. The only valid AES keyword value is OP. key_encrypting_key_identifier 212 z/OS V1R13 ICSF Application Programmer's Guide Multiple Secure Key Import Direction: Input/Output Type: String A 64-byte string internal key token or key label of a DES importer key-encrypting key. This parameter is ignored for AES secure keys. imported_key_identifier_length Direction: Input/Output Type: Integer The byte length of the imported_key_identifier parameter. This must be at least 64. imported_key_identifier Direction: Input/Output Type: String A 64-byte string that is to receive the output key token. If OP is specified in the key_form parameter, the service returns an internal key token. If IM is specified in the key_form parameter, the service returns an external key token. On input, this parameter is ignored except when the key_type is TOKEN. If you specify a key_type of TOKEN, then this field contains a valid token of the key type you want to encipher. See key_type for a list of valid key types. Appendix B, “Key Token Formats,” on page 777 describes the key tokens. Note that for a DATA key of length 16 or 24, no reference will be made to the data encryption algorithm bits or to the system's default algorithm; the token will be marked DES. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output imported_key_identifier will use the default method unless a rule array keyword overriding the default is specified. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. On CCF systems, to generate double-length DATAM and DATAMV keys in the importable form, the ANSI system keys must be installed in the CKDS. CDMF is only supported on CCF systems. With a PCIXCC, CEX2C, or CEX3C, creation of a DES NOCV key-encrypting key is only available for standard IMPORTERs and EXPORTERs. On an IBM Eserver zSeries 990, if key_form of the DES key is IM and the key_encrypting_key_identifier is a NOCV KEK, then the NOCV IMPORTER access control point must be enabled in the PCIXCC to use the function. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 72. Required access control points for Multiple Secure Key Import | Key Algorithm and Key Form Access control point | DES OP Secure Key Import - DES, OP | DES IM Secure Key Import - DES, IM Chapter 5. Managing Symmetric Cryptographic Keys 213 Multiple Secure Key Import | Table 72. Required access control points for Multiple Secure Key Import (continued) | Key Algorithm and Key Form Access control point | | | AES OP Multiple Clear Key Import/Multiple Secure Key Import – AES | | | To use a NOCV key-encrypting key with the Multiple Secure Key Import service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed. | | | | When the WRAP-ECB or WRAP-ENH keywords are specified and default key-wrapping method setting does not match the keyword, the Multiple Secure Key Import - Allow wrapping override keywords access control point must be enabled. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 73. Multiple secure key import required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions Only control vectors and key types supported by the Cryptographic Coprocessor Feature will be valid when importing a triple-length key. ICSF routes the request to a PCI Cryptographic Coprocessor if the control vector of a supplied internal token cannot be processed on the Cryptographic Coprocessor Feature, or if the key type is not valid for the Cryptographic Coprocessor Feature. DATAC is not supported. ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 Coprocessor 890 Key_type DATAXLAT is not supported. CDMF keyword is not supported. DATA and KEK tokens are not marked with the system encryption algorithm. ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. 214 z/OS V1R13 ICSF Application Programmer's Guide Multiple Secure Key Import Table 73. Multiple secure key import required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z9 EC Crypto Express2 Coprocessor Key_type DATAXLAT is not supported. CDMF keyword is not supported. DATA and KEK tokens are not marked with the system encryption algorithm. IBM System z9 BC Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Key_type DATAXLAT is not supported. CDMF keyword is not supported. DATA and KEK tokens are not marked with the system encryption algorithm. Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB not supported. Enhanced key token wrapping not supported. Crypto Express3 Coprocessor Key_type DATAXLAT is not supported. CDMF keyword is not supported. DATA and KEK tokens are not marked with the system encryption algorithm. Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). Enhanced key token wrapping not supported. z196 Crypto Express3 Coprocessor Key_type DATAXLAT is not supported. CDMF keyword is not supported. DATA and KEK tokens are not marked with the system encryption algorithm. PKA Decrypt (CSNDPKD and CSNFPKD) Use this service to decrypt (unwrap) a formatted key value. The service unwraps the key, deformats it, and returns the deformatted value to the application in the clear. PKCS 1.2 and ZERO-PAD formatting is supported. For PKCS 1.2, the decrypted data is examined to ensure it meets RSA DSI PKCS #1 block type 2 format specifications. ZERO-PAD is only supported for external RSA clear private keys. This service allows the use of clear or encrypted RSA private keys. If an external clear key token is used, the master keys are not required to be installed in any cryptographic coprocessor and PKA callable services does not have to be enabled. Requests are routed to a PCICA if available when a clear key token is used. Chapter 5. Managing Symmetric Cryptographic Keys 215 PKA Decrypt The callable service name for AMODE(64) invocation is CSNFPKD. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that are assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. This value must be 1. 216 z/OS V1R13 ICSF Application Programmer's Guide PKA Decrypt rule_array Direction: Input Type: String The keyword that provides control information to the callable service. The keyword is left-justified in an 8-byte field and padded on the right with blanks. Table 74. Keywords for PKA Decrypt Keyword Meaning Recovery Method (required) specifies the method to use to recover the key value. PKCS-1.2 RSA DSI PKCS #1 block type 02 will be used to recover the key value. ZERO-PAD The input PKA_enciphered_keyvalue is decrypted using the RSA private key. The entire result (including leading zeros) will be returned in the target_keyvalue field. The PKA_key_identifier must be an external RSA token or the labelname of a external token. This keyword requires requires May 2004 or later version of Licensed Internal Code (LIC) or a z890. This support on the PCICA does not require LIC code updates. PKA_enciphered_keyvalue_length Direction: Input Type: integer The length of the PKA_enciphered_keyvalue parameter in bytes. The maximum size that you can specify is 512 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 RSA public key. This byte-length string is left-justified within the PKA_enciphered_keyvalue parameter. data_structure_length Direction: Input Type: Integer The value must be 0. data_structure Direction: Input Type: String This field is currently ignored. PKA_key_identifier_length Direction: Input Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 217 PKA Decrypt 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 3500 bytes. PKA_key_identifier Direction: Input Type: String An internal RSA private key token, the label of an internal RSA private key token, or an external RSA private key token containing a clear RSA private key in modulus-exponent or Chinese Remainder 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 512 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 RSA modulus byte length. target_keyvalue Direction: Output Type: String This field will contain the decrypted, deformatted key value. If ZERO-PAD is specified, the decrypted key value, including leading zeros, will be returned. Restrictions The exponent of the RSA public key must be odd. Access control checking will not be performed in the PCI Cryptographic Coprocessor when a clear external key token is supplied. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. The RSA private key must be enabled for key management functions. The hardware configuration sets the limit on the modulus size of keys for key management; thus, this service will fail if the RSA key modulus bit length exceeds this limit. Routing of requests to coprocessors for systems with CCFs: This service examines the RSA key specified in the PKA_key_identifier parameter to determine how to route the request. v If the modulus bit length is less than 512 bits, or if the key is a X'02' form modulus-exponent private key, ICSF routes the request to the Cryptographic Coprocessor Feature. v If the key is a X'08' form CRT private key or a retained private key, the service routes the request to a PCI Cryptographic Coprocessor. 218 z/OS V1R13 ICSF Application Programmer's Guide PKA Decrypt v In the case of a retained key, the service routes the request to the specific PCI Cryptographic Coprocessor in which the key is retained. v If the key is a modulus-exponent form private key with a private section ID of X'06', then the service routes the request as follows: – Since the key must be a key-management key, if the KMMK is equal to the SMK on the Cryptographic Coprocessor Feature, the PKA decrypt service uses load balancing to route the request to either a Cryptographic Coprocessor Feature or to an available PCI Cryptographic Coprocessor. – If the KMMK is not equal to the SMK on the Cryptographic Coprocessor Feature, the request must be processed on a PCI Cryptographic Coprocessor. If there is no PCI Cryptographic Coprocessor online, the request will fail. v If the key is an external clear key, the request is routed in this order of preference. – PCICA – PCICC – CCF | The PKA Decrypt access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 75. PKA decrypt required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature ICSF routes the request to the Cryptographic Coprocessor Feature if the modulus bit length is less than 512 bits, or if the key is a X'02' form modulus-exponent private key. The ZERO-PAD keyword is not supported. RSA keys with moduli greater than 1024-bit length are not supported. PCI Cryptographic Coprocessor This service routes the request to the PCI Cryptographic Coprocessor in which the key is retained if the key is a X'08' form CRT private key or a retained private key The ZERO-PAD keyword is not supported. RSA keys with moduli greater than 2048-bit length are not supported. PCI Cryptographic Accelerator Only clear RSA private keys are supported. The ZERO-PAD keyword is not supported. RSA keys with moduli greater than 2048-bit length are not supported. Chapter 5. Managing Symmetric Cryptographic Keys 219 PKA Decrypt Table 75. PKA decrypt required hardware (continued) Server Required cryptographic hardware IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor Restrictions Old RSA private tokens encrypted under the CCF KMMK are not usable on the PCIXCC/CEX2C if the KMMK was not same as the ASYM-MK. RSA keys with moduli greater than 2048-bit length are not supported. PCI Cryptographic Accelerator Only clear RSA private keys are supported. RSA keys with moduli greater than 2048-bit length are not supported. IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC Old RSA private tokens encrypted under the CCF KMMK are not usable on the CEX2C if the KMMK was not same as the ASYM-MK. RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express2 Accelerator Only clear RSA private keys are supported. RSA keys with moduli greater than 2048-bit length are not supported. IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor Old RSA private tokens encrypted under the CCF KMMK are not usable on the CEX2C or CEX3C if the KMMK was not same as the ASYM-MK. RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express2 Accelerator Crypto Express3 Accelerator z196 Only clear RSA private keys are supported. RSA keys with moduli greater than 2048-bit length are not supported. Crypto Express3 Coprocessor Old RSA private tokens encrypted under the CCF KMMK are not usable on the CEX3C if the KMMK was not same as the ASYM-MK. Crypto Express3 Accelerator Only clear RSA private keys are supported. | | | RSA clear key support with moduli within the range 2048-bit to 4096-bit requires the Sep. 2011 or later licensed internal code (LIC). PKA Encrypt (CSNDPKE and CSNFPKE) This callable service encrypts a supplied clear key value under an RSA public key. The rule array keyword specifies the format of the key prior to encryption. On the z900 and if the ZERO-PAD or MRP keyword is specified, this service is routed to a PCI Cryptographic Accelerator. | 220 z/OS V1R13 ICSF Application Programmer's Guide PKA Encrypt The callable service name for AMODE(64) invocation is CSNFPKE. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that are assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. This value can be 1 or 2. rule_array Chapter 5. Managing Symmetric Cryptographic Keys 221 PKA Encrypt Direction: Input Type: String A keyword that provides control information to the callable service. The keyword is left-justified in an 8-byte field and padded on the right with blanks. Table 76. Keywords for PKA Encrypt Keyword Meaning Formatting Method (required) specifies the method to use to format the key value prior to encryption. PKCS-1.2 RSA DSI PKCS #1 block type 02 format will be used to format the supplied key value. ZERO-PAD The key value will be padded on the left with binary zeros to the length of the PKA key modulus. The exponent of the public key must be odd. MRP The key value will be padded on the left with binary zeros to the length of the PKA key modulus. The RSA public key may have an even or odd exponent. This keyword requires May 2004 or later version of Licensed Internal Code (LIC) or a z890. For PCICAs, the LIC code update is not required. Key Rule (Optional) KEYIDENT This indicates that the value in the keyvalue field is the label of clear tokens in the CKDS. The keyvalue_length must be 64. keyvalue_length Direction: Input Type: Integer The length of the keyvalue parameter. The maximum field size is 512 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. When key rule KEYIDENT is specified, then the keyvalue_length parameter is required to be 64 bytes. keyvalue Direction: Input Type: String This field contains the supplied clear key value to be encrypted under the PKA_key_identifier. When key rule KEYIDENT is specified, the keyvalue parameter is assumed to contain a label for a valid CKDS clear key token. data_structure_length Direction: Input Type: Integer This value must be 0. data_structure Direction: Input This field is currently ignored. PKA_key_identifier_length 222 z/OS V1R13 ICSF Application Programmer's Guide Type: String PKA Encrypt 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 3500 bytes. PKA_key_identifier Direction: Input Type: String The RSA public or private key token or the label of the RSA public 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 512 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 RSA public key. This byte-length string is left-justified within the PKA_enciphered_keyvalue parameter. Restrictions The exponent for RSA public keys must be odd. When the modulus is greater than 2048, the public key exponent must be 3 or 65537. Usage Notes v SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. v For RSA DSI PKCS #1 formatting, the key value length must be at least 11 bytes less than the modulus length of the RSA key. v The hardware configuration sets the limit on the modulus size of keys for key management; thus, this service will fail if the RSA key modulus bit length exceeds this limit. v The key value to be encrypted must be smaller than the modulus in the PKA_key_identifier. | The PKA Encrypt access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 5. Managing Symmetric Cryptographic Keys 223 PKA Encrypt Table 77. PKA encrypt required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions The MRP keyword is not supported. RSA keys with moduli greater than 1024-bit length are not supported. PCI Cryptographic Coprocessor If the modulus bit length of the key specified in the PKA_key_identifier parameter is greater than 1024, the request is routed to the PCICC. The MRP keyword is not supported. RSA keys with moduli greater than 2048-bit length are not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor Routed to a PCICA if one is available (ZERO-PAD and MRP only). IBM Eserver zSeries Crypto Express2 890 Coprocessor RSA keys with moduli greater than 2048-bit length are not supported. PCI Cryptographic Accelerator PKCS-1.2 keyword not supported. RSA keys with moduli greater than 2048-bit length are not supported. IBM System z9 EC Crypto Express2 Coprocessor Routed to a CEX2A if one is available (ZERO-PAD and MRP only). IBM System z9 BC RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express2 Accelerator PKCS-1.2 keyword not supported. RSA keys with moduli greater than 2048-bit length are not supported. IBM System z10 EC Crypto Express2 Coprocessor Routed to a CEX2A or CEX3A if one is available (ZERO-PAD and MRP only). Crypto Express3 Coprocessor RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express2 Accelerator PKCS-1.2 keyword not supported. IBM System z10 BC Crypto Express3 Accelerator z196 RSA keys with moduli greater than 2048-bit length are not supported. Crypto Express3 Coprocessor Routed to a CEX2A or CEX3A if one is available (ZERO-PAD and MRP only). Crypto Express3 Accelerator PKCS-1.2 keyword not supported. | | | RSA clear key support with moduli within the range 2048-bit to 4096-bit requires the Sep. 2011 or later licensed internal code (LIC). 224 z/OS V1R13 ICSF Application Programmer's Guide Prohibit Export Prohibit Export (CSNBPEX and CSNEPEX) Use this service to modify an exportable internal DES key token so that it cannot be exported. The callable service name for AMODE(64) invocation is CSNEPEX. Format CALL CSNBPEX( return_code, reason_code, exit_data_length, exit_data, key_identifier) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier Direction: Input/Output Type: String A 64-byte string variable containing the internal key token to be modified. The returned key_identifier will be encrypted under the current master key. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method Chapter 5. Managing Symmetric Cryptographic Keys 225 Prohibit Export which is ANSI X9.24 compliant. The output key_identifier will be wrapped in the same manner as the input key_identifier. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. The Prohibit Export access control point controls the function of this service. | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 78. Prohibit export required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI Cryptographic 900 Coprocessor On a PCI Cryptographic Coprocessor, the Prohibit Export service does not support NOCV key-encrypting keys, or DATA, DATAM, DATAMV, MAC, or MACVER keys with standard control vectors (for example, control vectors supported by the Cryptographic Coprocessor Feature). IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor DATA keys are not supported. Old, internal DATAM and DATAMV keys are not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor DATA keys are not supported. Old, internal DATAM and DATAMV keys are not supported. Crypto Express2 Coprocessor DATA keys are not supported. Old, internal DATAM and DATAMV keys are not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor DATA keys are not supported. Old, internal DATAM and DATAMV keys are not supported. Prohibit Export Extended (CSNBPEXX and CSNEPEXX) Use the prohibit export extended callable service to change the external token of a cryptographic key in exportable DES key token form so that it can be imported at the receiver node and is non-exportable from that node. You cannot prohibit export of DATA keys. The inputs are an external token of the key to change in the source_key_token parameter and the label or internal token of the exporter key-encrypting key in the KEK_key_identifier parameter. This service is a variation of the Prohibit Export service (CSNBPEX and CSNEPEX), which supports changing an internal token. The callable service name for AMODE(64) invocation is CSNEPEXX. 226 z/OS V1R13 ICSF Application Programmer's Guide Prohibit Export Extended Format CALL CSNBPEXX( return_code, reason_code, exit_data_length, exit_data, source_key_token, KEK_key_identifier) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. source_key_token Direction: Input/Output Type: String A 64-byte string of an external token of a key to change. It is in exportable form. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output source_key_token will be wrapped in the same manner as the input source_key_token. KEK_key_identifier Direction: Input/Output Type: String Chapter 5. Managing Symmetric Cryptographic Keys 227 Prohibit Export Extended A 64-byte string of an internal token or label of the exporter KEK used to encrypt the key contained in the external token specified in the previous parameter. Restrictions This callable service does not support version X'10' external DES key tokens (RKX key tokens). Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. The Prohibit Export Extended access control point controls the function of this service. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 79. Prohibit export extended required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor External MACD keys are not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor External MACD keys are not supported. Crypto Express2 Coprocessor External MACD keys are not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor External MACD keys are not supported. Random Number Generate (CSNBRNG, CSNERNG, CSNBRNGL and CSNERNGL) The callable service uses the cryptographic feature to generate a random number. The foundation for the random number generator is a time variant input with a very low probability of recycling. There are two forms of the Random Number Generate callable service. One version returns an 8-byte random number. The second version allows the caller to specify the length of the random number. Note: Random Number Generate on a z900 server requires the symmetric-keys master key to be set prior to using the service. 228 z/OS V1R13 ICSF Application Programmer's Guide Random Number Generate The callable service names for AMODE(64) invocation are CSNERNG and CSNERNGL. Format CALL CSNBRNG( return_code, reason_code, exit_data_length, exit_data, form, random_number ) CALL CSNBRNGL( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, reserved_length, reserved, random_number_length, random_number ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. form Chapter 5. Managing Symmetric Cryptographic Keys 229 Random Number Generate Direction: Input Type: Character string The 8-byte keyword that defines the characteristics of the random number should be left-justify and pad on the right with blanks. The keywords are listed in Table 80. Table 80. Keywords for the Form Parameter Keyword Meaning EVEN Generate a 64-bit random number with even parity in each byte. ODD Generate a 64-bit random number with odd parity in each byte. RANDOM Generate a 64-bit random number. Parity is calculated on the 7 high-order bits in each byte and is presented in the low-order bit in the byte. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. The value must be one. rule_array Direction: Input Type: String The keyword that provides control information to the callable service. 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. All keywords must be in contiguous storage. Table 81. Keywords for Random Number Generate Control Information Keyword Meaning Parity of the random number bytes (required) EVEN Generate a random number with even parity in each byte. Its length is the random_number_length. ODD Generate a random number with odd parity in each byte. Its length is the random_number_length. RANDOM Generate a random number. Its length is the random_number_length. reserved_length Direction: Input Type: Integer This parameter must be zero. reserved Direction: Input This parameter is ignored. 230 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Random Number Generate random_number_length Direction: Input/Output Type: Integer This parameter contains the desired length of the random_number that is returned by the CSNBRNGL callable service. The minimum value is 1 byte; the maximum value is 8192 bytes. random_number Direction: Output Type: String The generated number returned by the CSNBRNG callable service is stored in an 8-byte variable. The generated number returned by the CSNBRNGL callable service is stored in a variable that is at least random_number_length bytes long. Usage Notes The CSNBRNGL callable service returns a value under the following conditions: v The server has the cryptographic coprocessor that supports CSNBRNGL and the coprocessor creates the random number with the desired length. This requires a CEX2C or CEX3C with a version of the licensed internal code (LIC) that supports the RNGL verb. v The server has the cryptographic coprocessor that processes CSNBRNG requests. In this case, the CSNBRNGL callable service calls the processor to create the random number with the desired length, 8 bytes at a time. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 82. Random number generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Chapter 5. Managing Symmetric Cryptographic Keys 231 Remote Key Export Remote Key Export (CSNDRKX and CSNFRKX) This callable service uses the trusted block to generate or export DES keys for local use and for distribution to an ATM or other remote device. RKX uses a special structure to hold encrypted symmetric keys in a way that binds them to the trusted block and allows sequences of RKX calls to be bound together as if they were an atomic operation. The callable service name for AMODE(64) invocation is CSNFRKX. Format CALL CSNDRKX( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, trusted_block_length, trusted_block_identifier, certificate_length, certificate, certificate_parms_length, certificate_parms, transport_key_length, transport_key_identifier, rule_id_length, rule_id, importer_key_length, importer_key_identifier, source_key_length, source_key_identifier, asym_encrypted_key_length, asym_encrypted_key, sym_encrypted_key_length, sym_encrypted_key, extra_data_length, extra_data, key_check_parameters_length, key_check_parameters, key_check_length, key_check_value) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the specific results of processing. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. 232 z/OS V1R13 ICSF Application Programmer's Guide Remote Key Export exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. This number must be 0. rule_array Direction: Input Type: String Specifies a string variable containing an array of keywords. Currently no rule_array keywords are defined for this service, but you must still specify this parameter. trusted_block_length Direction: Input Type: Integer Specifies the number of bytes in the trusted_block_identifier parameter. The maximum length is 3500 bytes. trusted_block_identifier Direction: Input Type: String Specifies a trusted block label or trusted block token of an internal/complete trusted block constructed by the service, which is used to validate the public key certificate (certificate) and to define the rules for key generation and export. certificate_length Direction: Input Type: Integer Specifies the number of bytes in the certificate parameter. The maximum is 5000 bytes. If the certificate_length is zero and the trusted block's Asymmetric Encrypted Output Key Format indicates no asymmetric key output, this service will not attempt to use or validate the certificate in any way. Consequently, the output parameter asym_encrypted_key_length will contain zero and output parameter asym_encrypted_key will not be changed from its input content. If the certificate length is zero and the trusted block's Asymmetric Encrypted Output Key Format indicates PKCS1.2 output format or RSAOAEP output format, this service will exit with an error. Chapter 5. Managing Symmetric Cryptographic Keys 233 Remote Key Export If the certificate_length is non-zero and the trusted block's Asymmetric Encrypted Output Key Format indicates no asymmetric key output, this service will fail. certificate Direction: Input Type: String Contains a public-key certificate. The certificate must contain the public key modulus and exponent in binary_form, as well as a digital signature. The signature in the certificate will be verified using the root public key that is in the trusted block supplied in trusted_block_identifier parameter. certificate_parms_length Direction: Input Type: Integer Contains the number of bytes in the certificate_parms parameter. The length must be 36 bytes. certificate_parms Direction: Input Type: String Contains a structure provided by the caller used for identifying the location and length of values within the certificate in parameter certificate. For each of the values used by RKX, the structure contains offsets from the start of the certificate and length in bytes. It is the responsibility of the calling application program to provide these values. This method gives the greatest flexibility to support different certificate formats. The structure has this layout: Table 83. Structure of values used by RKX Offset (bytes) Length (bytes) 0 4 Offset of modulus 4 4 Length of modulus 8 4 Offset of public exponent 12 4 Length of public exponent 16 4 Offset of digital signature 20 4 Length of digital signature 24 1 Identifier for the hash algorithm used 25 1 Identifier for the digital hash formatting method Description v 01 - PKCS-1.0 v 02 - PKCS-1.1 v 03 - X9.31 v 04 - ISO-9796 v 05 - ZERO-PAD 234 26 2 Reserved - must be filled with 0x00 bytes 28 4 Offset of first byte of certificate data hashed to compute the digital signature 32 4 Length of the certificate data hashed to compute the digital signature z/OS V1R13 ICSF Application Programmer's Guide Remote Key Export The modulus, exponent, and signature values are right-justified and padded on the left with binary zeros if necessary. These values are defined for the hash algorithm identifier at offset 24 in the structure. Table 84. Values defined for hash algorithm identifier at offset 24 in the structure for remote key export Identifier Algorithm 0X01 SHA-1 0X02 MD5 0X03 RIPEMD-160 transport_key_length Direction: Input Type: Integer Contains the number of bytes in the transport_key_identifier parameter. transport_key_identifier Direction: Input Type: String Contains a label of an internal key token, or an RKX token for a Key Encrypting Key (KEK) that is used to encrypt a key exported by the RKX service. A transport key will not be used to encrypt a generated key. For flag bit0=1 (export existing key) within Rule section and parameter rule_id = Rule section ruleID, the transport_key_identifier encrypts the exported version of the key received in parameter source_key_identifier. The service can distinguish between the internal key token or RKX key token by virtue of the version number at offset 0x04 contained in the key token and the flag value at offset 0x00 as follows: Table 85. Transport_key_identifer used by RKX Flag Byte Offset 00 Version Number Offset 04 Description 0X01 0X00 Internal DES key token version 0 0X02 0X10 RKX Key token (Flag byte 0x02 indicates external key token) rule_id_length Direction: Input Type: Integer Contains the number of bytes in the rule_id parameter. The value must be 8. rule_id Direction: Input Type: String Specifies the rule in the trusted block that will be used to control key generation or export. The trusted block can contain multiple rules, each of which is identified by a rule ID value. Chapter 5. Managing Symmetric Cryptographic Keys 235 Remote Key Export importer_key_length Direction: Input Type: Integer Contains the number of bytes in the importer_key_identifier parameter. It must be zero if the Generate/Export flag in the rule section (section 0x12) of the Trusted Block is a zero, indicating a new key is to be generated. importer_key_identifier Direction: Input Type: String Contains a key token or key label for the IMPORTER key-encrypting key that is used to decipher the key passed in parameter source_key_identifier. It is unused if either RKX is being used to generate a key, or if the source_key_identifier is an RKX key token. source_key_length Direction: Input Type: Integer Contains the number of bytes in the source_key_identifier parameter. The parameter must be 0 if the trusted block Rule section ruleID = rule_id parameter and the flag bit0 = 0 (Generate new key). The parameter must be 64 if the trusted block Rule section has a flag bit0 = 1 (Export existing key). source_key_identifier Direction: Input Type: String Contains a label of a single or double length external or internal key token or an RKX key token for a key to be exported. It must be empty (source_key_length=0) if RKX is used to generate a new key. The service examines the key token to determine which form has been provided. This parameter is known as the source_key_identifier in other callable services. Table 86. Examination of key token for source_key_identifier Flag Byte Offset 00 Version Number Offset 04 Description 0X01 0X00 Internal DES key token version 0 0X02 0X00 External DES key token version 0 0X02 0X01 External DES key token version 1 0X02 0X10 RKX Key token (Flag byte 0x02 indicates external key token) asym_encrypted_key_length Direction: Input/Output Type: Integer The length of the asym_encrypted_key parameter. On input, it is the length of the storage to receive the output. On output, it is the length of the data returned in the asym_encrypted_key parameter. The maximum length is 512 bytes. asym_encrypted_key 236 z/OS V1R13 ICSF Application Programmer's Guide Remote Key Export Direction: Output Type: String The contents of this field is ignored on input. A string buffer RKX will use to return a generated or exported key that is encrypted under the public (asymmetric) key passed in parameter certificate. An error will be returned if the caller's buffer is too small to hold the value that would be returned. sym_encrypted_key_length Direction: Input/Output Type: Integer On input, the sym_encrypted_key_length parameter is an integer variable containing the number of bytes in the sym_encrypted_key field. On output, that value in sym_encrypted_key_length is replaced with the length of the key returned in sym_encrypted_key field. sym_encrypted_key Direction: Output Type: String Sym_encrypted_key is the string buffer RKX uses to return a generated or exported key that is encrypted under the key-encrypting key passed in the transport_key_identifier parameter. The value returned will be 64 bytes. An error will be returned if the caller's buffer is smaller than 64 bytes, and so too small to hold the value that would be returned. The sym_encrypted_key may be an RKX key token or a key token depending upon the value of the Symmetric Encrypted Output Key Format value of the Rule section within the trusted_block_identifier parameter. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The sym_encrypted_key will be wrapped in the same manner as the source_key_identifier. extra_data_length Direction: Input Type: Integer Contains the number of bytes of data in the extra_data parameter. It must be zero if the output format for the RSA-encrypted key in asym_encrypted_key is anything but RSAOEAP. The maximum size is 1024 bytes. extra_data Direction: Input Type: String Can be used in the OAEP key wrapping process. Extra_data is optional and is only applicable when the output format for the RSA-encrypted key returned in asym_encrypted_key is RSAOAEP. Note: RSAOAEP format is specified in the rule in the trusted block. key_check_parameters_length Direction: Input Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 237 Remote Key Export Contains the number of bytes in the key_check_parameters parameter. Currently, none of the defined key check algorithms require any key check parameters, so this field must specify 0. key_check_parameters Direction: Input Type: String Contains parameters that are required to calculate a key check value parameter, which will be returned in key_check_value. Currently, none of the defined key check algorithms require any key check parameters, but you must still specify this parameter. key_check_length Direction: Input/Output Type: Integer On input this parameter contains the number of bytes in the key_check_value parameter. On output, the value is replaced with the length of the key check value returned in the key_check_value parameter. The length depends on the key-check algorithm identifier. See Table 362 on page 816. key_check_value Direction: Output Type: String Used by RKX to return a key check value that calculates on the generated or exported key. Values in the rule specified with rule_id can specify a key check algorithm that should be used to calculate this output value. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | | The Remote Key Export - Gen or export a non-CCA node Key access control point controls the function of this service. | | | To use a NOCV IMPORTER key-encrypting key with the remote key export service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed. | | | To use a NOCV EXPORTER key-encrypting key with the remote key export service, the NOCV KEK usage for export-related functions access control point must be enabled in addition to one or both of the access control points listed. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 87. Remote key export required hardware Server Required cryptographic hardware IBM Eserver zSeries 990 IBM Eserver zSeries 890 238 z/OS V1R13 ICSF Application Programmer's Guide Restrictions This callable service is not supported. Remote Key Export Table 87. Remote key export required hardware (continued) Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 IBM Eserver z9 EC IBM System z9 BC This callable service is not supported. Cryptographic Express 2 Coprocessor RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). ENH-ONLY, USECONFG, WRAP-ENC and WRAP-ECB not supported. Crypto Express3 Coprocessor z196 RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express3 Coprocessor Restrict Key Attribute (CSNBRKA and CSNERKA) Use the Restrict Key Attribute callable service to modify an exportable internal or external CCA symmetric key-token so that its key can no longer be exported. The callable service name for AMODE(64) is CSNERKA. Format CALL 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 return_code Direction: Output Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 239 Restrict Key Attribute The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value must be between 1 and 10, inclusive. | | rule_array Direction: Input Type: String The rule_array contains keywords that provide control information to the callable service. 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. Table 88. Keywords for Restrict Key Attribute Control Information Keyword Meaning Token Type (Required) | AES Specifies the key token is an AES key token. | DES Specifies the key token is a DES key token. HMAC Specifies the key token is an HMAC key token. Export Control (Optional) | | | CCAXPORT 240 z/OS V1R13 ICSF Application Programmer's Guide For DES internal tokens, set bit 17 of the CV to 0 to prohibit any export of the key. This rule is only valid for Token Type DES. Restrict Key Attribute Table 88. Keywords for Restrict Key Attribute Control Information (continued) | | | | Keyword Meaning NOEXPORT For variable-length symmetric tokens, this prohibits the token from being exported by either a symmetric key or an asymmetric key, as well as prohibiting it from being exported to other formats. | | | | For DES internal tokens, this causes the export control bit (bit 17) to be set to 0 to indicate NO-XPORT and the TR-31 export control bit (bit 57) to be set to 1 to indicate no TR-31 export. This is the default. | | NOEX-AES Specifies to prohibit export using an AES key. This rule is not valid for Token Type DES. | | NOEX-DES Specifies to prohibit export using a DES key. This rule is not valid for Token Type DES. | | NOEX-RAW Specifies to prohibit export in RAW format. This rule is not valid for Token Type DES. | | NOEX-RSA Specifies to prohibit export using an RSA key. This rule is not valid for Token Type DES. | | NOEX-SYM Prohibits the key from being exported using a symmetric key. This rule is not valid for Token Type DES. | | | | NOEXAASY Prohibits the key from being exported using an authenticated asymmetric key (for example, an RSA key in a trusted block token). This rule is not valid for Token Type DES. | | | NOEXUASY Prohibits the key from being exported using an unauthenticated asymmetric key. This rule is not valid for Token Type DES. | | | NOT31XPT For DES internal tokens, set bit 57 of the CV to 1 to prohibit TR-31 export of the key. This rule is only valid for Token Type DES. | Input Transport Key (Optional) | | | IKEK-AES Specifies the KEK is an AES transport key. This is the default for Token Types AES and HMAC, and is not allowed with Token Type DES. | | IKEK-DES Specifies the KEK is a DES transport key This is the default for Token Type DES. | | IKEK-PKA Specifies the KEK is a PKA transport key. This is not allowed with Token Type DES. key_identifier_length Direction: Input/Output Type: Integer The length of the key_identifier parameter in bytes. The maximum value is 900. | key_identifier || | Direction: Input/Output Type: String Chapter 5. Managing Symmetric Cryptographic Keys 241 Restrict Key Attribute | | | | The key for which the export control is to be updated. The parameter contains an internal or external token or the 64-byte CKDS label of an internal token. If a label is specified, the key token will be updated in the CKDS and not returned by this service. | | If the key identifier supplied was an AES or DES token encrypted under the old master key, the token will be returned encrypted under the current master key. | key_encrypting_key_identifier_length || | Direction: Input Type: Integer | | | | | | The length of the key_encrypting_key_identifier parameter. When key_identifier is an internal token, the value must be zero. v If key_encrypting_key_identifier is a label for either the CKDS (IKEK-AES or IKEK-DES rules) or PKDS (IKEK-PKA rule), the value must be 64. v If key_encrypting_key_identifier is an AES KEK, the value must be between the actual length of the token and 725. | | v If key_encrypting_key_identifier is a DES KEK, the value must be 64. v If key_encrypting_key_identifier is an RSA KEK, the maximum length is 3500. | key_encrypting_key_identifier || | Direction: Input/Output Type: String | | | When key_encrypting_key_identifier_length is non-zero, key_encrypting_key_identifier contains an internal key token containing a key-encrypting key, or a key label. | | If the key identifier supplied was an AES or DES token encrypted under the old master key, the token will be returned encrypted under the current master key. opt_parameter1_length Direction: Input Type: Integer The byte length of the opt_parameter1 parameter. The value must be zero. 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. The value must be zero. opt_parameter2 Direction: Input This parameter is ignored. 242 z/OS V1R13 ICSF Application Programmer's Guide Type: String Restrict Key Attribute Usage Notes | | | | The access control points in the ICSF role that control the function of this service are: v Restrict Key Attribute - Export Control v Restrict Key Attribute - Permit setting the TR-31 export bit This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 89. Restrict Key Attribute required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC | | | | | IBM System z10 BC z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. Crypto Express3 Coprocessor HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). DES/AES key support requires the Sep. 2011 or later licensed internal code (LIC). Secure Key Import (CSNBSKI and CSNESKI) Use the secure key import callable service to encipher a single-length or double-length clear key under the system master key (DES or SYM-MK) or under an importer key-encrypting key. The clear key can then be imported as any of the possible key types. This service does not adjust key parity. The callable service can execute only when ICSF is in special secure mode, which is described in “Special Secure Mode” on page 10. To import double-length and triple-length DATA keys, or double-length MAC, MACVER, CIPHER, DECIPHER and ENCIPHER keys, use the Multiple Secure Key Import callable service. See “Multiple Secure Key Import (CSNBSKM and CSNESKM)” on page 209. To import AES DATA keys, use the multiple secure key import service (“Multiple Secure Key Import (CSNBSKM and CSNESKM)” on page 209). The callable service name for AMODE(64) invocation is CSNESKI. Chapter 5. Managing Symmetric Cryptographic Keys 243 Secure Key Import Format CALL CSNBSKI( return_code, reason_code, exit_data_length, exit_data, clear_key, key_type, key_form, importer_key_identifier, key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. clear_key Direction: Input Type: String The clear key to be enciphered. Specify a 16-byte string (clear key value). For single-length keys, the value must be left-justified and padded with zeros. For effective single-length keys, the value of the right half must equal the value of the left half. For double-length keys, specify the left and right key values. Note: For key types that can be single or double-length, a single length encrypted key will be generated if a clear_key value of zeros is supplied. key_type 244 z/OS V1R13 ICSF Application Programmer's Guide Secure Key Import Direction: Input Type: Character string The type of key you want to encipher under the master key or an importer key. Specify an 8-byte field that must contain a keyword from this list or the keyword TOKEN. If the key type is TOKEN, ICSF determines the key type from the CV in the key_identifier parameter. Key type values for the Secure Key Import callable service are: CIPHER, CVARDEC, CVARENC, CVARPINE, CVARXCVL, CVARXCVR, DATA, DATAXLAT, DECIPHER, ENCIPHER, EXPORTER, IKEYXLAT, IMPORTER, IMP-PKA, IPINENC, MAC, MACVER, OKEYXLAT, OPINENC, PINGEN and PINVER. For information on the meaning of the key types, see Table 3 on page 23. key_form Direction: Input Type: Character string The key form you want to generate. Enter a 4-byte keyword specifying whether the key should be enciphered under the master key (OP) or the importer key-encrypting key (IM). The keyword must be left-justified and padded with blanks. Valid keyword values are OP for encryption under the master key or IM for encryption under the importer key-encrypting key. If you specify IM, you must specify an importer key-encrypting key in the importer_key_identifier parameter. For a key_type of IMP-PKA, this service supports only the OP key_form. importer_key_identifier Direction: Input/Output Type: String The importer key-encrypting key under which you want to encrypt the clear key. Specify either a 64-byte string of the internal key format or a key label. If you specify IM for the key_form parameter, the importer_key_identifier parameter is required. key_identifier Direction: Input/Output Type: String The generated encrypted key. The parameter is a 64-byte string. The callable service returns either an internal key token if you encrypted the clear key under the master key (key_form was OP); or an external key token if you encrypted the clear key under the importer key-encrypting key (key_form was IM). If the imported key_type is IMPORTER or EXPORTER and the key_form is OP, the 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. Note: Propagation of the NOCV bit is not performed if the service is processed on the PCI Cryptographic Coprocessor. The secure key import service does not adjust key parity. ICSF supports two methods of wrapping the key value in a symmetric key token: the original ECB wrapping and an enhanced CBC wrapping method which is ANSI X9.24 compliant. The output key_identifier will use the default Chapter 5. Managing Symmetric Cryptographic Keys 245 Secure Key Import wrapping method unless a skeleton token is supplied as input. If a skeleton token is supplied as input, the wrapping method in the skeleton token will be used. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS. Systems with the Cryptographic Coprocessor Feature: To generate double-length MAC and MACVER keys in the importable form, the ANSI system keys must be installed in the CKDS. This service will mark DATA, IMPORTER and EXPORTER key tokens with the system encryption algorithm. v This service marks the imported DATA key token according to the system's default encryption algorithm, unless token copying overrides this. v KEKs are marked SYS-ENC unless token copying overrides this. v To override the default mark, supply a valid internal token of the same key type in the key_identifier field. The service will copy the marks of the supplied token to the imported token. Systems with the PCI X Cryptographic Coprocessor, Crypto Express2 Coprocessor, or Crypto Express3 Coprocessor: If key_form is IM and the importer_key_identifier is NOCV KEK, the NOCV IMPORTER access control point must be enabled. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 90. Required access control points for Secure Key Import | Key Form Access control point | OP Secure Key Import - DES, OP | | IM Secure Key Import - DES, IM | | | To use a NOCV key-encrypting key with the secure key import service, the NOCV KEK usage for import-related functions access control point must be enabled in addition to one or both of the access control points listed. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. 246 z/OS V1R13 ICSF Application Programmer's Guide Secure Key Import Table 91. Secure key import required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature PCI Cryptographic Coprocessor Marking of data encryption algorithm bits and token copying are performed only if the service is processed on the Cryptographic Coprocessor Feature. ICSF routes the request to a PCI Cryptographic Coprocessor if: v The control vector of a supplied internal token cannot be processed on the Cryptographic Coprocessor Feature, or if the key type is not valid for the Cryptographic Coprocessor Feature. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor Key_type DATAXLAT is not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor Key_type DATAXLAT is not supported. Crypto Express2 Coprocessor Key_type DATAXLAT is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Key_type DATAXLAT is not supported. Secure Key Import2 (CSNBSKI2 and CSNESKI2) | | | Use this service to encipher a variable-length symmetric key under the system master key or an AES IMPORTER KEK, depending on the Key Form rule provided. This service supports variable-length symmetric keys. This service returns variable-length CCA key tokens and uses the AESKW wrapping method. The callable service can execute only when ICSF is in special secure mode, which is described in “Special Secure Mode” on page 10. The callable service name for AMODE(64) is CSNESKI2. Chapter 5. Managing Symmetric Cryptographic Keys 247 Secure Key Import2 Format CALL CSNBSKI2( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, clear_key_bit_length, clear_key, key_name_length, key_name, user_associated_data_length, user_associated_data, key_encrypting_key_identifier_length, key_encrypting_key_identifier, target_key_identifier_length, target_key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value must be 3. rule_array 248 z/OS V1R13 ICSF Application Programmer's Guide Secure Key Import2 Direction: Input Type: String The rule_array contains keywords that provide control information to the callable service. 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. Table 92. Keywords for Secure Key Import2 Control Information Keyword Meaning Token algorithm (One Required) | HMAC The target key identifier is to be an HMAC key. AES The target key identifier is to be an AES key. Key Form (One Required) | | OP Specifies the key should be enciphered under the master key. IM Specifies the key should be enciphered under the key-encrypting key. Key Type (One Required) | | CIPHER The key type of the output token will be CIPHER. Only valid for AES algorithm. | | EXPORTER The key type of the output token will be EXPORTER. Only valid for AES algorithm. | | IMPORTER The key type of the output token will be IMPORTER. Only valid for AES algorithm. | MAC MAC generation key. Only valid for HMAC algorithm. | MACVER MAC verify key. Only valid for HMAC algorithm. TOKEN The key type will be determined from the key token supplied in the target_key_identifier parameter. ICSF does not check for the length of the key but uses the clear_key_bit_length parameter to determine the length of the key. clear_key_bit_length Direction: Input | Type: Integer The length of the value supplied in the clear_key parameter in bits. Valid lengths are 80 to 2048 for HMAC keys, and 128, 192, or 256 for AES keys. clear_key Direction: Input Type: String The value of the key to be imported. The value should be left justified and padded on the right with zeros to a byte boundary if the clear_key_bit_length is not a multiple of 8. key_name_length Direction: Input Type: Integer The length of the key_name parameter. Valid values are 0 and 64. key_name Chapter 5. Managing Symmetric Cryptographic Keys 249 Secure Key Import2 Direction: Input Type: String A 64-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 to 255 bytes. user_associated_data Direction: Input Type: String User-associated data to be stored in the associated data structure. | key_encrypting_key_identifier_length || | Direction: Input Type: Integer The byte length of the key_encrypting_key_identifier parameter. When Key Form is OP, the value must be zero. When Key Form is IM, the value must be between the actual length of the token and 725 when key_encrypting_key_identifier is a token. The value must be 64 when key_encrypting_key_identifier is a label. | | | | | | key_encrypting_key_identifier || | Direction: Input/Output Type: String | | | When the Key Form rule is OP, key_encrypting_key_identifier is ignored. When the Key Form rule is IM, key_encrypting_key_identifier contains an internal key token containing the AES importer key-encrypting key or a key label. | | If the token supplied was encrypted under the old master key, the token will be returned encrypted under the current master key. 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 900 bytes. | On output, the parameter will hold the actual length of the target key token. target_key_identifier Direction: Input/Output Type: String The output key token. On input, this parameter is ignored except when the Key Type keyword is TOKEN. If you specify the TOKEN keyword, then this field contains a valid token of the key type you want to import. On output, when Key Form is OP, this will be an internal variable-length symmetric token. When Key Form is IM, this will be an external variable-length symmetric token. See rule_array for a list of valid key types. | | | | | | 250 z/OS V1R13 ICSF Application Programmer's Guide Secure Key Import2 Usage Notes The following table shows the access control points in the ICSF role that control the function of this service. | Table 93. Required access control points for Secure Key Import2 | Key Form Access control point | OP Secure Key Import2 – OP | | IM Secure Key Import2 – IM This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 94. Secure Key Import2 required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC | | | | z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. Crypto Express3 Coprocessor HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). AES key support requires the Sep. 2011 or later licensed internal code (LIC). Symmetric Key Export (CSNDSYX and CSNFSYX) | | | | | | | | Use the symmetric key export callable service to transfer an application-supplied AES DATA (version X‘04’), DES DATA, or variable-length symmetric key token key from encryption under a master key to encryption under an application-supplied RSA public key or AES EXPORTER key. The application-supplied key must be an ICSF AES, DES, or HMAC internal key token or the label of such a token in the CKDS. The Symmetric Key Import or Symmetric Key Import2 callable services can import the key encrypted under the RSA public key or AES EXPORTER at the receiving node. The callable service name for AMODE(64) is CSNFSYX. Chapter 5. Managing Symmetric Cryptographic Keys 251 Symmetric Key Export Format CALL CSNDSYX( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, source_key_identifier_length, source_key_identifier, transporter_key_identifier_length, transporter_key_identifier, enciphered_key_length, enciphered_key) | | | | Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. Value may be 1, 2, or 3. rule_array Direction: Input 252 z/OS V1R13 ICSF Application Programmer's Guide Type: String Symmetric Key Export Keywords that provide control information to the callable service. Table 95 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. Table 95. Keywords for Symmetric Key Export Control Information Keyword Meaning Algorithm (One keyword, optional) | | | | | | | AES The key being exported is an AES key. If source_key_identifier is a variable-length symmetric key token or label, only the PKOAEP2 and AESKW key formatting methods are supported. DES The key being exported is a DES key. This is the default. HMAC The key being exported is an HMAC key. Only the PKOAEP2 and AESKW key formatting methods are supported. Key Formatting method (One required) | | | | | AESKW Specifies that the key is to be formatted using AESKW and placed in an external variable length CCA token. The transport_key_identifier must be an AES EXPORTER. This rule is not valid with the DES Algorithm keyword or with AES DATA (version X'04') keys. PKCSOAEP Specifies to format the key according to the method in RSA DSI PKCS #1V2 OAEP. The default hash method is SHA-1. Use the SHA-256 keyword for the SHA-256 hash method. PKCS–1.2 Specifies to format the key according the method found in RSA DSI PKCS #1 block type 02 to recover the symmetric key. PKOAEP2 Specifies to format the key according to the method found in RSA DSI PKCS #1 v2.1 RSAES-OAEP documentation. Not valid with DES algorithm or with AES DATA (version X’04’) keys. A hash method is required. ZERO-PAD The clear key is right-justified in the field provided, and the field is padded to the left with zeros up to the size of the RSA encryption block (which is the modulus length). | | | | | | | Hash Method (One, optional for PKCSOAEP, required for PKOAEP2. Not valid with any other Key Formatting method) SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash. This is the default for PKCSOAEP. SHA-256 Specifies to use the SHA-256 hash method to calculate the OAEP message hash. SHA-384 Specifies to use the SHA-384 hash method to calculate the OAEP message hash. Not valid with PKCSOAEP. SHA-512 Specifies to use the SHA-512 hash method to calculate the OAEP message hash. Not valid with PKCSOAEP. | | | source_key_identifier_length Direction: Input Type: Integer The length of the source_key_identifier parameter. The minimum size is 64 bytes. The maximum size is 725 bytes. Chapter 5. Managing Symmetric Cryptographic Keys 253 Symmetric Key Export source_key_identifier Direction: Input/Output Type: String The label or internal token of a secure AES DATA (version X‘04’), DES DATA, or variable-length symmetric key token to encrypt under the supplied RSA public key or AES EXPORTER key. The key in the key identifier must match the algorithm in the rule_array. DES is the default algorithm. | | | | | transporter_key_identifier_length || | Direction: Input Type: Integer The length of the transporter_key_identifier parameter. The maximum size is 3500 bytes for an RSA key token or 725 for an AES EXPORTER key token. The length must be 64 if transporter_key_identifier is a label. | | | | transporter_key_identifier || | Direction: Input Type: String | | An RSA public key token, AES EXPORTER token, or label of the key to protect the exported symmetric key. | | | | When the AESKW Key Formatting method is specified, this parameter must be an AES EXPORTER key token or label with the EXPORT bit on in the key-usage field. Otherwise, this parameter must be an RSA public key token or label. | enciphered_key_length || | Direction: Input/Output Type: Integer The length of the enciphered_key parameter. This is updated with the actual length of the enciphered_key generated. The maximum size you can specify in this parameter is 900 bytes, although the actual key length may be further restricted by your hardware configuration (as shown in Table 100 on page 257). | | | | | enciphered_key || | Direction: Output Type: String This field contains the exported key, protected by the RSA public or AES EXPORTER key specified in the transporter_key_identifier field. | | Restrictions If you are running with the Cryptographic Coprocessor Feature, the enhanced system keys must be present in the CKDS. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. If an RSA public key is specified as the transporter_key_identifier, the hardware configuration sets the limit on the modulus size of keys for key management; thus, this service will fail if the RSA key modulus bit length exceeds this limit. | | | 254 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Export | | | | | | | | | | | | | The strength of the exporter key expected by Symmetric Key Export depends on the attributes of the key being exported. The resulting return code and reason code when using an exporter KEK that is weaker depends on the “Variable-length Symmetric Token - disallow weak wrap” and “Variable-length Symmetric Token warn when weak wrap” access control points: v If the “Variable-length Symmetric Token - disallow weak wrap” access control point is disabled (the default), the key strength requirement will not be enforced. Using a weaker key will result in return code 0 with a non-zero reason code if the “Variable-length Symmetric Token - warn when weak wrap” access control point is enabled. Otherwise, a reason code of zero will be returned. v If the “disallow” access control point is enabled (using TKE), the key strength requirement will be enforced, and attempting to use a weaker key will result in return code 8. | | For AES DATA and AES CIPHER keys, the AES EXPORTER key must be at least as long as the key being exported to be considered sufficient strength. | | For HMAC keys, the AES EXPORTER must be sufficient strength as described in the following table. | | Table 96. AES EXPORTER strength required for exporting an HMAC key under an AES EXPORTER | | Key-usage field 2 in the HMAC key contains: Minimum strength of AES EXPORTER to adequately protect the HMAC key: | | SHA-256, SHA-384, SHA-512 256 bits | SHA-224 192 bits | | SHA-1 128 bits | | | If an RSA public key is specified as the transporter_key_identifier, the RSA key used must have a modulus size greater than or equal to the total PKOAEP2 message bit length (key size + total overhead): | | Table 97. Minimum RSA modulus strength required to contain a PKOAEP2 block when exporting an AES key | | | | AES key size SHA-1 SHA-256 SHA-384 SHA-512 | 128 bits 736 bits 928 bits 1184 bits 1440 bits | 192 bits 800 bits 992 bits 1248 bits 1504 bits | | 256 bits 800 bits 1056 bits 1312 bits 1568 bits | Table 98. Minimum RSA modulus length to adequately protect an AES key | | AES key to be exported: Minimum strength of RSA wrapping key to adequately protect the AES key: | AES 128 3072 | AES 192 7860 | | AES 256 15360 Total message sizes (and therefore minimum RSA key size) when the Hash Method is: Chapter 5. Managing Symmetric Cryptographic Keys 255 Symmetric Key Export | | Note that wrapping an AES 192-bit key or an AES 256-bit key with any RSA key will always be considered a weak wrap. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 99. Required access control points for Symmetric Key Export | | Key formatting method Algorithm Access control point | | PKCSOAEP AES Symmetric Key Export - AES, PKCSOAEP, PKCS-1.2 DES Symmetric Key Export - DES, PKCS-1.2 AES Symmetric Key Export - AES, PKCSOAEP, PKCS-1.2 DES Symmetric Key Export - DES, PKCS-1.2 AES Symmetric Key Export - AES, ZERO-PAD DES Symmetric Key Export - DES, ZERO-PAD HMAC Symmetric Key Export - HMAC, PKOAEP2 AES Symmetric Key Export - AES, PKOAEP2 AES or HMAC Symmetric Key Export - AESKW | | | | PKCS-1.2 | | | | ZERO-PAD | | | | PKOAEP2 | | | AESKW | | Restricted operation Access control point | | Prohibit wrapping a key with a weaker key Variable-length Symmetric Token - disallow weak wrap | | | Issue a non-zero reason code when using a weak wrapping key Variable-length Symmetric Token - warn when weak wrap | | | Note that both the “Variable-length Symmetric Token - disallow weak wrap” and “Variable-length Symmetric Token - warn when weak wrap” access control points are disabled in the default role. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. 256 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Export Table 100. Symmetric key export required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature RSA keys with moduli greater than 1024-bit length are not supported. Encrypted AES keys are not supported. The DES, HMAC, and PKOAEP2 keywords are not supported. PCI Cryptographic Coprocessor | | | | ICSF routes this service to a PCI Cryptographic Coprocessor if one is available on your server. This service will not be routed to a PCI Cryptographic Coprocessor if the modulus bit length of the RSA public key is less than 512 bits. Use of keyword PKCSOAEP requires the PCI Cryptographic Coprocessor and uses the SHA-1 hash method. The SHA-256 keyword is not supported for PKCSOAEP. RSA keys with moduli greater than 2048-bit length are not supported. Encrypted AES keys are not supported. | | The DES, AESKW, HMAC, and PKOAEP2 keywords are not supported. IBM Eserver zSeries PCI X Cryptographic Coprocessor 990 RSA keys with moduli greater than 2048-bit length are not supported. IBM Eserver zSeries Crypto Express2 Coprocessor 890 Encrypted AES keys are not supported. | | The AESKW, HMAC, and PKOAEP2 keywords are not supported. | | The SHA-256 keyword is not supported for PKCSOAEP. IBM System z9 EC IBM System z9 BC Crypto Express2 Coprocessor RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Encrypted AES key support requires the Nov. 2008 or later licensed internal code (LIC). | | The AESKW, HMAC, and PKOAEP2 keywords are not supported. | | The SHA-256 keyword is not supported for PKCSOAEP. Chapter 5. Managing Symmetric Cryptographic Keys 257 Symmetric Key Export Table 100. Symmetric key export required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z10 EC Crypto Express2 Coprocessor RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). IBM System z10 BC Encrypted AES key support requires the Nov. 2008 or later licensed internal code (LIC). | | The AESKW, HMAC, and PKOAEP2 keywords are not supported. | | The SHA-256 keyword is not supported for PKCSOAEP. | | Crypto Express3 Coprocessor | | The AESKW, HMAC, and PKOAEP2 keywords are not supported. The SHA-256 keyword is not supported for PKCSOAEP. | | z196 Crypto Express3 Coprocessor | | | | HMAC key support requires the Nov. 2010 licensed internal code (LIC). Variable-length AES Keys, the AESKW method, and PKCSOAEP with the SHA-256 hash method require the Sep. 2011 or later licensed internal code (LIC). Symmetric Key Generate (CSNDSYG and CSNFSYG) Use the symmetric key generate callable service to generate an AES or DES DATA key and return the key in two forms: enciphered under the master key and encrypted under an RSA public key. You can import the RSA public key encrypted form by using the symmetric key import service at the receiving node. Also use the symmetric key generate callable service to generate any DES importer or exporter key-encrypting key encrypted under a RSA public key according to the PKA92 formatting structure. See “PKA92 Key Format and Encryption Process” on page 881 for more details about PKA92 formatting. The callable service name for AMODE(64) invocation is CSNFSYG. 258 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Generate Format CALL 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, local_enciphered_key_token_length, local_enciphered_key_token, RSA_enciphered_key_length, RSA_enciphered_key) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input | | Type: Integer The number of keywords you supplied in the rule_array parameter. The value must be 1, 2, 3, 4, 5, 6, or 7. rule_array Direction: Input Type: String Chapter 5. Managing Symmetric Cryptographic Keys 259 Symmetric Key Generate Keywords that provide control information to the callable service. Table 101 lists the keywords. 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. Table 101. Keywords for Symmetric Key Generate Control Information Keyword Description Algorithm Algorithm (one keyword, optional) AES The key being generated is a secure AES AES key. DES The key being generated is a DES key. This is the default. DES Key formatting method (one keyword required) PKA92 Specifies the key-encrypting key is to be encrypted under a PKA96 RSA public key according to the PKA92 formatting structure. DES PKCSOAEP Specifies using the method found in RSA DSI PKCS #1V2 OAEP. The default hash method is SHA-1. Use the SHA-256 keyword for the SHA-256 hash method. AES or DES PKCS-1.2 Specifies the method found in RSA DSI PKCS #1 block type 02. AES or DES ZERO-PAD The clear key is right-justified in the AES or DES field provided, and the field is padded to the left with zeros up to the size of the RSA encryption block (which is the modulus length). | | | | Key Length (optional - for use with PKA92) SINGLE-R DES For key-encrypting keys, this specifies that the left half and right half of the generated key will have identical values. This makes the key operate identically to a single-length key with the same value. Without this keyword, the left and right halves of the key-encrypting key will each be generated randomly and independently. Key Length (optional - for use with PKCSOAEP, PKCS-1.2, or ZERO-PAD) SINGLE, KEYLN8 Specifies that the generated key should be 8 bytes in length. DES DOUBLE Specifies that the generated key should be 16 bytes in length. DES KEYLN16 Specifies that the generated key should be 16 bytes in length. AES or DES KEYLN24 Specifies that the generated key should be 24 bytes in length. AES or DES KEYLN32 Specifies that the generated key should be 32 bytes in length. AES Encipherment method for the local enciphered copy of the key (optional - for use with PKCSOAEP, PKCS-1.2, or ZERO-PAD 260 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Generate Table 101. Keywords for Symmetric Key Generate Control Information (continued) Keyword Description Algorithm OP Enciphers the key with the master key. The DES master key is used with DES keys and the AES master key is used with AES keys. AES or DES EX Enciphers the key with the EXPORTER key that is provided through the key_encrypting_key_identifier parameter. DES IM Enciphers the key with the IMPORTER key-encrypting key specified with the key_encrypting_key_identifier parameter. DES Key Wrapping Method (optional) USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default keyword. AES and DES The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. | WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. DES WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. AES or DES Translation Control (optional) ENH-ONLY Restrict rewrapping of the target_key_identifier token. Once the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. DES | Hash Method (optional - only valid with PKCSOAEP) | | | SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash. This is the default. AES or DES | | | SHA-256 Specifies to use the SHA-256 hash method to calculate the OAEP message hash. AES or DES key_encrypting_key_identifier Direction: Input/Output Type: String Chapter 5. Managing Symmetric Cryptographic Keys 261 Symmetric Key Generate 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. Otherwise, the parameter is ignored. 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. RSA_public_key_identifier Direction: Input Type: String The token, or label, of the RSA public key to be used for protecting the generated symmetric key. local_enciphered_key_token_length (was DES_enciphered_key_token_length) Direction: Input/Output Type: Integer The length in bytes of the local_enciphered_key_token. This field is updated with the actual length of the token that is generated. The minimum length is 64-bytes and the maximum length is 128 bytes. local_enciphered_key_token (was DES_enciphered_key_token) Direction: Input/Output Type: String This parameter contains the generated DATA key in the form of an internal or external token, depending on rule_array specification. If you specify PKA92, on input specify an internal (operational) key token of an Importer or Exporter Key. RSA_enciphered_key_length Direction: Input/Output Type: Integer The length of the RSA_enciphered_key parameter. This service updates this field with the actual length of the RSA_enciphered_key it generates. The maximum size is 512 bytes. RSA_enciphered_key Direction: Input/Output Type: String This field contains the RSA enciphered key, which is protected by the public key specified in the RSA_public_key_identifier field. | | Restrictions If the service is executed on the Cryptographic Coprocessor Feature, and you specify IM in the rule_array, you must enable Special Secure Mode. Use of PKA92 or PKCSOAEP requires a PCICC, PCIXCC, CEX2C, or CEX3C. 262 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Generate Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. If the service is executed on the Cryptographic Coprocessor Feature, the generated internal DATA key token is marked according to the system default algorithm. The hardware configuration sets the limit on the modulus size of keys for key management; thus, this service will fail if the RSA key 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 service enciphers one key copy using the key encipherment technique employed in the IBM Transaction Security System (TSS) 4753, 4755, and AS/400 cryptographic product PKA92 implementations (see “PKA92 Key Format and Encryption Process” on page 881). 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 service are permitted. The control vector for the local key is taken from a DES key token that must be present on input in the local_enciphered_key_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. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 102. Required access control points for Symmetric Key Generate | Key algorithm Key formatting rule Access control point | | DES PKCS-1.2 Symmetric Key Generate - DES, PKCS-1.2 | | DES ZERO-PAD Symmetric Key Generate - DES, ZERO-PAD | | DES PKA92 Symmetric Key Generate - DES, PKA92 | | AES PKCSOAEP, PKCS-1.2 Symmetric Key Generate - AES, PKCSOAEP, PKCS-1.2 | | | AES ZERO-PAD Symmetric Key Generate - AES, ZERO-PAD | | | | When the WRAP-ECB or WRAP-ENH keywords are specified and the default key-wrapping method setting does not match the keyword, the Symmetric Key Generate - Allow wrapping override keywords access control point must be enabled. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 5. Managing Symmetric Cryptographic Keys 263 Symmetric Key Generate Table 103. Symmetric key generate required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions ICSF routes this service to a PCI Cryptographic Coprocessor if one is available on your server. This service will not be routed to a PCI Cryptographic Coprocessor if the modulus bit length of the RSA public key is less than 512 bits. RSA keys with moduli greater than 1024-bit length are not supported. Secure AES keys are not supported. | | | DES, ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 keywords not supported. PCI Cryptographic Coprocessor | | Use of keyword PKA92 or PKCSOAEP requires the PCI Cryptographic Coprocessor. PKCSOAEP uses the SHA-1 hash method. RSA keys with moduli greater than 2048-bit length are not supported. Secure AES keys are not supported. | | | DES, ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, SHA-1, and SHA-256 keywords not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. IBM Eserver zSeries PCI X Cryptographic Coprocessor 990 IBM Eserver zSeries Crypto Express2 Coprocessor 890 The generated internal DATA key will not have any system encryption algorithm markings. RSA keys with moduli greater than 2048-bit length are not supported. Secure AES keys are not supported. | | | ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 keywords not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. 264 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Generate Table 103. Symmetric key generate required hardware (continued) Server Required cryptographic hardware Restrictions IBM Systems z9 EC Crypto Express2 Coprocessor The generated internal DATA key will not have any system encryption algorithm markings. IBM System z9 BC RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). | | ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. IBM System z10 EC Crypto Express2 Coprocessor IBM System z10 BC The generated internal DATA key will not have any system encryption algorithm markings. RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). | | ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. Crypto Express3 Coprocessor The generated internal DATA key will not have any system encryption algorithm markings. RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). | The SHA-256 keyword is not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. z196 | | | Crypto Express3 Coprocessor The generated internal DATA key will not have any system encryption algorithm markings. PKCSOAEP with the SHA-256 hash method requires the Sep. 2011 or later licensed internal code (LIC). Chapter 5. Managing Symmetric Cryptographic Keys 265 Symmetric Key Import Symmetric Key Import (CSNDSYI and CSNFSYI) Use the symmetric key import callable service to import a symmetric AES DATA or DES DATA key enciphered under an RSA public key. It returns the key in operational form, enciphered under the master key. This service also supports import of a PKA92-formatted DES key-encrypting key under a PKA96 RSA public key. The callable service name for AMODE(64) is CSNFSYI. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. 266 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Import rule_array_count Direction: Input | | Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 1, 2, 3, 4, or 5. rule_array Direction: Input Type: String The keywords that provide control information to the callable service. Table 104 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. Table 104. Keywords for Symmetric Key Import Control Information Keyword Meaning Algorithm (one keyword, optional) AES The key being imported is an AES key. DES The key being imported is a DES key. This is the default. Recovery Method (required) PKA92 Supported by the DES algorithm. Specifies the key-encrypting key is encrypted under a PKA96 RSA public key according to the PKA92 formatting structure. PKCSOAEP Specifies to use the method found in RSA DSI PKCS #1V2 OAEP. Supported by the DES and AES algorithms. The default hash method is SHA-1. Use the SHA-256 keyword for the SHA-256 hash method. PKCS-1.2 Specifies to use the method found in RSA DSI PKCS #1 block type 02. Supported by the DES and AES algorithms. ZERO-PAD The clear key is right-justified in the field provided, and the field is padded to the left with zeros up to the size of the RSA encryption block (which is the modulus length). Supported by the DES and AES algorithms. | | Key Wrapping Method (optional) USECONFG Specifies that the system default configuration should be used to determine the wrapping method. This is the default keyword. The system default key wrapping method can be specified using the DEFAULTWRAP parameter in the installation options data set. See the z/OS Cryptographic Services ICSF System Programmer's Guide. WRAP-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard. WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens and CBC wrapping for AES key tokens. Translation Control (optional) Chapter 5. Managing Symmetric Cryptographic Keys 267 Symmetric Key Import Table 104. Keywords for Symmetric Key Import Control Information (continued) Keyword Meaning ENH-ONLY Restrict rewrapping of the target_key_identifier token. Once the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method. | Hash Method (optional - only valid with PKCSOAEP) | | SHA-1 Specifies to use the SHA-1 hash method to calculate the OAEP message hash. This is the default. | | SHA-256 Specifies to use the SHA-256 hash method to calculate the OAEP message hash. RSA_enciphered_key_length Direction: Input Type: integer The length of the RSA_enciphered_key parameter. The maximum size is 512 bytes. RSA_enciphered_key Direction: Input Type: String The key to import, protected under an RSA public 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 RSA private 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 size must be 64 bytes. target_key_identifier Direction: Input/Output 268 z/OS V1R13 ICSF Application Programmer's Guide Type: String Symmetric Key Import This field contains the internal token of the imported symmetric key. Except for PKA92 processing, this service produces a DATA key token with a key of the same length as that contained in the imported token. Restrictions The exponent of the RSA public key must be odd. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. If the service is executed on the Cryptographic Coprocessor Feature, the generated internal DATA key token is marked according to the default system encryption algorithm unless token copying overrides this. Token copying is accomplished by supplying a valid DATA token with the desired algorithm marks in the target_key_identifier field. The hardware configuration sets the limit on the modulus size of keys for key management; thus, this service will fail if the RSA key modulus bit length exceeds this limit. The service will fail with return code 12 and reason code 11020. Specification of PKA92 with an input NOCV key-encrypting key token is not supported. During initialization of a PCICC, PCIXCC, CEX2C, or CEX3C, an Environment Identification, or EID, of zero will be set in the coprocessor. This will be interpreted by the PKA Symmetric Key Import service to mean that environment identification checking is to be bypassed. Thus it is possible on a OS/390 system for a key-encrypting key RSA-enciphered at a node (EID) to be imported at the same node. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 105. Required access control points for Symmetric Key Import | Key algorithm Key formatting rule Access control point | | DES PKCS-1.2 Symmetric Key Import - DES, PKCS-1.2 | | DES PKA92 KEK Symmetric Key Import - DES, PKA92 KEK | | DES ZERO-PAD Symmetric Key Import - DES, ZERO-PAD | | AES PKCSOAEP, PKCS-1.2 Symmetric Key Import - AES, PKCSOAEP, PKCS-1.2 | | | AES ZERO-PAD Symmetric Key Import - AES, ZERO-PAD | | | | When the WRAP-ECB or WRAP-ENH keywords are specified and the default key-wrapping method setting does not match the keyword, the Symmetric Key Import - Allow wrapping override keywords access control point must be enabled. Chapter 5. Managing Symmetric Cryptographic Keys 269 Symmetric Key Import This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 106. Symmetric key import required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions Request routed to the CCF when v The RSA_private_key_identifier is a modulus-exponent form private key with a private section ID of X'02' v The key modulus bit length is less than 512 RSA keys with moduli greater than 1024-bit length are not supported. Encrypted AES keys are not supported. | | DES, ENH-ONLY, USECONFG, WRAP-ENH and WRAP-ECB keywords not supported. PCI Cryptographic Coprocessor Request routed to PCICC when v The RSA_private_key_identifier is a modulus-exponent form private key with a private section ID of X'06' v The RSA_private_key_identifier is a CRT form private key with a private section ID of X'08' v The RSA_private_key_identifier is a retained key v PKA92 recovery method specified | | v PKCSOAEP recovery method (which uses the SHA-1 hash method) specified RSA keys with moduli greater than 2048-bit length are not supported. Encrypted AES keys are not supported. | | | DES, ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 keywords not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. 270 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Import Table 106. Symmetric key import required hardware (continued) Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor IBM Eserver zSeries Crypto Express2 890 Coprocessor The imported internal DATA key will not have any system encryption markings. Old RSA private keys encrypted under the CCF KMMK is not usable if the KMMK is not the same as the PCIXCC/CEX2C ASYM-MK. RSA keys with moduli greater than 2048-bit length are not supported. Encrypted AES keys are not supported. | | | ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 keywords not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. IBM System z9 EC IBM System z9 BC Crypto Express2 Coprocessor The imported internal DATA key will not have any system encryption markings. Old RSA private keys encrypted under the CCF KMMK is not usable if the KMMK is not the same as the CEX2C ASYM-MK. RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Encrypted AES keys are not supported. | | | ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 keywords not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. Chapter 5. Managing Symmetric Cryptographic Keys 271 Symmetric Key Import Table 106. Symmetric key import required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z10 EC Crypto Express2 Coprocessor The imported internal DATA key will not have any system encryption markings. Old RSA private keys encrypted under the CCF KMMK is not usable if the KMMK is not the same as the CEX2C or CEX3C ASYM-MK. IBM System z10 BC RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Encrypted AES key support requires the Nov. 2008 or later licensed internal code (LIC). | | | ENH-ONLY, USECONFG, WRAP-ENH, WRAP-ECB, and SHA-256 keywords not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. Crypto Express3 Coprocessor The imported internal DATA key will not have any system encryption markings. Old RSA private keys encrypted under the CCF KMMK is not usable if the KMMK is not the same as the CEX2C or CEX3C ASYM-MK. RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Encrypted AES key support requires the Nov. 2008 or later licensed internal code (LIC). | The SHA-256 keyword is not supported. | | PKCSOAEP with the SHA-256 hash method is not supported. z196 Crypto Express3 Coprocessor | | | The imported internal DATA key will not have any system encryption markings. Old RSA private keys encrypted under the CCF KMMK is not usable if the KMMK is not the same as the CEX2C or CEX3C ASYM-MK. PKCSOAEP with the SHA-256 hash method requires the Sep. 2011 or later licensed internal code (LIC). Symmetric Key Import2 (CSNDSYI2 and CSNFSYI2) Use the Symmetric Key Import2 callable service to import an HMAC or AES key enciphered under an RSA public key or AES EXPORTER key. It returns the key in operational form, enciphered under the master key. | | 272 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Import2 This service returns a variable-length CCA key token and uses the AESKW wrapping method. The callable service name for AMODE(64) is CSNFSYI2. Format CALL CSNDSYI2( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, enciphered_key_length, enciphered_key, transport_key_identifier_length, transport_key_identifier, key_name_length, key_name, target_key_identifier_length, target_key_identifier) | | | | Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 273 Symmetric Key Import2 The number of keywords you supplied in the rule_array parameter. The value must be 2. rule_array Direction: Input Type: String The keywords that provide control information to the callable service. 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. | Table 107. Keywords for Symmetric Key Import2 Control Information | Keyword | Algorithm (One required) | AES The key being imported is an AES key. | HMAC The key being imported is an HMAC key. | Recovery Method (Required) | | AESKW Specifies the enciphered key has been wrapped with the AESKW formatting method. | | | PKOAEP2 Specifies to use the method found in RSA DSI PKCS #1V2 OAEP. | enciphered_key_length || | Direction: Input Meaning Type: integer The length of the enciphered_key parameter. The maximum size is 900 bytes. | | enciphered_key || | Direction: Input Type: String The key to import, protected under either an RSA public key or an AES KEK. If the Recovery Method is PKOAEP2, 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. If the Recovery Method is AESKW, the encrypted key is an AES key or HMAC key in the external variable length key token. | | | | | | | transport_key_identifier_length || | Direction: Input Type: Integer The length of the transport_key_identifier parameter. When the transport_key_identifier parameter is a key label, this field must be 64. The maximum size is 3500 bytes for an RSA private key or 725 bytes for an AES IMPORTER KEK. | | | | | transport_key_identifier || | Direction: Input 274 z/OS V1R13 ICSF Application Programmer's Guide Type: String Symmetric Key Import2 | | | An internal RSA private key token, internal AES IMPORTER KEK, or the 64-byte label of a key token whose corresponding key protects the symmetric key. | | | When the AESKW Key Formatting method is specified, this parameter must be an AES IMPORTER with the IMPORT bit on in the key-usage field. Otherwise, this parameter must be an RSA private 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 A 64-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 The exponent of the RSA public key must be odd. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. This is the message layout used to encode the key material exported with the new PKOAEP2 formatting method. Table 108. PKCS#1 OAEP encoded message layout (PKOAEP2) Field Size Value Hash field 32 Bytes SHA-256 hash of associated data section in the source key identifier Key Bit Length 2 Bytes variable Key Material Byte length of the variable key material (rounded up to the nearest byte) Chapter 5. Managing Symmetric Cryptographic Keys 275 Symmetric Key Import2 Hash field The associated data for the HMAC variable length token is hashed using SHA-256. Specifically referring to vartoken.h, this is the "VarAssocData_t AD" section of the VarKeyTkn_t structure, for the full length indicated in the 'SectLn' field of the VarAssocData_t. Key Bit Length A 2 Byte key bit length field. Key Material The key material is padded to the nearest byte with '0' bits. This table lists the access control points in the ICSF role that control the function for this service. | Table 109. Symmetric Key Import2 Access Control Points | Key formatting method Algorithm Access control point | | PKOAEP2 HMAC, AES Symmetric Key Import2 HMAC/AES, PKOAEP2 | | | AESKW HMAC, AES Symmetric Key Import2 HMAC/AES, AESKW | | | | | When the Symmetric Key Import2 - disallow weak import access control point is enabled, a key token wrapped with a weaker key will not be imported. When the Variable-length Symmetric Token - warn when weak wrap access control point is enabled, the reason code will indicate when the wrapping key is weaker than the key being imported. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 110. Symmetric key import2 required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC 276 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor This service is not supported. z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Import2 Table 110. Symmetric key import2 required hardware (continued) | | Server Required cryptographic hardware Restrictions z196 Crypto Express3 Coprocessor HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). | | | AES key support and the AESKW wrapping method require the Sep. 2011 or later licensed internal code (LIC). Transform CDMF Key (CSNBTCK and CSNETCK) This callable service is only supported on an IBM Eserver zSeries 900. Use the transform CDMF key callable service to change a CDMF DATA key in an internal or external token to a transformed shortened DES key. You can also use the key label of a CKDS record as input. The Cryptographic Coprocessor Feature on IBM Eserver zSeries 900, S/390 Enterprise Servers and S/390 Multiprise is configured as either CDMF or DES-CDMF. This callable service ignores the input internal DATA token markings, and it marks the output internal token for use in the DES. If the input DATA key is in an external token, the operational KEK must be marked as DES or SYS-ENC. The service fails for an external DATA key encrypted under a KEK that is marked as CDMF. The callable service name for AMODE(64) invocation is CSNETCK. Format CALL CSNBTCK( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, source_key_identifier, kek_key_identifier, target_key_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 277 Transform CDMF Key The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. This number must be 0. rule_array Direction: Input Type: String Currently no rule_array keywords are defined for this service, but you still must specify this parameter. source_key_identifier Direction: Input/Output Type: String A 64-byte string of the internal token, external token or key label that contains the DATA key to transform. Token markings on this key token are ignored. kek_key_identifier Direction: Input/Output Type: String A 64-byte string of the internal token or a key label of a key encrypting key under which the source_key_identifier is encrypted. Note: If you supply a label for this parameter, the label must be unique in the CKDS. target_key_identifier Direction: Output Type: String A 64-byte string where the internal token or external token of the transformed shortened DES key is returned. The internal token is marked as DES. 278 z/OS V1R13 ICSF Application Programmer's Guide Transform CDMF Key Restrictions This service is available on S/390 Enterprise Servers and S/390 Multiprise with Cryptographic Coprocessor Features. These systems may be configured as either CDMF or DES-CDMF. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. This service transforms a CDMF DATA key to a transformed shortened DES DATA key to allow interoperability to a DES-only capable system. The algorithm is described in Transform CDMF Key Algorithm. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 111. Transform CDMF key required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries 990 This callable service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This callable service is not supported. IBM System z9 BC IBM System z10 EC This callable service is not supported. IBM System z10 BC z196 This callable service is not supported. Trusted Block Create (CSNDTBC and CSNFTBC) This callable service is used to create a trusted block in a two step process. The block will be in external form, encrypted under an IMP-PKA transport key. This means that the MAC key contained within the trusted block will be encrypted under the IMP-PKA key. The callable service name for AMODE(64) invocation is CSNFTBC. Chapter 5. Managing Symmetric Cryptographic Keys 279 Trusted Block Create Format CALL CSNDTBC( return_code, reason_code exit_data_length, exit_data, rule_array_count, rule_array, input_block_length input_block_identifier transport_key_identifier, trusted_block_length, trusted_block_identifier ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, ICSF and TSS Return and Reason Codes lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the specific results of processing. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. This number must be 1. rule_array Direction: Input Type: String Specifies a string variable containing an array of keywords. The keywords are 8 bytes long and must be left-justified and right padded with blanks 280 z/OS V1R13 ICSF Application Programmer's Guide Trusted Block Create This table lists the rule_array keywords for this callable service. Table 112. Rule_array keywords for Trusted Block Create (CSNDTBC) Keyword Meaning Operational Keywords - One Required INACTIVE Create the trusted block, but in inactive form. The MAC key is randomly generated, encrypted with the transport key, and inserted into the block. The ACTIVE flag is set to False (0), and the MAC is calculated over the block and inserted in the appropriate field. The resulting block is fully formed and protected, but it is not usable in any other CCA services. Use of the INACTIVE keyword is authorized by the 0x030F access control point. ACTIVATE This makes the trusted block usable in CCA services. Use of the ACTIVATE keyword is authorized by the 0x0310 access control point. input_block_length Direction: Input/Output Type: String Specifies the number of bytes of data in the input_block_identifier parameter. The maximum length is 3500 bytes. input_block_identifier Direction: Input Type: String Specifies a trusted block label or complete trusted block token, which will be updated by the service and returned in trusted_block_identifier. The length is indicated by input_block_length. Its content depends on the rule array keywords supplied to the service. When rule_array is INACTIVE the block is complete but typically does not have MAC protection. If MAC protection is present due to recycling an existing trusted block, then the MAC key and MAC value will be overlaid by the new MAC key and MAC value. The input_block_identifier includes all fields of the trusted block token, but the MAC key and MAC will be filled in by the service. The Active flag will be set to False (0) in the block returned in trusted_block_identifier. When the rule_array is ACTIVATE the block is complete, including the MAC protection which is validated during execution of the service. The Active flag must be False (0) on input. On output, the block will be returned in trusted_block_identifier provided the identifier is a token, with the Active flag changed to True (1), and the MAC value recalculated using the same MAC key. If the trusted_block_identifier is a label, the block will be written to the PKDS. transport_key_identifier Direction: Input Type: String Specifies a key label or key token for an IMP-PKA key that is used to protect the trusted block. trusted_block_length Direction: Input/Output Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 281 Trusted Block Create Specifies the number of bytes of data in trusted_block_identifier parameter. The maximum length is 3500 bytes. trusted_block_identifier Direction: Output Type: String Specifies a trusted block label or trusted block token for the trusted block constructed by the service. On input, the trusted_block_length contains the size of this buffer. On output, the trusted_block_length is updated with the actual byte length of the trusted block written to the buffer if the trusted_block_identifier is a token. The trusted block consists of the data supplied in input_block_identifier, but with the MAC protection and Active flag updated according to the rule array keyword that is provided. See Table 112 on page 281 for details on the actions. If the trusted_block_identifier is a label identifying a key record in key storage, the returned trusted block token will be written to the PKDS. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | | The following table shows the access control points in the ICSF role that control the function of this service. | Table 113. Required access control points for Trusted Block Create | Rule array keyword Access control point | INACTIVE Trusted Block Create - Create Block in Inactive form | | ACTIVATE Trusted Block Create - Activate an Inactive Block This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 114. Trusted Block Create required hardware Server Required cryptographic hardware IBM Eserver zSeries 990 Restrictions This callable service is not supported. IBM Eserver zSeries 890 IBM Eserver zSeries 900 IBM System z9 EC IBM System z9 BC IBM System z10 EC This callable service is not supported. Cryptographic Express2 Coprocessor RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express2 Coprocessor RSA key support with moduli within the range 2048-bit to 4096-bit requires the Nov. 2007 or later licensed internal code (LIC). IBM System z10 BC Crypto Express3 Coprocessor 282 z/OS V1R13 ICSF Application Programmer's Guide Trusted Block Create Table 114. Trusted Block Create required hardware (continued) | Server Required cryptographic hardware Restrictions z196 Crypto Express3 Coprocessor TR-31 Export (CSNBT31X and CSNET31X) | | | | Use the TR-31 Export callable service to convert a CCA token to TR-31 format for export to another party. Since there is not always a one-to-one mapping between the key attributes defined by TR-31 and those defined by CCA, the caller may need to specify the attributes to attach to the exported key through the rule array. | The callable service name for AMODE(64) is CSNET31X. | Format || | | | | | | | | | | | | | | | | | | | | CALL CSNBT31X( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, key_version_number, key_field_length, source_key_identifier_length, source_key_identifier, unwrap_kek_identifier_length, unwrap_kek_identifier, wrap_kek_identifier_length, wrap_kek_identifier, opt_blks_length, opt_blocks, tr31_key_block_length, tr31_key_block ) Parameters | return_code || | Direction: Output | | The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. | reason_code || | Direction: Output | | | | | | Type: Integer Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Chapter 5. Managing Symmetric Cryptographic Keys 283 TR-31 Export || | Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. | | | | exit_data || | Direction: Input/Output Type: String The data that is passed to the installation exit. | | rule_array_count || | Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 3, 4, or 5. | | | rule_array || | Direction: Input Type: String | | | | | The rule_array contains keywords that provide control information to the callable service. The keywords are 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords for this callable service are shown in the following table. See Table 116 on page 289 for valid combinations of Usage and Mode | Table 115. Keywords for TR-31 Export Rule Array Control Information | Keyword | TR-31 key block protection method – one required | | VARXOR-A Use the variant method corresponding to a TR-31 Key Block Version ID of “A” (0x41) | | VARDRV-B Use the key derivation method corresponding to a TR-31 Key Block Version ID of “B” (0x42) | | VARXOR-C Use the variant method corresponding to a TR-31 Key Block Version ID of “C” (0x43) | | | TR-31 key usage values for output key – one required Note: If ATTR-CV is specified from the Control Vector Transport group, then usage keyword must not be specified. The proprietary usage ‘10’ will be used. | BDK Base Derivation Key (BDK) – ( B0 ) | CVK Card Verification Key (CVK) – ( C0 ) | ENC Data encryption key – ( D0 ) | EMVACMK EMV application cryptogram master key – ( E0 ) | EMVSCMK EMV secure messaging for confidentiality master key – ( E1 ) | EMVSIMK EMV secure messaging for integrity master key – ( E2 ) | EMVDAMK EMV data authentication code key – ( E3 ) | EMVDNMK EMV dynamic numbers master key – ( E4 ) | EMVCPMK EMV card personalization master key – ( E5 ) | KEK Key-encrypting key – ( K0 ) 284 z/OS V1R13 ICSF Application Programmer's Guide Meaning TR-31 Export | Table 115. Keywords for TR-31 Export Rule Array Control Information (continued) | Keyword Meaning | | KEK-WRAP Key-encrypting key for wrapping TR-31 blocks (for ‘B’ and ‘C’ TR-31 Key Block Version IDs only) – ( K1 ) | ISOMAC0 Key for ISO 16609 MAC algorithm 1 using TDES – ( M0 ) | ISOMAC1 Key for ISO 9797-1 MAC algorithm 1– ( M1 ) | ISOMAC3 Key for ISO 9797-1 MAC algorithm 3– ( M3 ) | PINENC PIN encryption key – ( P0 ) | PINVO PIN verification key, “other” algorithm – ( V0 ) | PINV3624 PIN verification key for IBM 3624 algorithm – ( V1 ) | VISAPVV PIN verification key, VISA PVV algorithm – ( V2 ) | | | TR-31 modes of key use – one required Note: If ATTR-CV is specified from the Control Vector Transport group, then mode keyword must not be specified. The proprietary mode ‘1’ will be used. | ENCDEC Encrypt and decrypt – ( B ) | DEC-ONLY Decrypt only – ( D ) | ENC-ONLY Encrypt only – ( E ) | | | GENVER MAC or PIN generate and verify – ( C ) | | | | GEN-ONLY | | | VER-ONLY | | DERIVE Key Derivation(for ‘B’ and ‘C’ TR-31 Key Block Version IDs only) – ( X ) | ANY Any mode allowed – ( N ) | Export control to set export field in TR-31 key block – optional | | EXP-ANY Export allowed using any key-encrypting key. This is the default. | | | | EXP-TRST Export allowed using a trusted key-encrypting key, as defined in TR-31. Note: A CCA key wrapped in the X9.24 compliant CCA key block is considered a trusted key. | EXP-NONE Export prohibited | | | | Control vector transport control – optional Note: If no keyword from this group is supplied, the CV in the source_key_identifier is still verified to agree with the ‘key usage’ and ‘mode of use’ keywords specified from the groups above. | | | | | | INCL-CV v MAC key must have Gen and Ver bits on v PIN key must have any PINGEN bit and EPINVER bit on MAC or PIN generate only – ( G ) v MAC key must have only Gen bit on v PIN key must have any PINGEN bit on and EPINVER bit off MAC or PIN verify only– ( V ) v MAC key must have only Ver bit on v PIN key must have all PINGEN bits off and EPINVER bit on Include the CCA Control Vector as an optional field in the TR-31 key block header. The TR-31 usage and mode of use fields will indicate the key attributes, and those attributes (derived from the keywords passed from the above groups) will be verified by the callable service to be compatible with the ones in the included control vector. Chapter 5. Managing Symmetric Cryptographic Keys 285 TR-31 Export | Table 115. Keywords for TR-31 Export Rule Array Control Information (continued) | Keyword Meaning | | | | | | | | | | ATTR-CV Include the CCA Control Vector as an optional field in the TR-31 key block header. The TR-31 usage will be set to the proprietary ASCII value “10” (‘3130’x) to indicate usage information is specified in the included CV, and the mode of use will be set to the proprietary ASCII value “1” (‘31’x) to indicate that mode is likewise specified in the CV. Note: If this keyword is specified, then usage and mode keywords from the preceding groups must not be specified. The proprietary values will be used. | key_version_number || | | | | | | | | Direction: Input | key_field_length || | | | | | | | | | | | | | | | | Direction: Input Type: String The two bytes from this parameter are copied into the Key Version Number field of the output TR-31 key block. If no key version number is needed, the value must be 0x3030 (“00”). If the CCA key in parameter source_key_identifier is a key part (CV bit 44 is 1) then the key version number in the TR-31 key block is set to “c0” (0x6330) according to the TR-31 standard, which indicates that the TR-31 block contains a key part. In this case, the value passed to the callable service in the key_version_number parameter is ignored. Type: Integer This parameter specifies the length of the key field which is encrypted in the TR-31 block. The length must be a multiple of 8, the DES cipher block size, and it must be greater than or equal to the length of the cleartext key passed with parameter source_key_identifier plus the length of the 2-byte key length that precedes this key in the TR-31 block. For example, if the source key is a double-length TDES key of length 16 bytes, then the key field length must be greater than or equal to (16+2) bytes, and must also be a multiple of 8. This means that the minimum key_field_length in this case would be 24. TR-31 allows a variable number of padding bytes to follow the cleartext key, and the caller may choose to pad with more than the minimum number of bytes needed to form a block that is a multiple of 8. This is generally done to hide the length of the cleartext key from those who cannot decipher that key. Most often, all keys – single, double, or triple length – are padded to the same length so that it is not possible to determine which length is carried in the TR-31 block by examining the encrypted block. Note that this parameter is not expected to allow for ASCII encoding of the encrypted data stored in the key field according to the TR-31 specification. For example when the user passes a value of 24 here, following the minimum example above, the length of the final ASCII-encoded encrypted data in the key field in the output TR-31 key block will be 48 Bytes. | | | | | | source_key_identifier_length || | | | | Direction: Input | source_key_identifier || Direction: Input/Output Type: Integer This parameter specifies the length of the source_key_identifier parameter, in bytes. The value in this parameter must currently be 64, since only CCA key tokens are supported for the source key parameter. 286 z/OS V1R13 ICSF Application Programmer's Guide Type: String TR-31 Export | | | | | | | | This parameter contains either the label or the key token for the key that is to be exported. The key must be a CCA internal or external token. If the source key is an external token, an identifier for the KEK that wraps the source key must be passed in the unwrap_kek_identifier parameter. Only DES/TDES keys are supported. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key. | unwrap_kek_identifier_length || | | | | Direction: Input | unwrap_kek_identifier || | | | | | | | | Direction: Input/Output | wrap_kek_identifier_length || | | | | Direction: Input | wrap_kek_identifier || | | | | | | | | | Direction: Input/Output | | | | | | | | Type: Integer This parameter specifies the length of the unwrap_kek_identifier parameter, in bytes. If the source_key_identifier is an external CCA token, then this parameter must be 64. Otherwise, this parameter must be 0. Type: String When the source_key_identifier is an external CCA token, this parameter contains either the label or the key token for the KEK which the source_key_identifier is currently wrapped under. It must be a CCA internal DES KEK token of type EXPORTER or OKEYXLAT. If the source_key_identifier is not an external CCA token, this parameter is ignored. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key. Type: Integer This parameter specifies the length of the wrap_kek_identifier parameter, in bytes. If the unwrap_kek_identifier is also to be used to wrap the output TR-31 key block, specify 0 for this parameter. Otherwise, this parameter must be 64. Type: String When wrap_kek_identifier_length is 0, this parameter is ignored and the unwrap_kek_identifier is also to be used to wrap the output TR-31 key block . Otherwise, this parameter contains either the label or the key token for the KEK to use for wrapping the output TR-31 key block. It must be a CCA internal token for a KEK EXPORTER or OKEYXLAT type and must have the same clear key as the unwrap_kek_identifier. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key. Note: ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap/unwrap TR-31 version ‘B’/’C’ key blocks that have/will have ‘E’ exportability, because ECB-mode does not comply with ANSI X9.24 Part 1. This parameter exists to allow for KEK separation, it is possible that KEKs will be restricted as to what they can wrap, such that a KEK for wrapping CCA external keys may not be usable for wrapping TR-31 external keys, or vice versa. | opt_blks_length || | Direction: Input Type: Integer Chapter 5. Managing Symmetric Cryptographic Keys 287 TR-31 Export This parameter specifies the length of parameter opt_blocks in bytes. If no optional data is to be included in the TR-31 key block, this parameter must be set to zero. | | | | opt_blocks || | | | | | Direction: Input | TR31_key_block_length || | | | | | | | Direction: Input/Output | TR31_key_block || | | | Direction: Output | Type: String This parameter contains optional block data which is to be included in the output TR-31 key block. The optional block data is prepared using the TR-31 Optional Data Build callable service, and must be in ASCII. This parameter is ignored if opt_blks_length is zero. Type: Integer This parameter specifies the length of the TR31_key_block parameter, in bytes. On input, it must specify the size of the buffer available for the output TR-31 key block, and on return it is updated to contain the actual length of that returned key block. If the provided buffer is not large enough for the output TR-31 key block an error is returned. The maximum size of the output TR-31 key block is 9992 bytes. Type: String This parameter specifies the location of the exported TR-31 key block wrapped with the export key provided in the wrap_kek_identifier parameter. Restrictions | This callable service only exports DES and TDES keys. | | | Proprietary values for the TR-31 header fields are not supported by this callable service with the exception of the proprietary values used by IBM CCA when carrying a control vector in an optional block in the header. | Usage Notes | | | | | | Unless otherwise noted, all String parameters that are either written to, or read from, a TR-31 key block will be in EBCDIC format. Input parameters are converted to ASCII before being written to the TR-31 key block and output parameters are converted to EBCDIC before being returned (see Appendix G, “EBCDIC and ASCII Default Conversion Tables,” on page 891). TR-31 key blocks themselves are always in printable ASCII format as required by the ANSI TR-31 specification. | | | | | | | | | | | | | If keyword INCL-CV or ATTR-CV is specified, the service inserts the CCA control vector from the source key into an optional data field in the TR-31 header. The TR-31 Import callable service can extract this CV and use it as the CV for the CCA key it creates when importing the TR-31 block. This provides a way to use TR-31 for transport of CCA keys and to make the CCA key have identical control vectors on the sending and receiving nodes. The difference between INCL-CV and ATTR-CV is that INCL-CV is a normal TR-31 export in which the TR-31 key attributes are set based on the supplied rule array keywords but the CV is also included in the TR-31 block to provide additional detail. In contrast, the ATTR-CV causes the service to include the CV but to set both the TR-31 usage and mode of use fields to proprietary values which indicate that the usage and mode information are specified in the CV and not in the TR-31 header. For option INCL-CV, the export operation is still subject to the restrictions imposed by the settings of the 288 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Export | | | relevant access control points. For option ATTR CV, those access control points are not checked and any CCA key can be exported as long as the export control fields in the CV permit it. | | SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS. | | | | Note that the optional data, if present, must not already contain a padding Block, ID “PB”. A Padding Block of the appropriate size, if needed, will be added when building the TR-31 key block. If this callable service encounters a padding block in the optional block data, an error will occur. | | | | The access control points in the ICSF role that control the general function of this service are: v TR31 Export – Permit version A TR-31 key blocks v TR31 Export – Permit version B TR-31 key blocks | v TR31 Export – Permit version C TR-31 key blocks | | | | The following table lists the valid attribute translations for export of CCA keys to TR-31 key blocks along with the access control points which govern those translations. Any translation not listed here will result in an error. If an individual cell is blank, it represents the value of the cell immediately above it. | | | Note: In order to export a CCA key to a TR-31 key block, the appropriate key block version ACP needs to be enabled in addition to any required translation specific ACPs from below. | | | | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) | | Normally export of CCA keys to TR-31 key blocks is controlled by ACPs specific to the translation or a small set of translations, to give fine control. This ACP allows any allowable export to occur as long as the CV is included, thus overriding the specific ACPs. | | | | | | | | | Notes: Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error T31 Key Blk Vers. T31Usage T31 Mode T31 Alg’m Required “TR31 Export” ACP Any Exportable Key Permit export of any CCA key (for allowable export scenarios as defined by this table) as long as the TR-31 key block will have the CCA Control Vector (CV) included as an optional block (the INCL-CV keyword was supplied on the callable service). 1. Some target systems, produced by other vendors may not accept TR-31 key blocks with the proprietary optional CV block. 2. The ATTR-CV keyword does not require any ACPs. DUKPT Base Derivation Keys KEYGENKY UKPT BDK + ANY B0 A N T KEYGENKY UKPT BDK + DERIVE B0 B,C X T Permit KEYGENKY:UKPT to B0 Note: These are the base keys from which DUKPT initial keys are derived for individual devices such as PIN pads Card Verification Keys Chapter 5. Managing Symmetric Cryptographic Keys 289 TR-31 Export | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error T31Usage T31 Key Blk Vers. T31 Mode T31 Alg’m C0 A,B,C G D,T CVK + VER-ONLY A,B,C V D,T AMEXCSC, gen bit(20)=1, ver bit(21)=1 CVK + GENVER A,B,C C D,T CVVKEYA, gen bit(20)=1 CVK + GEN-ONLY A,B,C G T CVVKEYA, gen bit(20)=0, ver bit(21)=1 CVK + VER-ONLY A,B,C V T CVVKEYA, gen bit(20)=1, ver bit(21)=1 CVK + GENVER A,B,C C T ANY-MAC, CVK + GEN-ONLY gen bit(20)=1 A,B,C G T ANY-MAC, CVK + VER-ONLY gen bit(20)=0, ver bit(21)=1 A,B,C V T ANY-MAC, CVK + gen GENVER bit(20)=1, ver bit(21)=1 A,B,C C T CVK + gen GEN-ONLY bit(20)=1 or zeroCV A,B,C G T CVK + gen bit(20)=1, GENVER ver bit(21)=1 or zeroCV A,B,C C T Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords MAC AMEXCSC, gen bit(20)=1 CVK + GEN-ONLY AMEXCSC, gen bit(20)=0, ver bit(21)=1 DATA 290 z/OS V1R13 ICSF Application Programmer's Guide Required “TR31 Export” ACP Permit MAC/MACVER:AMEX-CSC to C0:G/C/V Permit MAC/MACVER:CVV-KEYA to C0:G/C/V Permit MAC/MACVER:ANY-MAC to C0:G/C/V Permit DATA to C0:G/C TR-31 Export | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Notes: Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error T31Usage T31 Key Blk Vers. T31 Mode T31 Alg’m Required “TR31 Export” ACP 1. Keys for computing or verifying (against supplied value) a card verification code with the CVV, CVC, CVC2 and CVV2 algorithms. In CCA, this corresponds to keys used with two different APIs. v Visa CVV and MasterCard CVC codes are computed with CVV_Generate and verified with CVV_Verify. Keys must be DATA or MAC with sub-type (in bits 0-3) “ANY-MAC” , “CVVKEY-A” or “CVVKEY-B”. The GEN bit (20) or VER bit (21) must be set appropriately. v American Express CSC codes are generated and verified with the Transaction_Validate verb. The key must be a MAC or MACVER key with sub-type “ANY-MAC” or “AMEX-CSC”. The GEN bit (20) or VER bit (21) must be set appropriately. 2. CCA and TR-31 represent CVV keys incompatibly. CCA represents the “A” and “B” keys as two 8 B keys, while TR-31 represents these as one 16 B key. The CVV generate and verify verbs now accept a 16 B CVV key, using left and right parts as A and B. Current Visa standards require this. 3. Import and export of the 8 B CVVKEY-A and CVVKEY-B types will only be allowed using the proprietary TR-31 usage+mode values to indicate encapsulation of the IBM CV in an optional block, since the 8 B CVVKEY-A is meaningless / useless as a TR-31 C0 usage key of any mode. 4. It is possible to convert a CCA CVV key into a CSC key or vice-versa, since the translation from TR 31 usage “C0” is controlled by rule array keywords on the import verb. This can be restricted by using ACPs, but if both of translation types are required they cannot be disabled and control is up to the development, deployment, and execution of the applications themselves Data Encryption Keys ENCIPHER (none) ENC + ENC-ONLY DECIPHER (none) CIPHER (none) DATA D0 A,B,C E D, T ENC + DEC-ONLY A,B,C D D, T ENC + ENCDEC A,B,C B D, T enc ENC + bit(18)=1, ENCDEC dec bit(19)=1 or zeroCV A,B,C B D, T Permit ENCIPHER/DECIPHER/CIPHER to D0:E/D/B Permit DATA to D0:B Note: There is asymmetry in the TR-31 to CCA and CCA to TR-31 translation. CCA keys can be exported to TR-31 ‘D0’ keys from CCA type ENCIPHER, DECIPHER, or CIPHER, or type DATA with proper Encipher and Decipher CV bits on. A TR-31 ‘D0’ key can only be imported to CCA types ENCIPHER, DECIPHER, or CIPHER, not the lower security DATA key type. This eliminates conversion to the lower security DATA type by export / re-import. Key Encrypting Keys EXPORTER or OKEYXLAT KEK + ENC-ONLY K0 A,B,C E T Permit EXPORTER/OKEYXLAT to K0:E IMPORTER or IKEYXLAT KEK + DEC-ONLY K0 A,B,C D T Permit IMPORTER/IKEYXLAT to K0:D EXPORTER or OKEYXLAT KEK-WRAP K1 + ENC-ONLY B,C E T Permit EXPORTER/OKEYXLAT to K1:E IMPORTER or IKEYXLAT KEK-WRAP K1 + DEC-ONLY B,C D T Permit IMPORTER/IKEYXLAT to K1:D Chapter 5. Managing Symmetric Cryptographic Keys 291 TR-31 Export | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Notes: Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error T31Usage T31 Key Blk Vers. T31 Mode T31 Alg’m Required “TR31 Export” ACP 1. To be exported a KEK must have either the EXPORTER/IMPORTER bit or the XLAT bit on in the CV. A KEK with only the Key Generate bits on will not be exportable. 2. ‘K1’ keys are not distinguished from ‘K0’ keys within CCA. The ‘K1’ key is a particular KEK for deriving keys used in the ‘B’ or ‘C’ version wrapping of TR-31 key blocks. CCA does not distinguish between targeted protocols currently and so there is no good way to represent the difference; also note that most wrapping mechanisms now involve derivation or key variation steps 3. The CCA KEK to TR-31 K0-B transition for export will not be allowed for security reasons, even with ACP control this gives an immediate path to turn a CCA EXPORTER to an IMPORTER and vice versa. Export of NO-CV KEKs will be allowed, exporter keys become ‘E’ mode normal K0 keys, importer keys become ‘D’ mode K0 keys. A user can turn any KEK to a NO-CV KEK by setting the flag bit and recalculating the TVV, the flag is not bound to the key like the CV is. MAC Keys MAC gen bit(20)=1 DATA MAC A,B,C G T ISOMAC0 + gen GEN-ONLY bit(20)=1 or zeroCV A,B,C G T gen bit(20)=1, ver bit(21)=1 ISOMAC0 + GENVER A,B,C C T DATAM gen bit(20)=1, ver bit(21)=1 ISOMAC0 + GENVER A,B,C C T DATA ISOMAC0 + gen bit(20)=1, GENVER ver bit(21)=1 or zeroCV A,B,C C T MACVER gen bit(20)=0, ver bit(21)=1 ISOMAC0 + VER-ONLY A,B,C V T DATAMV gen bit(20)=0, ver bit(21)=1 ISOMAC0 + VER-ONLY A,B,C V T 292 ISOMAC0 + GEN-ONLY M0 z/OS V1R13 ICSF Application Programmer's Guide Permit MAC/DATA/DATAM to M0:G/C Permit MACVER/DATAMV to M0:V TR-31 Export | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error MAC gen bit(20)=1 ISOMAC1 + GEN-ONLY DATA MAC T31Usage T31 Key Blk Vers. T31 Mode T31 Alg’m Required “TR31 Export” ACP M1 A,B,C G D,T Permit MAC/DATA/DATAM to M1:G/C ISOMAC1 + gen GEN-ONLY bit(20)=1 or zeroCV A,B,C G D,T gen bit(20)=1, ver bit(21)=1 ISOMAC1 + GENVER A,B,C C D,T DATAM gen bit(20)=1, ver bit(21)=1 ISOMAC1 + GENVER A,B,C C D,T DATA ISOMAC1 + gen bit(20)=1, GENVER ver bit(21)=1 or zeroCV A,B,C C D,T MACVER gen bit(20)=0, ver bit(21)=1 ISOMAC1 + VER-ONLY A,B,C V D,T DATAMV gen bit(20)=0, ver bit(21)=1 ISOMAC1 + VER-ONLY A,B,C V D,T MAC gen bit(20)=1 ISOMAC3 + GEN-ONLY A,B,C G D,T DATA ISOMAC3 + gen GEN-ONLY bit(20)=1 or zeroCV A,B,C G D,T MAC gen bit(20)=1, ver bit(21)=1 ISOMAC3 + GENVER A,B,C C D,T DATAM gen bit(20)=1, ver bit(21)=1 ISOMAC3 + GENVER A,B,C C D,T DATA ISOMAC3 + gen bit(20)=1, GENVER ver bit(21)=1 or zeroCV A,B,C C D,T MACVER gen bit(20)=0, ver bit(21)=1 ISOMAC3 + VER-ONLY A,B,C V D,T DATAMV gen bit(20)=0, ver bit(21)=1 ISOMAC3 + VER-ONLY A,B,C V D,T M3 Permit MACVER/DATAMV to M1:V Permit MAC/DATA/DATAM to M3:G/C Permit MACVER/DATAMV to M3:V Chapter 5. Managing Symmetric Cryptographic Keys 293 TR-31 Export | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Notes: Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error T31Usage T31 Key Blk Vers. T31 Mode T31 Alg’m Required “TR31 Export” ACP 1. M0 and M1 are identical (ISO 16609 based on ISO 9797) normal DES/TDES (CBC) MAC computation, except M1 allows 8 byte and 16 byte keys while M0 allows only 16 byte keys. Mode M3 is the X9.19 style triple-DES MAC. 2. CCA does not support M2, M4, or M5. 3. Although export of DATAM/DATAMV keys to TR-31 M0/M1/M3 key types is allowed, import to DATAM/DATAMV CCA types is not allowed since they are obsolete types. PIN Keys OPINENC (none) PINENC + ENC-ONLY IPINENC (none) PINENC + DEC-ONLY (none) (none) (none) PINVER NO-SPEC PINVO + ANY A,B,C E T Permit OPINENC to P0:E A,B,C D T Permit IPINENC to P0:D (none) A,B,C B T (none) V0 A N T Permit PINVER:NO-SPEC to V0, Permit PINGEN/PINVER to V0/V1/V2:N A,B,C V NO-SPEC PINVO + ANY A N [EPINVER PINVO + GEN-ONLY bit off in CV] A,B,C G Permit PINGEN:NO-SPEC to V0 [EPINVER PINVO + GENVER bit on in CV] A,B,C C Permit PINGEN:NO-SPEC to V0 A N A,B,C V IBM or PINV3624 + NO-SPEC ANY A N [EPINVER PINV3624 + GEN-ONLY bit off in CV] A,B,C G Permit PINGEN:NO-SPEC/IBM-PIN/IBMPINO to V1 [EPINVER PINV3624 + GENVER bit on in CV] A,B,C C Permit PINGEN:NO-SPEC/IBM-PIN/IBMPINO to V1 A N A,B,C V A N [no GEN bits on in CV] PINGEN PINVER PINGEN PINVER 294 V1 PINV3624 + VER-ONLY VISAPVV VISAPVV + ANY or NO-SPEC [no GEN bits on in CV] PINGEN PINVO + VER-ONLY IBM or PINV3624 + NO-SPEC ANY [no GEN bits on in CV] P0 V2 VISAPVV + VER-ONLY VISAPVV VISAPVV + ANY or NO-SPEC z/OS V1R13 ICSF Application Programmer's Guide Permit PINVER:NO-SPEC to V0 T T Permit PINGEN:NO-SPEC to V0, Permit PINGEN/PINVER to V0/V1/V2:N Permit PINVER:NO-SPEC/IBM-PIN/IBMPINO to V1, Permit PINGEN/PINVER to V0/V1/V2:N Permit PINVER:NO-SPEC/IBM-PIN/IBMPINO to V1 T T Permit PINGEN:NO-SPEC/IBM-PIN/IBMPINO to V1, Permit PINGEN/PINVER to V0/V1/V2:N Permit PINVER:NO-SPEC/VISA-PVV to V2, Permit PINGEN/PINVER to V0/V1/V2:N Permit PINVER:NO-SPEC/VISA-PVV to V2 T Permit PINGEN:NO-SPEC/VISA-PVV to V2, Permit PINGEN/PINVER to V0/V1/V2:N TR-31 Export | | | | | | | | | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Turning on the ACP(s) controlling export of PINVER to usage:mode V*:N and import of V*:N to PINGEN at the same time will allow changing PINVER keys to PINGEN keys. This is not recommended. This is possible because legacy (TR-31 2005-based) implementations used the same mode ‘N’ for PINGEN as well as PINVER keys. Export CCA Type (CSNBCVG keywords) CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error T31 Key Blk Vers. T31 Mode [EPINVER VISAPVV + bit off in PINGEN CV] A,B,C G Permit PINGEN:NO-SPEC/VISA-PVV to V2 [EPINVER VISAPVV + PINGEN bit on in CV] A,B,C C Permit PINGEN:NO-SPEC/VISA-PVV to V2 CCA Usage in CSNBCVG keywords T31Usage T31 Alg’m Required “TR31 Export” ACP Note: There is a subtle difference between TR-31 V0 mode and CCA ‘NO-SPEC’ subtype. V0 mode restricts keys from 3224 or PVV methods, while CCA ‘NO-SPEC’ allows any method. EMV Chip / Issuer Master Keys DKYGENKY DKYL0 + DMAC DKYL0 + DMV DKYL0 + DALL DKYL1 + DMAC DKYL1 + DMV DKYL1 + DALL DKYGENKY (DKYL0 + DDATA) (DKYL0 + DMPIN) DKYL0 + DALL EMVACMK + ANY E0 A N T EMVACMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVSCMK + E1 ANY A N T EMVSCMK + DERIVE B,C X T EMVSCMK + ANY A N T EMVSCMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T Permit DKYGENKY:DKYL0+DMAC to E0 Permit DKYGENKY:DKYL0+DMV to E0 0x019A Permit DKYGENKY:DKYL0+DALL to E0 0x019B Permit DKYGENKY:DKYL1+DMAC to E0 Permit DKYGENKY:DKYL1+DMV to E0 Permit DKYGENKY:DKYL1+DALL to E0 Permit DKYGENKY:DKYL0+DDATA to E1 Permit DKYGENKY:DKYL0+DMPIN to E1 Permit DKYGENKY:DKYL0+DALL to E1 Chapter 5. Managing Symmetric Cryptographic Keys 295 TR-31 Export | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) Export CCA Type (CSNBCVG keywords) CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error (DKYL1 + DDATA) (DKYL1 + DMPIN) DKYL1 + DALL DKYGENKY DKYL0 + DMAC DKYL0 + DALL DKYL1 + DMAC DKYL1 + DALL DATA (none) MAC (not MACVER) CIPHER (none) (none) ENCIPHER DKYGENKY 296 DKYL0 +DDATA T31 Key Blk Vers. T31 Mode EMVSCMK + ANY A N EMVSCMK + DERIVE B,C X EMVSCMK + ANY A N EMVSCMK + DERIVE B,C X EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T A N T EMVSIMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVSIMK + ANY A N T EMVSIMK + DERIVE B,C X T EMVACMK + ANY A N T EMVACMK + DERIVE B,C X T EMVDAMK + E3 ANY A N T Permit DATA/MAC/CIPHER/ENCIPHER to E3 EMVDAMK + DERIVE B,C X EMVDAMK + ANY A N EMVDAMK + MACGEN A G EMVDAMK + DERIVE B,C X EMVDAMK + ANY A N EMVDAMK + DERIVE B,C X EMVDAMK + ENC-ONLY A E EMVDAMK + DERIVE B,C X EMVDNMK + E4 ANY A N T Permit DKYGENKY:DKYL0+DDATA to E4 EMVDNMK + DERIVE B,C X EMVSIMK + ANY T31Usage E2 z/OS V1R13 ICSF Application Programmer's Guide T31 Alg’m Required “TR31 Export” ACP Permit DKYGENKY:DKYL1+DDATA to E1 Permit DKYGENKY:DKYL1+DMPIN to E1 Permit DKYGENKY:DKYL1+DALL to E1 Permit DKYGENKY:DKYL0+DMAC to E2 Permit DKYGENKY:DKYL0+DALL to E2 Permit DKYGENKY:DKYL1+DMAC to E2 Permit DKYGENKY:DKYL1+DALL to E2 TR-31 Export | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Table 116. Valid CCA to TR-31 Export Translations and Required Access Control Points (ACPs) (continued) | | EMV support in CCA is significantly different from TR-31. CCA key types do not match TR-31 types. Export CCA Type (CSNBCVG keywords) DKYGENKY CCA Usage in CSNBCVG keywords CSNBT31X Keywords all ‘usage’ + ‘mode’ here, else error DKYL0 +DALL DKYL0 + DEXP DKYL0 + DMAC DKYL0 +DDATA DKYL0 +DALL T31 Key Blk Vers. T31 Mode T31 Alg’m Required “TR31 Export” ACP EMVDNMK + ANY A N T Permit DKYGENKY:DKYL0+DALL to E4 EMVDNMK + DERIVE B,C X EMVCPMK + E5 ANY A N T Permit DKYGENKY:DKYL0+DEXP to E5 EMVCPMK + DERIVE B,C X EMVCPMK + ANY A N EMVCPMK + DERIVE B,C X EMVCPMK + ANY A N EMVCPMK + DERIVE B,C X EMVDNMK + ANY A N EMVDNMK + DERIVE B,C X T31Usage Permit DKYGENKY:DKYL0+DMAC to E5 Permit DKYGENKY:DKYL0+DDATA to E5 T Permit DKYGENKY:DKYL0+DALL to E5 Note: EMV Chip Card Master Keys are used by the chip cards to perform cryptographic operations, or in some cases to deriver keys used to perform operations. In CCA, these are: v Key Gen Keys of level DKYL0 or DYKL1 allowing derivation of operational keys, or v operational keys. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. | Table 117. TR-31 export required hardware | | | Server | | IBM Eserver zSeries 900 This service is not supported. | | IBM Eserver zSeries 990 This service is not supported. | | IBM Eserver zSeries 890 | IBM System z9 EC | IBM System z9 BC | IBM System z10 EC | IBM System z10 BC | | | z196 Required cryptographic hardware Restrictions This service is not supported. This service is not supported. Crypto Express3 Coprocessor TR-31 key support requires the Sep. 2011 or later LIC. Chapter 5. Managing Symmetric Cryptographic Keys 297 TR-31 Import | | TR-31 Import (CSNBT31I and CSNET31I) | | | | Use the TR-31 Import callable service to convert a TR-31 key block to a CCA token. Since there is not always a one-to-one mapping between the key attributes defined by TR-31 and those defined by CCA, the caller may need to specify the attributes to attach to the imported key through the rule array. | The callable service name for AMODE(64) is CSNET31I. | Format || | | | | | | | | | | | | | | | | | | | CALL CSNBT31I( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, TR31_key_block_length, TR31_key_block, unwrap_kek_identifier_length, unwrap_kek_identifier, wrap_kek_identifier_length, wrap_kek_identifier, output_key_identifier_length, output_key_identifier, num_opt_blks, cv_source, protection_method ) Parameters | return_code || | Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. | | | reason_code || | Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | | | | | exit_data_length || | Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. | | | | exit_data || | Direction: Input/Output 298 z/OS V1R13 ICSF Application Programmer's Guide Type: String TR-31 Import | The data that is passed to the installation exit. | rule_array_count || | Direction: Input | | Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 1, 2, 3, 4, or 5. | rule_array || | Direction: Input Type: String | | | | | | | | | The rule_array contains keywords that provide control information to the callable service. The keywords are 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords for this callable service are shown in the following table. One keyword from one CCA output key usage subgroup shown in the following table is required based on TR-31 input key usage, unless the CV is included in the TR-31 key block as an optional block. If the CV is included in the TR-31 key block as an optional block, the included CV will be used in the output key block as long as it does not conflict with the TR-31 header data. | See Table 120 on page 305 for valid combinations of Usage and Mode | Table 118. Keywords for TR-31 Import Rule Array Control Information | Keyword | Key Wrapping Method (One Required) | | INTERNAL Desired output_key_identifier is a CCA internal key token, wrapped using the card master key. | | | EXTERNAL Desired output_key_identifier is a CCA external key token, wrapped using the key represented by the unwrap_kek_identifier. | | | | | | CCA Output Key Usage Subgroups ( One keyword from one CCA output key usage subgroup shown in the following table is required based on TR-31 input key usage, unless the CV is included in the TR-31 key block as an optional block. If the CV is included in the TR-31 key block as an optional block, the included CV will be used in the output key block as long as it does not conflict with the TR-31 header data.) | C0 Subgroup (One Required for this TR-31 key usage) Meaning | | CVK-CVV Convert TR-31 CVK to a CCA key for use with CVV/CVC. The CCA key will be a MAC key with subtype CVVKEY-A. | | CVK-CSC Convert TR-31 CVK to a CCA key for use with CSC. The CCA key will be a MAC key with subtype AMEX CSC. | K0 Subgroup (One Required for this TR-31 key usage) | | | | EXPORTER For TR-31 K0-E or K0-B usage+mode keys. Convert TR-31 KEK to a CCA wrapping key. The key will convert to a CCA EXPORTER key. Note that the K0-B key import has a unique ACP. | | | | OKEYXLAT For TR-31 K0-E or K0-B usage+mode keys. Convert TR-31 KEK to a CCA wrapping key. The key will convert to a CCA OKEYXLAT key. Note that the K0-B key import has a unique ACP. Chapter 5. Managing Symmetric Cryptographic Keys 299 TR-31 Import | Table 118. Keywords for TR-31 Import Rule Array Control Information (continued) | Keyword Meaning | | | | IMPORTER For TR-31 K0-D or K0-B usage+mode keys. Convert TR-31 KEK to a CCA unwrapping key. The key will convert to a CCA IMPORTER key. Note that the K0-B key import has a unique ACP. | | | | IKEYXLAT For TR-31 K0-D or K0-B usage+mode keys. Convert TR-31 KEK to a CCA unwrapping key. The key will convert to a CCA IKEYXLAT key. Note that the K0-B key import has a unique ACP. | V0/V1/V2 Subgroup (One Required for these TR-31 key usages) | PINGEN Convert a TR-31 PIN verification key to a CCA PINGEN key. | PINVER Convert a TR-31 PIN verification key to a CCA PINVER key. | E0/E2,F0/F2 Subgroup (One Required for these TR-31 key usages) | | | DMAC Convert TR-31 EMV master key (chip card or issuer) for Application Cryptograms or Secure Messaging for Integrity to CCA DKYGENKY type DMAC | | | DMV Convert TR-31 EMV master key (chip card or issuer) for Application Cryptograms or Secure Messaging for Integrity to CCA DKYGENKY type DMV | E1,F1 Subgroup (One Required for these TR-31 key usages) | | | DMPIN Convert TR-31 EMV master key (chip card or issuer) for Secure Messaging for Confidentiality to CCA DKYGENKY type DMPIN | | | DDATA Convert TR-31 EMV master key (chip card or issuer) for Secure Messaging for Confidentiality to CCA DKYGENKY type DDATA | E5 Subgroup (One Required for this TR-31 key usage) | | DMAC Convert TR-31 EMV master key (issuer) for Card Personalization to CCA DKYGENKY type DMAC. | | DMV Convert TR-31 EMV master key (issuer) for Card Personalization to CCA DKYGENKY type DMV. | | DEXP Convert TR-31 EMV master key (issuer) for Card Personalization to CCA DKYGENKY type DEXP. | | | | Key Derivation Level (One Required with E0, E1, E2 TR-31 key usages unless the CV is included in the TR-31 key block as an optional block. If the CV is included in the TR-31 key block, the included CV will be used in the output key block as long as it does not conflict with the TR-31 header data.) | | DKYL0 Convert TR-31 EMV master key (chip card or issuer) to CCA DKYGENKY at derivation level DKYL0. | | DKYL1 Convert TR-31 EMV master key (chip card or issuer) to CCA DKYGENKY at derivation level DKYL1. | Key Type Modifier (Optional) | | | | NOOFFSET 300 z/OS V1R13 ICSF Application Programmer's Guide Valid only for V0/V1 TR-31 key usage values. Import the PINGEN or PINVER key into a key token that cannot participate in the generation or verification of a PIN when an offset or the Visa PVV process is requested. TR-31 Import | Table 118. Keywords for TR-31 Import Rule Array Control Information (continued) | Keyword | | | | | Key Wrapping Method (Optional) Note: Conflicts between wrapping keywords used and a CV passed in an optional data block of the TR-31 token will result in errors being returned. The main example of this is a CV that indicates ‘enhanced-only’ in bit 56 when the user or configured default specifies ECB for key wrapping. | | USECONFG Specifies that the configuration setting for the default wrapping method is to be used to wrap the key. This is the default. | | WRAP-ENH Specifies that the new enhanced wrapping method is to be used to wrap the key. | WRAP-ECB Specifies that the original wrapping method is to be used. | Translation Control (One Optional) | | | | | | | ENH-ONLY | | | | | | | | | | | | | | | | | Meaning Specify this keyword to indicate that the key once wrapped with the enhanced method cannot be wrapped with the original method. This restricts translation to the original method. If the keyword is not specified translation to the original method will be allowed. This turns on bit 56 in the control vector. This keyword is not valid if processing a zero CV data key. Notes: 1. If the TR-31 block contains a CV in the optional data block that does not have bit 56 turned on, bit 56 will be turned on in the output token, since with this keyword the user is asking for this behavior. The exception to this is for CVs of all 0x00 bytes, for this case no error will be generated but the CV will remain all 0x00 bytes. 2. Conflicts between wrapping keywords used and a CV passed in an optional data block of the TR-31 token will result in errors being returned. The main example of this is a CV that indicates ‘enhanced-only’ in bit 56 when the user or configured default specifies ECB for key wrapping. If the default wrapping method is ECB mode, but the enhanced mode and the ENH-ONLY restriction are desired for a particular key token, combine the ENH-ONLY keyword with the WRAP-ENH keyword. | TR31_key_block_length || | | | | Direction: Input | TR31_key_block || | | | Direction: Input | unwrap_kek_identifier_length || | | Direction: Input Type: Integer This parameter specifies the length of the TR31_key_block parameter, in bytes. The length field in the TR-31 block is a 4-digit decimal number, so the maximum acceptable length is 9992 bytes. Type: String This parameter contains the TR-31 key block that is to be imported. The key block is protected with the key passed in parameter unwrap_kek_identifier. Type: Integer This parameter specifies the length of the unwrap_kek_identifier parameter, in Chapter 5. Managing Symmetric Cryptographic Keys 301 TR-31 Import bytes. The value in this parameter must currently be 64, since only CCA internal key tokens are supported for the unwrap_kek_identifier parameter. | | | unwrap_kek_identifier || | | | | | | | Direction: Input/Output Type: String This parameter contains either the label or the key token for the key that is used to unwrap and check integrity of the imported key passed in the TR31_key_block parameter. The key must be a CCA internal token for a KEK IMPORTER or IKEYXLAT type. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key. Note: ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap/unwrap TR-31 version ‘B’/’C’ key blocks that have, or will have ,‘E’ exportability. This is because ECB-mode does not comply with ANSI X9.24 Part 1. | | | | | wrap_kek_identifier_length || | | | | Direction: Input | wrap_kek_identifier || | | | | | | | | | Direction: Input/Output Type: Integer This parameter specifies the length of the wrap_kek_identifier parameter, in bytes. If the unwrap_kek_identifier is also to be used to wrap the output CCA token, specify 0 for this parameter. Otherwise, this parameter must be 64. Type: String When wrap_kek_identifier_length is 0, this parameter is ignored and the unwrap_kek_identifier is also to be used to wrap the output CCA token. Otherwise, this parameter contains either the label or the key token for the KEK to use for wrapping the output CCA token. It must be a CCA internal token for a KEK EXPORTER or OKEYXLAT type and must have the same clear key as the unwrap_kek_identifier. If a key token is passed which is wrapped under the old master key, it will be updated on output so that it is wrapped under the current master key. Note: ECB-mode wrapped DES keys (CCA legacy wrap mode) cannot be used to wrap/unwrap TR-31 version ‘B’/’C’ key blocks that have/will have ‘E’ exportability. This is because ECB-mode does not comply with ANSI X9.24 Part 1. | | | | | output_key_identifier_length || | | | | | | Direction: Input/Output | output_key_identifier || | | | | Direction: Output Type: Integer This parameter specifies the length of the output_key_identifier parameter, in bytes. On input, it specifies the length of the buffer represented by the output_key_identifier parameter and must be at least 64 bytes long. On output, it contains the length of the token returned in the output_key_identifier parameter. Type: String This parameter contains the key token that is to receive the imported key. The output token will be a CCA internal or external key token containing the key received in the TR-31 key block. 302 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Import | num_opt_blocks || | | | Direction: Output | cv_source || | | | Direction: Output Type: Integer This parameter contains the number of optional blocks that are present in the TR-31 key block. Type: String This parameter contains information about how the control vector in the output key token was created. It can be one of the following three values: | | | 0x00 No CV was present in an optional block, and the output CV was created by the callable service based on input parameters and on the attributes in the TR-31 key block header. | | | | 0x01 A CV was obtained from an optional block in the TR-31 key block, and the key usage and mode of use were also specified in the TR-31 header. The callable service verified compatibility of the header values with the CV and then used that CV in the output key token. | | | | | 0x02 A CV was obtained from an optional block in the TR-31 key block, and the key usage and mode of use in the TR-31 header held the proprietary values indicating that key use and mode should be obtained from the included CV. The CV from the TR-31 token was used as the CV for the output key token. | Any value other than these are reserved for future use and are currently invalid. | protection_method || | | | Direction: Output Type: String This parameter contains information about what method was used to protect the input TR-31 key block. It can have one of the following values: | | 0x00 The TR-31 key block was protected using the variant method as identified by a Key Block Version ID value of “A” (0x41). | | 0x01 The TR-31 key block was protected using the derived key method as identified by a Key Block Version ID value of “B” (0x42). | | | | 0x02 The TR-31 key block was protected using the variant method as identified by a Key Block Version ID value of “C” (0x43). Functionally this method is the same as ‘A’, but to maintain consistency a different value will be returned here for ‘C’. | Any value other than these are reserved for future use and are currently invalid. | Restrictions | This callable service only imports DES and TDES keys. | | | Proprietary values for the TR-31 header fields are not supported by this callable service with the exception of the proprietary values used by IBM CCA when carrying a control vector in an optional block in the header. | | | Usage Notes Unless otherwise noted, all String parameters that are either written to, or read from, a TR-31 key block will be in EBCDIC format. Input parameters are converted Chapter 5. Managing Symmetric Cryptographic Keys 303 TR-31 Import | | | | to ASCII before being written to the TR-31 key block and output parameters are converted to EBCDIC before being returned (see Appendix G, “EBCDIC and ASCII Default Conversion Tables,” on page 891). TR-31 key blocks themselves are always in printable ASCII format as required by the ANSI TR-31 specification. | | If the TR-31 key block is marked as a key component, the resulting CCA key will have the Key Part bit (bit 44) in the control vector set to 1. | | The exportability attributes of the imported CCA token are set based on attributes in the TR-31 key block as described in the following table. | Table 119. Export attributes of an imported CCA token | | TR-31 export attribute value | | | | Non-exportable ("N") CCA imports the key to an internal CCA key token. CV bit 17 (export) is set to zero to indicate that the key is not exportable. CV bit 57 (TR-31 export) is set to one to indicate that the key is not exportable to TR-31. | | | | | | Exportable under trusted key ("E") If the TR-31 token is wrapped with a CCA KEK in the old ECB format, the request is rejected because that KEK is not a trusted key. If the CCA KEK is in a newer X9.24 compliant CCA key block, then the TR-31 key is imported to CCA in exactly the same way as described below for keys that are exportable under any key. | | | | | Exportable under any key CCA imports the key to an internal CCA key token. CV bit 17 ("S") (export) is set to one to indicate that the key is exportable. CV bit 57 (TR-31 export) is set to zero to indicate that the key is also exportable to TR-31. | | If necessary, use the Prohibit Export, Prohibit Exported Extended, or Restrict Key Attribute callable service to alter the export attributes of the CCA token after import. | | | | If the TR-31 key block contains an optional block with a CCA CV of ‘00007D00030000000000000000000000’ for a single length key or ‘00007D0003410000000000000000000000007D00032100000000000000000000’ for a double length key, the resulting CCA token will be a zero CV DATA token. | | | | | | | | | | | | | | | | | The TR-31 key block can contain a CCA control vector in an optional data field in the header. If the CV is present, the service will check that CV for compatibility with the TR-31 key attributes to ensure the CV is valid for the key and if there are no problems it will use that CV in the CCA key token that is output by the service. If a CV is received, the import operation is not subject to any ACP controlling the importation of specific key types. The CV may be present in the TR-31 key block in two different ways, depending on options used when creating that block. v If the TR-31 Export callable service was called with option INCL-CV, the control vector is included in the TR-31 key block and the TR-31 key usage and mode of use fields contain attributes from the set defined in the TR-31 standard. The TR-31 Import callable service checks that those TR-31 attributes are compatible with the CV included in the block. It also verifies that no rule array keywords conflict with the CV contained in the TR-31 block. v If the TR-31 Export callable service was called with option ATTR-CV, the control vector is included in the TR-31 key block and the TR-31 key usage and mode of use fields contain proprietary values (ASCII “10” and “1”, respectively) to indicate that the usage and mode information is contained in the included control vector. 304 z/OS V1R13 ICSF Application Programmer's Guide CCA action on import TR-31 Import In this case, the TR-31 Import service uses the included CV as the control vector for the CCA key token it produces. It also verifies that the CV does not conflict with rule array keywords passed | | | | | SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS. | | | | | | The access control points in the ICSF role that control the general function of this service are: v TR31 Import – Permit version A TR-31 key blocks v TR31 Import – Permit version B TR-31 key blocks v TR31 Import – Permit version C TR-31 key blocks v TR31 Import – Permit override of default wrapping method | | | | The following table lists the valid attribute translations for import of TR-31 key blocks to CCA keys along with the access control points which govern those translations. Any translation not listed here will result in an error. If an individual cell is blank, it represents the value of the cell immediately above it. | | | Note: In order to import a TR-31 key block to a CCA key, the appropriate key block version ACP needs to be enabled in addition to any required translation specific ACPs from below. | Table 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) | | | | T31 Key Import T31 Blk Vers. Usage T31 T31 Mode Alg’m | Keywords Output CCA Type (CSNBCVG keywords) Output CCA Usage (CSNBCVG keywords) Required TR31 Import ACP DUKPT Base Derivation Keys | B0 A N T (none) KEYGENKY UKPT | B0 B,C X T (none) KEYGENKY UKPT | B1 B,C (none) (none) (none) (none) (none) | Note: These are the base keys from which DUKPT initial keys are derived for individual devices such as PIN pads. | | | | (none) Card Verification Keys C0 A,B,C G, C D CVK-CSC MAC AMEX-CSC A,B,C T CVK-CSC MAC AMEX-CSC | A,B,C V D CVK-CSC MACVER AMEX-CSC | A,B,C T CVK-CSC MACVER AMEX-CSC | | | A,B,C G, C T CVK-CVV MAC CVVKEY-A A,B,C V T CVK-CVV MACVER CVVKEY-A Permit C0 to MAC/MACVER:AMEX-CSC Permit C0 to MAC/MACVER:CVVKEY-A Chapter 5. Managing Symmetric Cryptographic Keys 305 TR-31 Import | Table 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) (continued) | | | | T31 Key Import T31 Blk Usage Vers. | | The card verification keys are keys for computing or verifying (against supplied value) a card verification code with the CVV, CVC, CVC2 and CVV2 algorithms. | | | | | | | | | | | | | | | | | | | | | Notes: T31 T31 Mode Alg’m Keywords Output CCA Usage (CSNBCVG keywords) v Visa CVV and MasterCard CVC codes are computed with CVV_Generate and verified with CVV_Verify. Keys must be DATA or MAC with sub-type (in bits 0-3) “ANY-MAC” , “CVVKEY-A” or “CVVKEY-B”. The GEN bit (20) or VER bit (21) must be set appropriately. v American Express CSC codes are generated and verified with the Transaction_Validate verb. The key must be a MAC or MACVER key with sub-type “ANY-MAC” or “AMEX-CSC”. The GEN bit (20) or VER bit (21) must be set appropriately. 2. CCA and TR-31 represent CVV keys incompatibly. CCA represents the “A” and “B” keys as two 8 B keys, while TR-31 represents these as one 16 B key. The CVV generate and verify verbs now accept a 16 B CVV key, using left and right parts as A and B. Current Visa standards require this. 3. Import and export of the 8 B CVVKEY-A and CVVKEY-B types will only be allowed using the proprietary TR-31 usage+mode values to indicate encapsulation of the IBM CV in an optional block, since the 8 B CVVKEY-A is meaningless / useless as a TR-31 C0 usage key of any mode. 4. Import of a TR-31 key of usage C0 to CCA key type ‘ANY-MAC’ will not be allowed, although the ANY-MAC key is also usable for card verification purposes. 5. It is possible to convert a CCA CVV key into a CSC key or vice-versa, since the translation from TR-31 usage “C0” is controlled by rule array keywords on the import verb. This can be restricted by using ACPs, but if both of translation types are required they cannot be disabled and control is up to the development, deployment, and execution of the applications themselves. CCA does not have a ‘MAC GEN ONLY’ key type, so TR-31 usage of G will translate to a full MAC key. Data Encryption Keys A,B,C E D, T (none) ENCIPHER (none) | A,B,C D D, T (none) DECIPHER (none) | A,B,C B D, T (none) CIPHER (none) | | | | | | | D0 (none) Notes: 1. There is asymmetry in the TR-31 to CCA and CCA to TR-31 translation. CCA keys can be exported to TR-31 ‘D0’ keys from CCA type ENCIPHER, DECIPHER, or CIPHER, or type DATA with proper Encipher and Decipher CV bits on. A TR-31 ‘D0’ key can only be imported to CCA types ENCIPHER, DECIPHER, or CIPHER, not the lower security DATA key type. This eliminates conversion to the lower security DATA type by export / re-import. 2. There are no ACPs controlling import since the intent of the TR-31 key’s control is not interpreted, just directly translated to CCA control. | | | | Required TR31 Import ACP 1. In CCA, this corresponds to keys used with two different APIs. | | Output CCA Type (CSNBCVG keywords) Key Encrypting Keys K0 A,B,C E T A,B,C OKEYXLAT OKEYXLAT (none) EXPORTER EXPORTER (none) IKEYXLAT IKEYXLAT (none) IMPORTER IMPORTER (none) OKEYXLAT OKEYXLAT (none) | | | A,B,C D | | | A,B,C B A,B,C EXPORTER EXPORTER (none) | | | A,B,C IKEYXLAT IKEYXLAT (none) A,B,C IMPORTER IMPORTER (none) T A,B,C 306 T z/OS V1R13 ICSF Application Programmer's Guide Permit K0:E to EXPORTER/OKEYXLAT Permit K0:D to IMPORTER/IKEYXLAT Permit K0:B to EXPORTER/OKEYXLAT Permit K0:B to IMPORTER/IKEYXLAT TR-31 Import | Table 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) (continued) | | | | T31 Key Import T31 Blk Usage Vers. T31 T31 Mode Alg’m | | | K1 E B,C T B,C Keywords Output CCA Type (CSNBCVG keywords) Output CCA Usage (CSNBCVG keywords) OKEYXLAT OKEYXLAT (none) EXPORTER EXPORTER (none) IKEYXLAT IKEYXLAT (none) IMPORTER IMPORTER (none) OKEYXLAT OKEYXLAT (none) | | | B,C | | | B,C B,C EXPORTER EXPORTER (none) | | | B,C IKEYXLAT IKEYXLAT (none) B,C IMPORTER IMPORTER (none) | | | | | | | | | | | | D T B,C B T Permit K1:B to EXPORTER/OKEYXLAT Permit K1:B to IMPORTER/IKEYXLAT 2. It is possible to convert a CCA EXPORTER key to an OKEYXLAT, or to convert an IMPORTER to an IKEYXLAT by export / re-import. This can be restricted by using ACPs, but if both translations are required they cannot be disabled and control is up to the development, deployment, and execution of the applications themselves. 3. It will not be possible to export a CCA key to TR-31 type K0-B, in order to avoid the ability to translate a CCA EXPORTER to a CCA IMPORTER via export/import to the TR-31 token type. When a TR-31 key block does not have an included CV as an optional block, the default CV will be used to construct the output token. For IMPORTER / EXPORTER keys this means that the Key Generate bits will also be on in the KEK. MAC Keys M0 | M1 | M3 | A,B,C G,C T (none) MAC ANY-MAC A,B,C V T (none) MACVER ANY-MAC A,B,C G,C D, T (none) MAC ANY-MAC A,B,C V D, T (none) MACVER ANY-MAC A,B,C G,C D, T (none) MAC ANY-MAC A,B,C V D, T (none) MACVER ANY-MAC Permit M0/M1/M3 to MAC/MACVER:ANY-MAC Notes: 1. M0 and M1 are identical (ISO 16609 based on ISO 9797) normal DES/TDES (CBC) MAC computation, except M1 allows 8 byte and 16 byte keys while M0 allows only 16 byte keys. Mode M3 is the X9.19 style triple-DES MAC. 2. CCA does not support M2, M4, or M5. 3. Although export of DATAM/DATAMV keys to TR-31 M0/M1/M3 key types is allowed, import to DATAM/DATAMV CCA types is not allowed since they are obsolete types | | Permit K1:D to IMPORTER/IKEYXLAT 1. K1’ keys are not distinguished from ‘K0’ keys within CCA. The ‘K1’ key is a particular KEK for deriving keys used in the ‘B’ or ‘C’ version wrapping of TR-31 key blocks. CCA does not distinguish between targeted protocols currently and so there is no good way to represent the difference; also note that most wrapping mechanisms now involve derivation or key variation steps. | | | | | | | | | | Permit K1:E to EXPORTER/OKEYXLAT Notes: | | Required TR31 Import ACP PIN Keys P0 A,B,C E T (none) OPINENC (none) Permit P0:E to OPINENC | A,B,C D (none) IPINENC (none) Permit P0:D to IPINENC | | | A,B,C B – not supp (none) (none) (none) (none) Chapter 5. Managing Symmetric Cryptographic Keys 307 TR-31 Import | Table 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) (continued) | | | | T31 Key Import T31 Blk Usage Vers. T31 T31 Mode Alg’m | | | | V0 N A T Output CCA Type (CSNBCVG keywords) Output CCA Usage (CSNBCVG keywords) PINGEN [NOOFFSET] PINGEN NO-SPEC Permit V0 to [+NOOFFSET] PINGEN:NO-SPEC, Permit V0/V1/V2:N to PINGEN/PINVER Keywords Required TR31 Import ACP | | A,B,C G,C [NOOFFSET] PINGEN NO-SPEC Permit V0 to [+NOOFFSET] PINGEN:NO-SPEC | | | | A N PINVER [NOOFFSET] PINVER NO-SPEC Permit V0 to [+NOOFFSET] PINVER:NO-SPEC, Permit V0/V1/V2:N to PINGEN/PINVER | | A,B,C V [NOOFFSET] PINVER NO-SPEC Permit V0 to [+NOOFFSET] PINVER:NO-SPEC PINGEN [NOOFFSET] PINGEN IBM-PIN /IBM-PINO Permit V1 to PINGEN:IBM-PIN/IBM-PINO, Permit V0/V1/V2:N to PINGEN/PINVER | | | | V1 A N T | | A,B,C G,C [NOOFFSET] PINGEN IBM-PIN /IBM-PINO Permit V1 to PINGEN:IBM-PIN/IBM-PINO | | | | A N PINVER [NOOFFSET] PINVER IBM-PIN /IBM-PINO Permit V1 to PINVER:IBM-PIN/IBM-PINO, Permit V0/V1/V2:N to PINGEN/PINVER | | A,B,C V [NOOFFSET] PINVER IBM-PIN /IBM-PINO Permit V1 to PINVER:IBM-PIN/IBM-PINO PINGEN PINGEN VISA-PVV Permit V2 to PINGEN:VISA-PVV, Permit V0/V1/V2:N to PINGEN/PINVER PINGEN VISA-PVV Permit V2 to PINGEN:VISA-PVV PINVER VISA-PVV Permit V2 to PINVER:VISA-PVV, Permit V0/V1/V2:N to PINGEN/PINVER PINVER VISA-PVV Permit V2 to PINVER:VISA-PVV | | | | V2 A N | | A,B,C G,C | | | | A | | A,B,C V | | | | | | | | | | N T PINVER Notes: 1. NOOFFSET keyword may be passed to specify resultant CCA key to have NOOFFSET bit (bit 37) on in CV. However this will be automatic if CV is included and has NOOFFSET bit set. 2. NOOFFSET keyword is not supported for V2 usage since VISA-PVV algorithm does not support that concept. 3. There is a subtle difference between TR-31 V0 mode and CCA ‘NO-SPEC’ subtype. V0 mode restricts keys from 3224 or PVV methods, while CCA ‘NO-SPEC’ allows any method. 4. Turning on the ACP(s) controlling export of PINVER to usage:mode V*:N and import of V*:N to PINGEN at the same time will allow changing PINVER keys to PINGEN keys. This is not recommended. This is possible because legacy (TR-31 2005-based) implementations used the same mode ‘N’ for PINGEN as well as PINVER keys. | EMV Chip / Issuer Master Keys 308 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Import | Table 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) (continued) | | | | T31 Key Import T31 Blk Usage Vers. T31 T31 Mode Alg’m | | E0 A N | | B,C X DKYL0 +DMAC DKYL0 +DMAC | | A N DKYL0 +DMV DKYL0 +DMV | | B,C X DKYL0 +DMV DKYL0 +DMV | | A N DKYL1 +DMAC DKYL1 +DMAC | | B,C X DKYL1 +DMAC DKYL1 +DMAC | | A N DKYL1 +DMV DKYL1 +DMV | | B,C X DKYL1 +DMV DKYL1 +DMV A N, E, D, B | | B,C X DKYL0 +DMPIN DKYL0 +DMPIN | | A N, E, D, B DKYL0 +DDATA DKYL0 +DDATA | | B,C X DKYL0 +DDATA DKYL0 +DDATA | | A N, E, D, B DKYL1 +DMPIN DKYL1 +DMPIN | | B,C X DKYL1 +DMPIN DKYL1 +DMPIN | | A N, E, D, B DKYL1 +DDATA DKYL1 +DDATA | | B,C X DKYL1 +DDATA DKYL1 +DDATA A N | | B,C X DKYL0 +DMAC DKYL0 +DMAC | | A N DKYL1 +DMAC DKYL1 +DMAC | | B,C X DKYL1 +DMAC DKYL1 +DMAC A N, E, D, B, G B,C X | | | | | | | | E1 E2 E3 T T T T Keywords DKYL0 +DMAC DKYL0 +DMPIN DKYL0 +DMAC (none) (none) Output CCA Type (CSNBCVG keywords) Output CCA Usage (CSNBCVG keywords) Required TR31 Import ACP DKYGENKY DKYL0 +DMAC Permit E0 to DKYGENKY:DKYL0+DMAC DKYGENKY DKYGENKY ENCIPHER DKYL0 +DMPIN DKYL0 +DMAC (none) Permit E0 to DKYGENKY:DKYL0+DMV Permit E0 to DKYGENKY:DKYL1+DMAC Permit E0 to DKYGENKY:DKYL1+DMV Permit E1 to DKYGENKY:DKYL0+DMPIN Permit E1 to DKYGENKY:DKYL0+DDATA Permit E1 to DKYGENKY:DKYL1+DMPIN Permit E1 to DKYGENKY:DKYL1+DDATA Permit E2 to DKYGENKY:DKYL0+DMAC Permit E2 to DKYGENKY:DKYL1+DMAC Permit E3 to ENCIPHER (none) Chapter 5. Managing Symmetric Cryptographic Keys 309 TR-31 Import | Table 120. Valid TR-31 to CCA Import Translations and Required Access Control Points (ACPs) (continued) | | | | T31 Key Import T31 Blk Usage Vers. T31 T31 Mode Alg’m | | E4 A N, B B,C X (none) A G, C, T V, E, D, B, N DKYL0 +DMAC | | B,C X DKYL0 +DMAC DKYL0 +DMAC | | | | A G, C, V, E, D, B, N DKYL0 +DDATA DKYL0 +DDATA | | B,C X DKYL0 +DDATA DKYL0 +DDATA | | | | A G, C, V, E, D, B, N DKYL0 +DEXP DKYL0 +DEXP | | B,C X DKYL0 +DEXP DKYL0 +DEXP | | | | | | E5 T Keywords Output CCA Type (CSNBCVG keywords) Output CCA Usage (CSNBCVG keywords) Required TR31 Import ACP (none) DKYGENKY DKYL0 +DDATA Permit E4 to DKYGENKY:DKYL0+DDATA DKYL0 +DDATA DKYGENKY DKYL0 +DMAC Permit E5 to DKYGENKY:DKYL0+DMAC Permit E5 to DKYGENKY:DKYL0+DDATA Permit E5 to DKYGENKY:DKYL0+DEXP | | | | Note: EMV Chip Card Master Keys are used by the chip cards to perform cryptographic operations, or in some cases to derive keys used to perform operations. In CCA, these are: | | EMV support in CCA is significantly different. CCA key types do not match TR-31 types. v Key Gen Keys of level DKYL0 or DKYL1 allowing derivation of operational keys, or v operational keys. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. | Table 121. TR-31 export required hardware | | | Server | | IBM Eserver zSeries 900 This service is not supported. | | IBM Eserver zSeries 990 This service is not supported. | | IBM Eserver zSeries 890 | IBM System z9 EC | IBM System z9 BC 310 Required cryptographic hardware z/OS V1R13 ICSF Application Programmer's Guide Restrictions This service is not supported. TR-31 Import | Table 121. TR-31 export required hardware (continued) | | | Server | IBM System z10 EC | IBM System z10 BC | | | z196 | | Required cryptographic hardware Restrictions This service is not supported. Crypto Express3 Coprocessor TR-31 key support requires the Sept. 2011 or later LIC. TR-31 Optional Data Build (CSNBT31O and CSNET31O) | | | A TR-31 key block can hold optional fields which are securely bound to the key block using the integrated MAC. The optional blocks may either contain information defined in the TR-31 standard, or they may contain proprietary data. | | | Use the TR-31 Optional Data Build callable service to construct the optional block data structure for a TR-31 key block. It builds the structure by adding one optional block with each call, until your entire set of optional blocks have been added. | | | | | With each call, the application program provides a single optional block by specifying its ID, its length, and its data in parameters opt_block_id, opt_block_length, and opt_block_data respectively. Each subsequent call appends the current optional block to any preexisting blocks in the opt_blocks parameter. On the first call to the callable service, opt_blocks is typically empty. | The callable service name for AMODE(64) is CSNET31O. | Format || | | | | | | | | | | | | | | | CSNBT31O( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, opt_blocks_bfr_length, opt_blocks_length, opt_blocks, num_opt_blocks, opt_block_id, opt_block_data_length, opt_block_data ) Parameters | return_code || | Direction: Output | | | | Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Chapter 5. Managing Symmetric Cryptographic Keys 311 TR-31 Optional Data Build || | Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | | | | | exit_data_length || | Direction: Ignored Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | | exit_data || | Direction: Ignored Type: String This field is ignored. | | rule_array_count || | Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 0 since no keywords are currently defined for this callable service. | | | | rule_array || | Direction: Input Type: String The rule_array contains keywords that provide control information to the callable service. There are no rule_array keywords currently defined for this callable service. | | | | opt_blocks_bfr_length || | Direction: Input Type: Integer This parameter specifies the length of the buffer passed with the opt_blocks parameter. This length is used to determine if it would overflow the buffer size when adding a new optional block to the current contents of the buffer. | | | | opt_blocks_length || | Direction: Input/Output Type: Integer This parameter specifies the actual length of the set of optional blocks currently contained in the opt_blocks buffer. On output, it is updated with the length after the callable service has added the new optional block. | | | | opt_blocks || | Direction: Input/Output Type: String This parameter specifies a buffer containing the set of optional blocks being built. In the first call, it will generally be empty. The callable service will append one optional block to the buffer with each call. Parameter opt_blocks_bfr_length | | | 312 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Optional Data Build specifies the total length of this buffer, and an error will be returned if this length would be exceeded by adding the optional block in parameter opt_block_data to the current contents. This parameter is encoded in ASCII on both input and output. | | | | | num_opt_blocks || | | | | | Direction: Output | opt_block_id || | | | Direction: Input | opt_block_data_length || | | | | Direction: Input | opt_block_data || | | | | | Direction: Input | This parameter contains the number of optional blocks contained in the structure returned in parameter opt_blocks. This is provided as an output parameter so that it can subsequently be used as an input to the TR-31 Export callable service. Type: String This parameter specifies a two-byte value which is the identifier (ID) of the optional block passed in parameter opt_block_data. Type: Integer This parameter specifies the length of the data passed in parameter opt_block_data. Note that it is valid for this length to be zero; an optional block can have an ID and a length, but no data. Type: String This parameter specifies a buffer where the application passes the data for the optional block that is to be added to those already in the buffer in parameter opt_blocks. The length of this data is specified in parameter opt_block_data_length. Restrictions None. | | Type: Integer Usage Notes | | | | | | Unless otherwise noted, all String parameters that are either written to, or read from, a TR-31 key block will be in EBCDIC format. Input parameters are converted to ASCII before being written to the TR-31 key block and output parameters are converted to EBCDIC before being returned (see Appendix G, “EBCDIC and ASCII Default Conversion Tables,” on page 891). TR-31 key blocks themselves are always in printable ASCII format as required by the ANSI TR-31 specification. | | | | Note that the Padding Block, ID “PB” is not allowed to be added by the user. A Padding Block of the appropriate size, if needed, will be added when building the TR-31 key block in TR-31 Export. If the TR-31 Export callable service encounters a padding block in the optional block data, an error will occur. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 5. Managing Symmetric Cryptographic Keys 313 TR-31 Optional Data Build | Table 122. TR-31 Optional Data Build required hardware | | | Server | | IBM Eserver zSeries None 900 | | IBM Eserver zSeries None 990 | | IBM Eserver zSeries 890 | IBM System z9 EC | IBM System z9 BC | IBM System z10 EC | IBM System z10 BC | | z196 | | Required cryptographic hardware Restrictions None None None TR-31 Optional Data Read (CSNBT31R and CSNET31R) | | | | A TR-31 key block can hold optional fields which are securely bound to the key block using the integrated MAC. The optional blocks may either contain information defined in the TR-31 standard, or they may contain proprietary data. A separate range of optional block identifiers is reserved for use with proprietary blocks. | | Note that some of the parameters are only used with keyword INFO and others are only used with keyword DATA. | The callable service name for AMODE(64) is CSNET31R. | Format || | | | | | | | | | | | | | | | | CSNBT31R( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, TR31_key_block_length, TR31_key_block, opt_block_id, num_opt_blocks, opt_block_ids, opt_block_lengths, opt_block_data_length, opt_block_data ) Parameters | return_code || | Direction: Output 314 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer TR-31 Optional Data Read | | The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. | reason_code || | Direction: Output | | | | The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | exit_data_length || | Direction: Ignored | exit_data || | Direction: Ignored Type: String This field is ignored. | rule_array_count || | Direction: Input | | Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | | Type: Integer Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 1 | rule_array || | Direction: Input Type: String | | | | The rule_array contains keywords that provide control information to the callable service. The keywords are 8 bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords for this callable service are shown in the following table. | Table 123. Keywords for TR-31 Optional Data Read Rule Array Control Information | Keyword | Operation – one required | | INFO Return information about the optional blocks in the TR-31 key block. | | | DATA Return the data contained in a specified optional block in the TR-31 key block. | TR31_key_block_length || | | | | | Direction: Input | | TR31_key_block Meaning Type: Integer This parameter specifies the length of the TR31_key_block parameter, in bytes. The parameter may specify a length that is greater than the size of the key block however it can never be greater than the size of the buffer where the key block resides. This value must be between 16 and 9992 inclusive. Chapter 5. Managing Symmetric Cryptographic Keys 315 TR-31 Optional Data Read || | | | Direction: Input | opt_block_id || | | | | | | | Direction: Input | num_opt_blocks || | | | | | Direction: Input | opt_block_ids || | | | | | | | | | | Direction: Output | opt_block_lengths || | | | | | | | | | | Direction: Output | opt_block_data_length || | | | | | Direction: Input/Output | | opt_block_data Type: String This parameter contains the TR-31 key block that is to be parsed. The length of the TR-31 block is specified using parameter TR31_key_block_length. Type: String This parameter is only used with option DATA. It is ignored for others. It specifies a 2-byte string which contains the identifier of the block from which the application is requesting data. The callable service will locate this optional block within the TR-31 structure and copy the data from that optional block into the returned opt_block_data buffer. If the specified optional block is not found in the TR-31 key block, an error will occur. Type: Integer This parameter specifies the number of optional blocks in the TR-31 key block. The value is compared to the corresponding value in the TR-31 block header and if they do not match the callable service fails with an error. This parameter is only used for option INFO and is not examined for any other options. Type: String Array This parameter contains an array of two-byte string values. Each of these values is the identifier (ID) of one of the optional blocks contained in the TR-31 key block. The callable service returns a list containing the ID of each optional block that is in the TR-31 block, and the list is in the order that the optional blocks appear in the TR-31 header. The total length of the returned list will be two times the number of optional blocks, and the caller must supply a buffer with a length at least twice the value it passes in parameter num_opt_blocks. This parameter is only used for option INFO and is not examined for any other options. Type: Integer Array This parameter contains an array of integer values. Each of these values is the length in bytes of one of the optional blocks contained in the TR-31 key block. The callable service returns a list containing the length of each optional block that is in the TR-31 block, and the list is in the order that the optional blocks appear in the TR-31 header. The total length of the returned list will be four times the number of optional blocks and the application program must supply a buffer with a length at least four times the value it passes in parameter num_opt_blocks. This parameter is only used for option INFO and is not examined or altered for any other options. Type: Integer This parameter specifies the length for parameter opt_block_data. On input it must be set to the length of the buffer provided by the application program, and on output it is updated to contain the length of the returned optional block data, in bytes. It is only used for option DATA. 316 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Optional Data Read || | | | | | | | | | Direction: Output This parameter contains a buffer where the callable service stores the data it reads from the specified optional block. The buffer must have enough space for the data, as indicated by the input value of parameter opt_block_data_length. If not an error occurs and no changes are made to the contents of the buffer. If the size of the buffer is sufficient, the data is copied to the buffer and its length is stored in parameter opt_block_data_length. It is only used for option DATA and is not examined or altered for any other options. Restrictions None | | Type: String Usage Notes | | | | | | Unless otherwise noted, all String parameters that are either written to, or read from, a TR-31 key block will be in EBCDIC format. Input parameters are converted to ASCII before being written to the TR-31 key block and output parameters are converted to EBCDIC before being returned (see Appendix G, “EBCDIC and ASCII Default Conversion Tables,” on page 891). TR-31 key blocks themselves are always in printable ASCII format as required by the ANSI TR-31 specification. | | | | | | | | | | The TR-31 Optional Data Read callable service (CSNBT31R and CSNET31R) can be used in conjunction with the TR-31 Parse callable service (CSNBT31P and CSNET31P) to obtain both the standard header fields and any optional data blocks from the key block. This is generally a three-step process. 1. Use the TR-31 Parse callable service to determine how many optional blocks are in the TR-31 token. This is returned in the num_opt_blocks parameter. 2. Use keyword INFO with the TR-31 Optional Data Read callable service to obtain lists of the optional block identifiers and optional block lengths. Your buffers must be large enough to hold the returned data, but the required size can be determined from the number of blocks obtained in the step above. | | 3. Use keyword DATA with the TR-31 Optional Data Read callable service to obtain the data for a particular optional block, specified by the block identifier. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. | Table 124. TR-31 Optional Data Read required hardware | | | Server | | IBM Eserver zSeries None 900 | | IBM Eserver zSeries None 990 | | IBM Eserver zSeries 890 | IBM System z9 EC | IBM System z9 BC | IBM System z10 EC | IBM System z10 BC Required cryptographic hardware Restrictions None None Chapter 5. Managing Symmetric Cryptographic Keys 317 TR-31 Optional Data Read | Table 124. TR-31 Optional Data Read required hardware (continued) | | | | | | | Server Required cryptographic hardware z196 None Restrictions TR-31 Parse (CSNBT31P and CSNET31P) | | Use the TR-31 Parse callable service to retrieve standard header information from a TR-31 key block without importing the key. | The callable service name for AMODE(64) is CSNET31P. | Format || | | | | | | | | | | | | | | | | | | CALL CSNBT31P( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, TR31_key_block_length, TR31_key_block, key_block_version, key_block_length, key_usage, algorithm, mode, key_version_number, exportability, num_opt_blocks ) Parameters | return_code || | Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. | | | reason_code || | Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | | | | | exit_data_length || | Direction: Ignored Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | 318 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Parse | exit_data || | Direction: Ignored | This field is ignored. | rule_array_count || | Direction: Input | | | rule_array || | Direction: Input TR31_key_block_length || | Direction: Input TR31_key_block || | Direction: Input key_block_version || | Direction: Output key_block_length || | Direction: Output Type: Integer This parameter contains the length of the key block as obtained from the TR-31 key block header. Note that this may be different from the input value in parameter TR31_key_block_length, if the application program specifies a length that is greater than the actual length of the key block. | key_usage || | Direction: Output | | Type: String This parameter contains a one-byte character value that indicates the version of the TR-31 key block, parsed from the block itself. CCA only supports versions "A", "B", and "C" key blocks. | | | | | Type: String This parameter contains the TR-31 key block that is to be parsed. | | | | Type: Integer This parameter specifies the length of the TR31_key_block parameter, in bytes. The parameter may specify a length that is greater than the size of the key block (however it can never be greater than the size of the buffer where the key block resides). This value must be between 16 and 9992 inclusive. | | Type: String A rule_array contains keywords that provide control information to the callable service. No rule array keywords are currently defined for this callable service. | | | | | Type: Integer The number of keywords you are supplying in the rule_array parameter. The rule_array_count parameter must be 0 because no keywords are currently defined for this callable service. | | | Type: String Type: String This parameter contains a 2-byte string value indicating the TR-31 key usage value for the key contained in the block. The value is obtained from the TR-31 Chapter 5. Managing Symmetric Cryptographic Keys 319 TR-31 Parse key block header. The usage defines the type of function this key can be used with, such as data encryption, PIN encryption, or key wrapping. | | | algorithm || | Direction: Output This parameter contains a one-byte string identifying the cryptographic algorithm the wrapped key is to be used with. The value is read from the TR-31 key block header. CCA only supports "D" for a Single-DES key and "T" for a Triple-DES key. | | | | | mode || | Direction: Output | key_version_number || | Direction: Output Type: String This parameter contains a two-byte string obtained from the TR-31 key block header which represents versioning information about the key contained in the block. | | | | exportability || | Direction: Output Type: String This parameter contains a one-byte string indicating the key exportability value from the TR-31 key block header. This value indicates whether the key can be exported from this system, and if so it specifies conditions under which export is permitted. | | | | | num_opt_blocks || | Direction: Output Type: Integer This parameter contains the number of optional blocks that are part of the TR-31 key block. | | Restrictions None | | Type: String This parameter contains a one-byte string indicating the TR-31 mode of use for the key contained in the block. The value is obtained from the TR-31 key block header. The mode of use describes what operations the key can perform, within the limitations specified with the key usage value. For example, a key with usage for data encryption can have a mode to indicate it may be used for encryption only, decryption only, or both encryption and decryption. | | | | | | | Type: String Usage Notes Unless otherwise noted, all String parameters that are either written to, or read from, a TR-31 key block will be in EBCDIC format. Input parameters are converted to ASCII before being written to the TR-31 key block and output parameters are converted to EBCDIC before being returned (see Appendix G, “EBCDIC and ASCII Default Conversion Tables,” on page 891). TR-31 key blocks themselves are always in printable ASCII format as required by the ANSI TR-31 specification. | | | | | | 320 z/OS V1R13 ICSF Application Programmer's Guide TR-31 Parse | | | | | | | | | | | | The TR-31 Optional Data Read callable service (CSNBT31R and CSNET31R) can be used in conjunction with the TR-31 Parse callable service (CSNBT31P and CSNET31P) to obtain both the standard header fields and any optional data blocks from the key block. This is generally a three-step process. 1. Use the TR-31 Parse callable service to determine how many optional blocks are in the TR-31 token. This is returned in the num_opt_blocks parameter. 2. Use keyword INFO with the TR-31 Optional Data Read callable service to obtain lists of the optional block identifiers and optional block lengths. Your buffers must be large enough to hold the returned data, but the required size can be determined from the number of blocks obtained in the step above. 3. Use keyword DATA with the TR-31 Optional Data Read callable service to obtain the data for a particular optional block, specified by the block identifier. | | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. | Table 125. TR-31 Parse required hardware | | | Server | | IBM Eserver zSeries None 900 | | IBM Eserver zSeries None 990 | | IBM Eserver zSeries 890 | IBM System z9 EC | IBM System z9 BC | IBM System z10 EC | IBM System z10 BC | | z196 Required cryptographic hardware Restrictions None None None | User Derived Key (CSFUDK and CSFUDK6) This callable service is not supported on an IBM Eserver zSeries 990, IBM Eserver zSeries 890, z9 EC and z9 BC, z10 EC and z10 BC. Diversifed key generate callable service can be used to perform this processing. Use the user derived key callable service to generate a single-length or double-length MAC key or to update an existing user derived key. A single-length MAC key can be used to compute a MAC following the ANSI X9.9, ANSI X9.19, or the Europay, MasterCard and VISA (EMV) Specification MAC processing rules. A double-length MAC key can be used to compute a MAC following either the ANSI X9.19 optional double MAC processing rule or the EMV Specification MAC processing rule. This service updates an existing user derived key by XORing it with data you supply in the data_array parameter. This is called SESSION MAC key generation by VISA. Chapter 5. Managing Symmetric Cryptographic Keys 321 User Derived Key This service adjusts the user derived key or SESSION MAC key to odd parity. The parity of the supplied derivation key is not tested. The callable service name for AMODE(64) invocation is CSFUDK6. Format CALL CSFUDK( return_code, reason_code, exit_data_length, exit_data, key_type, rule_array_count, rule_array, derivation_key_identifier, source_key_identifier, data_array, generated_key_identifier) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_type Direction: Input Type: String The 8-byte keyword of 'MAC ' or 'MACD ' that specifies the key type to be generated. The keyword must be left-justified and padded on the right with blanks. MAC specifies an 8-byte, single-length MAC key which is used in the 322 z/OS V1R13 ICSF Application Programmer's Guide User Derived Key ANSI X9.9-1 or the ANSI X9.19 basic MAC processing rules. MACD specifies a 16-byte, double-length internal MAC key that uses the single-length control vector for both the left and right half of the key (MAC { MAC). The double-length MAC key is used in the ANSI X9.19 optional double-key MAC processing rules. The keyword 'TOKEN ' is also accepted. If you specify TOKEN with a rule_array of VISA or NOFORMAT, the key type is determined by the valid internal token of the single-length or double-length MAC key in the generated_key_identifier parameter. If you specify TOKEN with a rule_array of SESS-MAC, the key type is determined by the valid internal token of the single-length or double-length MAC key in the source_key_identifier. rule_array_count Direction: Input Type: Integer The number of keywords specified in the rule_array parameter. The value must be 1. rule_array Direction: Input Type: Character string The process rule for the user derived key in an 8-byte field. The keywords must be in 8 bytes of contiguous storage, left-justified and padded on the right with blanks. The keywords are shown in Table 126. Table 126. Keywords for User Derived Key Control Information Keyword Meaning User Derived Key Process Rules (required) NOFORMAT For generating a user derived key with no formatting done on the array before encryption under the derivation_key_identifier. SESS-MAC To update an existing user derived key supplied in the source_key_ identifier parameter with data provided in the data_array parameter. VISA For generating a user derived key using the VISA algorithm to format the data array input before encryption under the derivation_key_identifier. For guidance information refer to the VISA Integrated Circuit Card Specification, V1.3 Aug 31, 1996. derivation_key_identifier Direction: Input/Output Type: String For a rule_array value of VISA or NOFORMAT, this is a 64-byte key label or internal key token of the derivation key used to generate the user derived key. The key must be an EXPORTER key type. For any other keyword, this field must be a null token. source_key_identifier Direction: Input/Output Type: String Chapter 5. Managing Symmetric Cryptographic Keys 323 User Derived Key For a rule_array value of SESS-MAC, this is a 64-byte internal token of a single-length or double-length MAC key. For any other keyword, this field must be a null token. data_array Direction: Input Type: String Two 16-byte data elements required by the corresponding rule_array and key_type parameters. The data array consists of two 16-byte hexadecimal character fields whose specification depends on the process rule and key type. VISA requires only one 16-byte hexadecimal character input. Both NOFORMAT and SESS-MAC require one 16-byte input for a key type of MAC and two 16-byte inputs for a key type of MACD. If only one 16-byte field is required, then the rest of the data array is ignored by the callable service. generated_key_identifier Direction: Input/Output Type: String The 64-byte internal token of the generated single-length or double-length MAC key. This is an input field only if TOKEN is specified for key_type. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. This service requires that the ANSI system keys be installed in the CKDS. The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 127. User derived key required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries 990 This callable service is not supported. IBM Eserver zSeries 890 324 IBM System z9 EC and z9 BC This callable service is not supported. IBM System z10 EC and z10 BC This callable service is not supported. z196 This callable service is not supported. z/OS V1R13 ICSF Application Programmer's Guide Chapter 6. Protecting Data Use ICSF to 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. ICSF provides encipher and decipher callable services to perform these functions. If you use a key to encipher data, you must use the same key to decipher the data. To use clear keys directly, ICSF provides symmetric key decipher, symmetric key encipher, encode and decode callable services. These services encipher and decipher with clear keys. You can use clear keys indirectly by first using the clear key import callable service, and then using the encipher and decipher callable services. This topic describes these services: v “Ciphertext Translate (CSNBCTT or CSNBCTT1 and CSNECTT or CSNECTT1)” on page 328 v “Decipher (CSNBDEC or CSNBDEC1 and CSNEDEC or CSNEDEC1)” on page 331 v “Decode (CSNBDCO and CSNEDCO)” on page 338 v “Encipher (CSNBENC or CSNBENC1 and CSNEENC or CSNEENC1)” on page 340 v “Encode (CSNBECO and CSNEECO)” on page 348 v “Symmetric Algorithm Decipher (CSNBSAD or CSNBSAD1 and CSNESAD or CSNESAD1)” on page 350 v “Symmetric Algorithm Encipher (CSNBSAE or CSNBSAE1 and CSNESAE or CSNESAE1)” on page 356 v “Symmetric Key Decipher (CSNBSYD or CSNBSYD1 and CSNESYD or CSNESYD1)” on page 362 v “Symmetric Key Encipher (CSNBSYE or CSNBSYE1 and CSNESYE or CSNESYE1)” on page 371 Modes of Operation To encipher or decipher data or keys, ICSF uses either the U.S. National Institute of Standards and Technology (NIST) Data Encryption Standard (DES) algorithm or the Commercial Data Masking Facility (CDMF). The DES algorithm is documented in Federal Information Processing Standard #46. CDMF provides DES cryptography using an effectively shortened DATA key. See “System Encryption Algorithm” on page 49 for more information. To encipher or decipher data, ICSF also uses the U.S. National Institute of Standards and Technology (NIST) Advanced Encryption Standard (AES) algorithm. The AES algorithm is documented in Federal Information Processing Standard 197. ICSF enciphers and deciphers using several modes of operation. Some of the modes have variations related to padding or blocking of the data. The text in parentheses is the processing rule associated with that mode. The supported modes are: v Electronic code book (ECB) v Cipher block chaining (CBC) – Cipher block chaining with ciphertext stealing (CBC-CS) – Cipher block chaining compatible with CUSP/PCF (CUSP) © Copyright IBM Corp. 1997, 2011 325 – Cipher block chaining – Cipher block chaining – Cipher block chaining – Cipher block chaining v Cipher Feedback (CFB) compatible with IPS (IPS) using PKCS#7 padding (PKCS-PAD) using ANSI X9.23 padding (X9.23) using IBM 4700 padding (4700-PAD) – Cipher Feedback with a non-blocksize segment (CFB-LCFB) v Output Feedback (OFB) v Galois/Counter Mode (GCM) Electronic Code Book (ECB) Mode In the 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. ICSF uses the ECB encipherment mode for enciphering and deciphering data with clear keys using the encode and decode callable services. ICSF does not support ECB encipherment mode on CDMF-only systems. Cipher Block Chaining (CBC) Mode The CBC mode uses an initial chaining vector (ICV) in its processing. The CBC mode only processes blocks of data 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 callable services. “Cipher Processing Rules” on page 874 describes the CBC-specific processing rules in detail. Cipher Feedback (CFB) Mode The CFB mode uses an initial chaining vector (ICV) in its processing. CFB mode performs cipher feedback encryption. CFB mode operates on segments instead of blocks. The segment length (called s) is between one bit and the block size (called b) for the underlying algorithm (DES or AES), inclusive. ICSF only allows segment sizes which are a multiple of eight bits (complete bytes). Each encryption step takes an input block, enciphers it with the key provided to generate an output block, takes the most significant s bits of the output block, and then exclusive ORs that with the plaintext segment. The first input block is the ICV and each subsequent input block is formed by concatenating the (b-s) least significant bits of the previous input block and the ciphertext (s bits) from the previous step to form a full block. The input text can be of any length. The output text will have the same length as the input text. Output Feedback (OFB) Mode The OFB mode uses an initial chaining vector (ICV) in its processing. OFB mode requires that the ICV is a nonce (the ICV must be unique for each execution of the mode under the given key). Each encryption step takes an input block, enciphers it with the key provided to generate an output block, and then exclusive ORs the output block with the plaintext block. The first input block is the ICV and each subsequent input block is the previous output block. The input text can be of any length. The output text will have the same length as the input text. 326 z/OS V1R13 ICSF Application Programmer's Guide Galois/Counter Mode (GCM) The GCM mode uses an initialization vector (IV) in its processing. This mode is used for authenticated encryption with associated data. GCM provides confidentiality and authenticity for the encrypted data and authenticity for the additional authenticated data (AAD). The AAD is not encrypted. GCM mode requires that the IV is a nonce, i.e., the IV must be unique for each execution of the mode under the given key. The steps for GCM encryption are: 1. The hash subkey for the GHASH function is generated by applying the block cipher to the “zero” block. 2. The pre-counter block (J0) is generated from the IV. In particular, when the length of the IV is 96 bits, then the padding string 031||1 is appended to the IV to form the pre-counter block. Otherwise, the IV is padded with the minimum number of ‘0’ bits, possibly none, so that the length of the resulting string is a multiple of 128 bits (the block size); this string in turn is appended with 64 additional ‘0’ bits, followed by the 64-bit representation of the length of the IV, and the GHASH function is applied to the resulting string to form the pre-counter block. 3. The 32-bit incrementing function is applied to the pre-counter block to produce the initial counter block for an invocation of the GCTR function on the plaintext. The output of this invocation of the GCTR function is the ciphertext. 4. The AAD and the ciphertext are each appended with the minimum number of ‘0’ bits, possibly none, so that the bit lengths of the resulting strings are multiples of the block size. The concatenation of these strings is appended with the 64-bit representations of the lengths of the AAD and the ciphertext to produce block u. 5. The GHASH function is applied to block u to produce a single output block. 6. This output block is encrypted using the GCTR function with the pre-counter block that was generated in Step 2, and the result is truncated to the specified tag length to form the authentication tag. 7. The ciphertext and the tag are returned as the output. The plaintext can be of any length. The ciphertext will have the same length as the plaintext. For GCM decryption, the tag is an input parameter. ICSF calculates a tag using the same process as encryption and compares that to the parameter passed by the caller. If they match, the decryption will proceed. Triple DES Encryption Triple-DES encryption uses a triple-length DATA key comprised of three 8-byte DES keys to encipher 8 bytes of data using this 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 ICSF uses the triple-DES encryption in the CBC encipherment mode. Chapter 6. Protecting Data 327 A variation of the triple DES algorithm supports the use of a double-length DATA key comprised of two 8-byte DATA keys. In this method, the first 8-byte key is reused in the last encipherment step. Due to export regulations, triple-DES encryption may not be available on your processor. Ciphertext Translate (CSNBCTT or CSNBCTT1 and CSNECTT or CSNECTT1) This callable service is only supported on the IBM Eserver zSeries 900. ICSF provides a ciphertext translate callable service on DES-capable systems. The callable service deciphers encrypted data (ciphertext) under one data translation key and reenciphers it under another data translation key without having the data appear in the clear outside the Cryptographic Coprocessor Feature. ICSF uses the data translation key as either the input or the output data transport key. Such a function is useful in a multiple node network, where sensitive data is passed through multiple nodes prior to it reaching its final destination. “Using the Ciphertext Translate Callable Service” on page 66 provides some tips on using the callable service. Use the ciphertext translate callable service to decipher text under an “input” key and then to encipher the text under an “output” key. The callable service uses the cipher block chaining (CBC) mode of the DES. This service is available only on a DES-capable system. Choosing Between CSNBCTT and CSNBCTT1 CSNBCTT and CSNBCTT1 provide identical functions. When choosing the service to use, consider this: v CSNBCTT requires the input text and output text to reside in the caller's primary address space. Also, a program using CSNBCTT adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNECTT. v CSNBCTT1 allows the input text and output text to reside either in the caller's primary address space or in a data space. This allows you to translate more data with one call. However, a program using CSNBCTT1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to it running with other cryptographic products that follow this programming interface. The callable service name for AMODE(64) invocation is CSNECTT1. For CSNBCTT1 and CSNECTT1, text_id_in and text_id_out are access list entry token (ALET) parameters of the data spaces containing the input text and output text. 328 z/OS V1R13 ICSF Application Programmer's Guide Ciphertext Translate Format CALL CSNBCTT( return_code, reason_code, exit_data_length, exit_data, key_identifier_in, key_identifier_out, text_length, text_in, initialization_vector_in, initialization_vector_out, text_out ) CALL CSNBCTT1( return_code, reason_code, exit_data_length, exit_data, key_identifier_in, key_identifier_out, text_length, text_in, initialization_vector_in, initialization_vector_out, text_out, text_id_in, text_id_out ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String Chapter 6. Protecting Data 329 Ciphertext Translate The data that is passed to the installation exit. key_identifier_in Direction: Input/Output Type: String The 64-byte string of the internal key token containing the data translation (DATAXLAT) key, or the label of the CKDS record containing the DATAXLAT key used to encipher the input string. key_identifier_out Direction: Input/Output Type: String The 64-byte string of an internal key token containing the DATAXLAT key, or the label of the CKDS record containing the DATAXLAT key, used to reencipher the encrypted text. text_length Direction: Input Type: Integer The length of the ciphertext that is to be processed. The text length must be a multiple of 8 bytes. The maximum length of text is 2,147,836,647 bytes. Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced. text_in Direction: Input Type: String The text that is to be translated. The text is enciphered under the data translation key specified in the key_identifier_in parameter. initialization_vector_in Direction: Input Type: String The 8-byte initialization vector that is used to decipher the input data. This parameter is the initialization vector used at the previous cryptographic node. initialization_vector_out Direction: Input Type: String The 8-byte initialization vector that is used to encipher the input data. This is the new initialization vector used when the callable service enciphers the plaintext. text_out Direction: Output Type: String The field where the callable service returns the translated text. text_id_in Direction: Input 330 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Ciphertext Translate For CSNBCTT1 only, the ALET of the text to be translated. text_id_out Direction: Input Type: Integer For CSNBCTT1 only, the ALET of the text_out field that the application supplies. Restrictions The input ciphertext length must be an exact multiple of 8 bytes. The minimum length of the ciphertext that can be translated is 8 bytes. You cannot use this service on a CDMF-only system. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. The initialization vectors must have already been established between the communicating applications or must be passed with the data. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 128. Ciphertext translate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries 990 This callable service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This callable service is not supported. IBM System z9 BC IBM System z10 EC This callable service is not supported. IBM System z10 BC z196 This callable service is not supported. Decipher (CSNBDEC or CSNBDEC1 and CSNEDEC or CSNEDEC1) Use the decipher callable service to decipher data in an address space or a data space using the cipher block chaining mode. ICSF supports these processing rules to decipher data. You choose the type of processing rule that the decipher callable service should use for block chaining. Processing Rule Purpose ANSI X9.23 For cipher block chaining. The ciphertext must be an exact multiple of 8 bytes, but the plaintext will be Chapter 6. Protecting Data 331 Decipher 1 to 8 bytes shorter than the ciphertext. The text_length will also be reduced to show the original length of the plaintext. CBC For cipher block chaining. The ciphertext must be an exact multiple of 8 bytes, and the plaintext will have the same length. CUSP For cipher block chaining, but the ciphertext can be of any length. The plaintext will be the same length as the ciphertext. IBM 4700 For cipher block chaining. The ciphertext must be an exact multiple of 8 bytes, but the plaintext will be 1 to 8 bytes shorter than the ciphertext. The text_length will also be reduced to show the original length of the plaintext. IPS For cipher block chaining, but the ciphertext can be of any length. The plaintext will be the same length as the ciphertext. The cipher block chaining (CBC) mode uses an initial chaining value (ICV) in its processing. The first 8 bytes of ciphertext is deciphered and then the ICV is exclusive ORed with the resulting 8 bytes of data to form the first 8-byte block of plaintext. Thereafter, the 8-byte block of ciphertext is deciphered and exclusive ORed 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. A different ICV may be passed on each call to the decipher callable service. However, the same ICV that was used in the corresponding encipher callable service must be passed. Short blocks are text lengths of 1 to 7 bytes. A short block can be the only block. Trailing short blocks are blocks of 1 to 7 bytes that follow an exact multiple of 8 bytes. For example, if the text length is 21, there are two 8-byte blocks and a trailing short block of 5 bytes. Because the DES and CDMF process only text in exact multiples of 8 bytes, some special processing is required to decipher such short blocks. Short blocks and trailing short blocks of 1 to 7 bytes of data are processed according to the Cryptographic Unit Support Program (CUSP) rules, or by the record chaining scheme devised by and used in the Information Protection System (IPS) in the IPS/CMS product. These methods of treating short blocks and trailing short blocks do not increase the length of the ciphertext over the plaintext. If the plaintext was padded during encipherment, the length of the ciphertext will always be an exact multiple of 8 bytes. ICSF supports these padding schemes: v ANSI X9.23 v 4700-PAD 332 z/OS V1R13 ICSF Application Programmer's Guide Decipher Choosing Between CSNBDEC and CSNBDEC1 CSNBDEC and CSNBDEC1 provide identical functions. When choosing which service to use, consider this: v CSNBDEC requires the ciphertext and plaintext to reside in the caller's primary address space. Also, a program using CSNBDEC adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNEDEC. v CSNBDEC1 allows the ciphertext and plaintext to reside either in the caller's primary address space or in a data space. This can allow you to decipher more data with one call. However, a program using CSNBDEC1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to it running with other cryptographic products that follow this programming interface. The callable service name for AMODE(64) invocation is CSNEDEC1. For CSNBDEC1 and CSNEDEC1, cipher_text_id and clear_text_id are access list entry token (ALET) parameters of the data spaces containing the ciphertext and plaintext. Format CALL 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 ) CALL CSNBDEC1( 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, cipher_text_id, clear_text_id ) Parameters return_code Direction: Output Type: Integer Chapter 6. Protecting Data 333 Decipher The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier Direction: Input/Output Type: String A 64-byte string that is the internal key token containing the data-encrypting key, or the label of a CKDS 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. On the IBM Eserver zSeries 990,IBM Eserver zSeries 890, z9 EC and z9 BC single and 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 214783647 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. Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced. The application program passes the length of the ciphertext to the callable service. The callable service returns the length of the plaintext to your application program. cipher_text Direction: Input 334 z/OS V1R13 ICSF Application Programmer's Guide Type: String Decipher 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 exclusive ORed 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 The number of keywords you supply in the rule_array parameter. The value must be 1, 2, or 3. rule_array Direction: Input Type: Character string An array of 8-byte keywords providing the processing control information. The array is positional. See the keywords in Table 129. The first keyword in the array is the processing rule. You choose the processing rule you want the callable service 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 service will fail if keyword DES is specified in the rule_array in a CDMF-only system. The service will likewise fail if keyword CDMF is specified in the rule_array in a DES-only system. Table 129. Keywords for the Decipher Rule Array Control Information Keyword Meaning Processing Rule (required) CBC Performs ANSI X3.102 cipher block chaining. The data must be a multiple of 8 bytes. An OCV is produced and placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CBC OCV from the previous call is used as the ICV for this call. CUSP Performs deciphering that is compatible with IBM's CUSP and PCF products. The data can be of any length and does not need to be in multiples of 8 bytes. The ciphertext will be the same length as the plaintext. The CUSP/PCF OCV is placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CUSP/PCF OCV from the previous call is used as the ICV for this call. IPS Performs deciphering that is compatible with IBM's IPS product. The data can be of any length and does not need to be in multiples of 8 bytes. The ciphertext will be the same length as the plaintext. The IPS OCV is placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the IPS OCV from the previous call is used as the ICV for this call. Chapter 6. Protecting Data 335 Decipher Table 129. Keywords for the Decipher Rule Array Control Information (continued) Keyword Meaning X9.23 Deciphers with cipher block chaining and text length reduced to the original value. This is compatible with the requirements in ANSI standard X9.23. The ciphertext length must be an exact multiple of 8 bytes. Padding is removed from the plaintext. 4700-PAD Deciphers with cipher block chaining and text length reduced to the original value. The ciphertext length must be an exact multiple of 8 bytes. Padding is removed from the plaintext. ICV Selection (optional) CONTINUE This specifies taking the initialization vector from the output chaining vector (OCV) contained in the work area to which the chaining_vector parameter points. CONTINUE is valid only for processing rules CBC, IPS, and CUSP. INITIAL This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value. Encryption Algorithm (optional) CDMF This specifies using the Commercial Data Masking Facility and ignoring the token marking. You cannot use double- or triple-length keys with CDMF. The CDMF keyword, or tokens marked as CDMF, are only supported on an IBM Eserver zSeries 900. DES This specifies using the data encryption standard and ignoring the token marking. TOKEN This specifies using the data encryption algorithm in the DATA key token. This is the default. “Cipher Processing Rules” on page 874 describes the cipher processing rules in detail. chaining_vector Direction: Input/Output Type: String An 18-byte field that ICSF uses 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 8 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 callable service returns the deciphered text. cipher_text_id 336 z/OS V1R13 ICSF Application Programmer's Guide Decipher Direction: Input Type: Integer For CSNBDEC1/CSNEDEC1 only, the ALET of the ciphertext to be deciphered. clear_text_id Direction: Input Type: Integer For CSNBDEC1/CSNEDEC1 only, the ALET of the clear text supplied by the application. Restrictions The service will fail under these conditions: v If the keyword DES is specified in the rule_array parameter in a CDMF-only system v If the keyword CDMF is specified in the rule_array parameter in a DES-only system v If the key token contains double or triple-length keys and triple-DES is not enabled. v If the keyword CDMF is specified on a PCIXCC, CEX2C, or CEX3C. v If a token is marked CDMF on a PCIXCC, CEX2C, or CEX3C. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. On a CCF system, only a DATA key token or DATA key label can be used in this service. Single and double length CIPHER and DECIPHER keys are supported on a PCIXCC, CEX2C, or CEX3C. Related Information You cannot overlap the plaintext and ciphertext fields. For example: pppppp cccccc is not supported. cccccc pppppp is not supported. ppppppcccccc is supported. P represents the plaintext and c represents the ciphertext. On z990, z890, z9 EC or z9 BC system, the PCIXCC/CEX2C will support non destructive overlap. For example: pppppp cccccc is supported. “Cipher Processing Rules” on page 874 discusses the cipher processing rules. The Encipher callable services are described under “Encipher (CSNBENC or CSNBENC1 and CSNEENC or CSNEENC1)” on page 340. Chapter 6. Protecting Data 337 Decipher The Decipher - DES access control point controls the function of this service. | This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 130. Decipher required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. Crypto Express2 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. Decode (CSNBDCO and CSNEDCO) Use this callable service to decipher an 8-byte string using a clear key. The callable service uses the electronic code book (ECB) mode of the DES. (This service is available only on a DES-capable system.) The callable service name for AMODE(64) invocation is CSNEDCO. Considerations If you have only a clear key, you are not limited to using only the encode and decode callable services. v You can pass your clear key to the clear key import service, and get back a token that will allow you to use the encipher and decipher callable services. v On an IBM Eserver zSeries 990 and subsequent releases, consider using the Symmetric Key Decipher service (“Symmetric Key Decipher (CSNBSYD or CSNBSYD1 and CSNESYD or CSNESYD1)” on page 362). Format CALL CSNBDCO( return_code, reason_code, exit_data_length, exit_data, clear_key, cipher_text, clear_text) 338 z/OS V1R13 ICSF Application Programmer's Guide Decode Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. clear_key Direction: Input Type: String The 8-byte clear key value that is used to decode the data. cipher_text Direction: Input Type: String The ciphertext that is to be decoded. Specify 8 bytes of text. clear_text Direction: Output Type: String The 8-byte field where the plaintext is returned by the callable service. Restrictions You cannot use this service on a CDMF-only system. Usage Notes This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 6. Protecting Data 339 Decode Table 131. Decode required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries CP Assist for 990 Cryptographic Functions IBM Eserver zSeries 890 IBM System z9 EC IBM System z9 BC IBM System z10 EC IBM System z10 BC z196 CP Assist for Cryptographic Functions CP Assist for Cryptographic Functions CP Assist for Cryptographic Functions Encipher (CSNBENC or CSNBENC1 and CSNEENC or CSNEENC1) Use the encipher callable service to encipher data in an address space or a data space using the cipher block chaining mode. ICSF supports these processing rules to encipher data. You choose the type of processing rule that the encipher callable service should use for the block chaining. Processing Rule Purpose ANSI X9.23 For block chaining not necessarily in exact multiples of 8 bytes. This process rule pads the plaintext so that ciphertext produced is an exact multiple of 8 bytes. CBC For block chaining in exact multiples of 8 bytes. CUSP For block chaining not necessarily in exact multiples of 8 bytes. The ciphertext will be the same length as the plaintext. IBM 4700 For block chaining not necessarily in exact multiples of 8 bytes. This process rule pads the plaintext so that the ciphertext produced is an exact multiple of 8 bytes. IPS For block chaining not necessarily in exact multiples of 8 bytes. The ciphertext will be the same length as the plaintext. For more information about the processing rules, see Table 132 on page 344 and “Cipher Processing Rules” on page 874. The cipher block chaining (CBC) mode of operation uses an initial chaining vector (ICV) in its processing. The ICV is exclusive ORed with the first 8 bytes of plaintext prior to the encryption step, and thereafter, the 8-byte block of ciphertext just 340 z/OS V1R13 ICSF Application Programmer's Guide Encipher produced is exclusive ORed with the next 8-byte block of plaintext, and so on. This disguises any pattern that may 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 8 bytes of zero. However, the ICV may 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 callable service was invoked, assuming the same text, ICV, and key were used. Short blocks are text lengths of 1 to 7 bytes. A short block can be the only block. Trailing short blocks are blocks of 1 to 7 bytes that follow an exact multiple of 8 bytes. For example, if the text length is 21, there are two 8-byte blocks, and a trailing short block of 5 bytes. Short blocks and trailing short blocks of 1 to 7 bytes of data are processed according to the Cryptographic Unit Support Program (CUSP) rules, or by the record chaining scheme devised by and used by the Information Protection System (IPS) in the IPS/CMS program product. These methods of treating short blocks and trailing short blocks do not increase the length of the ciphertext over the plaintext. 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 8 bytes using one of several padding schemes. This padding produces a ciphertext that is an exact multiple of 8 bytes long. If the ciphertext is to be transmitted over a network, where one or more intermediate nodes will use the ciphertext translate callable service, the ciphertext must be produced using one of these methods of padding: v ANSI X9.23 v 4700 If the cleartext is already a multiple of 8, 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 8 bytes longer than the length of the plaintext to accommodate the maximum amount of padding. You should provide this extension in your installation's storage because ICSF cannot detect whether the extension was done. The minimum length of data that can be enciphered is one byte. 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. Chapter 6. Protecting Data 341 Encipher Choosing between CSNBENC and CSNBENC1 CSNBENC and CSNBENC1 provide identical functions. When choosing which service to use, consider this: v CSNBENC requires the cleartext and ciphertext to reside in the caller's primary address space. Also, a program using CSNBENC adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNEENC. v CSNBENC1 allows the cleartext and ciphertext to reside either in the caller's primary address space or in a data space. This can allow you to encipher more data with one call. However, a program using CSNBENC1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to it running with other cryptographic products that follow this programming interface. The callable service name for AMODE(64) invocation is CSNEENC1. For CSNBENC1 and CSNEENC1, clear_text_id and cipher_text_id are access list entry token (ALET) parameters of the data spaces containing the cleartext and ciphertext. Format CALL 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 ) CALL CSNBENC1( 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, clear_text_id, cipher_text_id ) Parameters return_code Direction: Output 342 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Encipher The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier Direction: Input/Output Type: String A 64-byte string that is the internal key token containing the data-encrypting key, or the label of a CKDS 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. On an IBM Eserver zSeries 990 and subsequent releases, 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 2,14783647 bytes. A zero 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. Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced (2147483647). The application program passes the length of the plaintext to the callable service. The callable service returns the length of the ciphertext to the application program. clear_text Chapter 6. Protecting Data 343 Encipher Direction: Input Type: String The text that is to be enciphered. initialization_vector Direction: Input Type: String The 8-byte supplied string for the cipher block chaining. The first 8 bytes (or less) block of the data is exclusive ORed 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 The number of keywords you supply in the rule_array parameter. The value must be 1, 2, or 3. rule_array Direction: Input Type: Character string An array of 8-byte keywords providing the processing control information. The array is positional. See the keywords in Table 132. The first keyword in the array is the processing rule. You choose the processing rule you want the callable service 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 service will fail if keyword DES is specified in the rule_array in a CDMF-only system. The service will likewise fail if the keyword CDMF is specified in the rule_array in a DES-only system. Table 132. Keywords for the Encipher Rule Array Control Information Keyword Meaning Processing Rule (required) 344 CBC Performs ANSI X3.102 cipher block chaining. The data must be a multiple of 8 bytes. An OCV is produced and placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CBC OCV from the previous call is used as the ICV for this call. CUSP Performs ciphering that is compatible with IBM's CUSP and PCF products. The data can be of any length and does not need to be in multiples of 8 bytes. The ciphertext will be the same length as the plaintext. The CUSP/PCF OCV is placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the CUSP/PCF OCV from the previous call is used as the ICV for this call. IPS Performs ciphering that is compatible with IBM's IPS product. The data may be of any length and does not need to be in multiples of 8 bytes. The ciphertext will be the same length as the plaintext. The IPS OCV is placed in the chaining_vector parameter. If the ICV selection keyword CONTINUE is specified, the IPS OCV from the previous call is used as the ICV for this call. z/OS V1R13 ICSF Application Programmer's Guide Encipher Table 132. Keywords for the Encipher Rule Array Control Information (continued) Keyword Meaning X9.23 Performs cipher block chaining with 1 to 8 bytes of padding. This is compatible with the requirements in ANSI standard X9.23. If the data is not in exact multiples of 8 bytes, X9.23 pads the plaintext so that the ciphertext produced is an exact multiple of 8 bytes. The plaintext is padded to the next multiple 8 bytes, even if this adds 8 bytes. An OCV is produced. 4700-PAD Performs padding by extending the user's plaintext with the caller's specified pad character, followed by a one-byte binary count field that contains the total number of bytes added to the message. 4700-PAD pads the plaintext so that the ciphertext produced is an exact multiple of 8 bytes. An OCV is produced. ICV Selection (optional) CONTINUE This specifies taking the initialization vector from the output chaining vector (OCV) contained in the work area to which the chaining_vector parameter points. CONTINUE is valid only for processing rules CBC, IPS, and CUSP. INITIAL This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value. Encryption Algorithm (optional) CDMF This specifies using the Commercial Data Masking Facility and ignoring the token marking. You cannot use double-length or triple-length keys with CDMF. The CDMF keyword, or tokens marked as CDMF, are only supported on an IBM Eserver zSeries 900. DES This specifies using the data encryption standard and ignoring the token marking. TOKEN This specifies using the data encryption algorithm in the DATA key token. TOKEN is the default. These recommendations help the caller determine which encipher processing rule to use: v If you are exchanging enciphered data with a specific implementation, for example, CUSP or ANSI X9.23, use that processing rule. v If the ciphertext translate callable service is to be invoked on the enciphered data at an intermediate node, ensure that the ciphertext is a multiple of 8 bytes. Use CBC, X9.23, or 4700-PAD to prevent the creation of ciphertext that is not a multiple of 8 bytes and that cannot be processed by the ciphertext translate callable service. v If the ciphertext length must be equal to the plaintext length and the plaintext length cannot be a multiple of 8 bytes, use either the IPS or CUSP processing rule. “Cipher Processing Rules” on page 874 describes the cipher processing rules in detail. pad_character Direction: Input Type: Integer Chapter 6. Protecting Data 345 Encipher An integer, 0 to 255, that is used as a padding character for the 4700-PAD process rule (rule_array parameter). chaining_vector Direction: Input/Output Type: String An 18-byte field that ICSF uses 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 8 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. cipher_text Direction: Output Type: String The enciphered text the callable service returns. The length of the ciphertext is returned in the text_length parameter. The cipher_text may be 8 bytes longer than the length of the clear_text field because of the padding that is required for some processing rules. clear_text_id Direction: Input Type: Integer For CSNBENC1/CSNEENC1 only, the ALET of the clear text to be enciphered. cipher_text_id Direction: Input Type: Integer For CSNBENC1/CSNEENC1 only, the ALET of the ciphertext that the application supplied. Restrictions The service will fail under these conditions: v If the keyword DES is specified in the rule_array parameter in a CDMF-only system v If the keyword CDMF is specified in the rule_array parameter in a DES-only system v If the key token contains double- or triple-length keys and triple-DES is not enabled. v If the keyword CDMF is specified on a PCIXCC, CEX2C, or CEX3C. v If a token is marked CDMF on a PCIXCC, CEX2C, or CEX3C. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. 346 z/OS V1R13 ICSF Application Programmer's Guide Encipher On a CCF system, only a DATA key token or DATA key label can be used in this service. Single and double length CIPHER and ENCIPHER keys are supported on a PCIXCC, CEX2C, or CEX3C. | The Encipher - DES access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 133. Encipher required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. Crypto Express2 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor If keyword CDMF is specified or if the token is marked as CDMF, the service fails. Related Information You cannot overlap the plaintext and ciphertext fields. For example: pppppp cccccc is not supported. cccccc pppppp is not supported. ppppppcccccc is supported. P represents the plaintext and c represents the ciphertext. On z990, z890 , z9 EC and z9 BC systems, the PCIXCC/CEX2C will support non destructive overlap. For example: cccccc pppppp is supported. The method used to produce the OCV is the same with the CBC, 4700-PAD, and X9.23 processing rules. However, that method is different from the method used by the CUSP and IPS processing rules. “Cipher Processing Rules” on page 874 discusses the cipher processing rules. Chapter 6. Protecting Data 347 Encipher The Decipher callable services are described under “Decipher (CSNBDEC or CSNBDEC1 and CSNEDEC or CSNEDEC1)” on page 331. Encode (CSNBECO and CSNEECO) Use the encode callable service to encipher an 8-byte string using a clear key. The callable service uses the electronic code book (ECB) mode of the DES. (This service is available only on a DES-capable system.) The callable service name for AMODE(64) invocation is CSNEECO. Considerations If you have only a clear key, you are not limited to using just the encode and decode callable services. v You can pass your clear key to the clear key import service, and get back a token that will allow you to use the encipher and decipher callable services. v On an IBM Eserver zSeries 990 and subsequent releases, consider using the Symmetric Key Encipher service (“Symmetric Key Encipher (CSNBSYE or CSNBSYE1 and CSNESYE or CSNESYE1)” on page 371). Format CALL CSNBECO( return_code, reason_code, exit_data_length, exit_data, clear_key, clear_text, cipher_text) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. 348 z/OS V1R13 ICSF Application Programmer's Guide Encode exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. clear_key Direction: Input Type: String The 8-byte clear key value that is used to encode the data. clear_text Direction: Input Type: String The plaintext that is to be encoded. Specify 8 bytes of text. cipher_text Direction: Output Type: String The 8-byte field where the ciphertext is returned by the callable service. Restrictions You cannot use this service on a CDMF-only system. Usage Notes This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 134. Encode required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries CP Assist for 990 Cryptographic Functions IBM Eserver zSeries 890 IBM System z9 EC IBM System z9 BC IBM System z10 EC IBM System z10 BC z196 CP Assist for Cryptographic Functions CP Assist for Cryptographic Functions CP Assist for Cryptographic Functions Chapter 6. Protecting Data 349 Symmetric Algorithm Decipher Symmetric Algorithm Decipher (CSNBSAD or CSNBSAD1 and CSNESAD or CSNESAD1) The symmetric algorithm decipher callable service deciphers data with the AES algorithm. Data is deciphered that has been enciphered in either CBC mode or ECB mode. You can specify that the clear text data was padded before encryption using the method described in the PKCS standards. In this case, the callable service will remove the padding bytes and return the unpaded clear text data. PKCS padding is described in “PKCS Padding Method” on page 877. The callable service names for AMODE(64) invocation are CSNESAD and CSNESAD1. Choosing Between CSNBSAD and CSNBSAD1 or CSNESAD and CSNESAD1 CSNBSAD, CSNBSAD1, CSNESAD, and CSNESAD1 provide identical functions. When choosing which service to use, consider this: v CSNBSAD and CSNESAD require the cipher text and plaintext to reside in the caller’s primary address space. Also, a program using CSNBSAD adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. v CSNBSAD1 and CSNESAD1 allow the cipher text and plaintext to reside either in the caller’s primary address space or in a data space. This can allow you to decipher more data with one call. However, a program using CSNBSAD1 and CSNESAD1 does not adhere to the IBM CCA: Cryptographic API and may need to be modified prior to it running with other cryptographic products that follow this programming interface. For CSNBSAD1 and CSNESAD1, cipher_text_id and clear_text_id are access list entry token (ALET) parameters of the data spaces containing the cipher text and plaintext. 350 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Algorithm Decipher Format CALL 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, cipher_text_length, cipher_text, clear_text_length, clear_text, optional_data_length, optional_data) CALL CSNBSAD1( return_code, reason_code, exit_data_length, exit_data, rule_array_count, rule_array, key_length, key_identifier, key_parms_length, key_parms, block_size, initialization_vector_length, initialization_vector, chain_data_length, chain_data, cipher_text_length, cipher_text, clear_text_length, clear_text, optional_data_length, optional_data cipher_text_id clear_text_id) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer Chapter 6. Protecting Data 351 Symmetric Algorithm Decipher The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | exit_data_length || | Direction: Ignored Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | | exit_data || | Direction: Ignored Type: String This field is ignored. | rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 2, 3 or 4. rule_array Direction: Input Type: String An array of 8-byte keywords providing the processing control information. The keywords must be in contiguous storage, left-justified and padded on the right with blanks. Table 135. Symmetric Algorithm Decipher Rule Array Keywords Keyword Meaning Algorithm (one keyword, required) AES Specifies that the Advanced Encryption Standard (AES) algorithm is to be used. The block size is 16 bytes. The key length may be 16, 24, or 32 bytes. Processing Rule (optional - zero or one keyword) CBC Performs encryption in cipher block chaining (CBC) mode. The text length must be a multiple of the AES block size (16-bytes). This is the default value. ECB Performs encryption in electronic code book (ECB) mode. The text length must be a multiple of the AES block size (16-bytes). PKCS-PAD Deciphers with cipher block chaining and text length reduced to the original value. The ciphertext length must be an exact multiple of 16 bytes. Padding is removed from the plaintext. Key Rule (required) KEYIDENT This indicates that the value in the key_identifier parameter is either an internal key token or the label of a key token in the CKDS. The key must be a secure AES key, that is, enciphered under the current master key. ICV Selection (optional - zero or one keyword) 352 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Algorithm Decipher Table 135. Symmetric Algorithm Decipher Rule Array Keywords (continued) Keyword Meaning INITIAL This specifies that this is the first request of a sequence of chained requests, and indicates that the initialization vector should be taken from the initialization_vector parameter. This is the default value. CONTINUE This specifies that this request is part of a sequence of chained requests, and is not the first request in that sequence. The initialization vector will be taken from the work area identified in the chain_data parameter. This keyword is only valid for processing rule CBC. key_identifier_length Direction: Input | | | | Type: Integer The length of the key_identifier parameter. The length must be 64 bytes for an AES DATA Internal Key Token (version X’04’) or a CKDS label, or between the actual length of the token and 725 for an AES CIPHER Internal Key Token (version X’05’). key_identifier Direction: Input Type: String This specifies an internal secure AES token or the labelname of a secure AES token in the CKDS. Normal CKDS labelname syntax is required. The AES key identifier must be an encrypted key contained in an internal key token, where the key is enciphered under the AES master key. The key can be 128-, 192-, or 256-bits in length. key_parms_length Direction: Input Type: Integer The length of the key_parms parameter. This must be 0. key_parms Direction: Ignored Type: String This parameter is ignored. It is reserved for future use. block_size Direction: Input Type: Integer The block size for the cryptographic algorithm. AES requires the block size to be 16. initialization_vector_length Direction: Input Type: Integer The length of the initialization_vector parameter. The length should be equal to the block length for the algorithm specified. This parameter is ignored if the process rule is ECB. Chapter 6. Protecting Data 353 Symmetric Algorithm Decipher initialization_vector Direction: Input Type: String This parameter contains the initialization vector (IV) for CBC mode decryption, including CBC mode invoked using the PKCS-PAD keyword. This parameter is ignored if the process rule is ECB. For AES CBC mode decryption, the initialization vector length must be 16 bytes, the length of an AES block. The IV must be the same value used when the data was encrypted. chain_data_length Direction: Input/Output Type: Integer The length of the chain_data parameter. On input it contains the length of the buffer provided with parameter chain_data. On output, it is updated with the length of the data returned in the chain_data parameter. chain_data Direction: Input/Output Type: String A buffer that is used as a work area for sequences of chained symmetric algorithm decipher requests. When the keyword INITIAL is used, this is an output parameter and receives data that is needed when deciphering the next part of the input data. When the keyword CONTINUE is used, this is an input/output parameter; the value received as output from the previous call in the sequence is provided as input to this call, and in turn this call will return new chain_data that will be used as input on the next call. When CONTINUE is used, both the data (chain_data parameter) and the length (chain_data_length parameter) must be the same values that were received in these parameters as output on the preceding call to the service in the chained sequence. The exact content and layout of chain_data is not described. For AES CBC encryption, the field must be at least 32-bytes in length. For AES ECB encryption the field is not used and any length is acceptable including zero. cipher_text_length Direction: Input Type: Integer The length of the cipher text. The length must be a multiple of the algorithm block size. cipher_text Direction: Input Type: String The text to be deciphered. clear_text_length Direction: Input/Output Type: Integer On input, this parameter specifies the size of the storage pointed to by the clear_text parameter. On output, this parameter has the actual length of the text stored in the clear_text parameter. 354 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Algorithm Decipher If process rule PKCS-PAD is used, the clear text length will be less than the cipher text length since padding bytes are removed. clear_text Direction: Output Type: String The deciphered text the service returns. optional_data_length Direction: Input Type: Integer The length of the optional_data parameter. This parameter must be 0. optional_data Direction: Ignored Type: String Optional data required by a specified algorithm. cipher_text_id Direction: Input Type: Integer For CSNBSAD1 and CSNESAD1 only, the ALET of the dataspace in which the cipher_text parameter resides. clear_text_id Direction: Input Type: Integer For CSNBSAD1 and CSNESAD1 only, the ALET of the dataspace in which the clear_text parameter resides. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | | The Symmetric Algorithm Decipher - secure AES keys access control point controls the function of this service. Table 136. Symmetric Algorithm Decipher required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC Crypto Express2 Coprocessor Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC) IBM System z9 BC Chapter 6. Protecting Data 355 Symmetric Algorithm Decipher Table 136. Symmetric Algorithm Decipher required hardware (continued) Server Required cryptographic hardware Restrictions IBM System z10 EC Crypto Express2 Coprocessor Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC) IBM System z10 BC Crypto Express3 Coprocessor | | | z196 Crypto Express3 Coprocessor AES Variable-length Symmetric Internal Key Tokens require the Sep. 2011 or later licensed internal code (LIC). Symmetric Algorithm Encipher (CSNBSAE or CSNBSAE1 and CSNESAE or CSNESAE1) The symmetric algorithm encipher callable service enciphers data with the AES algorithm. Data is enciphered that has been deciphered in either CBC mode or ECB mode. The callable service names for AMODE(64) invocation are CSNESAE and CSNESAE1 Choosing between CSNBSAE and CSNBSAE1 or CSNESAE and CSNESAE1 CSNBSAE, CSNBSAE1, CSNESAE, and CSNESAE1 provide identical functions. When choosing which service to use, consider this: v CSNBSAE and CSNESAE require the cipher text and plaintext to reside in the caller’s primary address space. Also, a program using CSNBSAE adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. v CSNBSAE1 and CSNESAE1 allow the cipher text and plaintext to reside either in the caller’s primary address space or in a data space. This can allow you to encipher more data with one call. However, a program using CSNBSAE1 and CSNESAE1 does not adhere to the IBM CCA: Cryptographic API and may need to be modified prior to it running with other cryptographic products that follow this programming interface. For CSNBSAE1 and CSNESAE1, cipher_text_id and clear_text_id are access list entry token (ALET) parameters of the data spaces containing the cipher text and plaintext. 356 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Algorithm Encipher Format CALL 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, clear_text_length, clear_text, cipher_text_length, cipher_text, optional_data_length, optional_data) CALL CSNBSAE1( 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, clear_text_length, clear_text, cipher_text_length, cipher_text, optional_data_length, optional_data clear_text_id cipher_text_id) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer Chapter 6. Protecting Data 357 Symmetric Algorithm Encipher The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. | exit_data_length || | Direction: Ignored Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. | | exit_data || | Direction: Ignored Type: String This field is ignored. | rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 2, 3 or 4. rule_array Direction: Input Type: String This keyword provides control information to the callable service. 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. Table 137. Symmetric Algorithm Encipher Rule Array Keywords Keyword Meaning Algorithm (one keyword, required) AES Specifies that the Advanced Encryption Standard (AES) algorithm will be used. The block size is 16-bytes, and the key length may be 16-, 24-, or 32-bytes (128-, 192-, 256-bits). Processing Rule (optional - zero or one keyword) CBC Performs encryption in cipher block chaining (CBC) mode. The text length must be a multiple of the AES block size (16-bytes). This is the default value. ECB Performs encryption in electronic code book (ECB) mode. The text length must be a multiple of the AES block size (16-bytes). PKCS-PAD Performs encryption in cipher block chaining (CBC) mode, but the data is padded using PKCS padding rules. The length of the clear text data does not have to be a multiple of the cipher block length. The cipher text will be longer than the clear text by at least one byte, and up to 16-bytes. The PKCS padding method is described in “PKCS Padding Method” on page 877. Key Rule (required) 358 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Algorithm Encipher Table 137. Symmetric Algorithm Encipher Rule Array Keywords (continued) Keyword Meaning KEYIDENT This indicates that the value in the key_identifier parameter is either an internal key token or the label of a key token in the CKDS. The key must be a secure AES key, that is, enciphered under the current master key. ICV Selection (optional - zero or one keyword) INITIAL This specifies that this is the first request of a sequence of chained requests, and indicates that the initialization vector should be taken from the initialization_vector parameter. This is the default value. CONTINUE This specifies that this request is part of a sequence of chained requests, and is not the first request in that sequence. The initialization vector will be taken from the work area identified in the chain_data parameter. This keyword is only valid for processing rule CBC. key_identifier_length Direction: Input | | | | Type: Integer The length of the key_identifier parameter. The length must be 64 bytes for an AES DATA Internal Key Token (version X’04’) or a CKDS label, or between the actual length of the token and 725 for an AES CIPHER Internal Key Token (version X’05’). key_identifier Direction: Input Type: String This specifies an internal secure AES token or the labelname of a secure AES token in the CKDS. Normal CKDS labelname syntax is required. The AES key identifier must be an encrypted key contained in an internal key token, where the key is enciphered under the AES master key. The key can be 128-, 192-, or 256-bits in length. key_parms_length Direction: Input Type: Integer The length of the key_parms parameter in bytes. It must be set to 0. key_parms Direction: Ignored Type: String This parameter is ignored. It is reserved for future use. block_size Direction: Input Type: Integer The block size for the cryptographic algorithm. AES requires the block size to be 16. initialization_vector_length Chapter 6. Protecting Data 359 Symmetric Algorithm Encipher Direction: Input Type: Integer The length of the initialization_vector parameter in bytes. This parameter is ignored if the process rule is ECB. initialization_vector Direction: Input Type: String This parameter contains the initialization vector (IV) for CBC mode encryption, including the CBC mode invoked using the PKCS-PAD keyword. This parameter is ignored if the process rule is ECB. For AES CBC mode encryption, the initialization vector length must be 16 bytes, the length of an AES block. The same IV must be used when decrypting the data. chain_data_length Direction: Input/Output Type: Integer The length in bytes of the chain_data parameter. On input it contains the length of the buffer provided with parameter chain_data. On output, it is updated with the length of the data returned in the chain_data parameter. chain_data Direction: Input/Output Type: String A buffer that is used as a work area for sequences of chained symmetric algorithm encipher requests. When the keyword INITIAL is used, this is an output parameter and receives data that is needed when enciphering the next part of the input data. When the keyword CONTINUE is used, this is an input/output parameter; the value received as output from the previous call in the sequence is provided as input to this call, and in turn this call will return new chain_data that will be used as input on the next call. When CONTINUE is used, both the data (chain_data parameter) and the length (chain_data_length parameter) must be the same values that were received in these parameters as output on the preceding call to the service in the chained sequence. The exact content and layout of chain_data is not described. For AES CBC encryption, the field must be at least 32-bytes in length. For AES ECB encryption the field is not used and any length is acceptable including zero. clear_text_length Direction: Input Type: Integer The length of the clear text data in the clear_text parameter. Unless process rule PKCS-PAD is used, the length must be a multiple of the algorithm block size. The length must be 1 or greater. clear_text Direction: Input The text to be enciphered. cipher_text_length 360 z/OS V1R13 ICSF Application Programmer's Guide Type: String Symmetric Algorithm Encipher Direction: Input/Output Type: Integer On input, this parameter specifies the size of the storage pointed to by the cipher_text parameter. On output, this parameter has the actual length of the text stored in the buffer addressed by the cipher_text parameter. If process rule PKCS-PAD is used, the cipher text length will exceed the clear text length by at least one byte, and up to 16-bytes. For other process rules, the cipher text length will be equal to the clear text length. cipher_text Direction: Output Type: String The enciphered text the service returns. optional_data_length Direction: Input Type: Integer The length of the optional_data parameter. This parameter is reserved for future use. It must be set to 0. optional_data Direction: Ignored Type: String The optional data used in processing the request. This parameter is ignored. cipher_text_id Direction: Input Type: Integer For CSNBSAE1 and CSNESAE1 only, the ALET of the dataspace in which the cipher_text parameter resides. clear_text_id Direction: Input Type: Integer For CSNBSAE1 and CSNESAE1 only, the ALET of the dataspace in which the clear_text parameter resides. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. | | The Symmetric Algorithm Encipher - secure AES keys access control point controls the function of this service. Table 138. Symmetric Algorithm Encipher required hardware Server IBM Eserver zSeries 900 Required cryptographic hardware Restrictions This service is not supported. Chapter 6. Protecting Data 361 Symmetric Algorithm Encipher Table 138. Symmetric Algorithm Encipher required hardware (continued) Server Required cryptographic hardware IBM Eserver zSeries 990 Restrictions This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC Crypto Express2 Coprocessor Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). Crypto Express2 Coprocessor Secure AES key support requires the Nov. 2008 or later licensed internal code (LIC). IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor | | | z196 Crypto Express3 Coprocessor AES Variable-length Symmetric Internal Key Tokens require the Sep. 2011 or later licensed internal code (LIC). Symmetric Key Decipher (CSNBSYD or CSNBSYD1 and CSNESYD or CSNESYD1) Use the symmetric key decipher callable service to decipher data using one of the supported modes. ICSF supports several processing rules to decipher data. You choose the type of processing rule that the Symmetric Key Decipher callable service should use for block chaining. See “Modes of Operation” on page 325 for more information. 362 Processing Rule Purpose ANSI X9.23 For cipher block chaining. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES). The plaintext will be between 1 and 8 bytes shorter than the ciphertext. This process rule always pads the plaintext during encryption so that ciphertext produced is an exact multiple of the block size, even if the plaintext was already a multiple of the blocksize. CBC For cipher block chaining. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext. CBC-CS For cipher block chaining. The ciphertext can be any length. The plaintext will have the same length as the ciphertext. CFB Performs cipher feedback encryption with the segment size equal to the block size. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext. CFB-LCFB Performs cipher feedback encryption with the z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Decipher segment size set by the caller. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext. CUSP For cipher block chaining. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext. ECB Performs electronic code book encryption. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext. GCM Perform Galois/Counter mode decryption, which provides both confidentiality and authentication for the plaintext and authentication for the additional authenticated data (AAD). The ciphertext can be any length. The plaintext will have the same length as the ciphertext. Additionally, the authentication tag will be verified before any data is returned. IPS For cipher block chaining. The ciphertext can be any length. The plaintext will have the same length as the ciphertext. OFB Perform output feedback mode encryption. The ciphertext can be any length. The plaintext will have the same length as the ciphertext. PKCS-PAD For cipher block chaining. The ciphertext must be an exact multiple of the block size (8 bytes for DES and 16 bytes for AES). The plaintext will be between 1 and the blocksize (8 bytes for DES, 16 bytes for AES) bytes shorter than the ciphertext. This process rule always pads the ciphertext so that ciphertext produced is an exact multiple of the blocksize, even if the plaintext was already a multiple of the blocksize. The Advanced Encryption Standard (AES) and Data Encryption Standard (DES) are supported. AES encryption uses a 128-, 192-, or 256-bit key. DES encryption uses a 56-, 112-, or 168-bit key. See the processing rule descriptions for limitations. For each algorithm, certain processing rules are not allowed. See the rule_array parameter description for more information. All modes except ECB use an initial chaining vector (ICV) in their processing. All modes that utilize chaining produce a resulting chaining value called the output chaining vector (OCV). The application can pass the OCV as the ICV in the next decipher call. This results in record chaining. 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. The key may be specified as a clear key value, an internal clear key token, or the label name of a clear key or an encrypted key in the CKDS. Chapter 6. Protecting Data 363 Symmetric Key Decipher Choosing Between CSNBSYD and CSNBSYD1 CSNBSYD and CSNBSYD1 provide identical functions. When choosing which service to use, consider this: v CSNBSYD requires the ciphertext and plaintext to reside in the caller's primary address space. Also, a program using CSNBSYD adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNESYD. v CSNBSYD1 allows the ciphertext and plaintext to reside either in the caller's primary address space or in a data space. This can allow you to decipher more data with one call. However, a program using CSNBSYD1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to it running with other cryptographic products that follow this programming interface. For CSNBSYD1, cipher_text_id and clear_text_id are access list entry token (ALET) parameters of the data spaces containing the ciphertext and plaintext. The callable service name for AMODE(64) invocation is CSNESYD1. Format CALL CSNBSYD( 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, cipher_text_length, cipher_text, clear_text_length, clear_text, optional_data_length, optional_data) 364 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Decipher CALL CSNBSYD1( 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, cipher_text_length, cipher_text, clear_text_length, clear_text, optional_data_length, optional_data cipher_text_id clear_text_id) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Ignored | Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. exit_data Direction: Ignored | Type: String This field is ignored. rule_array_count Direction: Input Type: Integer Chapter 6. Protecting Data 365 Symmetric Key Decipher The number of keywords you supplied in the rule_array parameter. The value may be 1, 2, 3 or 4. rule_array Direction: Input Type: String An array of 8-byte keywords providing the processing control information. The keywords must be in contiguous storage, left-justified and padded on the right with blanks. Table 139. Symmetric Key Decipher Rule Array Keywords Keyword Meaning Algorithm (required) AES Specifies that the Advanced Encryption Standard (AES) algorithm is to be used. The block size is 16 bytes. The key length may be 16, 24, or 32 bytes. The chain_data field must be at least 32 bytes in length. The OCV is the first 16 bytes in the chain_data. AES does not support the CUSP, IPS, or X9.23 processing rules. DES Specifies that the Data Encryption Standard (DES) algorithm is to be used. The algorithm, DES or TDES, will be determined from the length of the key supplied. The key length may be 8, 16, or 24. The block size is 8 bytes. The chain_data field must be at least 16 bytes in length. The OCV is the first eight bytes in the chain_data. DES does not support the GCM processing rule. | | Processing Rule (optional) 366 CBC Performs cipher block chaining. The text length must be a multiple of the block size for the specified algorithm. CBC is the default value. CBC-CS CBC mode (cipher block chaining) with ciphertext stealing. Input text may be any length. CFB CFB mode (cipher feedback) that is compatible with IBM's Encryption Facility product. Input text may be any length. CFB-LCFB CFB mode (cipher feedback). This rule allows the value of s (the segment size) to be something other than the block size (s is set to the block size with the CFB processing rule). key_parms_length and key_parms are used to set the value of s. Input text may be any length. CUSP CBC mode (cipher block chaining) that is compatible with IBM's CUSP and PCF products. Input text may be any length. ECB Performs electronic code book encryption. The text length must be a multiple of the block size for the specified algorithm. GCM GCM (Galois/Counter Mode). key_parms_length and key_parms are used to indicate the length of the tag (the value t) on input and contain the tag on output. Additional Authenticated Data (AAD) is contained in optional_data_length and optional_data. Input text may be any length. GCM does not support chaining, so CONTINUE and FINAL are not allowed for the ICV Selection rule. IPS CBC mode (cipher block chaining) that is compatible with IBM's IPS product. Input text may be any length. z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Decipher Table 139. Symmetric Key Decipher Rule Array Keywords (continued) Keyword Meaning OFB OFB mode (output feedback). Input text may be any length. PKCS-PAD CBC mode (cipher block chaining) but the ciphertext must be an exact multiple of the block length (8 bytes for DES and 16 bytes for AES). The plaintext will be 1 to 8 bytes shorter for DES and 1 to 16 bytes shorter for AES than the ciphertext. X9.23 CBC mode (cipher block chaining) for 1 to 8 bytes of padding dropped from the output clear text. Key Rule (optional) KEY-CLR This specifies that the key parameter contains a clear key value. KEY-CLR is the default value. KEYIDENT This specifies that the key_identifier field will be an internal clear token, or the label name of a clear key or encrypted key in the CKDS. Normal CKDS labelname syntax is required. ICV Selection (optional) INITIAL This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value. INITIAL is not valid with processing rule GCM. CONTINUE This specifies taking the initialization vector from the output chaining vector contained in the work area to which the chain_data parameter points. CONTINUE is not valid for processing rules ECB, GCM, or X9.23. FINAL This specifies taking the initialization vector from the output chaining vector contained in the work area to which the chain_data parameter points. Using FINAL indicates that this call contains the last portion of data. FINAL is valid for processing rules CBC-CS, CFB, CFB-LCBF, and OFB. ONLY This specifies taking the initialization vector from the initialization_vector parameter and that the entirety of the data to be processed is in this single call. ONLY is valid for processing rules CBC-CS, CFB, CFB-LCFB, GCM, and OFB. key_identifier_length Direction: Input Type: Integer The length of the key_identifier parameter. For clear keys, the length is in bytes and includes only the value of the key. The maximum size is 256 bytes. For the KEYIDENT keyword, this parameter value must be 64. key_identifier Direction: Input Type: String For the KEY-CLR keyword, this specifies the cipher key. The parameter must be left justified. For the KEYIDENT keyword, this specifies an internal clear token, or the label name of a clear key or an encrypted key in the CKDS. Normal CKDS labelname syntax is required. KEYIDENT is valid with DES and AES. key_parms_length Chapter 6. Protecting Data 367 Symmetric Key Decipher Direction: Input Type: Integer The length of the key_parms parameter. v For the CFB-LCFB processing rule, this length must be 1. v For the GCM processing rule, this is the length in bytes of the authentication tag to be verified. Valid lengths are 4, 8, 12, 13, 14, 15, 16. Using a length of 4 or 8 is stringly discouraged. v For all other processing rules, this field is ignored. You must specify the same length used when enciphering the text. key_parms Direction: Input Type: String This parameter contains key-related parameters specific to the encryption algorithm and processing mode. v For the CFB-LCFB processing rule, this 1-byte field specifies the segment size in bytes. Valid values are 1 to the block size, inclusive. The block size is eight for DES and sixteen for AES. v For the GCM processing rule, this contains the authentication tag for the provided ciphertext (cipher_text parameter) and additional authenticated data (optional_data parameter). v For all other processing rules, this field is ignored. For the modes where key_parms is used, you must specify the same key_parms used when enciphering the text using the Symmetric Key Encipher. block_size Direction: Input Type: Integer This parameter contains the processing size of the text block in bytes. This value will be algorithm specific. Be sure to specify the same block size as used to encipher the text. initialization_vector_length Direction: Input Type: Integer The length of the initialization_vector parameter. This parameter is ignored for the ECB processing rule. For the GCM processing rule, NIST recommends a length of 12, but tolerates any non-zero length. For all other processing rules, the length should be equal to the block length for the algorithm specified. initialization_vector Direction: Input Type: String This initialization chaining value. You must use the same ICV that was used to encipher the data. This parameter is ignored for the ECB processing rule. chain_data_length Direction: Input/Output 368 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Symmetric Key Decipher The length of the chain_data parameter. On output, the actual length of the chaining vector will be stored in the parameter. This parameter is ignored if the ICV selection keyword is ONLY. chain_data Direction: Input/Output Type: String This field is used as a system work area for the chaining vector. Your application program must not change the data in this string. The chaining vector holds the output chaining vector from the caller. The direction is output if the ICV selection keyword is INITIAL. This parameter is ignored if the ICV selection keyword is ONLY. The mapping of the chain_data depends on the algorithm specified. For AES, the chain_data field must be at least 32 bytes in length. The OCV is in the first 16 bytes in the chain_data. For DES, chain_data field must be at least 16 bytes in length. cipher_text_length Direction: Input Type: Integer The length of the ciphertext. A zero value in the cipher_text_length parameter is not valid except with the GCM processing rule when performing a GMAC operation. The length must be a multiple of the algorithm block size for the CBC, ECB, and PKCS-PAD processing rules, but may be any length with the other processing rules. cipher_text Direction: Input Type: String The text to be deciphered. clear_text_length Direction: Input/Output Type: Integer On input, this parameter specifies the size of the storage pointed to by the clear_text parameter. On output, this parameter has the actual length of the text stored in the clear_text parameter. The clear_text parameter must be at least the same length as the cipher_text parameter, except for the PKCS-PAD and X9.23 processing rules, where the padding is automatically dropped on output. clear_text Direction: Output Type: String The deciphered text the service returns. optional_data_length Direction: Input Type: Integer The length of the optional_data parameter. For the GCM processing rule, this parameter contains the length of the Additional Authenticated Data (AAD). For all other processing rules, this field is ignored. Chapter 6. Protecting Data 369 Symmetric Key Decipher optional_data Direction: Input Type: String Optional data required by a specified algorithm or processing mode. For the GCM processing rule, this parameter contains the Additional Authenticated Data (AAD). For all other processing rules, this field is ignored. You must specify the same optional_data used when enciphering the text using Symmetric Key Encipher. cipher_text_id Direction: Input Type: Integer For CSNBSYD1 only, the ALET of the ciphertext to be deciphered. clear_text_id Direction: Input Type: Integer For CSNBSYD1 only, the ALET of the clear text supplied by the application. Usage Notes v SAF may be invoked to verify the caller is authorized to use the specified key label stored in the CKDS. v To use a CKDS encrypted key, the ICSF segment of the CSFKEYS class general resource profile associated with the specified key label must contain SYMCPACFWRAP(YES). v No pre- or post-processing exits are enabled for this service. v The master keys need to be loaded only when using this service with encrypted key labels. v The AES algorithm will use hardware if it is available. Otherwise, clear key operations will be performed in software. v AES has the same availability restrictions as triple-DES. v This service will fail if execution would cause destructive overlay of the cipher_text field. | | When the label of an encrypted key is specified for the key_identifier parameter, the appropriate access control point listed below must be enabled. | Table 140. Required access control points for Symmetric Key Decipher | Key algorithm Access control point | | AES Symmetric Key Encipher/Decipher - Encrypted AES keys | | | DES Symmetric Key Encipher/Decipher - Encrypted DES keys 370 z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Decipher Table 141. Symmetric Key Decipher required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions DES keyword is not supported. CFB-LCFB, GCM, and OFB processing rules are not supported. IBM Eserver zSeries CP Assist for 990 Cryptographic Functions IBM Eserver zSeries 890 CFB-LCFB, GCM, and OFB processing rules are not supported. IBM System z9 EC CP Assist for Cryptographic Functions CFB-LCFB, GCM, and OFB processing rules are not supported. CP Assist for Cryptographic Functions CFB-LCFB, GCM, and OFB processing rules are not supported. IBM System z9 BC | | | | | | IBM System z10 EC | | | | | | z196 IBM System z10 BC Crypto Express3 Coprocessor CP Assist for Cryptographic Functions Crypto Express3 Coprocessor Encrypted keys require CEX3C with the Nov. 2009 or later licensed internal code (LIC). CFB-LCFB, GCM, and OFB processing rules are not supported. Encrypted keys require CEX3C with the Nov. 2009 or later licensed internal code (LIC). Related Information You cannot overlap the plaintext and ciphertext fields. For example: pppppp cccccc is not supported. cccccc pppppp is not supported. ppppppcccccc is supported. P represents the plaintext and c represents the ciphertext. “Cipher Processing Rules” on page 874 discusses the cipher processing rules. Symmetric Key Encipher (CSNBSYE or CSNBSYE1 and CSNESYE or CSNESYE1) Use the symmetric key encipher callable service to encipher data using one of the supported modes. ICSF supports several processing rules to encipher data. You choose the type of processing rule that the Symmetric Key Encipher callable service should use for the block chaining. See “Modes of Operation” on page 325 for more information. Processing Rule Purpose ANSI X9.23 For cipher block chaining. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES). The plaintext will be Chapter 6. Protecting Data 371 Symmetric Key Encipher between 1 and 8 bytes shorter than the ciphertext. This process rule always pads the plaintext during encryption so that ciphertext produced is an exact multiple of the block size, even if the plaintext was already a multiple of the blocksize. 372 CBC For cipher block chaining. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext. CBC-CS For cipher block chaining. The ciphertext can be any length. The plaintext will have the same length as the ciphertext. CFB Performs cipher feedback encryption with the segment size equal to the block size. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext. CFB-LCFB Performs cipher feedback encryption with the segment size set by the caller. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext. CUSP For cipher block chaining. The ciphertext can be of any length. The plaintext will have the same length as the ciphertext. ECB Performs electronic code book encryption. The ciphertext must be an exact multiple of the block size for the specified algorithm (8 bytes for DES, 16 bytes for AES). The plaintext will have the same length as the ciphertext. GCM Perform Galois/Counter mode decryption, which provides both confidentiality and authentication for the plaintext and authentication for the additional authenticated data (AAD). The ciphertext can be any length. The plaintext will have the same length as the ciphertext. Additionally, the authentication tag will be verified before any data is returned. IPS For cipher block chaining. The ciphertext can be any length. The plaintext will have the same length as the ciphertext. OFB Perform output feedback mode encryption. The ciphertext can be any length. The plaintext will have the same length as the ciphertext. PKCS-PAD For cipher block chaining. The ciphertext must be an exact multiple of the block size (8 bytes for DES and 16 bytes for AES). The plaintext will be between 1 and the blocksize (8 bytes for DES, 16 bytes for AES) bytes shorter than the ciphertext. This process rule always pads the ciphertext so that ciphertext produced is an exact multiple of the blocksize, even if the plaintext was already a multiple of the blocksize. z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Encipher The Advanced Encryption Standard (AES) and Data Encryption Standard (DES) are supported. AES encryption uses a 128-, 192-, or 256-bit key. The CBC, CBC-CS, CFB, CFB-LCFB, ECB, GCM, OFB, and XTS-AES modes are supported. All modes except ECB and XTS-AES use an initial chaining vector (ICV) in their processing. All modes that tolerate chaining produce 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. 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. The key may be specified as a clear key value, an internal clear key token, or the label name of a clear key or an encrypted key in the CKDS. Choosing between CSNBSYE and CSNBSYE1 CSNBSYE and CSNBSYE1 provide identical functions. When choosing which service to use, consider this: v CSNBSYE requires the cleartext and ciphertext to reside in the caller's primary address space. Also, a program using CSNBSYE adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNESYE. v CSNBSYE1 allows the cleartext and ciphertext to reside either in the caller's primary address space or in a data space. This can allow you to encipher more data with one call. However, a program using CSNBSYE1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified prior to it running with other cryptographic products that follow this programming interface. For CSNBSYE1, clear_text_id and cipher_text_id are access list entry token (ALET) parameters of the data spaces containing the cleartext and ciphertext. The callable service name for AMODE(64) invocation is CSNESYE1. Chapter 6. Protecting Data 373 Symmetric Key Encipher Format CALL CSNBSYE( 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, clear_text_length, clear_text, cipher_text_length, cipher_text, optional_data_length, optional_data) CALL CSNBSYE1( 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, clear_text_length, clear_text, cipher_text_length, cipher_text, optional_data_length, optional_data, clear_text_id, cipher_text_id) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output 374 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Symmetric Key Encipher The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Ignored | Type: Integer This field is ignored. It is recommended to specify 0 for this parameter. exit_data Direction: Ignored | Type: String This field is ignored. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 1, 2, 3 or 4. rule_array Direction: Input Type: String An array of 8-byte keywords providing the processing control information. The keywords must be in contiguous storage, left-justified and padded on the right with blanks. Table 142. Symmetric Key Encipher Rule Array Keywords Keyword Meaning Algorithm (required) AES Specifies that the Advanced Encryption Standard (AES) algorithm is to be used. The block size is 16 bytes. The key length may be 16, 24, or 32 bytes. The chain_data field must be at least 32 bytes in length. The OCV is the first 16 bytes in the chain_data. AES does not support the CUSP, IPS, or X9.23 processing rules. DES Specifies that the Data Encryption Standard (DES) algorithm is to be used. The algorithm, DES or TDES, will be determined from the length of the key supplied. The key length may be 8, 16, or 24. The block size is 8 bytes. The chain_data field must be at least 16 bytes in length. The OCV is the first eight bytes in the chain_data. DES does not support the GCM processing rule. | | Processing Rule (optional) CBC CBC mode (cipher block chaining). The text length must be a multiple of the block size for the specified algorithm. CBC is the default value. CBC-CS CBC mode (cipher block chaining) with ciphertext stealing. Input text may be any length. CFB CFB mode (cipher feedback) that is compatible with IBM's Encryption Facility product. Input text may be any length. Chapter 6. Protecting Data 375 Symmetric Key Encipher Table 142. Symmetric Key Encipher Rule Array Keywords (continued) Keyword Meaning CFB-LCFB CFB mode (cipher feedback). This rule allows the value of s (the segment size) to be something other than the block size (s is set to the block size with the CFB processing rule). The key_parms_length and key_parms parameters are used to set the value of s. Input text may be any length. CUSP CBC mode (cipher block chaining) that is compatible with IBM's CUSP and PCF products. Input text may be any length. ECB ECB mode (electronic codebook). The text length must be a multiple of the block size for the specified algorithm. GCM GCM mode (Galois/Counter Mode). The key_parms_length and key_parms parameters are used to indicate the length of the tag (the value t) on input and contain the tag on output. Additional Authenticated Data (AAD) is contained in the optional_data_length and optional_data parameters. Input text may be any length. IPS CBC mode (cipher block chaining) that is compatible with IBM's IPS product. Input text may be any length. OFB OFB mode (output feedback). Input text may be any length. PKCS-PAD CBC mode (cipher block chaining) not necessarily in exact multiples of the block length (8 bytes for DES and 16 bytes for AES). PKCS-PAD always pads the plaintext so that the ciphertext produced is an exact multiple of the block length and longer than the plaintext. X9.23 CBC mode (cipher block chaining) for 1 to 8 bytes of padding added according to ANSI X9.23. Input text may be any length. Key Rule (optional) KEY-CLR This specifies that the key parameter contains a clear key value. KEY-CLR is the default. KEYIDENT This specifies that the key_identifier field will be an internal clear token, or the label name of a clear key or encrypted key in the CKDS. Normal CKDS labelname syntax is required. ICV Selection (optional) 376 INITIAL This specifies taking the initialization vector from the initialization_vector parameter. INITIAL is the default value. INITIAL is not valid with processing rule GCM. CONTINUE This specifies taking the initialization vector from the output chaining vector contained in the work area to which the chain_data parameter points. CONTINUE is not valid for processing rules ECB, GCM, or X9.23. FINAL This specifies taking the initialization vector from the output chaining vector contained in the work area to which the chain_data parameter points. Using FINAL indicates that this call contains the last portion of data. FINAL is valid for processing rules CBC-CS, CFB, CFB-LCBF, and OFB. ONLY This specifies taking the initialization vector from the initialization_vector parameter and that the entirety of the data to be processed is in this single call. ONLY is valid for processing rules CBC-CS, CFB, CFB-LCFB, GCM, and OFB. z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Encipher key_identifier_length Direction: Input Type: Integer The length of the key_identifier parameter. For clear keys, the length is in bytes and includes only the value of the key. For the KEYIDENT keyword, this parameter value must be 64. key_identifier Direction: Input Type: String For the KEY-CLR keyword, this specifies the cipher key. The parameter must be left justified. For the KEYIDENT keyword, this specifies a internal clear token, or the label name of a clear key or an encrypted key in the CKDS. Normal CKDS label name syntax is required. key_parms_length Direction: Input Type: Integer The length of the key_parms parameter. v For the CFB-LCFB processing rule, this length must be 1. v For the GCM processing rule, this is the length in bytes of the authentication tag to be generated. Valid lengths are 4, 8, 12, 13, 14, 15, 16. Using a length of 4 or 8 is strongly discouraged. v For all other processing rules, this field is ignored. When deciphering the text, you must specify this same length. key_parms Direction: Input/Output Type: String This parameter contains key-related parameters specific to the encryption algorithm and processing mode. v For the CFB-LCFB processing rule, this 1-byte field specifies the segment size in bytes. Valid values are 1 to the blocksize, inclusive. The blocksize is eight for DES and sixteen for AES. v For the GCM processing rule, this will contain the generated authentication tag for the provided plaintext (plain_text parameter) and additional authenticated data (optional_data parameter). v For all other processing rules, this field is ignored. For the modes where key_parms is used, you must specify the same key_parms when deciphering the text using the Symmetric Key Decipher callable service. block_size Direction: Input Type: Integer This parameter contains the processing size of the text block in bytes. This value will be algorithm specific. Chapter 6. Protecting Data 377 Symmetric Key Encipher initialization_vector_length Direction: Input Type: Integer The length of the initialization_vector parameter. This parameter is ignored for the ECB processing rule. For the GCM processing rule, NIST recommends a length of 12, but tolerates any non-zero length. For all other processing rules, the length should be equal to the block length for the algorithm specified. initialization_vector Direction: Input Type: String This initialization chaining value. You must use the same ICV to decipher the data. This parameter is ignored for the ECB processing rule. chain_data_length Direction: Input/Output Type: Integer The length of the chain_data parameter. On output, the actual length of the chaining vector will be stored in the parameter. This parameter is ignored if the ICV selection keyword in ONLY. chain_data Direction: Input/Output Type: String This field is used as a system work area for the chaining vector. Your application program must not change the data in this string. The chaining vector holds the output chaining vector from the caller. The direction is output if the ICV selection keyword is INITIAL. This parameter is ignored if the ICV selection keyword in ONLY. The mapping of the chain_data depends on the algorithm specified. For AES, the chain_data field must be at least 32 bytes in length. The OCV is in the first 16 bytes in the chain_data. For DES, the chain_data field must be at least 16 bytes in length. clear_text_length Direction: Input Type: Integer The length of the cleartext. A zero value in the clear_text_length parameter is not valid except with the GCM processing rule when performing a GMAC operation. The length must be a multiple of the algorithm block size for the CBC, ECB, and PKCS-PAD processing rules, but may be any length with the other processing rules. For the processing rules that support partial blocks (or segments for CFB-LCFB), it is recommended that is the final block (or segment) be the only one that is partial. Having a partial block in the middle is not a supported operation as defined by the standards documents and may not be portable to other encryption systems. clear_text Direction: Input The text to be enciphered. 378 z/OS V1R13 ICSF Application Programmer's Guide Type: String Symmetric Key Encipher cipher_text_length Direction: Input/Output Type: Integer On input, this parameter specifies the size of the storage pointed to by the cipher_text parameter. On output, this parameter has the actual length of the text stored in the buffer addressed by the cipher_text parameter. cipher_text Direction: Output Type: String The enciphered text the service returns. optional_data_length Direction: Input Type: Integer The length of the optional_data parameter. For the GCM processing rule, this parameter contains the length of the Additional Authenticated Data (AAD), and may be any length, including zero. For all other processing rules, this field is ignored. optional_data Direction: Input Type: String Optional data required by a specified algorithm. Optional data required by a specified algorithm or processing mode. For the GCM processing rule, this parameter contains the Additional Authenticated Data (AAD). For all other processing rules, this field is ignored. You must specify the same optional_data when deciphering the text using Symmetric Key Decipher. clear_text_id Direction: Input Type: Integer For CSNBSYE1 only, the ALET of the clear text to be enciphered. cipher_text_id Direction: Input Type: Integer For CSNBSYE1 only, the ALET of the ciphertext that the application supplied. Usage Notes v SAF may be invoked to verify the caller is authorized to use the specified key label stored in the CKDS. v To use a CKDS encrypted key, the ICSF segment of the CSFKEYS class general resource profile associated with the specified key label must contain SYMCPACFWRAP(YES). v No pre- or post-processing exits are enabled for this service. v The master keys need to be loaded only when using this service with the encrypted key labels. Chapter 6. Protecting Data 379 Symmetric Key Encipher v The AES algorithm will use hardware if it is available. Otherwise, clear key operations will be performed in software. v AES has the same availability restrictions as triple-DES. v This service will fail if execution would cause destructive overlay of the clear_text field. | | When the label of an encrypted key is specified for the key_identifier parameter, the appropriate access control point listed below must be enabled. | Table 143. Required access control points for Symmetric Key Encipher | Key algorithm Access control point | | AES Symmetric Key Encipher/Decipher - Encrypted AES keys | | | DES Symmetric Key Encipher/Decipher - Encrypted DES keys Table 144. Symmetric Key Encipher required hardware Server Required cryptographic hardware IBM Eserver zSeries 900 Restrictions DES keyword is not supported. CFB-LCFB, GCM, and OFB processing rules are not supported. IBM Eserver zSeries CP Assist for 990 Cryptographic Functions IBM Eserver zSeries 890 CFB-LCFB, GCM, and OFB processing rules are not supported. IBM System z9 EC CP Assist for Cryptographic Functions CFB-LCFB, GCM, and OFB processing rules are not supported. CP Assist for Cryptographic Functions CFB-LCFB, GCM, and OFB processing rules are not supported. IBM System z9 BC | | | | | | IBM System z10 EC | | | | | | z196 IBM System z10 BC Crypto Express3 Coprocessor CCP Assist for Cryptographic Functions Crypto Express3 Coprocessor Encrypted keys require the CEX3C with the Nov. 2009 or later licensed internal code (LIC). CFB-LCFB, GCM, and OFB processing rules are not supported. Encrypted keys require the CEX3C with the Nov. 2009 or later licensed internal code (LIC). Related Information You cannot overlap the plaintext and ciphertext fields. For example: 380 pppppp cccccc is not supported. cccccc pppppp is not supported. z/OS V1R13 ICSF Application Programmer's Guide Symmetric Key Encipher ppppppcccccc is supported. P represents the plaintext and c represents the ciphertext. The method used to produce the OCV is the same with the CBC and X9.23 processing rules. However, that method is different from the method used by the CUSP and IPS processing rules. “Cipher Processing Rules” on page 874 discusses the cipher processing rules. Chapter 6. Protecting Data 381 Symmetric Key Encipher 382 z/OS V1R13 ICSF Application Programmer's Guide Chapter 7. Verifying Data Integrity and Authenticating Messages ICSF provides several 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 Chapter 9, “Using Digital Signatures,” on page 511) to authenticate messages. The choice of callable service 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 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, such as the modification detection code process. The callable services are described in the following topics: v “HMAC Generate (CSNBHMG or CSNBHMG1 and CSNEHMG or CSNEHMG1)” on page 385 v “HMAC Verify (CSNBHMV or CSNBHMV1 and CSNEHMV or CSNEHMV1)” on page 389 v “MAC Generate (CSNBMGN or CSNBMGN1 and CSNEMGN or CSNEMGN1)” on page 393 v “MAC Verify (CSNBMVR or CSNBMVR1 and CSNEMVR or CSNEMVR1)” on page 398 v “MDC Generate (CSNBMDG or CSNBMDG1 and CSNEMDG or CSNEMDG1)” on page 404 v “One-Way Hash Generate (CSNBOWH or CSNBOWH1 and CSNEOWH or CSNEOWH1)” on page 408 v “Symmetric MAC Generate (CSNBSMG or CSNBSMG1 and CSNESMG or CSNESMG1)” on page 413 v “Symmetric MAC Verify (CSNBSMV or CSNBSMV1 and CSNESMV or CSNESMV1)” on page 417 How MACs are Used When a message is sent, an application program can generate an authentication code for it using the MAC generation callable service. ICSF supports the ANSI X9.9-1 basic procedure and both the ANSI X9.19 basic procedure and optional double key MAC procedure. The service computes the text of the message authentication code using the algorithm and a key. The ANSI X9.9-1 or ANSI X9.19 basic procedures accept either a single-length MAC generation (MAC) key or a data-encrypting (DATA) key, and the message text. The ANSI X9.19 optional double key MAC procedure accepts a double-length MAC key and the message text. The message text may be in clear or encrypted form. The originator of the message sends the MAC with the message text. When the receiver gets the message, an application program calls the MAC verification callable service. The callable service generates a MAC using the same algorithm as the sender and either the single-length or double-length MAC © Copyright IBM Corp. 1997, 2011 383 verification key, the single-length or double-length MAC generation key, or DATA key, and the message text. The MACVER callable service 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 that the message is either bogus or has been altered. The newly computed MAC is not revealed outside the cryptographic feature. 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 generation and MAC verification services requires the use of MAC and MACVER keys in these services, respectively. To accomplish this, the originator of the message generates a MAC/MACVER key pair, uses the MAC key in the MAC generation service, 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 only receive a MACVER key and can use only this key in the MAC verification service. 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 DATA keys are used in the MAC generation service, or if DATA or MAC keys are used in the MAC verification service. 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 that the data has not been altered during transmission. For example, an active eavesdropper can tap into a transmission line, and interject bogus messages or alter sensitive data being transmitted. If the data is accompanied by a MAC, the recipient can use a callable service to detect whether the data has been altered. Since both the sender and receiver share a secret key, the receiver can use a callable service 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 may be accepted as unaltered. Furthermore, since 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 Are Used Hashing functions include the MDC and one-way hash. You need to hash text before submitting it to digital signature services (see Chapter 9, “Using Digital Signatures,” on page 511). How MDCs Are Used When a message is sent, an application program can generate a modification detection code for it using the MDC generation callable service. The service computes the modification detection code, a 128-bit value, using a one-way cryptographic function and the message text (which itself may be in clear or encrypted form). The originator of the message ensures that the MDC is transmitted 384 z/OS V1R13 ICSF Application Programmer's Guide with integrity to the intended receiver of the message. For example, the MDC could be published in a reliable source of public information. When the receiver gets the message, an application program calls the MDC callable service. The callable service generates an MDC by using the same one-way cryptographic function and the message text. The application program can compare the new MDC with the one generated by the originator of the message. If the MDCs match, the receiver knows that the message was not altered. In a similar manner, MDCs can be used to ensure the integrity of data stored on the system or on removable media, such as tape. By using 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 that the data has not been altered during transmission. It is easy to compute an MDC for specific data, yet hard to find data that will result in a given MDC. In effect, the problem of ensuring the integrity of a large file is reduced to ensuring the integrity of a 128-bit 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. Once an MDC has been established for a file, the MDC generation callable service can be run at any later time on the file. The resulting MDC can be compared with the stored MDC to detect deliberate or inadvertent modification. SHA-1 is a FIPS standard required for DSS. MD5 is a hashing algorithm used to derive Message Digests in Digital Signature applications. HMAC Generate (CSNBHMG or CSNBHMG1 and CSNEHMG or CSNEHMG1) Use the HMAC generate callable service to generate a keyed hash message authentication code (MAC) for the text string provided as input. The callable service names for AMODE(64) are CSNEHMG and CSFEHMG1. Choosing Between CSNBHMG and CSNBHMG1 CSNBHMG and CSNBHMG1 provide identical functions. When choosing which service to use, consider the following: v CSNBHMG requires the application-supplied text to reside in the caller’s primary address space. v CSNBHMG1 allows the application-supplied text to reside either in the caller’s primary address space or in a data space. This can allow you to process more data with one call. For CSNBHMG1, text_id_in is an access list entry token (ALET) parameter of the data space containing the application-supplied text. Chapter 7. Verifying Data Integrity and Authenticating Messages 385 HMAC Generate Format CALL 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 ) CALL CSNBHMG1( 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, text_id_in ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. 386 z/OS V1R13 ICSF Application Programmer's Guide HMAC Generate exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 2 or 3. rule_array Direction: Input Type: String Keywords that provide control information to the callable service. 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. Table 145. Keywords for HMAC Generate Control Information Keyword Meaning Token algorithm (One required) HMAC Specifies the HMAC algorithm to be used to generate the MAC. Hash method (One required) SHA-1 Specifies the FIPS-198 HMAC procedure using the SHA-1 hash method, a symmetric key and text to produce a 20-byte (160-bit) MAC. SHA-224 Specifies the FIPS-198 HMAC procedure using the SHA-224 hash method, a symmetric key and text to produce a 28-byte (224-bit) MAC. SHA-256 Specifies the FIPS-198 HMAC procedure using the SHA-256 hash method, a symmetric key and text to produce a 32-byte (256-bit) MAC. SHA-384 Specifies the FIPS-198 HMAC procedure using the SHA-384 hash method, a symmetric key and text to produce a 48-byte (384-bit) MAC. SHA-512 Specifies the FIPS-198 HMAC procedure using the SHA-512 hash method, a symmetric key and text to produce a 64-byte (512-bit) MAC. Segmenting Control (One optional) FIRST First call, this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; segmenting is not employed by the application program. This is the default value. key_identifier_length Direction: Input Type: Integer Chapter 7. Verifying Data Integrity and Authenticating Messages 387 HMAC Generate 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 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. The value must be 128 bytes. chaining_vector Direction: Input/Output Type: String An 128-byte string that ICSF uses 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 callable service returns the MAC value if the segmenting rule is ONLY or LAST. text_id_in Direction: Input Type: Integer For CSNBHMG1 only, the ALET of the text for which the MAC is generated. 388 z/OS V1R13 ICSF Application Programmer's Guide HMAC Generate Usage Notes This table lists the access control points in the ICSF role that control the function for this service. Table 146. HMAC Generate Access Control Points Hash method Access control point SHA-1 HMAC Generate - SHA-1 SHA-224 HMAC Generate - SHA-224 SHA-256 HMAC Generate - SHA-256 SHA-384 HMAC Generate - SHA-384 SHA-512 HMAC Generate - SHA-512 This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 147. HMAC generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC | | z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor HMAC keys not supported. Crypto Express3 Coprocessor HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). HMAC Verify (CSNBHMV or CSNBHMV1 and CSNEHMV or CSNEHMV1) Use the HMAC verify callable service to verify a keyed hash message authentication code (MAC) for the text string provided as input. The callable service names for AMODE(64) are CSNEHMV and CSFEHMV1. Choosing Between CSNBHMV and CSNBHMV1 CSNBHMV and CSNBHMV1 provide identical functions. When choosing which service to use, consider the following: v CSNBHMV requires the application-supplied text to reside in the caller’s primary address space. v CSNBHMV1 allows the application-supplied text to reside either in the caller’s primary address space or in a data space. This can allow you to process more Chapter 7. Verifying Data Integrity and Authenticating Messages 389 HMAC Verify data with one call. For CSNBHMV1, text_id_in is an access list entry token (ALET) parameter of the data space containing the application-supplied text. Format CALL 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 ) CALL CSNBHMV1( 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, text_id_in ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output 390 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer HMAC Verify The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you supplied in the rule_array parameter. The value may be 2 or 3. rule_array Direction: Input Type: String Keywords that provide control information to the callable service. 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. Table 148. Keywords for HMAC Verify Control Information Keyword Meaning Token algorithm (One required) HMAC Specifies the HMAC algorithm to be used to verify the MAC. Hash method (One required) SHA-1 Specifies the FIPS-198 HMAC procedure using the SHA-1 hash method, a symmetric key and text to produce a 20-byte (160-bit) MAC. SHA-224 Specifies the FIPS-198 HMAC procedure using the SHA-224 hash method, a symmetric key and text to produce a 28-byte (224-bit) MAC. SHA-256 Specifies the FIPS-198 HMAC procedure using the SHA-256 hash method, a symmetric key and text to produce a 32-byte (256-bit) MAC. SHA-384 Specifies the FIPS-198 HMAC procedure using the SHA-384 hash method, a symmetric key and text to produce a 48-byte (384-bit) MAC. SHA-512 Specifies the FIPS-198 HMAC procedure using the SHA-512 hash method, a symmetric key and text to produce a 64-byte (512-bit) MAC. Segmenting Control (optional) FIRST First call, this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; segmenting is not employed by the application program. This is the default value. Chapter 7. Verifying Data Integrity and Authenticating Messages 391 HMAC Verify 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 MAC is generated. chaining_vector_length Direction: Input/Output Type: Integer The length of the chaining_vector in bytes. The value must be 128 bytes. chaining_vector Direction: Input/Output Type: String An 128-byte string that ICSF uses 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. text_id_in Direction: Input Type: Integer For CSNBHMV1 only, the ALET of the text for which the MAC is generated. 392 z/OS V1R13 ICSF Application Programmer's Guide HMAC Verify Usage Notes This table lists the access control points in the ICSF role that control the function for this service. Table 149. HMAC Verify Access Control Points Hash method Access control point SHA-1 HMAC Generate - SHA-1 SHA-224 HMAC Generate - SHA-224 SHA-256 HMAC Generate - SHA-256 SHA-384 HMAC Generate - SHA-384 SHA-512 HMAC Generate - SHA-512 This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 150. HMAC generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries 900 This service is not supported. IBM Eserver zSeries 990 This service is not supported. IBM Eserver zSeries 890 IBM System z9 EC This service is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC | | z196 Crypto Express2 Coprocessor This service is not supported. Crypto Express3 Coprocessor HMAC keys not supported. Crypto Express3 Coprocessor HMAC key support requires the Nov. 2010 or later licensed internal code (LIC). MAC Generate (CSNBMGN or CSNBMGN1 and CSNEMGN or CSNEMGN1) Use the MAC generate callable service to generate a 4-, 6-, or 8-byte message authentication code (MAC) for an application-supplied text string. You can specify that the callable service uses either the ANSI X9.9-1 procedure or the ANSI X9.19 optional double key MAC procedure to compute the MAC. For the ANSI X9.9-1 procedure you identify either a MAC generate key or a DATA key, and the message text. For the ANSI X9.19 optional double key MAC procedure, you identify a double-length MAC key and the message text. The MAC generate callable service also supports the padding rules specified in the EMV Specification and ISO 16609. For the EMV MAC procedure, you identify a single- or double-length MAC key and the message text. For the ISO 16609 procedure you identify a double-length MAC or DATA key and the message text. Chapter 7. Verifying Data Integrity and Authenticating Messages 393 MAC Generate Choosing Between CSNBMGN and CSNBMGN1 CSNBMGN and CSNBMGN1 provide identical functions. When choosing which service to use, consider the following: v CSNBMGN requires the application-supplied text to reside in the caller's primary address space. Also, a program using CSNBMGN adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNEMGN. v CSNBMGN1 allows the application-supplied text to reside either in the caller's primary address space or in a data space. This can allow you to process more data with one call. However, a program using CSNBMGN1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface, and may need to be modified before it can run with other cryptographic products that follow this programming interface. The callable service name for AMODE(64) invocation is CSNEMGN1. For CSNBMGN1, text_id_in is an access list entry token (ALET) parameter of the data space containing the application-supplied text. Format CALL CSNBMGN( return_code, reason_code, exit_data_length, exit_data, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector, mac ) CALL CSNBMGN1( return_code, reason_code, exit_data_length, exit_data, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector, mac, text_id_in ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code 394 z/OS V1R13 ICSF Application Programmer's Guide MAC Generate Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier Direction: Input/Output Type: String The 64-byte key label or internal key token that identifies a single or double-length MAC generate key, a DATAM key, or a single-length DATA 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. The maximum length of text is 214783647 bytes. If the text_length is not a multiple of 8 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. Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced. text Direction: Input Type: String The application-supplied text for which the MAC is generated. rule_array_count Direction: Input Type: Integer The number of keywords specified in the rule_array parameter. The value can be 0, 1, 2, or 3. rule_array Direction: Input Type: Character string Chapter 7. Verifying Data Integrity and Authenticating Messages 395 MAC Generate Zero to three keywords that provide control information to the callable service. The keywords are shown in Table 151. 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. Table 151. Keywords for MAC generate Control Information Keyword Meaning MAC Process Rules (optional) EMVMAC EMV padding rule with a single-length MAC key. The key_identifier parameter must identify a single-length MAC or a single-length DATA key. The text is always padded with 1 to 8 bytes so that the resulting text length is a multiple of 8 bytes. The first pad character is X'80'. The remaining 0 to 7 pad characters are X'00'. EMVMACD EMV padding rule with a double-length MAC key. The key_identifier parameter must identify a double-length MAC key. The padding rules are the same as for EMVMAC. X9.19OPT ANSI X9.19 optional double key MAC procedure. The key_identifier parameter must identify a double-length MAC key. The padding rules are the same as for X9.9-1. X9.9-1 ANSI X9.9-1 and X9.19 basic procedure. The key_identifier parameter must identify a single-length MAC or a single-length DATA key. X9.9-1 causes the MAC to be computed from all of the data. The text is padded only if the text length is not a multiple of 8 bytes. If padding is required, the pad character X'00' is used. This is the default value. TDES-MAC ISO 16609 procedure. The key_identifier must identify a double-length MAC or a double-length DATA key. The text is padded only if the text length is not a multiple of 8 bytes. Segmenting Control (optional) FIRST First call, this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; segmenting is not employed by the application program. This is the default value. MAC Length and Presentation (optional) 396 HEX-8 Generates a 4-byte MAC value and presents it as 8 hexadecimal characters. HEX-9 Generates a 4-byte MAC value and presents it as 2 groups of 4 hexadecimal characters with a space between the groups. MACLEN4 Generates a 4-byte MAC value. This is the default value. MACLEN6 Generates a 6-byte MAC value. MACLEN8 Generates an 8-byte MAC value. z/OS V1R13 ICSF Application Programmer's Guide MAC Generate chaining_vector Direction: Input/Output Type: String An 18-byte string that ICSF uses 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 callable service returns the MAC value if the segmenting rule is ONLY or LAST. Allocate an 8-byte field for MAC values of 4 bytes, 6 bytes, 8 bytes, or HEX-8. Allocate a 9-byte MAC field if you specify HEX-9 in the rule_array parameter. text_id_in Direction: Input Type: Integer For CSNBMGN1/CSNEMGN1 only, the ALET of the text for which the MAC is generated. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. CCF Systems: To use a DATA key, the NOCV-enablement keys must be present in the CKDS. Using a DATA key instead of a MAC generate key in this service substantially increases the path length for generating the MAC. To calculate a MAC in one call, specify the ONLY keyword for segmenting control for the rule_array parameter. For two or more calls, specify the FIRST keyword for the first input block, the MIDDLE keyword for intermediate blocks (if any), and the LAST keyword for the last block. For a given text string, the resulting MAC is the same whether the text is segmented or not. | The MAC Generate access control point controls the function of this service. The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 7. Verifying Data Integrity and Authenticating Messages 397 MAC Generate Table 152. MAC generate required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions ICSF routes the request to a PCI Cryptographic Coprocessor if the control vector in the supplied key identifier cannot be processed on the Cryptographic Coprocessor Feature. If no PCI Cryptographic Coprocessor is online in this case, the request fails. The request must meet the following restrictions: v The MAC Process Rule is X9.19OPT or EMVMACD. v The MAC key is a valid double-length MAC generate key. v The text_length must be less than or equal to 4K bytes for the FIRST and MIDDLE keywords, and the text length must be a multiple of 8 bytes. v The text_length on the final call (ONLY or LAST) can not be greater than 4K including padding. TDES-MAC not supported. IBM Eserver zSeries PCI X Cryptographic Coprocessor 990 TDES-MAC not supported. IBM Eserver zSeries Crypto Express2 Coprocessor 890 IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express2 Coprocessor Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Related Information For more information about MAC processing rules and segmenting control, refer to IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface Reference. The MAC verification callable service is described in “MAC Verify (CSNBMVR or CSNBMVR1 and CSNEMVR or CSNEMVR1).” MAC Verify (CSNBMVR or CSNBMVR1 and CSNEMVR or CSNEMVR1) Use the MAC verify callable service to verify a 4-, 6-, or 8-byte message authentication code (MAC) for an application-supplied text string. You can specify that the callable service uses either the ANSI X9.9-1 procedure or the ANSI X9.19 optional double key MAC procedure to compute the MAC. For the ANSI X9.9-1 398 z/OS V1R13 ICSF Application Programmer's Guide MAC Verify procedure you identify either a MAC verify key, a MAC generation key, or a DATA key, and the message text. For the ANSI X9.19 optional double key MAC procedure, you identify either a double-length MAC verify key or a double-length MAC generation key and the message text. The cryptographic feature compares the generated MAC with the one sent with the message. A return code indicates whether the MACs are the same. If the MACs are the same, the receiver knows the message was not altered. The generated MAC never appears in storage is not revealed outside the cryptographic feature. The MAC verify callable service also supports the padding rules specified in the EMV Specification and ISO 16609. For the EMV MAC procedure, you identify a single- or double-length MAC key and the message text. For the ISO 16609 procedure you identify a double-length MAC or DATA key and the message text. Choosing Between CSNBMVR and CSNBMVR1 CSNBMVR and CSNBMVR1 provide identical functions. When choosing which service to use, consider the following: v CSNBMVR requires the application-supplied text to reside in the caller's primary address space. Also, a program using CSNBMVR adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNEMVR. v CSNBMVR1 allows the application-supplied text to reside either in the caller's primary address space or in a data space. This can allow you to verify more data with one call. However, a program using CSNBMVR1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface , and may need to be modified before it can run with other cryptographic products that follow this programming interface. The callable service name for AMODE(64) invocation is CSNEMVR1. For CSNBMVR1, text_id_in is an access list entry token (ALET) parameter of the data space containing the application-supplied text. Format CALL CSNBMVR( return_code, reason_code, exit_data_length, exit_data, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector, mac ) Chapter 7. Verifying Data Integrity and Authenticating Messages 399 MAC Verify CALL CSNBMVR1( return_code, reason_code, exit_data_length, exit_data, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector, mac, text_id_in ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier Direction: Input/Output Type: String The 64-byte key label or internal key token that identifies a single or double-length MAC verify key, a single or double-length MAC verify key, a single or double length MAC generation key, a DATAM or DATAMV key, or a single-length DATA key. The type of key depends on the MAC process rule in the rule_array parameter. text_length Direction: Input 400 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer MAC Verify The length of the text you supply in the text parameter. The maximum length of text is 214783647 bytes. If the text_length parameter is not a multiple of 8 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. Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced (2147483647). text Direction: Input Type: String The application-supplied text for which the MAC is generated. rule_array_count Direction: Input Type: Integer The number of keywords specified in the rule_array parameter. The value can be 0, 1, 2, or 3. rule_array Direction: Input Type: String Zero to three keywords that provide control information to the callable service. The keywords are shown in Table 153. 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. Table 153. Keywords for MAC verify Control Information Keyword Meaning MAC Process Rules (optional) EMVMAC EMV padding rule with a single-length MAC key. The key_identifier parameter must identify a single-length MAC, MACVER, or DATA key. The text is always padded with 1 to 8 bytes so that the resulting text length is a multiple of 8 bytes. The first pad character is X'80'. The remaining 0 to 7 pad characters are X'00'. EMVMACD EMV padding rule with a double-length MAC key. The key_identifier parameter must identify a double-length MAC or MACVER key. The padding rules are the same as for EMVMAC. X9.19OPT ANSI X9.9-1 and X9.19 basic procedure. The key_identifier parameter must identify a single-length MAC, MACVER, or DATA key. X9.9-1 causes the MAC to be computed from all of the data. The text is padded only if the text length is not a multiple of 8 bytes. If padding is required, the pad character X'00' is used. This is the default value. Chapter 7. Verifying Data Integrity and Authenticating Messages 401 MAC Verify Table 153. Keywords for MAC verify Control Information (continued) Keyword Meaning X9.9-1 ANSI X9.9-1 and X9.19 basic procedure. The key_identifier parameter must identify a single-length MAC, or single-length DATA key. X9.9-1 causes the MAC to be computed from all of the data. The text is padded only if the text length is not a multiple of 8 bytes. If padding is required, the pad character X'00' is used. This is the default value. TDES-MAC ISO 16609 procedure. The key_identifier must identify a double-length MAC or a double-length DATA key. The text is padded only if the text length is not a multiple of 8 bytes. Segmenting Control (optional) FIRST First call; this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; the application program does not employ segmenting. This is the default value. MAC Length and Presentation (optional) HEX-8 Verifies a 4-byte MAC value that is represented as 8 hexadecimal characters. HEX-9 Verifies a 4-byte MAC value that is represented as 2 groups of 4 hexadecimal characters with a space character between the groups. MACLEN4 Verifies a 4-byte MAC value. This is the default value. MACLEN6 Verifies a 6-byte MAC value. MACLEN8 Verifies an 8-byte MAC value. chaining_vector Direction: Input/Output Type: String An 18-byte string that ICSF uses 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: Output Type: String The 8- 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 X'09' keyword in the rule_array parameter, the input MAC is 9 bytes. text_id_in Direction: Input Type: Integer For CSNBMVR1/CSNEMVR1 only, the ALET of the text for which the MAC is to be verified. 402 z/OS V1R13 ICSF Application Programmer's Guide MAC Verify Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. 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. CCF Systems only: To use a MAC generation key or a DATA key, the NOCV enablement keys must be present in the CKDS. Using either a MAC generation key or a DATA key instead of a MAC verify key in this service substantially increases the path length for verifying the MAC. | The MAC Verify access control point controls the function of this service. The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 154. MAC verify required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions ICSF routes the request to a PCI Cryptographic Coprocessor if the control vector in the supplied key identifier cannot be processed on the Cryptographic Coprocessor Feature. The request must meet the following restrictions: v The MAC Process Rule is X9.19OPT or EMVMACD. v The MAC key is a valid double-length MAC generate key. v The text_length on the final call (ONLY or LAST) can not be greater than 4K including padding. v The text_length must be less than or equal to 4K bytes for the FIRST and MIDDLE keywords, and the text length must be a multiple of 8 bytes. TDES-MAC not supported. IBM Eserver zSeries PCI X Cryptographic Coprocessor 990 TDES-MAC not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor IBM System z9 BC Chapter 7. Verifying Data Integrity and Authenticating Messages 403 MAC Verify Table 154. MAC verify required hardware (continued) Server Required cryptographic hardware IBM System z10 EC IBM System z10 BC Crypto Express2 Coprocessor Restrictions Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Related Information For more information about MAC processing rules and segmenting control, refer to IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface Reference. The MAC generation callable service is described in “MAC Generate (CSNBMGN or CSNBMGN1 and CSNEMGN or CSNEMGN1)” on page 393. MDC Generate (CSNBMDG or CSNBMDG1 and CSNEMDG or CSNEMDG1) A modification detection code (MDC) can be used to provide a form of support for data integrity. Use the MDC generate callable service to generate a 128-bit modification detection code (MDC) for an application-supplied text string. The returned MDC value should be securely stored and/or sent to another user. To validate the integrity of the text string at a later time, the MDC generate callable service is again used to generate a 128-bit MDC. The new MDC value is compared with the original MDC value. If the values are equal, the text is accepted as unchanged. Choosing Between CSNBMDG and CSNBMDG1 CSNBMDG and CSNBMDG1 provide identical functions. When choosing which service to use, consider the following: v CSNBMDG requires the application-supplied text to reside in the caller's primary address space. Also, a program using CSNBMDG adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. The callable service name for AMODE(64) invocation is CSNEMDG. v CSNBMDG1 allows the application-supplied text to reside either in the caller's primary address space or in a data space. This can allow you to process more data with one call. However, a program using CSNBMDG1 does not adhere to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface and may need to be modified before it can run with other cryptographic products that follow this programming interface. The callable service name for AMODE(64) invocation is CSNEMDG1. For CSNBMDG1, text_id_in parameter specifies the access list entry token (ALET) for the data space containing the application-supplied text. 404 z/OS V1R13 ICSF Application Programmer's Guide MDC Generate Format CALL CSNBMDG( return_code, reason_code, exit_data_length, exit_data, text_length, text, rule_array_count, rule_array, chaining_vector, mdc ) CALL CSNBMDG1( return_code, reason_code, exit_data_length, exit_data, text_length, text, rule_array_count, rule_array, chaining_vector, mdc, text_id_in ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes,” on page 725 lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes,” on page 725 lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. text_length Chapter 7. Verifying Data Integrity and Authenticating Messages 405 MDC Generate Direction: Input Type: Integer The length of the text you supply in the text parameter. The maximum length of text is 214783647 bytes. Note: The MAXLEN value may still be specified in the options data set, but only the maximum value limit will be enforced (2147483647). Additional restrictions on length of the text depend on whether padding of the text is requested, and on the segmenting control used. v When padding is requested (by specifying a process rule of PADMDC-2 or PADMDC-4 in the rule_array parameter), a text length of 0 is valid for any segment control specified in the rule_array parameter (FIRST, MIDDLE, LAST, or ONLY). When LAST or ONLY is specified, the supplied text will be padded with X'FF's 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 a process rule of MDC-2 or MDC-4), the total length of the text provided (over a single or segmented calls) must be at least 16 bytes, and a multiple of 8. For segmented calls with no padding, text length of 0 is valid on any of the calls provided the total length over the segmented calls is at least 16 and a multiple of 8. For a single call (that is, segment control is ONLY) with no padding, the length the text provided must be at least 16, and a multiple of 8. text Direction: Input Type: String The application-supplied text for which the MDC is generated. rule_array_count Direction: Input Type: Integer The number of keywords specified in the rule_array parameter. This value must be 2. rule_array Direction: Input Type: Character string The two keywords that provide control information to the callable service are shown in Table 155. The two keywords must be in 16 bytes of contiguous storage with each of the two keywords left-justified in its own 8-byte location and padded on the right with blanks. For example, ’MDC-2 FIRST ’ Choose one of the MDC process rule control keywords and one of the segmenting control keywords from the following table. Table 155. Keywords for MDC Generate Control Information Keyword Meaning MDC Process Rules (required) MDC-2 406 z/OS V1R13 ICSF Application Programmer's Guide MDC-2 specifies two encipherments per 8 bytes of input text and no padding of the input text. MDC Generate Table 155. Keywords for MDC Generate Control Information (continued) Keyword Meaning MDC-4 MDC-4 specifies four encipherments per 8 bytes of input text and no padding of the input text. PADMDC-2 PADMDC-2 specifies two encipherments per 8 bytes of input text and padding of the input text. When the segment rule specifies ONLY or LAST, the input text is padded with X'FF's and a padding count in the last byte to bring the total text length to the next even multiple of 8 that is greater than, or equal to, 16. PADMDC-4 PADMDC-4 specifies four encipherments per 8 bytes of input text and padding of the input text. When the segment rule specifies ONLY or LAST, the input text is padded with X'FF's and a padding count in the last byte to bring the total text length to the next even multiple of 8 that is greater than, or equal to, 16. Segmenting Control (required) FIRST First call; this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; segmenting is not employed by the application program. chaining_vector Direction: Input/Output Type: String An 18-byte string that ICSF uses 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. mdc Direction: Input/Output Type: String A 16-byte field in which the callable service returns the MDC value when the segmenting rule is ONLY or LAST. When the segmenting rule is FIRST or MIDDLE, the value returned in this field is an intermediate MDC value that will be used as input for a subsequent call and must not be changed by the application program. text_id_in Direction: Input Type: Integer For CSNBMDG1/CSNEMDG1 only, the ALET for the data space containing the text for which the MDC is to be generated. Usage Notes To calculate an MDC in one call, specify the ONLY keyword for segmenting control in the rule_array parameter. For more than one call, specify the FIRST keyword for Chapter 7. Verifying Data Integrity and Authenticating Messages 407 MDC Generate the first input block, the MIDDLE keyword for any intermediate blocks, and the LAST keyword for the last block. For a given text string, the resulting MDC is the same whether the text is segmented or not. The two versions of MDC calculation (with two or four encipherments per 8 bytes of input text) allow the caller to trade a performance improvement for a decrease in security. Since 2 encipherments create results different from the results of 4 encipherments, ensure that you use the same number of encipherments to verify the MDC value. The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 156. MDC generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries CP Assist for 990 Cryptographic Functions IBM Eserver zSeries 890 IBM System z9 EC IBM System z9 BC CP Assist for Cryptographic Functions IBM System z10 EC IBM System z10 BC CP Assist for Cryptographic Functions z196 CP Assist for Cryptographic Functions One-Way Hash Generate (CSNBOWH or CSNBOWH1 and CSNEOWH or CSNEOWH1) Use the one-way hash generate callable service to generate a one-way hash on specified text. This service supports the following methods: v MD5 - software only v SHA-1 v RIPEMD-160 - software only v SHA-224 v SHA-256 v SHA-384 v SHA-512 The callable service names for AMODE(64) invocation are CSNEOWH and CSNEOWH1. 408 z/OS V1R13 ICSF Application Programmer's Guide One-Way Hash Generate Format CALL 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) CALL CSNBOWH1( 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, text_id_in) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes assigned to it that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String Chapter 7. Verifying Data Integrity and Authenticating Messages 409 One-Way Hash Generate The data that is passed to the installation exit. rule_array_count Direction: Input Type: Integer The number of keywords you are supplying in the rule_array parameter. The value must be 1 or 2. rule_array Direction: Input Type: String Keywords that provide control information to the callable service are listed in Table 157. The optional chaining flag keyword indicates whether calls to this service 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. Table 157. Keywords for One-Way Hash Generate Rule Array Control Information Keyword Meaning Hash Method (required) MD5 Hash algorithm is MD5 algorithm. Use this hash method for PKCS-1.0 and PKCS-1.1. Length of hash generated is 16 bytes. | | | | | | MD5-LG Hash algorithm is similar to the MD5 algorithm. Use this hash method for PKCS-1.0 and PKCS-1.1. Length of hash generated is 16 bytes. Legacy hash values from release HCR7751 and lower prior to APAR OA33657 will be generated for verification purposes with previously archived hash values. | | | | | RPMD-LG Hash algorithm is similar to the RIPEMD-160. Length of hash generated is 20 bytes. Legacy hash values from release HCR7751 and lower prior to APAR OA33657 will be generated for verification purposes with previously archived hash values. RPMD-160 Hash algorithm is RIPEMD-160. Length of hash generated is 20 bytes. SHA-1 Hash algorithm is SHA-1 algorithm. Use this hash method for DSS. Length of hash generated is 20 bytes. SHA-224 Hash algorithm is SHA-256 algorithm. Length of hash generated is 28 bytes. SHA-256 Hash algorithm is SHA-256 algorithm. Length of hash generated is 32 bytes. SHA-384 Hash algorithm is SHA-384 algorithm. Length of hash generated is 48 bytes. SHA-512 Hash algorithm is SHA-512 algorithm. Length of hash generated is 64 bytes. Chaining Flag (optional) 410 FIRST Specifies this is the first call in a series of chained calls. Intermediate results are stored in the hash field. LAST Specifies this is the last call in a series of chained calls. z/OS V1R13 ICSF Application Programmer's Guide One-Way Hash Generate Table 157. Keywords for One-Way Hash Generate Rule Array Control Information (continued) Keyword Meaning MIDDLE Specifies this is a middle call in a series of chained calls. Intermediate results are stored in the hash field. ONLY Specifies this is the only call and the call is not chained. This is the default. text_length Direction: Input Type: Integer The length of the text parameter in bytes. Note: If you specify the FIRST or MIDDLE keyword, then the text length must be a multiple of the blocksize of the hash method. For MD5, RPMD-160, SHA-1, SHA-224 and SHA-256, this is a multiple of 64 bytes. For SHA-384 and SHA-512, this is a multiple of 128 bytes. For ONLY and LAST, this service performs the required padding according to the algorithm specified. text Direction: Input Type: String The application-supplied text on which this service 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 at least 20 bytes; for MD5 this must be at least 16 bytes. For SHA-224 and SHA-256, the length must be at least 32 bytes long. Even though the length of the SHA-224 hash is less than SHA-256, the extra bytes are used as a work area during the generation of the hash value. The SHA-224 value is left-justified and padded with zeroes. For SHA-384 and SHA-512, the length must be at least 64 bytes long. Even though the length of the SHA-384 hash is less than SHA-512, the Chapter 7. Verifying Data Integrity and Authenticating Messages 411 One-Way Hash Generate extra bytes are used as a work area during the generation of the hash value. The SHA-384 value is left-justified and padded with zeroes. 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. text_id_in Direction: Input Type: Integer For CSNBOWH1 only, the ALET for the data space containing the text for which to generate the hash. Usage Notes Although MD5, SHA-1 and SHA-256 allow it, bit length text is not supported for any hashing method. The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 158. One-way hash generate required hardware Server Required cryptographic hardware IBM Eserver zSeries Cryptographic 900 Coprocessor Feature Restrictions SHA-1 requires CCF SHA-224 keyword not supported SHA-256 keyword not supported SHA-384 keyword not supported SHA-512 keyword not supported IBM Eserver zSeries CP Assist for 990 Cryptographic Functions IBM Eserver zSeries 890 SHA-1 requires CPACF SHA-224 keyword not supported SHA-256 keyword not supported SHA-384 keyword not supported SHA-512 keyword not supported IBM System z9 EC IBM System z9 BC 412 CP Assist for Cryptographic Functions IBM System z10 EC IBM System z10 BC CP Assist for Cryptographic Functions z196 CP Assist for Cryptographic Functions z/OS V1R13 ICSF Application Programmer's Guide SHA-384 keyword not supported SHA-512 keyword not supported One-Way Hash Generate Symmetric MAC Generate (CSNBSMG or CSNBSMG1 and CSNESMG or CSNESMG1) Use the symmetric MAC generate callable service to generate a 96- or 128-bit message authentication code (MAC) for an application-supplied text string using an AES key. The callable service names for AMODE(64) invocation are CSNESMG and CSNESMG1. Choosing Between CSNBSMG and CSNBSMG1 or CSNESMG and CSNESMG1 CSNBSMG, CSNBSMG1, CSNESMG, and CSNESMG1 provide identical functions. When choosing which service to use, consider this: v CSNBSMG and CSNESMG require the text to reside in the caller’s primary address space. Also, a program using CSNBSMG adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. v CSNBSMG1 and CSNESMG1 allow the text to reside either in the caller’s primary address space or in a data space. This can allow you to decipher more data with one call. However, a program using CSNBSMG1 and CSNESMG1 do not adhere to the IBM CCA: Cryptographic API and may need to be modified prior to it running with other cryptographic products that follow this programming interface. For CSNBSMG1 and CSNESMG1, text_id_in is an access list entry token (ALET) parameter of the data spaces containing the text. Format CALL CSNBSMG( return_code, reason_code, exit_data_length, exit_data, key_identifier_length, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector_length, chaining_vector, reserved_data_length, reserved_data mac_length mac ) Chapter 7. Verifying Data Integrity and Authenticating Messages 413 Symmetric MAC Generate CALL CSNBSMG1( return_code, reason_code, exit_data_length, exit_data, key_identifier_length, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector_length, chaining_vector, reserved_data_length, reserved_data mac_length mac text_id_in) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier_length Direction: Input Type: String The length of the key_identifier parameter. For the KEY-CLR keyword, the length is in bytes and includes only the value of the key length. The key length value can be 16, 24, or 32. For the KEYIDENT keyword, the length must be 64. key_identifier 414 z/OS V1R13 ICSF Application Programmer's Guide Symmetric MAC Generate Direction: Input Type: String For the KEY-CLR keyword, this specifies the clear AES key. The parameter must be left justified. For the KEYIDENT keyword, this specifies an internal clear AES token or the label name of a clear AES key in the CKDS. Normal CKDS label name syntax is required. text_length Direction: Input Type: Integer The length of the text you supply in the text parameter. The maximum length of text is 2147483647 bytes. If the text_length is not a multiple of 8 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 generated. rule_array_count Direction: Input Type: Integer The number of keywords specified in the rule_array parameter. The value can be 1, 2, 3 or 4. rule_array Direction: Input Type: Character string This keyword provides control information to the callable service. 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. 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. Table 159. Keywords for symmetric MAC generate control information Keyword Meaning Algorithm (required) AES Specifies that the Advanced Encryption Standard (AES) algorithm is to be used. MAC processing rule (optional) CBC-MAC CBC MAC with padding for any key length. This is the default value. XCBC-MAC AES-XCBC-MAC-96 and AES-XCBC-PRF-128 MAC generation with padding for 128-bit keys. Key rule (optional) KEY-CLR This specifies that the key parameter contains a clear key value. This is the default value. Chapter 7. Verifying Data Integrity and Authenticating Messages 415 Symmetric MAC Generate Table 159. Keywords for symmetric MAC generate control information (continued) Keyword Meaning KEYIDENT This specifies that the key_identifier field will be an internal clear token or the label name of a clear key in the CKDS. Normal CKDS label name syntax is required. Segmenting Control (optional) FIRST First call, this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; segmenting is not employed by the application program. This is the default value. chaining_vector_length Direction: Input/Output Type: Integer The length of the chaining_vector parameter. On output, the actual length of the chaining vector will be stored in the parameter. chaining_vector Direction: Input/Output Type: String This field is used as a system work area for the chaining vector. Your application program must not change the data in this string. The chaining vector holds the output chaining vector from the caller. The mapping of the chaining_vector depends on the algorithm specified. For AES, the chaining_vector field must be at least 36 bytes in length. reserved_data_length Direction: Input Type: Integer Reserved for future use. Value must be zero. reserved_data Direction: Ignored Type: String Reserved for future use. mac_length Direction: Input Type: Integer The length in bytes of the MAC to be returned in the mac field. The allowable values are 12 and 16 bytes. mac Direction: Output Type: String The 12-byte or 16-byte field in which the callable service returns the MAC value if the segmenting rule is ONLY or LAST. 416 z/OS V1R13 ICSF Application Programmer's Guide Symmetric MAC Generate text_id_in Direction: Input Type: Integer For CSNBSMG1 and CSNESMG1 only, the ALET of the text for which the MAC is generated. Usage Notes The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 160. Symmetric MAC generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries CPACF 990 IBM Eserver zSeries 890 IBM System z9 EC CPACF IBM System z9 BC IBM System z10 EC IBM System z10 BC CPACF z196 CPACF Symmetric MAC Verify (CSNBSMV or CSNBSMV1 and CSNESMV or CSNESMV1) Use the symmetric MAC verify callable service to verify a 96- or 128-bit message authentication code (MAC) for an application-supplied text string using an AES key. The callable service names for AMODE(64) invocation are CSNESMV and CSNESMV1. Choosing Between CSNBSMV and CSNBSMV1 or CSNESMV and CSNESMV1 CSNBSMV, CSNBSMV1, CSNESMV, and CSNESMV1 provide identical functions. When choosing which service to use, consider this: v CSNBSMV and CSNESMV require the text to reside in the caller’s primary address space. Also, a program using CSNBSMV adheres to the IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface. v CSNBSMV1 and CSNESMV1 allow the text to reside either in the caller’s primary address space or in a data space. This can allow you to decipher more data with one call. However, a program using CSNBSMV1 and CSNESMV1 do not adhere to the IBM CCA: Cryptographic API and may need to be modified prior to it running with other cryptographic products that follow this programming interface. Chapter 7. Verifying Data Integrity and Authenticating Messages 417 Symmetric MAC Verify For CSNBSMV1 and CSNESMV1, text_id_in is an access list entry token (ALET) parameter of the data spaces containing the text. Format CALL CSNBSMV( return_code, reason_code, exit_data_length, exit_data, key_identifier_length, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector_length, chaining_vector, reserved_data_length, reserved_data mac_length mac ) CALL CSNBSMV1( return_code, reason_code, exit_data_length, exit_data, key_identifier_length, key_identifier, text_length, text, rule_array_count, rule_array, chaining_vector_length, chaining_vector, reserved_data_length, reserved_data mac_length mac text_id_in ) Parameters return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length 418 z/OS V1R13 ICSF Application Programmer's Guide Symmetric MAC Verify Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFF' (2 gigabytes). The data is identified in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. key_identifier_length Direction: Input Type: Integer The length of the key_identifier parameter. For the KEY-CLR keyword, the length is in bytes and includes only the value of the key length. The key length value can be 16, 24, or 32. For the KEYIDENT keyword, the length must be 64. key_identifier Direction: Input Type: String For the KEY-CLR keyword, this specifies the clear AES key. The parameter must be left justified. For the KEYIDENT keyword, this specifies an internal clear AES token or the label name of a clear AES key in the CKDS. Normal CKDS label name syntax is required. text_length Direction: Input Type: Integer The length of the text you supply in the text parameter. The maximum length of text is 2147483647 bytes. If the text_length parameter is not a multiple of 8 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 The number of keywords specified in the rule_array parameter. The value can be 1, 2, 3 or 4. rule_array Direction: Input Type: String Chapter 7. Verifying Data Integrity and Authenticating Messages 419 Symmetric MAC Verify This keyword provides control information to the callable service. 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 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. Table 161. Keywords for symmetric MAC verify control information Keyword Meaning Algorithm (required) AES Specifies that the Advanced Encryption Standard (AES) algorithm is to be used. MAC processing rule (optional) CBC-MAC CBC MAC with padding for any key length. This is the default value. XCBC-MAC AES-XCBC-MAC-96 and AES-XCBC-PRF-128 MAC generation with padding for 128-bit keys. Key rule (optional) KEY-CLR This specifies that the key parameter contains a clear key value. This is the default value. KEYIDENT This specifies that the key_identifier field will be an internal clear token or the label name of a clear key in the CKDS. Normal CKDS label name syntax is required. Segmenting Control (optional) FIRST First call, this is the first segment of data from the application program. LAST Last call; this is the last data segment. MIDDLE Middle call; this is an intermediate data segment. ONLY Only call; segmenting is not employed by the application program. This is the default value. chaining_vector_length Direction: Input/Output Type: String The length of the chaining_vector parameter. On output, the actual length of the chaining vector will be stored in the parameter. chaining_vector Direction: Input/Output Type: String This field is used as a system work area for the chaining vector. Your application program must not change the data in this string. The chaining vector holds the output chaining vector from the caller. The mapping of the chaining_vector depends on the algorithm specified. For AES, the chaining_vector field must be at least 36 bytes in length. reserved_data_length Direction: Input 420 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Symmetric MAC Verify Reserved for future use. Value must be zero. reserved_data Direction: Ignored Type: String Reserved for future use. mac_length Direction: Input Type: Integer The length in bytes of the MAC to be verified the mac field. The allowable values are 12 and 16 bytes. mac Direction: Input Type: String The 12-byte or 16-byte field that contains the MAC value you want to verify. The value must be left-justified and padded with zeros. text_id_in Direction: Input Type: Integer For CSNBSMV1 and CSNESMV1 only, the ALET of the text for which the MAC is to be verified. Usage Notes The following table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 162. Symmetric MAC verify required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature IBM Eserver zSeries CPACF 990 IBM Eserver zSeries 890 IBM System z9 EC CPACF IBM System z9 BC IBM System z10 EC IBM System z10 BC CPACF z196 CPACF Chapter 7. Verifying Data Integrity and Authenticating Messages 421 Symmetric MAC Verify 422 z/OS V1R13 ICSF Application Programmer's Guide Chapter 8. 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. ICSF provides callable services to translate, verify, and generate PINs. You can use the callable services to prevent unauthorized disclosures when organizations handle PINs. | These callable services are described in these topics: v “Clear PIN Encrypt (CSNBCPE and CSNECPE)” on page 434 v “Clear PIN Generate (CSNBPGN and CSNEPGN)” on page 438 v “Clear PIN Generate Alternate (CSNBCPA and CSNECPA)” on page 442 v “CVV Key Combine (CSNBCKC and CSNECKC)” on page 448 v “Encrypted PIN Generate (CSNBEPG and CSNEEPG)” on page 453 v “Encrypted PIN Translate (CSNBPTR and CSNEPTR)” on page 458 v “Encrypted PIN Verify (CSNBPVR and CSNEPVR)” on page 466 v “PIN Change/Unblock (CSNBPCU and CSNEPCU)” on page 473 v “Secure Messaging for Keys (CSNBSKY and CSNESKY)” on page 479 v “Secure Messaging for PINs (CSNBSPN and CSNESPN)” on page 482 v “SET Block Compose (CSNDSBC and CSNFSBC)” on page 487 v “SET Block Decompose (CSNDSBD and CSNFSBD)” on page 492 v “Transaction Validation (CSNBTRV and CSNETRV)” on page 498 v “VISA CVV Service Generate (CSNBCSG and CSNECSG)” on page 502 v “VISA CVV Service Verify (CSNBCSV and CSNECSV)” on page 506 How Personal Identification Numbers (PINs) are Used Many people are familiar with PINs, which allow them to use 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 that no one other than the account owner can use it. ICSF allows your applications to generate PINs, to verify supplied PINs, and to translate PINs from one format to another. How VISA Card Verification Values Are Used The Visa International Service Association (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 VISA card-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 ICSF callable services generate and verify the CVV4 by the track-2 method. The VISA CVV service generate callable service calculates a 1- 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 service verify callable service calculates the CVV by the same method, compares it to the 4. The VISA CVV and the MasterCard CVC refer to the same value. CVV is used here to mean both CVV and CVC. © Copyright IBM Corp. 1997, 2011 423 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. 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 wish to use an ATM to access an account at home. The PIN entered at the ATM might need to be encrypted at the ATM and sent over one or more financial networks to the traveler's home bank. At the home bank, the PIN must be verified prior to access being allowed. On intermediate systems (between networks), applications can use the Encrypted PIN translate callable service to re-encrypt a PIN block from one key to another. Running on ICSF, 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 services you can use in secure communications with EMV smart cards. The processing capabilities are consistent with the specifications provided in these documents: v EMV 2000 Integrated Circuit Card 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 (CSNBDKG and CSNEDKG) callable service 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 services 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 services. v The secure messaging for keys (CSNBSKY and CSNESKY) service enables you to securely incorporate a key into a message part (generally the value portion of a TLV component of a secure message for a card). Similarly, the secure messaging for PINs (CSNBSPN and CSNESPN) service enables secure incorporation of a PIN block into a message part. v The PIN change/unblock (CSNBPCU and CSNEPCU) service enables you to encrypt 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 PKA encrypt (CSNDPKE) service enables you to validate a digital signature created according to ISO 9796-2 standard by encrypting information you format, including a hash value of the message to be validated. You compare the resulting enciphered data to the digital signature accompanying the message to be validated. 424 z/OS V1R13 ICSF Application Programmer's Guide v The MAC generate and MAC verify services post-pad a X'80'...X'00' string to a message as required for authenticating messages exchanged with EMV smart cards. PIN Callable Services You use the PIN callable services to generate, verify, and translate PINs. This topic discusses the PIN callable services, as well as the various PIN algorithms and PIN block formats supported by ICSF. 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 callable service. Using a PIN generation algorithm, data used in the algorithm, and the PIN generation key, the Clear PIN generate callable service generates a clear PIN and a PIN verification value, or offset. The Clear PIN Generate callable service can only execute in special secure mode. For a description of this mode, see “Special Secure Mode” on page 10. Using a PIN generation algorithm, data used in the algorithm, the PIN generation key, and an outbound PIN encrypting key, the encrypted PIN generate callable service 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 callable service. Generating a PIN Validation Value from an Encrypted PIN Block To generate a clear VISA PIN validation value (PVV) from an encrypted PIN block, call the clear PIN generate alternate callable service. The PIN block can be encrypted under an input PIN-encrypting key (IPINENC) or an output PIN encrypting key (OPINENC). Using an IPINENC key requires that NOCV keys are enabled in the CKDS. Verifying a PIN To verify a supplied PIN, call the Encrypted PIN verify callable service. 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 callable service generates a verification PIN. The service 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 callable service. 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 callable service 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 ICSF supports these algorithms for generating and verifying personal identification numbers: v IBM 3624 institution-assigned PIN Chapter 8. Financial Services 425 v IBM 3624 customer-selected PIN (through a PIN offset) v IBM German Bank Pool PIN (verify through an institution key) v IBM German Bank Pool PIN (verify through a pool key and a PIN offset). This algorithm is supported when the service using the PIN is processed on the Cryptographic Coprocessor Feature. Restriction: This algorithm is not supported on a z990, z890, z9 EC or z9 BC. v VISA PIN through a VISA PIN validation value v Interbank PIN The algorithms are discussed in detail in “PIN Formats and Algorithms” on page 863. Using PINs on Different Systems ICSF allows you to translate different PIN block formats, which lets you use personal identification numbers on different systems. ICSF supports these formats: v IBM 3624 v IBM 3621 (same as IBM 5906) v IBM 4704 encrypting PINPAD format v ISO 0 (same as ANSI 9.8, VISA 1, and ECI 1) v ISO 1 (same as ECI 4) v ISO 2 v ISO 3 v VISA 2 v VISA 3 v VISA 4 v ECI 2 v ECI 3 The formats are discussed in “PIN Formats and Algorithms” on page 863. PIN-Encrypting Keys A unique master key variant enciphers each type of key. For further key separation, an installation can choose to have each PIN block format enciphered under a different PIN-encrypting key. The PIN-encrypting keys can have a 16-byte PIN block variant constant exclusive ORed on them prior to using to translate or verify PIN blocks. This is specified in the format control field in the Encrypted PIN translate and Encrypted PIN verify callable services. You should only use PIN block variant constants when you are communicating with another host processor with the Integrated Cryptographic Service Facility. Derived Unique Key Per Transaction Algorithms ICSF supports ANSI X9.24 derived unique key per transaction algorithms to generate PIN-encrypting keys from user data. ICSF supports both single- and double-length key generation. Keywords for single- and double-length key generation can not be mixed. A PCICC, PCIXCC, CEX2C, or CEX3C is required for this support. Double-length key generation is only supported on z990 with the May 2004 LIC or higher, z890, z9 EC, z9 BC and IBM System z10 EC. Encrypted PIN Translate The UKPTIPIN, IPKTOPIN and UKPTBOTH keywords will cause the service 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 must supply the current key serial number when these keywords are specified. 426 z/OS V1R13 ICSF Application Programmer's Guide Encrypted PIN Verify The UKPTIPIN keyword will cause the service to generate single-length keys. DUKPT-IP is the keyword for double-length key generation. The input_PIN_profile must supply the current key serial number when these keywords are specified. For more information about PIN-encrypting keys, see z/OS Cryptographic Services ICSF Administrator's Guide. ANSI X9.8 PIN Restrictions | | | | | | | Access control points (ACP) in the ICSF role control PIN block processing restrictions from the X9.8 standard. These access control points are available on the z196 with the CEX3C. These callable services are affected by these access control points. These access control points are disabled in the default role. A TKE Workstation is required to enable these ACPs. v Clear PIN Generate Alternate (CSNBCPA and CSNECPA) v Encrypted PIN Generate (CSNBEPG and CSNEEPG) v Encrypted PIN Translate (CSNBPTR and CSNEPTR) | v Encrypted PIN Verify (CSNBPVR and CSNEPVR) v Secure Messaging for PINs (CSNBSPN and CSNESPN) There are four access control points: v ANSI X9.8 PIN - Enforce PIN block restrictions v ANSI X9.8 PIN - Allow modification of PAN v ANSI X9.8 PIN - Allow only ANSI PIN blocks | v ANSI X9.8 PIN – Use stored decimalization tables only | | | PIN decimalization tables can be stored in the CEX3C coprocessors for use by callable services. Only tables that have been activated can be used. A TKE Workstation is required to manage the tables in the coprocessors. | | | | Note: ICSF routes work to all active coprocessors based on work load. All coprocessors must have the same set of active decimalization tables for the ANSI X9.8 PIN – Use stored decimalization tables only access control point to be effective. ANSI X9.8 PIN - Enforce PIN block restrictions When ANSI X9.8 PIN - Enforce PIN block restrictions access control point is enable, the following restrictions will be enforced. v CSNBPTR and CSNBSPN will not accept IBM 3624 PIN format in the output profile parameter when the input profile parameter is not IBM 3624. v CSNBPTR 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 CSNBPTR and CSNBSPN 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 v When the input profile parameter of CSNBPTR or CSNBSPN contains either ISO-0 or ISO-3 formats, the decrypted PIN block will be examined to ensure that the PAN within the PIN block is the same as the PAN which was supplied as the input PAN parameter, and that this is the same as the PAN which was supplied as the output PAN parameter. Chapter 8. Financial Services 427 v The input PAN and output PAN parameters of CSNBPTR or CSNBSPN must be equivalent. v When the rule array for CSNBCPA 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 the ANSI X9.8 PIN - Allow modification of PAN access control point, the ANSI X9.8 PIN - Enforce PIN block restrictions must also be enabled. The ANSI X9.8 PIN - Allow modification of PAN access control point cannot be enabled by itself. When the ANSI X9.8 PIN - Allow modification of PAN access control point is enabled, the input PAN and output PAN parameters will be tested in CSNBPTR or CSNBSPN. The input PAN will be compared to the portions of the PAN which are recoverable from the decrypted PIN block. If the PANs compare, then the account number will be changed in the output PIN block. ANSI X9.8 PIN - Allow only ANSI PIN blocks In order to enable the ANSI X9.8 PIN - Allow only ANSI PIN blocks access control point, the ANSI X9.8 PIN - Enforce PIN block restrictions must also be enabled. The ANSI X9.8 PIN - Allow only ANSI PIN blocks access control point cannot be enabled by itself. When this access control point is enable, CSNBPTR will allow reformatting of the PIN block as shown in the following table. Table 163. ANSI X9.8 PIN - Allow only ANSI PIN blocks Reformat To: ISO Format 0 ISO Format 1 ISO Format 3 Not permitted Reformat permitted From: ISO Format 0 Reformat permitted Change of PAN not permitted Change of PAN not permitted ISO Format 1 Reformat permitted Reformat permitted Reformat permitted ISO Format 3 Reformat permitted Not permitted Reformat permitted Change of PAN not permitted | Change of PAN not permitted ANSI X9.8 PIN – Use stored decimalization tables only | | The ANSI X9.8 PIN – Use stored decimalization tables only access control point may be enabled by itself. | | | | | | | When this access control point is enabled, CSNBPGN, CSNBCPA, CSNBEPG, and CSNBPVR services must supply a decimalization table that matches the active decimalization tables stored in the coprocessors. The decimalization table in the data_array parameter will be compared against the active decimalization tables in the coprocessor and if the supplied table matches a stored table, the request will be processed. If the supplied table doesn’t match any of the stored tables or there are no stored tables, the request will fail. | | | PIN decimalization tables can be stored in the CEX3C coprocessors for use by callable services. Only tables that have been activated can be used. A TKE Workstation is required to manage the tables in the coprocessors. 428 z/OS V1R13 ICSF Application Programmer's Guide Note: ICSF routes work to all active coprocessors based on work load. All coprocessors must have the same set of decimalization tables for the decimalization table access control point to be effective. | | | | The PIN Profile The PIN profile consists of: v PIN block format (see “PIN Block Format”) v Format control (see “Format Control” on page 432) v Pad digit (see “Pad Digit” on page 432) v Current Key Serial Number (for UKPT and DUKPT – see “Current Key Serial Number” on page 433) Table 164 shows the format of a PIN profile. Table 164. Format of a PIN Profile Bytes Description 0–7 PIN block format 8–15 Format control 16–23 Pad digit 24–47 Current Key Serial Number (for UKPT and DUKPT ) 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 Table 165 for a list of valid values. Table 165. Format Values of PIN Blocks Format Value Description ECI-2 Eurocheque International format 2 ECI-3 Eurocheque International format 3 ISO-0 ISO format 0, ANSI X9.8, VISA 1, and ECI 1 ISO-1 ISO format 1 and ECI 4 ISO-2 ISO format 2 ISO-3 ISO format 3 VISA-2 VISA format 2 VISA-3 VISA format 3 VISA-4 VISA format 4 3621 IBM 3621 and 5906 3624 IBM 3624 4704-EPP IBM 4704 with encrypting PIN pad PIN Block Format and PIN Extraction Method Keywords | | In the Clear PIN Generate Alternate, Encrypted PIN Translate and Encrypted PIN Verify callable services, you may specify a PIN extraction keyword for a given PIN block format. In this table, 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. If you specify a PIN extraction method keyword that is not the default, the request will be routed to the PCI Cryptographic Coprocessor on the z900 server. Chapter 8. Financial Services 429 Table 166. PIN Block Format and PIN Extraction Method Keywords 430 PIN Block Format PIN Extraction Method Keywords ECI-2 PINLEN04 The PIN extraction method keywords specify a PIN extraction method for a PINLEN04 format. ECI-3 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. ISO-0 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. ISO-1 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. ISO-2 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. ISO-3 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. VISA-2 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. VISA-3 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. VISA-4 PINBLOCK The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. 3621 PADDIGIT, HEXDIGIT, PINLEN04 to PINLEN12, PADEXIST The PIN extraction method keywords specify a PIN extraction method for an IBM 3621 PIN block format. The first keyword, PADDIGIT, is the default PIN extraction method for the PIN block format. 3624 PADDIGIT, HEXDIGIT, PINLEN04 to PINLEN16, PADEXIST The PIN extraction method keywords specify a PIN extraction method for an IBM 3624 PIN block format. The first keyword, PADDIGIT, is the default PIN extraction method for the PIN block format. z/OS V1R13 ICSF Application Programmer's Guide Description Table 166. PIN Block Format and PIN Extraction Method Keywords (continued) PIN Block Format PIN Extraction Method Keywords 4704-EPP PINBLOCK Description The PIN extraction method keywords specify a PIN extraction method for a PINBLOCK format. | The PIN extraction methods operate as follows: | | | PINBLOCK Specifies that the service use one of these: 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 service use the pad value in the PIN profile to identify the end of the PIN. | | | HEXDIGIT Specifies that the service use the first occurrence of a digit in the range from X'A' to X'F' as the pad value to determine the PIN length. | | | PINLENxx Specifies that the service use the length specified in the keyword, where xx can range from 4 to 16 digits, to identify the PIN. | | | PADEXIST Specifies that the service use the character in the 16th position of the PIN block as the value of the pad value. Enhanced PIN Security Mode An Enhanced PIN Security Mode is available. This optional mode is selected by enabling the PTR Enhanced PIN Security access control point in the PCICC, PCIXCC, CEX2C, or CEX3C default role. When active, this control point affects all PIN callable services that extract or format a PIN using a PIN-block format of 3621 or 3624 with a PIN-extraction method of PADDIGIT. Table 167 summarizes the callable services affected by the Enhanced PIN Security Mode and describes the effect that the mode has when the access control point is enabled. Table 167. Callable Services Affected by Enhanced PIN Security Mode PIN-block format and PIN-extraction method Callable Services Affected PIN processing changes when Enhanced PIN Security Mode enabled ECI-2, 3621, or 3624 formats AND PINLENxx PIN-block format and PIN-extraction method The PINLENxx keyword in rule_array parameter for PIN extraction method is not allowed if the Enhanced PIN Security Mode is enabled. Note: The services will fail with return code 8 reason code '7E0'x. Clear_PIN_Generate_Alternate Encrypted_PIN_Translate Encrypted_PIN_Verify Chapter 8. Financial Services 431 Table 167. Callable Services Affected by Enhanced PIN Security Mode (continued) PIN-block format and PIN-extraction method Callable Services Affected PIN processing changes when Enhanced PIN Security Mode enabled 3621 or 3624 format and PADDIGIT Clear_PIN_Generate_Alternate PIN extraction determines the PIN length by scanning from right to left until a digit, not equal to the pad digit, is found. The minimum PIN length is set at four digits, so scanning ceases one digit past the position of the 4th PIN digit in the block. Encrypted_PIN_Translate Encrypted_PIN_Verify PIN Change/Unblock 3621 or 3624 format and PADDIGIT Clear_PIN_Encrypt Encrypted_PIN_Generate PIN formatting does not examine the PIN, in the output PIN block, to see if it contains the pad digit. Encrypted_PIN_Translate 3621 or 3624 format and PADDIGIT Encrypted_PIN_Translate Restricted to non-decimal digit for PAD digit. 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. Specify one of these values: NONE No format control. PBVC A PIN block variant constant (PBVC) enforces format control. Use the PBVC value only if you have coded PBVC in the encrypted PIN translate callable service. For the PBVC, the clear PIN key-encrypting key has been exclusive ORed with one of the PIN block formats. The cryptographic feature removes the pattern from the clear PIN key-encrypting key prior to it decrypting the PIN block. Restriction: PBVC is not supported on IBM Eserver zSeries 990 and subsequent releases. Notes: 1. Only control vectors and extraction methods valid for the Cryptographic Coprocessor Feature may be used if the PBVC format control is desired. 2. PBVC is supported for compatibility with prior releases of OS/390 ICSF and existing ICSF applications. It is recommended that a format control of NONE be specified for maximum flexibility to run on PCI Cryptographic Coprocessors. If you do not specify a value for the format control parameter, ICSF uses hexadecimal zeros. Table 182 on page 447 lists the PIN block variant constants. Pad Digit Some PIN formats require this parameter. If the PIN format does not need a pad digit, the callable service ignores this parameter. Table 168 on page 433 shows the format of a pad digit. The PIN profile pad digit must be specified in upper case. 432 z/OS V1R13 ICSF Application Programmer's Guide Table 168. Format of a Pad Digit Bytes Description 16–22 Seven space characters 23 Character representation of a hexadecimal pad digit or a space if a pad digit is not needed. Characters must be one of these: 0–9, A–F, or a blank. Each PIN format supports only a pad digit in a certain range. This table lists the valid pad digits for each PIN block format. Table 169. Pad Digits for PIN Block Formats PIN Block Format Output PIN Profile Input PIN Profile ECI-2 Pad digit is not used Pad digit is not used ECI-3 Pad digit is not used Pad digit is not used ISO-0 F Pad digit is not used ISO-1 Pad digit is not used Pad digit is not used ISO-2 Pad digit is not used Pad digit is not used ISO-3 Pad digit is not used Pad digit is not used VISA-2 0 through 9 Pad digit is not used VISA-3 0 through F Pad digit is not used VISA-4 F Pad digit is not used 3621 0 through F 0 through F 3624 0 through F 0 through F 4704-EPP F Pad digit is not used The callable service returns an error indicating that the PAD digit is not valid if all of these conditions are met: 1. 2. 3. The PTR Enhanced Security access control point 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 Recommendations for the Pad Digit IBM recommends that you use a nondecimal pad digit in the range of A through 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 may 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. Table 170 on page 434 shows the format of the current key serial number. Chapter 8. Financial Services 433 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. Table 170. Format of the Current Key Serial Number Field | Bytes Description 24–47 Character representation of the current key serial number used to derive the initial PIN encrypting key. It is left justified and padded with 4 blanks. Decimalization Tables | | Decimalization tables can be loaded in the coprocessors to restrict attacks using modified tables. The management of the tables requires a TKE Workstation. | | | | Clear PIN Generate (CSNBPGN and CSNEPGN), Clear PIN Generate Alternate (CSNBCPA and CSNECPA), Encrypted PIN Generate (CSNBEPG and CSNEEPG), and Encrypted PIN Verify (CSNBPVR and CSNEPVR) callable services will make use of the stored decimalization tables. | | | | | The ANSI X9.8 PIN – Use stored decimalization tables only access control point is used to restrict the use of tables. When the access control point is enabled, the table supplied by the callable service will be compared against the active tables stored in the coprocessor. If the supplied table doesn’t match any of the active tables, the request will fail. | | | A TKE workstation (Version 7.1 or later) is required to manage the PIN decimalization tables. The tables must be loaded and then activated. Only active tables are checked when the access control point is enabled. | | | Note: ICSF routes work to all active coprocessors based on work load. All coprocessors must have the same set of decimalization tables for the decimalization table access control point to be effective. Clear PIN Encrypt (CSNBCPE and CSNECPE) The Clear PIN Encrypt callable service formats a PIN into one of these PIN block formats and encrypts the results. You can use this service to create an encrypted PIN block for transmission. With the RANDOM keyword, you can have the service generate random PIN numbers. Note: A clear PIN is a sensitive piece of information. Ensure that your application program and system design provide adequate protection for any clear PIN value. v IBM 3621 format v IBM 3624 format v ISO-0 format (same as the ANSI 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 VISA 2 format v VISA 3 format v VISA 4 format v ECI2 format v ECI3 format 434 z/OS V1R13 ICSF Application Programmer's Guide Clear PIN Encrypt An enhanced PIN security mode, on PCICC, PCIXCC, CEX2C, or CEX3C, is available for formatting an encrypted PIN block into IBM 3621 format or IBM 3624 format. To do this, you must enable the PTR Enhanced PIN Security access control point in the default role. When activated, this mode limits checking of the PIN to decimal digits. No other PIN block consistency checking will occur. The callable service name for AMODE(64) invocation is CSNECPE. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output Type: Integer The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFFFF' (2 gigabytes). The data is defined in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. PIN_encrypting_key_identifier Direction: Input/Output Type: String Chapter 8. Financial Services 435 Clear PIN Encrypt 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 The number of keywords you are supplying in the rule_array parameter. Valid values are 0 and 1. | | rule_array Direction: Input Type: Character string Keywords that provide control information to the callable service. 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 shown as follows: Table 171. Process Rules for the Clear PIN Encryption Callable Service Process Rule Description ENCRYPT This is the default. Use of this keyword is optional. RANDOM Causes the service to generate a random PIN value. The length of the PIN is based on the value in the clear_PIN variable. Set the value of the clear PIN to zero and use as many digits as the desired random PIN; pad the remainder of the clear PIN variable with space characters. clear_PIN Direction: Input Type: String A 16-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 A 24-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 429 for additional information. PAN_data Direction: Input Type: String A 12-byte PAN in character format. The service uses this parameter if the PIN profile specifies the ISO-0 or VISA-4 keyword for the PIN block format. Otherwise, ensure that this parameter is a 12-byte variable in application storage. The information in this variable will be ignored, but the variable must be specified. 436 z/OS V1R13 ICSF Application Programmer's Guide Clear PIN Encrypt Note: When using the ISO-0 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 service 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. If PBVC is specified as the format control, the service will fail. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. SAF will be invoked to check authorization to use the Clear PIN encrypt service and the label of the PIN_encrypting_key_identifier. | The Clear PIN Encrypt access control point controls the function of this service. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Table 172. Clear PIN encrypt required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries PCI Cryptographic 900 Coprocessor ISO-3 PIN block format is not supported. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor ISO-3 PIN block format is not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor ISO-3 PIN block format requires the Nov. 2007 or later licensed internal code (LIC). Crypto Express2 Coprocessor ISO-3 PIN block format requires the Nov. 2007 or later licensed internal code (LIC). IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196 Crypto Express3 Coprocessor Chapter 8. Financial Services 437 Clear PIN Generate Clear PIN Generate (CSNBPGN and CSNEPGN) Use the Clear PIN generate callable service 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 IBM German Bank Pool (GBP-PINO) - not supported on an IBM Eserver zSeries 990 and subsequent releases. v VISA PIN validation value (VISA-PVV) v Interbank PIN (INBK-PIN) The callable service can execute only when ICSF is in special secure mode. This mode is described in “Special Secure Mode” on page 10. For guidance information about VISA, see their appropriate publications. The Interbank PIN algorithm is available only on S/390 Enterprise Servers, the S/390 Multiprise, and the IBM Eserver Zseries. The callable service name for AMODE(64) invocation is CSNEPGN. Format CALL 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 return_code Direction: Output Type: Integer The return code specifies the general result of the callable service. Appendix A, “ICSF and TSS Return and Reason Codes” lists the return codes. reason_code Direction: Output Type: Integer The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. Appendix A, “ICSF and TSS Return and Reason Codes” lists the reason codes. exit_data_length Direction: Input/Output 438 z/OS V1R13 ICSF Application Programmer's Guide Type: Integer Clear PIN Generate The length of the data that is passed to the installation exit. The length can be from X'00000000' to X'7FFFFFFFFF' (2 gigabytes). The data is defined in the exit_data parameter. exit_data Direction: Input/Output Type: String The data that is passed to the installation exit. PIN_generating_key_identifier Direction: Input/Output Type: Character string The 64-byte key label or internal key token that identifies the PIN generation (PINGEN) key. If the PIN_generating_key_identifier identifies a key which does not have the default PIN generation key control vector, the request will be routed to a PCI Cryptographic Coprocessor. rule_array_count Direction: Input Type: Integer The number of process rules specified in the rule_array parameter. The value must be 1. rule_array Direction: Input Type: Character string The process rule provides control information to the callable service. Specify one of the values in Table 173. The keyword is left-justified in an 8-byte field, and padded on the right with blanks. Table 173. Process Rules for the Clear PIN Generate Callable Service Process Rule Description GBP-PIN The IBM German Bank Pool PIN, which uses the institution PINGEN key to generate an institution PIN (IPIN). GBP-PINO The IBM German Bank Pool PIN offset, which uses the pool PINGEN key to generate a pool PIN (PPIN). It uses the institution PIN (IPIN) as input and calculates the PIN offset, which is the output. GBP-PINO is not supported on an IBM Eserver zSeries 990 and subsequent releases. IBM-PIN The IBM 3624 PIN, which is an institution-assigned PIN. It does not calculate the PIN offset. IBM-PINO The IBM 3624 PIN offset, which is a customer-selected PIN and calculates the PIN offset (the output). INBK-PIN The Interbank PIN is generated. VISA-PVV The VISA PIN validation value. Input is the customer PIN. PIN_length Direction: Input Type: Integer Chapter 8. Financial Services 439 Clear PIN Generate 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 through 16. If the length is greater than 12, the request will be routed to the PCI Cryptographic Coprocessor. 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 through 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, then the rest of the data array is ignored by the callable service. Table 174 describes the array elements. Table 174. Array Elements for the Clear PIN Generate Callable Service Array Element Description Clear_PIN Clear user selected PIN of 4 to 12 digits of 0 through 9. Left-justified and padded with spaces. For IBM-PINO, this is the clear customer PIN (CSPIN). For GBP-PINO, this is the institution PIN. For IBM-PIN and GBP-PIN, this field is ignored. Decimalization_table Decimalization table for IBM and GBP only. Sixteen digits of 0 through 9. Note: If the ANSI X9.8 PIN – Use stored decimalization tables only access control point is enabled in the ICSF role, this table must match one of the active decimalization tables in the coprocessors. Trans_sec_parm For VISA only, the leftmost sixteen digits. Eleven digits of the personal account number (PAN). One digit key index. Four digits of customer selected PIN. | | | | | For Interbank only, sixteen digits. Eleven right-most digits of the personal account number (PAN). A constant of 6. One digit key selector index. Three digits of PIN validation data. Validation_data Validation data for IBM and IBM German Bank Pool padded to 16 bytes. One to sixteen characters of hexadecimal account data left-justified and padded on the right with blanks. Table 175 on page 441 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. 440 z/OS V1R13 ICSF Application Programmer's Guide Clear PIN Generate Table 175. Array Elements Required by the Process Rule Process Rule IBM-PIN IBM-PINO GBP-PIN GBP-PINO Decimalization_table 1 1 1 1 Validation_data 2 2 2 2 Clear_PIN 3 VISA-PVV INBK-PIN 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 Direction: Output Type: Character string The 16-byte generated output, left-justified and padded on the right with blanks. Restrictions PIN lengths of 13-16 require the optional PCI Cryptographic Coprocessor. Usage Notes SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS or PKDS. 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. | | This table shows the access control points in the ICSF role that control the function of this service. | Table 176. Required access control points for Clear PIN Generate | Rule array keywords Access control point | | IBM-PIN IBM-PINO Clear PIN Generate - 3624 | GBP-PIN Clear PIN Generate - GBP | VISA-PVV Clear PIN Generate - VISA PVV | | INBK-PIN Clear PIN Generate - Interbank | | | If the ANSI X9.8 PIN – Use stored decimalization tables only access control point is enabled in the ICSF role, any decimalization table specified must match one of the active decimalization tables in the coprocessors. This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. Chapter 8. Financial Services 441 Clear PIN Generate Table 177. Clear PIN generate required hardware Server Required cryptographic hardware Restrictions IBM Eserver zSeries Cryptographic 900 Coprocessor Feature ICSF routes this service to a PCI Cryptographic Coprocessor if the control vector of the PIN generating key cannot be processed on the Cryptographic Coprocessor Feature. IBM Eserver zSeries PCI X Cryptographic 990 Coprocessor Rule_array keyword GBP-PINO is not supported. IBM Eserver zSeries Crypto Express2 890 Coprocessor IBM System z9 EC Crypto Express2 Coprocessor Rule_array keyword GBP-PINO is not supported. Crypto Express2 Coprocessor Rule_array keyword GBP-PINO is not supported. IBM System z9 BC IBM System z10 EC IBM System z10 BC Crypto Express3 Coprocessor z196