8305406: Add @spec tags in java.base/java.* (part 2) #21326

hns · 2024-10-03T14:04:51Z

Please review a doc update to add @spec tags to crypto and security APIs in java.base.

This was authored and proposed as #13336 by @jonathan-gibbons as part of an effort to add @spec tags and an external specifications page to API documentation. The original PR was reviewed and approved, yet for some reason it was never integrated.

Since I couldn't reopen Jon's PR I created a new pull request based the original commits. They still apply cleanly, and I made sure all links are still valid and working. I added a commit to update the copyright header dates.

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8305406: Add @spec tags in java.base/java.* (part 2) (Enhancement - P3)

Reviewers

Valerie Peng (@valeriepeng - Reviewer)

Contributors

Daniel Jeliński <djelinski@openjdk.org>
Hannes Wallnöfer <hannesw@openjdk.org>

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/21326/head:pull/21326
$ git checkout pull/21326

Update a local copy of the PR:
$ git checkout pull/21326
$ git pull https://git.openjdk.org/jdk.git pull/21326/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 21326

View PR using the GUI difftool:
$ git pr show -t 21326

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/21326.diff

Webrev

Link to Webrev Comment

….java Co-authored-by: Daniel Jelinski <djelinski1@gmail.com>

bridgekeeper · 2024-10-03T14:05:53Z

👋 Welcome back hannesw! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2024-10-03T14:06:41Z

@hns This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8305406: Add @spec tags in java.base/java.* (part 2)

Co-authored-by: Daniel Jeliński <djelinski@openjdk.org>
Co-authored-by: Hannes Wallnöfer <hannesw@openjdk.org>
Reviewed-by: valeriep

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 334 new commits pushed to the master branch:

f1a9a8d: 8342902: Deduplication of acquire calls in BindingSpecializer causes escape-analyisis failure
f1cc890: 8343086: [BACKOUT] JDK-8295269 G1: Improve slow startup due to predictor initialization
36d7173: 8339289: Enhance Attach API to support arbitrary length arguments - Windows
ff165f9: 8342934: TYPE_USE annotations printed with error causing "," in toString output
0853aee: 8338426: Test java/nio/channels/Selector/WakeupNow.java failed
c202a2f: 8295269: G1: Improve slow startup due to predictor initialization
5cbd578: 8342930: New tests from JDK-8335912 are failing
1e35da8: 8343063: RISC-V: remove redundant reg copy in generate_resolve_blob
4f8f395: 8343060: RISC-V: enable TestFloat16VectorConvChain for riscv
a9eb50a: 8342953: RISC-V: Fix definition of RISCV_HWPROBE_EXT_ZVFHMIN
... and 324 more: https://git.openjdk.org/jdk/compare/7d524d7e378430afb3a262e8fe544bd1be22748c...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2024-10-03T14:07:37Z

@hns The following labels will be automatically applied to this pull request:

net
security

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

mlbridge · 2024-10-03T14:10:47Z

Webrevs

hns · 2024-10-22T14:41:15Z

One of the reasons for adding the javadoc @spec tag is to create an "External Specifications" page in API docs. This feature is currently disabled in OpenJDK build (because of incomplete @spec tags in libraries), but I have uploaded a bundle of API docs with this PR and the "External Specifications" page enabled. This should make this PR somewhat easier to review as the spec URLs can be reviewed directly in the browser.

valeriepeng · 2024-10-23T21:14:23Z

Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.

valeriepeng · 2024-10-23T21:39:13Z

src/java.base/share/classes/java/security/Key.java

 * Security Appendix</a>
 * of the <cite>Java Object Serialization Specification</cite> for more information.
 *
+ * @spec serialization/index.html Java Object Serialization Specification


How about "Java Security Standard Algorithm Names Specification"? Should its reference be covered by @SPEC tag? I see that java.security.Security class has @SPEC tag for it, but not this class. Maybe it's due to the reference is in the javadoc for a pkg private method?

Maybe it's due to the reference is in the javadoc for a pkg private method?

That may be why Jon's automated update didn't pick it up, but note that this is an interface so getAlgorithm() is actually a public method. I'll add the @spec tag.

jonathan-gibbons · 2024-10-23T21:59:55Z

Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.

Valerie,

The intent of @spec is to include any external specification that is referenced in the public API documentation. As a rule of thumb, an external specification is any one given by name and/or an absolute URL. Note, not all references with absolute URLs are specifications. Some may be references to additional non-normative sources such as guides and similar materials.

