Authors: James Cox, Gregg Arquero, John Craig, Richard Kisley

This article introduces the updates for the Common Cryptographic Architecture (CCA) 8.4 for IBM z17, which will also be made available on IBM z16.

Audience:

Users of CCA for payment or cryptography applications on 

• ICSF

• IBM z17, z16.

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 adds support for the following features:

• support for ML-KEM (NIST FIPS 203) and ML-DSA (NIST FIPS 204} key generation and use with digital signatures (ML-DSA) and key encapsulation (ML-KEM) in the CCA API.

• support for RSA 8K

Support requirements:

• ICSF exploitation APAR OA66395 (HCR77D2 - 77E0)

• ICSF toleration APAR OA66396 (HCR77C0 - 77E0)

• CCA firmware version 8.4 installed to IBM CEX8S (4770) hardware features on IBM z16

ML-DSA key generation and digital signatures

The CCA release 8.4 adds support for generating ML-DSA pure X’05’ keys as well as ML-DSA-SHA512-prehash X’07’ keys. These keys can be used with the CSNDDSG verb to generate signatures, and with the CSNDDSV verb to verify signatures. As per the FIPS-204 specification ML-DSA signatures are now non-deterministic by default. A new rule “DETER “ can be used with CSNDDSG to use the optional deterministic signature generate mode.

A new rule “CONTEXT“ is available for the CSNDDSG and CSNDDSV verbs to signify provision of a context string of 1 to 255 bytes.

A new rule “RAWSEED” is available for the CSNDPKG and CSNDDSG verbs to facilitate running known answer tests with random components. This rule should only be used for testing and known answer test purposes.

See below for specific guidance on running ML-DSA known answer tests from NIST.

ML-KEM key generation and key encapsulation for distribution

The CCA release 8.4 adds support for generating ML-KEM X’06’ keys. This new key type can be used with the CSNDPKE verb to generate a 32 byte random key and its corresponding ciphertext, and with CSNDPKD to decrypt that ciphertext. ML-KEM is purely a key-establishment mechanism and cannot be used to encrypt known plaintext. Please note: currently a 32 byte key is made for every ML-KEM security level.

A new rule group “Key Format” is available in CSNDPKE and CSNDPKD for use exclusively by ML-KEM keys. This rule group is used to specify how the 32 byte random shared secret should be returned in clear_source_data for CSNDPKE or clear_target_key for CSNDPKD.

• The rules “CLEAR”, “AES-KB”, and “AES-ENC” are available in CSNDPKE.

• The rules “CLEAR” and “AES-KB” are available in CSNDPKD.

• If “CLEAR” is specified the random value will be returned in the clear.

• If “AES-ENC” is specified the random value will be returned encrypted under the symmetric AES key provided in the sym_key_identifer field.

• If “AES-KB” is specified the random value will be returned inserted into the AES skeleton key token provided in the sym_key_identifier. If no “Key Format” rule is specified with CSNDPKE nothing will be returned in clear_source_data. If no “Key Format” rule is specified with CSNDPKD the shared secret will be returned in the clear.

A new rule “RAWSEED” is available for use with the CSNDPKG and CSNDPKE verbs to facilitate running known answer tests with a random component. This rule should only be used for testing and known answer test purposes.

See below for specific guidance on running ML-KEM known answer tests from NIST.

RSA 8192-bit Modulus CCA service updates

The CCA releases 8.4 and 7.6 add support for RSA keys with modulus bit lengths of up to 8192-bits.

• The following RSA token types now support up to an 8192-bit modulus:

• X’04’ RSA_PUBL

• X’30’ RSA_AES_ME

• X’31’ RSA_AES_CRT

• X’30’ RSA_AES_2_ME

• X’31’ RSA_AES_2_CRT

• X.509 RSA public key certificates

• The following CCA services support RSA tokens and RSA public key certificates (* denotes applicability) with up to an 8192-bit modulus:

