RSA hardware key usage over TLSv1.3

Overview

A major difference from TLSv1.2 to TLSv1.3 is that Static RSA and Diffie-Hellman cipher suites have been removed for key exchange and handshake but not for key signing. For RSA hardware keys, the only supported signature algorithm in TLSv1.3 is RSASSA-PSS. If you have previously generated RSA hardware keys that were used with the IBMJCECCA provider for key exchange over TLSv1.2, it would fail when you migrate to TLSv1.3 because the existing RSA keys would not have the ability to use RSASSA-PSS. You must create an RSA key with an RSASSA-PSS signature algorithm. Generate RSA keys with the -sigAlg RSASSA-PSS parameter by using hwkeytool as explained in the section RSA key generation by using hwkeytool over TLSv1.3.

You can also generate RSA keys by using the RACDCERT command. For more information refer section RSA key generation by using GENCERT over TLSv1.3.

In this release of the IBM Semeru Runtime Certified Edition for z/OS, the use of RSASSA-PSS is enforced by the IBMJCECCA provider by validating that an RSA private key in PKDS format has the RSASSA-PSS parameter specification. This validation results in a limitation where RSA keys generated by using the RACF GENCERT command are rejected for TLSv1.3, because the keys do not contain the RSASSA-PSS parameter specification.

This limitation is resolved in this release of IBM Semeru Runtime Certified Edition for z/OS, by allowing the generation of RACF RSA(PKDS) certificates, even when the SIGATTR parameter is omitted. This ensures that all PKDS entries are properly read and translated as RSASSA-PSS entries. Additionally, the update allows RSA keys generated by using hwkeytool without the sigAlg argument to automatically default to RSASSA-PSS. This resolution works if the key size is greater than 2048 and the key is protected by an ECC primary key with AES.

In this and the later releases of IBM Semeru Runtime Certified Edition for z/OS, updates have been made to allow successful RSA hardware key generation by using hwkeytool and RACDCERTeven when the RSASSA-PSS signature parameter is omitted.

RSA key generation by using hwkeytool over TLSv1.3

#RACF keystore using safkeyringjcecca
hwkeytool -genkeypair \
 -v \
 -alias root \
 -dname "CN=rsatest, OU=Poughkeepsie, O=IBM, C=US" \
 -keystore safkeyringjcecca://"$MYID"/HWKeyringRACF \
 -provider IBMJCECCA \
 -keyalg RSA \
 -sigAlg RSASSA-PSS \
 -keysize 2048 \
 -storetype JCECCARACFKS \
 -hardwaretype PKDS \
 -validity 999

#RACF keystore using safkeyring
hwkeytool -genkeypair \
  -v \
  -alias root \
  -dname "CN=rsatest, OU=Poughkeepsie, O=IBM, C=US" \
  -keystore safkeyring://"$MYID"/HWKeyringRACF \
  -provider IBMJCECCA \
  -keyalg RSA \
  -sigAlg RSASSA-PSS \
  -keysize 2048 \
  -storetype JCECCARACFKS \
  -hardwaretype PKDS \
  -validity 999 \
  -J-Djava.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider

#JCECCA keystore
hwkeytool -genkeypair \
  -alias root \
  -dname "CN=rsatest" \
  -keystore RSAkeystoreCCA \
  -provider IBMJCECCA \
  -keyalg RSA \
  -sigAlg RSASSA-PSS \
  -keysize 2048 \
  -keypass "password" \
  -storepass "password" \
  -storetype JCECCAKS \
  -validity 999

RSA key generation by using GENCERT over TLSv1.3

RACDCERT GENCERT CERTAUTH SUBJECTSDN(CN('User5CAOnP03')) WITHLABEL('User5CAOnP03') TRUST SIZE(2048) NOTAFTER(DATE(2048/12/31)) SIGATTR(RSAPSS)
RACDCERT GENCERT ID(JAZZSV1) SUBJECTSDN(CN('User5CASignedP03')) WITHLABEL('User5CASignedP03') SIGNWITH(CERTAUTH LABEL('User5CAOnP03')) TRUST NOTAFTER(DATE(2030/12/31)) SIGATTR(RSAPSS)
setropts raclist(digtcert) refresh
LISTUSER JAZZSV1
racdcert list(label('HWPerRACF'))

Migration from TLSv1.2

If you have previously generated RSA keys that were working with TLSv1.2, it would fail when you migrate to TLSv1.3 because the existing RSA keys would not have the ability to use RSASSA-PSS. Follow these steps to migrate to TLSv1.3 smoothly.

• Recreate the certificates/keys by using the hwkeytool command with the -sigAlg RSASSA-PSS parameter as described in the previous section in this document.
• Translate the keys by using the steps given in Translate and replace an RSA key for RSA PSS.
• Recreate the certificates/keys using z/OS v2.4 and later with the RACDCERT GENCERT command as detailed in RACDCERT GENCERT (Generate certificate).

For more information about updating a z/OS® System SSL application to support TLSv1.3, see Required updates to enable TLS V1.3 protocol support for your version of z/OS.