Authors: Richard Kisley, Rumeel Jessamy, John Craig, Benedikt Wenz, Eric Rossman
This article describes how to use the ML-DSA and ML-KEM updates for the Common Cryptographic Architecture (CCA) 8.4 and Enterprise PKCS #11 (EP11) on z/OS and Linux for IBM Z — with sample code.
Audience:
Users of CCA and EP11 for cryptography applications on
What is CCA?
CCA is both an Architecture and a set of APIs. It provides:
-
Crypto algorithms and secure key management
-
Specialized & standard functions for banking and payment network interoperability across 156 APIs
-
A common API and architecture for all IBM z, Cognitive and x64/x86 server platforms
What is EP11?
EP11 is a stateless enterprise-grade and HSM-based implementation of the PKCS #11 standard interface. It provides:
-
Crypto algorithms and secure key management corresponding to PKCS #11 standard mechanisms
-
Specialized functions for uses cases like ethereum support (BLS12-381, EIP2333), digital asset support (BIP32, SLIP10) and data re-encryption inside the HSM
What are ML-KEM and ML-DSA?
-
ML-KEM (FIPS 203) is a post-quantum encryption/key encapsulation algorithm. It allows secure key exchange over an insecure channel, protecting against quantum attacks. While ML-KEM is often used in hybrid key exchange or TLS key negotiation, the samples here offer a simple ML-KEM - only key negotiation that can be built on for many use cases.
-
ML-DSA (FIPS 204) is a post-quantum digital signature scheme, part of the NIST PQC competition. It provides authentication and integrity by allowing users to sign and verify messages securely, even against quantum-capable adversaries. (e.g Pure ML-DSA, Pre-hash ML-DSA)
ML-KEM samples
There are C samples for both CCA and EP11, and REXX samples for CCA. The action inside each sample is very straightforward for a key establishment operation between Alice and Bob, although all steps happen inside one sample for convenience.
-
Alice generates the key pair
-
Alice pulls the public key from the key pair object - and would send to Bob in a normal key establishment
-
Bob performs encapsulation -
-
for ML-KEM this means that a new random number is generated inside the HSM and returned encrypted by the public key.
-
The secret is also returned optionally either in the clear or encrypted by the card master key / wrapping key for use by Bob.
-
In a normal key establishment Bob would send the public-key-encrypted secret to Alice.
-
Alice performs the decapsulation - using the private key to decrypt the secret inside the HSM. The secret is returned optionally either in the clear or encrypted by the card master key / wrapping key.
You will see the appropriate API calls and options for each step inside the samples, please reach out to the crypto team for any questions!
Links to the samples
ML-DSA samples
There are C samples for both CCA and EP11, and REXX samples for CCA. The action inside each sample is very straightforward for a signature operation and verification between Alice and Bob, although all steps happen inside one sample for convenience.
-
Alice generates the key pair
-
Alice pulls the public key from the key pair object - and would normally send to Bob or post publicly
-
Alice performs a signature over a message (PureML-DSA) or a hash of a message (HashML-DSA) - using the private key and the HSM. The raw signature is returned and can be placed with the message in a data structure or protocol object as appropriate, sending the result to Bob.
-
Bob performs signature verification -
-
Bob uses the public key with the signature and the message (PureML-DSA) or a hash of the message (HashML-DSA)
You will see the appropriate API calls and options for each step inside the samples, please reach out to the crypto team for any questions!
Links to the samples
Support requirements:
For more info, please see the following