• PKA Key Management Services: including PKA Key Token Build (CSNDPKB), PKA Key Generate (CSNDPKG) and others.

• Symmetric Key Management services:

• Symmetric Key Import (CSNDSYI)

• Symmetric Key Import2 (CSNDSYI2)

• Symmetric Key Export with Data (CSNDSXD)

• Symmetric Key Generate (CSNDSYG)*

• Symmetric Key Export (CSNDSYX)*

• Services

• Digital Signature Generate (CSNDDSG)

• Digital Signature Verify (CSNDDSV)*

• PKA Encrypt (CSNDPKE)*

• PKA Decrypt (CSNDPKD)

• Public Infrastructure Certificate (CSNDPIC)

ICSF support for RSA keys with up to 8192-bit modulus require ICSF FMID HCR77D2 and later.

The ICSF PKDS Keys Utility key generation panel has been updated to support RSA key generation with up to an 8192-bit modulus. Key label support for RSA keys with a modulus bit length greater than 4096-bits require a large common record (KDSRL) format PKDS.

Finally, the ICSF_WEAK_CCA_KEYS health check has been updated on HCR77D2 and later to display RSA key labels in the active PKDS that have a modulus bit length less than 2048 bits. This is increased from 1024 bits and is in line with NIST’s recommendation for secure RSA keys. This health check will run during ICSF initialization.

For more info, please see the following

• Our refreshed Cryptographic Coprocessor site: CCA Functional Overview

• The new Application Programmer’s guide: ICSF Application Programmer’s Guide

running ML-DSA and ML-KEM known answer tests from NIST

ML-DSA known answer test runs

NIST has provided known answer tests for ML-DSA on their ACVP-Server github page.
https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/

To run keyGen KATs

• Call CSNDPKB

• Set byte 0 of the input key value structure (kvs) to either X’05’ for pure or X’07’ for pre-hash.

• Set byte 1 of kvs to X’00’ to specify no clear key will be provided.

• Set bytes 2-3 of the kvs to 0x0404, 0x0605, or 0×0807 for ML-DSA 4,4 6,5 or 8,7.

• Pass rule array keywords “QSA-PAIR”, ”U-DIGSIG” to tell CSNDPKB to generate a skeleton key token for a public/private key pair with digital signature key usage enabled.

• Call CSNDPKG

• Copy the 32 byte “seed” value from the ACVP KAT to the regeneration_data field and set regeneration_data_length to 32.

• Set the rule array to “CLEAR RAWSEED “ To tell PKG to return the generated key pair in the clear and to use the seed data provided.

• mem-compare the returned public key, confirm it matches the expected KAT data

• mem-compare the returned private key, skipping over the first 32 bytes of the KAT data private key. The first 32 bytes of the private key contain the “rho” parameter, the same “rho” value is already stored in the first 32 bytes of the public key. Rho must be skipped because CCA returns key values in the parameterized X’02’ clear key format.

To run sigGen KATs

• Call CSNDPKB

• Set byte 0 of the kvs to either X’05’ for pure or X’07’ for pre-hash.

• Set byte 1 of kvs to X’02’ to specify that the private key provided will be in parametrized format.

• Set bytes 2-3 of the kvs to 0x0404, 0x0605, or 0×0807 for ML-DSA 4,4 6,5 or 8,7.

• Set bytes 4-5 of the kvs to the parameterized length of the public/private key. rho | key | tr | s1 | s2 | t0 | t1.

• Copy the sk from the KAT to the end of the kvs header. Note that the KAT does not provide t1, because the public key is not provided in prompt.txt. For the purposes of a signature generate KAT t1 can be all zeros.

• Set the rule array to QSA-PAIRU-DIGSIG to tell CSNDPKB to generate a skeleton key token for a public/private key pair with digital signature key usage enabled.

• Call CSNDDSG

• rule array

• If signatureInterface is “internal” add the “ACVP ” rule to the rule array.

