Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
59a90cc
JDK-8305406: Add @spec tags in java.base/java.* (part 2)
jonathan-gibbons Apr 4, 2023
7bfac25
Update src/java.base/share/classes/java/security/cert/X509Certificate…
jonathan-gibbons Apr 5, 2023
ce6eb0a
Address review feedback
jonathan-gibbons Apr 5, 2023
902c312
Add @spec tags for nist.gov docs
jonathan-gibbons Jun 8, 2023
7646f07
Update copyright header dates
hns Oct 21, 2024
7f4a602
Add @spec tags as per review feedback
hns Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/java.base/share/classes/com/sun/crypto/provider/AESKeyWrap.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@
* <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
* "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"</a>
* and represents AES cipher in KW mode.
*
* @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
* Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
*/
class AESKeyWrap extends FeedbackCipher {

Expand Down
3 changes: 3 additions & 0 deletions src/java.base/share/classes/com/sun/crypto/provider/AESKeyWrapPadded.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@
* <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
* "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"</a>
* and represents AES cipher in KWP mode.
*
* @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
* Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
*/
class AESKeyWrapPadded extends FeedbackCipher {

Expand Down
3 changes: 3 additions & 0 deletions src/java.base/share/classes/com/sun/crypto/provider/KWUtil.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@
* This class acts as the base class for AES KeyWrap algorithms as defined
* in <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
* "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"
*
* @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
* Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
*/
class KWUtil {

Expand Down
3 changes: 3 additions & 0 deletions src/java.base/share/classes/com/sun/crypto/provider/KeyWrapCipher.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@
* This class is the impl class for AES KeyWrap algorithms as defined in
* <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
* "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"
*
* @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
* Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
*/
abstract class KeyWrapCipher extends CipherSpi {

Expand Down
5 changes: 4 additions & 1 deletion src/java.base/share/classes/java/security/DrbgParameters.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2016, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -227,6 +227,9 @@
* Calling {@link SecureRandom#generateSeed(int)} will directly read
* from this system default entropy source.
*
* @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf
* Recommendation for Random Number Generation Using Deterministic Random Bit Generators
*
* @since 9
*/
public class DrbgParameters {
Expand Down
7 changes: 6 additions & 1 deletion src/java.base/share/classes/java/security/Key.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -86,6 +86,10 @@
* Security Appendix</a>
* of the <cite>Java Object Serialization Specification</cite> for more information.
*
* @spec serialization/index.html Java Object Serialization Specification
Copy link
Contributor

@valeriepeng valeriepeng Oct 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

@hns hns Oct 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @see PublicKey
* @see PrivateKey
* @see KeyPair
Expand Down Expand Up @@ -124,6 +128,7 @@ public interface Key extends java.io.Serializable {
* Java Security Standard Algorithm Names Specification</a>
* for information about standard key algorithm names.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @return the name of the algorithm associated with this key.
*/
String getAlgorithm();
Expand Down
3 changes: 2 additions & 1 deletion src/java.base/share/classes/java/security/KeyRep.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -44,6 +44,7 @@
* Security Appendix</a>
* of the <cite>Java Object Serialization Specification</cite> for more information.
*
* @spec serialization/index.html Java Object Serialization Specification
* @see Key
* @see KeyFactory
* @see javax.crypto.spec.SecretKeySpec
Expand Down
5 changes: 5 additions & 0 deletions src/java.base/share/classes/java/security/SecureRandom.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,11 @@
* <li>{@link SecureRandomSpi#engineReseed(SecureRandomParameters)}
* </ul>
*
* @spec https://www.rfc-editor.org/info/rfc4086
* RFC 4086: Randomness Requirements for Security
* @spec https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-2.pdf
* Security Requirements for Cryptographic Modules
*
* @see java.security.SecureRandomSpi
* @see java.util.Random
*
Expand Down
3 changes: 3 additions & 0 deletions src/java.base/share/classes/java/security/Security.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -423,6 +423,7 @@ private static String getProviderProperty(String key, Provider provider) {
*
* @return the value of the specified property.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @deprecated This method used to return the value of a proprietary
* property in the master file of the "SUN" Cryptographic Service
* Provider in order to determine how to parse algorithm-specific
Expand Down Expand Up @@ -657,6 +658,7 @@ public static Provider getProvider(String name) {
* if the filter is not in the required format
* @throws NullPointerException if filter is {@code null}
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @see #getProviders(java.util.Map)
* @since 1.3
*/
Expand Down Expand Up @@ -734,6 +736,7 @@ public static Provider[] getProviders(String filter) {
* if the filter is not in the required format
* @throws NullPointerException if filter is {@code null}
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @see #getProviders(java.lang.String)
* @since 1.3
*/
Expand Down
4 changes: 3 additions & 1 deletion src/java.base/share/classes/java/security/cert/CRL.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -56,6 +56,8 @@ public abstract class CRL {
* "{@docRoot}/../specs/security/standard-names.html">
* Java Security Standard Algorithm Names</a> document
* for information about standard CRL types.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
*/
protected CRL(String type) {
this.type = type;
Expand Down
5 changes: 4 additions & 1 deletion src/java.base/share/classes/java/security/cert/CRLReason.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2014, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -31,6 +31,9 @@
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate and CRL
* Profile</a>.
*
* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @author Sean Mullan
* @since 1.7
* @see X509CRLEntry#getRevocationReason
Expand Down
15 changes: 7 additions & 8 deletions src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -81,14 +81,13 @@
* necessary locking. Multiple threads each manipulating separate objects
* need not synchronize.
*
* @spec https://www.rfc-editor.org/info/rfc2560
* RFC 2560: X.509 Internet Public Key Infrastructure Online Certificate
* Status Protocol - OCSP
* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @since 1.8
*
* @see <a href="http://www.ietf.org/rfc/rfc2560.txt"><i>RFC&nbsp;2560: X.509
* Internet Public Key Infrastructure Online Certificate Status Protocol -
* OCSP</i></a>
* @see <a href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC&nbsp;5280:
* Internet X.509 Public Key Infrastructure Certificate and Certificate
* Revocation List (CRL) Profile</i></a>
*/
public abstract class PKIXRevocationChecker extends PKIXCertPathChecker {
private URI ocspResponder;
Expand Down
10 changes: 9 additions & 1 deletion src/java.base/share/classes/java/security/cert/TrustAnchor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -125,6 +125,10 @@ public class TrustAnchor {
* decoded
* @throws NullPointerException if the specified
* {@code X509Certificate} is {@code null}
*
* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
*/
public TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints)
{
Expand Down Expand Up @@ -207,6 +211,10 @@ public TrustAnchor(X500Principal caPrincipal, PublicKey pubKey,
* or incorrectly formatted or the name constraints cannot be decoded
* @throws NullPointerException if the specified {@code caName} or
* {@code pubKey} parameter is {@code null}
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
*/
public TrustAnchor(String caName, PublicKey pubKey, byte[] nameConstraints)
{
Expand Down
10 changes: 9 additions & 1 deletion src/java.base/share/classes/java/security/cert/X509CRL.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -95,6 +95,9 @@
* }
* }</pre>
*
* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @author Hemma Prafullchandra
* @since 1.2
*
Expand Down Expand Up @@ -457,6 +460,11 @@ public X509CRLEntry getRevokedCertificate(X509Certificate certificate) {
* relevant ASN.1 definitions.
*
* @return the signature algorithm OID string.
*
* @spec https://www.rfc-editor.org/info/rfc3279
* RFC 3279: Algorithms and Identifiers for the Internet X.509
* Public Key Infrastructure Certificate and Certificate
* Revocation List (CRL) Profile
*/
public abstract String getSigAlgOID();

Expand Down
16 changes: 15 additions & 1 deletion src/java.base/share/classes/java/security/cert/X509CRLSelector.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -65,6 +65,9 @@
* provide the necessary locking. Multiple threads each manipulating
* separate objects need not synchronize.
*
* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @see CRLSelector
* @see X509CRL
*
Expand Down Expand Up @@ -193,6 +196,10 @@ public void setIssuers(Collection<X500Principal> issuers) {
*
* @param names a {@code Collection} of names (or {@code null})
* @throws IOException if a parsing error occurs
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @see #getIssuerNames
*/
public void setIssuerNames(Collection<?> names) throws IOException {
Expand Down Expand Up @@ -238,6 +245,9 @@ public void addIssuer(X500Principal issuer) {
* <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253</a> form
* @throws IOException if a parsing error occurs
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @deprecated Use {@link #addIssuer(X500Principal)} or
* {@link #addIssuerName(byte[])} instead. This method should not be
* relied on as it can fail to match some CRLs because of a loss of
Expand Down Expand Up @@ -493,6 +503,10 @@ public Collection<X500Principal> getIssuers() {
* protect against subsequent modifications.
*
* @return a {@code Collection} of names (or {@code null})
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @see #setIssuerNames
*/
public Collection<Object> getIssuerNames() {
Expand Down
23 changes: 22 additions & 1 deletion src/java.base/share/classes/java/security/cert/X509CertSelector.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2023, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 2024, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -74,6 +74,9 @@
* provide the necessary locking. Multiple threads each manipulating
* separate objects need not synchronize.
*
* @spec https://www.rfc-editor.org/info/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @see CertSelector
* @see X509Certificate
*
Expand Down Expand Up @@ -194,6 +197,9 @@ public void setIssuer(X500Principal issuer) {
* (or {@code null})
* @throws IOException if a parsing error occurs (incorrect form for DN)
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @deprecated Use {@link #setIssuer(X500Principal)} or
* {@link #setIssuer(byte[])} instead. This method should not be relied on
* as it can fail to match some certificates because of a loss of encoding
Expand Down Expand Up @@ -286,6 +292,9 @@ public void setSubject(X500Principal subject) {
* (or {@code null})
* @throws IOException if a parsing error occurs (incorrect form for DN)
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @deprecated Use {@link #setSubject(X500Principal)} or
* {@link #setSubject(byte[])} instead. This method should not be relied
* on as it can fail to match some certificates because of a loss of
Expand Down Expand Up @@ -728,6 +737,12 @@ public void setSubjectAlternativeNames(Collection<List<?>> names)
* RFC 5280, section 4.2.1.6)
* @param name the name in string form (not {@code null})
* @throws IOException if a parsing error occurs
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @spec https://www.rfc-editor.org/info/rfc822
* RFC 822: STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES
*/
public void addSubjectAlternativeName(int type, String name)
throws IOException {
Expand Down Expand Up @@ -1269,6 +1284,9 @@ public X500Principal getIssuer() {
* @return the required issuer distinguished name in RFC 2253 format
* (or {@code null})
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @deprecated Use {@link #getIssuer()} or {@link #getIssuerAsBytes()}
* instead. This method should not be relied on as it can fail to match
* some certificates because of a loss of encoding information in the
Expand Down Expand Up @@ -1328,6 +1346,9 @@ public X500Principal getSubject() {
* @return the required subject distinguished name in RFC 2253 format
* (or {@code null})
*
* @spec https://www.rfc-editor.org/info/rfc2253
* RFC 2253: Lightweight Directory Access Protocol (v3):
* UTF-8 String Representation of Distinguished Names
* @deprecated Use {@link #getSubject()} or {@link #getSubjectAsBytes()}
* instead. This method should not be relied on as it can fail to match
* some certificates because of a loss of encoding information in the
Expand Down
Loading