On 5/31/20 9:26 PM, Weijun Wang wrote:
Replies inline below. I've removed the items I agree with for simplicity.
On May 30, 2020, at 3:32 AM, Sean Mullan <sean.mul...@oracle.com> wrote:
On 5/23/20 4:21 AM, Weijun Wang wrote:
CSR updated at https://bugs.openjdk.java.net/browse/JDK-8245274 with the full
patch on docs.
- Comments on the Specification section:
Some of this wording where you discuss what is going to be done in jarsigner
and the tool doc seems more like it belongs in the Solution section, but it may
be ok either way (not sure, I guess Joe will let you know if it is an issue).
+RSASSA-PSS \<= 3072 RSASSA-PSS using SHA-256
+ \<= 7680 RSASSA-PSS using SHA-384
+ \> 7680 RSASSA-PSS using SHA-512
It might be better to be more specific, for example "RSASSA-PSS with the SHA-256 message
digest algorithm" I used the term "with" as that is the word we use in the standard
signature algorithm strings.
Can I simply say "RSASSA-PSS with SHA-256"? Otherwise the text is much longer
than the other rows. That said, we have enough width and no need to wrap.
How about "RSASSA-PSS (with SHA-256)"
I think the parentheses helps.
Also, we used to say HASHwithENC, but here it's "ENC with HASH". Hopefully this
will not make people laugh.
+for keysize \<= 3072 bits, use a `PSSParameterSpec` with SHA-256 as the hash
s/use a `PSSParameterSpec`/a `PSSParameterSpec` will be used/
+and MGF1 algorithms; for keysize \<= 7680 bits, use SHA-384; for
+keysize \>= 7680 bits, use SHA-512.
s/use SHA-384/SHA-384 will be used/
s/use SHA-512/SHA-512 will be used/
My original text is
Precisely, for keysize \<= 3072 bits, use a `PSSParameterSpec` with SHA-256
as the hash and MGF1 algorithms; for keysize \<= 7680 bits, use SHA-384; for
keysize \>= 7680 bits, use SHA-512.
So the object of "use" here is the PSSParameterSpec. If I change it to passive
voice, it will be
a `PSSParameterSpec` with SHA-256 as the hash and MGF1 algorithms will be
used,
and `PSSParameterSpec` (instead of SHA-256) will be the noun. The "SHA-384 will be
used" in the next sentence might not be 100% grammatically correct in this sense but
I think it's OK and nobody will misunderstand it. (In fact, there is the same problem in
my original text).
When you say "use a `PSSParameterSpec` with SHA-256" it sounds to me as
you are telling the reader they need to take action to do that. But this
is what jarsigner itself will be doing.
Another option which I will throw out, is to change the RSASSA-PSS rows
in the table above it to be more like the keytool table, so that it
includes the keysize ranges, ex:
+RSASSA-PSS \<= 3072 RSASSA-PSS (with SHA-256)
+ \<= 7680 RSASSA-PSS (with SHA-384)
+ \> 7680 RSASSA-PSS (with SHA-512)
Then you could simplify the following text as something like:
* If an RSASSA-PSS key is encoded with parameters,
then the signature will use the same parameters. Otherwise, the
signature will use parameters that are determined by the size of the key
as specified in the table above. For example, an 3072-bit RSASSA-PSS key
will use RSASSA-PSS as the signature algorithm and SHA-256 as the hash
and MGF1 algorithms.
I don't think you need to mention PSSParameterSpec at all. It seems like
a detail that is more for an application developer and doesn't need to
be detailed here.
Thanks,
Max
p.s. This is probably the only RFE I can add into jdk15 before rdp1 now. The
strong p12 algorithms and new CACERTS keystore type won't be ready. I do have
several bug fixes that can wait till rdp2.
Yes, I hope there is still time. I have added my name as Reviewer, so
you should submit the CSR soon. Also, I view all of my comments as
wording changes/tweaks and not changes to the specification which is
basically to add support for these algorithms to jarsigner.
--Sean
