Z/OS ICSF System Programmer's Guide Chapter 6
Total Page:16
File Type:pdf, Size:1020Kb
z/OS IBM Cryptographic Services Integrated Cryptographic Service Facility System Programmer's Guide Version2Release2 SC14-7507-05 Note Before using this information and the product it supports, read the information in “Notices” on page 367. This edition applies to ICSF FMID HCR77B1 and Version 2 Release 2 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 2007, 2016. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures ..............vii ICSF system resource planning for random number generation ...........27 Tables ...............ix Steps to create the installation options data set . 27 Creating an ICSF CTRACE configuration data set 30 Steps to create the ICSF startup procedure . 32 About this information ........xi Steps to provide access to the ICSF panels . 33 Who should use this information .......xi Requiring signature verification for ICSF module How to use this information .........xi CSFINPV2 ..............35 Where to find more information .......xiii Steps to start ICSF for the first time .....36 IBM Crypto Education .........xiii Customizing ICSF after the first start ......38 Parameters in the installation options data set . 38 How to send your comments to IBM . xv Improving CKDS performance .......55 If you have a technical problem .......xv Dispatching priority of ICSF ........55 Creating ICSF exits and generic services ....55 Summary of changes ........xvii Changes made in Cryptographic Support for z/OS Chapter 3. Migration .........57 V1R13 - z/OS V2R2 (FMID HCR77B1) as updated Terminology ..............58 April 2016 ..............xvii Migrating from earlier software releases .....58 Changes made in Cryptographic Support for z/OS Actions to perform before installing ICSF FMID V1R13 - z/OS V2R2 (FMID HCR77B1) .....xvii HCR77B1 ..............58 Changes made in Enhanced Cryptographic Actions to perform before the first start of ICSF Support for z/OS V1R13 - z/OS V2R1 (FMID FMID HCR77B1 ............62 HCR77B0) ..............xviii Actions to perform after the first start of ICSF Changes made in Cryptographic Support for z/OS FMID HCR77B1 ............64 V1R13 - z/OS V2R1 (FMID HCR77A1) as updated Callable services ............66 June 2014 ...............xix Identification of cryptographic features ....74 Changes made in Cryptographic Support for z/OS Ensure the expected P11 master key support is V1R13 - z/OS V2R1 (FMID HCR77A1) .....xx available ..............74 Changes made in Cryptographic Support for Key store policy ............75 z/OS V1R12-R13 (FMID HCR77A0) .....xxiii ICSF key data sets ...........75 Changing the RSA master key .......78 Chapter 1. Introduction to z/OS ICSF . 1 Migrating to 24-byte DES master key .....79 Features ................1 Installation options data set ........79 Cryptographic hardware features ......1 Function restrictions ..........80 Server hardware ............2 CICS attachment facility .........80 z/OS ICSF FMIDs ...........6 Dynamic LPA load ...........81 ICSF features ..............7 Special secure mode ..........81 The Cryptographic Key Data Set (CKDS) .....8 Resource Manager Interface (RMF) .....81 The Public Key Data Set (PKDS) ........8 System abend codes ..........81 The Token Data Set (TKDS) .........9 SMF records .............86 Additional background information ......9 TKE workstation ...........86 Running PCF applications on z/OS ICSF ....9 Migrating from the IBM eServer zSeries 900 . 88 Using RMF and SMF to monitor z/OS ICSF Migrating a CKDS and PKDS between a CCF events ...............10 system and a non-CCF system .......88 Controlling access to ICSF ........10 Callable services ............92 Steps prior to starting installation .......10 Functions not supported .........93 Setup considerations ..........93 Chapter 2. Installation, initialization, Programming considerations .......93 and customization ..........13 Chapter 4. Operating ICSF ......95 Steps for installation and initialization .....13 Starting and stopping ICSF .........95 Steps to customize SYS1.PARMLIB .....14 Modifying ICSF .............96 Creating the CKDS ...........15 Command syntax notation .........96 Creating the PKDS ...........20 How to read syntax diagrams .......96 Creating the TKDS ...........23 ICSF operator commands ..........99 © Copyright IBM Corp. 2007, 2016 iii Display ICSF .............99 The KGUP exit ............141 SETICSF ..............104 Entry and return specifications .......141 Using different configurations ........111 Registers at entry ...........142 Adding and removing cryptographic coprocessors 113 Registers at return...........143 Adding cryptographic coprocessors .....113 Exits environment ............143 Steps for activating/deactivating cryptographic Mainline exits ............143 coprocessors .............113 service exits .............143 Steps to configure on/off cryptographic CKDS entry retrieval exit ........143 coprocessors .............114 KGUP, Conversion Programs, and Single-record, Steps for enabling/disabling cryptographic Read-write exits ...........143 coprocessors .............114 Security exits ............144 | Adding and removing regional cryptographic Exit recovery .............144 servers ...............115 Mainline installation exits .........144 | Steps to add a regional cryptographic server . 115 Purpose and use of the exits .......144 | Steps to remove a regional cryptographic server 116 Environment of the exits ........145 Configuring ICSF to use TCP/IP for Installing the exits ...........145 | communications with regional cryptographic Input ...............146 servers ..............116 Return Codes ............152 Displaying cryptographic coprocessor status using Services installation exits .........152 the DISPLAY ICSF operator command .....119 Purpose and use of the exits .......153 | Adding a regional cryptographic server using the Environment of the exits ........153 SETICSF operator command ........120 Installing the exits ...........153 Changing regional cryptographic server status Input ...............158 using the SETICSF operator command .....120 Return Codes ............163 Performance considerations for using installation CSVDYNEX service exit .........164 options ...............120 Cryptographic key data set entry retrieval Dispatching priority of ICSF ........120 installation exit .............166 VTAM session-level encryption .......120 Purpose and use of the exit........166 System SSL encryption ..........121 Environment of the exit .........166 Access method services cryptographic option. 121 Installing the exit ...........167 Remote key loading ...........121 Input ...............167 Event recording ............122 Return codes ............168 System Management Facilities (SMF) recording 122 PCF conversion program installation exit ....168 Message recording...........130 Purpose and use of the exit........169 Security considerations ..........130 Environment of the exit .........169 Controlling the program environment ....131 Installing the exit ...........169 Controlling access to KGUP .......131 Input ...............170 Controlling access to CSFDUTIL ......131 Return codes ............171 Controlling access to the callable services . 131 Single-record, Read-write installation exit ....171 Controlling access to cryptographic keys . 132 Purpose and use of the exit........172 Controlling access to secure key tokens....132 Environment of the exit .........172 Scheduling changes for cryptographic keys . 132 Installing the exit ...........173 Controlling access to administrative panel Input ...............173 functions ..............132 Return codes ............175 Obtaining RACF SMF log records .....133 Exit points for security installation exits ....175 Debugging aids ............133 Security installation exits .........175 Component trace ...........133 Purpose and use of the exits .......175 Abnormal endings...........134 Environment of the exits ........176 IPCS formatting routine .........134 Installing the exits ...........176 Detecting ICSF serialization contention Input ...............178 conditions .............136 Return codes ............179 Key generator utility program installation exit . 179 Chapter 5. Installation exits .....139 Purpose and use of the exit........179 Types of exits .............139 Environment of the exit .........181 Mainline exits ............140 Installing the exit ...........181 Exits for the services ..........140 Input ...............181 The PCF CKDS conversion program exit . 140 The SET statement...........190 The single-record, read-write exit ......140 Return codes ............190 The cryptographic key data set entry retrieval exit ................141 Security exits ............141 iv z/OS ICSF System Programmer's Guide Chapter 6. Installation-defined The Cryptographic Communication Vector Table Callable Services..........191 (CCVT) ..............318 Writing a callable service .........191 The Cryptographic Communication Vector Table Contents of registers ..........192 Extension (CCVE) ...........319 Security access control checking ......193 Generic Service Table (CSFMGST) .....320 Checking the parameters ........193 RMF measurements table .........321 Link-editing the callable service ......194 Defining a callable service .........194 Appendix B. ICSF SMF records....325 Writing a service stub ..........194 Record type 82 (52) — ICSF record ......325 Example of a service stub ........195 Record environment