IBM Crypto Education Community - Group home

ICSF introduces new support for CCA Release 8.1

By GREGG ARQUERO posted Wed May 17, 2023 11:00 AM


Authors: Gregg Arquero, John Craig, Richard Kisley, Michael Miele, Jimmy Hill, Laura Reeve

With APAR OA61978, ICSF shipped new functionality in support of CCA Release 8.1 for z16. This APAR is available on ICSF FMID’s HCR77D1 and HCR77D2. An accompanying coexistence APAR, OA63657, is available for ICSF FMIDs HCR77C0 - HCR77D2 and is recommended when OA61978 is applied and sysplex sharing is enabled with an ICSF release where key block exploitation is unavailable. OA61978 includes the addition of the RSAES-OAEP v2.1 encryption/decryption scheme as well as the much-awaited expansion of TR-31 key block functionality. In this article we will take a look at the extent of these improvements and what they mean for z/OS users.


TR-31 is an interoperable key exchange key block format originally defined by the American National Standards Institute (ANSI) Accredited Standards Committee (ASC) in ASC X9 TR 31-2005. This has been updated and recently standardized in ANSI X9.143-2022. As a standard this provides a set of requirements for those that claim to implement X9.143-2022. While the backing document is now X9.143, the common reference name is still ‘TR-31 Key Block’, although another name has been proposed - the X9 Symmetric Wrapped Key Block or X9-SWKB.

Previously, ICSF’s support for TR-31 key blocks was limited to allowing the exchange of CCA key tokens as external TR-31 key blocks via import and export services. The existing ICSF TR-31 callable services: TR-31 Import (CSNBT31I), TR-31 Export (CSNBT31X: renamed now to TR-31 Translate), TR-31 Parse (CSNBT31P), TR-31 Optional Data Build (CSNBT31O), and TR-31 Optional Data Read (CSNBT31R) have been enhanced with this release. 

Internal/’native’ TR-31 support

This release adds support for the generation of new AES, DES, or HMAC internal and external TR-31 key blocks or skeletons using a new callable service, TR-31 Create (CSNBT31C & CSNET31C). Note that internal key blocks are encrypted under the Main wrapping Key(MK), while external key block are encrypted under a Key Encrypting Key (KEK). TR-31 Translate (CSNBT31X & CSNET31X) can also be used to translate an existing CCA key token to an internal operational TR-31 key block.

ICSF and CCA 8.1 now support the use of internal symmetric TR-31 key blocks as operational keys in over 70 services. The TR-31 key blocks can be passed directly into ICSF cryptographic callable services in the same manner as CCA key tokens. The majority of ICSF services and utilities that support symmetric CCA tokens have been updated to support symmetric TR-31 key blocks. Exceptions include: deprecated services, EMV simplification services, TKE operational key load, and Key Generator Utility Program (transport key support only).

PCI compliance-tagged TR-31 key blocks

The updates services also support TR-31 PCI-HSM compliance-tagged key blocks, which follow the same standards that CCA key blocks must meet to be compliance-tagged. Note: not all TR-31 key blocks or key management are compliant under PCI (e.g. single DES, keys wrapped with a weaker key), so a new IBM TR-31 proprietary optional block was added with the compliance-tag support. The CSNBKTC2 service may be used to test whether a TR-31 key block will be allowed to migrate to compliance-tag, and to migrate a TR-31 key block when the coprocessor domain is in PCI-HSM migration mode. 

CKDS and TR-31 key blocks

ICSF also supports the storage of symmetric TR-31 key blocks in the CKDS when using the large common record format (KDSRL) introduced in HCR77D2. Since ICSF FMID HCR77D1 does not support KDSRL format key data sets (KDS), symmetric TR-31 key blocks cannot be stored in the CKDS. TR-31 Key blocks cannot be referenced by label in a callable service but can be passed in directly. In addition, there will be no ability to browse TR-31 key blocks with the CKDS keys utility on HCR77D1 and CKDS reenciphers must be initiated from a HCR77D2 or later system if KDS sysplex sharing is enabled.

Valuable TR-31 key block features

One significant feature of TR-31 key blocks is support for extension through optional blocks (OBs), which have been greatly enhanced in X9.143. Below are a few of the interesting new OBs that have been added to the CCA API:

  1. Time of Creation (TC) and Time Stamp (TS): These two OBs contain the UTC date/time for when the key block was created (TC) and when it was last changed (TS).

  2. Label (LB): This OB contains an optional, user-defined label for the key. While this key label is not tied to the label under which the key is stored in CKDS, it is similar to the label that can be stored with a CCA AES X’05’ key token and can be a useful label binding method.

  3. Derivation Control (DA): Used solely for ‘B3’ key derivation keys, this OB lists out which keys can be derived from the key token by specifying the allowed algorithm, usage, mode of use and exportabiity for derived keys. Enforced by CEX8S CCA firmware, this is an important control over the allowed derivation results of a base key.

  4. Wrapping Pedigree (WP): This OB tracks whether the key in the key block has ever been wrapped by a key weaker than itself. This block can only be added when the key is initially created and will be modified by CCA 8.1 firwmare if the key gets re-wrapped.

  5. Key Check Value (KC): This OB contains the key check value (KCV) for the key in the key block. The CMAC method is the documented method of KCV for TDES and AES keys.

  6. IBM Proprietary block: This block includes IBM specific compliance-tag indicators and CPACF export controls.

OAEP 2.1

Optimal Asymmetric Encryption Padding (OAEP) is a method of formatting plaintext to be used in RSA encryption to permit different ciphertexts to be created from the same plaintext. This encryption scheme provides defense against chosen plaintext attacks. ICSF now supports version 2.1 of this scheme in its PKA Encrypt (CSNDPKE) and PKA Decrypt (CSNDPKD) services, improving upon its existing support for OAEP 2.0. Three additional SHA algorithms: SHA-224, SHA-384, and SHA-512 have also been added for use with OAEP v2.1.

For more info

Please see the following: