IBM Crypto Education Community - Group home

CCA 8.0 for Linux on IBM Z

By Richard Kisley posted Mon May 22, 2023 09:45 PM


Authors: Richard Kisley, Michael Miele, Jimmy Hill, Orion Hayes

This article introduces the updates for the Common Cryptographic Architecture (CCA) 8.0 for Linux on IBM Z16. The CCA 8.0 software download is also the best way to receive all updates for CCA 7.4 for CEX7S on IBM Z15, as well as CCA 6.7 for CEX6S on IBM Z14. 

Update 16-Jun-2023: Description & link for sample code added.


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.

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?

This update for Linux and CCA firmware on IBM Z is: CCA 8.0 for Linux on IBM Z, supporting CEX8S on IBM Z16 adds support the following features:

  • QSA Secure Key and Dual Signature Update, with Hybrid Quantum Safe Key Exchange Scheme
  • TLS protection for Trusted Key Entry (TKE) workstation communication
  • Australian Payment Network (APN) Key Derivation & MAC Generation/Verification
  • Schnorr Digital Signature Algorithm (EC-SDSA)
  • Key Translation from CCA Token to PKCS #11 Format (Azure Key Exchange Support)
  • New API: Encrypted PIN Verify2 (CSNBPVR2)
  • TR-34 Expiration Checking for Certificates & Revocation Lists
  • Enhancements for TR-31 Symmetric Key Management
  • Wrap Enhanced Method 3 (WRAPENH3) Configuration Management
  • 24KB Message Size Support

Supported distros & versions:

CCA 8.0 was initially tested with the following Linux on IBM Z distributions

  •  Ubuntu 20.04LTS
  •  Red Hat Enterprise Linux 8 Update 6
  •  Red Hat Enterprise Linux 7 Update 9
  •  SUSE Linux Enterprise Server 15 SP 4

QSA Secure Key and Dual Signature Support

This release adds Linux on Z CCA library support for CCA CEX8S implementations of NIST Quantum-Safe algorithm standardization candidates CRYSTALS-Kyber and CRYSTALS-Dilithium. The updates include

  • QSA Token: updated for the new Round 3 algorithm versions and higher strength/longer key sizes.
  • OIDs for the New QSA key types and sizes:
    • CRYSTALS-Dilithium (8,7), NIST Round 2 with OID:
    • CRYSTALS-Dilithium (8,7), NIST Round 3 with OID:
    • CRYSTALS-Dilithium (6,5), NIST Round 3 with OID:
    • CRYSTALS-Kyber (1024), NIST Round 2 with OID:
  • QSA Programming Interface Changes:
    • Dual/hybrid-signed health queries (CSUACFQ) with Elliptic Curve and CRYSTALS-Dilithium signatures.
    • Updated QSA key tokens, key generation and management (CSNDPKB, CSNDPKG, CSNDPKI, CSNDPKX, CSNDKTC)
    • Export of a QSA token under an AES KEK (CSNDPKT:)
    • Generate & verify a Dilithium signatures using the new Dilithium keys (CSNDDSG & CSNDDSV:).
    • Use Kyber keys for data encryption (CSNDPKE, CSNDPKD).
    • Exploit a full hybrid Elliptic Curve & Quantum Safe Algorithm (Dilithium & Kyber) Key Exchange System through the CCA API, with full path strength of AES-256 equivalence (CSNDPKE, CSNDEDH).

Sample code

The cca_qsa_keygen_sign_verify sample generates a QSA public/private key pair for Crystals Dilithium (6,5) and uses that key pair to sign and verify some sample data. This sample can be used to assist in the development of a working software program that intends to sign or verify a message using a QSA (Dilithium) key.  Link to Sample Code:

TLS Connection for TKE Communication

Communication between the TKE workstation and the catcher.exe daemon can now be secured with a TLS connection. While key exchanges were always encrypted and the full path from the TKE to the CCA card has always been protected to the strongest cryptography available, the addition of TLS for public network hops adds extra peace of mind. The installation and start-up script queries the OpenSSL version and will default to TLS mode if available. For more, refer to section, "TKE catcher configuration for a TLS connection" in the "Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide Version 8.0".

Australian Payment Network (APN) Key Derivation & One-Way Function (OWF)

Support for the Australian Payment Network (APN) key derivation and MAC generation (based on standard AS2805.5.4) has been added in the CCA 8.0 release. Key generation is enhanced for APN support in Diversified Key Generate (CSNBDKG) and Random Number Generate Long (CSNBRNGL). Further, Symmetric Algorithm Encipher (CSNBSAE) is updated to generate and verify the APN One Way Function (OWF).

Elliptic Curve - Schnorr Digital Signature Algorithm (EC-SDSA)

Support for the ISO/IEC 14888 Elliptic Curve - Schnorr Digital Signature Algorithm (EC-SDSA) has been added to the Digital Signature Generate (CSNDDSG) and Digital Signature Verify (CSNDDSV) verbs. Use ECC curves secp256r1 (P256) and secp521r1 (P521). Note that SHA-256 must be used with P256 and SHA-512 with P521.

CCA Token to PKCS #11 Format (Cloud/Hyperscaler) Key Exchange

To enhance key exchange with applications that use PKCS #11, which includes popular Cloud/Hyperscalers, two services: PKA Key Translate (CSNDPKT) and Symmetric Key Export (CSNDSYX), now allow key translation from a CCA token format to the PKCS #11 object format. The PKCS #11 mechanism called CKM_RSA_AES_KEY_WRAP is supported for translation of an RSA or ECC private key, or an AES CIPHER key, to an AES wrapped PKCS #11 object.

When using CKM_RSA_AES_KEY_WRAP the RSA KEK must be an RSA-public key with a modulus length of 4096-bits, 3072-bits, or 2048-bits. However, with the access-control points (ACPs) "Prohibit weak wrapping - Transport keys" (X'0328') or "Warn when weak wrap - Transport keys" (X'032C') set to binary '1', the usable RSA keys are limited, thus impacting the usefulness of CKM-RAKW. Changing these ACP should be met with caution for any wider impact. To allow narrower scope a new ACP, "CKM_RAKW - Allow RSA2048 to wrap stronger keys (e.g., AES-128, 192, 256)" (X'033E') has been added which allows for a relaxed RSA KEK strength when used with CKM-RAKW.

New API: Encrypted PIN Verify2 (CSNBPVR2)

A new verb Encrypted PIN Verify2 (CSNBPVR2) was introduced in the CCA 8.0 release. The CSNBPVR2 service validates a customer encrypted PIN-block against a reference encrypted PIN block. You can specify these PIN-block formats: IBM 3624, ISO-0 (same as ANS X9.8, VISA-1, and ECI-1), ISO-1 (same as ECI-4), ISO-2, ISO-3, ISO-4.

The service also supports truncated customer PINs, optionally verifying an indicated number of PIN digits (minimum of 4) that is less than the number of digits for the reference PIN. Both DES-DUKPT (ANSI x9.24-1 2007) and AES-DUKPT (ANSI x9.24-3 2017) are also supported.

TR-34 Expiration Checking for Certificates & Revocation Lists

There were 2 important enhancements for the TR-34 symmetric key management in CCA 8.0: Larger CRLs are now supported for TR-34 Bind-Begin (CSNDT34B) and TR-34 Key Distribution (CSNDT34D). The new manximum crl_length is 6000 bytes, although this must be balanced against other paramenters. While CRL and KRD certificate date checking was already supported in all four TR-34 verbs (CSNDT34B, CSNDT34C, CSNDT34D, & CSNDT34R), this handling can now be modified to return either an error or an informational message.

Enhancements for TR-31 Symmetric Key Management

TR-31 symmetric key management is significantly enhanced in CCA 8.0 to ease interchange with major payment networks, updating the Key Export to TR31 (CSNBT31X) and TR31 Key Import (CANBT31I) verbs.

  • The TR-31 'N' Mode of Use is now allowed with B, C, and D wrapping methods. The Key Usages that allow 'N' Mode of Use in verbs CSNBT31X and CSNBT31I are the following:
    • 'B0'
    • 'E0', 'E1', 'E2', 'E3', 'E4', 'E5'
    • 'V0', 'V1', 'V2'
  • The CSNBT31X verb now allows export of a CCA Key Encrypting Key (KEK) as a 'K0' Key Usage with 'B' Mode of Use.

Wrap Enhanced Method 3 (WRAPENH3) Configuration Management 

The WRAPENH3 DES key wrapping method, introduced in the CCA 7.3 release, is a Payment Card Industry (PCI) PIN compliant wrapping method that has been independently reviewed for compliance.  The WRAPENH3 method includes enhanced key bundling with length obfuscation, as well as a message authentication code (MAC) for integrity protection. This method does not use legacy 'variant' processing methods such as XOR of the key attributes. IBM fixed-length TDES key blocks with WRAPENH3 are supported in all (non-deprecated) CCA services where TDES keys are used.

For more info:

1 comment


Mon June 12, 2023 06:32 AM

Are samples for CCA 8.0 provided also? Where can I found them? Thank you in advance !

Thank you for updating with Samples !