Summary

Add support for HSS/LMS in keytool and jarsigner. Update JAR specification to support signatures with HSS/LMS and other key algorithms.

Problem

HSS/LMS is a new signature algorithm introduced in JDK 21. We need to support it in keytool and jarsigner.

Solution

Changes made to the JAR file specification:

The JAR signing and verification processes needs to know what files are signature-related and what are not for those files inside the META-INF directory. Currently the rule understands .DSA, .RSA, and .EC files, plus MANIFEST.MF itself. Adding a new file extension is a non-trivial behavior change and could lead to compatibility issues. This is the very reason why we reused .RSA and .EC when we introduced support for the RSASSA-PSS and EdDSA algorithms.

With the introduction of another new signature algorithm -- HSS/LMS -- and possibly more PQC signature algorithms in the near future, we propose to reuse .DSA for them. DSA is a legacy signature algorithm which is not recommended today, and its full name -- Digital Signature Algorithm -- is rather neutral for a general purpose extension name. Also, while we choose different extensions based on the key algorithms at signing, the JAR verification process has never tried to match the extension name with the key algorithm, which means as long as a file ends in one of these extensions it could contain a PKCS7 signature of any key algorithm. This is the reason why we have already supported HSS/LMS signature verification without any code change in this area in JDK 21.

Changes made to keytool:

1. Support HSS/LMS as a keytool -genkeypair -keyalg, and use HSS/LMS as its default -sigalg algorithm. When -sigalg is specified to be another algorithm, keytool should fail.

2. Support displaying a certificate using HSS/LMS as the signature algorithm using keytool -list or keytool -printcert.

Changes made to jarsigner:

1. Support signing a JAR file with an HSS/LMS key, and use HSS/LMS as its default -sigalg algorithm. When -sigalg is specified to be another algorithm, jarsigner should fail.

Note: since OpenJDK only includes an HSS/LMS implementation on signature verification, certain new functions above require a 3rd-party security provider that supports key pair generation and signature generation.

Minor changes to the keytool man page

We take this chance to clarify the difference between these 3 concepts:

1. The -keysize option, used to specify the key size of a key pair to be generated
2. The -groupname option, used to specify the named group of a key pair to be generated
3. key size, the actual size of a key, determined by either -keysize or -groupname.

Back when keytool was created long ago, for a single key algorithm, the only attribute of a key is its bit length, and it is determined by the -keysize option when keytool -genkeypair is called. When EC was introduced, there are different EC curves that might have the same key size (For example, secp256r1 and secp256k1 are all 256 bits). We added the -groupname option so that user can choose a curve name when generating a key pair.

-keysize and -groupname are thus two parallel mechanisms to tell keytool how to generate a key pair, and each is able to determine the "key size" of the generated keys. However, in the keytool man page, -keysize is still shown as the primary option and -groupname as secondary, and "keysize" is used in a lot of places where "key size" should have been used.

These changes are made:

1. Put -keysize and -groupname on the same level.
2. Create a new section for -groupname in the default options values section
3. Change "keysize" to "key size" when it means the actual key size of an existing key

Specification

The following change will be made to the JAR file specification:

 Digital signature files have the same filenames as the .SF files but
 different extensions. The extension varies depending on the algorithm
 of the signer's private key.

    `.RSA` (PKCS7 signature, for RSA or RSASSA-PSS keys)
    `.EC` (PKCS7 signature, for EC or EdDSA keys)
-   `.DSA` (PKCS7 signature, for DSA keys)
+   `.DSA` (PKCS7 signature, for DSA or any other key algorithm)

A copy of the changes on the JAR file specification and the man pages of keytool and jarsigner is attached to this CSR.