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
This commit is contained in:
Jonathan Gibbons 2024-10-26 06:57:45 +00:00 committed by Hannes Wallnöfer
parent 1476f6c475
commit 873f8a696f
59 changed files with 311 additions and 51 deletions

View file

@ -164,6 +164,10 @@ import sun.security.util.KnownOIDs;
* Consult the release documentation for your implementation to see if any
* other transformations are supported.
*
* @spec https://www.rfc-editor.org/info/rfc5116
* RFC 5116: An Interface and Algorithms for Authenticated Encryption
* @spec https://www.rfc-editor.org/info/rfc7539
* RFC 7539: ChaCha20 and Poly1305 for IETF Protocols
* @author Jan Luehe
* @see KeyGenerator
* @see SecretKey

View file

@ -137,6 +137,8 @@ public class EncryptedPrivateKeyInfo {
* is empty, i.e. 0-length.
* @exception NoSuchAlgorithmException if the specified algName is
* not supported.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
*/
public EncryptedPrivateKeyInfo(String algName, byte[] encryptedData)
throws NoSuchAlgorithmException {
@ -226,6 +228,8 @@ public class EncryptedPrivateKeyInfo {
* for information about standard Cipher algorithm names.
*
* @return the encryption algorithm name.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
*/
public String getAlgName() {
return algid == null ? params.getAlgorithm() : algid.getName();

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 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
@ -59,6 +59,7 @@
* How to Implement a Provider in the Java Cryptography Architecture}</li>
* </ul>
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @since 1.4
*/
package javax.crypto;

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2018, 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
@ -39,6 +39,8 @@ import java.util.Objects;
* <p> This class can be used to initialize a {@code Cipher} object that
* implements the <i>ChaCha20</i> algorithm.
*
* @spec https://www.rfc-editor.org/info/rfc7539
* RFC 7539: ChaCha20 and Poly1305 for IETF Protocols
* @since 11
*/
public final class ChaCha20ParameterSpec implements AlgorithmParameterSpec {

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011, 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
@ -56,6 +56,12 @@ import java.security.spec.AlgorithmParameterSpec;
* applications. Other values can be specified for this class, but not
* all CSP implementations will support them.
*
* @spec https://www.rfc-editor.org/info/rfc5116
* RFC 5116: An Interface and Algorithms for Authenticated Encryption
* @spec https://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf
* Recommendation for Block Cipher Modes of Operation: Galois/Counter
* Mode (GCM) and GMAC
*
* @see javax.crypto.Cipher
*
* @since 1.7

View file

@ -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
@ -72,6 +72,8 @@ import java.security.spec.MGF1ParameterSpec;
* EncodingParameters ::= OCTET STRING(SIZE(0..MAX))
* </pre>
*
* @spec https://www.rfc-editor.org/info/rfc8017
* RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
* @see java.security.spec.MGF1ParameterSpec
* @see PSource
*

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2022, 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
@ -54,6 +54,8 @@ import java.util.Arrays;
* this class requests the password as a char array, so it can be overwritten
* when done.
*
* @spec https://www.rfc-editor.org/info/rfc2898
* RFC 2898: PKCS #5: Password-Based Cryptography Specification Version 2.0
* @author Jan Luehe
* @author Valerie Peng
*

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2022, 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
@ -33,6 +33,8 @@ import java.security.spec.AlgorithmParameterSpec;
* <a href="http://www.ietf.org/rfc/rfc2898.txt">PKCS #5</a>
* standard.
*
* @spec https://www.rfc-editor.org/info/rfc2898
* RFC 2898: PKCS #5: Password-Based Cryptography Specification Version 2.0
* @author Jan Luehe
*
* @since 1.4

View file

@ -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
@ -42,6 +42,9 @@ package javax.crypto.spec;
* }
* EncodingParameters ::= OCTET STRING(SIZE(0..MAX))
* </pre>
*
* @spec https://www.rfc-editor.org/info/rfc8017
* RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
* @author Valerie Peng
*
* @since 1.5

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2023, 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
@ -39,6 +39,8 @@ import java.util.Arrays;
* <p> This class can be used to initialize a {@code Cipher} object that
* implements the <i>RC2</i> algorithm.
*
* @spec https://www.rfc-editor.org/info/rfc2268
* RFC 2268: A Description of the RC2(r) Encryption Algorithm
* @author Jan Luehe
*
* @since 1.4

View file

@ -39,6 +39,8 @@ import java.util.Arrays;
* <p> This class can be used to initialize a {@code Cipher} object that
* implements the <i>RC5</i> algorithm.
*
* @spec https://www.rfc-editor.org/info/rfc2040
* RFC 2040: The RC5, RC5-CBC, RC5-CBC-Pad, and RC5-CTS Algorithms
* @author Jan Luehe
*
* @since 1.4

View file

@ -98,6 +98,8 @@ public class SecretKeySpec implements KeySpec, SecretKey {
* for information about standard algorithm names.
* @exception IllegalArgumentException if <code>algorithm</code>
* is null or <code>key</code> is null or empty.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
*/
public SecretKeySpec(byte[] key, String algorithm) {
String errMsg = doSanityCheck(key, algorithm);
@ -144,6 +146,8 @@ public class SecretKeySpec implements KeySpec, SecretKey {
* @exception ArrayIndexOutOfBoundsException is thrown if
* <code>offset</code> or <code>len</code> index bytes outside the
* <code>key</code>.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
*/
public SecretKeySpec(byte[] key, int offset, int len, String algorithm) {
if (key == null || algorithm == null) {

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 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
@ -63,6 +63,7 @@ public abstract class ExtendedSSLSession implements SSLSession {
* order of preference. The return value is an empty array if
* no signature algorithm is supported.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @see SSLParameters#getAlgorithmConstraints
*/
public abstract String[] getLocalSupportedSignatureAlgorithms();
@ -86,6 +87,7 @@ public abstract class ExtendedSSLSession implements SSLSession {
* order of preference. The return value is an empty array if
* the peer has not sent the supported signature algorithms.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @see X509KeyManager
* @see X509ExtendedKeyManager
*/

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2023, 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
@ -53,6 +53,11 @@ import java.util.regex.PatternSyntaxException;
* <P>
* Note that {@code SNIHostName} objects are immutable.
*
* @spec https://www.rfc-editor.org/info/rfc5890
* RFC 5890: Internationalized Domain Names for Applications (IDNA):
* Definitions and Document Framework
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
* @see SNIServerName
* @see StandardConstants#SNI_HOST_NAME
*
@ -92,6 +97,15 @@ public final class SNIHostName extends SNIServerName {
*
* @throws NullPointerException if {@code hostname} is {@code null}
* @throws IllegalArgumentException if {@code hostname} is illegal
*
* @spec https://www.rfc-editor.org/info/rfc1122
* RFC 1122: Requirements for Internet Hosts - Communication Layers
* @spec https://www.rfc-editor.org/info/rfc1123
* RFC 1123: Requirements for Internet Hosts - Application and Support
* @spec https://www.rfc-editor.org/info/rfc3490
* RFC 3490: Internationalizing Domain Names in Applications (IDNA)
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
*/
public SNIHostName(String hostname) {
// IllegalArgumentException will be thrown if {@code hostname} is
@ -159,6 +173,17 @@ public final class SNIHostName extends SNIServerName {
*
* @throws NullPointerException if {@code encoded} is {@code null}
* @throws IllegalArgumentException if {@code encoded} is illegal
*
* @spec https://www.rfc-editor.org/info/rfc1122
* RFC 1122: Requirements for Internet Hosts - Communication Layers
* @spec https://www.rfc-editor.org/info/rfc1123
* RFC 1123: Requirements for Internet Hosts - Application and Support
* @spec https://www.rfc-editor.org/info/rfc3490
* RFC 3490: Internationalizing Domain Names in Applications (IDNA)
* @spec https://www.rfc-editor.org/info/rfc4366
* RFC 4366: Transport Layer Security (TLS) Extensions
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
*/
public SNIHostName(byte[] encoded) {
// NullPointerException will be thrown if {@code encoded} is null
@ -198,6 +223,11 @@ public final class SNIHostName extends SNIServerName {
*
* @return the {@link StandardCharsets#US_ASCII}-compliant hostname
* of this {@code SNIHostName} object
*
* @spec https://www.rfc-editor.org/info/rfc5890
* RFC 5890: Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
*/
public String getAsciiName() {
return hostname;
@ -215,6 +245,9 @@ public final class SNIHostName extends SNIServerName {
* the other server name object to compare with.
* @return true if, and only if, the {@code other} is considered
* equal to this instance
*
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
*/
@Override
public boolean equals(Object other) {

View file

@ -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
@ -41,6 +41,8 @@ import java.util.List;
* {@code SNIServerName} objects are immutable. Subclasses should not provide
* methods that can change the state of an instance once it has been created.
*
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
* @see SSLParameters#getServerNames()
* @see SSLParameters#setServerNames(List)
*

View file

@ -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
@ -413,6 +413,8 @@ import java.util.function.BiFunction;
* because there is no way to guarantee the eventual packet ordering.
* </OL>
*
* @spec https://www.rfc-editor.org/info/rfc2246
* RFC 2246: The TLS Protocol Version 1.0
* @see SSLContext
* @see SSLSocket
* @see SSLServerSocket
@ -859,6 +861,8 @@ public abstract class SSLEngine {
* if this engine has not received the proper SSL/TLS/DTLS close
* notification message from the peer.
*
* @spec https://www.rfc-editor.org/info/rfc2246
* RFC 2246: The TLS Protocol Version 1.0
* @see #isInboundDone()
* @see #isOutboundDone()
*/
@ -1351,6 +1355,8 @@ public abstract class SSLEngine {
* Application-Layer Protocol Negotiation (ALPN), can negotiate
* application-level values between peers.
*
* @spec https://www.rfc-editor.org/info/rfc7301
* RFC 7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension
* @implSpec
* The implementation in this class throws
* {@code UnsupportedOperationException} and performs no other action.

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 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
@ -300,6 +300,7 @@ public class SSLParameters {
* Java Security Standard Algorithm Names</a> document
* for information about standard algorithm names.
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @see X509ExtendedTrustManager
*
* @since 1.7
@ -674,6 +675,9 @@ public class SSLParameters {
* @throws IllegalArgumentException if protocols is null, or if
* any element in a non-empty array is null or an
* empty (zero-length) string
*
* @spec https://www.rfc-editor.org/info/rfc7301
* RFC 7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension
* @see #getApplicationProtocols
* @since 9
*/

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2022, 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
@ -770,6 +770,9 @@ public abstract class SSLSocket extends Socket
* if a value was successfully negotiated.
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
*
* @spec https://www.rfc-editor.org/info/rfc7301
* RFC 7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension
* @since 9
*/
public String getApplicationProtocol() {

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2022, 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
@ -198,6 +198,8 @@ public abstract class SSLSocketFactory extends SocketFactory {
* does not implement the operation
* @throws NullPointerException if {@code s} is {@code null}
*
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
* @since 1.8
*/
public Socket createSocket(Socket s, InputStream consumed,

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 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
@ -49,6 +49,8 @@ public final class StandardConstants {
* <P>
* The value of this constant is {@value}.
*
* @spec https://www.rfc-editor.org/info/rfc6066
* RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
* @see SNIServerName
* @see SNIHostName
*/

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 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
@ -36,6 +36,7 @@
* </b></a></li>
* </ul>
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @since 1.4
*/
package javax.net.ssl;

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2017, 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
@ -33,6 +33,7 @@
* </b></a></li>
* </ul>
*
* @spec security/standard-names.html Java Security Standard Algorithm Names
* @since 1.4
*/
package javax.security.auth.login;

View file

@ -60,6 +60,14 @@ import sun.security.util.*;
* {@code X509Certificate} return X500Principals representing the
* issuer and subject fields of the certificate.
*
* @spec https://www.rfc-editor.org/info/rfc1779
* RFC 1779: A String Representation of Distinguished Names
* @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/rfc5280
* RFC 5280: Internet X.509 Public Key Infrastructure Certificate
* and Certificate Revocation List (CRL) Profile
* @see java.security.cert.X509Certificate
* @since 1.4
*/
@ -141,6 +149,10 @@ public final class X500Principal implements Principal, java.io.Serializable {
* is {@code null}
* @exception IllegalArgumentException if the {@code name}
* is improperly specified
*
* @spec https://www.rfc-editor.org/info/rfc4512
* RFC 4512: Lightweight Directory Access Protocol (LDAP):
* Directory Information Models
*/
public X500Principal(String name) {
this(name, Collections.emptyMap());
@ -181,6 +193,10 @@ public final class X500Principal implements Principal, java.io.Serializable {
* @exception IllegalArgumentException if the {@code name} is
* improperly specified or a keyword in the {@code name} maps to an
* OID that is not in the correct form
*
* @spec https://www.rfc-editor.org/info/rfc4512
* RFC 4512: Lightweight Directory Access Protocol (LDAP):
* Directory Information Models
* @since 1.6
*/
public X500Principal(String name, Map<String, String> keywordMap) {

View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2014, 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
@ -44,6 +44,17 @@
* Directory Information Models</a></li>
* </ul>
*
* @spec https://www.rfc-editor.org/info/rfc1779
* RFC 1779: A String Representation of Distinguished Names
* @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/rfc4512
* RFC 4512: Lightweight Directory Access Protocol (LDAP):
* Directory Information Models
* @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.4
*/
package javax.security.auth.x500;