z/OS Cryptographic Services ICSF System Programmer's Guide
Previous topic |
Next topic
|
Contents
|
Contact z/OS
|
Library
|
PDF
Contents (exploded view)
z/OS Cryptographic Services ICSF System Programmer's Guide
SA22-7520-17
System Programmer's Guide
Figures
Tables
z/OS Cryptographic Services Integrated Cryptographic Service Facility System Programmer's Guide
Summary of changes
Changes made in z/OS Version 1 Release 13
Changes made in z/OS Version 1 Release 12
Changes made in z/OS Version 1 Release 11
Introduction to z/OS ICSF
Hardware Features
Cryptographic Hardware
Crypto Express3 Feature (CEX3C or CEX3A)
Crypto Express2 Feature (CEX2C or CEX2A)
PCI X Cryptographic Coprocessor (PCIXCC)
CP Assist for Cryptographic Functions (CPACF)
PCI Cryptographic Accelerator (PCICA)
Cryptographic Coprocessor Feature (CCF)
PCI Cryptographic Coprocessor (PCICC)
Server Hardware
IBM zEnterprise 196 (z196)
IBM System z10 Enterprise Class and IBM System z10 Business Class (z10 BC)
IBM System z9 Business Class (z9 BC)
IBM System z9 Enterprise Class (z9 EC)
IBM eServer zSeries 990 (z990)
IBM eServer zSeries 890 (z890)
IBM eServer zSeries 900 (z900) — Feature Code 800
IBM eServer zSeries 800 (z800) — Feature Code 800
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
ICSF System SVC 143
Running 4753-HSP applications on 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
Migrating to a larger PKDS
Creating the TKDS
ICSF System Resource Planning for the TKDS and Session Object Memory Areas
Steps to create the TKDS
Steps to create the Installation Options 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
MK Initialization for SMP/E - CCF Systems Only
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
Ensure the expected 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()
ICSF Key Data Sets
CKDS
Migrating to the variable length CKDS
PKDS
TKDS
Key Tokens
Changing the RSA master key
Installation Options Data Set
Function Restrictions
CICS Attachment Facility
Dynamic LPA Load
Special Secure Mode
Resource Manager Interface (RMF)
System Abend Codes
SMF Records
TKE Workstation
TKE Version 3.1 and Access to Callable Services
TKE Version 4.x and Higher and Access to Callable Services
TKE Enablement from the Support Element
Migrating from the IBM eServer zSeries 900
Callable Services
Functions Not Supported
Setup Considerations
Programming Considerations
Migrating from 4753-HSP
Operating ICSF
Starting and stopping ICSF
Modifying ICSF
Using different configurations
Configuring the z890, z990, z9 EC, z9 BC, z10 EC, z10 BC, and z196
Configuring the IBM eServer zSeries 900
Single Image Mode
Logical Partition (LPAR) Mode
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 (PCICC, PCIXCC, CEX2C, and CEX3C)
Intrusion Latch on the PCICC, PCIXCC, CEX2C, or CEX3C
Steps for enabling/disabling cryptographic coprocessors (CCF)
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)
ICSF Status Change (Subtype 3)
Error Handling for Cryptographic Coprocessor Feature (Subtype 4)
Special Secure Mode Change (Subtype 5)
Master Key Part Entry (Subtype 6)
Operational Key Part Entry (Subtype 7)
CKDS Refresh (Subtype 8)
Dynamic CKDS Update (Subtype 9)
PKA Key Part Entry (Subtype 10)
Clear New Master Key Part Entry (Subtype 11)
PKSC Commands (Subtype 12)
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)
PCI Cryptographic Coprocessor Timing (Subtype 17)
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 (Subtype 25)
PKDS Data Space Refresh (Subtype 26)
PKA Key Management Extensions (Subtype 27)
High Performance Encrypted Key (Subtype 28)
TKE Workstation Audit Record (Subtype 29)
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
Examining the Trace Entry Buffer
CSF TRACE Common Header
Service and Exit Trace Entry Types
Type-Specific Data for Misc Trace Entries
Type-Specific Data for Service Trace Entries
Instruction Trace Entry Types
Type-Specific Data for Instruction Trace Entries
Sysplex CKDS Entry Types
Type-Specific Data for Sysplex CKDS Trace Entries
Sysplex PKDS Entry Types
Type-Specific Data for Sysplex PKDS Trace Entries
Sysplex TKDS Entry Types
Type-Specific Data for Sysplex TKDS Trace Entries
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
CSFEXIT1
CSFEXIT2 and CSFEXIT3
CSFEXIT4 and CSFEXIT5
The Exit Name Table
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
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 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
Example 1
Example 2
Example 3
Example 4
Including Information in a Key Entry
Example 1
Example 2
Example 3
Converting Key Types
Example 1
Example 2
Example 3
Example 4
Example 5
Example 6
Running the Conversion Program
Example of a Conversion Initial Activity Report
Example of a Conversion Update Activity Report
Compatibility and Coexistence of 4753-HSP and ICSF
Running 4753-HSP and ICSF on the same z/OS system
Appendix A. Diagnosis Reference Information
Cryptographic Key Data Set (CKDS) Formats
Fixed-Length Cryptographic Key Data Set (CKDS) Record Format
Format of the Fixed-Length CKDS Header Record
Format of the Fixed-Length CKDS Record
Variable-Length Cryptographic Key Data Set (CKDS) Record Format
Format of the Variable-Length Header Record
Format of the Variable-Length CKDS Record
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
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 Key Token, 1024-bit Modulus-Exponent External Form
RSA Private Key Token, 4096-bit Modulus-Exponent External Form
RSA Private Key Token, 4096-bit Chinese Remainder Theorem External Form
RSA Private Internal Key Token
RSA Private Key Token, 1024-bit Modulus-Exponent Internal Form for Cryptographic Coprocessor Feature
RSA Private Key Token, 1024-bit Modulus-Exponent Internal Form for PCICC, PCIXCC, CEX2C, or CEX3C
RSA Private Key Token, 4096-bit Chinese Remainder Theorem Internal Form
DSS Key Token Formats
DSS Public Key Token
DSS Private External Key Token
DSS 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
Trusted block section X'11'
Trusted block section X'12'
Trusted block section X'13'
Trusted block section X'14'
Trusted block section X'15'
Data Areas
The Cryptographic Communication Vector Table (CCVT)
The Cryptographic Communication Vector Table Extension (CCVE)
DES Master Key Verification Pattern Block (MKVB)
Generic Service Table (CSFMGST)
RMF Measurements Table
Appendix B. 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 3
Status Change Section
Subtype 4
Condition Code Three Section
Subtype 5
Special Security Mode Section
Subtype 6
Master Key Part Section
Subtype 7
KEU Key Part Entry Section
Subtype 8
Cryptographic Key Data Set Refresh Section
Subtype 9
Dynamic CKDS Update
Subtype 10
PKA Key Part Entry
Subtype 11
Clear New Master Key Part Entry
Subtype 12
PKSC Commands
Subtype 13
Dynamic PKDS Update
Subtype 14
PCI Cryptographic Coprocessor Master Key Entry
Subtype 15
PCI Cryptographic Coprocessor Master Key Entry
Subtype 16
PCI Cryptographic Coprocessor TKE
Subtype 17
PCI Cryptographic Coprocessor Timing
Subtype 18
Cryptographic Coprocessor Configuration
Subtype 19
PCI X Cryptographic Coprocessor Timing
Subtype 20
Cryptographic Coprocessor 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
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
Appendix C. CICS-ICSF Attachment Facility
Installing the CICS-ICSF Attachment Facility
Steps for installing the CICS-ICSF attachment facility
Implementing the CICS wait list
Appendix D. Helpful Hints for ICSF First Time Startup
Checklist for First-Time Startup of ICSF
Step 1. Hardware Setup - CCF Systems
Step 1. Hardware Setup - PCIXCC/CEX2C/CEX3C Systems
Step 2. LPAR Activation Profiles - CCF Systems
Step 2. LPAR Activation Profiles - PCIXCC, CEX2C, and CEX3C Systems
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
Appendix E. Using AMS REPRO Encryption
Steps for setting up ICSF
Appendix F. z890, z990, z9 EC, z9 BC, z10 EC, z10 BC, or z196 without a PCIXCC, CEX2C, or CEX3C
Applications and programs
Callable services
ICSF Setup and Initialization
Secure Sockets Layer (SSL)
TKE workstation
Notices
Programming Interface Information
Trademarks
Index
Copyright IBM Corporation 1990, 2014
z/OS Cryptographic Services ICSF System Programmer's Guide
z/OS Cryptographic Services ICSF System Programmer's Guide
Copyright IBM Corporation 1990, 2014
