diff --git a/src/java.base/share/classes/java/security/Key.java b/src/java.base/share/classes/java/security/Key.java index 190a3db2999..ed6ec42d362 100644 --- a/src/java.base/share/classes/java/security/Key.java +++ b/src/java.base/share/classes/java/security/Key.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2025, 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 @@ -120,10 +120,9 @@ public interface Key extends java.io.Serializable { /** * Returns the standard algorithm name for this key. For - * example, "DSA" would indicate that this key is a DSA key. - * See the key related sections (KeyFactory, KeyGenerator, - * KeyPairGenerator, and SecretKeyFactory) in the + * example, "RSA" would indicate that this key is an RSA key. + * See the Key Algorithms section in the + * * Java Security Standard Algorithm Names Specification * for information about standard key algorithm names. * diff --git a/src/java.base/share/classes/java/security/spec/EncodedKeySpec.java b/src/java.base/share/classes/java/security/spec/EncodedKeySpec.java index 7ddc9bf8e03..e9838efdaf1 100644 --- a/src/java.base/share/classes/java/security/spec/EncodedKeySpec.java +++ b/src/java.base/share/classes/java/security/spec/EncodedKeySpec.java @@ -74,16 +74,17 @@ public abstract class EncodedKeySpec implements KeySpec { * * @param encodedKey the encoded key. The contents of the * array are copied to protect against subsequent modification. - * @param algorithm the algorithm name of the encoded key - * See the KeyFactory section in the + * @param algorithm the algorithm name of the encoded key. + * See the AsymmetricKey Algorithms section in the + * * Java Security Standard Algorithm Names Specification - * for information about standard algorithm names. + * for information about standard asymmetric key algorithm names. * @spec security/standard-names.html Java Security Standard Algorithm Names * @throws NullPointerException if {@code encodedKey} * or {@code algorithm} is null. * @throws IllegalArgumentException if {@code algorithm} is * the empty string {@code ""} + * @spec security/standard-names.html Java Security Standard Algorithm Names * @since 9 */ protected EncodedKeySpec(byte[] encodedKey, String algorithm) { diff --git a/src/java.base/share/classes/java/security/spec/PKCS8EncodedKeySpec.java b/src/java.base/share/classes/java/security/spec/PKCS8EncodedKeySpec.java index 799de359956..af7f135d7c4 100644 --- a/src/java.base/share/classes/java/security/spec/PKCS8EncodedKeySpec.java +++ b/src/java.base/share/classes/java/security/spec/PKCS8EncodedKeySpec.java @@ -83,16 +83,17 @@ public class PKCS8EncodedKeySpec extends EncodedKeySpec { * @param encodedKey the key, which is assumed to be * encoded according to the PKCS #8 standard. The contents of * the array are copied to protect against subsequent modification. - * @param algorithm the algorithm name of the encoded private key - * See the KeyFactory section in the + * @param algorithm the algorithm name of the encoded private key. + * See the AsymmetricKey Algorithms section in the + * * Java Security Standard Algorithm Names Specification - * for information about standard algorithm names. + * for information about standard asymmetric key algorithm names. * @spec security/standard-names.html Java Security Standard Algorithm Names * @throws NullPointerException if {@code encodedKey} * or {@code algorithm} is null. * @throws IllegalArgumentException if {@code algorithm} is * the empty string {@code ""} + * @spec security/standard-names.html Java Security Standard Algorithm Names * @since 9 */ public PKCS8EncodedKeySpec(byte[] encodedKey, String algorithm) { diff --git a/src/java.base/share/classes/java/security/spec/X509EncodedKeySpec.java b/src/java.base/share/classes/java/security/spec/X509EncodedKeySpec.java index e9801f6f7f3..a405104cd07 100644 --- a/src/java.base/share/classes/java/security/spec/X509EncodedKeySpec.java +++ b/src/java.base/share/classes/java/security/spec/X509EncodedKeySpec.java @@ -73,16 +73,17 @@ public class X509EncodedKeySpec extends EncodedKeySpec { * @param encodedKey the key, which is assumed to be * encoded according to the X.509 standard. The contents of the * array are copied to protect against subsequent modification. - * @param algorithm the algorithm name of the encoded public key - * See the KeyFactory section in the + * @param algorithm the algorithm name of the encoded public key. + * See the AsymmetricKey Algorithms section in the + * * Java Security Standard Algorithm Names Specification - * for information about standard algorithm names. + * for information about standard asymmetric key algorithm names. * @spec security/standard-names.html Java Security Standard Algorithm Names * @throws NullPointerException if {@code encodedKey} * or {@code algorithm} is null. * @throws IllegalArgumentException if {@code algorithm} is * the empty string {@code ""} + * @spec security/standard-names.html Java Security Standard Algorithm Names * @since 9 */ public X509EncodedKeySpec(byte[] encodedKey, String algorithm) { diff --git a/src/java.base/share/classes/javax/crypto/KDF.java b/src/java.base/share/classes/javax/crypto/KDF.java index 9859bd47787..5c9c7e71ce4 100644 --- a/src/java.base/share/classes/javax/crypto/KDF.java +++ b/src/java.base/share/classes/javax/crypto/KDF.java @@ -483,7 +483,11 @@ public final class KDF { * Derives a key, returned as a {@code SecretKey} object. * * @param alg - * the algorithm of the resultant {@code SecretKey} object + * the algorithm of the resultant {@code SecretKey} object. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. * @param derivationSpec * the object describing the inputs to the derivation function * @@ -500,6 +504,7 @@ public final class KDF { * * @see Delayed Provider * Selection + * @spec security/standard-names.html Java Security Standard Algorithm Names * */ public SecretKey deriveKey(String alg, diff --git a/src/java.base/share/classes/javax/crypto/KDFSpi.java b/src/java.base/share/classes/javax/crypto/KDFSpi.java index dcd2029c0c0..e2625a1930d 100644 --- a/src/java.base/share/classes/javax/crypto/KDFSpi.java +++ b/src/java.base/share/classes/javax/crypto/KDFSpi.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2024, 2025, 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 @@ -115,7 +115,11 @@ public abstract class KDFSpi { * result of {@code deriveData}. * * @param alg - * the algorithm of the resultant {@code SecretKey} object + * the algorithm of the resultant {@code SecretKey} object. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. * @param derivationSpec * derivation parameters * @@ -129,6 +133,7 @@ public abstract class KDFSpi { * if {@code alg} is empty or invalid * @throws NullPointerException * if {@code alg} or {@code derivationSpec} is null + * @spec security/standard-names.html Java Security Standard Algorithm Names */ protected abstract SecretKey engineDeriveKey(String alg, AlgorithmParameterSpec derivationSpec) @@ -154,4 +159,4 @@ public abstract class KDFSpi { AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException; -} \ No newline at end of file +} diff --git a/src/java.base/share/classes/javax/crypto/KEM.java b/src/java.base/share/classes/javax/crypto/KEM.java index 287efc75371..927b36ba25c 100644 --- a/src/java.base/share/classes/javax/crypto/KEM.java +++ b/src/java.base/share/classes/javax/crypto/KEM.java @@ -222,7 +222,13 @@ public final class KEM { * to be returned, inclusive * @param to the final index of the shared secret byte array * to be returned, exclusive - * @param algorithm the algorithm name for the secret key that is returned + * @param algorithm the algorithm name for the secret key that is returned. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. + * Specify "Generic" if the output will be used as the input keying + * material of a key derivation function (KDF). * @return a {@link Encapsulated} object containing a portion of * the shared secret, key encapsulation message, and optional * parameters. The portion of the shared secret is a @@ -237,6 +243,7 @@ public final class KEM { * @throws UnsupportedOperationException if the combination of * {@code from}, {@code to}, and {@code algorithm} * is not supported by the encapsulator + * @spec security/standard-names.html Java Security Standard Algorithm Names */ public Encapsulated encapsulate(int from, int to, String algorithm) { return e.engineEncapsulate(from, to, algorithm); @@ -345,7 +352,13 @@ public final class KEM { * to be returned, inclusive * @param to the final index of the shared secret byte array * to be returned, exclusive - * @param algorithm the algorithm name for the secret key that is returned + * @param algorithm the algorithm name for the secret key that is returned. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. + * Specify "Generic" if the output will be used as the input keying + * material of a key derivation function (KDF). * @return a portion of the shared secret as a {@code SecretKey} * containing the bytes of the secret ranging from {@code from} * to {@code to}, exclusive, and an algorithm name as specified. @@ -361,6 +374,7 @@ public final class KEM { * @throws UnsupportedOperationException if the combination of * {@code from}, {@code to}, and {@code algorithm} * is not supported by the decapsulator + * @spec security/standard-names.html Java Security Standard Algorithm Names */ public SecretKey decapsulate(byte[] encapsulation, int from, int to, String algorithm) diff --git a/src/java.base/share/classes/javax/crypto/KEMSpi.java b/src/java.base/share/classes/javax/crypto/KEMSpi.java index 61d13aeb024..6f6eefedbb9 100644 --- a/src/java.base/share/classes/javax/crypto/KEMSpi.java +++ b/src/java.base/share/classes/javax/crypto/KEMSpi.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2023, 2025, 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 @@ -129,7 +129,13 @@ public interface KEMSpi { * to be returned, inclusive * @param to the final index of the shared secret byte array * to be returned, exclusive - * @param algorithm the algorithm name for the secret key that is returned + * @param algorithm the algorithm name for the secret key that is returned. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. + * Specify "Generic" if the output will be used as the input keying + * material of a key derivation function (KDF). * @return an {@link KEM.Encapsulated} object containing a portion of * the shared secret as a key with the specified algorithm, * key encapsulation message, and optional parameters. @@ -141,6 +147,7 @@ public interface KEMSpi { * is not supported by the encapsulator * @see KEM.Encapsulated * @see KEM.Encapsulator#encapsulate(int, int, String) + * @spec security/standard-names.html Java Security Standard Algorithm Names */ KEM.Encapsulated engineEncapsulate(int from, int to, String algorithm); @@ -188,7 +195,13 @@ public interface KEMSpi { * to be returned, inclusive * @param to the final index of the shared secret byte array * to be returned, exclusive - * @param algorithm the algorithm name for the secret key that is returned + * @param algorithm the algorithm name for the secret key that is returned. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. + * Specify "Generic" if the output will be used as the input keying + * material of a key derivation function (KDF). * @return a portion of the shared secret as a {@code SecretKey} with * the specified algorithm * @throws DecapsulateException if an error occurs during the @@ -201,6 +214,7 @@ public interface KEMSpi { * {@code from}, {@code to}, and {@code algorithm} * is not supported by the decapsulator * @see KEM.Decapsulator#decapsulate(byte[], int, int, String) + * @spec security/standard-names.html Java Security Standard Algorithm Names */ SecretKey engineDecapsulate(byte[] encapsulation, int from, int to, String algorithm) throws DecapsulateException; diff --git a/src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java b/src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java index d36510a21a8..be185cb34ad 100644 --- a/src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java +++ b/src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2025, 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 @@ -93,9 +93,10 @@ public class SecretKeySpec implements KeySpec, SecretKey { * the array are copied to protect against subsequent modification. * @param algorithm the name of the secret-key algorithm to be associated * with the given key material. - * See the - * Java Security Standard Algorithm Names document - * for information about standard algorithm names. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. * @exception IllegalArgumentException if algorithm * is null or key is null or empty. * @@ -137,9 +138,10 @@ public class SecretKeySpec implements KeySpec, SecretKey { * @param len the length of the key material. * @param algorithm the name of the secret-key algorithm to be associated * with the given key material. - * See the - * Java Security Standard Algorithm Names document - * for information about standard algorithm names. + * See the SecretKey Algorithms section in the + * + * Java Security Standard Algorithm Names Specification + * for information about standard secret key algorithm names. * @exception IllegalArgumentException if algorithm * is null or key is null, empty, or too short, * i.e. {@code key.length-offset