• If deterministic is “true” add the “DETER ” rule to the rule array.

• If deterministic is “false” optionally add “NONDETER” to the rule array (NONDETER is default). Also add “RAWSEED” so that the “rnd” value can be passed.

• If preHash is “preHash” and hash-alg is SHA-512 (only preHash hash alg CCA supports).

• Add the “SHA-512” rule.

• If preHash is “pure”

• Add the “CRDLHASH” rule.

• If a context is provided add the “CONTEXT” rule.

• Add the “CRDL-DSA” and “MESSAGE” rules.

• If deterministic is “false” and no context string is provided.

• Set the first two bytes of the data field to be the length of the “rnd” field from the KAT (always 32 bytes for CSNDDSG).

• After the two byte rnd/seed length field copy the 32 byte “rnd” value.

• After the “rnd” value copy the message to be signed.

• Data length will be 2 + seed length (32) + msg to be signed length.

• If deterministic is “false” and a context string is provided.

• Set the first two bytes of the data field to be the length of the “rnd” field from the KAT (always 32 bytes for DSG).

• After the two byte rnd/seed length field copy the 32 byte “rnd” value.

• After the “rnd” value set the next two bytes to be the length of the KATs context data.

• After the two byte context_length field copy the context data.

• After the context data copy the message to be signed.

• Data length will be 2 + seed length (32) + 2 + context length + msg to be signed length.

• If deterministic is “true” and a context string is not provided.

• The data field will just contain the message to be signed.

• Data length will just be msg to be signed length

• If deterministic is “true” and a context string is provided.

• Set the first two bytes of the data field to be the length of the “context” field from the KAT.

• After the two byte context length field copy the context.

• After the “context” value copy the message to be signed.

• Data length will be 2 + context length + msg to be signed length.

• Mem-cmp the returned signature with the expected KAT signature.

To run sigVer KATs

• Call CSNDPKB

• Set byte 0 of the kvs to either X’05’ for pure or X’07’ for pre-hash.

• Set byte 1 of kvs to X’03’ to specify that only the public key will be provded.

• Set bytes 2-3 of the kvs to 0x0404, 0x0605, or 0×0807 for ML-DSA 4,4 6,5 or 8,7.

• Set bytes 4-5 of the kvs to the length of the public key. rho | t1.

• Copy the pk from the KAT to the end of the kvs header.

• Set the rule array to QSA-PUBLU-DIGSIG to tell CSNDPKB to generate a skeleton key token for a public key with digital signature key usage enabled.

• Call CSNDDSV

• rule array

• If signatureInterface is “internal” add the “ACVP” rule to the rule array.

• If preHash is “preHash” and hash-alg is SHA-512 (only preHash hash alg CCA supports).

• Add the “SHA-512” rule.

• If preHash is “pure”

• Add the “CRDLHASH” rule.

• If a context is provided add the “CONTEXT” rule.

• Add the “CRDL-DSA” and “MESSAGE” rules.

• Copy the signature to be verified to the data out filed.

• if a context string is provided.

• Set the first two bytes of the data field to be the length of the “context” field from the KAT.

• After the two byte context length field copy the context.

• After the “context” value copy the message to be signed.

• Data length will be 2 + context length + msg to be verified length.

• If a context string is not provided.

• The data field will just contain the message to be verified.

• Data length will just be msg to be verifed length

• Confirm that the message verifies if the KAT specifies “testPassed” = “true”.

• Confirm that the message fails to verify if the KAT specifies “testPassed” = “false”.

ML-KEM known answer test runs

NIST has provided known answer tests for ML-KEM on their ACVP-Server github page.
https://github.com/usnistgov/ACVP-Server/tree/master/gen-val/json-files/

To run keyGen KATs

• Call CSNDPKB

• Set byte 0 of the input key value structure (kvs) to X’06’ for ML-KEM.

• Set byte 1 of kvs to X’00’ to specify no clear key will be provided.

