Skip to main content

Techdocs Library > Flashes >

Cryptographic Support for z/OS V1R13 - z/OS V2R1 (HCR77A1)

Document Author:

Sheri DeGroodt

Document ID:


Doc. Organization:

IBM Systems

Document Revised:


Product(s) covered:

# 2064; # 2066; # 2084; # 2086; # 2094; # 2096; # 2097; # 2098; ICSF; z9-109; z9 BC; z9 EC; z10; z10 BC; z10 EC; z114; z196; zEC12; zEnterprise; zEnterprise 196; zEnterprise EC12; z/OS

Abstract: The newest version of ICSF, FMID HCR77A1, called ‘Cryptographic Support for z/OS V1R13 – z/OS V2R1’ was announced on July 23, 2013 and available for download on Sept. 20, 2013 at the z/OS Download website ( This flash provides highlights of this updated component of z/OS.

This new version of ICSF provides support for the newest IBM mainframe, the zEnterprise BC12, or zBC12, which was announced on July 23, 2013 (see Announcement Letter #113-121) and the GA2 enhancements to the IBM zEnterprise EC12, or zEC12 also announced on July 23, 2013 (see Announcement Letter #113-119) . These enhancements provide support for the latest updates to the IBM Common Cryptographic Architecture and Enterprise PKCS #11, both of which are supported in the IBM crypto hardware. In addition, this new version of ICSF includes additional enhancements not specifically related to the new hardware.
The new capabilities include:
  • AP Configuration Simplification
  • KDS Key Utilization Statistics
  • Dynamic SSM
  • UDX Reduction and Simplification
  • Europay/Mastercard/Visa (EMV) Enhancements
  • Key wrapping and other security enhancements
  • OWH/RNG Authorization Access
  • SAF ACEE Selection
  • Non-SAF Protected IQF
  • RKX Key Export Wrapping
  • AES MAC Enhancements
  • PKCS #11 Enhancements
  • Improved CTRACE Support

Note that this version of ICSF drops support for the old CCF (Cryptographic Coprocessor Feature) machines (z800/z900 and earlier).

AP Configuration Simplification with Migration Check

Over the last several versions of ICSF, the logic for activating the Crypto Coprocessors that are assigned to the LPAR has changed. Historically, the DES-MK had to be loaded first to enable encryption, in general, however IBM realized that with the availability of AES encryption, some customers would never implement DES/TDES encryption and this requirement no longer made sense.

The goal of the new activation logic is to provide consistent support for the encryption algorithms that the customer wants to support. ICSF will, on a coprocessor-by-coprocessor basis, compare the Master Key Verification Pattern or MKVP (a hash of the actual key value) to the value of the MKVP stored in the header record associated with that algorithm (DES/TDES and/or AES in the CKDS, RSA and/or ECC in the PKDS and P11 in the TKDS). If a particular master key is loaded into the coprocessor (i.e. the master key is not binary 0s in the coprocessor), then its MKVP must match the MKVP stored in the appropriate header record of the keystore, otherwise the coprocessor will not be activated. If a particular master key is not loaded into the coprocessor (i.e. the MKVP is binary 0s) then it will not be checked against the current keystore. If all of the master keys loaded on a coprocessor match the key stores, that coprocessor will become active on the system and will be able to perform crypto operations for all algorithms.

For example, let’s assume that there are four coprocessors assigned to LPAR1 (COP #1, COP #2, COP #3 and COP #4), and the header record of the CKDS has a MKVP for both the DES-MK and AES-MK (i.e. the header record does not contain binary 0s in the respective MKVP fields). For simplicity, we’ll also assume that the RSA-MK and ECC-MK are not loaded in any of the coprocessors.

If the MKVP of the DES-MK in the header record matches all four coprocessors, then all four coprocessors will be eligible to be activated, pending the status of the checks on the AES-MK. Now suppose that the AES-MK loaded into COP #1 and COP #2 matches the AES-MK MKVP in the CKDS header record. Both COP #1 and COP #2 will be activated and will be able to process both DES/TDES and AES operations. Finally, if the AES-MK loaded into COP #3 and COP #4 does not match the header record of the CKDS, these coprocessors will have the status ‘Master key incorrect’ on the Coprocessor Management panel and will not be active. Even though the DES-MK is loaded correctly on COP #3 and COP #4, these two coprocessors will not be available (active) until the AES-MKs are corrected. As in previous versions of ICSF, the master key status can still be displayed via the Coprocessor Management panel.

Since prior versions of ICSF would activate any cards where the master key was loaded correctly, this change in activation logic means that migration to HCR77A1 could cause an outage. For example, in the above environment, running HCR7751, AES would have been supported on COP #1 and COP #2, but not on COP #3 and COP #4. If you upgraded ICSF to HCR77A1 in this environment, all AES operations would be prevented once HCR77A1 was activated.

To identify such issues, there is a new migration check to identify such an environment. The new check is ICSFMIG77A1_COPROCESSOR_ACTIVE and is available for HCR7770, HCR7780, HCR7790 and HCR77A0 via OA42011. The check will identify which coprocessors would become active when running HCR77A1, and which coprocessors have mismatched master keys and would not become active.

With HCR77A1, the master key change process will check the new master key registers for potential inconsistencies and prevent such a master key change. These checks coupled with the new KDS Administration support that was added in HCR7790 and HCR77A0 means that ICSF will not allow the coprocessors to get into an inconsistent state, even across a Sysplex sharing the key repositories.

KDS Key Utilization Statistics

In preparation for improvements in the area of key management, ICSF will now record additional metadata related to keys. The primary change will be the addition of a last referenced date/time stamp in the key token. The key tokens already contained date/time stamps for the creation date of the key as well as a last modified date/time stamp. The last referenced date/time stamps will be updated each time a particular key is targeted to be part of an operation, but not if it is just one item in a mass operation. For example, a re-encipher of a keystore will not change the last referenced date since the key was not specified individually. On the other hand, however, take the case of the CSNDSYX API exporting an AES or DES data key under an RSA or AES exporter key. Since both keys, the RSA or AES exporter key used to encrypt the data key and the AES or DES data key being encrypted and exported, are specifically being used to perform or are the target of a cryptographic operation, both will have their last reference date/time stamp updated by the API.

To implement this change, new fields have to be added to every key token in the keystores (CKDS/PKDS, TKDS), changing the record layout of each of the keystores. For efficiency, ICSF will now use a common KDSR Record Format across all three keystores. ICSF will continue to support the older keystore layouts. You can convert to the new KDSR Record Format by performing the equivalent of a coordinated master key change, but instead of reenciphering the operational keys, they will simply be written in the new record format. ICSF will not currently check this last referenced date/time stamp, but by converting to the new record format, it will start updating the field for use by utilities and tools in the future. If the keystores are being shared by multiple systems, all must be at HCR77A1 to migrate.

Because the size of the key tokens increase to support this change, there is a possibility that a TKDS token will be too large for the Token Key Dataset. There is a new migration check provided, via APAR OA42011 called ICSFMIG77A1_TKDS_OBJECT which will check for TKDS records that would exceed the size limit.

Dynamic SSM

Special Secure Mode (SSM) is an option that is specified at ICSF start-up and controls whether key material can be entered in the clear. SSM(YES) lowers the security of your system to allow you to load keys in the clear and generate clear PINs. Running SSM(NO) prohibits you from loading master keys via the PPINIT utility or the ICSF panels because the key material would exist in the clear within the environment. SSM(NO) also prohibits you from creating clear keys via KGUP or using the ICSF APIs.

With HCR77A1 you can now define a RACF profile, CSF.SSM.ENABLE in the XFACILIT class to set SSM to YES. If this profile does not exist, ICSF will use the SSM setting from the options data set. (The default is NO.)

The SSM setting impacts the ability to set master keys, especially at first-time start-up of ICSF. If running in COMPAT(YES) or COMPAT(COEXIST) mode, you cannot dynamically change a master key, but must either re-IPL the system or stop all crypto applications (especially those using PCF macros) to change the master key.

User Defined Extensions (UDX) Simplification and Reduction

UDX’s provide a way to install your own local code inside the secure tamper-resistant boundary of the Crypto Express card where it can run securely. This capability is important when you want to test or manipulate data (such as PINs) that require the hardware protection of an HSM. With the latest CEX4S card and this version of ICSF, several commonly used UDX’s have been incorporated into the CCA

  • Recover PIN from offset (CSFBPFO) –This new API will recover the customer-entered PIN using the PIN generation key, account information and an IBM-PINO offset, returning the result in a PIN block formatted to the specifications of the calling application.
  • Symmetric Key Export with Data (CSFDSXD) – will export a symmetric key, encrypted using an RSA key and inserted into a PKCS #1 block type 2.
  • Authentication Parameter Generate (CSFBAPG) – A Domain Parameter (not to be confused with Usage Domains) is a required input when generating Digital Signature Algorithm or Diffie-Hellman key pairs. Historically ICSF has generated this domain parameter via software, which is then passed to the hardware when the key pair is generated. With this new API, the domain parameter will be calculated in the secure hardware as part of the key generation process, improving performance of the API.

Multiple customers use these three UDX’s with small variations, so they have been incorporated into the CCA. The functions are now available to all customers, relieving the requirement to have the UDX updated every time either the crypto hardware is changed or a new version of ICSF is installed. Applications which currently use these UDXs can migrate to the new API, replacing the UDX.

Europay/Mastercard/Visa (EMV) Enhancements

EMV provides a global standard for inter-operation of integrated circuit cards and the point-of-sale terminals and ATMs that rely on them to authenticate credit and debit card transactions. The latest enhancement to the EMV standards includes support for TDES-CBC when generating diversified keys. The Diversified Key Generate (CSNBDKG) API has been enhanced to support the updated EMV specs.

Key Wrapping and other security enhancements

Key wrapping is the concept of encrypting another key. That is, if key material needs to leave the secure environment of the tamper-resistant, tamper-responding hardware, it should first be encrypted, by another key. The standards and best practices for key wrapping are constantly being revised and this version of ICSF provides a couple of enhancements to match these updates:

  • The Unique Key Derive (CSNBUKD) API now supports the generation of an Initial PIN Encrypting Key (IPEK) which can be loaded into an ATM or POS device and used to generate the same set of keys on the device as on the host
  • The Symmetric Key Import2 (CSNDSYI2) API has been updated to use enhanced wrapping where a DES key and it’s control vector are wrapped using an AES wrapping key
  • Fixed-length payload support for variable length symmetric key tokens – one problem with variable length tokens is that the length of the token may give an attacker an insight into the key material (i.e. the length). HCR77A1 will still use a variable length token, but you now have the option to store the key material into a fixed length section of the token, hiding the key length. Multiple APIs have been updated to support this new key token layout.

OWH/RNG Authorization Access

In HCR77A1 the customer can control whether a SAF check is performed for two common APIs: One-Way Hash (CSNBOWH) and Random Number Generate (CSNBRNG).

On previous generations of crypto hardware, the one-way hash was calculated on the secure crypto card, but with the current hardware this function is performed on the CPACF (clear key) hardware. This function is now available via assembler language instructions (KIMD, KLMD) and there is no way to secure these instructions. It does not make sense to continue to protect an API whose function can be performed by simply writing an assembler language routine.

The random number generate function is still performed on the crypto card and prior to HCR77A0 it still made sense to protect this API to prevent a Denial Of Service attack where the RNG API was called repeatedly preventing other users from accessing the card. Starting with HCR77A0 ICSF now provides caching support, where it will build a cache (actually multiple caches) of random numbers that can service requests for random numbers much more efficiently and quickly and reduce the impact of this DOS attack.

For compatibility, ICSF can still perform these SAF checks to ensure that the caller is authorized to perform these functions. However, by creating a CSF.CSFSERV.AUTH.CSFOWH.DISABLE or CSF.CSFSERV.AUTH.CSFRNG.DISABLE profile in the XFACILIT class, the respective SAF checks will be disabled, even if the CSFSERV class profiles exist.

SAF ACEE Selection

This new support allows an authorized caller (either system key or supervisor state) to override the default ACEE search by providing an ENVR object (a flattened ACEE). It provides z/OS Communications Server and other system components a way to provide the ACEE to be used for authority checking when performing work on behalf of another caller.

Non SAF-Protected IQF

Some of the information returned by the ICSF Query Facility (CSFIQF) API is returned from the Crypto Express card and requires that the caller be SAF authorized to use the API and access the card. This version of ICSF introduces a new API, CSFIQF2, that does not provide information specific to the cryptographic coprocessors and does not require SAF protection.

RKX Key Export Wrapping

The Remote Key Export (CSNDRKX) callable service uses a trusted block to generate or export DES keys for local use and for distribution to an ATM or other remote device. The API uses a special structure to hold encrypted symmetric keys in a way that binds them to the trusted block and is specifically designed for exporting PIN blocks to non-CCA systems. The API has been enhanced to allow rule array keywords to specify the wrapping mode (default, original or enhanced) when exporting the key.

AES MAC Enhancements

The Symmetric MAC Generate (CSNBSMG) and Symmetric MAC Verify (CSNBSMV) APIs have been enhanced to more closely align with RFC 3566 and RFC 4434, providing stronger security for z/OS Communications Server.

PKCS #11 Enhancements

Enterprise PKCS #11 (EP11) Mode was introduced with the previous release of ICSF, providing the ability to use secure keys (protected by the Hardware Security Module or HSM) with PKCS #11 APIs.

HCR77A1 adds additional support for Enterprise PKCS #11 including

  • Secure Diffie-Hellman and Elliptic Curve Diffie-Hellman keys
  • Key derivation using a secure key as a base key
  • Clear or Secure key RSA-PSS – PKCS #11 V2.1 introduced new signing/verifying digital signatures based on the Probabilistic Signature Scheme (PSS)
  • Offload DSA and Diffie-Hellman domain parameter generate
  • Allow compliance mode of a key to be changed
  • Allow clear key brainpool EC curves to be used in FIPS mode

Improved CTRACE Support

Hopefully you’ll never need to use it, but tracing support has been significantly enhanced with HCR77A1. ICSF will now rely on the Component Tracing available with z/OS for capturing trace data specific to ICSF. Tracing options are configurable, using a new member of SYS1.PARMLIB, called CTICSFxx. ICSF ships a default member, CTICSF00. The TRACEENTRY statement in the options data set has been deprecated.

This new support will be significantly more robust than the internal tracing that ICSF has provided in the past.

TKE 7.3

TKE 7.3 LIC is the latest version of the TKE application. It provides support for the new hardware capabilities that are supported by the zBC12 and GA2 of the zEC12 with HCR77A1. There is also new TKE hardware, FC #0842 available. TKE 7.3 will run on either this new hardware or the previous hardware feature, FC #0841.

Another significant enhancement with TKE 7.3 is the addition of an installation wizard that will take you through the steps needed to setup the TKE for the first time.

TKE 7.2 or TKE 7.3 is required to manage your zEC12 or zBC12.


ICSF, HCR77A1 provides exploitation support for all of the hardware functionality on the the Crypto Express4S on your zEC12 GA2 or zBC12. In addition, it provides performance and operational enhancements for your zEC12, zBC12, z196, z114, z10 EC and BC. You can download this new FMID from the z/OS Downloads website ( and install with SMP/E. As always, be sure to check the latest PSP buckets for recommended service for the HCR77A1 FMID. Also remember to use the FIXCAT category (IBM.Coexistence.ICSF.z/OS_V1R13-V2R1-HCR77A1) and keyword (ICSFA1C/K) for toleration searches. This will identify fixes that allow prior levels of ICSF to coexist with, and fallback from, HCR77A1.


Hardware; Software




IBM System z Family

S/W Pillar(s):

IBM System z Software




, ICSF, zEC12, zBC12, z196, z114, z10EC, z10BC, z9EC, z9BC, z9-109, zEnterprise, zEnterprise 196, z/OS

The Techdocs Library
Is this your first visit to Techdocs (the Technical Sales Library)?

Learn more

Techdocs QuickSearch