Authors: Richard Kisley, Jimmy Hill, Orion Hayes, Laura Reeve, Mike Miele

This article introduces the updates for the Common Cryptographic Architecture (CCA) 8.1 for Linux on IBM Z.

Audience:

Users of CCA for payment or cryptography applications on 

• CCA for Linux on IBM Z,

• For the newly introduced IBM Z16, as well as the IBM Z14 and IBM Z15, which receive function updates as applicable when new firmware is applied and the new CCA library is used.

What is CCA?

CCA is both an Architecture and a set of APIs.  It provides:

• Crypto algorithms and secure key management

• Specialized functions for banking and payment network interoperability

• A common API and architecture for all IBM z, Cognitive and x64/x86 server platforms

• Over 156 APIs with more than 1000 options, from ASC X9 TR-31 key support to ASC X9 TR-34 mutually authenticated RSA/certificate based TDES and AES key exchange, as well as traditional PIN-secured transaction processing and other support for core banking functions and major payment network key derivation and cryptograms.

What are the updates?

The last update was: CCA 8.0 for CEX8S for Linux on IBM Z16.

This update, CCA 8.1 for CEX8S for Linux on IBM Z16, adds the following features, described in more detail below:

• TR-31 (X9.143) native key block support in operational APIs, not just for key transport

• Combined Key Store: simplified approach to key storage

• SHA-3, for hash and digital signature generation/verification

• CCA Host support to send SHA3 requests to the CPACF

• OAEP 2.1 encoding for RSA encryption, decryption

TR-31 Support in CCA 8.1

X9.143 is a security standard that details the first international standard key-block format for financial services, referred to as the TR-31 key block. Having support for a standardized key block format makes it more convenient for CCA users to exchange keys with other systems. 

The CCA 8.1 release adds support to build, send, receive, and use TR-31 key blocks natively in over 70 CCA services that use symmetric keys, wrapped by the MKs in the CEX8S. Key storage is also updated to support TR-31 key blocks. The changes in CCA 8.1 will also make it simple to migrate keys between CCA and TR-31 key blocks. Please note that there is no requirement for users to switch to TR-31 key blocks; support for CCA proprietary key blocks will remain and grow.

The new TR-31 Create (CSNBT31C) service can be used to generate a complete internal or external TR-31 key block, or to generate a skeleton that can be populated with a key using CSNBKPI2. Users can also generate a compliance-tagged TR-31 key block, add optional blocks and set many restrictions using CSNBT31C. CSNBT31X and CSNBT31I also have enhancements to support changing between CCA and TR-31 key blocks. Please see the LoZ CCA 8.1 Application Programmer’s Guide for more information on how to use these services.

CCA 8.1 adds a new proprietary IBM optional block for internal TR-31 tokens to show whether a key is compliance tagged. This is similar to the compliance-tag in the CCA TDES, AES and RSA tokens. Users can call CSNBKTR2 to compliance-tag a TR-31 key block.

The optional blocks (OBs) support has been greatly enhanced in X9.143, which is reflected in CCA 8.1. Below are a few of the interesting new OBs:

1. Time of Creation (TC) and Time Stamp (TS): These two OBs contain the UTC date/time of 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. Note that this is NOT the same as the key label used with key storage, but rather it is similar to the label that can be stored inside a CCA AES X’05’ key token.

3. Derivation Control (DA): Used solely for ‘B3’ key derivation keys (KDKs), this OB lists which keys can be derived from the key in the key block. This makes it simple for users to restrict how a KDK can be used.

4. Wrapping Pedigree (WP): This OB marks 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 if the key gets rewrapped.

5. Key Check Value (KC): This OB contains the key check value for the key in the key block.

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

For more info, please see the following:

• LoZ CCA 8.1 Application Programmer’s Guide

• CryptoCard page

• X9.143 Specification

New Combined Key Store

The Combined Key Store (CKS) supports AES, HMAC, DES, PKA (ECC, RSA), and PQA (Crystals-Dilithium, Crystals-Kyber) keys in both the CCA and TR31 formats all within the same key store. Keys can be created directly in the CKS or migrated from existing key-type specific key stores. The following new services were added for the CKS:

• CSNBCKRC: Combined Key Store Key Record Create

• Creates a key token record in the CKS.

• CSNBCKRD: Combined Key Store Key Record Delete

• Deletes either an entire key record or the key token from the record in the CKS.

• CSNBCKRL: Combined Key Store Key Record List

• Creates a key-record-list containing information about specified key records in the CKS.

• CSNBCKRR: Combined Key Store Key Record Read

• Reads a key token from the CKS.

• CSNBCKRW: Combined Key Store Key Record Write

• Writes an internal or external key token into the CKS.

For service specific details, please refer to the LoZ CCA 8.1 Application Programmer’s Guide.

Migrating Keys from AES, DES, or PKA Type Specific Key Stores into the Combined Key Store

The panel.exe utility can be used to migrate existing AES, DES, and PKA keys from the type specific key stores into the CKS. Once migrated, future operations on those keys can be performed using the new CKS services or by configuring the environment to use a new “redirect” feature, which redirects all key store services to the CKS.

Example Key Store Migration Using Panel

To migrate AES keys from the AES type specific key store into the CKS, the following panel.exe command would be used:

Redirect Key Type-Specific Key Store services to the CKS

Once the keys are migrated into the CKS, two options are available for future key management operations. The first option is to switch application code to use the CKS services. The second option uses the re-direct environment variables to allow continued use of the existing key-type specific services:

• DES_USE_CMB_KS - Redirects DES key-store calls (e.g., CSNBKRR, CSNBKRW, etc.)

• AES_USE_CMB_KS - Redirects AES key-store calls (e.g., CSNBAKRR, CSNBAKRC, etc.)

• PKA_USE_CMB_KS - Redirects PKA key-store calls (e.g., CSNDKRR, CSNDKRD, etc.)

Note: The environment variables must be set prior to library initialization at application startup.

Example of setting the environment to redirect AES key-store specific services to the CKS:

SHA-3 Support

SHA-3 was standardized by NIST in 2015. The CCA 8.1 release adds SHA-3 to the CSNBOWH, CSNDDSG, and CSNDDSV services:

• SHA3-224

• SHA3-256

• SHA3-384

• SHA3-512

Note: The SHA3 instances are not supported with the PKCS-1.0, PKCS-PSS, nor X9.31 RSA formatting methods in the CSNDDSG and CSNDDSV services.

CCA 8.1 also adds support for CPACF accelerated SHA3 processing. The environmental variable CSU_HCPUACLR is used to to enable CPACF use. This can also be done using the CSUACRA service with the HCPUACLR keyword.

OAEP 2.1 Support

Optimal Asymmetric Encryption Padding (OAEP) is a method of encoding plaintext to be used in RSA encryption to permit different ciphertexts to be created from the same plaintext. This provides defense against chosen plaintext attacks. CCA 8.1 for Linux on Z 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.