Overview

This article will focus on CRYSTALS-Kyber and CRYSTALS-Dilithium keys and demonstrate how we can create, save, retrieve, and delete them on our z/OS system.

Quantum-safe cryptography includes a suite of algorithms that are resistant to attacks by both classical and quantum computers. IBM's Semeru JDK currently supports the CRYSTALS-Kyber and CRYSTALS-Dilithium algorithms. For further reading and tutorials on these algorithms on Java, check out my other articles in the "QSC on Java" series.

Creating keys

MASTER key

The MASTER value allows you to encrypt your key under the ICSF Master key but not store the key in the PKDS (Public Key Data Set). This configuration is also the default value when a value is not specified.

CRYSTALS-Kyber

KeyPairGenerator kyberKPG = KeyPairGenerator.getInstance("CRYSTALS-Kyber", "IBMJCECCA");
KyberKeyParameterSpec kyberGenPS = new KyberKeyParameterSpec(
    "kyber1024r2",
    KeyHWAttributeValues.MASTER,
    KeyHWAttributeValues.KEYMANAGEMENT
);
kyberKPG.initialize(kyberGenPS, null);
KeyPair kyberKeyPair = kyberKPG.generateKeyPair();

CRYSTALS-Dilithium

KeyPairGenerator dilithiumKPG = KeyPairGenerator.getInstance("CRYSTALS-Dilithium", "IBMJCECCA");
DilithiumKeyParameterSpec dilithiumGenPS = new DilithiumKeyParameterSpec(
    "dilithium87r3",
    KeyHWAttributeValues.MASTER,
    KeyHWAttributeValues.SIGNATURE);
dilithiumKPG.initialize(dilithiumGenPS, null);
KeyPair dilithiumKeyPair = dilithiumKPG.generateKeyPair();

CLEAR key

The CLEAR value generates a clear key that is tokenized for use with the hardware and is not encrypted under the ICSF Master key.

CRYSTALS-Kyber

KyberKeyParameterSpec kyberGenPS = new KyberKeyParameterSpec(
    "kyber1024r2",
    KeyHWAttributeValues.CLEAR,
    KeyHWAttributeValues.KEYMANAGEMENT
);

CRYSTALS-Dilithium

DilithiumKeyParameterSpec dilithiumGenPS = new DilithiumKeyParameterSpec(
    "dilithium87r3",
    KeyHWAttributeValues.CLEAR,
    KeyHWAttributeValues.SIGNATURE
);

PKDS key

The PKDS value causes a label to be returned and the key to be stored in the PKDS.

CRYSTALS-Kyber

KyberKeyParameterSpec kyberGenPS = new KyberKeyParameterSpec(
    "kyber1024r2",
    KeyHWAttributeValues.PKDS,
    KeyHWAttributeValues.KEYMANAGEMENT,
    "KYBER.KEY"
);

CRYSTALS-Dilithium

DilithiumKeyParameterSpec dilithiumGenPS = new DilithiumKeyParameterSpec(
    "dilithium87r3",
    KeyHWAttributeValues.PKDS,
    KeyHWAttributeValues.SIGNATURE,
    "DILITH.KEY"
);

Retrieving keys

Once the keys are stored in the PKDS, you can then retrieve the keys later on to use in your applications.

CRYSTALS-Kyber

KeyLabelKeySpec labelSpec = new KeyLabelKeySpec("KYBER.KEY");
KeyFactory factory = KeyFactory.getInstance("CRYSTALS-Kyber", "IBMJCECCA");
KyberPrivateKey kyberPrivateKey = (KyberPrivateKey) factory.generatePrivate(labelSpec);
KyberPublicKey kyberPublicKey = (KyberPublicKey) factory.generatePublic(labelSpec);

CRYSTALS-Dilithium

KeyLabelKeySpec labelSpec = new KeyLabelKeySpec("DILITH.KEY");
KeyFactory factory = KeyFactory.getInstance("CRYSTALS-Kyber", "IBMJCECCA");
DilithiumPrivateKey dilithiumPrivateKey = (DilithiumPrivateKey) factory.generatePrivate(labelSpec);
DilithiumPublicKey dilithiumPublicKey = (DilithiumPublicKey) factory.generatePublic(labelSpec);

Deleting keys

When you no longer need the PKDS entry of your key, you can delete the entry from your dataset.

CRYSTALS-Kyber

kyberPrivateKey.deletePKDSEntry();

CRYSTALS-Dilithium

dilithiumPrivateKey.deletePKDSEntry();

Conclusion

In this article, we've seen how to create, store, retrieve, and delete QSC keys in our Java applications. Thanks for reading!

If you have additional questions, please email me at Gregory.Cernera@ibm.com.

How to obtain an IBM Semeru JDK

The IBM Java SAF APIs are included in the IBM Semeru Runtime Certified Edition for z/OS download. Please follow the links below to download the IBM Semeru JDK onto your own machines.

 How to obtain IBM Semeru Runtime Certified Edition for z/OS?
IBM Semeru Runtime Certified Edition for z/OS is available for zero license charge through Shopz SMP/E, or you can download the non-SMP/E here. The subscription and service number is 5655-I48.

Supporting Links:
IBM Semeru Runtime Certified Edition for z/OS product page
For additional information on installation, troubleshooting and support please visit IBM Documentation.