1 files changed, 56 insertions, 0 deletions
diff --git a/keystore/java/android/security/KeyGeneratorSpec.java b/keystore/java/android/security/KeyGeneratorSpec.java
index 0e490cd7cadb..29b1209b0805 100644
--- a/keystore/java/android/security/KeyGeneratorSpec.java
+++ b/keystore/java/android/security/KeyGeneratorSpec.java
@@ -22,6 +22,7 @@ import android.text.TextUtils;
 import java.security.spec.AlgorithmParameterSpec;
 import java.util.Date;
 
+import javax.crypto.Cipher;
 import javax.crypto.KeyGenerator;
 import javax.crypto.SecretKey;
 
@@ -51,6 +52,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
     private final @KeyStoreKeyConstraints.PurposeEnum int mPurposes;
     private final @KeyStoreKeyConstraints.PaddingEnum int mPaddings;
     private final @KeyStoreKeyConstraints.BlockModeEnum int mBlockModes;
+    private final boolean mRandomizedEncryptionRequired;
     private final @KeyStoreKeyConstraints.UserAuthenticatorEnum int mUserAuthenticators;
     private final int mUserAuthenticationValidityDurationSeconds;
     private final boolean mInvalidatedOnNewFingerprintEnrolled;
@@ -66,6 +68,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
             @KeyStoreKeyConstraints.PurposeEnum int purposes,
             @KeyStoreKeyConstraints.PaddingEnum int paddings,
             @KeyStoreKeyConstraints.BlockModeEnum int blockModes,
+            boolean randomizedEncryptionRequired,
             @KeyStoreKeyConstraints.UserAuthenticatorEnum int userAuthenticators,
             int userAuthenticationValidityDurationSeconds,
             boolean invalidatedOnNewFingerprintEnrolled) {
@@ -89,6 +92,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
         mPurposes = purposes;
         mPaddings = paddings;
         mBlockModes = blockModes;
+        mRandomizedEncryptionRequired = randomizedEncryptionRequired;
         mUserAuthenticators = userAuthenticators;
         mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
         mInvalidatedOnNewFingerprintEnrolled = invalidatedOnNewFingerprintEnrolled;
@@ -172,6 +176,19 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
     }
 
     /**
+     * Returns {@code true} if encryption using this key must be sufficiently randomized to produce
+     * different ciphertexts for the same plaintext every time. The formal cryptographic property
+     * being required is <em>indistinguishability under chosen-plaintext attack ({@code
+     * IND-CPA})</em>. This property is important because it mitigates several classes of
+     * weaknesses due to which ciphertext may leak information about plaintext. For example, if a
+     * given plaintext always produces the same ciphertext, an attacker may see the repeated
+     * ciphertexts and be able to deduce something about the plaintext.
+     */
+    public boolean isRandomizedEncryptionRequired() {
+        return mRandomizedEncryptionRequired;
+    }
+
+    /**
      * Gets the set of user authenticators which protect access to this key. The key can only be
      * used iff the user has authenticated to at least one of these user authenticators.
      *
@@ -223,6 +240,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
         private @KeyStoreKeyConstraints.PurposeEnum int mPurposes;
         private @KeyStoreKeyConstraints.PaddingEnum int mPaddings;
         private @KeyStoreKeyConstraints.BlockModeEnum int mBlockModes;
+        private boolean mRandomizedEncryptionRequired = true;
         private @KeyStoreKeyConstraints.UserAuthenticatorEnum int mUserAuthenticators;
         private int mUserAuthenticationValidityDurationSeconds = -1;
         private boolean mInvalidatedOnNewFingerprintEnrolled;
@@ -363,6 +381,43 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
         }
 
         /**
+         * Sets whether encryption using this key must be sufficiently randomized to produce
+         * different ciphertexts for the same plaintext every time. The formal cryptographic
+         * property being required is <em>indistinguishability under chosen-plaintext attack
+         * ({@code IND-CPA})</em>. This property is important because it mitigates several classes
+         * of weaknesses due to which ciphertext may leak information about plaintext. For example,
+         * if a given plaintext always produces the same ciphertext, an attacker may see the
+         * repeated ciphertexts and be able to deduce something about the plaintext.
+         *
+         * <p>By default, {@code IND-CPA} is required.
+         *
+         * <p>When {@code IND-CPA} is required:
+         * <ul>
+         * <li>block modes which do not offer {@code IND-CPA}, such as {@code ECB}, are prohibited;
+         * </li>
+         * <li>in block modes which use an IV, such as {@code CBC}, {@code CTR}, and {@code GCM},
+         * caller-provided IVs are rejected when encrypting, to ensure that only random IVs are
+         * used.</li>
+         *
+         * <p>Before disabling this requirement, consider the following approaches instead:
+         * <ul>
+         * <li>If you are generating a random IV for encryption and then initializing a {@code}
+         * Cipher using the IV, the solution is to let the {@code Cipher} generate a random IV
+         * instead. This will occur if the {@code Cipher} is initialized for encryption without an
+         * IV. The IV can then be queried via {@link Cipher#getIV()}.</li>
+         * <li>If you are generating a non-random IV (e.g., an IV derived from something not fully
+         * random, such as the name of the file being encrypted, or transaction ID, or password,
+         * or a device identifier), consider changing your design to use a random IV which will then
+         * be provided in addition to the ciphertext to the entities which need to decrypt the
+         * ciphertext.</li>
+         * </ul>
+         */
+        public Builder setRandomizedEncryptionRequired(boolean required) {
+            mRandomizedEncryptionRequired = required;
+            return this;
+        }
+
+        /**
          * Sets the user authenticators which protect access to this key. The key can only be used
          * iff the user has authenticated to at least one of these user authenticators.
          *
@@ -427,6 +482,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
                     mPurposes,
                     mPaddings,
                     mBlockModes,
+                    mRandomizedEncryptionRequired,
                     mUserAuthenticators,
                     mUserAuthenticationValidityDurationSeconds,
                     mInvalidatedOnNewFingerprintEnrolled);