Return an Android platform compatible HPKE SPI where available.

If the platform class is available then return a delegating
wrapper which inherits from it.

Also pulled in a few more stubs to enable check builds for the
platform classes on OpenJDK.

Also added Tink-compatible aliases for our current HPKE implentations.

android-stub/src/main/java/android/crypto/hpke/HpkeSpi.java

@@ -0,0 +1,194 @@
+/*
+ * Copyright (C) 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.crypto.hpke;
+
+import java.security.GeneralSecurityException;
+import java.security.InvalidKeyException;
+import java.security.PrivateKey;
+import java.security.PublicKey;
+import libcore.util.NonNull;
+import libcore.util.Nullable;
+
+
+/**
+ * Service Provider Interface for HPKE client API classes to communicate with implementations
+ * of HPKE as described in RFC 9180.
+ * <p>
+ * There are no standard Java Cryptography Architecture names or interface classes for HPKE,
+ * but instances of this class can be obtained by calling
+ * {@code Provider.getService("ConscryptHpke", String SuiteName)} where {@code suiteName}
+ * is the name of the HPKE suite, e.g.
+ * {@code "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM"}.
+ */
+public interface HpkeSpi {
+    /**
+     * Initialises an HPKE SPI in one of the sender modes described in RFC 9180.
+     * <p>
+     * If {@code psk} and {@code psk_id} are supplied then Pre-Shared Key Authentication
+     * will be used.
+     * <p>
+     * If {@code senderKey} is supplied then Asymmetric Key Authentication will be used.
+     * <p>
+     * If neither is supplied then "base" mode (no sender authentication) will be used.
+     * <p>
+     * Note that only base mode is currently supported on Android.
+     * <p>
+     * Public and private keys must be supplied in a format that can be used by the
+     * implementation.  An instance of the {@code "XDH"} {@link java.security.KeyFactory} can
+     * be used to translate {@code KeySpecs} or keys from another {@link java.security.Provider}
+     *
+     * @param recipientKey public key of the recipient
+     * @param info application-supplied information, may be null or empty
+     * @param senderKey private key of the sender, for symmetric auth modes only, else null
+     * @param psk pre-shared key, for PSK auth modes only, else null
+     * @param psk_id pre-shared key ID, for PSK auth modes only, else null
+     * @throws InvalidKeyException if recipientKey is null or an unsupported key format
+     * @throws UnsupportedOperationException if mode is not a supported HPKE mode
+     * @throws IllegalStateException if this SPI has already been initialised
+     */
+    void engineInitSender(
+            @NonNull PublicKey recipientKey,
+            @Nullable byte[] info,
+            @Nullable PrivateKey senderKey,
+            @Nullable byte[] psk,
+            @Nullable byte[] psk_id)
+            throws InvalidKeyException;
+
+    /**
+     * Initialises an HPKE SPI in one of the sender modes described in RFC 9180 with
+     * a predefined random seed to allow testing against known test vectors.
+     * <p>
+     * This mode provides absolutely no security and should only be used for testing
+     * purposes.
+     * <p>
+     * If {@code psk} and {@code psk_id} are supplied then Pre-Shared Key Authentication
+     * will be used.
+     * <p>
+     * If {@code senderKey} is supplied then Asymmetric Key Authentication will be used.
+     * <p>
+     * If neither is supplied then "base" mode (no sender authentication) will be used.
+     * <p>
+     * Note that only base mode is currently supported on Android.
+     * <p>
+     * Public and private keys must be supplied in a format that can be used by the
+     * implementation.  An instance of the {@code "XDH"} {@link java.security.KeyFactory} can
+     * be used to translate {@code KeySpecs} or keys from another {@link java.security.Provider}
+     *
+     *
+     * @param recipientKey public key of the recipient
+     * @param info application-supplied information, may be null or empty
+     * @param senderKey private key of the sender, for symmetric auth modes only, else null
+     * @param psk pre-shared key, for PSK auth modes only, else null
+     * @param psk_id pre-shared key ID, for PSK auth modes only, else null
+     * @param sKe Predetermined random seed, should only be usesd  for validation against
+     *            known test vectors
+     * @throws InvalidKeyException if recipientKey is null or an unsupported key format or senderKey
+     *            is an unsupported key format
+     * @throws UnsupportedOperationException if mode is not a supported HPKE mode
+     * @throws IllegalStateException if this SPI has already been initialised
+     */
+    void engineInitSenderWithSeed(
+            @NonNull PublicKey recipientKey,
+            @Nullable byte[] info,
+            @Nullable PrivateKey senderKey,
+            @Nullable byte[] psk,
+            @Nullable byte[] psk_id,
+            @NonNull byte[] sKe)
+            throws InvalidKeyException;
+
+    /**
+     * Initialises an HPKE SPI in one of the sender modes described in RFC 9180.
+     * <p>
+     * If {@code psk} and {@code psk_id} are supplied then Pre-Shared Key Authentication
+     * will be used.
+     * <p>
+     * If {@code senderKey} is supplied then Asymmetric Key Authentication will be used.
+     * <p>
+     * If neither is supplied then "base" mode (no sender authentication) will be used.
+     * <p>
+     * Note that only base mode is currently supported on Android.
+     * <p>
+     * Public and private keys must be supplied in a format that can be used by the
+     * implementation.  An instance of the {@code "XDH"} {@link java.security.KeyFactory} can
+     * be used to translate {@code KeySpecs} or keys from another {@link java.security.Provider}
+     *
+     * @param encapsulated encapsulated ephemeral key from a sender
+     * @param recipientKey private key of the recipient
+     * @param info application-supplied information, may be null or empty
+     * @param senderKey public key of sender, for asymmetric auth modes only, else null
+     * @param psk pre-shared key, for PSK auth modes only, else null
+     * @param psk_id pre-shared key ID, for PSK auth modes only, else null
+     * @throws InvalidKeyException if recipientKey is null or an unsupported key format or senderKey
+     *         is an unsupported key format
+     * @throws UnsupportedOperationException if mode is not a supported HPKE mode
+     * @throws IllegalStateException if this SPI has already been initialised
+     */
+    void engineInitRecipient(
+            @NonNull byte[] encapsulated,
+            @NonNull PrivateKey recipientKey,
+            @Nullable byte[] info,
+            @Nullable PublicKey senderKey,
+            @Nullable byte[] psk,
+            @Nullable byte[] psk_id)
+            throws InvalidKeyException;
+
+    /**
+     * Seals a message, using the internal key schedule maintained by an HPKE sender SPI.
+     *
+     * @param plaintext the plaintext
+     * @param aad optional associated data, may be null or empty
+     * @return the ciphertext
+     * @throws NullPointerException if the plaintext is null
+     * @throws IllegalStateException if this SPI has not been initialised or if it was initialised
+     *         as a recipient
+     */
+    @NonNull byte[] engineSeal(@NonNull byte[] plaintext, @Nullable byte[] aad);
+
+    /**
+     * Opens a message, using the internal key schedule maintained by an HPKE recipient SPI.
+     *
+     * @param ciphertext the ciphertext
+     * @param aad optional associated data, may be null or empty
+     * @return the plaintext
+     * @throws IllegalStateException if this SPI has not been initialised or if it was initialised
+     *         as a sender
+     * @throws GeneralSecurityException on decryption failures
+     */
+    @NonNull byte[] engineOpen(@NonNull byte[] ciphertext, @Nullable byte[] aad)
+            throws GeneralSecurityException;
+
+    /**
+     * Exports secret key material from this SPI as described in RFC 9180.
+     *
+     * @param length  expected output length
+     * @param context optional context string, may be null or empty
+     * @return exported value
+     * @throws IllegalArgumentException if the length is not valid for the KDF in use
+     * @throws IllegalStateException if this SPI has not been initialised
+     *
+     */
+    @NonNull byte[] engineExport(int length, @Nullable byte[] context);
+
+    /**
+     * Returns the encapsulated key material for an HPKE sender.
+     *
+     * @return the key material
+     * @throws IllegalStateException if this SPI has not been initialised or if it was initialised
+     *         as a recipient
+     */
+    @NonNull byte[] getEncapsulated();
+}

