Document when encrypted AndroidKeyStore keys are wiped.

This also drops the boolean parameter from
KeyGeneratorSpec.Builder.setEncryptionRequired to match the already
launched KeyPairGeneratorSpec.Builder.setEncryptionRequired.

Bug: 18088752
Change-Id: I91a3e8c77958971b1bda8329319f1a0d8043b669

5 files changed, 40 insertions, 18 deletions

diff --git a/keystore/java/android/security/AndroidKeyStore.java b/keystore/java/android/security/AndroidKeyStore.java
index e82ff6a..69d80e6 100644
--- a/keystore/java/android/security/AndroidKeyStore.java
+++ b/keystore/java/android/security/AndroidKeyStore.java
@@ -103,8 +103,9 @@ public class AndroidKeyStore extends KeyStoreSpi {
                     keyAliasInKeystore, null, null, keyCharacteristics);
             if ((errorCode != KeymasterDefs.KM_ERROR_OK)
                     && (errorCode != android.security.KeyStore.NO_ERROR)) {
-                throw new UnrecoverableKeyException("Failed to load information about key."
-                        + " Error code: " + errorCode);
+                throw (UnrecoverableKeyException)
+                        new UnrecoverableKeyException("Failed to load information about key")
+                                .initCause(mKeyStore.getInvalidKeyException(alias, errorCode));
             }
 
             int keymasterAlgorithm =
diff --git a/keystore/java/android/security/KeyGeneratorSpec.java b/keystore/java/android/security/KeyGeneratorSpec.java
index 5a10a0a..97e3a67 100644
--- a/keystore/java/android/security/KeyGeneratorSpec.java
+++ b/keystore/java/android/security/KeyGeneratorSpec.java
@@ -306,16 +306,15 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
          * secure lock screen credential (e.g., password, PIN, or pattern).
          *
          * <p>Note that this feature requires that the secure lock screen (e.g., password, PIN,
-         * pattern) is set up. Otherwise key generation will fail.
+         * pattern) is set up, otherwise key generation will fail. Moreover, this key will be
+         * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device
+         * Administrator). Finally, this key cannot be used until the user unlocks the secure lock
+         * screen after boot.
          *
          * @see KeyguardManager#isDeviceSecure()
          */
-        public Builder setEncryptionRequired(boolean required) {
-            if (required) {
-                mFlags |= KeyStore.FLAG_ENCRYPTED;
-            } else {
-                mFlags &= ~KeyStore.FLAG_ENCRYPTED;
-            }
+        public Builder setEncryptionRequired() {
+            mFlags |= KeyStore.FLAG_ENCRYPTED;
             return this;
         }
 
diff --git a/keystore/java/android/security/KeyPairGeneratorSpec.java b/keystore/java/android/security/KeyPairGeneratorSpec.java
index 1fcb355..7fd5cb5 100644
--- a/keystore/java/android/security/KeyPairGeneratorSpec.java
+++ b/keystore/java/android/security/KeyPairGeneratorSpec.java
@@ -654,11 +654,14 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
         }
 
         /**
-         * Indicates that this key must be encrypted at rest. This will protect the key pair with
-         * the secure lock screen credential (e.g., password, PIN, or pattern).
+         * Indicates that this key pair must be encrypted at rest. This will protect the key pair
+         * with the secure lock screen credential (e.g., password, PIN, or pattern).
          *
          * <p>Note that this feature requires that the secure lock screen (e.g., password, PIN,
-         * pattern) is set up. Otherwise key pair generation will fail.
+         * pattern) is set up, otherwise key pair generation will fail. Moreover, this key pair will
+         * be deleted when the secure lock screen is disabled or reset (e.g., by the user or a
+         * Device Administrator). Finally, this key pair cannot be used until the user unlocks the
+         * secure lock screen after boot.
          *
          * @see KeyguardManager#isDeviceSecure()
          */
