archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-25 22:04:51 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8346736: Java Security Standard Algorithm Names spec should include key algorithm names

Browse source 
Reviewed-by: mullan, hchao
This commit is contained in:
Weijun Wang 2025-01-27 18:21:51 +00:00
parent aba60a9274
commit 039e73fcdb
9 changed files with 75 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

9
src/java.base/share/classes/java/security/Key.java
View file

@ -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 <a href=
* "{@docRoot}/../specs/security/standard-names.html">
* example, "RSA" would indicate that this key is an RSA key.
* See the Key Algorithms section in the
* <a href="{@docRoot}/../specs/security/standard-names.html#key-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* for information about standard key algorithm names.
*

9
src/java.base/share/classes/java/security/spec/EncodedKeySpec.java
View file

@ -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 <a href=
* "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
* @param algorithm the algorithm name of the encoded key.
* See the AsymmetricKey Algorithms section in the
* <a href="{@docRoot}/../specs/security/standard-names.html#asymmetrickey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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) {

9
src/java.base/share/classes/java/security/spec/PKCS8EncodedKeySpec.java
View file

@ -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 <a href=
* "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
* @param algorithm the algorithm name of the encoded private key.
* See the AsymmetricKey Algorithms section in the
* <a href="{@docRoot}/../specs/security/standard-names.html#asymmetrickey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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) {

9
src/java.base/share/classes/java/security/spec/X509EncodedKeySpec.java
View file

@ -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 <a href=
* "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
* @param algorithm the algorithm name of the encoded public key.
* See the AsymmetricKey Algorithms section in the
* <a href="{@docRoot}/../specs/security/standard-names.html#asymmetrickey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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) {

7
src/java.base/share/classes/javax/crypto/KDF.java
View file

@ -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
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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 <a href="#DelayedProviderSelection">Delayed Provider
* Selection</a>
* @spec security/standard-names.html Java Security Standard Algorithm Names
*
*/
public SecretKey deriveKey(String alg,

11
src/java.base/share/classes/javax/crypto/KDFSpi.java
View file

@ -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
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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;
}
}

18
src/java.base/share/classes/javax/crypto/KEM.java
View file

@ -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
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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)

20
src/java.base/share/classes/javax/crypto/KEMSpi.java
View file

@ -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
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* 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;

16
src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java
View file

@ -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 <a href="{@docRoot}/../specs/security/standard-names.html">
* Java Security Standard Algorithm Names</a> document
* for information about standard algorithm names.
* See the SecretKey Algorithms section in the
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* for information about standard secret key algorithm names.
* @exception IllegalArgumentException if <code>algorithm</code>
* is null or <code>key</code> 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 <a href="{@docRoot}/../specs/security/standard-names.html">
* Java Security Standard Algorithm Names</a> document
* for information about standard algorithm names.
* See the SecretKey Algorithms section in the
* <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
* Java Security Standard Algorithm Names Specification</a>
* for information about standard secret key algorithm names.
* @exception IllegalArgumentException if <code>algorithm</code>
* is null or <code>key</code> is null, empty, or too short,
* i.e. {@code key.length-offset<len}.