common/src/main/java/org/conscrypt/OpenSSLProvider.java

@@ -518,13 +518,32 @@ public OpenSSLProvider(String providerName) {
         put("CertificateFactory.X509", PREFIX + "OpenSSLX509CertificateFactory");
         put("Alg.Alias.CertificateFactory.X.509", "X509");
 
-        /* === HPKE - Conscrypt internal only === */
+        /* === HPKE === */
+        String baseClass = classExists("android.crypto.hpke.HpkeSpi")
+                ? PREFIX + "AndroidHpkeSpi"
+                : PREFIX + "HpkeImpl";
+
         put("ConscryptHpke.DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM",
-            PREFIX + "HpkeImpl$X25519_AES_128");
+                baseClass + "$X25519_AES_128");
+        put("Alg.Alias.ConscryptHpke.DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_128_GCM",
+                "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM");
         put("ConscryptHpke.DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_256_GCM",
-            PREFIX + "HpkeImpl$X25519_AES_256");
+                baseClass + "$X25519_AES_256");
+        put("Alg.Alias.ConscryptHpke.DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_AES_256_GCM",
+                "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_256_GCM");
         put("ConscryptHpke.DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/CHACHA20POLY1305",
-            PREFIX + "HpkeImpl$X25519_CHACHA20");
+                baseClass + "$X25519_CHACHA20");
+        put("Alg.Alias.ConscryptHpke.DHKEM_X25519_HKDF_SHA256_HKDF_SHA256_GhpkeCHACHA20POLY1305",
+                "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/CHACHA20POLY1305");
+    }
+
+    private boolean classExists(String classname) {
+        try {
+            Class.forName(classname);
+        } catch (ClassNotFoundException e) {
+            return false;
+        }
+        return true;
     }
 
     private void putMacImplClass(String algorithm, String className) {

libcore-stub/src/main/java/libcore/util/NonNull.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2017 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package libcore.util;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE_USE;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Denotes that a type use can never be null.
+ * <p>
+ * This is a marker annotation and it has no specific attributes.
+ * @hide
+ */
+@Documented
+@Retention(SOURCE)
+@Target({FIELD, METHOD, PARAMETER, TYPE_USE})
+public @interface NonNull {
+   /**
+    * Min Android API level (inclusive) to which this annotation is applied.
+    */
+   int from() default Integer.MIN_VALUE;
+
+   /**
+    * Max Android API level to which this annotation is applied.
+    */
+   int to() default Integer.MAX_VALUE;
+}

libcore-stub/src/main/java/libcore/util/Nullable.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2017 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package libcore.util;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE_USE;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Denotes that a type use can be a null.
+ * <p>
+ * This is a marker annotation and it has no specific attributes.
+ * @hide
+ */
+@Documented
+@Retention(SOURCE)
+@Target({FIELD, METHOD, PARAMETER, TYPE_USE})
+public @interface Nullable {
+   /**
+    * Min Android API level (inclusive) to which this annotation is applied.
+    */
+   int from() default Integer.MIN_VALUE;
+
+   /**
+    * Max Android API level to which this annotation is applied.
+    */
+   int to() default Integer.MAX_VALUE;
+}