8318096: Introduce AsymmetricKey interface with a getParams method

Reviewed-by: darcy, mullan, ascarpino

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

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2023, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package java.security;
+
+import java.security.spec.AlgorithmParameterSpec;
+
+/**
+ * An asymmetric key, which can be either a public key or a private key.
+ * This interface contains methods that are common to either a public key or
+ * a private key.
+ *
+ * @since 22
+ */
+public interface AsymmetricKey extends Key {
+    /**
+     * Returns the parameters associated with this key.
+     * The parameters are optional and may be either
+     * explicitly specified or implicitly created during
+     * key pair generation.
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return the associated parameters, may be {@code null}
+     */
+    default AlgorithmParameterSpec getParams() {
+        return null;
+    }
+}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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
@@ -57,7 +57,7 @@ package java.security;
  * @since 1.1
  */
 
-public interface PrivateKey extends Key, javax.security.auth.Destroyable {
+public interface PrivateKey extends AsymmetricKey, javax.security.auth.Destroyable {
 
     // Declare serialVersionUID to be compatible with JDK1.1
     /**

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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,7 +44,7 @@ package java.security;
  *
  */
 
-public interface PublicKey extends Key {
+public interface PublicKey extends AsymmetricKey {
     // Declare serialVersionUID to be compatible with JDK1.1
     /**
      * The class fingerprint that is set to indicate serialization

src/java.base/share/classes/java/security/interfaces/DSAParams.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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
@@ -26,6 +26,7 @@
 package java.security.interfaces;
 
 import java.math.BigInteger;
+import java.security.spec.AlgorithmParameterSpec;
 
 /**
  * Interface to a DSA-specific set of key parameters, which defines a
@@ -40,7 +41,7 @@ import java.math.BigInteger;
  * @author Josh Bloch
  * @since 1.1
  */
-public interface DSAParams {
+public interface DSAParams extends AlgorithmParameterSpec {
 
     /**
      * Returns the prime, {@code p}.

src/java.base/share/classes/java/security/interfaces/DSAPrivateKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, 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
@@ -62,4 +62,18 @@ public interface DSAPrivateKey extends DSAKey, java.security.PrivateKey {
      * @return the value of the private key, {@code x}.
      */
     BigInteger getX();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default DSAParams getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/DSAPublicKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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
@@ -62,4 +62,18 @@ public interface DSAPublicKey extends DSAKey, java.security.PublicKey {
      * @return the value of the public key, {@code y}.
      */
     BigInteger getY();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default DSAParams getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/ECPrivateKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2023, 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
@@ -26,6 +26,7 @@ package java.security.interfaces;
 
 import java.math.BigInteger;
 import java.security.PrivateKey;
+import java.security.spec.ECParameterSpec;
 
 /**
  * The interface to an elliptic curve (EC) private key.
@@ -56,4 +57,18 @@ public interface ECPrivateKey extends PrivateKey, ECKey {
      * @return the private value S.
      */
     BigInteger getS();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default ECParameterSpec getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/ECPublicKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2023, 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
@@ -25,6 +25,7 @@
 package java.security.interfaces;
 
 import java.security.PublicKey;
+import java.security.spec.ECParameterSpec;
 import java.security.spec.ECPoint;
 
 /**
@@ -58,4 +59,18 @@ public interface ECPublicKey extends PublicKey, ECKey {
      * @return the public point W.
      */
     ECPoint getW();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default ECParameterSpec getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/EdECPrivateKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2023, 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
@@ -25,6 +25,7 @@
 package java.security.interfaces;
 
 import java.security.PrivateKey;
+import java.security.spec.NamedParameterSpec;
 import java.util.Optional;
 
 /**
@@ -52,4 +53,18 @@ public interface EdECPrivateKey extends EdECKey, PrivateKey {
      * If the key is not available, then an empty {@code Optional}.
      */
     Optional<byte[]> getBytes();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default NamedParameterSpec getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/EdECPublicKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2023, 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
@@ -26,6 +26,7 @@ package java.security.interfaces;
 
 import java.security.PublicKey;
 import java.security.spec.EdECPoint;
+import java.security.spec.NamedParameterSpec;
 
 /**
  * An interface for an elliptic curve public key as defined by
@@ -47,4 +48,18 @@ public interface EdECPublicKey extends EdECKey, PublicKey {
      * @return the {@code EdECPoint} representing the public key.
      */
     EdECPoint getPoint();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default NamedParameterSpec getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/RSAPrivateKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2023, 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
@@ -26,6 +26,7 @@
 package java.security.interfaces;
 
 import java.math.BigInteger;
+import java.security.spec.AlgorithmParameterSpec;
 
 /**
  * The interface to an RSA private key.
@@ -59,4 +60,18 @@ public interface RSAPrivateKey extends java.security.PrivateKey, RSAKey
      * @return the private exponent
      */
     BigInteger getPrivateExponent();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default AlgorithmParameterSpec getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/RSAPublicKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2023, 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
@@ -26,6 +26,7 @@
 package java.security.interfaces;
 
 import java.math.BigInteger;
+import java.security.spec.AlgorithmParameterSpec;
 
 /**
  * The interface to an RSA public key.
@@ -56,4 +57,18 @@ public interface RSAPublicKey extends java.security.PublicKey, RSAKey
      * @return the public exponent
      */
     BigInteger getPublicExponent();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default AlgorithmParameterSpec getParams() {
+        return null;
+    }
 }

src/java.base/share/classes/java/security/interfaces/XECPrivateKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2023, 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
@@ -25,6 +25,7 @@
 package java.security.interfaces;
 
 import java.security.PrivateKey;
+import java.security.spec.AlgorithmParameterSpec;
 import java.util.Optional;
 
 /**
@@ -53,5 +54,19 @@ public interface XECPrivateKey extends XECKey, PrivateKey {
      *     and the private key is not allowed to leave the crypto boundary).
      */
     Optional<byte[]> getScalar();
+
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default AlgorithmParameterSpec getParams() {
+        return null;
+    }
 }
 

src/java.base/share/classes/java/security/interfaces/XECPublicKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2023, 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
@@ -26,6 +26,7 @@ package java.security.interfaces;
 
 import java.math.BigInteger;
 import java.security.PublicKey;
+import java.security.spec.AlgorithmParameterSpec;
 
 /**
  * An interface for an elliptic curve public key as defined by RFC 7748.
@@ -52,5 +53,18 @@ public interface XECPublicKey extends XECKey, PublicKey {
      */
     BigInteger getU();
 
+    /**
+     * {@inheritDoc java.security.AsymmetricKey}
+     *
+     * @implSpec
+     * The default implementation returns {@code null}.
+     *
+     * @return {@inheritDoc java.security.AsymmetricKey}
+     * @since 22
+     */
+    @Override
+    default AlgorithmParameterSpec getParams() {
+        return null;
+    }
 }