Security

In reviewing your installation security plan before installing ICSF, consider these points:

Controlling access to disk copies of the CKDS
You should determine which users and applications should have access to each copy of the CKDS on your system.

Note: The in-storage copy of the CKDS can be accessed only through ICSF functions such as callable services or the ICSF panels. To protect the in-storage copy of the CKDS, control who can use these services.
Controlling access to the PKDS
You should determine which users and applications should have access to the PKDS on your system.

Note: The in-storage copy of the PKDS can be accessed only through ICSF functions such as callable services or the ICSF panels. To protect the in-storage copy of the PKDS, control who can use these services.
Controlling access to the Key Generator Utility Program (KGUP)
Anyone who is running the KGUP can read and change an unprotected CKDS. To prevent unauthorized persons from using the KGUP, store the program in an APF-authorized library that is protected by the Security Server (RACF). KGUP is also protected by CSFSERV(CSFKGUP).
Controlling access to services
Users of the Security Server (RACF) can use the CSFSERV class to perform access checking and auditing of services. The CSFSERV class also protects critical administrative TSO panel utilities, such as changing the master key and refreshing a key data set. The audit records that are produced by these checks are SMF type 80 records.

In addition, the cryptographic coprocessors have access control for services and some panel utilities. These controls can be managed using the TKE workstation.
Controlling access to key material
Users of the Security Server (RACF) can use the CSFKEYS and CRYPTOZ classes to perform access checking and auditing of key material. The audit records that are produced by these check are SMF type 80 records.

Key stores collectively refers to the Cryptographic Key Data Set (CKDS) and Public Key Data Set (PKDS) and their contents. ICSF provides additional security options for key material that are referred to as Key Store Policy. The audit records that are produced by these checks are SMF type 82 records.
Key token authorization checking controls
ICSF will verify, when an application passes a callable service a key token instead of a key label, that the user has authority to the secure token. ICSF does this by identifying key labels associated with the key token so that a SAF authorization check (which depends on key labels) can be carried out against profiles in the CSFKEYS class. An audit record is produced when the key token is not authorized.
Default key label checking controls
Administrators can define what happens when a key token is passed to a callable service instead of a key label.
Duplicate key token checking controls
ICSF prevents applications and the Key Generator Utility Program (KGUP) from storing duplicate tokens in a CKDS or PKDS.
Granular key label access controls
Administrators can raise the level of access authority required to create, write to, or delete a key label.
Symmetric key label export controls
Administrators can raise the level of access authority required to export a symmetric key (transfer it from encryption under a master key to encryption under an application-supplied RSA public key) when an application calls the Symmetric Key Export callable service (CSNDSYX or CSNFSYX). In this case, a SAF authorization check is performed against profiles in the XCSFKEY class rather than the CSFKEYS class.
PKA key management extensions controls
Administrators can set additional restrictions on how keys can be used. These additional restrictions are specified in the ICSF segment of CSFKEYS (or XCSFKEY) profiles. Using the ICSF segment of profiles in these classes, you can:
- Specify that asymmetric keys covered by the profile cannot be used for secure export or import operations.
- Specify that asymmetric keys covered by the profile cannot be used in the handshake operations performed by the Digital Signature Generate (CSNDDSG and CSNFDSG), Digital Signature Verify (CSNDDSV and CSNFDSV), PKA Encrypt (CSNDPKE and CSNFPKE), and PKA Decrypt (CSNDPKD and CSNFPKD) callable services.
- Specify whether symmetric keys covered by the profile can be exported using the Symmetric Key Export callable service (CSNDSYX or CSNFSYX). If allowing the symmetric keys covered by the profile to be exported, you can specify which asymmetric keys can be used to perform the export operation. You can specify this by supplying a list of labels of RSA keys in the PKDS, or a list of certificates in either a PKCS #11 token, or a SAF key ring.
Key store record archiving
ICSF administrators determine which records in the key data sets are unused and can be deleted. Administrators can mark key data set records are archived. These records cannot be used by an application unless the administrator allows their use through an optional control. An audit record is produced for the use of an archived record. An optional joblog message can be issued for the first attempt that an archived record is used.
Key material validity
ICSF administrators can define a period when the key material of a key data set record can be used by applications. Any attempt to use the record outside of the validity dates causes the service request to fail and produce an audit record.