diff --git a/keystore/java/android/security/KeyStore.java b/keystore/java/android/security/KeyStore.java
index 53963a6b..3ed8899 100644
--- a/keystore/java/android/security/KeyStore.java
+++ b/keystore/java/android/security/KeyStore.java
@@ -18,6 +18,7 @@ package android.security;
 
 import android.app.ActivityThread;
 import android.app.Application;
+import android.app.KeyguardManager;
 import com.android.org.conscrypt.NativeConstants;
 
 import android.content.Context;
@@ -73,6 +74,19 @@ public class KeyStore {
 
     // Flags for "put" "import" and "generate"
     public static final int FLAG_NONE = 0;
+
+    /**
+     * Indicates that this key (or key pair) must be encrypted at rest. This will protect the key
+     * (or key pair) with the secure lock screen credential (e.g., password, PIN, or pattern).
+     *
+     * <p>Note that this requires that the secure lock screen (e.g., password, PIN, pattern) is set
+     * up, otherwise key (or key pair) generation or import will fail. Moreover, this key (or key
+     * pair) will be deleted when the secure lock screen is disabled or reset (e.g., by the user or
+     * a Device Administrator). Finally, this key (or key pair) cannot be used until the user
+     * unlocks the secure lock screen after boot.
+     *
+     * @see KeyguardManager#isDeviceSecure()
+     */
     public static final int FLAG_ENCRYPTED = 1;
 
     // States
@@ -582,7 +596,7 @@ public class KeyStore {
                 case NO_ERROR:
                     return new KeyStoreException(errorCode, "OK");
                 case LOCKED:
-                    return new KeyStoreException(errorCode, "Keystore locked");
+                    return new KeyStoreException(errorCode, "User authentication required");
                 case UNINITIALIZED:
                     return new KeyStoreException(errorCode, "Keystore not initialized");
                 case SYSTEM_ERROR:
@@ -619,6 +633,8 @@ public class KeyStore {
      */
     InvalidKeyException getInvalidKeyException(String keystoreKeyAlias, KeyStoreException e) {
         switch (e.getErrorCode()) {
+            case LOCKED:
+                return new UserNotAuthenticatedException();
             case KeymasterDefs.KM_ERROR_KEY_EXPIRED:
                 return new KeyExpiredException();
             case KeymasterDefs.KM_ERROR_KEY_NOT_YET_VALID:
diff --git a/keystore/java/android/security/KeyStoreParameter.java b/keystore/java/android/security/KeyStoreParameter.java
index ea5ca71..7332332 100644
--- a/keystore/java/android/security/KeyStoreParameter.java
+++ b/keystore/java/android/security/KeyStoreParameter.java
@@ -305,7 +305,7 @@ public final class KeyStoreParameter implements ProtectionParameter {
      *
      * <pre class="prettyprint">
      * KeyStoreParameter params = new KeyStoreParameter.Builder(mContext)
-     *         .setEncryptionRequired()
+     *         .setEncryptionRequired(true)
      *         .build();
      * </pre>
      */
@@ -338,12 +338,15 @@ public final class KeyStoreParameter implements ProtectionParameter {
         }
 
         /**
-         * Indicates that this {@link java.security.KeyStore} entry must be encrypted at rest. This
-         * will protect the entry with the secure lock screen credential (e.g., password, PIN, or
-         * pattern).
+         * Sets whether this {@link java.security.KeyStore} entry must be encrypted at rest.
+         * Encryption at rest will protect the entry with the secure lock screen credential (e.g.,
+         * password, PIN, or pattern).
          *
          * <p>Note that enabling this feature requires that the secure lock screen (e.g., password,
-         * PIN, pattern) is set up. Otherwise setting the {@code KeyStore} entry will fail.
+         * PIN, pattern) is set up, otherwise setting the {@code KeyStore} entry will fail.
+         * Moreover, this entry will be deleted when the secure lock screen is disabled or reset
+         * (e.g., by the user or a Device Administrator). Finally, this entry cannot be used until
+         * the user unlocks the secure lock screen after boot.
          *
          * @see KeyguardManager#isDeviceSecure()
          */