Table of Contents (exploded view)
Cryptographic Services ICSF: System Programmer's Guide
Summary of changes
Changes made in Enhanced Cryptographic Support for z/OS V1R13 - z/OS V2R1 (FMID HCR77B0)
Changes made in Cryptographic Support for z/OS V1R13 - z/OS V2R1 (FMID HCR77A1) as updated June 2014
Changes made in Cryptographic Support for z/OS V1R13 - z/OS V2R1 (FMID HCR77A1)
Changes made in Cryptographic Support for z/OS V1R12-R13 (FMID HCR77A0)
Changes made in Cryptographic Support for z/OS V1R11-R13 (FMID HCR7790)
Introduction to z/OS ICSF
Features
Cryptographic hardware features
Server hardware
z/OS ICSF FMIDs
ICSF features
The Cryptographic Key Data Set (CKDS)
The Public Key Data Set (PKDS)
The Token Data Set (TKDS)
Additional background information
Running PCF applications on z/OS ICSF
Using RMF and SMF to monitor z/OS ICSF events
Controlling access to ICSF
Steps prior to starting installation
Installation, initialization, and customization
Steps for installation and initialization
Steps to customize SYS1.PARMLIB
Creating the CKDS
ICSF system resource planning for the CKDS
Additional CKDS performance considerations
Steps to create the CKDS
Creating the PKDS
ICSF system resource planning for the PKDS
Steps to create the PKDS
Creating the TKDS
ICSF system resource planning for the TKDS and session object memory areas
Steps to create the TKDS
ICSF system resource planning for random number generation
Steps to create the installation options data set
Creating an ICSF CTRACE configuration data set
Steps to create the ICSF startup procedure
Steps to provide access to the ICSF panels
Steps to start ICSF for the first time
Steps for initializing ICSF
Customizing ICSF after the first start
Parameters in the installation options data set
Improving CKDS performance
Dispatching priority of ICSF
Creating ICSF exits and generic services
Migration
Terminology
Migrating from earlier software releases
Callable services
Identification of cryptographic features
Ensure the expected CCA master key support is available
Ensure the expected P11 master key support is available
Ensure that the CSFPUTIL utility is not used to initialize a PKDS
Modify ICSF startup procedure to run new startup program
Ensure PKCS #11 applications call C_Finalize() prior to calling dlclose()
Key store policy
ICSF key data sets
Record metadata
CKDS
Migrating to the variable length CKDS
PKDS
TKDS
Migrating to the KDSR format key data set
Converting to KDSR format using the CSFCRC callable service
Converting to KDSR format using the ICSF panels
Changing the RSA master key
Migrating to 24-byte DES master key
Installation options data set
Function restrictions
CICS attachment facility
Dynamic LPA load
Special secure mode
Resource Manager Interface (RMF)
Verifying archived hash values
System abend codes
SMF records
TKE workstation
Access to callable services
TKE enablement from the support element
Enabling access control points for PKCS #11 coprocessor firmware
Migrating from the IBM eServer zSeries 900
Migrating a CKDS and PKDS between a CCF system and a non-CCF system
CCF only system
CCF with PCICCs
Callable services
Functions not supported
Setup considerations
Programming considerations
Operating ICSF
Starting and stopping ICSF
Modifying ICSF
Using different configurations
Adding and removing cryptographic coprocessors
Adding cryptographic coprocessors
Steps for activating/deactivating cryptographic coprocessors
Steps to configure on/off cryptographic coprocessors
Steps for enabling/disabling cryptographic coprocessors
Intrusion latch on the cryptographic coprocessors
Performance considerations for using installation options
Dispatching priority of ICSF
VTAM session-level encryption
System SSL encryption
Access method services cryptographic option
Remote key loading
Event recording
System Management Facilities (SMF) recording
ICSF Initialization (Subtype 1)
Operational Key Part Entry (Subtype 7)
CKDS Refresh (Subtype 8)
Dynamic CKDS Update (Subtype 9)
Dynamic PKDS Update (Subtype 13)
Cryptographic Coprocessor Clear Master Key Entry (Subtype 14)
Cryptographic Coprocessor Retained Key Create or Delete (Subtype 15)
Cryptographic Coprocessor TKE Command Request or Reply (Subtype 16)
Cryptographic Coprocessor Configuration (Subtype 18)
PCI X Cryptographic Coprocessor Timing (Subtype 19)
Cryptographic Coprocessor Timing (Subtype 20)
ICSF Sysplex Group (Subtype 21)
Trusted Block Create (Subtype 22)
Token Data Set (TKDS) (Subtype 23)
Duplicate Key Tokens (Subtype 24)
Key Store Policy Key Token Authorization Checking (Subtype 25)
PKDS Refresh (Subtype 26)
Key Store Policy PKA Key Management Extensions (Subtype 27)
High Performance Encrypted Key (Subtype 28)
TKE Workstation Audit Record (Subtype 29)
Key Store Policy Archived and Inactive Checking (Subtype 30)
Message recording
Security considerations
Controlling the program environment
Controlling access to KGUP
Controlling access to CSFDUTIL
Controlling access to the callable services
Controlling access to cryptographic keys
Controlling access to secure key tokens
Scheduling changes for cryptographic keys
Controlling access to administrative panel functions
Obtaining RACF SMF log records
Debugging aids
Component trace
Abnormal endings
IPCS formatting routine
Detecting ICSF serialization contention conditions
Installation exits
Types of exits
Mainline exits
Exits for the services
The PCF CKDS conversion program exit
The single-record, read-write exit
The cryptographic key data set entry retrieval exit
Security exits
The KGUP exit
Entry and return specifications
Registers at entry
Registers at return
Exits environment
Mainline exits
service exits
CKDS entry retrieval exit
KGUP, Conversion Programs, and Single-record, Read-write exits
Security exits
Exit recovery
Mainline installation exits
Purpose and use of the exits
CSFEXIT1
CSFEXIT2
CSFEXIT3
CSFEXIT4
CSFEXIT5
Environment of the exits
Installing the exits
Input
The Exit Parameter Block
Parameters
Return Codes
Services installation exits
Purpose and use of the exits
Environment of the exits
Installing the exits
Input
Exit parameter block
Secondary parameter block
Parameters
Return Codes
CSVDYNEX service exit
Cryptographic key data set entry retrieval installation exit
Purpose and use of the exit
Environment of the exit
Installing the exit
Input
Return codes
PCF conversion program installation exit
Purpose and use of the exit
Environment of the exit
Installing the exit
Input
Return codes
Single-record, Read-write installation exit
Purpose and use of the exit
Environment of the exit
Installing the exit
Input
Return codes
Exit points for security installation exits
Security installation exits
Purpose and use of the exits
Security initialization exit
Security termination exit
Security service exit
Security key exit
Environment of the exits
Installing the exits
Input
Return codes
Key generator utility program installation exit
Purpose and use of the exit
KGUP calling points
Processing in the exit
Environment of the exit
Installing the exit
Input
The SET statement
Return codes
Installation-defined Callable Services
Writing a callable service
Contents of registers
Security access control checking
Checking the parameters
Link-editing the callable service
Defining a callable service
Writing a service stub
Example of a service stub
Converting a CKDS from fixed length to variable length record format
Migration from PCF to z/OS ICSF
Running PCF and z/OS ICSF on the same system
Running in compatibility mode
Running in coexistence mode
Changing the DES master key in compatibility or coexistence mode
Running in noncompatibility mode
Specifying compatibility modes during migration
Converting a PCF CKDS to ICSF format
How the PCF conversion program runs
Calling installation exits during conversion
Using the conversion program override file
Bypassing conversion of entries
Including information in a key entry
Converting key types
Running the conversion program
Example of a Conversion Initial Activity Report
Example of a Conversion Update Activity Report
Diagnosis reference information
Cryptographic Key Data Set (CKDS) formats
Public Key Data Set (PKDS) format
Format of the PKDS header record
Format of the PKDS record
Token data set (TKDS) format
Format of the header record of the token data set
Format of the token and object records
Common section of the token and object records
Format of the token-specific section of the token record
Format of the object-specific sections of the token object records
KDSR record format
AES key token format
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
Internal PKA tokens
PKA null key token
RSA key token formats
RSA public key token
RSA private external key token
RSA private internal key token
ECC key token format
Associated data format for ECC token
AESKW wrapped payload format for ECC private key token
Trusted block key token
Trusted block sections
Trusted block integrity
Number representation in trusted blocks
Format of trusted block sections
Data areas
The Cryptographic Communication Vector Table (CCVT)
The Cryptographic Communication Vector Table Extension (CCVE)
Generic Service Table (CSFMGST)
RMF measurements table
ICSF SMF records
Record type 82 (52) — ICSF record
Record environment
Record mapping
Header/self-defining section
Server user or end user audit section
Subtype 1
Initialization section
Subtype 7
Operational key load section
Subtype 8
Cryptographic key data set refresh section
Subtype 9
Dynamic CKDS update
Subtype 13
Dynamic PKDS update
Subtype 14
Cryptographic coprocessor master key entry
Subtype 15
PCI Cryptographic coprocessor retained key create/delete
Subtype 16
PCI Cryptographic coprocessor TKE
Subtype 18
Cryptographic processor configuration
Subtype 19
PCI X Cryptographic coprocessor timing
Subtype 20
Cryptographic processor processing times
Subtype 21
ICSF sysplex group change section
Subtype 22
Trusted block create callable services section
Subtype 23
Token data set update
Subtype 24
Duplicate tokens found
Subtype 25
Key store policy for key token authorization checking
Subtype 26
Public key data set refresh
Subtype 27
PKA key management extensions
Subtype 28
High performance encrypted key
Subtype 29
TKE workstation audit record
Subtype 30
Key store policy archived and inactive KDS records
CICS-ICSF Attachment Facility
Installing the CICS-ICSF Attachment Facility
Steps for installing the CICS-ICSF attachment facility
Implementing the CICS wait list
Helpful hints for ICSF first time startup
Checklist for first-time startup of ICSF
Step 1. Hardware setup
Step 2. LPAR activation profiles
Step 3. ICSF setup
Step 4. TKE setup
Step 5. ICSF startup
Step 6. Loading master keys and initializing the CKDS through ICSF panels
Step 7. Customizing TKE and loading master keys
Step 8. CICS-ICSF Attachment Facility setup
Step 9. Complete ICSF initialization
Commonly encountered ICSF first time setup/initialization messages
Using AMS REPRO encryption
Steps for setting up ICSF
Systems without Cryptographic features
Applications and programs
Callable services
ICSF setup and initialization
Secure Sockets Layer (SSL)
TKE workstation