This PR, and others that have preceded it, are mechanically derived by examining @see and {@link} tags in public API documentation. Once this initial work has been completed, it will be up to individual component teams to update any @spec tags in their area, either adding new tags, or modifying/updating the URLs of existing tags.

valeriepeng · 2024-10-24T02:21:20Z

src/java.base/share/classes/java/security/package-info.java

 *
 * </ul>
 *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names


How about the other 2 under Package Specification (from line 49-53)? Does this PR need to cover them also?

Same question applies for the java/security/interfaces/package-info.java file as well.

I guess the link for PKCS #8 would be https://www.rfc-editor.org/info/rfc5208 , but the doc comment says "November 1993", while the spec page says "May 2008", so maybe that should be updated as well. For the JCA Reference Guide, it's not clear to me it qualifies as a specification. So this and java/security/interfaces/package-info.java are cases that I think should be handled by the component maintainers.

valeriepeng · 2024-10-24T02:46:11Z

src/java.base/share/classes/java/security/cert/package-info.java

+ * @spec security/standard-names.html Java Security Standard Algorithm Names
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile


How about RFC 2560 (line 39-40)?

I can add a @spec tag for RFC 2560 here. Possibly the mention in the description should also be converted to a link, but I think this PR should be limited to adding @spec tags.

hns

Thanks for looking at this, Valerie. As Jon said in his comment, this PR is based on automated detection of @see and {@link} tags, and therefore not necessarily complete.

That said I will add @spec for those cases you pointed out that I think are unambigous (see inline comments). Others that I think need more consideration and possibly updates of other parts of the doc comments I would prefer to be handled by the component maintainers.

hns · 2024-10-24T07:48:07Z

src/java.base/share/classes/java/security/Key.java

 * Security Appendix</a>
 * of the <cite>Java Object Serialization Specification</cite> for more information.
 *
+ * @spec serialization/index.html Java Object Serialization Specification


Maybe it's due to the reference is in the javadoc for a pkg private method?

That may be why Jon's automated update didn't pick it up, but note that this is an interface so getAlgorithm() is actually a public method. I'll add the @spec tag.

hns · 2024-10-24T08:31:50Z

src/java.base/share/classes/java/security/cert/package-info.java

+ * @spec security/standard-names.html Java Security Standard Algorithm Names
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile


I can add a @spec tag for RFC 2560 here. Possibly the mention in the description should also be converted to a link, but I think this PR should be limited to adding @spec tags.

hns · 2024-10-24T08:47:55Z

src/java.base/share/classes/java/security/package-info.java

 *
 * </ul>
 *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names


I guess the link for PKCS #8 would be https://www.rfc-editor.org/info/rfc5208 , but the doc comment says "November 1993", while the spec page says "May 2008", so maybe that should be updated as well. For the JCA Reference Guide, it's not clear to me it qualifies as a specification. So this and java/security/interfaces/package-info.java are cases that I think should be handled by the component maintainers.

hns · 2024-10-24T14:36:33Z

@valeriepeng I added two more @spec tags as suggested by your feedback (the ones I felt confident about).

I'm also uploading new API docs with the "External Specifications" page here:
https://cr.openjdk.org/~hannesw/8305406/api.01/external-specs.html

hns · 2024-10-24T14:48:19Z

/author set @jonathan-gibbons
/contributor add @djelinski
/contributor add @hns

openjdk · 2024-10-24T14:48:48Z

@hns
Setting overriding author to Jonathan Gibbons <jjg@openjdk.org>. When this pull request is integrated, the overriding author will be used in the commit.

openjdk · 2024-10-24T14:49:00Z

@hns
Contributor Daniel Jeliński <djelinski@openjdk.org> successfully added.

openjdk · 2024-10-24T14:49:35Z

@hns
Contributor Hannes Wallnöfer <hannesw@openjdk.org> successfully added.

valeriepeng · 2024-10-25T21:17:30Z

src/java.base/share/classes/javax/net/ssl/SSLParameters.java

     *     Java Security Standard Algorithm Names</a> document
     *     for information about standard algorithm names.
     *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names


There are more than 1 mentioning of the Java Security Standard Algorithm Names spec in this class. Do you know why only this one is covered by the @SPEC tag? Is it due to that the rest of the references contain "#" indicating a segment of the spec?

Never mind, I see that the scope is only about absolute URLs in one of the earlier replies.

valeriepeng · 2024-10-25T21:54:23Z

Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.

Valerie,

