Table of Contents (exploded view)
Abstract for z/OS Cryptographic Services Integrated Cryptographic Service Facility Administrator'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-V2R1 (FMID HCR77A1) as updated June 2014
Changes made in Cryptographic Support for z/OS V1R13-V2R1 (FMID HCR77A1)
Changes made in Cryptographic Support for z/OS V1R12-R13 (FMID HCR77A0)
Changes made in z/OS Version 1 Release 13 (FMID HCR7790)
Introduction
The Tasks of a Data Security System
The Role of Cryptography in Data Security
Symmetric Cryptography
The Data Encryption Algorithm and the Data Encryption Standard
Advanced Encryption Standard
Asymmetric Algorithm or Public Key Cryptography
The RSA Public Key Algorithm
Elliptic Curve Digital Signature Algorithm (ECDSA)
Cryptographic Hardware Features supported by z/OS ICSF
Crypto Express5 Feature (CEX5A, CEX5C or CEX5P)
Crypto Express4 Feature (CEX4A, CEX4C or CEX4P)
Crypto Express3 Feature (CEX3C or CEX3A)
Crypto Express2 Feature (CEX2C or CEX2A)
Crypto Express2-1P Feature
PCI X Cryptographic Coprocessor (PCIXCC)
CP Assist for Cryptographic Functions (CPACF)
CP Assist for Cryptographic Functions (CPACF) DES/TDES Enablement
PCI Cryptographic Accelerator (PCICA)
Identification of cryptographic features
Managing Crypto Express2 Features on an IBM System z9 EC, z9 BC, z10 EC, and z10 BC
Managing Crypto Express3 Features on an IBM System z10 EC, z10 BC, IBM zEnterprise 196, 114, BC12 and EC12
Managing Crypto Express4 Features on an IBM zEnterprise BC12 and EC12
Managing Crypto Express5 Features on an IBM z13
Strength of Hardware Cryptography
The Role of Key Secrecy in Data Security
Understanding cryptographic keys
Values of keys
Types of keys
Master keys
CCA operational keys
Symmetric keys
Data-encrypting keys
Cipher text translation keys
MAC keys
PIN keys
Key-encrypting keys
Key-generating keys
Cryptographic variable keys
Secure messaging keys
Asymmetric keys
Trusted blocks
PKCS #11 operational keys
Protection and control of cryptographic keys
Master key concept
Symmetric key separation
DES keys
AES and HMAC keys
Asymmetric key usage
Migrating from PCF and CUSP key types
Key strength and wrapping of key
Access control points
DES key wrapping
AES key wrapping
DES master key
Protection of distributed keys
Protecting keys stored with a file
Remote key loading
Using DES and AES transport keys to protect keys sent between systems
Using RSA public keys to protect keys sent between systems
Protection of data
Managing cryptographic keys
Managing CCA cryptographic keys
Generating cryptographic keys
Symmetric keys
Key Generator Utility Program (KGUP)
Key generate callable service
Services that import clear key values
Enhanced key management for crypto assist instructions
Encrypted key support for Crypto Assist instructions
Asymmetric keys
Entering keys
Entering master keys
Entering system keys into the CKDS
Entering keys into the CKDS
Entering keys by using the key generator utility program
Special secure mode
Entering keys by using the dynamic CKDS update services
Entering keys into the PKDS
Entering keys by using the dynamic PKDS update services
Maintaining cryptographic keys
CKDS
PKDS
Key Store Policy
Defining a Key Store Policy
Enabling access authority checking for key tokens
Determining access to tokens not stored in the CKDS or PKDS
Enabling duplicate key label checking
Increasing the level of authority needed to modify key labels
Increasing the level of authority required to export symmetric keys
Controlling how cryptographic keys can be used
Restricting asymmetric keys from being used in secure import and export operations
Restricting asymmetric keys from being used in handshake operations
Placing restrictions on exporting symmetric keys
Enabling PKA key management extensions
PKA key management extensions example
Enabling use of archived KDS records
Distributing CCA keys
Common Cryptographic Architecture Key Distribution
ANSI TR-31 key block
Public Key Cryptographic Standard Key Distribution
Managing PKCS #11 cryptographic keys
PKCS #11 Overview
Enterprise PKCS #11 master key
Managing tokens and objects in the TKDS
PKCS #11 and FIPS 140-2
TKDS key protection
Setting up and maintaining cryptographic key data sets
Setting up and maintaining the cryptographic key data set (CKDS)
Setting up and maintaining the PKA key data set (PKDS)
Setting up and maintaining the token data set (TKDS)
Key data set metadata
Metadata
Archiving and recalling a record in a key data set
Variable-length metadata blocks
IBM metadata blocks
Key material validity dates
Sharing KDS with older releases of ICSF and sysplex implications
Controlling who can use cryptographic keys and services
System authorization facility (SAF) controls
Cryptographic coprocessor access controls for services and utilities
Steps for SAF-protecting ICSF services and CCA keys
Setting up profiles in the CSFSERV general resource class
Setting up profiles in the CSFKEYS general resource class
Enabling use of encrypted keys in Symmetric Key Encipher and Symmetric Key Decipher callable services
Using the pass phrase initialization utility
Requirements for running the Pass Phrase Initialization Utility
SAF Protection
Running the Pass Phrase Initialization Utility
Steps for initializing a system for the first time
Steps for reinitializing a system
Steps for adding a CCA coprocessor after first time Pass Phrase Initialization
Steps to add missing master keys
Initializing multiple systems with pass phrase initialization utility
Managing CCA Master Keys
Identification of cryptographic features
Changes concerning the RSA master key (RSA-MK)
Changes concerning the DES master key
Coprocessor Activation
New Master Keys Automatically Set When ICSF Started
Entering master key parts
Generating master key data for master key entry
Steps for generating key parts using ICSF utilities
Steps for generating a checksum, verification pattern, or hash pattern for a key part
Steps for entering the first master key part
Steps for entering intermediate key parts
Steps for entering the final key part
Steps for restarting the key entry process
Initializing the CKDS and PKDS at First-Time Startup
CKDS
Steps for initializing a CKDS
Updating the CKDS with the AES master key
PKDS
Steps for initializing the PKDS
Updating the PKDS with the ECC master key
Performing a Local CKDS Refresh
Performing a Local PKDS Refresh
Reentering master keys when they have been cleared
Changing the master keys
Steps for enabling and disabling PKA callable services and Dynamic CKDS/PKDS Access
Symmetric Master Keys and the CKDS
Steps for reenciphering the CKDS and performing a local symmetric master key change
Asymmetric master keys and the PKDS
Steps for reenciphering the PKDS and performing a local asymmetric master key change
Steps for adding cryptographic coprocessors after initialization
Steps for clearing master keys
Managing Enterprise PKCS #11 Master Keys
Entering master key parts using TKE
First Time Use of Secure PKCS #11 Keys
Initialize or Update the TKDS
Changing the Master Key
Re-entering Master Keys after they have been cleared
Setting the Master Key
Key management on systems without coprocessors
Initializing the CKDS at first-time startup
Steps for initializing a CKDS
Local CKDS refresh
Callable services
Running in a Sysplex Environment
CKDS management in a sysplex
Setting symmetric master keys for the first time when sharing a CKDS in a sysplex environment
Using master key entry
Using pass phrase initialization
PKDS management in a sysplex
Setting asymmetric master keys for the first time when sharing a PKDS in a sysplex environment
Considerations when changing asymmetric master keys in a sysplex
TKDS management in a sysplex
Setting the P11 master key for the first time when sharing a TKDS in a sysplex environment
Changing PKCS #11 master keys when the TKDS is shared in a sysplex environment
Coordinated Change Master Key and Coordinated Refresh
Performing a coordinated refresh
Performing a coordinated change master key
Recovering from a coordinated administration failure
Coordinated change master key and coordinated refresh messages
New master key register mismatch
Cataloged failures
Mainline processing failure
Backout processing failure
Set master key failure
Back-level ICSF releases in the sysplex
Rename failures
Managing Cryptographic Keys Using the Key Generator Utility Program
Steps for disallowing dynamic CKDS updates during CKDS administration updates
Using KGUP for key exchange
Using KGUP control statements
General Rules for CKDS Records
CKDS record level authentication
KGUP Uniqueness Checking
Dynamic CKDS Update Services Uniqueness Checking
Key Store Policy Duplicate Token Checking
Access Control Points and Key Wrapping
Syntax of the ADD and UPDATE control statements
Using the ADD and UPDATE control statements for key management and distribution functions
To Import Keys
Import a Clear Key Value
Import an Encrypted Key Value for DES keys
To Generate Keys
Generate an Importer Key For File Encryption
Generate an AES data key
Generate a Complementary, Clear Key Value
Generate a Complementary, Encrypted Key Value
Generate a Complementary Key Pair For Other Systems
To Create NULL Keys
Create NULL Key Records
Syntax of the RENAME Control Statement
Syntax of the DELETE Control Statement
To Delete Keys
Syntax of the SET Control Statement
Syntax of the OPKYLOAD Control Statement
Examples of Control Statements
Example 1: ADD Control Statement
Example 2: ADD Control Statement with CLEAR Keyword
Example 3: ADD Control Statement with one TRANSKEY Keyword
Example 4: ADD Control Statement with two TRANSKEY Keywords
Example 5: ADD Control Statement with a Range of NULL Keys
Example 6: ADD Control Statement with OUTTYPE and TRANSKEY Keywords
Example 7: UPDATE Control Statement with Key Value and Transkey Keywords
Example 8: DELETE Control Statement
Example 9: RENAME Control Statement
Example 10: SET Control Statement
Example 11: OPKYLOAD Control Statement
Example 12: OPKYLOAD Control Statement for NOCV Key-encrypting Keys
Example 13 – ADD and UPDATE Control Statements with CLRDES and CLRAES Key Type
Example 14 – ADD and UPDATE Control Statement for a Group of CLRDES or CLRAES Keys with a Key Value
Example 15 – ADD and UPDATE Control Statements with ALGORITHM Keyword
Example 16 – ADD control statement to add a range of CLRDES keys
Example 17 – UPDATE control statement with CLRDES keyword
Example 18 – UPDATE control statement with CLRDES keyword
Example 19 – DELETE control statement with CLRDES keyword
Example 20 – DELETE control statement to delete a group of CLRDES key labels
Example 21 – RENAME Control Statement with CLRDES Keyword
Example 22 – ADD Control Statement with CLRAES Keyword
Example 23 – ADD Control Statement to Add a Group of CLRAES Keys
Example 24 – ADD Control Statement to Add a Group of CLRAES Keys
Example 25 – ADD Control Statement to Add a Range of CLRAES Keys
Example 26 – UPDATE Control Statement with CLRAES Keyword
Example 27 – UPDATE Control Statement with CLRAES Keyword
Example 28 – DELETE Control Statement with CLRAES Keyword
Example 29 – DELETE Control Statement to Delete a Group of CLRAES Key Labels
Example 30 – RENAME Control Statement with CLRAES Keyword
Example 31 – ADD Control Statement for ALGORITHM keyword
Example 32 – UPDATE Control Statement with the ALGORITHM keyword
Specifying KGUP data sets
Submitting a job stream for KGUP
Enabling Special Secure Mode
Running KGUP Using the MVS/ESA Batch Local Shared Resource (LSR) Facility
Reducing Control Area Splits and Control Interval Splits from a KGUP Run
Refreshing the In-Storage CKDS
Using KGUP Panels
Steps for creating KGUP control statements using the ICSF panels
Steps for creating ADD, UPDATE, or DELETE control statements
Steps for creating a RENAME control statement
Steps for creating a SET control statement
Steps for editing control statements
Steps for specifying data sets using the ICSF panels
Steps for creating the job stream using the ICSF panels
Example of a KGUP job stream with existing data sets
Example of a KGUP job stream with non-existing data sets
Steps for refreshing the active CKDS using the ICSF panels
Scenario of Two ICSF Systems Establishing Initial Transport Keys
Scenario of an ICSF System and a PCF System Establishing Initial Transport Keys
Scenario of an ICSF System and IBM 4765 PCIe and IBM 4764 PCI-X Cryptographic Coprocessors Establishing Initial Transport Keys
Viewing and Changing System Status
Identification of cryptographic features
Displaying administrative control functions
Displaying cryptographic coprocessor status
Changing coprocessor or accelerator status
Deactivating the last coprocessor
Displaying coprocessor hardware status
Displaying installation options
Display CCA domain roles
Displaying the EP11 domain roles
Displaying installation exits
Displaying installation-defined callable services
Managing User Defined Extensions
Display UDXs for a coprocessor
Display coprocessors for a UDX
Using the Utility Panels to Encode and Decode Data
Steps for encoding data
Steps for decoding data
Using the Utility Panels to Manage Keys in the PKDS
RACF Protecting ICSF Services used by the PKDS Key Management Panels
Generate a new RSA public/private PKDS key pair record
Delete an existing key record
Export a public key to an X.509 certificate for importation elsewhere
Import a public key from an X.509 certificate received from elsewhere
Processing Indicators
Success
Failure
Using PKCS11 Token Browser Utility Panels
RACF Protecting ICSF Services used by the Token Browser Utility Panels
Token browser panel utility
Steps to use the PKCS11 token browser panel utility
Token Browser main panel
Token Create Successful
Token Delete Confirmation
Token Delete Successful
Object Delete Successful
List Token panel
Token Details panel
Data Object Details panel
Certificate Object Details panel
Secret Key Object Details panel
Public Key Object Details panel
Private Key Object Details panel
Domain Parameters Object Details panel
Using the ICSF Utility Program CSFEUTIL
Symmetric Master Keys and the CKDS
Refreshing the in-storage CKDS using a utility program
Return and reason codes for the CSFEUTIL program
CSFWEUTL
Using the ICSF Utility Program CSFPUTIL
Asymmetric master keys and the PKDS
Refreshing the in-storage copy of the PKDS
Return and reason codes for the CSFPUTIL program
CSFWPUTL
Using the ICSF Utility Program CSFDUTIL
Using the Duplicate Token Utility
CSFDUTIL output
Return and reason codes for the CSFDUTIL program
CSFWDUTL
Rewrapping DES key token values in the CKDS using the utility program CSFCNV2
Using ICSF Health Checks
SAF Authorization for ICSF health checks
Accessing the ICSF Health Checks
ICSF_COPROCESSOR_STATE_NEGCHANGE
ICSF_DEPRECATED_SERV_WARNINGS
ICSF_KEY_EXPIRATION
ICSF_MASTER_KEY_CONSISTENCY
ICSFMIG_DEPRECATED_SERV_WARNINGS
ICSFMIG_MASTER_KEY_CONSISTENCY
ICSFMIG7731_ICSF_RETAINED_RSAKEY
ICSFMIG77A1_COPROCESSOR_ACTIVE
ICSFMIG77A1_TKDS_OBJECT
ICSFMIG77A1_UNSUPPORTED_HW
ICSF Panels
ICSF Primary Menu panel
CSFACF00 — Administrative Control Functions panel
CSFCKD20 — CKDS Operations panel
CSFCKD30 — PKDS Operations panel
CSFCMK10 — Reencipher CKDS panel
CSFCMK12 — Reencipher PKDS panel
CSFCMK20 — Change Master Key panel
CSFCMK21 — Refresh PKA Cryptographic Key Data Set panel
CSFCMK22 — Change Asymmetric Master Key panel
CSFCMK30 — Initialize a PKDS panel
CSFCMP00 — Coprocessor Management panel
CSFMKM10 — Key Data Set Management panel
CSFMKM20 — CKDS Management panel
CSFMKM30 — PKDS Management panel
CSFMKV00 — Checksum and Verification Pattern panel
CSFMKV10 — Key Type Selection panel
CSFPMC10 — Pass Phrase MK/CKDS/PKDS Initialization panel
CSFPMC30 — Pass Phrase MK/CKDS/PKDS Initialization panel
CSFPMC40 — Pass Phrase MK/CKDS/PKDS Initialization panel
CSFPMC20 — Pass Phrase MK/CKDS/PKDS Initialization
CSFPPM00 — Master Key Values from Pass Phrase panel
CSFRNG00 — ICSF Random Number Generator panel
CSFSOP00 — Installation Options panel
CSFSOP10 — Installation Options panel
CSFSOP30 — Installation Exits Display panel
CSFUTL00 — ICSF Utilities panel
Control Vector Table
Supporting Algorithms and Calculations
Checksum Algorithm
Algorithm for calculating a verification pattern
AES master key verification pattern algorithm
Pass Phrase Initialization master key calculations
The MDC–4 Algorithm for Generating Hash Patterns
Notations Used in Calculations
MDC-1 Calculation
MDC-4 Calculation
PR/SM Considerations during Key Entry
Allocating Cryptographic Resources to a Logical Partition
Allocating Resources
Entering the Master Key or Other Keys in LPAR Mode
Reusing or Reassigning a Domain
CCA access control points and ICSF utilities
Access Control Points
Callable services affected by key store policy
Summary of Key Store Policy (KSP) and Enhanced Keylabel Access Control interactions
Questionable (Weak) Keys