• Set byte 2-3 of the kvs to 0×0768, or 0×1024 for ML-KEM 768 or 1024.

• Set the rule array to QSA-PAIRU-DIGSIG to tell PKB to generate a skeleton key token for a public/private key pair with digital signature key usage enabled.

• Call CSNDPKG

• Copy the 32 byte “d” value followed by the 32 byte “z” value from the ACVP KAT to the regeneration_data field and set regeneration_data_length to 64.

• Set the rule array to “CLEAR RAWSEED “ To tell PKG to return the generated key pair in the clear and to use the seed data provided.

• mem-compare the returned public key, confirm it matches the expected KAT data “ek” (Encapsulate key)

• mem-compare the returned private key

• CCA returns the parameterized private key comprising of spv | phash | ran

• The ACVP KATs list the private key “dk” (Decapsulate key) as spv | ppv | ps | phash | ran.

• A copy of the public key is stored after spv bytes of the private key.

• For ML-KEM1024 spv and ppv are 1536 bytes each and the public key length is 1568 bytes. For ML-KEM768 spv and ppv are 1152 bytes each and the public key is 1184 bytes.

• For both ML-KEM1024 and ML-KEM768 phash, ran, and ps are 32 bytes each.

• Mem-compare spv bytes of the returned private key with the first spv bytes of the kat “dk” key.

• memcmp( &returnedPrivateKey(spvLen), &KATdk(spvLen + publicKeyLen), phashLen + ranLen);

To run Decap KATs

• Call CSNDPKB

• Set byte 0 of the input key value structure (kvs) to X’06’ for ML-KEM.

• Set byte 1 of kvs to X’01’ to specify that the private/public key will be provided in the Know Answer Test format.

• Set byte 2-3 of the kvs to 0x0768, or 0x1024. To select ML-KEM 768 or 1024.

• Set byte 4-5 of the kvs to the KAT length of the public/private key (length of KAT “dk”). spv | ppv | ps | phash | ran.

• Copy the “dk” from the KAT prompt.json to the end of the kvs header.

• Set the rule array to QSA-PAIRU-DATAENC to tell PKB to generate a skeleton key token for a public/private key pair with data encipherment key usage enabled.

• Call CSNDPKD

• Set the “ZERO-PAD” rule.

• Copy the “c” ciphertext to the source_encrypted_key data field.

• Mem-compare the returned 32 byte shared secret with the KAT expected “k”.

To run Encap KATs

• Call CSNDPKB

• Set byte 0 of the input key value structure (kvs) to X’06’ for ML-KEM.

• Set byte 1 of kvs to X’03’ to specify that only the public key will be provided.

• Set byte 2-3 of the kvs to 0x0768, or 0x1024. To select ML-KEM 768 or 1024.

• Set byte 4-5 of the kvs to the length of the public key (length of KAT “ek”). ppv | ps.

• Copy the “ek” from the KAT prompt.json to the end of the kvs header.

• Set the rule array to QSA-PUBL-DATAENC to tell PKB to generate a skeleton key token for a public key with data encipherment signature key usage enabled.

• Call CSNDPKE

• Set the “RANDOM ZERO-PADRAWSEED CLEAR ” rules. (ML-KEM PKE must always use RANDOM). The CLEAR rule signifies that the 32 byte random shared secret value will be returned in the clear_source_data field. The RAWSEED rule signifies that the first two bytes of the clear_source_data field will denote the length of the provided seed and the seed will be stored following the length field.

• Set the first 2 byte of the clear_source_data to be 32 to signify a 32 byte seed.

• Following the seed length field copy the 32 byte seed “m” from the KAT.

• The clear_source_data_length field will be 2 + 32 = 34 bytes.

• Mem-compare the returned 32 byte shared secret (clear_source_data) with the KAT expected “k”.

• Mem-compare the returned ciphertext (target_data) with the KAT expected "c”