The intent of @spec is to include any external specification that is referenced in the public API documentation. As a rule of thumb, an external specification is any one given by name and/or an absolute URL. Note, not all references with absolute URLs are specifications. Some may be references to additional non-normative sources such as guides and similar materials.

This PR, and others that have preceded it, are mechanically derived by examining @see and {@link} tags in public API documentation. Once this initial work has been completed, it will be up to individual component teams to update any @spec tags in their area, either adding new tags, or modifying/updating the URLs of existing tags.

I see. Thanks for the clarification.

hns · 2024-10-26T06:56:38Z

Thanks!

/integrate

openjdk · 2024-10-26T06:57:47Z

Going to push as commit 873f8a6.
Since your change was applied there have been 335 commits pushed to the master branch:

1476f6c: 8343030: RISC-V: Small assembler cleanups
f1a9a8d: 8342902: Deduplication of acquire calls in BindingSpecializer causes escape-analyisis failure
f1cc890: 8343086: [BACKOUT] JDK-8295269 G1: Improve slow startup due to predictor initialization
36d7173: 8339289: Enhance Attach API to support arbitrary length arguments - Windows
ff165f9: 8342934: TYPE_USE annotations printed with error causing "," in toString output
0853aee: 8338426: Test java/nio/channels/Selector/WakeupNow.java failed
c202a2f: 8295269: G1: Improve slow startup due to predictor initialization
5cbd578: 8342930: New tests from JDK-8335912 are failing
1e35da8: 8343063: RISC-V: remove redundant reg copy in generate_resolve_blob
4f8f395: 8343060: RISC-V: enable TestFloat16VectorConvChain for riscv
... and 325 more: https://git.openjdk.org/jdk/compare/7d524d7e378430afb3a262e8fe544bd1be22748c...master

Your commit was automatically rebased without conflicts.

openjdk · 2024-10-26T06:57:54Z

@hns Pushed as commit 873f8a6.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

jonathan-gibbons and others added 4 commits October 3, 2024 14:52

JDK-8305406: Add @SPEC tags in java.base/java.* (part 2)

59a90cc

Update src/java.base/share/classes/java/security/cert/X509Certificate…

7bfac25

….java Co-authored-by: Daniel Jelinski <djelinski1@gmail.com>

Address review feedback

ce6eb0a

Add @SPEC tags for nist.gov docs

902c312

openjdk bot added the rfr Pull request is ready for review label Oct 3, 2024

openjdk bot added security security-dev@openjdk.org net net-dev@openjdk.org labels Oct 3, 2024

Update copyright header dates

7646f07

valeriepeng reviewed Oct 23, 2024

View reviewed changes

valeriepeng reviewed Oct 24, 2024

View reviewed changes

hns commented Oct 24, 2024

View reviewed changes

Add @SPEC tags as per review feedback

7f4a602

valeriepeng reviewed Oct 25, 2024

View reviewed changes

valeriepeng approved these changes Oct 25, 2024

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Oct 25, 2024

openjdk bot added the integrated Pull request has been integrated label Oct 26, 2024

openjdk bot closed this Oct 26, 2024

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 26, 2024

8305406: Add @spec tags in java.base/java.* (part 2) #21326

8305406: Add @spec tags in java.base/java.* (part 2) #21326

Uh oh!

Conversation

hns commented Oct 3, 2024 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Contributors

Reviewing

Webrev

Uh oh!

bridgekeeper bot commented Oct 3, 2024

Uh oh!

openjdk bot commented Oct 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Oct 3, 2024

Uh oh!

mlbridge bot commented Oct 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

hns commented Oct 22, 2024

Uh oh!

valeriepeng commented Oct 23, 2024

Uh oh!

valeriepeng Oct 23, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonathan-gibbons commented Oct 23, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hns left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hns commented Oct 24, 2024

Uh oh!

hns commented Oct 24, 2024

Uh oh!

openjdk bot commented Oct 24, 2024

Uh oh!

openjdk bot commented Oct 24, 2024

Uh oh!

openjdk bot commented Oct 24, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

valeriepeng commented Oct 25, 2024

Uh oh!

hns commented Oct 26, 2024

Uh oh!

openjdk bot commented Oct 26, 2024

Uh oh!

openjdk bot commented Oct 26, 2024

Uh oh!

Reviewers

Assignees

Labels

hns commented Oct 3, 2024 •

edited by openjdk bot

Loading

openjdk bot commented Oct 3, 2024 •

edited

Loading

mlbridge bot commented Oct 3, 2024 •

edited

Loading

valeriepeng Oct 23, 2024 •

edited

Loading