You should familiarize yourself with the controls that you can enable and decide on the Key Store Policy that is best for your installation.
Enforcing PIN block restrictions
Requirements in the ANSI X9.8 PIN standard intended to guard against PIN block attacks can be implemented by enabling certain access control points on the Crypto Express3 Coprocessor using the optional Trusted Key Entry (TKE) workstation. These access control points are:
- 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
When enabled, these access control points limit the capabilities of the following callable services:
- Clear PIN Generate Alternate (CSNBCPA and CSNECPA)
- Encrypted PIN Translate (CSNBPTR and CSNEPTR)
- Secure Messaging for PINs (CSNBSPN and CSNESPN)
Scheduling changes for cryptographic keys
To reduce the possibility of exposing a key value, you may want to change the value of cryptographic keys, including master keys, from time to time:
- You can use the ICSF panels to change the DES, AES, ECC and RSA master keys.
- If you have an optional Trusted Key Entry (TKE) workstation installed, you can use it to change DES, AES, ECC and RSA master keys on all cryptographic coprocessors.
- You can use KGUP or the ICSF panel to change the CKDS.
- You can develop applications that use the dynamic CKDS update callable services to change both the in-storage and DASD copies of the CKDS.
- You can develop applications that use the dynamic PKDS update callable services to change both the in-storage and DASD copies of the PKDS.
You can perform all of these operations without interrupting cryptographic functions.
Allowing or preventing clear cryptographic keys
With ICSF, keys exist in the clear only in these cases:
- if you specifically allow special secure mode, applications can use the Clear PIN Generate, Secure Key Import, Secure Key Import2, and Multiple Secure Key Import callable services. Access control points for these services must be enabled.
- If ICSF is not in special secure mode, most keys in the system are encrypted except DATA keys that a user may enter through the use of the clear key import callable service. CLRAES and CLRDES keys are also not encrypted.
  Note: The clear key import callable service is equivalent to the PCF EMK macro.
- The encode callable service can use a clear key to encipher data.
- If you use the Master Key Entry panels to enter the key parts of a master key, the key parts appear briefly in the clear in host storage.
- Clear keys are used to provide improved performance for the DES, TDES and AES algorithms. Symmetric key encrypt and decrypt services (CSNBSYD and CSNBSYE) are available on all CP's.
Sending cryptographic keys to other installations
To eliminate the need to have a courier deliver clear keys between installations, you can use either or both of these options:
- AES and DES transport keys to encrypt CCA keys or TR-31 key blocks for network distribution.
- The receiving installation's RSA public key to encrypt a DES or AES DATA key prior to electronic distribution.
Both of these methods make key distribution more secure.
Controlling access to the disk copies
You should determine which users and applications should have access to each DASD copy of the CKDS, PKDS and TKDS on your system.
SMF records generated by ICSF
ICSF generates type 82 records in the SMF data set when these conditions occur:
- ICSF starts.
- A cryptographic processor is configured online or offline.
- When the in-storage CKDS is refreshed.
- When the in-storage PKDS is refreshed.
- You use the ICSF panels to process an operational key loaded using the TKE workstation.
- When an application uses any of the dynamic services that updates the CKDS.
- When an application uses any of the dynamic services that updates the PKDS.
- When you use the Master Key Entry panels to enter a master key in the cryptographic coprocessor.
- When you create or delete a retained key on a coprocessor.
- When you use the TKE workstation to communicate with cryptographic coprocessors.
- To capture measurements of timing and configuration for the cryptographic feature coprocessor or accelerator.
- When ICSF joins or leaves the ICSF sysplex group.
- When you use the Trusted Block Create callable service to create or activate a trusted block.
- When you use the PKCS #11 token management callable services to create or delete a token or object or to modify an attribute value of an object.
- When the security administrator has indicated that duplicate key tokens must be identified.
- When a callable service fails a key store policy check.
- When TKE audit records are processed.
- When CKDS, PKDS, or TKDS metadata is changed.
- When an archived or inactive CKDS, PKDS, or TKDS record is referenced.
The SMF record type 82 subtype indicates the type of event that caused ICSF to write the SMF record. For subtypes that log state changes, the SMF record will contain additional audit information about the server user and, optionally, the end user.

You can also use the Security Server (RACF) or an equivalent product to record attempts to use protected cryptographic keys or functions.
Recording and formatting type 82 SMF records in a report
Sample jobs are available (in SYS1.SAMPLIB) to assist in the recording and formatting of type 82 SMF data:
- CSFSMFJ - JCL that executes the code to dump and format SMF type 82 records for ICSF. Before executing the JOB step, you need to make modifications to the JCL (see the prologue in the sample for specific instructions). After the JCL has been modified, terminate SMF recording of the currently active dump dataset (by issuing I SMF) to allow for the unloading of SMF records. After SMF recording has been terminated, execute the JCL. The output goes into the held queue.
- CSFSMFR - An EXEC that formats the SMF records into a readable report.
Recording and formatting type 80 SMF records in a report
RACF provides support to log type 80 SMF records when a user attempts to access an ICSF service, utility, or key label when a profile is defined for the service, utility or label. See the z/OS Security Server RACF Auditor's Guide for guidance on how to activate this logging and to format the type 80 SMF records.