am 651dbfde: am ad48c4c9: am c1c6528d: Merge "Add EcIesParameterSpec to enable ECIES crypto."

* commit '651dbfde73171ad6451dc8f9288fa4df50f99e4c':
  Add EcIesParameterSpec to enable ECIES crypto.

1 files changed, 287 insertions, 0 deletions

diff --git a/keystore/java/android/security/EcIesParameterSpec.java b/keystore/java/android/security/EcIesParameterSpec.java
new file mode 100644
index 0000000..0f19812
--- /dev/null
+++ b/keystore/java/android/security/EcIesParameterSpec.java
@@ -0,0 +1,287 @@
+package android.security;
+
+import android.annotation.IntDef;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.security.spec.AlgorithmParameterSpec;
+
+import javax.crypto.Cipher;
+import javax.crypto.Mac;
+
+/**
+ * {@link AlgorithmParameterSpec} for ECIES (Integrated Encryption Scheme using Elliptic Curve
+ * cryptography) based on {@code ISO/IEC 18033-2}.
+ *
+ * <p>ECIES is a hybrid authenticated encryption scheme. Encryption is performed using an Elliptic
+ * Curve (EC) public key. The resulting ciphertext can be decrypted only using the corresponding EC
+ * private key. The scheme is called hybrid because the EC key is only used to securely encapsulate
+ * symmetric key material. Encryption of plaintext and authentication of the corresponding
+ * ciphertext is performed using symmetric cryptography.
+ *
+ * <p>Encryption using ECIES consists of two stages:
+ * <ol>
+ * <li>Key Encapsulation Mechanism (KEM) randomly generates symmetric key material and securely
+ * encapsulates it in the output so that it can be extracted by the KEM when decrypting.
+ * Encapsulated key material is represented in the output as an EC point.</li>
+ * <li>The above symmetric key material is used by Data Encapsulation Mechanism (DEM) to encrypt the
+ * provided plaintext and authenticate the ciphertext. The resulting authenticated ciphertext is
+ * then output. When decrypting, the DEM first authenticates the ciphertext and, only if it
+ * authenticates, decrypts the ciphertext and outputs the plaintext.</li>
+ * </ol>
+ *
+ * <p>Details of KEM:
+ * <ul>
+ * <li>Only curves with cofactor of {@code 1} are supported.</li>
+ * <li>{@code CheckMode}, {@code OldCofactorMode}, {@code CofactorMode}, and {@code SingleHashMode}
+ * are {@code 0}.
+ * <li>Point format is specified by {@link #getKemPointFormat()}.</li>
+ * <li>KDF algorithm is specified by {@link #getKemKdfAlgorithm()}.</li>
+ * </ul>
+ *
+ * <p>Details of DEM:
+ * <ul>
+ * <li>Only DEM1-like mechanism is supported, with its symmetric cipher (SC) specified by
+ * {@link #getDemCipherTransformation()} (e.g., {@code AES/CBC/NoPadding} for standard DEM1) and
+ * MAC algorithm specified by {@link #getDemMacAlgorithm()} (e.g., {@code HmacSHA1} for standard
+ * DEM1).</li>
+ * </ul>
+ *
+ * @hide
+ */
+public class EcIesParameterSpec implements AlgorithmParameterSpec {
+
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(value = {PointFormat.UNCOMPRESSED, PointFormat.COMPRESSED})
+    public @interface PointFormatEnum {}
+
+    /**
+     * Wire format of the EC point.
+     */
+    public static abstract class PointFormat {
+
+        private PointFormat() {}
+
+        /** Unspecified point format. */
+        public static final int UNSPECIFIED = -1;
+
+        /**
+         * Uncompressed point format: both coordinates are stored separately.
+         *
+         * <p>The wire format is byte {@code 0x04} followed by binary representation of the
+         * {@code x} coordinate followed by binary representation of the {@code y} coordinate. See
+         * {@code ISO 18033-2} section {@code 5.4.3}.
+         */
+        public static final int UNCOMPRESSED = 0;
+
+        /**
+         * Compressed point format: only one coordinate is stored.
+         *
+         * <p>The wire format is byte {@code 0x02} or {@code 0x03} (depending on the value of the
+         * stored coordinate) followed by the binary representation of the {@code x} coordinate.
+         * See {@code ISO 18033-2} section {@code 5.4.3}.
+         */
+        public static final int COMPRESSED = 1;
+    }
+
+    /**
+     * Default parameter spec: NIST P-256 curve (aka secp256r1 aka prime256v1), compressed point
+     * format, {@code HKDFwithSHA256}, DEM uses 128-bit AES GCM.
+     */
+    public static final EcIesParameterSpec DEFAULT = new EcIesParameterSpec(
+            "P-256",
+            PointFormat.COMPRESSED,
+            "HKDFwithSHA256",
+            "AES/GCM/NoPadding",
+            128,
+            null,
+            0);
+
+    private final String mKemCurveName;
+    private final @PointFormatEnum int mKemPointFormat;
+    private final String mKemKdfAlgorithm;
+    private final String mDemCipherTransformation;
+    private final int mDemCipherKeySize;
+    private final String mDemMacAlgorithm;
+    private final int mDemMacKeySize;
+
+    private EcIesParameterSpec(
+            String kemCurveName,
+            @PointFormatEnum int kemPointFormat,
+            String kemKdfAlgorithm,
+            String demCipherTransformation,
+            int demCipherKeySize,
+            String demMacAlgorithm,
+            int demMacKeySize) {
+        mKemCurveName = kemCurveName;
+        mKemPointFormat = kemPointFormat;
+        mKemKdfAlgorithm = kemKdfAlgorithm;
+        mDemCipherTransformation = demCipherTransformation;
+        mDemCipherKeySize = demCipherKeySize;
+        mDemMacAlgorithm = demMacAlgorithm;
+        mDemMacKeySize = demMacKeySize;
+    }
+
+    /**
+     * Returns KEM EC curve name (e.g., {@code secp256r1}) or {@code null} if not specified.
+     */
+    public String getKemCurveName() {
+        return mKemCurveName;
+    }
+
+    /**
+     * Returns KEM EC point wire format or {@link PointFormat#UNSPECIFIED} if not specified.
+     */
+    public @PointFormatEnum int getKemPointFormat() {
+        return mKemPointFormat;
+    }
+
+    /**
+     * Returns KEM KDF algorithm (e.g., {@code HKDFwithSHA256} or {@code KDF1withSHA1}) or
+     * {@code null} if not specified.
+     */
+    public String getKemKdfAlgorithm() {
+        return mKemKdfAlgorithm;
+    }
+
+    /**
+     * Returns DEM {@link Cipher} transformation (e.g., {@code AES/GCM/NoPadding} or
+     * {@code AES/CBC/PKCS7Padding}) or {@code null} if not specified.
+     *
+     * @see Cipher#getInstance(String)
+     * @see #getDemCipherKeySize()
+     */
+    public String getDemCipherTransformation() {
+        return mDemCipherTransformation;
+    }
+
+    /**
+     * Returns DEM {@link Cipher} key size in bits.
+     *
+     * @see #getDemCipherTransformation()
+     */
+    public int getDemCipherKeySize() {
+        return mDemCipherKeySize;
+    }
+
+    /**
+     * Returns DEM {@link Mac} algorithm (e.g., {@code HmacSHA256} or {@code HmacSHA1}) or
+     * {@code null} if not specified.
+     *
+     * @see Mac#getInstance(String)
+     * @see #getDemMacKeySize()
+     */
+    public String getDemMacAlgorithm() {
+        return mDemMacAlgorithm;
+    }
+
+    /**
+     * Returns DEM {@link Mac} key size in bits.
+     *
+     * @see #getDemCipherTransformation()
+     */
+    public int getDemMacKeySize() {
+        return mDemMacKeySize;
+    }
+
+    /**
+     * Builder of {@link EcIesParameterSpec}.
+     */
+    public static class Builder {
+        private String mKemCurveName;
+        private @PointFormatEnum int mKemPointFormat = PointFormat.UNSPECIFIED;
+        private String mKemKdfAlgorithm;
+        private String mDemCipherTransformation;
+        private int mDemCipherKeySize = 128;
+        private String mDemMacAlgorithm;
+        private int mDemMacKeySize = -1;
+
+        /**
+         * Sets KEM EC curve name. For example, {@code P-256} or {@code secp256r1}.
+         *
+         * <p>NOTE: Only curves with cofactor of {@code 1} are supported.
+         */
+        public Builder setKemCurveName(String name) {
+            mKemCurveName = name;
+            return this;
+        }
+
+        /**
+         * Sets KEM EC point wire format.
+         */
+        public Builder setKemPointFormat(@PointFormatEnum int pointFormat) {
+            mKemPointFormat = pointFormat;
+            return this;
+        }
+
+        /**
+         * Sets KEM KDF algorithm. For example, {@code HKDFwithSHA256}, {@code KDF2withSHA256}, or
+         * {@code KDF1withSHA1}.
+         */
+        public Builder setKemKdfAlgorithm(String algorithm) {
+            mKemKdfAlgorithm = algorithm;
+            return this;
+        }
+
+        /**
+         * Sets DEM {@link Cipher} transformation. For example, {@code AES/GCM/NoPadding},
+         * {@code AES/CBC/PKCS7Padding} or {@code AES/CTR/NoPadding}.
+         *
+         * @see Cipher#getInstance(String)
+         */
+        public Builder setDemCipherTransformation(String transformation) {
+            mDemCipherTransformation = transformation;
+            return this;
+        }
+
+        /**
+         * Returns DEM {@link Cipher} key size in bits.
+         *
+         * <p>The default value is {@code 128} bits.
+         *
+         * @see #setDemCipherTransformation(String)
+         */
+        public Builder setDemCipherKeySize(int sizeBits) {
+            mDemCipherKeySize = sizeBits;
+            return this;
+        }
+
+        /**
+         * Sets DEM {@link Mac} algorithm. For example, {@code HmacSHA256} or {@code HmacSHA1}.
+         *
+         * @see Mac#getInstance(String)
+         */
+        public Builder setDemMacAlgorithm(String algorithm) {
+            mDemMacAlgorithm = algorithm;
+            return this;
+        }
+
+        /**
+         * Sets DEM {@link Mac} key size in bits.
+         *
+         * <p>By default, {@code Mac} key size is the same as the {@code Cipher} key size.
+         *
+         * @see #setDemCipherKeySize(int)
+         */
+        public Builder setDemMacKeySize(int sizeBits) {
+            mDemMacKeySize = sizeBits;
+            return this;
+        }
+
+        /**
+         * Returns a new {@link EcIesParameterSpec} based on the current state of this builder.
+         */
+        public EcIesParameterSpec build() {
+            int demMacKeySize = (mDemMacKeySize != -1) ? mDemMacKeySize : mDemCipherKeySize;
+            return new EcIesParameterSpec(
+                    mKemCurveName,
+                    mKemPointFormat,
+                    mKemKdfAlgorithm,
+                    mDemCipherTransformation,
+                    mDemCipherKeySize,
+                    mDemMacAlgorithm,
+                    demMacKeySize
+                    );
+        }
+    }
+}