RSA hardware key usage over TLSv1.3

Content

In IBM® Semeru Runtime Certified Edition for z/OS®, versions 11 and 17, the Transport Layer Security (TLS) protocol defaults to version 1.3 (TLSv1.3). If an RSA key is used, TLSv1.3 protocol requires handshake messages to be signed with an RSASSA-PSS signature. No other signature schemes are accepted.

In the IBM SDK, Java™ Technology Edition, version 8.0.8.5, and Semeru Runtime Certified Edition for z/OS, versions 11.0.19.0 and 17.0.7.0, 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.

In the IBM SDK, Java™ Technology Edition, version 8.0.8.15, and Semeru Runtime Certified Edition for z/OS, versions 11.0.19.1 and 17.0.9.0, this limitation is resolved 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.

RSA key generation by using hwkeytool over TLSv1.3

RSA keys can be generated by using hwkeytool with the -sigAlg RSASSA-PSS parameter as shown in the following example. All keys in the key store and keyring must be generated by using the signing algorithm RSASSA-PSS, else a failure can occur. 

#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

RSA keys can be generated by using GENCERT SIGATTR/SIGATTR(RSAPSS) as shown in the following example. All keys in the keyring must use the signing algorithm RSASSA-PSS, else a failure can occur.

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'))

Note: RSA keys generated by using the hwkeytool command without the -sigAlg RSASSA-PSS parameter or  by using RACDCERT command without the SIGATTR option will result in failures.

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.